From 20f74c20f7efe80f0b0199153934dddd80e21d8e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C5=81ukasz=20Langa?= <lukasz@langa.pl>
Date: Wed, 26 Aug 2020 18:18:14 +0200
Subject: [PATCH 0001/1034] Stop running Primer on macOS as it's flaky on
 GitHub Actions

---
 .github/workflows/primer.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/primer.yml b/.github/workflows/primer.yml
index b5dea5e7139..9b10db0d285 100644
--- a/.github/workflows/primer.yml
+++ b/.github/workflows/primer.yml
@@ -9,7 +9,7 @@ jobs:
       fail-fast: false
       matrix:
         python-version: [3.6, 3.7, 3.8]
-        os: [ubuntu-latest, macOS-latest, windows-latest]
+        os: [ubuntu-latest, windows-latest]
 
     steps:
       - uses: actions/checkout@v2

From 1ebe9b70c5624da964364841e30a2e3ffe109c4e Mon Sep 17 00:00:00 2001
From: Yurii Karabas <1998uriyyo@gmail.com>
Date: Wed, 24 Jun 2020 00:33:05 +0300
Subject: [PATCH 0002/1034] Simplify black code by using generator expressions

---
 src/black/__init__.py | 44 +++++++++++++++++++++----------------------
 1 file changed, 21 insertions(+), 23 deletions(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index 200e31fd458..954b93c77d7 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -641,10 +641,9 @@ def path_empty(
     """
     Exit if there is no `src` provided for formatting
     """
-    if len(src) == 0:
-        if verbose or not quiet:
-            out(msg)
-            ctx.exit(0)
+    if not src and (verbose or not quiet):
+        out(msg)
+        ctx.exit(0)
 
 
 def reformat_one(
@@ -928,7 +927,7 @@ def format_file_contents(src_contents: str, *, fast: bool, mode: Mode) -> FileCo
     valid by calling :func:`assert_equivalent` and :func:`assert_stable` on it.
     `mode` is passed to :func:`format_str`.
     """
-    if src_contents.strip() == "":
+    if not src_contents.strip():
         raise NothingChanged
 
     dst_contents = format_str(src_contents, mode=mode)
@@ -1062,7 +1061,7 @@ def get_grammars(target_versions: Set[TargetVersion]) -> List[Grammar]:
 
 def lib2to3_parse(src_txt: str, target_versions: Iterable[TargetVersion] = ()) -> Node:
     """Given a string with source, return the lib2to3 Node."""
-    if src_txt[-1:] != "\n":
+    if not src_txt.endswith("\n"):
         src_txt += "\n"
 
     for grammar in get_grammars(set(target_versions)):
@@ -1547,11 +1546,10 @@ def is_triple_quoted_string(self) -> bool:
 
     def contains_standalone_comments(self, depth_limit: int = sys.maxsize) -> bool:
         """If so, needs to be split before emitting."""
-        for leaf in self.leaves:
-            if leaf.type == STANDALONE_COMMENT and leaf.bracket_depth <= depth_limit:
-                return True
-
-        return False
+        return any(
+            leaf.type == STANDALONE_COMMENT and leaf.bracket_depth <= depth_limit
+            for leaf in self.leaves
+        )
 
     def contains_uncollapsable_type_comments(self) -> bool:
         ignored_ids = set()
@@ -3992,12 +3990,13 @@ class StringParenWrapper(CustomSplitMapMixin, BaseStringSplitter):
     def do_splitter_match(self, line: Line) -> TMatchResult:
         LL = line.leaves
 
-        string_idx = None
-        string_idx = string_idx or self._return_match(LL)
-        string_idx = string_idx or self._else_match(LL)
-        string_idx = string_idx or self._assert_match(LL)
-        string_idx = string_idx or self._assign_match(LL)
-        string_idx = string_idx or self._dict_match(LL)
+        string_idx = (
+            self._return_match(LL)
+            or self._else_match(LL)
+            or self._assert_match(LL)
+            or self._assign_match(LL)
+            or self._dict_match(LL)
+        )
 
         if string_idx is not None:
             string_value = line.leaves[string_idx].value
@@ -4196,7 +4195,7 @@ def do_transform(self, line: Line, string_idx: int) -> Iterator[TResult[Line]]:
         is_valid_index = is_valid_index_factory(LL)
         insert_str_child = insert_str_child_factory(LL[string_idx])
 
-        comma_idx = len(LL) - 1
+        comma_idx = -1
         ends_with_comma = False
         if LL[comma_idx].type == token.COMMA:
             ends_with_comma = True
@@ -4444,11 +4443,10 @@ def contains_pragma_comment(comment_list: List[Leaf]) -> bool:
         of the more common static analysis tools for python (e.g. mypy, flake8,
         pylint).
     """
-    for comment in comment_list:
-        if comment.value.startswith(("# type:", "# noqa", "# pylint:")):
-            return True
-
-    return False
+    return any(
+        comment.value.startswith(("# type:", "# noqa", "# pylint:"))
+        for comment in comment_list
+    )
 
 
 def insert_str_child_factory(string_leaf: Leaf) -> Callable[[LN], None]:

From 4ca92ac91c944b252caf8c2265e5854f839a66f4 Mon Sep 17 00:00:00 2001
From: Yurii Karabas <1998uriyyo@gmail.com>
Date: Wed, 26 Aug 2020 09:35:21 +0300
Subject: [PATCH 0003/1034] Revert contains_standalone_comments function
 changes

---
 src/black/__init__.py | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index 954b93c77d7..96dd0e46e7b 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -1546,10 +1546,11 @@ def is_triple_quoted_string(self) -> bool:
 
     def contains_standalone_comments(self, depth_limit: int = sys.maxsize) -> bool:
         """If so, needs to be split before emitting."""
-        return any(
-            leaf.type == STANDALONE_COMMENT and leaf.bracket_depth <= depth_limit
-            for leaf in self.leaves
-        )
+        for leaf in self.leaves:
+            if leaf.type == STANDALONE_COMMENT and leaf.bracket_depth <= depth_limit:
+                return True
+
+        return False
 
     def contains_uncollapsable_type_comments(self) -> bool:
         ignored_ids = set()

From e268cbaf668cc86b1e6aa52e52483cf4592e176c Mon Sep 17 00:00:00 2001
From: Yurii Karabas <1998uriyyo@gmail.com>
Date: Wed, 26 Aug 2020 13:43:00 +0300
Subject: [PATCH 0004/1034]  Revert contains_pragma_comment function changes

---
 src/black/__init__.py | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index 96dd0e46e7b..f51a50d3612 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -4444,10 +4444,11 @@ def contains_pragma_comment(comment_list: List[Leaf]) -> bool:
         of the more common static analysis tools for python (e.g. mypy, flake8,
         pylint).
     """
-    return any(
-        comment.value.startswith(("# type:", "# noqa", "# pylint:"))
-        for comment in comment_list
-    )
+    for comment in comment_list:
+        if comment.value.startswith(("# type:", "# noqa", "# pylint:")):
+            return True
+
+    return False
 
 
 def insert_str_child_factory(string_leaf: Leaf) -> Callable[[LN], None]:

From 5f78401b2863c4c2e8417905fa8b8bf4d648510d Mon Sep 17 00:00:00 2001
From: Rowan Rodrik van der Molen <rowan@ytec.nl>
Date: Sat, 11 Jul 2020 21:20:31 +0200
Subject: [PATCH 0005/1034] Fix g:black_fast and
 g:black_(skip)_string_normalization opts

---
 plugin/black.vim | 15 +++++++++------
 1 file changed, 9 insertions(+), 6 deletions(-)

diff --git a/plugin/black.vim b/plugin/black.vim
index 4af044e7a68..3dd3f2151c3 100644
--- a/plugin/black.vim
+++ b/plugin/black.vim
@@ -41,8 +41,12 @@ endif
 if !exists("g:black_linelength")
   let g:black_linelength = 88
 endif
-if !exists("g:black_skip_string_normalization")
-  let g:black_skip_string_normalization = 0
+if !exists("g:black_string_normalization")
+  if exists("g:black_skip_string_normalization")
+    let g:black_string_normalization = !g:black_skip_string_normalization
+  else
+    let g:black_string_normalization = 1
+  endif
 endif
 
 python3 << EndPython3
@@ -50,6 +54,7 @@ import collections
 import os
 import sys
 import vim
+from distutils.util import strtobool
 
 
 class Flag(collections.namedtuple("FlagBase", "name, cast")):
@@ -62,15 +67,13 @@ class Flag(collections.namedtuple("FlagBase", "name, cast")):
     name = self.var_name
     if name == "line_length":
       name = name.replace("_", "")
-    if name == "string_normalization":
-      name = "skip_" + name
     return "g:black_" + name
 
 
 FLAGS = [
   Flag(name="line_length", cast=int),
-  Flag(name="fast", cast=bool),
-  Flag(name="string_normalization", cast=bool),
+  Flag(name="fast", cast=strtobool),
+  Flag(name="string_normalization", cast=strtobool),
 ]
 
 

From 7fe19fac5bccc08dbcf21c293ab50f1fcda7716f Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Wed, 26 Aug 2020 18:17:59 -0400
Subject: [PATCH 0006/1034] Fix multiline docstring quote normalization

The quotes of multiline docstrings are now only normalized when string
normalization is off, instead of the string normalization setting being
ignored and the quotes being *always* normalized.

I had to make a new test case and data file since the current pair for
docstrings only worked when there is no formatting difference between the
formatting results with string normalization on and off. I needed to add
tests for when there *are* differences between the two. So I split
test_docstring's test code when string normalization is disabled into a
new test case along with a new data file.
---
 CHANGES.md                                    |   7 +
 docs/change_log.md                            |   7 +
 src/black/__init__.py                         |   1 -
 .../data/docstring_no_string_normalization.py | 209 ++++++++++++++++++
 tests/test_black.py                           |  13 +-
 5 files changed, 232 insertions(+), 5 deletions(-)
 create mode 100644 tests/data/docstring_no_string_normalization.py

diff --git a/CHANGES.md b/CHANGES.md
index 11341779f58..7352b857075 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,5 +1,12 @@
 ## Change Log
 
+### Unreleased
+
+#### _Black_
+
+- `Black` now respects `--skip-string-normalization` when normalizing multiline
+  docstring quotes (#1637)
+
 ### 20.8b1
 
 #### _Packaging_
diff --git a/docs/change_log.md b/docs/change_log.md
index 658414bf967..b7337166659 100644
--- a/docs/change_log.md
+++ b/docs/change_log.md
@@ -2,6 +2,13 @@
 
 ## Change Log
 
+### Unreleased
+
+#### _Black_
+
+- `Black` now respects `--skip-string-normalization` when normalizing multiline
+  docstring quotes (#1637)
+
 ### 20.8b1
 
 #### _Packaging_
diff --git a/src/black/__init__.py b/src/black/__init__.py
index f51a50d3612..34d8145c0f7 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -2049,7 +2049,6 @@ def visit_STRING(self, leaf: Leaf) -> Iterator[Line]:
                 if leaf.value[tail_len + 1] == docstring[-1]:
                     docstring = docstring + " "
             leaf.value = leaf.value[0:lead_len] + docstring + leaf.value[tail_len:]
-            normalize_string_quotes(leaf)
 
         yield from self.visit_default(leaf)
 
diff --git a/tests/data/docstring_no_string_normalization.py b/tests/data/docstring_no_string_normalization.py
new file mode 100644
index 00000000000..0457fcf114f
--- /dev/null
+++ b/tests/data/docstring_no_string_normalization.py
@@ -0,0 +1,209 @@
+class ALonelyClass:
+    '''
+    A multiline class docstring.
+    '''
+    def AnEquallyLonelyMethod(self):
+        '''
+        A multiline method docstring'''
+        pass
+
+
+def one_function():
+    '''This is a docstring with a single line of text.'''
+    pass
+
+
+def shockingly_the_quotes_are_normalized():
+    '''This is a multiline docstring.
+    This is a multiline docstring.
+    This is a multiline docstring.
+    '''
+    pass
+
+
+def foo():
+  """This is a docstring with             
+  some lines of text here
+  """
+  return
+
+
+def baz():
+  '''"This" is a string with some
+  embedded "quotes"'''
+  return
+
+
+def poit():
+  """
+  Lorem ipsum dolor sit amet.       
+
+  Consectetur adipiscing elit:
+   - sed do eiusmod tempor incididunt ut labore
+   - dolore magna aliqua
+     - enim ad minim veniam
+     - quis nostrud exercitation ullamco laboris nisi
+   - aliquip ex ea commodo consequat
+  """
+  pass
+
+
+def under_indent():
+  """
+  These lines are indented in a way that does not
+make sense.
+  """
+  pass
+
+
+def over_indent():
+  """
+  This has a shallow indent
+    - But some lines are deeper
+    - And the closing quote is too deep
+    """
+  pass
+
+
+def single_line():
+    """But with a newline after it!
+
+    """
+    pass
+
+
+def this():
+    r"""
+    'hey ho'
+    """
+
+
+def that():
+  """ "hey yah" """
+
+
+def and_that():
+  """
+  "hey yah" """
+
+
+def and_this():
+  ''' 
+  "hey yah"'''
+
+
+def believe_it_or_not_this_is_in_the_py_stdlib(): ''' 
+"hey yah"'''
+
+
+def shockingly_the_quotes_are_normalized_v2():
+    '''
+    Docstring Docstring Docstring
+    '''
+    pass
+
+# output
+
+class ALonelyClass:
+    '''
+    A multiline class docstring.
+    '''
+
+    def AnEquallyLonelyMethod(self):
+        '''
+        A multiline method docstring'''
+        pass
+
+
+def one_function():
+    '''This is a docstring with a single line of text.'''
+    pass
+
+
+def shockingly_the_quotes_are_normalized():
+    '''This is a multiline docstring.
+    This is a multiline docstring.
+    This is a multiline docstring.
+    '''
+    pass
+
+
+def foo():
+    """This is a docstring with
+    some lines of text here
+    """
+    return
+
+
+def baz():
+    '''"This" is a string with some
+    embedded "quotes"'''
+    return
+
+
+def poit():
+    """
+    Lorem ipsum dolor sit amet.
+
+    Consectetur adipiscing elit:
+     - sed do eiusmod tempor incididunt ut labore
+     - dolore magna aliqua
+       - enim ad minim veniam
+       - quis nostrud exercitation ullamco laboris nisi
+     - aliquip ex ea commodo consequat
+    """
+    pass
+
+
+def under_indent():
+    """
+      These lines are indented in a way that does not
+    make sense.
+    """
+    pass
+
+
+def over_indent():
+    """
+    This has a shallow indent
+      - But some lines are deeper
+      - And the closing quote is too deep
+    """
+    pass
+
+
+def single_line():
+    """But with a newline after it!"""
+    pass
+
+
+def this():
+    r"""
+    'hey ho'
+    """
+
+
+def that():
+    """ "hey yah" """
+
+
+def and_that():
+    """
+    "hey yah" """
+
+
+def and_this():
+    '''
+    "hey yah"'''
+
+
+def believe_it_or_not_this_is_in_the_py_stdlib():
+    '''
+    "hey yah"'''
+
+
+def shockingly_the_quotes_are_normalized_v2():
+    '''
+    Docstring Docstring Docstring
+    '''
+    pass
diff --git a/tests/test_black.py b/tests/test_black.py
index f5d4e1115a8..629afc5b0ad 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -517,11 +517,16 @@ def test_docstring(self) -> None:
         self.assertFormatEqual(expected, actual)
         black.assert_equivalent(source, actual)
         black.assert_stable(source, actual, DEFAULT_MODE)
+
+    @patch("black.dump_to_file", dump_to_stderr)
+    def test_docstring_no_string_normalization(self) -> None:
+        """Like test_docstring but with string normalization off."""
+        source, expected = read_data("docstring_no_string_normalization")
         mode = replace(DEFAULT_MODE, string_normalization=False)
-        not_normalized = fs(source, mode=mode)
-        self.assertFormatEqual(expected, not_normalized)
-        black.assert_equivalent(source, not_normalized)
-        black.assert_stable(source, not_normalized, mode=mode)
+        actual = fs(source, mode=mode)
+        self.assertFormatEqual(expected, actual)
+        black.assert_equivalent(source, actual)
+        black.assert_stable(source, actual, mode)
 
     def test_long_strings(self) -> None:
         """Tests for splitting long strings."""

From 2b75f8870eac943c93e93c740c9d2ef74efeeb41 Mon Sep 17 00:00:00 2001
From: mbarkhau <mbarkhau@gmail.com>
Date: Thu, 27 Aug 2020 11:47:59 +0000
Subject: [PATCH 0007/1034] fix 1631 and add test (#1641)

---
 CHANGES.md            |  2 ++
 src/black/__init__.py |  3 ++-
 tests/test_black.py   | 18 ++++++++++++++++++
 3 files changed, 22 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index 7352b857075..1c53604d4d5 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -7,6 +7,8 @@
 - `Black` now respects `--skip-string-normalization` when normalizing multiline
   docstring quotes (#1637)
 
+- fixed a crash when PWD=/ on POSIX (#1631)
+
 ### 20.8b1
 
 #### _Packaging_
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 34d8145c0f7..048e771ce96 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -5831,7 +5831,8 @@ def normalize_path_maybe_ignore(
     `report` is where "path ignored" output goes.
     """
     try:
-        normalized_path = path.resolve().relative_to(root).as_posix()
+        abspath = path if path.is_absolute() else Path.cwd() / path
+        normalized_path = abspath.resolve().relative_to(root).as_posix()
     except OSError as e:
         report.path_ignored(path, f"cannot be read because {e}")
         return None
diff --git a/tests/test_black.py b/tests/test_black.py
index 629afc5b0ad..bc80c8fca8b 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -9,6 +9,7 @@
 from io import BytesIO, TextIOWrapper
 import os
 from pathlib import Path
+from platform import system
 import regex as re
 import sys
 from tempfile import TemporaryDirectory
@@ -1939,6 +1940,23 @@ def test_find_project_root(self) -> None:
             self.assertEqual(black.find_project_root((src_dir,)), src_dir.resolve())
             self.assertEqual(black.find_project_root((src_python,)), src_dir.resolve())
 
+    def test_bpo_33660_workaround(self) -> None:
+        if system() == "Windows":
+            return
+
+        # https://bugs.python.org/issue33660
+
+        old_cwd = Path.cwd()
+        try:
+            root = Path("/")
+            os.chdir(str(root))
+            path = Path("workspace") / "project"
+            report = black.Report(verbose=True)
+            normalized_path = black.normalize_path_maybe_ignore(path, root, report)
+            self.assertEqual(normalized_path, "workspace/project")
+        finally:
+            os.chdir(str(old_cwd))
+
 
 class BlackDTestCase(AioHTTPTestCase):
     async def get_application(self) -> web.Application:

From 0c6d4ca0c33aa97202e0e94a4a2389cc432597bc Mon Sep 17 00:00:00 2001
From: Tristan Seligmann <mithrandi@mithrandi.net>
Date: Fri, 28 Aug 2020 17:37:37 +0200
Subject: [PATCH 0008/1034] Fix typo in comment (#1650)

Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
---
 fuzz.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/fuzz.py b/fuzz.py
index fdd4917f2ec..604e6ced291 100644
--- a/fuzz.py
+++ b/fuzz.py
@@ -42,8 +42,8 @@ def test_idempotent_any_syntatically_valid_python(
     try:
         dst_contents = black.format_str(src_contents, mode=mode)
     except black.InvalidInput:
-        # This is a bug - if it's valid Python code, as above, black should be
-        # able to code with it.  See issues #970, #1012, #1358, and #1557.
+        # This is a bug - if it's valid Python code, as above, Black should be
+        # able to cope with it.  See issues #970, #1012, #1358, and #1557.
         # TODO: remove this try-except block when issues are resolved.
         return
 

From 573b8de54470dbad8bcaaebd5a28dad507c44666 Mon Sep 17 00:00:00 2001
From: Jon Dufresne <jon.dufresne@gmail.com>
Date: Mon, 31 Aug 2020 14:18:43 -0700
Subject: [PATCH 0009/1034] Remove flake8 W503 from docs as it is ignored by
 default (#1661)

Fixes #1660
---
 .flake8                      |  4 ++--
 docs/compatible_configs.md   | 20 +++++++-------------
 docs/the_black_code_style.md | 10 +++-------
 3 files changed, 12 insertions(+), 22 deletions(-)

diff --git a/.flake8 b/.flake8
index cee6db4446b..656c0df24ee 100644
--- a/.flake8
+++ b/.flake8
@@ -1,7 +1,7 @@
 [flake8]
-ignore = E203, E266, E501, W503
+extend-ignore = E203, E266, E501
 # line length is intentionally set to 80 here because black uses Bugbear
-# See https://github.com/psf/black/blob/master/README.md#line-length for more details
+# See https://github.com/psf/black/blob/master/docs/the_black_code_style.md#line-length for more details
 max-line-length = 80
 max-complexity = 18
 select = B,C,E,F,W,T4,B9
diff --git a/docs/compatible_configs.md b/docs/compatible_configs.md
index 25e959e3281..82f13932b0b 100644
--- a/docs/compatible_configs.md
+++ b/docs/compatible_configs.md
@@ -32,7 +32,7 @@ line_length = 88
 _Black_ wraps imports that surpass `line-length` by moving identifiers into their own
 indented line. If that still doesn't fit the bill, it will put all of them in separate
 lines and put a trailing comma. A more detailed explanation of this behaviour can be
-[found here](https://github.com/psf/black#how-black-wraps-lines).
+[found here](https://github.com/psf/black/blob/master/docs/the_black_code_style.md#how-black-wraps-lines).
 
 isort's default mode of wrapping imports that extend past the `line_length` limit is
 "Grid".
@@ -146,21 +146,15 @@ There are a few deviations that cause incompatibilities with _Black_.
 
 ```
 max-line-length = 88
-extend-ignore = E203, W503
+extend-ignore = E203
 ```
 
 ### Why those options above?
 
-When breaking a line, _Black_ will break it before a binary operator. This is compliant
-with PEP 8, but this behaviour will cause flake8 to raise
-`W503 line break before binary operator` warnings.
-
 In some cases, as determined by PEP 8, _Black_ will enforce an equal amount of
 whitespace around slice operators. Due to this, Flake8 will raise
-`E203 whitespace before ':'` warnings.
-
-Since both of these warnings are not PEP 8 compliant, Flake8 should be configured to
-ignore these warnings via `extend-ignore = E203, W503`.
+`E203 whitespace before ':'` warnings. Since this warning is not PEP 8 compliant, Flake8
+should be configured to ignore it via `extend-ignore = E203`.
 
 Also, as like with isort, flake8 should be configured to allow lines up to the length
 limit of `88`, _Black_'s default. This explains `max-line-length = 88`.
@@ -173,7 +167,7 @@ limit of `88`, _Black_'s default. This explains `max-line-length = 88`.
 ```ini
 [flake8]
 max-line-length = 88
-extend-ignore = E203, W503
+extend-ignore = E203
 ```
 
 </details>
@@ -184,7 +178,7 @@ extend-ignore = E203, W503
 ```cfg
 [flake8]
 max-line-length = 88
-extend-ignore = E203, W503
+extend-ignore = E203
 ```
 
 </details>
@@ -195,7 +189,7 @@ extend-ignore = E203, W503
 ```ini
 [flake8]
 max-line-length = 88
-extend-ignore = E203, W503
+extend-ignore = E203
 ```
 
 </details>
diff --git a/docs/the_black_code_style.md b/docs/the_black_code_style.md
index 09d58307a05..735e9c015d7 100644
--- a/docs/the_black_code_style.md
+++ b/docs/the_black_code_style.md
@@ -199,12 +199,12 @@ You'd do it like this:
 max-line-length = 80
 ...
 select = C,E,F,W,B,B950
-ignore = E203, E501, W503
+extend-ignore = E203, E501
 ```
 
 You'll find _Black_'s own .flake8 config file is configured like this. Explanation of
-why W503 and E203 are disabled can be found further in this documentation. And if you're
-curious about the reasoning behind B950,
+why E203 is disabled can be found further in this documentation. And if you're curious
+about the reasoning behind B950,
 [Bugbear's documentation](https://github.com/PyCQA/flake8-bugbear#opinionated-warnings)
 explains it. The tl;dr is "it's like highway speed limits, we won't bother you if you
 overdo it by a few km/h".
@@ -309,10 +309,6 @@ multiple lines. This is so that _Black_ is compliant with the recent changes in
 [PEP 8](https://www.python.org/dev/peps/pep-0008/#should-a-line-break-before-or-after-a-binary-operator)
 style guide, which emphasizes that this approach improves readability.
 
-This behaviour may raise `W503 line break before binary operator` warnings in style
-guide enforcement tools like Flake8. Since `W503` is not PEP 8 compliant, you should
-tell Flake8 to ignore these warnings.
-
 ### Slices
 
 PEP 8

From 1d2d7264ec7c448744b771910cc972da03b1cb80 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Mon, 31 Aug 2020 17:20:05 -0400
Subject: [PATCH 0010/1034] Fix incorrect space before colon in if/while stmts
 (#1655)

* Fix incorrect space before colon in if/while stmts

Previously Black would format this code

```
if (foo := True):
	print(foo)
```

as

```
if (foo := True) :
	print(foo)
```

adding an incorrect space after the RPAR. Buggy code in the
normalize_invisible_parens function caused the colon to be wrapped in
invisible parentheses. The LPAR of that pair was then prefixed with a
single space at the request of the whitespace function.

This commit fixes the accidental skipping of a pre-condition check
which must return True before parenthesis normalization of a specific
child Leaf or Node can happen. The pre-condition check being skipped
was why the colon was wrapped in invisible parentheses.

* Add an entry in CHANGES.md
---
 CHANGES.md            | 3 +++
 docs/change_log.md    | 5 +++++
 src/black/__init__.py | 4 ++--
 tests/data/pep_572.py | 4 ++++
 4 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 1c53604d4d5..7e356f1f29c 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -7,6 +7,9 @@
 - `Black` now respects `--skip-string-normalization` when normalizing multiline
   docstring quotes (#1637)
 
+- `Black` no longer adds an incorrect space after a parenthesized assignment expression
+  in if/while statements (#1655)
+
 - fixed a crash when PWD=/ on POSIX (#1631)
 
 ### 20.8b1
diff --git a/docs/change_log.md b/docs/change_log.md
index b7337166659..cc5015f873c 100644
--- a/docs/change_log.md
+++ b/docs/change_log.md
@@ -9,6 +9,11 @@
 - `Black` now respects `--skip-string-normalization` when normalizing multiline
   docstring quotes (#1637)
 
+- `Black` no longer adds an incorrect space after a parenthesized assignment expression
+  in if/while statements (#1655)
+
+- fixed a crash when PWD=/ on POSIX (#1631)
+
 ### 20.8b1
 
 #### _Packaging_
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 048e771ce96..64a18655905 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -5190,9 +5190,9 @@ def normalize_invisible_parens(node: Node, parens_after: Set[str]) -> None:
 
         if check_lpar:
             if is_walrus_assignment(child):
-                continue
+                pass
 
-            if child.type == syms.atom:
+            elif child.type == syms.atom:
                 if maybe_make_parens_invisible_in_atom(child, parent=node):
                     wrap_in_parentheses(node, child, visible=False)
             elif is_one_tuple(child):
diff --git a/tests/data/pep_572.py b/tests/data/pep_572.py
index 9e429f913ce..637b3bb38c6 100644
--- a/tests/data/pep_572.py
+++ b/tests/data/pep_572.py
@@ -2,6 +2,8 @@
 (a := a)
 if (match := pattern.search(data)) is None:
     pass
+if (match := pattern.search(data)):
+    pass
 [y := f(x), y ** 2, y ** 3]
 filtered_data = [y for x in data if (y := f(x)) is None]
 (y := f(x))
@@ -41,3 +43,5 @@ def foo(answer: (p := 42) = 5):
 
 while x := f(x):
     pass
+while (x := f(x)):
+    pass

From 1af648d0c14342021bb8c4220fb8adcd7362d45d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C5=81ukasz=20Langa?= <lukasz@langa.pl>
Date: Tue, 1 Sep 2020 13:18:46 +0200
Subject: [PATCH 0011/1034] Mention optional invalid W503 warning in
 pycodestyle

---
 docs/compatible_configs.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/docs/compatible_configs.md b/docs/compatible_configs.md
index 82f13932b0b..990820a6771 100644
--- a/docs/compatible_configs.md
+++ b/docs/compatible_configs.md
@@ -156,6 +156,13 @@ whitespace around slice operators. Due to this, Flake8 will raise
 `E203 whitespace before ':'` warnings. Since this warning is not PEP 8 compliant, Flake8
 should be configured to ignore it via `extend-ignore = E203`.
 
+When breaking a line, _Black_ will break it before a binary operator. This is compliant
+with PEP 8 as of
+[April 2016](https://github.com/python/peps/commit/c59c4376ad233a62ca4b3a6060c81368bd21e85b#diff-64ec08cc46db7540f18f2af46037f599).
+There's a disabled-by-default warning in Flake8 which goes against this PEP 8
+recommendation called `W503 line break before binary operator`. It should not be enabled
+in your configuration.
+
 Also, as like with isort, flake8 should be configured to allow lines up to the length
 limit of `88`, _Black_'s default. This explains `max-line-length = 88`.
 

From 6b935a34d08c0b18d858e7da5093dc69a29c55f2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C5=81ukasz=20Langa?= <lukasz@langa.pl>
Date: Tue, 1 Sep 2020 13:24:31 +0200
Subject: [PATCH 0012/1034] Clarify current trailing comma behavior in the docs

---
 docs/the_black_code_style.md | 14 ++++----------
 1 file changed, 4 insertions(+), 10 deletions(-)

diff --git a/docs/the_black_code_style.md b/docs/the_black_code_style.md
index 735e9c015d7..19464ba482a 100644
--- a/docs/the_black_code_style.md
+++ b/docs/the_black_code_style.md
@@ -244,16 +244,6 @@ required due to an inner function starting immediately after.
 _Black_ will add trailing commas to expressions that are split by comma where each
 element is on its own line. This includes function signatures.
 
-Unnecessary trailing commas are removed if an expression fits in one line. This makes it
-1% more likely that your line won't exceed the allotted line length limit. Moreover, in
-this scenario, if you added another argument to your call, you'd probably fit it in the
-same line anyway. That doesn't make diffs any larger.
-
-One exception to removing trailing commas is tuple expressions with just one element. In
-this case _Black_ won't touch the single trailing comma as this would unexpectedly
-change the underlying data type. Note that this is also the case when commas are used
-while indexing. This is a tuple in disguise: `numpy_array[3, ]`.
-
 One exception to adding trailing commas is function signatures containing `*`, `*args`,
 or `**kwargs`. In this case a trailing comma is only safe to use on Python 3.6. _Black_
 will detect if your file is already 3.6+ only and use trailing commas in this situation.
@@ -262,6 +252,10 @@ in function signatures that have stars in them. In other words, if you'd like a
 comma in this situation and _Black_ didn't recognize it was safe to do so, put it there
 manually and _Black_ will keep it.
 
+A pre-existing trailing comma informs _Black_ to always explode contents of the current
+bracket pair into one item per line. Read more about this in the
+[Pragmatism](#pragmatism) section below.
+
 ### Strings
 
 _Black_ prefers double quotes (`"` and `"""`) over single quotes (`'` and `'''`). It

From 25c1b6dff7264278c1ca1649f321a3bd8df293b1 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Fri, 4 Sep 2020 17:20:55 -0400
Subject: [PATCH 0013/1034] Update primer.json to reflect Black's adoption
 (#1674)

- tox recently adopted Black
https://github.com/tox-dev/tox/commit/a7903508fa07068b327e15cfdbf8ea330ab78765

- attrs already adopted Black but they updated to 20.08b1 + did a format pass and removed some trailing commas
https://github.com/python-attrs/attrs/commit/f680c5b83e65413eeb684c68ece60198015058c3
---
 src/black_primer/primer.json | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/black_primer/primer.json b/src/black_primer/primer.json
index 546f47782cd..6371d44ce1f 100644
--- a/src/black_primer/primer.json
+++ b/src/black_primer/primer.json
@@ -10,7 +10,7 @@
     },
     "attrs": {
       "cli_arguments": [],
-      "expect_formatting_changes": true,
+      "expect_formatting_changes": false,
       "git_clone_url": "https://github.com/python-attrs/attrs.git",
       "long_checkout": false,
       "py_versions": ["all"]
@@ -98,7 +98,7 @@
     },
     "tox": {
       "cli_arguments": [],
-      "expect_formatting_changes": true,
+      "expect_formatting_changes": false,
       "git_clone_url": "https://github.com/tox-dev/tox.git",
       "long_checkout": false,
       "py_versions": ["all"]

From 17908718338e6ba10d01f3b484ed0fe9542b8169 Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <hugovk@users.noreply.github.com>
Date: Sat, 5 Sep 2020 19:38:43 +0300
Subject: [PATCH 0014/1034] Test primer on Pillow (#1679)

---
 src/black_primer/primer.json | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/src/black_primer/primer.json b/src/black_primer/primer.json
index 6371d44ce1f..6086c4c813a 100644
--- a/src/black_primer/primer.json
+++ b/src/black_primer/primer.json
@@ -61,6 +61,13 @@
       "long_checkout": false,
       "py_versions": ["all"]
     },
+    "pillow": {
+      "cli_arguments": [],
+      "expect_formatting_changes": false,
+      "git_clone_url": "https://github.com/python-pillow/Pillow.git",
+      "long_checkout": false,
+      "py_versions": ["all"]
+    },
     "poetry": {
       "cli_arguments": [],
       "expect_formatting_changes": true,

From 6b5753a41781ef7a8746aeea52c26e07f4b43c27 Mon Sep 17 00:00:00 2001
From: Tom Saunders <tom-saunders@users.noreply.github.com>
Date: Sat, 5 Sep 2020 20:15:28 +0100
Subject: [PATCH 0015/1034] Handle .COLOR_DIFF in the same way as .DIFF (#1673)

---
 CHANGES.md            |  2 ++
 src/black/__init__.py |  6 ++---
 tests/test_black.py   | 53 ++++++++++++++++++++++++++++++++++++++++---
 3 files changed, 55 insertions(+), 6 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 7e356f1f29c..52c8016a257 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -12,6 +12,8 @@
 
 - fixed a crash when PWD=/ on POSIX (#1631)
 
+- Prevent coloured diff output being interleaved with multiple files (#1673)
+
 ### 20.8b1
 
 #### _Packaging_
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 64a18655905..f7e7603321a 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -661,7 +661,7 @@ def reformat_one(
                 changed = Changed.YES
         else:
             cache: Cache = {}
-            if write_back != WriteBack.DIFF:
+            if write_back not in (WriteBack.DIFF, WriteBack.COLOR_DIFF):
                 cache = read_cache(mode)
                 res_src = src.resolve()
                 if res_src in cache and cache[res_src] == get_cache_info(res_src):
@@ -735,7 +735,7 @@ async def schedule_formatting(
     :func:`format_file_in_place`.
     """
     cache: Cache = {}
-    if write_back != WriteBack.DIFF:
+    if write_back not in (WriteBack.DIFF, WriteBack.COLOR_DIFF):
         cache = read_cache(mode)
         sources, cached = filter_cached(cache, sources)
         for src in sorted(cached):
@@ -746,7 +746,7 @@ async def schedule_formatting(
     cancelled = []
     sources_to_cache = []
     lock = None
-    if write_back == WriteBack.DIFF:
+    if write_back in (WriteBack.DIFF, WriteBack.COLOR_DIFF):
         # For diff output, we need locks to ensure we don't interleave output
         # from different processes.
         manager = Manager()
diff --git a/tests/test_black.py b/tests/test_black.py
index bc80c8fca8b..edcf7208b46 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+import multiprocessing
 import asyncio
 import logging
 from concurrent.futures import ThreadPoolExecutor
@@ -1395,9 +1396,55 @@ def test_no_cache_when_writeback_diff(self) -> None:
             src = (workspace / "test.py").resolve()
             with src.open("w") as fobj:
                 fobj.write("print('hello')")
-            self.invokeBlack([str(src), "--diff"])
-            cache_file = black.get_cache_file(mode)
-            self.assertFalse(cache_file.exists())
+            with patch("black.read_cache") as read_cache, patch(
+                "black.write_cache"
+            ) as write_cache:
+                self.invokeBlack([str(src), "--diff"])
+                cache_file = black.get_cache_file(mode)
+                self.assertFalse(cache_file.exists())
+                write_cache.assert_not_called()
+                read_cache.assert_not_called()
+
+    def test_no_cache_when_writeback_color_diff(self) -> None:
+        mode = DEFAULT_MODE
+        with cache_dir() as workspace:
+            src = (workspace / "test.py").resolve()
+            with src.open("w") as fobj:
+                fobj.write("print('hello')")
+            with patch("black.read_cache") as read_cache, patch(
+                "black.write_cache"
+            ) as write_cache:
+                self.invokeBlack([str(src), "--diff", "--color"])
+                cache_file = black.get_cache_file(mode)
+                self.assertFalse(cache_file.exists())
+                write_cache.assert_not_called()
+                read_cache.assert_not_called()
+
+    @event_loop()
+    def test_output_locking_when_writeback_diff(self) -> None:
+        with cache_dir() as workspace:
+            for tag in range(0, 4):
+                src = (workspace / f"test{tag}.py").resolve()
+                with src.open("w") as fobj:
+                    fobj.write("print('hello')")
+            with patch("black.Manager", wraps=multiprocessing.Manager) as mgr:
+                self.invokeBlack(["--diff", str(workspace)], exit_code=0)
+                # this isn't quite doing what we want, but if it _isn't_
+                # called then we cannot be using the lock it provides
+                mgr.assert_called()
+
+    @event_loop()
+    def test_output_locking_when_writeback_color_diff(self) -> None:
+        with cache_dir() as workspace:
+            for tag in range(0, 4):
+                src = (workspace / f"test{tag}.py").resolve()
+                with src.open("w") as fobj:
+                    fobj.write("print('hello')")
+            with patch("black.Manager", wraps=multiprocessing.Manager) as mgr:
+                self.invokeBlack(["--diff", "--color", str(workspace)], exit_code=0)
+                # this isn't quite doing what we want, but if it _isn't_
+                # called then we cannot be using the lock it provides
+                mgr.assert_called()
 
     def test_no_cache_when_stdin(self) -> None:
         mode = DEFAULT_MODE

From e3ccabb23c5dc5495bd8f96b5c90c1db6a350d6d Mon Sep 17 00:00:00 2001
From: Bryan Bugyi <bryanbugyi34@gmail.com>
Date: Sat, 5 Sep 2020 20:24:00 -0400
Subject: [PATCH 0016/1034] Fix unstable formatting on string split + %
 formatting (#1680)

Fixes #1595
---
 src/black/__init__.py                  |  2 +-
 src/blib2to3/pgen2/pgen.py             |  3 +--
 tests/data/long_strings.py             |  6 ++----
 tests/data/long_strings__regression.py | 21 +++++++++++++++++----
 4 files changed, 21 insertions(+), 11 deletions(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index f7e7603321a..eed059e2837 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -2668,9 +2668,9 @@ def rhs(line: Line, features: Collection[Feature]) -> Iterator[Line]:
                 transformers = [
                     string_merge,
                     string_paren_strip,
+                    string_split,
                     delimiter_split,
                     standalone_comment_split,
-                    string_split,
                     string_paren_wrap,
                     rhs,
                 ]
diff --git a/src/blib2to3/pgen2/pgen.py b/src/blib2to3/pgen2/pgen.py
index 13ec51d1878..a685145933c 100644
--- a/src/blib2to3/pgen2/pgen.py
+++ b/src/blib2to3/pgen2/pgen.py
@@ -168,8 +168,7 @@ def calcfirst(self, name: Text) -> None:
                 if symbol in inverse:
                     raise ValueError(
                         "rule %s is ambiguous; %s is in the first sets of %s as well"
-                        " as %s"
-                        % (name, symbol, label, inverse[symbol])
+                        " as %s" % (name, symbol, label, inverse[symbol])
                     )
                 inverse[symbol] = label
         self.first[name] = totalset
diff --git a/tests/data/long_strings.py b/tests/data/long_strings.py
index e1ed90f22de..151396b5239 100644
--- a/tests/data/long_strings.py
+++ b/tests/data/long_strings.py
@@ -380,8 +380,7 @@ def foo():
 
 old_fmt_string1 = (
     "While we are on the topic of %s, we should also note that old-style formatting"
-    " must also be preserved, since some %s still uses it."
-    % ("formatting", "code")
+    " must also be preserved, since some %s still uses it." % ("formatting", "code")
 )
 
 old_fmt_string2 = "This is a %s %s %s %s" % (
@@ -448,8 +447,7 @@ def foo():
 
 assert some_type_of_boolean_expression, (
     "Followed by a really really really long string that is used to provide context to"
-    " the AssertionError exception, which uses dynamic string %s."
-    % "formatting"
+    " the AssertionError exception, which uses dynamic string %s." % "formatting"
 )
 
 assert some_type_of_boolean_expression, (
diff --git a/tests/data/long_strings__regression.py b/tests/data/long_strings__regression.py
index 044bb4a5deb..33bf14cfaa3 100644
--- a/tests/data/long_strings__regression.py
+++ b/tests/data/long_strings__regression.py
@@ -310,6 +310,13 @@ def who(self):
             passenger_association=passenger_association,
         )
 
+if __name__ == "__main__":
+    for i in range(4, 8):
+        cmd = (
+            r"for pid in $(ps aux | grep paster | grep -v grep | grep '\-%d' | awk '{print $2}'); do kill $pid; done"
+            % (i)
+        )
+
 # output
 
 
@@ -435,14 +442,12 @@ def foo():
 
 func_call_where_string_arg_has_old_fmt_and_bad_parens(
     "A long string with {}. This string is so long that it is ridiculous. It can't fit"
-    " on one line at alllll."
-    % "formatting",
+    " on one line at alllll." % "formatting",
 )
 
 func_call_where_string_arg_has_old_fmt_and_bad_parens(
     "A long string with {}. This {} is so long that it is ridiculous. It can't fit on"
-    " one line at alllll."
-    % ("formatting", "string"),
+    " one line at alllll." % ("formatting", "string"),
 )
 
 
@@ -702,3 +707,11 @@ def who(self):
                 passenger_association=passenger_association,
             )
         )
+
+
+if __name__ == "__main__":
+    for i in range(4, 8):
+        cmd = (
+            r"for pid in $(ps aux | grep paster | grep -v grep | grep '\-%d' | awk"
+            r" '{print $2}'); do kill $pid; done" % (i)
+        )

From 7bca930ca3d84bbd01e98937b6b8a493d0254c7c Mon Sep 17 00:00:00 2001
From: Bryan Bugyi <bryanbugyi34@gmail.com>
Date: Sun, 6 Sep 2020 11:02:57 -0400
Subject: [PATCH 0017/1034] Fix crash on concatenated string + comment (fixes
 #1596) (#1677)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 src/black/__init__.py                  | 28 +++++++++++++++++++++-----
 tests/data/long_strings__regression.py | 27 +++++++++++++++++++++++++
 2 files changed, 50 insertions(+), 5 deletions(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index eed059e2837..ed5256eefe1 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -2889,11 +2889,8 @@ class StringMerger(CustomSplitMapMixin, StringTransformer):
     """StringTransformer that merges strings together.
 
     Requirements:
-        (A) The line contains adjacent strings such that at most one substring
-        has inline comments AND none of those inline comments are pragmas AND
-        the set of all substring prefixes is either of length 1 or equal to
-        {"", "f"} AND none of the substrings are raw strings (i.e. are prefixed
-        with 'r').
+        (A) The line contains adjacent strings such that ALL of the validation checks
+        listed in StringMerger.__validate_msg(...)'s docstring pass.
             OR
         (B) The line contains a string which uses line continuation backslashes.
 
@@ -3142,6 +3139,7 @@ def __validate_msg(line: Line, string_idx: int) -> TResult[None]:
             * Ok(None), if ALL validation checks (listed below) pass.
                 OR
             * Err(CannotTransform), if any of the following are true:
+                - The target string group does not contain ANY stand-alone comments.
                 - The target string is not in a string group (i.e. it has no
                   adjacent strings).
                 - The string group has more than one inline comment.
@@ -3150,6 +3148,26 @@ def __validate_msg(line: Line, string_idx: int) -> TResult[None]:
                   length greater than one and is not equal to {"", "f"}.
                 - The string group consists of raw strings.
         """
+        # We first check for "inner" stand-alone comments (i.e. stand-alone
+        # comments that have a string leaf before them AND after them).
+        for inc in [1, -1]:
+            i = string_idx
+            found_sa_comment = False
+            is_valid_index = is_valid_index_factory(line.leaves)
+            while is_valid_index(i) and line.leaves[i].type in [
+                token.STRING,
+                STANDALONE_COMMENT,
+            ]:
+                if line.leaves[i].type == STANDALONE_COMMENT:
+                    found_sa_comment = True
+                elif found_sa_comment:
+                    return TErr(
+                        "StringMerger does NOT merge string groups which contain "
+                        "stand-alone comments."
+                    )
+
+                i += inc
+
         num_of_inline_string_comments = 0
         set_of_prefixes = set()
         num_of_strings = 0
diff --git a/tests/data/long_strings__regression.py b/tests/data/long_strings__regression.py
index 33bf14cfaa3..745a636cdcf 100644
--- a/tests/data/long_strings__regression.py
+++ b/tests/data/long_strings__regression.py
@@ -310,6 +310,19 @@ def who(self):
             passenger_association=passenger_association,
         )
 
+xxxxxxx_xxxxxx_xxxxxxx = xxx(
+    [
+        xxxxxxxxxxxx(
+            xxxxxx_xxxxxxx=(
+                '((x.aaaaaaaaa = "xxxxxx.xxxxxxxxxxxxxxxxxxxxx") || (x.xxxxxxxxx = "xxxxxxxxxxxx")) && '
+                # xxxxx xxxxxxxxxxxx xxxx xxx (xxxxxxxxxxxxxxxx) xx x xxxxxxxxx xx xxxxxx.
+                "(x.bbbbbbbbbbbb.xxx != "
+                '"xxx:xxx:xxx::cccccccccccc:xxxxxxx-xxxx/xxxxxxxxxxx/xxxxxxxxxxxxxxxxx") && '
+            )
+        )
+    ]
+)
+
 if __name__ == "__main__":
     for i in range(4, 8):
         cmd = (
@@ -709,6 +722,20 @@ def who(self):
         )
 
 
+xxxxxxx_xxxxxx_xxxxxxx = xxx(
+    [
+        xxxxxxxxxxxx(
+            xxxxxx_xxxxxxx=(
+                '((x.aaaaaaaaa = "xxxxxx.xxxxxxxxxxxxxxxxxxxxx") || (x.xxxxxxxxx ='
+                ' "xxxxxxxxxxxx")) && '
+                # xxxxx xxxxxxxxxxxx xxxx xxx (xxxxxxxxxxxxxxxx) xx x xxxxxxxxx xx xxxxxx.
+                "(x.bbbbbbbbbbbb.xxx != "
+                '"xxx:xxx:xxx::cccccccccccc:xxxxxxx-xxxx/xxxxxxxxxxx/xxxxxxxxxxxxxxxxx") && '
+            )
+        )
+    ]
+)
+
 if __name__ == "__main__":
     for i in range(4, 8):
         cmd = (

From 6284953d07060804dcdeacf4626b76aed7a20683 Mon Sep 17 00:00:00 2001
From: Bryan Bugyi <bryanbugyi34@gmail.com>
Date: Sun, 6 Sep 2020 12:15:40 -0400
Subject: [PATCH 0018/1034] Fix crash on assert and parenthesized % format
 (fixes #1597, fixes #1605) (#1681)

---
 src/black/__init__.py                  | 27 ++++++++++++++---
 tests/data/long_strings__regression.py | 42 ++++++++++++++++++++++++++
 2 files changed, 65 insertions(+), 4 deletions(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index ed5256eefe1..3753d5fca8d 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -112,6 +112,10 @@ class InvalidInput(ValueError):
     """Raised when input source code fails all parse attempts."""
 
 
+class BracketMatchError(KeyError):
+    """Raised when an opening bracket is unable to be matched to a closing bracket."""
+
+
 T = TypeVar("T")
 E = TypeVar("E", bound=Exception)
 
@@ -1308,7 +1312,13 @@ def mark(self, leaf: Leaf) -> None:
         self.maybe_decrement_after_lambda_arguments(leaf)
         if leaf.type in CLOSING_BRACKETS:
             self.depth -= 1
-            opening_bracket = self.bracket_match.pop((self.depth, leaf.type))
+            try:
+                opening_bracket = self.bracket_match.pop((self.depth, leaf.type))
+            except KeyError as e:
+                raise BracketMatchError(
+                    "Unable to match a closing bracket to the following opening"
+                    f" bracket: {leaf}"
+                ) from e
             leaf.opening_bracket = opening_bracket
             if not leaf.value:
                 self.invisible.append(leaf)
@@ -3324,10 +3334,17 @@ def do_transform(self, line: Line, string_idx: int) -> Iterator[TResult[Line]]:
                 yield TErr(
                     "Will not strip parentheses which have comments attached to them."
                 )
+                return
 
         new_line = line.clone()
         new_line.comments = line.comments.copy()
-        append_leaves(new_line, line, LL[: string_idx - 1])
+        try:
+            append_leaves(new_line, line, LL[: string_idx - 1])
+        except BracketMatchError:
+            # HACK: I believe there is currently a bug somewhere in
+            # right_hand_split() that is causing brackets to not be tracked
+            # properly by a shared BracketTracker.
+            append_leaves(new_line, line, LL[: string_idx - 1], preformatted=True)
 
         string_leaf = Leaf(token.STRING, LL[string_idx].value)
         LL[string_idx - 1].remove()
@@ -4598,7 +4615,9 @@ def line_to_string(line: Line) -> str:
     return str(line).strip("\n")
 
 
-def append_leaves(new_line: Line, old_line: Line, leaves: List[Leaf]) -> None:
+def append_leaves(
+    new_line: Line, old_line: Line, leaves: List[Leaf], preformatted: bool = False
+) -> None:
     """
     Append leaves (taken from @old_line) to @new_line, making sure to fix the
     underlying Node structure where appropriate.
@@ -4614,7 +4633,7 @@ def append_leaves(new_line: Line, old_line: Line, leaves: List[Leaf]) -> None:
     for old_leaf in leaves:
         new_leaf = Leaf(old_leaf.type, old_leaf.value)
         replace_child(old_leaf, new_leaf)
-        new_line.append(new_leaf)
+        new_line.append(new_leaf, preformatted=preformatted)
 
         for comment_leaf in old_line.comments_after(old_leaf):
             new_line.append(comment_leaf, preformatted=True)
diff --git a/tests/data/long_strings__regression.py b/tests/data/long_strings__regression.py
index 745a636cdcf..1c82613d410 100644
--- a/tests/data/long_strings__regression.py
+++ b/tests/data/long_strings__regression.py
@@ -330,6 +330,25 @@ def who(self):
             % (i)
         )
 
+def A():
+    def B():
+        def C():
+            def D():
+                def E():
+                    def F():
+                        def G():
+                            assert (
+                                c_float(val[0][0] / val[0][1]).value
+                                == c_float(value[0][0] / value[0][1]).value
+                            ), "%s didn't roundtrip" % tag
+
+class xxxxxxxxxxxxxxxxxxxxx(xxxx.xxxxxxxxxxxxx):
+    def xxxxxxx_xxxxxx(xxxx):
+        assert xxxxxxx_xxxx in [
+            x.xxxxx.xxxxxx.xxxxx.xxxxxx,
+            x.xxxxx.xxxxxx.xxxxx.xxxx,
+        ], ("xxxxxxxxxxx xxxxxxx xxxx (xxxxxx xxxx) %x xxx xxxxx" % xxxxxxx_xxxx)
+
 # output
 
 
@@ -742,3 +761,26 @@ def who(self):
             r"for pid in $(ps aux | grep paster | grep -v grep | grep '\-%d' | awk"
             r" '{print $2}'); do kill $pid; done" % (i)
         )
+
+
+def A():
+    def B():
+        def C():
+            def D():
+                def E():
+                    def F():
+                        def G():
+                            assert (
+                                c_float(val[0][0] / val[0][1]).value
+                                == c_float(value[0][0] / value[0][1]).value
+                            ), "%s didn't roundtrip" % tag
+
+
+class xxxxxxxxxxxxxxxxxxxxx(xxxx.xxxxxxxxxxxxx):
+    def xxxxxxx_xxxxxx(xxxx):
+        assert xxxxxxx_xxxx in [
+            x.xxxxx.xxxxxx.xxxxx.xxxxxx,
+            x.xxxxx.xxxxxx.xxxxx.xxxx,
+        ], (
+            "xxxxxxxxxxx xxxxxxx xxxx (xxxxxx xxxx) %x xxx xxxxx" % xxxxxxx_xxxx
+        )

From 1e8916f450505bfe58649c1ff8c0a3708de47daa Mon Sep 17 00:00:00 2001
From: Michael Wilkinson <goi42@users.noreply.github.com>
Date: Tue, 8 Sep 2020 12:42:57 -0400
Subject: [PATCH 0019/1034] Add link to conda-forge integration (#1687)

* Add link to conda-forge integration

resolves #1686

* README: keep PyPI tags together

Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
---
 README.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/README.md b/README.md
index 20f6fa420b2..942e85444d3 100644
--- a/README.md
+++ b/README.md
@@ -11,6 +11,7 @@
 <a href="/psf/black/blob/master/LICENSE"><img alt="License: MIT" src="https://black.readthedocs.io/en/stable/_static/license.svg"></a>
 <a href="https://pypi.org/project/black/"><img alt="PyPI" src="https://img.shields.io/pypi/v/black"></a>
 <a href="https://pepy.tech/project/black"><img alt="Downloads" src="https://pepy.tech/badge/black"></a>
+<a href="https://anaconda.org/conda-forge/black/"><img alt="conda-forge" src="https://img.shields.io/conda/dn/conda-forge/black.svg?label=conda-forge"></a>
 <a href="/psf/black"><img alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></a>
 </p>
 

From cd055efd7d999421984e8b63afe53b5f9854deb9 Mon Sep 17 00:00:00 2001
From: Bryan Bugyi <bryanbugyi34@gmail.com>
Date: Thu, 10 Sep 2020 12:24:01 -0400
Subject: [PATCH 0020/1034] Fix unstable subscript assignment string wrapping
 (#1678)

Fixes #1598
---
 src/black/__init__.py                  | 7 +++++--
 tests/data/long_strings__regression.py | 9 +++++++++
 2 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index 3753d5fca8d..bfb77126218 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -3507,9 +3507,12 @@ def __get_max_string_length(self, line: Line, string_idx: int) -> int:
                 # WMA4 a single space.
                 offset += 1
 
-                # WMA4 the lengths of any leaves that came before that space.
-                for leaf in LL[: p_idx + 1]:
+                # WMA4 the lengths of any leaves that came before that space,
+                # but after any closing bracket before that space.
+                for leaf in reversed(LL[: p_idx + 1]):
                     offset += len(str(leaf))
+                    if leaf.type in CLOSING_BRACKETS:
+                        break
 
         if is_valid_index(string_idx + 1):
             N = LL[string_idx + 1]
diff --git a/tests/data/long_strings__regression.py b/tests/data/long_strings__regression.py
index 1c82613d410..8290a4cbc1c 100644
--- a/tests/data/long_strings__regression.py
+++ b/tests/data/long_strings__regression.py
@@ -349,6 +349,10 @@ def xxxxxxx_xxxxxx(xxxx):
             x.xxxxx.xxxxxx.xxxxx.xxxx,
         ], ("xxxxxxxxxxx xxxxxxx xxxx (xxxxxx xxxx) %x xxx xxxxx" % xxxxxxx_xxxx)
 
+value.__dict__[
+    key
+] = "test"  # set some Thrift field to non-None in the struct aa bb cc dd ee
+
 # output
 
 
@@ -784,3 +788,8 @@ def xxxxxxx_xxxxxx(xxxx):
         ], (
             "xxxxxxxxxxx xxxxxxx xxxx (xxxxxx xxxx) %x xxx xxxxx" % xxxxxxx_xxxx
         )
+
+
+value.__dict__[
+    key
+] = "test"  # set some Thrift field to non-None in the struct aa bb cc dd ee

From ecc1f17ee57fd1d6c29e47194b1025721f99455b Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <hugovk@users.noreply.github.com>
Date: Thu, 10 Sep 2020 22:52:23 +0300
Subject: [PATCH 0021/1034] Virtualenv is now formatted with newest Black
 https://github.com/pypa/virtualenv/pull/1939 (#1695)

---
 src/black_primer/primer.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/black_primer/primer.json b/src/black_primer/primer.json
index 6086c4c813a..8a90192f27d 100644
--- a/src/black_primer/primer.json
+++ b/src/black_primer/primer.json
@@ -112,7 +112,7 @@
     },
     "virtualenv": {
       "cli_arguments": [],
-      "expect_formatting_changes": true,
+      "expect_formatting_changes": false,
       "git_clone_url": "https://github.com/pypa/virtualenv.git",
       "long_checkout": false,
       "py_versions": ["all"]

From c0a8e4224360a6917dcb5d889b08d5fdcfaf7c2d Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Thu, 10 Sep 2020 16:21:37 -0400
Subject: [PATCH 0022/1034] Fix empty line handling when formatting typing
 stubs (#1646)

Black used to erroneously remove all empty lines between non-function
code and decorators when formatting typing stubs. Now a single empty
line is enforced.

I chose for putting empty lines around decorated classes that have empty
bodies since removing empty lines around such classes would cause a
formatting issue that seems to be impossible to fix.

For example:

```
class A: ...
@some_decorator
class B: ...
class C: ...
class D: ...

@some_other_decorator
def foo(): -> None: ...
```

It is easy to enforce no empty lines between class A, B, and C.
Just return 0, 0 for a line that is a decorator and precedes an stub
class. Fortunately before this commit, empty lines after that class
would be removed already.

Now let's look at the empty line between class D and function foo. In
this case, there should be an empty line there since it's class code next
to function code. The problem is that when deciding to add X empty lines
before a decorator, you can't tell whether it's before a class or a
function. If the decorator is before a function, then an empty line
is needed, while no empty lines are needed when the decorator is
before a class.

So even though I personally prefer no empty lines around decorated
classes, I had to go the other way surrounding decorated classes with
empty lines.

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 CHANGES.md              |  3 ++
 docs/change_log.md      |  3 ++
 src/black/__init__.py   | 11 +++++--
 tests/data/force_pyi.py | 67 ++++++++++++++++++++++++++++++++++++++---
 tests/test_black.py     |  7 +++--
 5 files changed, 82 insertions(+), 9 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 52c8016a257..59d9320639b 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -7,6 +7,9 @@
 - `Black` now respects `--skip-string-normalization` when normalizing multiline
   docstring quotes (#1637)
 
+- `Black` no longer removes all empty lines between non-function code and decorators
+  when formatting typing stubs. Now `Black` enforces a single empty line. (#1646)
+
 - `Black` no longer adds an incorrect space after a parenthesized assignment expression
   in if/while statements (#1655)
 
diff --git a/docs/change_log.md b/docs/change_log.md
index cc5015f873c..e183ca545b6 100644
--- a/docs/change_log.md
+++ b/docs/change_log.md
@@ -9,6 +9,9 @@
 - `Black` now respects `--skip-string-normalization` when normalizing multiline
   docstring quotes (#1637)
 
+- `Black` no longer removes all empty lines between non-function code and decorators
+  when formatting typing stubs. Now `Black` enforces a single empty line. (#1646)
+
 - `Black` no longer adds an incorrect space after a parenthesized assignment expression
   in if/while statements (#1655)
 
diff --git a/src/black/__init__.py b/src/black/__init__.py
index bfb77126218..9e18a7d904b 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -1834,6 +1834,10 @@ def _maybe_empty_lines_for_class_or_def(
             return 0, 0
 
         if self.previous_line.is_decorator:
+            if self.is_pyi and current_line.is_stub_class:
+                # Insert an empty line after a decorated stub class
+                return 0, 1
+
             return 0, 0
 
         if self.previous_line.depth < current_line.depth and (
@@ -1857,8 +1861,11 @@ def _maybe_empty_lines_for_class_or_def(
                     newlines = 0
                 else:
                     newlines = 1
-            elif current_line.is_def and not self.previous_line.is_def:
-                # Blank line between a block of functions and a block of non-functions
+            elif (
+                current_line.is_def or current_line.is_decorator
+            ) and not self.previous_line.is_def:
+                # Blank line between a block of functions (maybe with preceding
+                # decorators) and a block of non-functions
                 newlines = 1
             else:
                 newlines = 0
diff --git a/tests/data/force_pyi.py b/tests/data/force_pyi.py
index 25246c22ca7..07ed93c6879 100644
--- a/tests/data/force_pyi.py
+++ b/tests/data/force_pyi.py
@@ -1,6 +1,65 @@
-def f(): ...
+from typing import Union
+
+@bird
+def zoo(): ...
+
+class A: ...
+@bar
+class B:
+    def BMethod(self) -> None: ...
+    @overload
+    def BMethod(self, arg : List[str]) -> None: ...
+
+class C: ...
+@hmm
+class D: ...
+class E: ...
+
+@baz
+def foo() -> None:
+    ...
+
+class F (A , C): ...
+def spam() -> None: ...
+
+@overload
+def spam(arg: str) -> str: ...
+
+var  : int = 1
+
+def eggs() -> Union[str, int]: ...
 
-def g(): ...
 # output
-def f(): ...
-def g(): ...
+
+from typing import Union
+
+@bird
+def zoo(): ...
+
+class A: ...
+
+@bar
+class B:
+    def BMethod(self) -> None: ...
+    @overload
+    def BMethod(self, arg: List[str]) -> None: ...
+
+class C: ...
+
+@hmm
+class D: ...
+
+class E: ...
+
+@baz
+def foo() -> None: ...
+
+class F(A, C): ...
+
+def spam() -> None: ...
+@overload
+def spam(arg: str) -> str: ...
+
+var: int = 1
+
+def eggs() -> Union[str, int]: ...
diff --git a/tests/test_black.py b/tests/test_black.py
index edcf7208b46..e928dc04984 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -1574,7 +1574,6 @@ def test_tricky_unicode_symbols(self) -> None:
         black.assert_stable(source, actual, DEFAULT_MODE)
 
     def test_single_file_force_pyi(self) -> None:
-        reg_mode = DEFAULT_MODE
         pyi_mode = replace(DEFAULT_MODE, is_pyi=True)
         contents, expected = read_data("force_pyi")
         with cache_dir() as workspace:
@@ -1587,9 +1586,11 @@ def test_single_file_force_pyi(self) -> None:
             # verify cache with --pyi is separate
             pyi_cache = black.read_cache(pyi_mode)
             self.assertIn(path, pyi_cache)
-            normal_cache = black.read_cache(reg_mode)
+            normal_cache = black.read_cache(DEFAULT_MODE)
             self.assertNotIn(path, normal_cache)
-        self.assertEqual(actual, expected)
+        self.assertFormatEqual(expected, actual)
+        black.assert_equivalent(contents, actual)
+        black.assert_stable(contents, actual, pyi_mode)
 
     @event_loop()
     def test_multi_file_force_pyi(self) -> None:

From 811decd7f10fb2fb3ae343b9d9d0a3ae53b86a53 Mon Sep 17 00:00:00 2001
From: Daniel <61800298+ffe4@users.noreply.github.com>
Date: Sun, 13 Sep 2020 17:59:18 +0200
Subject: [PATCH 0023/1034] Fix typo in docstring (#1700)

Added a missing preposition
---
 src/black/__init__.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index 9e18a7d904b..ffaafe23f9e 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -925,7 +925,7 @@ def format_stdin_to_stdout(
 
 
 def format_file_contents(src_contents: str, *, fast: bool, mode: Mode) -> FileContent:
-    """Reformat contents a file and return new contents.
+    """Reformat contents of a file and return new contents.
 
     If `fast` is False, additionally confirm that the reformatted code is
     valid by calling :func:`assert_equivalent` and :func:`assert_stable` on it.

From 6dddbd72414061cde9dd8ee72eac373b7fcf8b54 Mon Sep 17 00:00:00 2001
From: QuentinSoubeyran <45202794+QuentinSoubeyran@users.noreply.github.com>
Date: Sat, 19 Sep 2020 20:33:10 +0200
Subject: [PATCH 0024/1034] PEP 614 support (#1717)

---
 CHANGES.md               |   2 +
 Pipfile                  |   2 +-
 Pipfile.lock             | 297 +++++++++++++++++++++++++--------------
 src/black/__init__.py    |  70 ++++++++-
 src/blib2to3/Grammar.txt |   2 +-
 tests/data/decorators.py | 176 +++++++++++++++++++++++
 tests/data/python39.py   |  37 +++++
 tests/test_black.py      |  61 +++++++-
 8 files changed, 530 insertions(+), 117 deletions(-)
 create mode 100644 tests/data/decorators.py
 create mode 100644 tests/data/python39.py

diff --git a/CHANGES.md b/CHANGES.md
index 59d9320639b..7ad3482d07a 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -17,6 +17,8 @@
 
 - Prevent coloured diff output being interleaved with multiple files (#1673)
 
+- Added support for PEP 614 relaxed decorator syntax on python 3.9 (#1711)
+
 ### 20.8b1
 
 #### _Packaging_
diff --git a/Pipfile b/Pipfile
index 44f57f6773c..1ced1ed096b 100644
--- a/Pipfile
+++ b/Pipfile
@@ -29,7 +29,7 @@ mypy_extensions = ">=0.4.3"
 pathspec = ">=0.6"
 regex = ">=2020.1.8"
 toml = ">=0.10.1"
-typed-ast = "==1.4.0"
+typed-ast = "==1.4.1"
 typing_extensions = ">=3.7.4"
 black = {editable = true,extras = ["d"],path = "."}
 dataclasses = {"python_version <" = "3.7","version >" = "0.6"}
diff --git a/Pipfile.lock b/Pipfile.lock
index 32b8012ff0e..e09d69ea83d 100644
--- a/Pipfile.lock
+++ b/Pipfile.lock
@@ -1,7 +1,7 @@
 {
     "_meta": {
         "hash": {
-            "sha256": "61d09a6b8a8c310becd5e108ed08e0eeae50c7323c08c8040367abded0cb1031"
+            "sha256": "46390803c9b9e1b77a1b4a29de602d864dea188488d3aee6361030c91529611c"
         },
         "pipfile-spec": 6,
         "requires": {},
@@ -58,11 +58,11 @@
         },
         "attrs": {
             "hashes": [
-                "sha256:0ef97238856430dcf9228e07f316aefc17e8939fc8507e18c6501b761ef1a42a",
-                "sha256:2867b7b9f8326499ab5b0e2d12801fa5c98842d2cbd22b35112ae04bf85b4dff"
+                "sha256:26b54ddbbb9ee1d34d5d3668dd37d6cf74990ab23c828c2888dccdceee395594",
+                "sha256:fce7fc47dfc976152e82d53ff92fa0407700c21acd20886a13777a0d20e655dc"
             ],
             "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==20.1.0"
+            "version": "==20.2.0"
         },
         "black": {
             "editable": true,
@@ -186,39 +186,40 @@
         },
         "toml": {
             "hashes": [
-                "sha256:229f81c57791a41d65e399fc06bf0848bab550a9dfd5ed66df18ce5f05e73d5c",
                 "sha256:235682dd292d5899d361a811df37e04a8828a5b1da3115886b73cf81ebc9100e",
+                "sha256:bda89d5935c2eac546d648028b9901107a595863cb36bae0c73ac804a9b4ce88",
                 "sha256:926b612be1e5ce0634a2ca03470f95169cf16f939018233a670519cb4ac58b0f",
-                "sha256:bda89d5935c2eac546d648028b9901107a595863cb36bae0c73ac804a9b4ce88"
+                "sha256:229f81c57791a41d65e399fc06bf0848bab550a9dfd5ed66df18ce5f05e73d5c"
             ],
             "index": "pypi",
             "version": "==0.10.1"
         },
         "typed-ast": {
             "hashes": [
-                "sha256:1170afa46a3799e18b4c977777ce137bb53c7485379d9706af8a59f2ea1aa161",
-                "sha256:18511a0b3e7922276346bcb47e2ef9f38fb90fd31cb9223eed42c85d1312344e",
-                "sha256:262c247a82d005e43b5b7f69aff746370538e176131c32dda9cb0f324d27141e",
-                "sha256:2b907eb046d049bcd9892e3076c7a6456c93a25bebfe554e931620c90e6a25b0",
-                "sha256:354c16e5babd09f5cb0ee000d54cfa38401d8b8891eefa878ac772f827181a3c",
-                "sha256:48e5b1e71f25cfdef98b013263a88d7145879fbb2d5185f2a0c79fa7ebbeae47",
-                "sha256:4e0b70c6fc4d010f8107726af5fd37921b666f5b31d9331f0bd24ad9a088e631",
-                "sha256:630968c5cdee51a11c05a30453f8cd65e0cc1d2ad0d9192819df9978984529f4",
-                "sha256:66480f95b8167c9c5c5c87f32cf437d585937970f3fc24386f313a4c97b44e34",
-                "sha256:71211d26ffd12d63a83e079ff258ac9d56a1376a25bc80b1cdcdf601b855b90b",
-                "sha256:7954560051331d003b4e2b3eb822d9dd2e376fa4f6d98fee32f452f52dd6ebb2",
-                "sha256:838997f4310012cf2e1ad3803bce2f3402e9ffb71ded61b5ee22617b3a7f6b6e",
-                "sha256:95bd11af7eafc16e829af2d3df510cecfd4387f6453355188342c3e79a2ec87a",
-                "sha256:bc6c7d3fa1325a0c6613512a093bc2a2a15aeec350451cbdf9e1d4bffe3e3233",
-                "sha256:cc34a6f5b426748a507dd5d1de4c1978f2eb5626d51326e43280941206c209e1",
-                "sha256:d755f03c1e4a51e9b24d899561fec4ccaf51f210d52abdf8c07ee2849b212a36",
-                "sha256:d7c45933b1bdfaf9f36c579671fec15d25b06c8398f113dab64c18ed1adda01d",
-                "sha256:d896919306dd0aa22d0132f62a1b78d11aaf4c9fc5b3410d3c666b818191630a",
-                "sha256:fdc1c9bbf79510b76408840e009ed65958feba92a88833cdceecff93ae8fff66",
-                "sha256:ffde2fbfad571af120fcbfbbc61c72469e72f550d676c3342492a9dfdefb8f12"
+                "sha256:0666aa36131496aed8f7be0410ff974562ab7eeac11ef351def9ea6fa28f6355",
+                "sha256:0c2c07682d61a629b68433afb159376e24e5b2fd4641d35424e462169c0a7919",
+                "sha256:249862707802d40f7f29f6e1aad8d84b5aa9e44552d2cc17384b209f091276aa",
+                "sha256:24995c843eb0ad11a4527b026b4dde3da70e1f2d8806c99b7b4a7cf491612652",
+                "sha256:269151951236b0f9a6f04015a9004084a5ab0d5f19b57de779f908621e7d8b75",
+                "sha256:4083861b0aa07990b619bd7ddc365eb7fa4b817e99cf5f8d9cf21a42780f6e01",
+                "sha256:498b0f36cc7054c1fead3d7fc59d2150f4d5c6c56ba7fb150c013fbc683a8d2d",
+                "sha256:4e3e5da80ccbebfff202a67bf900d081906c358ccc3d5e3c8aea42fdfdfd51c1",
+                "sha256:6daac9731f172c2a22ade6ed0c00197ee7cc1221aa84cfdf9c31defeb059a907",
+                "sha256:715ff2f2df46121071622063fc7543d9b1fd19ebfc4f5c8895af64a77a8c852c",
+                "sha256:73d785a950fc82dd2a25897d525d003f6378d1cb23ab305578394694202a58c3",
+                "sha256:8c8aaad94455178e3187ab22c8b01a3837f8ee50e09cf31f1ba129eb293ec30b",
+                "sha256:8ce678dbaf790dbdb3eba24056d5364fb45944f33553dd5869b7580cdbb83614",
+                "sha256:aaee9905aee35ba5905cfb3c62f3e83b3bec7b39413f0a7f19be4e547ea01ebb",
+                "sha256:bcd3b13b56ea479b3650b82cabd6b5343a625b0ced5429e4ccad28a8973f301b",
+                "sha256:c9e348e02e4d2b4a8b2eedb48210430658df6951fa484e59de33ff773fbd4b41",
+                "sha256:d205b1b46085271b4e15f670058ce182bd1199e56b317bf2ec004b6a44f911f6",
+                "sha256:d43943ef777f9a1c42bf4e552ba23ac77a6351de620aa9acf64ad54933ad4d34",
+                "sha256:d5d33e9e7af3b34a40dc05f498939f0ebf187f07c385fd58d591c533ad8562fe",
+                "sha256:fc0fea399acb12edbf8a628ba8d2312f583bdbdb3335635db062fa98cf71fca4",
+                "sha256:fe460b922ec15dd205595c9b5b99e2f056fd98ae8f9f56b888e7a17dc2b757e7"
             ],
             "index": "pypi",
-            "version": "==1.4.0"
+            "version": "==1.4.1"
         },
         "typing-extensions": {
             "hashes": [
@@ -305,11 +306,11 @@
         },
         "attrs": {
             "hashes": [
-                "sha256:0ef97238856430dcf9228e07f316aefc17e8939fc8507e18c6501b761ef1a42a",
-                "sha256:2867b7b9f8326499ab5b0e2d12801fa5c98842d2cbd22b35112ae04bf85b4dff"
+                "sha256:26b54ddbbb9ee1d34d5d3668dd37d6cf74990ab23c828c2888dccdceee395594",
+                "sha256:fce7fc47dfc976152e82d53ff92fa0407700c21acd20886a13777a0d20e655dc"
             ],
             "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==20.1.0"
+            "version": "==20.2.0"
         },
         "babel": {
             "hashes": [
@@ -328,11 +329,11 @@
         },
         "bleach": {
             "hashes": [
-                "sha256:2bce3d8fab545a6528c8fa5d9f9ae8ebc85a56da365c7f85180bfe96a35ef22f",
-                "sha256:3c4c520fdb9db59ef139915a5db79f8b51bc2a7257ea0389f30c846883430a4b"
+                "sha256:52b5919b81842b1854196eaae5ca29679a2f2e378905c346d3ca8227c2c66080",
+                "sha256:9f8ccbeb6183c6e6cddea37592dfb0167485c1e3b13b3363bc325aa8bda3adbd"
             ],
             "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
-            "version": "==3.1.5"
+            "version": "==3.2.1"
         },
         "certifi": {
             "hashes": [
@@ -341,6 +342,39 @@
             ],
             "version": "==2020.6.20"
         },
+        "cffi": {
+            "hashes": [
+                "sha256:0da50dcbccd7cb7e6c741ab7912b2eff48e85af217d72b57f80ebc616257125e",
+                "sha256:12a453e03124069b6896107ee133ae3ab04c624bb10683e1ed1c1663df17c13c",
+                "sha256:15419020b0e812b40d96ec9d369b2bc8109cc3295eac6e013d3261343580cc7e",
+                "sha256:15a5f59a4808f82d8ec7364cbace851df591c2d43bc76bcbe5c4543a7ddd1bf1",
+                "sha256:23e44937d7695c27c66a54d793dd4b45889a81b35c0751ba91040fe825ec59c4",
+                "sha256:29c4688ace466a365b85a51dcc5e3c853c1d283f293dfcc12f7a77e498f160d2",
+                "sha256:57214fa5430399dffd54f4be37b56fe22cedb2b98862550d43cc085fb698dc2c",
+                "sha256:577791f948d34d569acb2d1add5831731c59d5a0c50a6d9f629ae1cefd9ca4a0",
+                "sha256:6539314d84c4d36f28d73adc1b45e9f4ee2a89cdc7e5d2b0a6dbacba31906798",
+                "sha256:65867d63f0fd1b500fa343d7798fa64e9e681b594e0a07dc934c13e76ee28fb1",
+                "sha256:672b539db20fef6b03d6f7a14b5825d57c98e4026401fce838849f8de73fe4d4",
+                "sha256:6843db0343e12e3f52cc58430ad559d850a53684f5b352540ca3f1bc56df0731",
+                "sha256:7057613efefd36cacabbdbcef010e0a9c20a88fc07eb3e616019ea1692fa5df4",
+                "sha256:76ada88d62eb24de7051c5157a1a78fd853cca9b91c0713c2e973e4196271d0c",
+                "sha256:837398c2ec00228679513802e3744d1e8e3cb1204aa6ad408b6aff081e99a487",
+                "sha256:8662aabfeab00cea149a3d1c2999b0731e70c6b5bac596d95d13f643e76d3d4e",
+                "sha256:95e9094162fa712f18b4f60896e34b621df99147c2cee216cfa8f022294e8e9f",
+                "sha256:99cc66b33c418cd579c0f03b77b94263c305c389cb0c6972dac420f24b3bf123",
+                "sha256:9b219511d8b64d3fa14261963933be34028ea0e57455baf6781fe399c2c3206c",
+                "sha256:ae8f34d50af2c2154035984b8b5fc5d9ed63f32fe615646ab435b05b132ca91b",
+                "sha256:b9aa9d8818c2e917fa2c105ad538e222a5bce59777133840b93134022a7ce650",
+                "sha256:bf44a9a0141a082e89c90e8d785b212a872db793a0080c20f6ae6e2a0ebf82ad",
+                "sha256:c0b48b98d79cf795b0916c57bebbc6d16bb43b9fc9b8c9f57f4cf05881904c75",
+                "sha256:da9d3c506f43e220336433dffe643fbfa40096d408cb9b7f2477892f369d5f82",
+                "sha256:e4082d832e36e7f9b2278bc774886ca8207346b99f278e54c9de4834f17232f7",
+                "sha256:e4b9b7af398c32e408c00eb4e0d33ced2f9121fd9fb978e6c1b57edd014a7d15",
+                "sha256:e613514a82539fc48291d01933951a13ae93b6b444a88782480be32245ed4afa",
+                "sha256:f5033952def24172e60493b68717792e3aebb387a8d186c43c020d9363ee7281"
+            ],
+            "version": "==1.14.2"
+        },
         "cfgv": {
             "hashes": [
                 "sha256:32e43d604bbe7896fe7c248a9c2276447dbef840feb28fe20494f62af110211d",
@@ -381,43 +415,71 @@
         },
         "coverage": {
             "hashes": [
-                "sha256:098a703d913be6fbd146a8c50cc76513d726b022d170e5e98dc56d958fd592fb",
-                "sha256:16042dc7f8e632e0dcd5206a5095ebd18cb1d005f4c89694f7f8aafd96dd43a3",
-                "sha256:1adb6be0dcef0cf9434619d3b892772fdb48e793300f9d762e480e043bd8e716",
-                "sha256:27ca5a2bc04d68f0776f2cdcb8bbd508bbe430a7bf9c02315cd05fb1d86d0034",
-                "sha256:28f42dc5172ebdc32622a2c3f7ead1b836cdbf253569ae5673f499e35db0bac3",
-                "sha256:2fcc8b58953d74d199a1a4d633df8146f0ac36c4e720b4a1997e9b6327af43a8",
-                "sha256:304fbe451698373dc6653772c72c5d5e883a4aadaf20343592a7abb2e643dae0",
-                "sha256:30bc103587e0d3df9e52cd9da1dd915265a22fad0b72afe54daf840c984b564f",
-                "sha256:40f70f81be4d34f8d491e55936904db5c527b0711b2a46513641a5729783c2e4",
-                "sha256:4186fc95c9febeab5681bc3248553d5ec8c2999b8424d4fc3a39c9cba5796962",
-                "sha256:46794c815e56f1431c66d81943fa90721bb858375fb36e5903697d5eef88627d",
-                "sha256:4869ab1c1ed33953bb2433ce7b894a28d724b7aa76c19b11e2878034a4e4680b",
-                "sha256:4f6428b55d2916a69f8d6453e48a505c07b2245653b0aa9f0dee38785939f5e4",
-                "sha256:52f185ffd3291196dc1aae506b42e178a592b0b60a8610b108e6ad892cfc1bb3",
-                "sha256:538f2fd5eb64366f37c97fdb3077d665fa946d2b6d95447622292f38407f9258",
-                "sha256:64c4f340338c68c463f1b56e3f2f0423f7b17ba6c3febae80b81f0e093077f59",
-                "sha256:675192fca634f0df69af3493a48224f211f8db4e84452b08d5fcebb9167adb01",
-                "sha256:700997b77cfab016533b3e7dbc03b71d33ee4df1d79f2463a318ca0263fc29dd",
-                "sha256:8505e614c983834239f865da2dd336dcf9d72776b951d5dfa5ac36b987726e1b",
-                "sha256:962c44070c281d86398aeb8f64e1bf37816a4dfc6f4c0f114756b14fc575621d",
-                "sha256:9e536783a5acee79a9b308be97d3952b662748c4037b6a24cbb339dc7ed8eb89",
-                "sha256:9ea749fd447ce7fb1ac71f7616371f04054d969d412d37611716721931e36efd",
-                "sha256:a34cb28e0747ea15e82d13e14de606747e9e484fb28d63c999483f5d5188e89b",
-                "sha256:a3ee9c793ffefe2944d3a2bd928a0e436cd0ac2d9e3723152d6fd5398838ce7d",
-                "sha256:aab75d99f3f2874733946a7648ce87a50019eb90baef931698f96b76b6769a46",
-                "sha256:b1ed2bdb27b4c9fc87058a1cb751c4df8752002143ed393899edb82b131e0546",
-                "sha256:b360d8fd88d2bad01cb953d81fd2edd4be539df7bfec41e8753fe9f4456a5082",
-                "sha256:b8f58c7db64d8f27078cbf2a4391af6aa4e4767cc08b37555c4ae064b8558d9b",
-                "sha256:c1bbb628ed5192124889b51204de27c575b3ffc05a5a91307e7640eff1d48da4",
-                "sha256:c2ff24df02a125b7b346c4c9078c8936da06964cc2d276292c357d64378158f8",
-                "sha256:c890728a93fffd0407d7d37c1e6083ff3f9f211c83b4316fae3778417eab9811",
-                "sha256:c96472b8ca5dc135fb0aa62f79b033f02aa434fb03a8b190600a5ae4102df1fd",
-                "sha256:ce7866f29d3025b5b34c2e944e66ebef0d92e4a4f2463f7266daa03a1332a651",
-                "sha256:e26c993bd4b220429d4ec8c1468eca445a4064a61c74ca08da7429af9bc53bb0"
-            ],
-            "index": "pypi",
-            "version": "==5.2.1"
+                "sha256:0203acd33d2298e19b57451ebb0bed0ab0c602e5cf5a818591b4918b1f97d516",
+                "sha256:0f313707cdecd5cd3e217fc68c78a960b616604b559e9ea60cc16795c4304259",
+                "sha256:1c6703094c81fa55b816f5ae542c6ffc625fec769f22b053adb42ad712d086c9",
+                "sha256:1d44bb3a652fed01f1f2c10d5477956116e9b391320c94d36c6bf13b088a1097",
+                "sha256:280baa8ec489c4f542f8940f9c4c2181f0306a8ee1a54eceba071a449fb870a0",
+                "sha256:29a6272fec10623fcbe158fdf9abc7a5fa032048ac1d8631f14b50fbfc10d17f",
+                "sha256:2b31f46bf7b31e6aa690d4c7a3d51bb262438c6dcb0d528adde446531d0d3bb7",
+                "sha256:2d43af2be93ffbad25dd959899b5b809618a496926146ce98ee0b23683f8c51c",
+                "sha256:381ead10b9b9af5f64646cd27107fb27b614ee7040bb1226f9c07ba96625cbb5",
+                "sha256:47a11bdbd8ada9b7ee628596f9d97fbd3851bd9999d398e9436bd67376dbece7",
+                "sha256:4d6a42744139a7fa5b46a264874a781e8694bb32f1d76d8137b68138686f1729",
+                "sha256:50691e744714856f03a86df3e2bff847c2acede4c191f9a1da38f088df342978",
+                "sha256:530cc8aaf11cc2ac7430f3614b04645662ef20c348dce4167c22d99bec3480e9",
+                "sha256:582ddfbe712025448206a5bc45855d16c2e491c2dd102ee9a2841418ac1c629f",
+                "sha256:63808c30b41f3bbf65e29f7280bf793c79f54fb807057de7e5238ffc7cc4d7b9",
+                "sha256:71b69bd716698fa62cd97137d6f2fdf49f534decb23a2c6fc80813e8b7be6822",
+                "sha256:7858847f2d84bf6e64c7f66498e851c54de8ea06a6f96a32a1d192d846734418",
+                "sha256:78e93cc3571fd928a39c0b26767c986188a4118edc67bc0695bc7a284da22e82",
+                "sha256:7f43286f13d91a34fadf61ae252a51a130223c52bfefb50310d5b2deb062cf0f",
+                "sha256:86e9f8cd4b0cdd57b4ae71a9c186717daa4c5a99f3238a8723f416256e0b064d",
+                "sha256:8f264ba2701b8c9f815b272ad568d555ef98dfe1576802ab3149c3629a9f2221",
+                "sha256:9342dd70a1e151684727c9c91ea003b2fb33523bf19385d4554f7897ca0141d4",
+                "sha256:9361de40701666b034c59ad9e317bae95c973b9ff92513dd0eced11c6adf2e21",
+                "sha256:9669179786254a2e7e57f0ecf224e978471491d660aaca833f845b72a2df3709",
+                "sha256:aac1ba0a253e17889550ddb1b60a2063f7474155465577caa2a3b131224cfd54",
+                "sha256:aef72eae10b5e3116bac6957de1df4d75909fc76d1499a53fb6387434b6bcd8d",
+                "sha256:bd3166bb3b111e76a4f8e2980fa1addf2920a4ca9b2b8ca36a3bc3dedc618270",
+                "sha256:c1b78fb9700fc961f53386ad2fd86d87091e06ede5d118b8a50dea285a071c24",
+                "sha256:c3888a051226e676e383de03bf49eb633cd39fc829516e5334e69b8d81aae751",
+                "sha256:c5f17ad25d2c1286436761b462e22b5020d83316f8e8fcb5deb2b3151f8f1d3a",
+                "sha256:c851b35fc078389bc16b915a0a7c1d5923e12e2c5aeec58c52f4aa8085ac8237",
+                "sha256:cb7df71de0af56000115eafd000b867d1261f786b5eebd88a0ca6360cccfaca7",
+                "sha256:cedb2f9e1f990918ea061f28a0f0077a07702e3819602d3507e2ff98c8d20636",
+                "sha256:e8caf961e1b1a945db76f1b5fa9c91498d15f545ac0ababbe575cfab185d3bd8"
+            ],
+            "index": "pypi",
+            "version": "==5.3"
+        },
+        "cryptography": {
+            "hashes": [
+                "sha256:10c9775a3f31610cf6b694d1fe598f2183441de81cedcf1814451ae53d71b13a",
+                "sha256:180c9f855a8ea280e72a5d61cf05681b230c2dce804c48e9b2983f491ecc44ed",
+                "sha256:247df238bc05c7d2e934a761243bfdc67db03f339948b1e2e80c75d41fc7cc36",
+                "sha256:26409a473cc6278e4c90f782cd5968ebad04d3911ed1c402fc86908c17633e08",
+                "sha256:2a27615c965173c4c88f2961cf18115c08fedfb8bdc121347f26e8458dc6d237",
+                "sha256:2e26223ac636ca216e855748e7d435a1bf846809ed12ed898179587d0cf74618",
+                "sha256:321761d55fb7cb256b771ee4ed78e69486a7336be9143b90c52be59d7657f50f",
+                "sha256:4005b38cd86fc51c955db40b0f0e52ff65340874495af72efabb1bb8ca881695",
+                "sha256:4b9e96543d0784acebb70991ebc2dbd99aa287f6217546bb993df22dd361d41c",
+                "sha256:548b0818e88792318dc137d8b1ec82a0ab0af96c7f0603a00bb94f896fbf5e10",
+                "sha256:725875681afe50b41aee7fdd629cedbc4720bab350142b12c55c0a4d17c7416c",
+                "sha256:7a63e97355f3cd77c94bd98c59cb85fe0efd76ea7ef904c9b0316b5bbfde6ed1",
+                "sha256:94191501e4b4009642be21dde2a78bd3c2701a81ee57d3d3d02f1d99f8b64a9e",
+                "sha256:969ae512a250f869c1738ca63be843488ff5cc031987d302c1f59c7dbe1b225f",
+                "sha256:9f734423eb9c2ea85000aa2476e0d7a58e021bc34f0a373ac52a5454cd52f791",
+                "sha256:b45ab1c6ece7c471f01c56f5d19818ca797c34541f0b2351635a5c9fe09ac2e0",
+                "sha256:cc6096c86ec0de26e2263c228fb25ee01c3ff1346d3cfc219d67d49f303585af",
+                "sha256:dc3f437ca6353979aace181f1b790f0fc79e446235b14306241633ab7d61b8f8",
+                "sha256:e7563eb7bc5c7e75a213281715155248cceba88b11cb4b22957ad45b85903761",
+                "sha256:e7dad66a9e5684a40f270bd4aee1906878193ae50a4831922e454a2a457f1716",
+                "sha256:eb80a288e3cfc08f679f95da72d2ef90cb74f6d8a8ba69d2f215c5e110b2ca32",
+                "sha256:fa7fbcc40e2210aca26c7ac8a39467eae444d90a2c346cbcffd9133a166bcc67"
+            ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
+            "version": "==3.1"
         },
         "distlib": {
             "hashes": [
@@ -468,11 +530,11 @@
         },
         "identify": {
             "hashes": [
-                "sha256:9f5fcf22b665eaece583bd395b103c2769772a0f646ffabb5b1f155901b07de2",
-                "sha256:b1aa2e05863dc80242610d46a7b49105e2eafe00ef0c8ff311c1828680760c76"
+                "sha256:c770074ae1f19e08aadbda1c886bc6d0cb55ffdc503a8c0fe8699af2fc9664ae",
+                "sha256:d02d004568c5a01261839a05e91705e3e9f5c57a3551648f9b3fb2b9c62c0f62"
             ],
             "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==1.4.29"
+            "version": "==1.5.3"
         },
         "idna": {
             "hashes": [
@@ -490,6 +552,14 @@
             "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==1.2.0"
         },
+        "jeepney": {
+            "hashes": [
+                "sha256:3479b861cc2b6407de5188695fa1a8d57e5072d7059322469b62628869b8e36e",
+                "sha256:d6c6b49683446d2407d2fe3acb7a368a77ff063f9182fe427da15d622adc24cf"
+            ],
+            "markers": "sys_platform == 'linux'",
+            "version": "==0.4.3"
+        },
         "jinja2": {
             "hashes": [
                 "sha256:89aab215427ef59c34ad58735269eb58b1a5808103067f7bb9d5836c651b3bb0",
@@ -500,11 +570,11 @@
         },
         "keyring": {
             "hashes": [
-                "sha256:182f94fc0381546489e3e4d90384a8c1d43cc09ffe2eb4a826e7312df6e1be7c",
-                "sha256:cd4d486803d55bdb13e2d453eb61dbbc984773e4f2b98a455aa85b1f4bc421e4"
+                "sha256:4e34ea2fdec90c1c43d6610b5a5fafa1b9097db1802948e90caf5763974b8f8d",
+                "sha256:9aeadd006a852b78f4b4ef7c7556c2774d2432bbef8ee538a3e9089ac8b11466"
             ],
             "markers": "python_version >= '3.6'",
-            "version": "==21.3.1"
+            "version": "==21.4.0"
         },
         "markupsafe": {
             "hashes": [
@@ -649,6 +719,14 @@
             "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==2.6.0"
         },
+        "pycparser": {
+            "hashes": [
+                "sha256:2d475327684562c3a96cc71adf7dc8c4f0565175cf86b6d7a404ff4c771f15f0",
+                "sha256:7582ad22678f0fcd81102833f60ef8d0e57288b6b5fb00323d101be910e35705"
+            ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
+            "version": "==2.20"
+        },
         "pyflakes": {
             "hashes": [
                 "sha256:0d94e0e05a19e57a99444b6ddcf9a6eb2e5c68d3ca1e98e90707af8152c90a92",
@@ -659,11 +737,11 @@
         },
         "pygments": {
             "hashes": [
-                "sha256:647344a061c249a3b74e230c739f434d7ea4d8b1d5f3721bc0f3558049b38f44",
-                "sha256:ff7a40b4860b727ab48fad6360eb351cc1b33cbf9b15a0f689ca5353e9463324"
+                "sha256:307543fe65c0947b126e83dd5a61bd8acbd84abec11f43caebaf5534cbc17998",
+                "sha256:926c3f319eda178d1bd90851e4317e6d8cdb5e292a3386aac9bd75eca29cf9c7"
             ],
             "markers": "python_version >= '3.5'",
-            "version": "==2.6.1"
+            "version": "==2.7.1"
         },
         "pyparsing": {
             "hashes": [
@@ -761,6 +839,14 @@
             ],
             "version": "==1.4.0"
         },
+        "secretstorage": {
+            "hashes": [
+                "sha256:15da8a989b65498e29be338b3b279965f1b8f09b9668bd8010da183024c8bff6",
+                "sha256:b5ec909dde94d4ae2fa26af7c089036997030f0cf0a5cb372b4cccabd81c143b"
+            ],
+            "markers": "sys_platform == 'linux'",
+            "version": "==3.1.2"
+        },
         "setuptools-scm": {
             "hashes": [
                 "sha256:09c659d1d6680811c43f476a33c6d3d9872416580786e96bd29ea03e6a818e41",
@@ -848,21 +934,21 @@
         },
         "toml": {
             "hashes": [
-                "sha256:229f81c57791a41d65e399fc06bf0848bab550a9dfd5ed66df18ce5f05e73d5c",
                 "sha256:235682dd292d5899d361a811df37e04a8828a5b1da3115886b73cf81ebc9100e",
+                "sha256:bda89d5935c2eac546d648028b9901107a595863cb36bae0c73ac804a9b4ce88",
                 "sha256:926b612be1e5ce0634a2ca03470f95169cf16f939018233a670519cb4ac58b0f",
-                "sha256:bda89d5935c2eac546d648028b9901107a595863cb36bae0c73ac804a9b4ce88"
+                "sha256:229f81c57791a41d65e399fc06bf0848bab550a9dfd5ed66df18ce5f05e73d5c"
             ],
             "index": "pypi",
             "version": "==0.10.1"
         },
         "tqdm": {
             "hashes": [
-                "sha256:1a336d2b829be50e46b84668691e0a2719f26c97c62846298dd5ae2937e4d5cf",
-                "sha256:564d632ea2b9cb52979f7956e093e831c28d441c11751682f84c86fc46e4fd21"
+                "sha256:8f3c5815e3b5e20bc40463fa6b42a352178859692a68ffaa469706e6d38342a5",
+                "sha256:faf9c671bd3fad5ebaeee366949d969dca2b2be32c872a7092a1e1a9048d105b"
             ],
             "markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==4.48.2"
+            "version": "==4.49.0"
         },
         "twine": {
             "hashes": [
@@ -874,29 +960,30 @@
         },
         "typed-ast": {
             "hashes": [
-                "sha256:1170afa46a3799e18b4c977777ce137bb53c7485379d9706af8a59f2ea1aa161",
-                "sha256:18511a0b3e7922276346bcb47e2ef9f38fb90fd31cb9223eed42c85d1312344e",
-                "sha256:262c247a82d005e43b5b7f69aff746370538e176131c32dda9cb0f324d27141e",
-                "sha256:2b907eb046d049bcd9892e3076c7a6456c93a25bebfe554e931620c90e6a25b0",
-                "sha256:354c16e5babd09f5cb0ee000d54cfa38401d8b8891eefa878ac772f827181a3c",
-                "sha256:48e5b1e71f25cfdef98b013263a88d7145879fbb2d5185f2a0c79fa7ebbeae47",
-                "sha256:4e0b70c6fc4d010f8107726af5fd37921b666f5b31d9331f0bd24ad9a088e631",
-                "sha256:630968c5cdee51a11c05a30453f8cd65e0cc1d2ad0d9192819df9978984529f4",
-                "sha256:66480f95b8167c9c5c5c87f32cf437d585937970f3fc24386f313a4c97b44e34",
-                "sha256:71211d26ffd12d63a83e079ff258ac9d56a1376a25bc80b1cdcdf601b855b90b",
-                "sha256:7954560051331d003b4e2b3eb822d9dd2e376fa4f6d98fee32f452f52dd6ebb2",
-                "sha256:838997f4310012cf2e1ad3803bce2f3402e9ffb71ded61b5ee22617b3a7f6b6e",
-                "sha256:95bd11af7eafc16e829af2d3df510cecfd4387f6453355188342c3e79a2ec87a",
-                "sha256:bc6c7d3fa1325a0c6613512a093bc2a2a15aeec350451cbdf9e1d4bffe3e3233",
-                "sha256:cc34a6f5b426748a507dd5d1de4c1978f2eb5626d51326e43280941206c209e1",
-                "sha256:d755f03c1e4a51e9b24d899561fec4ccaf51f210d52abdf8c07ee2849b212a36",
-                "sha256:d7c45933b1bdfaf9f36c579671fec15d25b06c8398f113dab64c18ed1adda01d",
-                "sha256:d896919306dd0aa22d0132f62a1b78d11aaf4c9fc5b3410d3c666b818191630a",
-                "sha256:fdc1c9bbf79510b76408840e009ed65958feba92a88833cdceecff93ae8fff66",
-                "sha256:ffde2fbfad571af120fcbfbbc61c72469e72f550d676c3342492a9dfdefb8f12"
+                "sha256:0666aa36131496aed8f7be0410ff974562ab7eeac11ef351def9ea6fa28f6355",
+                "sha256:0c2c07682d61a629b68433afb159376e24e5b2fd4641d35424e462169c0a7919",
+                "sha256:249862707802d40f7f29f6e1aad8d84b5aa9e44552d2cc17384b209f091276aa",
+                "sha256:24995c843eb0ad11a4527b026b4dde3da70e1f2d8806c99b7b4a7cf491612652",
+                "sha256:269151951236b0f9a6f04015a9004084a5ab0d5f19b57de779f908621e7d8b75",
+                "sha256:4083861b0aa07990b619bd7ddc365eb7fa4b817e99cf5f8d9cf21a42780f6e01",
+                "sha256:498b0f36cc7054c1fead3d7fc59d2150f4d5c6c56ba7fb150c013fbc683a8d2d",
+                "sha256:4e3e5da80ccbebfff202a67bf900d081906c358ccc3d5e3c8aea42fdfdfd51c1",
+                "sha256:6daac9731f172c2a22ade6ed0c00197ee7cc1221aa84cfdf9c31defeb059a907",
+                "sha256:715ff2f2df46121071622063fc7543d9b1fd19ebfc4f5c8895af64a77a8c852c",
+                "sha256:73d785a950fc82dd2a25897d525d003f6378d1cb23ab305578394694202a58c3",
+                "sha256:8c8aaad94455178e3187ab22c8b01a3837f8ee50e09cf31f1ba129eb293ec30b",
+                "sha256:8ce678dbaf790dbdb3eba24056d5364fb45944f33553dd5869b7580cdbb83614",
+                "sha256:aaee9905aee35ba5905cfb3c62f3e83b3bec7b39413f0a7f19be4e547ea01ebb",
+                "sha256:bcd3b13b56ea479b3650b82cabd6b5343a625b0ced5429e4ccad28a8973f301b",
+                "sha256:c9e348e02e4d2b4a8b2eedb48210430658df6951fa484e59de33ff773fbd4b41",
+                "sha256:d205b1b46085271b4e15f670058ce182bd1199e56b317bf2ec004b6a44f911f6",
+                "sha256:d43943ef777f9a1c42bf4e552ba23ac77a6351de620aa9acf64ad54933ad4d34",
+                "sha256:d5d33e9e7af3b34a40dc05f498939f0ebf187f07c385fd58d591c533ad8562fe",
+                "sha256:fc0fea399acb12edbf8a628ba8d2312f583bdbdb3335635db062fa98cf71fca4",
+                "sha256:fe460b922ec15dd205595c9b5b99e2f056fd98ae8f9f56b888e7a17dc2b757e7"
             ],
             "index": "pypi",
-            "version": "==1.4.0"
+            "version": "==1.4.1"
         },
         "typing-extensions": {
             "hashes": [
diff --git a/src/black/__init__.py b/src/black/__init__.py
index ffaafe23f9e..c1db8e6ef64 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -178,14 +178,12 @@ class TargetVersion(Enum):
     PY36 = 6
     PY37 = 7
     PY38 = 8
+    PY39 = 9
 
     def is_python2(self) -> bool:
         return self is TargetVersion.PY27
 
 
-PY36_VERSIONS = {TargetVersion.PY36, TargetVersion.PY37, TargetVersion.PY38}
-
-
 class Feature(Enum):
     # All string literals are unicode
     UNICODE_LITERALS = 1
@@ -199,6 +197,7 @@ class Feature(Enum):
     ASYNC_KEYWORDS = 7
     ASSIGNMENT_EXPRESSIONS = 8
     POS_ONLY_ARGUMENTS = 9
+    RELAXED_DECORATORS = 10
     FORCE_OPTIONAL_PARENTHESES = 50
 
 
@@ -237,6 +236,17 @@ class Feature(Enum):
         Feature.ASSIGNMENT_EXPRESSIONS,
         Feature.POS_ONLY_ARGUMENTS,
     },
+    TargetVersion.PY39: {
+        Feature.UNICODE_LITERALS,
+        Feature.F_STRINGS,
+        Feature.NUMERIC_UNDERSCORES,
+        Feature.TRAILING_COMMA_IN_CALL,
+        Feature.TRAILING_COMMA_IN_DEF,
+        Feature.ASYNC_KEYWORDS,
+        Feature.ASSIGNMENT_EXPRESSIONS,
+        Feature.RELAXED_DECORATORS,
+        Feature.POS_ONLY_ARGUMENTS,
+    },
 }
 
 
@@ -2184,6 +2194,9 @@ def whitespace(leaf: Leaf, *, complex_subscript: bool) -> str:  # noqa: C901
         ):
             # Python 2 print chevron
             return NO
+        elif prevp.type == token.AT and p.parent and p.parent.type == syms.decorator:
+            # no space in decorators
+            return NO
 
     elif prev.type in OPENING_BRACKETS:
         return NO
@@ -5499,6 +5512,49 @@ def is_walrus_assignment(node: LN) -> bool:
     return inner is not None and inner.type == syms.namedexpr_test
 
 
+def is_simple_decorator_trailer(node: LN, last: bool = False) -> bool:
+    """Return True iff `node` is a trailer valid in a simple decorator"""
+    return node.type == syms.trailer and (
+        (
+            len(node.children) == 2
+            and node.children[0].type == token.DOT
+            and node.children[1].type == token.NAME
+        )
+        # last trailer can be arguments
+        or (
+            last
+            and len(node.children) == 3
+            and node.children[0].type == token.LPAR
+            # and node.children[1].type == syms.argument
+            and node.children[2].type == token.RPAR
+        )
+    )
+
+
+def is_simple_decorator_expression(node: LN) -> bool:
+    """Return True iff `node` could be a 'dotted name' decorator
+
+    This function takes the node of the 'namedexpr_test' of the new decorator
+    grammar and test if it would be valid under the old decorator grammar.
+
+    The old grammar was: decorator: @ dotted_name [arguments] NEWLINE
+    The new grammar is : decorator: @ namedexpr_test NEWLINE
+    """
+    if node.type == token.NAME:
+        return True
+    if node.type == syms.power:
+        if node.children:
+            return (
+                node.children[0].type == token.NAME
+                and all(map(is_simple_decorator_trailer, node.children[1:-1]))
+                and (
+                    len(node.children) < 2
+                    or is_simple_decorator_trailer(node.children[-1], last=True)
+                )
+            )
+    return False
+
+
 def is_yield(node: LN) -> bool:
     """Return True if `node` holds a `yield` or `yield from` expression."""
     if node.type == syms.yield_expr:
@@ -5684,6 +5740,8 @@ def get_features_used(node: Node) -> Set[Feature]:
     - underscores in numeric literals;
     - trailing commas after * or ** in function signatures and calls;
     - positional only arguments in function signatures and lambdas;
+    - assignment expression;
+    - relaxed decorator syntax;
     """
     features: Set[Feature] = set()
     for n in node.pre_order():
@@ -5703,6 +5761,12 @@ def get_features_used(node: Node) -> Set[Feature]:
         elif n.type == token.COLONEQUAL:
             features.add(Feature.ASSIGNMENT_EXPRESSIONS)
 
+        elif n.type == syms.decorator:
+            if len(n.children) > 1 and not is_simple_decorator_expression(
+                n.children[1]
+            ):
+                features.add(Feature.RELAXED_DECORATORS)
+
         elif (
             n.type in {syms.typedargslist, syms.arglist}
             and n.children
diff --git a/src/blib2to3/Grammar.txt b/src/blib2to3/Grammar.txt
index f14e2b516bd..eafaee84cb3 100644
--- a/src/blib2to3/Grammar.txt
+++ b/src/blib2to3/Grammar.txt
@@ -12,7 +12,7 @@ file_input: (NEWLINE | stmt)* ENDMARKER
 single_input: NEWLINE | simple_stmt | compound_stmt NEWLINE
 eval_input: testlist NEWLINE* ENDMARKER
 
-decorator: '@' dotted_name [ '(' [arglist] ')' ] NEWLINE
+decorator: '@' namedexpr_test NEWLINE
 decorators: decorator+
 decorated: decorators (classdef | funcdef | async_funcdef)
 async_funcdef: ASYNC funcdef
diff --git a/tests/data/decorators.py b/tests/data/decorators.py
new file mode 100644
index 00000000000..acfad51fcb8
--- /dev/null
+++ b/tests/data/decorators.py
@@ -0,0 +1,176 @@
+# This file doesn't use the standard decomposition.
+# Decorator syntax test cases are separated by double # comments.
+# Those before the 'output' comment are valid under the old syntax.
+# Those after the 'ouput' comment require PEP614 relaxed syntax.
+# Do not remove the double # separator before the first test case, it allows
+# the comment before the test case to be ignored.
+
+##
+
+@decorator
+def f():
+    ...
+
+##
+
+@decorator(arg)
+def f():
+    ...
+    
+##
+
+@decorator(kwarg=0)
+def f():
+    ...
+
+##
+
+@decorator(*args)
+def f():
+    ...
+
+##
+
+@decorator(**kwargs)
+def f():
+    ...
+
+##
+
+@decorator(*args, **kwargs)
+def f():
+    ...
+
+##
+
+@decorator(*args, **kwargs,)
+def f():
+    ...
+
+##
+
+@dotted.decorator
+def f():
+    ...
+
+##
+
+@dotted.decorator(arg)
+def f():
+    ...
+    
+##
+
+@dotted.decorator(kwarg=0)
+def f():
+    ...
+
+##
+
+@dotted.decorator(*args)
+def f():
+    ...
+
+##
+
+@dotted.decorator(**kwargs)
+def f():
+    ...
+
+##
+
+@dotted.decorator(*args, **kwargs)
+def f():
+    ...
+
+##
+
+@dotted.decorator(*args, **kwargs,)
+def f():
+    ...
+
+##
+
+@double.dotted.decorator
+def f():
+    ...
+
+##
+
+@double.dotted.decorator(arg)
+def f():
+    ...
+    
+##
+
+@double.dotted.decorator(kwarg=0)
+def f():
+    ...
+
+##
+
+@double.dotted.decorator(*args)
+def f():
+    ...
+
+##
+
+@double.dotted.decorator(**kwargs)
+def f():
+    ...
+
+##
+
+@double.dotted.decorator(*args, **kwargs)
+def f():
+    ...
+
+##
+
+@double.dotted.decorator(*args, **kwargs,)
+def f():
+    ...
+
+##
+
+@_(sequence["decorator"])
+def f():
+    ...
+
+##
+
+@eval("sequence['decorator']")
+def f():
+    ...
+
+# output
+
+##
+
+@decorator()()
+def f():
+    ...
+
+##
+
+@(decorator)
+def f():
+    ...
+
+##
+
+@sequence["decorator"]
+def f():
+    ...
+
+##
+
+@decorator[List[str]]
+def f():
+    ...
+
+##
+
+@var := decorator
+def f():
+    ...
\ No newline at end of file
diff --git a/tests/data/python39.py b/tests/data/python39.py
new file mode 100644
index 00000000000..ae67c2257eb
--- /dev/null
+++ b/tests/data/python39.py
@@ -0,0 +1,37 @@
+#!/usr/bin/env python3.9
+
+@relaxed_decorator[0]
+def f():
+    ...
+
+@relaxed_decorator[extremely_long_name_that_definitely_will_not_fit_on_one_line_of_standard_length]
+def f():
+    ...
+
+@extremely_long_variable_name_that_doesnt_fit := complex.expression(with_long="arguments_value_that_wont_fit_at_the_end_of_the_line")
+def f():
+    ...
+
+# output
+
+
+#!/usr/bin/env python3.9
+
+
+@relaxed_decorator[0]
+def f():
+    ...
+
+
+@relaxed_decorator[
+    extremely_long_name_that_definitely_will_not_fit_on_one_line_of_standard_length
+]
+def f():
+    ...
+
+
+@extremely_long_variable_name_that_doesnt_fit := complex.expression(
+    with_long="arguments_value_that_wont_fit_at_the_end_of_the_line"
+)
+def f():
+    ...
\ No newline at end of file
diff --git a/tests/test_black.py b/tests/test_black.py
index e928dc04984..e17f43b88d4 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -59,9 +59,13 @@
 PROJECT_ROOT = THIS_DIR.parent
 DETERMINISTIC_HEADER = "[Deterministic header]"
 EMPTY_LINE = "# EMPTY LINE WITH WHITESPACE" + " (this comment will be removed)"
-PY36_ARGS = [
-    f"--target-version={version.name.lower()}" for version in black.PY36_VERSIONS
-]
+PY36_VERSIONS = {
+    TargetVersion.PY36,
+    TargetVersion.PY37,
+    TargetVersion.PY38,
+    TargetVersion.PY39,
+}
+PY36_ARGS = [f"--target-version={version.name.lower()}" for version in PY36_VERSIONS]
 T = TypeVar("T")
 R = TypeVar("R")
 
@@ -705,7 +709,7 @@ def test_string_prefixes(self) -> None:
     @patch("black.dump_to_file", dump_to_stderr)
     def test_numeric_literals(self) -> None:
         source, expected = read_data("numeric_literals")
-        mode = replace(DEFAULT_MODE, target_versions=black.PY36_VERSIONS)
+        mode = replace(DEFAULT_MODE, target_versions=PY36_VERSIONS)
         actual = fs(source, mode=mode)
         self.assertFormatEqual(expected, actual)
         black.assert_equivalent(source, actual)
@@ -714,7 +718,7 @@ def test_numeric_literals(self) -> None:
     @patch("black.dump_to_file", dump_to_stderr)
     def test_numeric_literals_ignoring_underscores(self) -> None:
         source, expected = read_data("numeric_literals_skip_underscores")
-        mode = replace(DEFAULT_MODE, target_versions=black.PY36_VERSIONS)
+        mode = replace(DEFAULT_MODE, target_versions=PY36_VERSIONS)
         actual = fs(source, mode=mode)
         self.assertFormatEqual(expected, actual)
         black.assert_equivalent(source, actual)
@@ -800,6 +804,16 @@ def test_python38(self) -> None:
             black.assert_equivalent(source, actual)
         black.assert_stable(source, actual, DEFAULT_MODE)
 
+    @patch("black.dump_to_file", dump_to_stderr)
+    def test_python39(self) -> None:
+        source, expected = read_data("python39")
+        actual = fs(source)
+        self.assertFormatEqual(expected, actual)
+        major, minor = sys.version_info[:2]
+        if major > 3 or (major == 3 and minor >= 9):
+            black.assert_equivalent(source, actual)
+        black.assert_stable(source, actual, DEFAULT_MODE)
+
     @patch("black.dump_to_file", dump_to_stderr)
     def test_fmtonoff(self) -> None:
         source, expected = read_data("fmtonoff")
@@ -1212,6 +1226,39 @@ def test_lib2to3_parse(self) -> None:
         black.lib2to3_parse(py3_only, {TargetVersion.PY36})
         black.lib2to3_parse(py3_only, {TargetVersion.PY27, TargetVersion.PY36})
 
+    def test_get_features_used_decorator(self) -> None:
+        # Test the feature detection of new decorator syntax
+        # since this makes some test cases of test_get_features_used()
+        # fails if it fails, this is tested first so that a useful case
+        # is identified
+        simples, relaxed = read_data("decorators")
+        # skip explanation comments at the top of the file
+        for simple_test in simples.split("##")[1:]:
+            node = black.lib2to3_parse(simple_test)
+            decorator = str(node.children[0].children[0]).strip()
+            self.assertNotIn(
+                Feature.RELAXED_DECORATORS,
+                black.get_features_used(node),
+                msg=(
+                    f"decorator '{decorator}' follows python<=3.8 syntax"
+                    "but is detected as 3.9+"
+                    # f"The full node is\n{node!r}"
+                ),
+            )
+        # skip the '# output' comment at the top of the output part
+        for relaxed_test in relaxed.split("##")[1:]:
+            node = black.lib2to3_parse(relaxed_test)
+            decorator = str(node.children[0].children[0]).strip()
+            self.assertIn(
+                Feature.RELAXED_DECORATORS,
+                black.get_features_used(node),
+                msg=(
+                    f"decorator '{decorator}' uses python3.9+ syntax"
+                    "but is detected as python<=3.8"
+                    # f"The full node is\n{node!r}"
+                ),
+            )
+
     def test_get_features_used(self) -> None:
         node = black.lib2to3_parse("def f(*, arg): ...\n")
         self.assertEqual(black.get_features_used(node), set())
@@ -1628,7 +1675,7 @@ def test_pipe_force_pyi(self) -> None:
 
     def test_single_file_force_py36(self) -> None:
         reg_mode = DEFAULT_MODE
-        py36_mode = replace(DEFAULT_MODE, target_versions=black.PY36_VERSIONS)
+        py36_mode = replace(DEFAULT_MODE, target_versions=PY36_VERSIONS)
         source, expected = read_data("force_py36")
         with cache_dir() as workspace:
             path = (workspace / "file.py").resolve()
@@ -1647,7 +1694,7 @@ def test_single_file_force_py36(self) -> None:
     @event_loop()
     def test_multi_file_force_py36(self) -> None:
         reg_mode = DEFAULT_MODE
-        py36_mode = replace(DEFAULT_MODE, target_versions=black.PY36_VERSIONS)
+        py36_mode = replace(DEFAULT_MODE, target_versions=PY36_VERSIONS)
         source, expected = read_data("force_py36")
         with cache_dir() as workspace:
             paths = [

From bc138d12630ec38cb1b11b2fb2ca8762ac2ae7a4 Mon Sep 17 00:00:00 2001
From: Vipul <finn02@disroot.org>
Date: Sun, 27 Sep 2020 05:54:21 +0000
Subject: [PATCH 0025/1034] End 'force-exclude' help message with a period
 (#1727)

It would be nice, if like other options help message, force-exclude's
help message also ends with a period punctuation mark.
---
 README.md                      | 2 +-
 docs/installation_and_usage.md | 2 +-
 src/black/__init__.py          | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 942e85444d3..aef850f1415 100644
--- a/README.md
+++ b/README.md
@@ -133,7 +133,7 @@ Options:
 
   --force-exclude TEXT            Like --exclude, but files and directories
                                   matching this regex will be excluded even
-                                  when they are passed explicitly as arguments
+                                  when they are passed explicitly as arguments.
 
   -q, --quiet                     Don't emit non-error messages to stderr.
                                   Errors are still emitted; silence those with
diff --git a/docs/installation_and_usage.md b/docs/installation_and_usage.md
index cc0269198a2..7d37f59264b 100644
--- a/docs/installation_and_usage.md
+++ b/docs/installation_and_usage.md
@@ -88,7 +88,7 @@ Options:
 
   --force-exclude TEXT            Like --exclude, but files and directories
                                   matching this regex will be excluded even
-                                  when they are passed explicitly as arguments
+                                  when they are passed explicitly as arguments.
 
   -q, --quiet                     Don't emit non-error messages to stderr.
                                   Errors are still emitted; silence those with
diff --git a/src/black/__init__.py b/src/black/__init__.py
index c1db8e6ef64..dce7a24445a 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -454,7 +454,7 @@ def target_version_option_callback(
     type=str,
     help=(
         "Like --exclude, but files and directories matching this regex will be "
-        "excluded even when they are passed explicitly as arguments"
+        "excluded even when they are passed explicitly as arguments."
     ),
 )
 @click.option(

From 4d71d74a442ccc6c309a0667147997c1eeb755fd Mon Sep 17 00:00:00 2001
From: Pete Grayson <github@jpgrayson.net>
Date: Sun, 27 Sep 2020 21:41:11 +0000
Subject: [PATCH 0026/1034] Repair colorama wrapping on non-Windows platforms
 (#1670)

* Repair colorama wrapping on non-Windows platforms

The wrap_stream_for_windows() function calls
colorama.initialise.wrap_stream() function to apply colorama's magic to
wrapper to the output stream. Except this wrapper is only applied on
Windows platforms that need it, otherwise the original stream is
returned as-is.

The colorama wrapped stream lacks a detach() method, so a no-op lambda
was being assigned to the wrapped stream.

The problem is that the no-op lambda was being assigned unconditionally
whether or not colorama actually returns a wrapped stream, thus
replacing the original TextIOWrapper's detach() method. Replacing the
detach() method with a no-op lambda is the root cause of the problem
observed in #1664.

The solution is to only assign the no-op detach() method if the stream
lacks its own detach() method.

Repairs #1664
---
 CHANGES.md            |  2 ++
 README.md             |  1 +
 src/black/__init__.py | 30 +++++++++++-------------------
 3 files changed, 14 insertions(+), 19 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 7ad3482d07a..dfc54224b41 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -15,6 +15,8 @@
 
 - fixed a crash when PWD=/ on POSIX (#1631)
 
+- fixed "I/O operation on closed file" when using --diff (#1664)
+
 - Prevent coloured diff output being interleaved with multiple files (#1673)
 
 - Added support for PEP 614 relaxed decorator syntax on python 3.9 (#1711)
diff --git a/README.md b/README.md
index aef850f1415..f17b353b023 100644
--- a/README.md
+++ b/README.md
@@ -636,6 +636,7 @@ Multiple contributions by:
 - [Paul Ganssle](mailto:p.ganssle@gmail.com)
 - [Paul Meinhardt](mailto:mnhrdt@gmail.com)
 - [Peter Bengtsson](mailto:mail@peterbe.com)
+- [Peter Grayson](mailto:pete@jpgrayson.net)
 - [Peter Stensmyr](mailto:peter.stensmyr@gmail.com)
 - pmacosta
 - [Quentin Pradet](mailto:quentin@pradet.me)
diff --git a/src/black/__init__.py b/src/black/__init__.py
index dce7a24445a..9af58014c51 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -871,30 +871,22 @@ def color_diff(contents: str) -> str:
 
 def wrap_stream_for_windows(
     f: io.TextIOWrapper,
-) -> Union[io.TextIOWrapper, "colorama.AnsiToWin32.AnsiToWin32"]:
+) -> Union[io.TextIOWrapper, "colorama.AnsiToWin32"]:
     """
-    Wrap the stream in colorama's wrap_stream so colors are shown on Windows.
+    Wrap stream with colorama's wrap_stream so colors are shown on Windows.
 
-    If `colorama` is not found, then no change is made. If `colorama` does
-    exist, then it handles the logic to determine whether or not to change
-    things.
+    If `colorama` is unavailable, the original stream is returned unmodified.
+    Otherwise, the `wrap_stream()` function determines whether the stream needs
+    to be wrapped for a Windows environment and will accordingly either return
+    an `AnsiToWin32` wrapper or the original stream.
     """
     try:
-        from colorama import initialise
-
-        # We set `strip=False` so that we can don't have to modify
-        # test_express_diff_with_color.
-        f = initialise.wrap_stream(
-            f, convert=None, strip=False, autoreset=False, wrap=True
-        )
-
-        # wrap_stream returns a `colorama.AnsiToWin32.AnsiToWin32` object
-        # which does not have a `detach()` method. So we fake one.
-        f.detach = lambda *args, **kwargs: None  # type: ignore
+        from colorama.initialise import wrap_stream
     except ImportError:
-        pass
-
-    return f
+        return f
+    else:
+        # Set `strip=False` to avoid needing to modify test_express_diff_with_color.
+        return wrap_stream(f, convert=None, strip=False, autoreset=False, wrap=True)
 
 
 def format_stdin_to_stdout(

From 82c1f871d07e9c6334b5fb0bf089273a08ffd195 Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <hugovk@users.noreply.github.com>
Date: Mon, 28 Sep 2020 05:42:01 +0300
Subject: [PATCH 0027/1034] Hypothesis is now formatted with Black 20.8b1
 (#1729)

---
 src/black_primer/primer.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/black_primer/primer.json b/src/black_primer/primer.json
index 8a90192f27d..5818444e632 100644
--- a/src/black_primer/primer.json
+++ b/src/black_primer/primer.json
@@ -47,7 +47,7 @@
     },
     "hypothesis": {
       "cli_arguments": [],
-      "expect_formatting_changes": true,
+      "expect_formatting_changes": false,
       "git_clone_url": "https://github.com/HypothesisWorks/hypothesis.git",
       "long_checkout": false,
       "py_versions": ["all"]

From 172c0a78facd8f938629f216c95507bbfeddfe5e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Hakan=20=C3=87elik?= <hakancelik96@outlook.com>
Date: Mon, 28 Sep 2020 22:55:35 +0300
Subject: [PATCH 0028/1034] Fix unnecessary if checks (#1728)

---
 src/black/__init__.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index 9af58014c51..24e9d4edaaa 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -859,9 +859,9 @@ def color_diff(contents: str) -> str:
     for i, line in enumerate(lines):
         if line.startswith("+++") or line.startswith("---"):
             line = "\033[1;37m" + line + "\033[0m"  # bold white, reset
-        if line.startswith("@@"):
+        elif line.startswith("@@"):
             line = "\033[36m" + line + "\033[0m"  # cyan, reset
-        if line.startswith("+"):
+        elif line.startswith("+"):
             line = "\033[32m" + line + "\033[0m"  # green, reset
         elif line.startswith("-"):
             line = "\033[31m" + line + "\033[0m"  # red, reset

From 283d999c3f89e2204cbf5a61242665bedd6887ef Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <hugovk@users.noreply.github.com>
Date: Fri, 2 Oct 2020 14:47:57 +0300
Subject: [PATCH 0029/1034] Primer: pyramid and sqlalchemy are now formatted
 with latest Black (#1736)

---
 src/black_primer/primer.json | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/black_primer/primer.json b/src/black_primer/primer.json
index 5818444e632..cdc863ca032 100644
--- a/src/black_primer/primer.json
+++ b/src/black_primer/primer.json
@@ -77,7 +77,7 @@
     },
     "pyramid": {
       "cli_arguments": [],
-      "expect_formatting_changes": true,
+      "expect_formatting_changes": false,
       "git_clone_url": "https://github.com/Pylons/pyramid.git",
       "long_checkout": false,
       "py_versions": ["all"]
@@ -98,7 +98,7 @@
     },
     "sqlalchemy": {
       "cli_arguments": [],
-      "expect_formatting_changes": true,
+      "expect_formatting_changes": false,
       "git_clone_url": "https://github.com/sqlalchemy/sqlalchemy.git",
       "long_checkout": false,
       "py_versions": ["all"]

From d9884b6d330d56b2d2ea1d24f1bdf36ff433c0e6 Mon Sep 17 00:00:00 2001
From: Cha Gyuseok <cgs.zx6@gmail.com>
Date: Wed, 7 Oct 2020 23:45:06 +0900
Subject: [PATCH 0030/1034] docs: update `used-by` link to proper url (#1745)

---
 README.md | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index f17b353b023..9c10a63fe29 100644
--- a/README.md
+++ b/README.md
@@ -212,12 +212,13 @@ know!)
 
 ### NOTE: This is a beta product
 
-_Black_ is already [successfully used](#used-by) by many projects, small and big. It
-also sports a decent test suite. However, it is still very new. Things will probably be
-wonky for a while. This is made explicit by the "Beta" trove classifier, as well as by
-the "b" in the version number. What this means for you is that **until the formatter
-becomes stable, you should expect some formatting to change in the future**. That being
-said, no drastic stylistic changes are planned, mostly responses to bug reports.
+_Black_ is already [successfully used](https://github.com/psf/black#used-by) by many
+projects, small and big. It also sports a decent test suite. However, it is still very
+new. Things will probably be wonky for a while. This is made explicit by the "Beta"
+trove classifier, as well as by the "b" in the version number. What this means for you
+is that **until the formatter becomes stable, you should expect some formatting to
+change in the future**. That being said, no drastic stylistic changes are planned,
+mostly responses to bug reports.
 
 Also, as a temporary safety measure, _Black_ will check that the reformatted code still
 produces a valid AST that is equivalent to the original. This slows it down. If you're

From dd2f86ac0a043815821d228b9db036a295be5372 Mon Sep 17 00:00:00 2001
From: Hadi Alqattan <alqattanhadizaki@gmail.com>
Date: Fri, 9 Oct 2020 00:13:13 +0300
Subject: [PATCH 0031/1034] Support stable Python3.9. (#1748)

* Support stable Python3.9.

* Get back to 3.9-dev

* Add py39 to black usage.

* remove 3.9 temporarily.
---
 .github/workflows/doc.yml      | 4 ++--
 .github/workflows/fuzz.yml     | 2 +-
 .github/workflows/primer.yml   | 2 +-
 .github/workflows/test.yml     | 2 +-
 CONTRIBUTING.md                | 2 +-
 README.md                      | 2 +-
 docs/contributing_to_black.md  | 2 +-
 docs/installation_and_usage.md | 2 +-
 readthedocs.yml                | 2 +-
 setup.py                       | 1 +
 10 files changed, 11 insertions(+), 10 deletions(-)

diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml
index 6023a02a7f7..d266e55aa02 100644
--- a/.github/workflows/doc.yml
+++ b/.github/workflows/doc.yml
@@ -21,10 +21,10 @@ jobs:
     steps:
       - uses: actions/checkout@v2
 
-      - name: Set up Python 3.8
+      - name: Set up Python 3.9
         uses: actions/setup-python@v2
         with:
-          python-version: 3.8
+          python-version: 3.9
 
       - name: Install dependencies
         run: |
diff --git a/.github/workflows/fuzz.yml b/.github/workflows/fuzz.yml
index 92caa0fd5c1..9aec3c08c63 100644
--- a/.github/workflows/fuzz.yml
+++ b/.github/workflows/fuzz.yml
@@ -8,7 +8,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: [3.6, 3.7, 3.8]
+        python-version: [3.6, 3.7, 3.8] # Python3.9 should be added after fixing [https://github.com/Zac-HD/hypothesmith/issues/11].
 
     steps:
       - uses: actions/checkout@v2
diff --git a/.github/workflows/primer.yml b/.github/workflows/primer.yml
index 9b10db0d285..b623b938345 100644
--- a/.github/workflows/primer.yml
+++ b/.github/workflows/primer.yml
@@ -8,7 +8,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: [3.6, 3.7, 3.8]
+        python-version: [3.6, 3.7, 3.8, 3.9]
         os: [ubuntu-latest, windows-latest]
 
     steps:
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index bd0af61e7f5..e30a8b8eb68 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -8,7 +8,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: [3.6, 3.7, 3.8]
+        python-version: [3.6, 3.7, 3.8, 3.9]
         os: [ubuntu-latest, macOS-latest, windows-latest]
 
     steps:
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0687aaeee52..d446e6a0806 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -19,7 +19,7 @@ unlikely to get accepted. You can still try but prepare to be disappointed.
 
 ## Technicalities
 
-Development on the latest version of Python is preferred. As of this writing it's 3.8.
+Development on the latest version of Python is preferred. As of this writing it's 3.9.
 You can use any operating system. I am using macOS myself and CentOS at work.
 
 Install all development dependencies using:
diff --git a/README.md b/README.md
index 9c10a63fe29..2ca76dd6415 100644
--- a/README.md
+++ b/README.md
@@ -86,7 +86,7 @@ Options:
   -l, --line-length INTEGER       How many characters per line to allow.
                                   [default: 88]
 
-  -t, --target-version [py27|py33|py34|py35|py36|py37|py38]
+  -t, --target-version [py27|py33|py34|py35|py36|py37|py38|py39]
                                   Python versions that should be supported by
                                   Black's output. [default: per-file auto-
                                   detection]
diff --git a/docs/contributing_to_black.md b/docs/contributing_to_black.md
index e5307adb5d0..8e332993f97 100644
--- a/docs/contributing_to_black.md
+++ b/docs/contributing_to_black.md
@@ -21,7 +21,7 @@ unlikely to get accepted. You can still try but prepare to be disappointed.
 
 ## Technicalities
 
-Development on the latest version of Python is preferred. As of this writing it's 3.8.
+Development on the latest version of Python is preferred. As of this writing it's 3.9.
 You can use any operating system. I am using macOS myself and CentOS at work.
 
 Install all development dependencies using:
diff --git a/docs/installation_and_usage.md b/docs/installation_and_usage.md
index 7d37f59264b..7de8b657adf 100644
--- a/docs/installation_and_usage.md
+++ b/docs/installation_and_usage.md
@@ -41,7 +41,7 @@ Options:
   -l, --line-length INTEGER       How many characters per line to allow.
                                   [default: 88]
 
-  -t, --target-version [py27|py33|py34|py35|py36|py37|py38]
+  -t, --target-version [py27|py33|py34|py35|py36|py37|py38|py39]
                                   Python versions that should be supported by
                                   Black's output. [default: per-file auto-
                                   detection]
diff --git a/readthedocs.yml b/readthedocs.yml
index 15065033d0f..32bcf1fa50e 100644
--- a/readthedocs.yml
+++ b/readthedocs.yml
@@ -1,6 +1,6 @@
 version: 2
 python:
-  version: 3.8
+  version: 3.9
   install:
     - requirements: docs/requirements.txt
     - method: setuptools
diff --git a/setup.py b/setup.py
index 12fde2568cf..14bc1ef586a 100644
--- a/setup.py
+++ b/setup.py
@@ -93,6 +93,7 @@ def get_long_description() -> str:
         "Programming Language :: Python :: 3.6",
         "Programming Language :: Python :: 3.7",
         "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
         "Programming Language :: Python :: 3 :: Only",
         "Topic :: Software Development :: Libraries :: Python Modules",
         "Topic :: Software Development :: Quality Assurance",

From f311d82569b9595d85c08cc8fcf5250de525e7a0 Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Mon, 12 Oct 2020 22:03:00 -0700
Subject: [PATCH 0032/1034] Add blackd to nicely exit if missing aiohttp deps
 (#1761)

- If no aiohttp* deps exist nicely print a helpful message and exit
- There seems to be no nice way to optionally install the entry point, so lets make the entry point nicer

Test:
```
cooper-mbp1:black cooper$ /tmp/tb/bin/pip install .
cooper-mbp1:black cooper$ /tmp/tb/bin/blackd
aiohttp dependency is not installed: No module named 'aiohttp'. Please re-install black with the '[d]' extra install  to obtain aiohttp_cors: `pip install black[d]`
cooper-mbp1:black cooper$ /tmp/tb/bin/pip install .[d]
...
Successfully installed aiohttp-3.6.3 aiohttp-cors-0.7.0 black
cooper-mbp1:black cooper$ /tmp/tb/bin/blackd
blackd version 20.8b2.dev31+gdd2f86a.d20201013 listening on localhost port 45484
```

Fixes #1688
---
 src/blackd/__init__.py | 17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)

diff --git a/src/blackd/__init__.py b/src/blackd/__init__.py
index d79bfe75bc2..f77a5e8e7be 100644
--- a/src/blackd/__init__.py
+++ b/src/blackd/__init__.py
@@ -1,13 +1,24 @@
 import asyncio
+import logging
+import sys
 from concurrent.futures import Executor, ProcessPoolExecutor
 from datetime import datetime
 from functools import partial
-import logging
 from multiprocessing import freeze_support
 from typing import Set, Tuple
 
-from aiohttp import web
-import aiohttp_cors
+try:
+    from aiohttp import web
+    import aiohttp_cors
+except ImportError as ie:
+    print(
+        f"aiohttp dependency is not installed: {ie}. "
+        + "Please re-install black with the '[d]' extra install "
+        + "to obtain aiohttp_cors: `pip install black[d]`",
+        file=sys.stderr,
+    )
+    sys.exit(-1)
+
 import black
 import click
 

From 4d6a84a8294d035747404d00b88a925fc2640e1e Mon Sep 17 00:00:00 2001
From: Hadi Alqattan <alqattanhadizaki@gmail.com>
Date: Mon, 19 Oct 2020 00:24:33 +0300
Subject: [PATCH 0033/1034] Allow black's Github action params overriding.
 (#1755)

* Allow default params overriding.

* Update: docs and action.yaml.

* The second contirbution, add my name to authors.md

* Correct docs `with.args` example.

* Just to rerun the Travis jobs.

* chmod 755
---
 README.md                       |  1 +
 action.yml                      |  2 +-
 Dockerfile => action/Dockerfile |  4 +++-
 action/entrypoint.sh            | 10 ++++++++++
 docs/authors.md                 |  1 +
 docs/github_actions.md          |  4 +++-
 6 files changed, 19 insertions(+), 3 deletions(-)
 rename Dockerfile => action/Dockerfile (64%)
 create mode 100755 action/entrypoint.sh

diff --git a/README.md b/README.md
index 2ca76dd6415..7cd4d7f13b2 100644
--- a/README.md
+++ b/README.md
@@ -574,6 +574,7 @@ Multiple contributions by:
 - [Gregory P. Smith](mailto:greg@krypto.org)
 - Gustavo Camargo
 - hauntsaninja
+- [Hadi Alqattan](mailto:alqattanhadizaki@gmail.com)
 - [Heaford](mailto:dan@heaford.com)
 - [Hugo Barrera](mailto::hugo@barrera.io)
 - Hugo van Kemenade
diff --git a/action.yml b/action.yml
index 2ce1c0bf2ef..60bf369a3d8 100644
--- a/action.yml
+++ b/action.yml
@@ -6,4 +6,4 @@ branding:
   icon: "check-circle"
 runs:
   using: "docker"
-  image: "Dockerfile"
+  image: "action/Dockerfile"
diff --git a/Dockerfile b/action/Dockerfile
similarity index 64%
rename from Dockerfile
rename to action/Dockerfile
index a03d23a1078..eb2209940db 100644
--- a/Dockerfile
+++ b/action/Dockerfile
@@ -5,4 +5,6 @@ ENV PYTHONUNBUFFERED 1
 
 RUN pip install --upgrade --no-cache-dir black
 
-ENTRYPOINT /usr/local/bin/black --check --diff  .
+COPY entrypoint.sh /entrypoint.sh
+
+ENTRYPOINT ["/entrypoint.sh"]
diff --git a/action/entrypoint.sh b/action/entrypoint.sh
new file mode 100755
index 00000000000..dc86fa1996e
--- /dev/null
+++ b/action/entrypoint.sh
@@ -0,0 +1,10 @@
+#!/bin/sh
+set -e
+
+if [ $# -eq 0 ]; then
+    # Default (if no args provided).
+    sh -c "black . --check --diff"
+else
+    # Custom args.
+    sh -c "black $*"
+fi
diff --git a/docs/authors.md b/docs/authors.md
index a5349b4b9df..ebf64eaae76 100644
--- a/docs/authors.md
+++ b/docs/authors.md
@@ -69,6 +69,7 @@ Multiple contributions by:
 - [Gregory P. Smith](mailto:greg@krypto.org)
 - Gustavo Camargo
 - hauntsaninja
+- [Hadi Alqattan](mailto:alqattanhadizaki@gmail.com)
 - [Heaford](mailto:dan@heaford.com)
 - [Hugo Barrera](mailto::hugo@barrera.io)
 - Hugo van Kemenade
diff --git a/docs/github_actions.md b/docs/github_actions.md
index 7ff87540242..ac80c2fab6f 100644
--- a/docs/github_actions.md
+++ b/docs/github_actions.md
@@ -15,5 +15,7 @@ jobs:
     steps:
       - uses: actions/checkout@v2
       - uses: actions/setup-python@v2
-      - uses: psf/black@stable
+      - uses: psf/black@stable # the default is equivalent to `black . --diff --check`.
+        with: # (optional - override the default parameters).
+          args: ". --diff --check"
 ```

From 3e3da8eef6f4ba48da1505ad68ca0e1d788f6d6b Mon Sep 17 00:00:00 2001
From: "David W.H. Swenson" <dwhs@hyperblazer.net>
Date: Sun, 18 Oct 2020 23:27:15 +0200
Subject: [PATCH 0034/1034] Fix GitHub markdown links to work on RTD (#1752)

* Fix internal links to work on RTD

Note that these still lead to GitHub, instead of staying on RTD.

* Point links to better anchors
---
 CONTRIBUTING.md                |  2 +-
 README.md                      |  2 +-
 docs/authors.md                |  1 +
 docs/change_log.md             |  6 ++++++
 docs/contributing_to_black.md  |  2 +-
 docs/installation_and_usage.md | 15 ++++++++-------
 6 files changed, 18 insertions(+), 10 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d446e6a0806..a4250f78718 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -52,7 +52,7 @@ your PR. You may need to change
 configuration for it to pass.
 
 For more `black-primer` information visit the
-[documentation](https://github.com/psf/black/blob/master/docs/black_primer.md).
+[documentation](https://github.com/psf/black/blob/master/docs/black_primer.md#black-primer).
 
 ## Hygiene
 
diff --git a/README.md b/README.md
index 7cd4d7f13b2..47472810114 100644
--- a/README.md
+++ b/README.md
@@ -164,7 +164,7 @@ about _Black_'s changes or will overwrite _Black_'s changes. A good example of t
 should be configured to neither warn about nor overwrite _Black_'s changes.
 
 Actual details on _Black_ compatible configurations for various tools can be found in
-[compatible_configs](https://github.com/psf/black/blob/master/docs/compatible_configs.md).
+[compatible_configs](https://github.com/psf/black/blob/master/docs/compatible_configs.md#black-compatible-configurations).
 
 ### Migrating your code style without ruining git blame
 
diff --git a/docs/authors.md b/docs/authors.md
index ebf64eaae76..cdf5046c446 100644
--- a/docs/authors.md
+++ b/docs/authors.md
@@ -133,6 +133,7 @@ Multiple contributions by:
 - [Paul Ganssle](mailto:p.ganssle@gmail.com)
 - [Paul Meinhardt](mailto:mnhrdt@gmail.com)
 - [Peter Bengtsson](mailto:mail@peterbe.com)
+- [Peter Grayson](mailto:pete@jpgrayson.net)
 - [Peter Stensmyr](mailto:peter.stensmyr@gmail.com)
 - pmacosta
 - [Quentin Pradet](mailto:quentin@pradet.me)
diff --git a/docs/change_log.md b/docs/change_log.md
index e183ca545b6..1ee35a4d8f9 100644
--- a/docs/change_log.md
+++ b/docs/change_log.md
@@ -17,6 +17,12 @@
 
 - fixed a crash when PWD=/ on POSIX (#1631)
 
+- fixed "I/O operation on closed file" when using --diff (#1664)
+
+- Prevent coloured diff output being interleaved with multiple files (#1673)
+
+- Added support for PEP 614 relaxed decorator syntax on python 3.9 (#1711)
+
 ### 20.8b1
 
 #### _Packaging_
diff --git a/docs/contributing_to_black.md b/docs/contributing_to_black.md
index 8e332993f97..f0be872a578 100644
--- a/docs/contributing_to_black.md
+++ b/docs/contributing_to_black.md
@@ -54,7 +54,7 @@ your PR. You may need to change
 configuration for it to pass.
 
 For more `black-primer` information visit the
-[documentation](https://github.com/psf/black/blob/master/docs/black_primer.md).
+[documentation](https://github.com/psf/black/blob/master/docs/black_primer.md#).
 
 ## Hygiene
 
diff --git a/docs/installation_and_usage.md b/docs/installation_and_usage.md
index 7de8b657adf..c91a1c400ef 100644
--- a/docs/installation_and_usage.md
+++ b/docs/installation_and_usage.md
@@ -119,7 +119,7 @@ about _Black_'s changes or will overwrite _Black_'s changes. A good example of t
 should be configured to neither warn about nor overwrite _Black_'s changes.
 
 Actual details on _Black_ compatible configurations for various tools can be found in
-[compatible_configs](https://github.com/psf/black/blob/master/docs/compatible_configs.md).
+[compatible_configs](https://github.com/psf/black/blob/master/docs/compatible_configs.md#).
 
 ## Migrating your code style without ruining git blame
 
@@ -167,12 +167,13 @@ know!)
 
 ## NOTE: This is a beta product
 
-_Black_ is already [successfully used](#used-by) by many projects, small and big. It
-also sports a decent test suite. However, it is still very new. Things will probably be
-wonky for a while. This is made explicit by the "Beta" trove classifier, as well as by
-the "b" in the version number. What this means for you is that **until the formatter
-becomes stable, you should expect some formatting to change in the future**. That being
-said, no drastic stylistic changes are planned, mostly responses to bug reports.
+_Black_ is already [successfully used](https://github.com/psf/black#used-by) by many
+projects, small and big. It also sports a decent test suite. However, it is still very
+new. Things will probably be wonky for a while. This is made explicit by the "Beta"
+trove classifier, as well as by the "b" in the version number. What this means for you
+is that **until the formatter becomes stable, you should expect some formatting to
+change in the future**. That being said, no drastic stylistic changes are planned,
+mostly responses to bug reports.
 
 Also, as a temporary safety measure, _Black_ will check that the reformatted code still
 produces a valid AST that is equivalent to the original. This slows it down. If you're

From 3be0aa71d9e39a8fdb6f38cc796709bf4f9c11d9 Mon Sep 17 00:00:00 2001
From: johnthagen <johnthagen@users.noreply.github.com>
Date: Mon, 19 Oct 2020 13:34:42 -0400
Subject: [PATCH 0035/1034] Update PyCharm integrations instructions to avoid
 running on external changes (#1769)

---
 docs/editor_integration.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/docs/editor_integration.md b/docs/editor_integration.md
index 73107d6a4a1..21a6865d60e 100644
--- a/docs/editor_integration.md
+++ b/docs/editor_integration.md
@@ -72,7 +72,9 @@ On Windows / Linux / BSD:
       - Output paths to refresh: `$FilePath$`
       - Working directory: `$ProjectFileDir$`
 
-   - Uncheck "Auto-save edited files to trigger the watcher" in Advanced Options
+   - In Advanced Options
+     - Uncheck "Auto-save edited files to trigger the watcher"
+     - Uncheck "Trigger the watcher on external changes"
 
 ## Wing IDE
 

From 407052724fa1c97ee8bcd4e96de650def00be03e Mon Sep 17 00:00:00 2001
From: Sagi Shadur <saroad2@gmail.com>
Date: Mon, 19 Oct 2020 20:35:26 +0300
Subject: [PATCH 0036/1034] Switch to pytest and tox (#1763)

* Add venv to .gitignore

* Use tox to run tests

* Make fuzz run in tox

* Split tests files

* Fix import error
---
 .github/workflows/fuzz.yml |   7 +-
 .github/workflows/test.yml |   5 +-
 .gitignore                 |   1 +
 test_requirements.txt      |   4 +
 tests/test_black.py        | 230 +------------------------------------
 tests/test_blackd.py       | 192 +++++++++++++++++++++++++++++++
 tests/util.py              |  43 +++++++
 tox.ini                    |  26 +++++
 8 files changed, 275 insertions(+), 233 deletions(-)
 create mode 100644 test_requirements.txt
 create mode 100644 tests/test_blackd.py
 create mode 100644 tests/util.py
 create mode 100644 tox.ini

diff --git a/.github/workflows/fuzz.yml b/.github/workflows/fuzz.yml
index 9aec3c08c63..343eed10df8 100644
--- a/.github/workflows/fuzz.yml
+++ b/.github/workflows/fuzz.yml
@@ -21,11 +21,8 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          python -m pip install --upgrade coverage
-          python -m pip install --upgrade hypothesmith
-          python -m pip install -e ".[d]"
+          python -m pip install --upgrade tox
 
       - name: Run fuzz tests
         run: |
-          coverage run fuzz.py
-          coverage report
+          tox -e fuzz
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index e30a8b8eb68..8dd4e4f59fd 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -22,9 +22,8 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          python -m pip install --upgrade coverage
-          python -m pip install -e ".[d]"
+          python -m pip install --upgrade tox
 
       - name: Unit tests
         run: |
-          coverage run -m unittest
+          tox -e py
diff --git a/.gitignore b/.gitignore
index 6b94cacd183..3207e72ae28 100644
--- a/.gitignore
+++ b/.gitignore
@@ -15,3 +15,4 @@ src/_black_version.py
 .dmypy.json
 *.swp
 .hypothesis/
+venv/
\ No newline at end of file
diff --git a/test_requirements.txt b/test_requirements.txt
new file mode 100644
index 00000000000..999d05c0106
--- /dev/null
+++ b/test_requirements.txt
@@ -0,0 +1,4 @@
+pytest >= 6.0.1
+pytest-mock >= 3.2.0
+pytest-cases >= 2.1.2
+coverage >= 5.2.1
\ No newline at end of file
diff --git a/tests/test_black.py b/tests/test_black.py
index e17f43b88d4..7927b368b5d 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -22,7 +22,6 @@
     Dict,
     Generator,
     List,
-    Tuple,
     Iterator,
     TypeVar,
 )
@@ -36,18 +35,10 @@
 import black
 from black import Feature, TargetVersion
 
-try:
-    import blackd
-    from aiohttp.test_utils import AioHTTPTestCase, unittest_run_loop
-    from aiohttp import web
-except ImportError:
-    has_blackd_deps = False
-else:
-    has_blackd_deps = True
-
 from pathspec import PathSpec
 
 # Import other test classes
+from tests.util import THIS_DIR, read_data, DETERMINISTIC_HEADER
 from .test_primer import PrimerCLITests  # noqa: F401
 
 
@@ -55,10 +46,6 @@
 ff = partial(black.format_file_in_place, mode=DEFAULT_MODE, fast=True)
 fs = partial(black.format_str, mode=DEFAULT_MODE)
 THIS_FILE = Path(__file__)
-THIS_DIR = THIS_FILE.parent
-PROJECT_ROOT = THIS_DIR.parent
-DETERMINISTIC_HEADER = "[Deterministic header]"
-EMPTY_LINE = "# EMPTY LINE WITH WHITESPACE" + " (this comment will be removed)"
 PY36_VERSIONS = {
     TargetVersion.PY36,
     TargetVersion.PY37,
@@ -74,29 +61,6 @@ def dump_to_stderr(*output: str) -> str:
     return "\n" + "\n".join(output) + "\n"
 
 
-def read_data(name: str, data: bool = True) -> Tuple[str, str]:
-    """read_data('test_name') -> 'input', 'output'"""
-    if not name.endswith((".py", ".pyi", ".out", ".diff")):
-        name += ".py"
-    _input: List[str] = []
-    _output: List[str] = []
-    base_dir = THIS_DIR / "data" if data else PROJECT_ROOT
-    with open(base_dir / name, "r", encoding="utf8") as test:
-        lines = test.readlines()
-    result = _input
-    for line in lines:
-        line = line.replace(EMPTY_LINE, "")
-        if line.rstrip() == "# output":
-            result = _output
-            continue
-
-        result.append(line)
-    if _input and not _output:
-        # If there's no output marker, treat the entire file as already pre-formatted.
-        _output = _input[:]
-    return "".join(_input).strip() + "\n", "".join(_output).strip() + "\n"
-
-
 @contextmanager
 def cache_dir(exists: bool = True) -> Iterator[Path]:
     with TemporaryDirectory() as workspace:
@@ -119,17 +83,6 @@ def event_loop() -> Iterator[None]:
         loop.close()
 
 
-@contextmanager
-def skip_if_exception(e: str) -> Iterator[None]:
-    try:
-        yield
-    except Exception as exc:
-        if exc.__class__.__name__ == e:
-            unittest.skip(f"Encountered expected exception {exc}, skipping")
-        else:
-            raise
-
-
 class FakeContext(click.Context):
     """A fake click Context for when calling functions that need it."""
 
@@ -239,9 +192,12 @@ def test_empty_ff(self) -> None:
             os.unlink(tmp_file)
         self.assertFormatEqual(expected, actual)
 
-    def test_self(self) -> None:
+    def test_run_on_test_black(self) -> None:
         self.checkSourceFile("tests/test_black.py")
 
+    def test_run_on_test_blackd(self) -> None:
+        self.checkSourceFile("tests/test_blackd.py")
+
     def test_black(self) -> None:
         self.checkSourceFile("src/black/__init__.py")
 
@@ -1969,14 +1925,6 @@ def fail(*args: Any, **kwargs: Any) -> None:
         ):
             ff(THIS_FILE)
 
-    @unittest.skipUnless(has_blackd_deps, "blackd's dependencies are not installed")
-    def test_blackd_main(self) -> None:
-        with patch("blackd.web.run_app"):
-            result = CliRunner().invoke(blackd.main, [])
-            if result.exception is not None:
-                raise result.exception
-            self.assertEqual(result.exit_code, 0)
-
     def test_invalid_config_return_code(self) -> None:
         tmp_file = Path(black.dump_to_file())
         try:
@@ -2053,174 +2001,6 @@ def test_bpo_33660_workaround(self) -> None:
             os.chdir(str(old_cwd))
 
 
-class BlackDTestCase(AioHTTPTestCase):
-    async def get_application(self) -> web.Application:
-        return blackd.make_app()
-
-    # TODO: remove these decorators once the below is released
-    # https://github.com/aio-libs/aiohttp/pull/3727
-    @skip_if_exception("ClientOSError")
-    @unittest.skipUnless(has_blackd_deps, "blackd's dependencies are not installed")
-    @unittest_run_loop
-    async def test_blackd_request_needs_formatting(self) -> None:
-        response = await self.client.post("/", data=b"print('hello world')")
-        self.assertEqual(response.status, 200)
-        self.assertEqual(response.charset, "utf8")
-        self.assertEqual(await response.read(), b'print("hello world")\n')
-
-    @skip_if_exception("ClientOSError")
-    @unittest.skipUnless(has_blackd_deps, "blackd's dependencies are not installed")
-    @unittest_run_loop
-    async def test_blackd_request_no_change(self) -> None:
-        response = await self.client.post("/", data=b'print("hello world")\n')
-        self.assertEqual(response.status, 204)
-        self.assertEqual(await response.read(), b"")
-
-    @skip_if_exception("ClientOSError")
-    @unittest.skipUnless(has_blackd_deps, "blackd's dependencies are not installed")
-    @unittest_run_loop
-    async def test_blackd_request_syntax_error(self) -> None:
-        response = await self.client.post("/", data=b"what even ( is")
-        self.assertEqual(response.status, 400)
-        content = await response.text()
-        self.assertTrue(
-            content.startswith("Cannot parse"),
-            msg=f"Expected error to start with 'Cannot parse', got {repr(content)}",
-        )
-
-    @skip_if_exception("ClientOSError")
-    @unittest.skipUnless(has_blackd_deps, "blackd's dependencies are not installed")
-    @unittest_run_loop
-    async def test_blackd_unsupported_version(self) -> None:
-        response = await self.client.post(
-            "/", data=b"what", headers={blackd.PROTOCOL_VERSION_HEADER: "2"}
-        )
-        self.assertEqual(response.status, 501)
-
-    @skip_if_exception("ClientOSError")
-    @unittest.skipUnless(has_blackd_deps, "blackd's dependencies are not installed")
-    @unittest_run_loop
-    async def test_blackd_supported_version(self) -> None:
-        response = await self.client.post(
-            "/", data=b"what", headers={blackd.PROTOCOL_VERSION_HEADER: "1"}
-        )
-        self.assertEqual(response.status, 200)
-
-    @skip_if_exception("ClientOSError")
-    @unittest.skipUnless(has_blackd_deps, "blackd's dependencies are not installed")
-    @unittest_run_loop
-    async def test_blackd_invalid_python_variant(self) -> None:
-        async def check(header_value: str, expected_status: int = 400) -> None:
-            response = await self.client.post(
-                "/", data=b"what", headers={blackd.PYTHON_VARIANT_HEADER: header_value}
-            )
-            self.assertEqual(response.status, expected_status)
-
-        await check("lol")
-        await check("ruby3.5")
-        await check("pyi3.6")
-        await check("py1.5")
-        await check("2.8")
-        await check("py2.8")
-        await check("3.0")
-        await check("pypy3.0")
-        await check("jython3.4")
-
-    @skip_if_exception("ClientOSError")
-    @unittest.skipUnless(has_blackd_deps, "blackd's dependencies are not installed")
-    @unittest_run_loop
-    async def test_blackd_pyi(self) -> None:
-        source, expected = read_data("stub.pyi")
-        response = await self.client.post(
-            "/", data=source, headers={blackd.PYTHON_VARIANT_HEADER: "pyi"}
-        )
-        self.assertEqual(response.status, 200)
-        self.assertEqual(await response.text(), expected)
-
-    @skip_if_exception("ClientOSError")
-    @unittest.skipUnless(has_blackd_deps, "blackd's dependencies are not installed")
-    @unittest_run_loop
-    async def test_blackd_diff(self) -> None:
-        diff_header = re.compile(
-            r"(In|Out)\t\d\d\d\d-\d\d-\d\d \d\d:\d\d:\d\d\.\d\d\d\d\d\d \+\d\d\d\d"
-        )
-
-        source, _ = read_data("blackd_diff.py")
-        expected, _ = read_data("blackd_diff.diff")
-
-        response = await self.client.post(
-            "/", data=source, headers={blackd.DIFF_HEADER: "true"}
-        )
-        self.assertEqual(response.status, 200)
-
-        actual = await response.text()
-        actual = diff_header.sub(DETERMINISTIC_HEADER, actual)
-        self.assertEqual(actual, expected)
-
-    @skip_if_exception("ClientOSError")
-    @unittest.skipUnless(has_blackd_deps, "blackd's dependencies are not installed")
-    @unittest_run_loop
-    async def test_blackd_python_variant(self) -> None:
-        code = (
-            "def f(\n"
-            "    and_has_a_bunch_of,\n"
-            "    very_long_arguments_too,\n"
-            "    and_lots_of_them_as_well_lol,\n"
-            "    **and_very_long_keyword_arguments\n"
-            "):\n"
-            "    pass\n"
-        )
-
-        async def check(header_value: str, expected_status: int) -> None:
-            response = await self.client.post(
-                "/", data=code, headers={blackd.PYTHON_VARIANT_HEADER: header_value}
-            )
-            self.assertEqual(
-                response.status, expected_status, msg=await response.text()
-            )
-
-        await check("3.6", 200)
-        await check("py3.6", 200)
-        await check("3.6,3.7", 200)
-        await check("3.6,py3.7", 200)
-        await check("py36,py37", 200)
-        await check("36", 200)
-        await check("3.6.4", 200)
-
-        await check("2", 204)
-        await check("2.7", 204)
-        await check("py2.7", 204)
-        await check("3.4", 204)
-        await check("py3.4", 204)
-        await check("py34,py36", 204)
-        await check("34", 204)
-
-    @skip_if_exception("ClientOSError")
-    @unittest.skipUnless(has_blackd_deps, "blackd's dependencies are not installed")
-    @unittest_run_loop
-    async def test_blackd_line_length(self) -> None:
-        response = await self.client.post(
-            "/", data=b'print("hello")\n', headers={blackd.LINE_LENGTH_HEADER: "7"}
-        )
-        self.assertEqual(response.status, 200)
-
-    @skip_if_exception("ClientOSError")
-    @unittest.skipUnless(has_blackd_deps, "blackd's dependencies are not installed")
-    @unittest_run_loop
-    async def test_blackd_invalid_line_length(self) -> None:
-        response = await self.client.post(
-            "/", data=b'print("hello")\n', headers={blackd.LINE_LENGTH_HEADER: "NaN"}
-        )
-        self.assertEqual(response.status, 400)
-
-    @skip_if_exception("ClientOSError")
-    @unittest.skipUnless(has_blackd_deps, "blackd's dependencies are not installed")
-    @unittest_run_loop
-    async def test_blackd_response_black_version_header(self) -> None:
-        response = await self.client.post("/")
-        self.assertIsNotNone(response.headers.get(blackd.BLACK_VERSION_HEADER))
-
-
 with open(black.__file__, "r", encoding="utf-8") as _bf:
     black_source_lines = _bf.readlines()
 
diff --git a/tests/test_blackd.py b/tests/test_blackd.py
new file mode 100644
index 00000000000..9127297c54f
--- /dev/null
+++ b/tests/test_blackd.py
@@ -0,0 +1,192 @@
+import re
+import unittest
+from unittest.mock import patch
+
+from click.testing import CliRunner
+
+from tests.util import read_data, DETERMINISTIC_HEADER, skip_if_exception
+
+try:
+    import blackd
+    from aiohttp.test_utils import AioHTTPTestCase, unittest_run_loop
+    from aiohttp import web
+except ImportError:
+    has_blackd_deps = False
+else:
+    has_blackd_deps = True
+
+
+class BlackDTestCase(AioHTTPTestCase):
+    @unittest.skipUnless(has_blackd_deps, "blackd's dependencies are not installed")
+    def test_blackd_main(self) -> None:
+        with patch("blackd.web.run_app"):
+            result = CliRunner().invoke(blackd.main, [])
+            if result.exception is not None:
+                raise result.exception
+            self.assertEqual(result.exit_code, 0)
+
+    async def get_application(self) -> web.Application:
+        return blackd.make_app()
+
+    # TODO: remove these decorators once the below is released
+    # https://github.com/aio-libs/aiohttp/pull/3727
+    @skip_if_exception("ClientOSError")
+    @unittest.skipUnless(has_blackd_deps, "blackd's dependencies are not installed")
+    @unittest_run_loop
+    async def test_blackd_request_needs_formatting(self) -> None:
+        response = await self.client.post("/", data=b"print('hello world')")
+        self.assertEqual(response.status, 200)
+        self.assertEqual(response.charset, "utf8")
+        self.assertEqual(await response.read(), b'print("hello world")\n')
+
+    @skip_if_exception("ClientOSError")
+    @unittest.skipUnless(has_blackd_deps, "blackd's dependencies are not installed")
+    @unittest_run_loop
+    async def test_blackd_request_no_change(self) -> None:
+        response = await self.client.post("/", data=b'print("hello world")\n')
+        self.assertEqual(response.status, 204)
+        self.assertEqual(await response.read(), b"")
+
+    @skip_if_exception("ClientOSError")
+    @unittest.skipUnless(has_blackd_deps, "blackd's dependencies are not installed")
+    @unittest_run_loop
+    async def test_blackd_request_syntax_error(self) -> None:
+        response = await self.client.post("/", data=b"what even ( is")
+        self.assertEqual(response.status, 400)
+        content = await response.text()
+        self.assertTrue(
+            content.startswith("Cannot parse"),
+            msg=f"Expected error to start with 'Cannot parse', got {repr(content)}",
+        )
+
+    @skip_if_exception("ClientOSError")
+    @unittest.skipUnless(has_blackd_deps, "blackd's dependencies are not installed")
+    @unittest_run_loop
+    async def test_blackd_unsupported_version(self) -> None:
+        response = await self.client.post(
+            "/", data=b"what", headers={blackd.PROTOCOL_VERSION_HEADER: "2"}
+        )
+        self.assertEqual(response.status, 501)
+
+    @skip_if_exception("ClientOSError")
+    @unittest.skipUnless(has_blackd_deps, "blackd's dependencies are not installed")
+    @unittest_run_loop
+    async def test_blackd_supported_version(self) -> None:
+        response = await self.client.post(
+            "/", data=b"what", headers={blackd.PROTOCOL_VERSION_HEADER: "1"}
+        )
+        self.assertEqual(response.status, 200)
+
+    @skip_if_exception("ClientOSError")
+    @unittest.skipUnless(has_blackd_deps, "blackd's dependencies are not installed")
+    @unittest_run_loop
+    async def test_blackd_invalid_python_variant(self) -> None:
+        async def check(header_value: str, expected_status: int = 400) -> None:
+            response = await self.client.post(
+                "/", data=b"what", headers={blackd.PYTHON_VARIANT_HEADER: header_value}
+            )
+            self.assertEqual(response.status, expected_status)
+
+        await check("lol")
+        await check("ruby3.5")
+        await check("pyi3.6")
+        await check("py1.5")
+        await check("2.8")
+        await check("py2.8")
+        await check("3.0")
+        await check("pypy3.0")
+        await check("jython3.4")
+
+    @skip_if_exception("ClientOSError")
+    @unittest.skipUnless(has_blackd_deps, "blackd's dependencies are not installed")
+    @unittest_run_loop
+    async def test_blackd_pyi(self) -> None:
+        source, expected = read_data("stub.pyi")
+        response = await self.client.post(
+            "/", data=source, headers={blackd.PYTHON_VARIANT_HEADER: "pyi"}
+        )
+        self.assertEqual(response.status, 200)
+        self.assertEqual(await response.text(), expected)
+
+    @skip_if_exception("ClientOSError")
+    @unittest.skipUnless(has_blackd_deps, "blackd's dependencies are not installed")
+    @unittest_run_loop
+    async def test_blackd_diff(self) -> None:
+        diff_header = re.compile(
+            r"(In|Out)\t\d\d\d\d-\d\d-\d\d \d\d:\d\d:\d\d\.\d\d\d\d\d\d \+\d\d\d\d"
+        )
+
+        source, _ = read_data("blackd_diff.py")
+        expected, _ = read_data("blackd_diff.diff")
+
+        response = await self.client.post(
+            "/", data=source, headers={blackd.DIFF_HEADER: "true"}
+        )
+        self.assertEqual(response.status, 200)
+
+        actual = await response.text()
+        actual = diff_header.sub(DETERMINISTIC_HEADER, actual)
+        self.assertEqual(actual, expected)
+
+    @skip_if_exception("ClientOSError")
+    @unittest.skipUnless(has_blackd_deps, "blackd's dependencies are not installed")
+    @unittest_run_loop
+    async def test_blackd_python_variant(self) -> None:
+        code = (
+            "def f(\n"
+            "    and_has_a_bunch_of,\n"
+            "    very_long_arguments_too,\n"
+            "    and_lots_of_them_as_well_lol,\n"
+            "    **and_very_long_keyword_arguments\n"
+            "):\n"
+            "    pass\n"
+        )
+
+        async def check(header_value: str, expected_status: int) -> None:
+            response = await self.client.post(
+                "/", data=code, headers={blackd.PYTHON_VARIANT_HEADER: header_value}
+            )
+            self.assertEqual(
+                response.status, expected_status, msg=await response.text()
+            )
+
+        await check("3.6", 200)
+        await check("py3.6", 200)
+        await check("3.6,3.7", 200)
+        await check("3.6,py3.7", 200)
+        await check("py36,py37", 200)
+        await check("36", 200)
+        await check("3.6.4", 200)
+
+        await check("2", 204)
+        await check("2.7", 204)
+        await check("py2.7", 204)
+        await check("3.4", 204)
+        await check("py3.4", 204)
+        await check("py34,py36", 204)
+        await check("34", 204)
+
+    @skip_if_exception("ClientOSError")
+    @unittest.skipUnless(has_blackd_deps, "blackd's dependencies are not installed")
+    @unittest_run_loop
+    async def test_blackd_line_length(self) -> None:
+        response = await self.client.post(
+            "/", data=b'print("hello")\n', headers={blackd.LINE_LENGTH_HEADER: "7"}
+        )
+        self.assertEqual(response.status, 200)
+
+    @skip_if_exception("ClientOSError")
+    @unittest.skipUnless(has_blackd_deps, "blackd's dependencies are not installed")
+    @unittest_run_loop
+    async def test_blackd_invalid_line_length(self) -> None:
+        response = await self.client.post(
+            "/", data=b'print("hello")\n', headers={blackd.LINE_LENGTH_HEADER: "NaN"}
+        )
+        self.assertEqual(response.status, 400)
+
+    @skip_if_exception("ClientOSError")
+    @unittest.skipUnless(has_blackd_deps, "blackd's dependencies are not installed")
+    @unittest_run_loop
+    async def test_blackd_response_black_version_header(self) -> None:
+        response = await self.client.post("/")
+        self.assertIsNotNone(response.headers.get(blackd.BLACK_VERSION_HEADER))
diff --git a/tests/util.py b/tests/util.py
new file mode 100644
index 00000000000..9c3d3cbc99d
--- /dev/null
+++ b/tests/util.py
@@ -0,0 +1,43 @@
+import unittest
+from contextlib import contextmanager
+from pathlib import Path
+from typing import List, Tuple, Iterator
+
+THIS_DIR = Path(__file__).parent
+PROJECT_ROOT = THIS_DIR.parent
+EMPTY_LINE = "# EMPTY LINE WITH WHITESPACE" + " (this comment will be removed)"
+DETERMINISTIC_HEADER = "[Deterministic header]"
+
+
+@contextmanager
+def skip_if_exception(e: str) -> Iterator[None]:
+    try:
+        yield
+    except Exception as exc:
+        if exc.__class__.__name__ == e:
+            unittest.skip(f"Encountered expected exception {exc}, skipping")
+        else:
+            raise
+
+
+def read_data(name: str, data: bool = True) -> Tuple[str, str]:
+    """read_data('test_name') -> 'input', 'output'"""
+    if not name.endswith((".py", ".pyi", ".out", ".diff")):
+        name += ".py"
+    _input: List[str] = []
+    _output: List[str] = []
+    base_dir = THIS_DIR / "data" if data else PROJECT_ROOT
+    with open(base_dir / name, "r", encoding="utf8") as test:
+        lines = test.readlines()
+    result = _input
+    for line in lines:
+        line = line.replace(EMPTY_LINE, "")
+        if line.rstrip() == "# output":
+            result = _output
+            continue
+
+        result.append(line)
+    if _input and not _output:
+        # If there's no output marker, treat the entire file as already pre-formatted.
+        _output = _input[:]
+    return "".join(_input).strip() + "\n", "".join(_output).strip() + "\n"
diff --git a/tox.ini b/tox.ini
new file mode 100644
index 00000000000..500a2cad579
--- /dev/null
+++ b/tox.ini
@@ -0,0 +1,26 @@
+[tox]
+envlist = py{36,37,38,39},fuzz
+
+[testenv]
+setenv = PYTHONPATH = {toxinidir}/src
+skip_install = True
+deps =
+    -r{toxinidir}/test_requirements.txt
+commands =
+    pip install -e .[d]
+    coverage erase
+    coverage run -m pytest tests
+    coverage report
+
+[testenv:fuzz]
+skip_install = True
+deps =
+    -r{toxinidir}/test_requirements.txt
+    hypothesmith
+    lark-parser < 0.10.0
+; lark-parser's version is set due to a bug in hypothesis. Once it solved, that would be fixed.
+commands =
+    pip install -e .[d]
+    coverage erase
+    coverage run fuzz.py
+    coverage report
\ No newline at end of file

From 989ea69bd1d0a02aa6c5794d941c122f7b4958b4 Mon Sep 17 00:00:00 2001
From: Antek S <3324881+bluefish6@users.noreply.github.com>
Date: Tue, 27 Oct 2020 11:52:19 +0100
Subject: [PATCH 0037/1034] Update readme.md with current version (#1788)

* Update readme.md with current version

* Update version_control_integration.md
---
 README.md                           | 2 +-
 docs/version_control_integration.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 47472810114..d34ce146e0d 100644
--- a/README.md
+++ b/README.md
@@ -372,7 +372,7 @@ Use [pre-commit](https://pre-commit.com/). Once you
 ```yaml
 repos:
   - repo: https://github.com/psf/black
-    rev: 19.10b0 # Replace by any tag/version: https://github.com/psf/black/tags
+    rev: 20.8b1 # Replace by any tag/version: https://github.com/psf/black/tags
     hooks:
       - id: black
         language_version: python3 # Should be a command that runs python3.6+
diff --git a/docs/version_control_integration.md b/docs/version_control_integration.md
index 25dac308c47..2d8bc172eba 100644
--- a/docs/version_control_integration.md
+++ b/docs/version_control_integration.md
@@ -9,7 +9,7 @@ Use [pre-commit](https://pre-commit.com/). Once you
 ```yaml
 repos:
   - repo: https://github.com/psf/black
-    rev: 19.10b0 # Replace by any tag/version: https://github.com/psf/black/tags
+    rev: 20.8b1 # Replace by any tag/version: https://github.com/psf/black/tags
     hooks:
       - id: black
         language_version: python3 # Should be a command that runs python3.6+

From cabeb5b5457b8fd29d608eca944be6074bd3f31f Mon Sep 17 00:00:00 2001
From: Bibo-Joshi <hinrich.mahler@freenet.de>
Date: Tue, 27 Oct 2020 21:59:43 +0100
Subject: [PATCH 0038/1034] Document some culprits with pre-commit (#1783)

* Document some culprits with pre-commit

* make pre-commit happy

* don't use monospace for black & pre-commit

Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>

* make pre-commit happy again

Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
---
 docs/version_control_integration.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/docs/version_control_integration.md b/docs/version_control_integration.md
index 2d8bc172eba..0e09854a2e5 100644
--- a/docs/version_control_integration.md
+++ b/docs/version_control_integration.md
@@ -23,6 +23,11 @@ for your project. See _Black_'s own
 [pyproject.toml](https://github.com/psf/black/blob/master/pyproject.toml) for an
 example.
 
+When using the `--diff` flag with `pre-commit`, you must also use the `--check` flag.
+When you want to run _Black_ only on specific files in pre-commit, either use
+pre-commit's own `files` and `exclude` or, when using _Black_'s `--include`, set
+`--force-exclude` to the negated regex of `--include`.
+
 If you're already using Python 3.7, switch the `language_version` accordingly. Finally,
 `stable` is a branch that tracks the latest release on PyPI. If you'd rather run on
 master, this is also an option.

From e6cd10e7615f4df537e2eaefcf3904a4feecad1f Mon Sep 17 00:00:00 2001
From: Sagi Shadur <saroad2@gmail.com>
Date: Fri, 30 Oct 2020 17:12:04 +0200
Subject: [PATCH 0039/1034] Extract formatting tests (#1785)

* Update test versions

* Use parametrize to remove tests duplications

* Extract sources format tests

* Fix mypy errors

* Fix .travis.yml
---
 .travis.yml           |   4 +-
 test_requirements.txt |   9 +-
 tests/test_black.py   | 416 ++----------------------------------------
 tests/test_format.py  |  98 ++++++++++
 tests/util.py         |  48 ++++-
 5 files changed, 160 insertions(+), 415 deletions(-)
 create mode 100644 tests/test_format.py

diff --git a/.travis.yml b/.travis.yml
index 86cf24df51b..f035343c6fb 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -4,9 +4,9 @@ cache:
   directories:
     - $HOME/.cache/pre-commit
 env:
-  - TEST_CMD="coverage run -m unittest"
+  - TEST_CMD="tox -e py"
 install:
-  - pip install coverage coveralls pre-commit
+  - pip install coverage coveralls pre-commit tox
   - pip install -e '.[d]'
 script:
   - $TEST_CMD
diff --git a/test_requirements.txt b/test_requirements.txt
index 999d05c0106..3e65cdb669f 100644
--- a/test_requirements.txt
+++ b/test_requirements.txt
@@ -1,4 +1,5 @@
-pytest >= 6.0.1
-pytest-mock >= 3.2.0
-pytest-cases >= 2.1.2
-coverage >= 5.2.1
\ No newline at end of file
+pytest >= 6.1.1
+pytest-mock >= 3.3.1
+pytest-cases >= 2.3.0
+coverage >= 5.3
+parameterized >= 0.7.4
\ No newline at end of file
diff --git a/tests/test_black.py b/tests/test_black.py
index 7927b368b5d..b0cf6ed5caa 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -5,7 +5,6 @@
 from concurrent.futures import ThreadPoolExecutor
 from contextlib import contextmanager
 from dataclasses import replace
-from functools import partial
 import inspect
 from io import BytesIO, TextIOWrapper
 import os
@@ -38,13 +37,19 @@
 from pathspec import PathSpec
 
 # Import other test classes
-from tests.util import THIS_DIR, read_data, DETERMINISTIC_HEADER
+from tests.util import (
+    THIS_DIR,
+    read_data,
+    DETERMINISTIC_HEADER,
+    BlackBaseTestCase,
+    DEFAULT_MODE,
+    fs,
+    ff,
+    dump_to_stderr,
+)
 from .test_primer import PrimerCLITests  # noqa: F401
 
 
-DEFAULT_MODE = black.FileMode(experimental_string_processing=True)
-ff = partial(black.format_file_in_place, mode=DEFAULT_MODE, fast=True)
-fs = partial(black.format_str, mode=DEFAULT_MODE)
 THIS_FILE = Path(__file__)
 PY36_VERSIONS = {
     TargetVersion.PY36,
@@ -57,10 +62,6 @@
 R = TypeVar("R")
 
 
-def dump_to_stderr(*output: str) -> str:
-    return "\n" + "\n".join(output) + "\n"
-
-
 @contextmanager
 def cache_dir(exists: bool = True) -> Iterator[Path]:
     with TemporaryDirectory() as workspace:
@@ -122,29 +123,7 @@ def isolation(self, *args: Any, **kwargs: Any) -> Generator[BinaryIO, None, None
                 sys.stderr = hold_stderr
 
 
-class BlackTestCase(unittest.TestCase):
-    maxDiff = None
-    _diffThreshold = 2 ** 20
-
-    def assertFormatEqual(self, expected: str, actual: str) -> None:
-        if actual != expected and not os.environ.get("SKIP_AST_PRINT"):
-            bdv: black.DebugVisitor[Any]
-            black.out("Expected tree:", fg="green")
-            try:
-                exp_node = black.lib2to3_parse(expected)
-                bdv = black.DebugVisitor()
-                list(bdv.visit(exp_node))
-            except Exception as ve:
-                black.err(str(ve))
-            black.out("Actual tree:", fg="red")
-            try:
-                exp_node = black.lib2to3_parse(actual)
-                bdv = black.DebugVisitor()
-                list(bdv.visit(exp_node))
-            except Exception as ve:
-                black.err(str(ve))
-        self.assertMultiLineEqual(expected, actual)
-
+class BlackTestCase(BlackBaseTestCase):
     def invokeBlack(
         self, args: List[str], exit_code: int = 0, ignore_config: bool = True
     ) -> None:
@@ -163,16 +142,6 @@ def invokeBlack(
             ),
         )
 
-    @patch("black.dump_to_file", dump_to_stderr)
-    def checkSourceFile(self, name: str, mode: black.FileMode = DEFAULT_MODE) -> None:
-        path = THIS_DIR.parent / name
-        source, expected = read_data(str(path), data=False)
-        actual = fs(source, mode=mode)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, mode)
-        self.assertFalse(ff(path))
-
     @patch("black.dump_to_file", dump_to_stderr)
     def test_empty(self) -> None:
         source = expected = ""
@@ -192,48 +161,6 @@ def test_empty_ff(self) -> None:
             os.unlink(tmp_file)
         self.assertFormatEqual(expected, actual)
 
-    def test_run_on_test_black(self) -> None:
-        self.checkSourceFile("tests/test_black.py")
-
-    def test_run_on_test_blackd(self) -> None:
-        self.checkSourceFile("tests/test_blackd.py")
-
-    def test_black(self) -> None:
-        self.checkSourceFile("src/black/__init__.py")
-
-    def test_pygram(self) -> None:
-        self.checkSourceFile("src/blib2to3/pygram.py")
-
-    def test_pytree(self) -> None:
-        self.checkSourceFile("src/blib2to3/pytree.py")
-
-    def test_conv(self) -> None:
-        self.checkSourceFile("src/blib2to3/pgen2/conv.py")
-
-    def test_driver(self) -> None:
-        self.checkSourceFile("src/blib2to3/pgen2/driver.py")
-
-    def test_grammar(self) -> None:
-        self.checkSourceFile("src/blib2to3/pgen2/grammar.py")
-
-    def test_literals(self) -> None:
-        self.checkSourceFile("src/blib2to3/pgen2/literals.py")
-
-    def test_parse(self) -> None:
-        self.checkSourceFile("src/blib2to3/pgen2/parse.py")
-
-    def test_pgen(self) -> None:
-        self.checkSourceFile("src/blib2to3/pgen2/pgen.py")
-
-    def test_tokenize(self) -> None:
-        self.checkSourceFile("src/blib2to3/pgen2/tokenize.py")
-
-    def test_token(self) -> None:
-        self.checkSourceFile("src/blib2to3/pgen2/token.py")
-
-    def test_setup(self) -> None:
-        self.checkSourceFile("setup.py")
-
     def test_piping(self) -> None:
         source, expected = read_data("src/black/__init__", data=False)
         result = BlackRunner().invoke(
@@ -291,22 +218,6 @@ def test_piping_diff_with_color(self) -> None:
         self.assertIn("\033[31m", actual)
         self.assertIn("\033[0m", actual)
 
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_function(self) -> None:
-        source, expected = read_data("function")
-        actual = fs(source)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_function2(self) -> None:
-        source, expected = read_data("function2")
-        actual = fs(source)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
     @patch("black.dump_to_file", dump_to_stderr)
     def _test_wip(self) -> None:
         source, expected = read_data("wip")
@@ -322,14 +233,6 @@ def _test_wip(self) -> None:
         black.assert_equivalent(source, actual)
         black.assert_stable(source, actual, black.FileMode())
 
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_function_trailing_comma(self) -> None:
-        source, expected = read_data("function_trailing_comma")
-        actual = fs(source)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
     @unittest.expectedFailure
     @patch("black.dump_to_file", dump_to_stderr)
     def test_trailing_comma_optional_parens_stability1(self) -> None:
@@ -351,14 +254,6 @@ def test_trailing_comma_optional_parens_stability3(self) -> None:
         actual = fs(source)
         black.assert_stable(source, actual, DEFAULT_MODE)
 
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_expression(self) -> None:
-        source, expected = read_data("expression")
-        actual = fs(source)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
     @patch("black.dump_to_file", dump_to_stderr)
     def test_pep_572(self) -> None:
         source, expected = read_data("pep_572")
@@ -434,14 +329,6 @@ def test_expression_diff_with_color(self) -> None:
         self.assertIn("\033[31m", actual)
         self.assertIn("\033[0m", actual)
 
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_fstring(self) -> None:
-        source, expected = read_data("fstring")
-        actual = fs(source)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
     @patch("black.dump_to_file", dump_to_stderr)
     def test_pep_570(self) -> None:
         source, expected = read_data("pep_570")
@@ -472,14 +359,6 @@ def test_string_quotes(self) -> None:
         black.assert_equivalent(source, not_normalized)
         black.assert_stable(source, not_normalized, mode=mode)
 
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_docstring(self) -> None:
-        source, expected = read_data("docstring")
-        actual = fs(source)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
     @patch("black.dump_to_file", dump_to_stderr)
     def test_docstring_no_string_normalization(self) -> None:
         """Like test_docstring but with string normalization off."""
@@ -490,14 +369,6 @@ def test_docstring_no_string_normalization(self) -> None:
         black.assert_equivalent(source, actual)
         black.assert_stable(source, actual, mode)
 
-    def test_long_strings(self) -> None:
-        """Tests for splitting long strings."""
-        source, expected = read_data("long_strings")
-        actual = fs(source)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
     def test_long_strings_flag_disabled(self) -> None:
         """Tests for turning off the string processing logic."""
         source, expected = read_data("long_strings_flag_disabled")
@@ -506,162 +377,6 @@ def test_long_strings_flag_disabled(self) -> None:
         self.assertFormatEqual(expected, actual)
         black.assert_stable(expected, actual, mode)
 
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_long_strings__edge_case(self) -> None:
-        """Edge-case tests for splitting long strings."""
-        source, expected = read_data("long_strings__edge_case")
-        actual = fs(source)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_long_strings__regression(self) -> None:
-        """Regression tests for splitting long strings."""
-        source, expected = read_data("long_strings__regression")
-        actual = fs(source)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_slices(self) -> None:
-        source, expected = read_data("slices")
-        actual = fs(source)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_percent_precedence(self) -> None:
-        source, expected = read_data("percent_precedence")
-        actual = fs(source)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_comments(self) -> None:
-        source, expected = read_data("comments")
-        actual = fs(source)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_comments2(self) -> None:
-        source, expected = read_data("comments2")
-        actual = fs(source)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_comments3(self) -> None:
-        source, expected = read_data("comments3")
-        actual = fs(source)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_comments4(self) -> None:
-        source, expected = read_data("comments4")
-        actual = fs(source)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_comments5(self) -> None:
-        source, expected = read_data("comments5")
-        actual = fs(source)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_comments6(self) -> None:
-        source, expected = read_data("comments6")
-        actual = fs(source)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_comments7(self) -> None:
-        source, expected = read_data("comments7")
-        mode = replace(DEFAULT_MODE, target_versions={black.TargetVersion.PY38})
-        actual = fs(source, mode=mode)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_comment_after_escaped_newline(self) -> None:
-        source, expected = read_data("comment_after_escaped_newline")
-        actual = fs(source)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_cantfit(self) -> None:
-        source, expected = read_data("cantfit")
-        actual = fs(source)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_import_spacing(self) -> None:
-        source, expected = read_data("import_spacing")
-        actual = fs(source)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_composition(self) -> None:
-        source, expected = read_data("composition")
-        actual = fs(source)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_composition_no_trailing_comma(self) -> None:
-        source, expected = read_data("composition_no_trailing_comma")
-        mode = replace(DEFAULT_MODE, target_versions={black.TargetVersion.PY38})
-        actual = fs(source, mode=mode)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_empty_lines(self) -> None:
-        source, expected = read_data("empty_lines")
-        actual = fs(source)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_remove_parens(self) -> None:
-        source, expected = read_data("remove_parens")
-        actual = fs(source)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_string_prefixes(self) -> None:
-        source, expected = read_data("string_prefixes")
-        actual = fs(source)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
     @patch("black.dump_to_file", dump_to_stderr)
     def test_numeric_literals(self) -> None:
         source, expected = read_data("numeric_literals")
@@ -680,21 +395,6 @@ def test_numeric_literals_ignoring_underscores(self) -> None:
         black.assert_equivalent(source, actual)
         black.assert_stable(source, actual, mode)
 
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_numeric_literals_py2(self) -> None:
-        source, expected = read_data("numeric_literals_py2")
-        actual = fs(source)
-        self.assertFormatEqual(expected, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_python2(self) -> None:
-        source, expected = read_data("python2")
-        actual = fs(source)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
     @patch("black.dump_to_file", dump_to_stderr)
     def test_python2_print_function(self) -> None:
         source, expected = read_data("python2_print_function")
@@ -704,14 +404,6 @@ def test_python2_print_function(self) -> None:
         black.assert_equivalent(source, actual)
         black.assert_stable(source, actual, mode)
 
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_python2_unicode_literals(self) -> None:
-        source, expected = read_data("python2_unicode_literals")
-        actual = fs(source)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
     @patch("black.dump_to_file", dump_to_stderr)
     def test_stub(self) -> None:
         mode = replace(DEFAULT_MODE, is_pyi=True)
@@ -770,78 +462,6 @@ def test_python39(self) -> None:
             black.assert_equivalent(source, actual)
         black.assert_stable(source, actual, DEFAULT_MODE)
 
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_fmtonoff(self) -> None:
-        source, expected = read_data("fmtonoff")
-        actual = fs(source)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_fmtonoff2(self) -> None:
-        source, expected = read_data("fmtonoff2")
-        actual = fs(source)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_fmtonoff3(self) -> None:
-        source, expected = read_data("fmtonoff3")
-        actual = fs(source)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_fmtonoff4(self) -> None:
-        source, expected = read_data("fmtonoff4")
-        actual = fs(source)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_remove_empty_parentheses_after_class(self) -> None:
-        source, expected = read_data("class_blank_parentheses")
-        actual = fs(source)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_new_line_between_class_and_code(self) -> None:
-        source, expected = read_data("class_methods_new_line")
-        actual = fs(source)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_bracket_match(self) -> None:
-        source, expected = read_data("bracketmatch")
-        actual = fs(source)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_tuple_assign(self) -> None:
-        source, expected = read_data("tupleassign")
-        actual = fs(source)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_beginning_backslash(self) -> None:
-        source, expected = read_data("beginning_backslash")
-        actual = fs(source)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
     def test_tab_comment_indentation(self) -> None:
         contents_tab = "if 1:\n\tif 2:\n\t\tpass\n\t# comment\n\tpass\n"
         contents_spc = "if 1:\n    if 2:\n        pass\n    # comment\n    pass\n"
@@ -1569,13 +1189,6 @@ def test_read_cache_line_lengths(self) -> None:
             two = black.read_cache(short_mode)
             self.assertNotIn(path, two)
 
-    def test_tricky_unicode_symbols(self) -> None:
-        source, expected = read_data("tricky_unicode_symbols")
-        actual = fs(source)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
     def test_single_file_force_pyi(self) -> None:
         pyi_mode = replace(DEFAULT_MODE, is_pyi=True)
         contents, expected = read_data("force_pyi")
@@ -1672,13 +1285,6 @@ def test_multi_file_force_py36(self) -> None:
                 self.assertIn(path, pyi_cache)
                 self.assertNotIn(path, normal_cache)
 
-    def test_collections(self) -> None:
-        source, expected = read_data("collections")
-        actual = fs(source)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
     def test_pipe_force_py36(self) -> None:
         source, expected = read_data("force_py36")
         result = CliRunner().invoke(
diff --git a/tests/test_format.py b/tests/test_format.py
new file mode 100644
index 00000000000..e4677707e3c
--- /dev/null
+++ b/tests/test_format.py
@@ -0,0 +1,98 @@
+from unittest.mock import patch
+
+import black
+from parameterized import parameterized
+
+from tests.util import (
+    BlackBaseTestCase,
+    fs,
+    ff,
+    DEFAULT_MODE,
+    dump_to_stderr,
+    read_data,
+    THIS_DIR,
+)
+
+SIMPLE_CASES = [
+    "beginning_backslash",
+    "bracketmatch",
+    "cantfit",
+    "class_blank_parentheses",
+    "class_methods_new_line",
+    "collections",
+    "comments",
+    "comments2",
+    "comments3",
+    "comments4",
+    "comments5",
+    "comments6",
+    "comments7",
+    "comment_after_escaped_newline",
+    "composition",
+    "composition_no_trailing_comma",
+    "docstring",
+    "empty_lines",
+    "expression",
+    "fmtonoff",
+    "fmtonoff2",
+    "fmtonoff3",
+    "fmtonoff4",
+    "fstring",
+    "function",
+    "function2",
+    "function_trailing_comma",
+    "import_spacing",
+    "long_strings",
+    "long_strings__edge_case",
+    "long_strings__regression",
+    "numeric_literals_py2",
+    "percent_precedence",
+    "python2",
+    "python2_unicode_literals",
+    "remove_parens",
+    "slices",
+    "string_prefixes",
+    "tricky_unicode_symbols",
+    "tupleassign",
+]
+
+
+SOURCES = [
+    "tests/test_black.py",
+    "tests/test_format.py",
+    "tests/test_blackd.py",
+    "src/black/__init__.py",
+    "src/blib2to3/pygram.py",
+    "src/blib2to3/pytree.py",
+    "src/blib2to3/pgen2/conv.py",
+    "src/blib2to3/pgen2/driver.py",
+    "src/blib2to3/pgen2/grammar.py",
+    "src/blib2to3/pgen2/literals.py",
+    "src/blib2to3/pgen2/parse.py",
+    "src/blib2to3/pgen2/pgen.py",
+    "src/blib2to3/pgen2/tokenize.py",
+    "src/blib2to3/pgen2/token.py",
+    "setup.py",
+]
+
+
+class TestSimpleFormat(BlackBaseTestCase):
+    @parameterized.expand(SIMPLE_CASES)
+    @patch("black.dump_to_file", dump_to_stderr)
+    def test_simple_format(self, filename: str) -> None:
+        source, expected = read_data(filename)
+        actual = fs(source)
+        self.assertFormatEqual(expected, actual)
+        black.assert_equivalent(source, actual)
+        black.assert_stable(source, actual, DEFAULT_MODE)
+
+    @parameterized.expand(SOURCES)
+    @patch("black.dump_to_file", dump_to_stderr)
+    def test_source_is_formatted(self, filename: str) -> None:
+        path = THIS_DIR.parent / filename
+        source, expected = read_data(str(path), data=False)
+        actual = fs(source, mode=DEFAULT_MODE)
+        self.assertFormatEqual(expected, actual)
+        black.assert_equivalent(source, actual)
+        black.assert_stable(source, actual, DEFAULT_MODE)
+        self.assertFalse(ff(path))
diff --git a/tests/util.py b/tests/util.py
index 9c3d3cbc99d..da65ed0cc93 100644
--- a/tests/util.py
+++ b/tests/util.py
@@ -1,7 +1,10 @@
+import os
 import unittest
 from contextlib import contextmanager
 from pathlib import Path
-from typing import List, Tuple, Iterator
+from typing import List, Tuple, Iterator, Any
+import black
+from functools import partial
 
 THIS_DIR = Path(__file__).parent
 PROJECT_ROOT = THIS_DIR.parent
@@ -9,6 +12,39 @@
 DETERMINISTIC_HEADER = "[Deterministic header]"
 
 
+DEFAULT_MODE = black.FileMode(experimental_string_processing=True)
+ff = partial(black.format_file_in_place, mode=DEFAULT_MODE, fast=True)
+fs = partial(black.format_str, mode=DEFAULT_MODE)
+
+
+def dump_to_stderr(*output: str) -> str:
+    return "\n" + "\n".join(output) + "\n"
+
+
+class BlackBaseTestCase(unittest.TestCase):
+    maxDiff = None
+    _diffThreshold = 2 ** 20
+
+    def assertFormatEqual(self, expected: str, actual: str) -> None:
+        if actual != expected and not os.environ.get("SKIP_AST_PRINT"):
+            bdv: black.DebugVisitor[Any]
+            black.out("Expected tree:", fg="green")
+            try:
+                exp_node = black.lib2to3_parse(expected)
+                bdv = black.DebugVisitor()
+                list(bdv.visit(exp_node))
+            except Exception as ve:
+                black.err(str(ve))
+            black.out("Actual tree:", fg="red")
+            try:
+                exp_node = black.lib2to3_parse(actual)
+                bdv = black.DebugVisitor()
+                list(bdv.visit(exp_node))
+            except Exception as ve:
+                black.err(str(ve))
+        self.assertMultiLineEqual(expected, actual)
+
+
 @contextmanager
 def skip_if_exception(e: str) -> Iterator[None]:
     try:
@@ -24,11 +60,15 @@ def read_data(name: str, data: bool = True) -> Tuple[str, str]:
     """read_data('test_name') -> 'input', 'output'"""
     if not name.endswith((".py", ".pyi", ".out", ".diff")):
         name += ".py"
-    _input: List[str] = []
-    _output: List[str] = []
     base_dir = THIS_DIR / "data" if data else PROJECT_ROOT
-    with open(base_dir / name, "r", encoding="utf8") as test:
+    return read_data_from_file(base_dir / name)
+
+
+def read_data_from_file(file_name: Path) -> Tuple[str, str]:
+    with open(file_name, "r", encoding="utf8") as test:
         lines = test.readlines()
+    _input: List[str] = []
+    _output: List[str] = []
     result = _input
     for line in lines:
         line = line.replace(EMPTY_LINE, "")

From b64fd2bbec420ff71f7592f40816ae7de2fa4a15 Mon Sep 17 00:00:00 2001
From: Shota Ray Imaki <shota.imaki@icloud.com>
Date: Sat, 31 Oct 2020 00:13:55 +0900
Subject: [PATCH 0040/1034] Add compatible configuration files. (psf#1789)
 (#1792)

* Add compatible configuration files. (psf#1789)

* Simplify isort configuration files. (#1789)
---
 docs/compatible_configs.md                    | 3 +++
 docs/compatible_configs/flake8/.flake8        | 3 +++
 docs/compatible_configs/flake8/setup.cfg      | 3 +++
 docs/compatible_configs/flake8/tox.ini        | 3 +++
 docs/compatible_configs/isort/.editorconfig   | 2 ++
 docs/compatible_configs/isort/.isort.cfg      | 2 ++
 docs/compatible_configs/isort/pyproject.toml  | 2 ++
 docs/compatible_configs/isort/setup.cfg       | 2 ++
 docs/compatible_configs/pylint/pylintrc       | 5 +++++
 docs/compatible_configs/pylint/pyproject.toml | 5 +++++
 docs/compatible_configs/pylint/setup.cfg      | 5 +++++
 11 files changed, 35 insertions(+)
 create mode 100644 docs/compatible_configs/flake8/.flake8
 create mode 100644 docs/compatible_configs/flake8/setup.cfg
 create mode 100644 docs/compatible_configs/flake8/tox.ini
 create mode 100644 docs/compatible_configs/isort/.editorconfig
 create mode 100644 docs/compatible_configs/isort/.isort.cfg
 create mode 100644 docs/compatible_configs/isort/pyproject.toml
 create mode 100644 docs/compatible_configs/isort/setup.cfg
 create mode 100644 docs/compatible_configs/pylint/pylintrc
 create mode 100644 docs/compatible_configs/pylint/pyproject.toml
 create mode 100644 docs/compatible_configs/pylint/setup.cfg

diff --git a/docs/compatible_configs.md b/docs/compatible_configs.md
index 990820a6771..c6724e77e57 100644
--- a/docs/compatible_configs.md
+++ b/docs/compatible_configs.md
@@ -10,6 +10,9 @@ tools out there.
 (e.g. `pyproject.toml`). The provided examples are to only configure their corresponding
 tools, using **their** supported file formats.
 
+Compatible configuration files can be
+[found here](https://github.com/psf/black/blob/master/docs/compatible_configs/).
+
 ## isort
 
 [isort](https://pypi.org/p/isort/) helps to sort and format imports in your Python code.
diff --git a/docs/compatible_configs/flake8/.flake8 b/docs/compatible_configs/flake8/.flake8
new file mode 100644
index 00000000000..8dd399ab55b
--- /dev/null
+++ b/docs/compatible_configs/flake8/.flake8
@@ -0,0 +1,3 @@
+[flake8]
+max-line-length = 88
+extend-ignore = E203
diff --git a/docs/compatible_configs/flake8/setup.cfg b/docs/compatible_configs/flake8/setup.cfg
new file mode 100644
index 00000000000..8dd399ab55b
--- /dev/null
+++ b/docs/compatible_configs/flake8/setup.cfg
@@ -0,0 +1,3 @@
+[flake8]
+max-line-length = 88
+extend-ignore = E203
diff --git a/docs/compatible_configs/flake8/tox.ini b/docs/compatible_configs/flake8/tox.ini
new file mode 100644
index 00000000000..8dd399ab55b
--- /dev/null
+++ b/docs/compatible_configs/flake8/tox.ini
@@ -0,0 +1,3 @@
+[flake8]
+max-line-length = 88
+extend-ignore = E203
diff --git a/docs/compatible_configs/isort/.editorconfig b/docs/compatible_configs/isort/.editorconfig
new file mode 100644
index 00000000000..edc849a54a6
--- /dev/null
+++ b/docs/compatible_configs/isort/.editorconfig
@@ -0,0 +1,2 @@
+[*.py]
+profile = black
diff --git a/docs/compatible_configs/isort/.isort.cfg b/docs/compatible_configs/isort/.isort.cfg
new file mode 100644
index 00000000000..f238bf7ea13
--- /dev/null
+++ b/docs/compatible_configs/isort/.isort.cfg
@@ -0,0 +1,2 @@
+[settings]
+profile = black
diff --git a/docs/compatible_configs/isort/pyproject.toml b/docs/compatible_configs/isort/pyproject.toml
new file mode 100644
index 00000000000..cea9915bebf
--- /dev/null
+++ b/docs/compatible_configs/isort/pyproject.toml
@@ -0,0 +1,2 @@
+[tool.isort]
+profile = black
diff --git a/docs/compatible_configs/isort/setup.cfg b/docs/compatible_configs/isort/setup.cfg
new file mode 100644
index 00000000000..c76db01ff4e
--- /dev/null
+++ b/docs/compatible_configs/isort/setup.cfg
@@ -0,0 +1,2 @@
+[isort]
+profile = black
diff --git a/docs/compatible_configs/pylint/pylintrc b/docs/compatible_configs/pylint/pylintrc
new file mode 100644
index 00000000000..7abddd2c330
--- /dev/null
+++ b/docs/compatible_configs/pylint/pylintrc
@@ -0,0 +1,5 @@
+[MESSAGES CONTROL]
+disable = C0330, C0326
+
+[format]
+max-line-length = 88
diff --git a/docs/compatible_configs/pylint/pyproject.toml b/docs/compatible_configs/pylint/pyproject.toml
new file mode 100644
index 00000000000..49ad7a2c771
--- /dev/null
+++ b/docs/compatible_configs/pylint/pyproject.toml
@@ -0,0 +1,5 @@
+[tool.pylint.messages_control]
+disable = "C0330, C0326"
+
+[tool.pylint.format]
+max-line-length = "88"
diff --git a/docs/compatible_configs/pylint/setup.cfg b/docs/compatible_configs/pylint/setup.cfg
new file mode 100644
index 00000000000..3ada24530ea
--- /dev/null
+++ b/docs/compatible_configs/pylint/setup.cfg
@@ -0,0 +1,5 @@
+[pylint]
+max-line-length = 88
+
+[pylint.messages_control]
+disable = C0330, C0326

From 5d978df8b54d4fb102142508353a04932a4b5b04 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Fri, 30 Oct 2020 08:15:09 -0700
Subject: [PATCH 0041/1034] Bump cryptography from 3.1 to 3.2 (#1791)

Bumps [cryptography](https://github.com/pyca/cryptography) from 3.1 to 3.2.
- [Release notes](https://github.com/pyca/cryptography/releases)
- [Changelog](https://github.com/pyca/cryptography/blob/master/CHANGELOG.rst)
- [Commits](https://github.com/pyca/cryptography/compare/3.1...3.2)

Signed-off-by: dependabot[bot] <support@github.com>

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 Pipfile.lock | 355 +++++++++++++++++++++++++--------------------------
 1 file changed, 172 insertions(+), 183 deletions(-)

diff --git a/Pipfile.lock b/Pipfile.lock
index e09d69ea83d..95b7613114a 100644
--- a/Pipfile.lock
+++ b/Pipfile.lock
@@ -53,7 +53,6 @@
                 "sha256:0c3c816a028d47f659d6ff5c745cb2acf1f966da1fe5c19c77a70282b25f4c5f",
                 "sha256:4291ca197d287d274d0b6cb5d6f8f8f82d434ed288f962539ff18cc9012f9ea3"
             ],
-            "markers": "python_full_version >= '3.5.3'",
             "version": "==3.0.1"
         },
         "attrs": {
@@ -61,7 +60,6 @@
                 "sha256:26b54ddbbb9ee1d34d5d3668dd37d6cf74990ab23c828c2888dccdceee395594",
                 "sha256:fce7fc47dfc976152e82d53ff92fa0407700c21acd20886a13777a0d20e655dc"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==20.2.0"
         },
         "black": {
@@ -92,16 +90,13 @@
                 "sha256:6988bd2b895eef432d562370bb707d540f32f7360ab13da45340101bc2307d84"
             ],
             "index": "pypi",
-            "python_version <": "3.7",
-            "version": "==0.6",
-            "version >": "0.6"
+            "version": "==0.6"
         },
         "idna": {
             "hashes": [
                 "sha256:b307872f855b18632ce0c21c5e45be78c0ea7ae4c15c828c20788b26921eb3f6",
                 "sha256:b97d804b1e9b523befed77c48dacec60e6dcb0b5391d57af6a65a312a90648c0"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==2.10"
         },
         "multidict": {
@@ -124,7 +119,6 @@
                 "sha256:fcfbb44c59af3f8ea984de67ec7c306f618a3ec771c2843804069917a8f2e255",
                 "sha256:feed85993dbdb1dbc29102f50bca65bdc68f2c0c8d352468c25b54874f23c39d"
             ],
-            "markers": "python_version >= '3.5'",
             "version": "==4.7.6"
         },
         "mypy-extensions": {
@@ -170,26 +164,10 @@
             "index": "pypi",
             "version": "==2020.7.14"
         },
-        "setuptools-scm": {
-            "hashes": [
-                "sha256:09c659d1d6680811c43f476a33c6d3d9872416580786e96bd29ea03e6a818e41",
-                "sha256:69258e2eeba5f7ce1ed7a5f109519580fa3578250f8e4d6684859f86d1b15826",
-                "sha256:731550a27e3901ee501c3bf99140b5436b8eeba341a9d19911cf364b8d573293",
-                "sha256:892e63b4983f9e30f9e8bf89ad03d2a02a47e6e5ced09b03ae6fe952ade8a579",
-                "sha256:a8994582e716ec690f33fec70cca0f85bd23ec974e3f783233e4879090a7faa8",
-                "sha256:b42c150c34d6120babf3646abd7513e032be2e230b3d2034f27404c65aa0c977",
-                "sha256:eaaec16b7af25c5f532b5af2332213bb6223d15cca4518f6dbc4c055641c86fd",
-                "sha256:efc928d6a64162c88cdc85fa4b84adfbd6dbf9f9b04319bc495eb16dcfaae00a"
-            ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
-            "version": "==4.1.2"
-        },
         "toml": {
             "hashes": [
-                "sha256:235682dd292d5899d361a811df37e04a8828a5b1da3115886b73cf81ebc9100e",
-                "sha256:bda89d5935c2eac546d648028b9901107a595863cb36bae0c73ac804a9b4ce88",
                 "sha256:926b612be1e5ce0634a2ca03470f95169cf16f939018233a670519cb4ac58b0f",
-                "sha256:229f81c57791a41d65e399fc06bf0848bab550a9dfd5ed66df18ce5f05e73d5c"
+                "sha256:bda89d5935c2eac546d648028b9901107a595863cb36bae0c73ac804a9b4ce88"
             ],
             "index": "pypi",
             "version": "==0.10.1"
@@ -198,9 +176,11 @@
             "hashes": [
                 "sha256:0666aa36131496aed8f7be0410ff974562ab7eeac11ef351def9ea6fa28f6355",
                 "sha256:0c2c07682d61a629b68433afb159376e24e5b2fd4641d35424e462169c0a7919",
+                "sha256:0d8110d78a5736e16e26213114a38ca35cb15b6515d535413b090bd50951556d",
                 "sha256:249862707802d40f7f29f6e1aad8d84b5aa9e44552d2cc17384b209f091276aa",
                 "sha256:24995c843eb0ad11a4527b026b4dde3da70e1f2d8806c99b7b4a7cf491612652",
                 "sha256:269151951236b0f9a6f04015a9004084a5ab0d5f19b57de779f908621e7d8b75",
+                "sha256:3742b32cf1c6ef124d57f95be609c473d7ec4c14d0090e5a5e05a15269fb4d0c",
                 "sha256:4083861b0aa07990b619bd7ddc365eb7fa4b817e99cf5f8d9cf21a42780f6e01",
                 "sha256:498b0f36cc7054c1fead3d7fc59d2150f4d5c6c56ba7fb150c013fbc683a8d2d",
                 "sha256:4e3e5da80ccbebfff202a67bf900d081906c358ccc3d5e3c8aea42fdfdfd51c1",
@@ -209,12 +189,16 @@
                 "sha256:73d785a950fc82dd2a25897d525d003f6378d1cb23ab305578394694202a58c3",
                 "sha256:8c8aaad94455178e3187ab22c8b01a3837f8ee50e09cf31f1ba129eb293ec30b",
                 "sha256:8ce678dbaf790dbdb3eba24056d5364fb45944f33553dd5869b7580cdbb83614",
+                "sha256:92c325624e304ebf0e025d1224b77dd4e6393f18aab8d829b5b7e04afe9b7a2c",
                 "sha256:aaee9905aee35ba5905cfb3c62f3e83b3bec7b39413f0a7f19be4e547ea01ebb",
+                "sha256:b52ccf7cfe4ce2a1064b18594381bccf4179c2ecf7f513134ec2f993dd4ab395",
                 "sha256:bcd3b13b56ea479b3650b82cabd6b5343a625b0ced5429e4ccad28a8973f301b",
                 "sha256:c9e348e02e4d2b4a8b2eedb48210430658df6951fa484e59de33ff773fbd4b41",
                 "sha256:d205b1b46085271b4e15f670058ce182bd1199e56b317bf2ec004b6a44f911f6",
                 "sha256:d43943ef777f9a1c42bf4e552ba23ac77a6351de620aa9acf64ad54933ad4d34",
                 "sha256:d5d33e9e7af3b34a40dc05f498939f0ebf187f07c385fd58d591c533ad8562fe",
+                "sha256:d648b8e3bf2fe648745c8ffcee3db3ff903d0817a01a12dd6a6ea7a8f4889072",
+                "sha256:fac11badff8313e23717f3dada86a15389d0708275bddf766cca67a84ead3e91",
                 "sha256:fc0fea399acb12edbf8a628ba8d2312f583bdbdb3335635db062fa98cf71fca4",
                 "sha256:fe460b922ec15dd205595c9b5b99e2f056fd98ae8f9f56b888e7a17dc2b757e7"
             ],
@@ -232,26 +216,41 @@
         },
         "yarl": {
             "hashes": [
-                "sha256:040b237f58ff7d800e6e0fd89c8439b841f777dd99b4a9cca04d6935564b9409",
-                "sha256:17668ec6722b1b7a3a05cc0167659f6c95b436d25a36c2d52db0eca7d3f72593",
-                "sha256:3a584b28086bc93c888a6c2aa5c92ed1ae20932f078c46509a66dce9ea5533f2",
-                "sha256:4439be27e4eee76c7632c2427ca5e73703151b22cae23e64adb243a9c2f565d8",
-                "sha256:48e918b05850fffb070a496d2b5f97fc31d15d94ca33d3d08a4f86e26d4e7c5d",
-                "sha256:9102b59e8337f9874638fcfc9ac3734a0cfadb100e47d55c20d0dc6087fb4692",
-                "sha256:9b930776c0ae0c691776f4d2891ebc5362af86f152dd0da463a6614074cb1b02",
-                "sha256:b3b9ad80f8b68519cc3372a6ca85ae02cc5a8807723ac366b53c0f089db19e4a",
-                "sha256:bc2f976c0e918659f723401c4f834deb8a8e7798a71be4382e024bcc3f7e23a8",
-                "sha256:c22c75b5f394f3d47105045ea551e08a3e804dc7e01b37800ca35b58f856c3d6",
-                "sha256:c52ce2883dc193824989a9b97a76ca86ecd1fa7955b14f87bf367a61b6232511",
-                "sha256:ce584af5de8830d8701b8979b18fcf450cef9a382b1a3c8ef189bedc408faf1e",
-                "sha256:da456eeec17fa8aa4594d9a9f27c0b1060b6a75f2419fe0c00609587b2695f4a",
-                "sha256:db6db0f45d2c63ddb1a9d18d1b9b22f308e52c83638c26b422d520a815c4b3fb",
-                "sha256:df89642981b94e7db5596818499c4b2219028f2a528c9c37cc1de45bf2fd3a3f",
-                "sha256:f18d68f2be6bf0e89f1521af2b1bb46e66ab0018faafa81d70f358153170a317",
-                "sha256:f379b7f83f23fe12823085cd6b906edc49df969eb99757f58ff382349a3303c6"
-            ],
-            "markers": "python_version >= '3.5'",
-            "version": "==1.5.1"
+                "sha256:03b7a44384ad60be1b7be93c2a24dc74895f8d767ea0bce15b2f6fc7695a3843",
+                "sha256:076157404db9db4bb3fa9db22db319bbb36d075eeab19ba018ce20ae0cacf037",
+                "sha256:1c05ae3d5ea4287470046a2c2754f0a4c171b84ea72c8a691f776eb1753dfb91",
+                "sha256:2467baf8233f7c64048df37e11879c553943ffe7f373e689711ec2807ea13805",
+                "sha256:2bb2e21cf062dfbe985c3cd4618bae9f25271efcad9e7be1277861247eee9839",
+                "sha256:311effab3b3828ab34f0e661bb57ff422f67d5c33056298bda4c12195251f8dd",
+                "sha256:3526cb5905907f0e42bee7ef57ae4a5f02bc27dcac27859269e2bba0caa4c2b6",
+                "sha256:39b1e586f34b1d2512c9b39aa3cf24c870c972d525e36edc9ee19065db4737bb",
+                "sha256:4bed5cd7c8e69551eb19df15295ba90e62b9a6a1149c76eb4a9bab194402a156",
+                "sha256:51c6d3cf7a1f1fbe134bb92f33b7affd94d6de24cd64b466eb12de52120fb8c6",
+                "sha256:59f78b5da34ddcffb663b772f7619e296518712e022e57fc5d9f921818e2ab7c",
+                "sha256:6f29115b0c330da25a04f48612d75333bca04521181a666ca0b8761005a99150",
+                "sha256:73d4e1e1ef5e52d526c92f07d16329e1678612c6a81dd8101fdcae11a72de15c",
+                "sha256:9b48d31f8d881713fd461abfe7acbb4dcfeb47cec3056aa83f2fbcd2244577f7",
+                "sha256:a1fd575dd058e10ad4c35065e7c3007cc74d142f622b14e168d8a273a2fa8713",
+                "sha256:b3dd1052afd436ba737e61f5d3bed1f43a7f9a33fc58fbe4226eb919a7006019",
+                "sha256:b99c25ed5c355b35d1e6dae87ac7297a4844a57dc5766b173b88b6163a36eb0d",
+                "sha256:c056e86bff5a0b566e0d9fab4f67e83b12ae9cbcd250d334cbe2005bbe8c96f2",
+                "sha256:c45b49b59a5724869899798e1bbd447ac486215269511d3b76b4c235a1b766b6",
+                "sha256:cd623170c729a865037828e3f99f8ebdb22a467177a539680dfc5670b74c84e2",
+                "sha256:d25d3311794e6c71b608d7c47651c8f65eea5ab15358a27f29330b3475e8f8e5",
+                "sha256:d695439c201ed340745250f9eb4dfe8d32bf1e680c16477107b8f3ce4bff4fdb",
+                "sha256:d77f6c9133d2aabb290a7846aaa74ec14d7b5ab35b01591fac5a70c4a8c959a2",
+                "sha256:d894a2442d2cd20a3b0b0dce5a353d316c57d25a2b445e03f7eac90eee27b8af",
+                "sha256:db643ce2b58a4bd11a82348225c53c76ecdd82bb37cf4c085e6df1b676f4038c",
+                "sha256:e3a0c43a26dfed955b2a06fdc4d51d2c51bc2200aff8ce8faf14e676ea8c8862",
+                "sha256:e77bf79ad1ccae672eab22453838382fe9029fc27c8029e84913855512a587d8",
+                "sha256:f2f0174cb15435957d3b751093f89aede77df59a499ab7516bbb633b77ead13a",
+                "sha256:f3031c78edf10315abe232254e6a36b65afe65fded41ee54ed7976d0b2cdf0da",
+                "sha256:f4c007156732866aa4507d619fe6f8f2748caabed4f66b276ccd97c82572620c",
+                "sha256:f4f27ff3dd80bc7c402def211a47291ea123d59a23f59fe18fc0e81e3e71f385",
+                "sha256:f57744fc61e118b5d114ae8077d8eb9df4d2d2c11e2af194e21f0c11ed9dcf6c",
+                "sha256:f835015a825980b65356e9520979a1564c56efea7da7d4b68a14d4a07a3a7336"
+            ],
+            "version": "==1.6.2"
         }
     },
     "develop": {
@@ -301,7 +300,6 @@
                 "sha256:0c3c816a028d47f659d6ff5c745cb2acf1f966da1fe5c19c77a70282b25f4c5f",
                 "sha256:4291ca197d287d274d0b6cb5d6f8f8f82d434ed288f962539ff18cc9012f9ea3"
             ],
-            "markers": "python_full_version >= '3.5.3'",
             "version": "==3.0.1"
         },
         "attrs": {
@@ -309,7 +307,6 @@
                 "sha256:26b54ddbbb9ee1d34d5d3668dd37d6cf74990ab23c828c2888dccdceee395594",
                 "sha256:fce7fc47dfc976152e82d53ff92fa0407700c21acd20886a13777a0d20e655dc"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==20.2.0"
         },
         "babel": {
@@ -317,7 +314,6 @@
                 "sha256:1aac2ae2d0d8ea368fa90906567f5c08463d98ade155c0c4bfedd6a0f7160e38",
                 "sha256:d670ea0b10f8b723672d3a6abeb87b565b244da220d76b4dba1b66269ec152d4"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==2.8.0"
         },
         "black": {
@@ -332,7 +328,6 @@
                 "sha256:52b5919b81842b1854196eaae5ca29679a2f2e378905c346d3ca8227c2c66080",
                 "sha256:9f8ccbeb6183c6e6cddea37592dfb0167485c1e3b13b3363bc325aa8bda3adbd"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
             "version": "==3.2.1"
         },
         "certifi": {
@@ -344,43 +339,50 @@
         },
         "cffi": {
             "hashes": [
-                "sha256:0da50dcbccd7cb7e6c741ab7912b2eff48e85af217d72b57f80ebc616257125e",
-                "sha256:12a453e03124069b6896107ee133ae3ab04c624bb10683e1ed1c1663df17c13c",
-                "sha256:15419020b0e812b40d96ec9d369b2bc8109cc3295eac6e013d3261343580cc7e",
-                "sha256:15a5f59a4808f82d8ec7364cbace851df591c2d43bc76bcbe5c4543a7ddd1bf1",
-                "sha256:23e44937d7695c27c66a54d793dd4b45889a81b35c0751ba91040fe825ec59c4",
-                "sha256:29c4688ace466a365b85a51dcc5e3c853c1d283f293dfcc12f7a77e498f160d2",
-                "sha256:57214fa5430399dffd54f4be37b56fe22cedb2b98862550d43cc085fb698dc2c",
-                "sha256:577791f948d34d569acb2d1add5831731c59d5a0c50a6d9f629ae1cefd9ca4a0",
-                "sha256:6539314d84c4d36f28d73adc1b45e9f4ee2a89cdc7e5d2b0a6dbacba31906798",
-                "sha256:65867d63f0fd1b500fa343d7798fa64e9e681b594e0a07dc934c13e76ee28fb1",
-                "sha256:672b539db20fef6b03d6f7a14b5825d57c98e4026401fce838849f8de73fe4d4",
-                "sha256:6843db0343e12e3f52cc58430ad559d850a53684f5b352540ca3f1bc56df0731",
-                "sha256:7057613efefd36cacabbdbcef010e0a9c20a88fc07eb3e616019ea1692fa5df4",
-                "sha256:76ada88d62eb24de7051c5157a1a78fd853cca9b91c0713c2e973e4196271d0c",
-                "sha256:837398c2ec00228679513802e3744d1e8e3cb1204aa6ad408b6aff081e99a487",
-                "sha256:8662aabfeab00cea149a3d1c2999b0731e70c6b5bac596d95d13f643e76d3d4e",
-                "sha256:95e9094162fa712f18b4f60896e34b621df99147c2cee216cfa8f022294e8e9f",
-                "sha256:99cc66b33c418cd579c0f03b77b94263c305c389cb0c6972dac420f24b3bf123",
-                "sha256:9b219511d8b64d3fa14261963933be34028ea0e57455baf6781fe399c2c3206c",
-                "sha256:ae8f34d50af2c2154035984b8b5fc5d9ed63f32fe615646ab435b05b132ca91b",
-                "sha256:b9aa9d8818c2e917fa2c105ad538e222a5bce59777133840b93134022a7ce650",
-                "sha256:bf44a9a0141a082e89c90e8d785b212a872db793a0080c20f6ae6e2a0ebf82ad",
-                "sha256:c0b48b98d79cf795b0916c57bebbc6d16bb43b9fc9b8c9f57f4cf05881904c75",
-                "sha256:da9d3c506f43e220336433dffe643fbfa40096d408cb9b7f2477892f369d5f82",
-                "sha256:e4082d832e36e7f9b2278bc774886ca8207346b99f278e54c9de4834f17232f7",
-                "sha256:e4b9b7af398c32e408c00eb4e0d33ced2f9121fd9fb978e6c1b57edd014a7d15",
-                "sha256:e613514a82539fc48291d01933951a13ae93b6b444a88782480be32245ed4afa",
-                "sha256:f5033952def24172e60493b68717792e3aebb387a8d186c43c020d9363ee7281"
-            ],
-            "version": "==1.14.2"
+                "sha256:005f2bfe11b6745d726dbb07ace4d53f057de66e336ff92d61b8c7e9c8f4777d",
+                "sha256:09e96138280241bd355cd585148dec04dbbedb4f46128f340d696eaafc82dd7b",
+                "sha256:0b1ad452cc824665ddc682400b62c9e4f5b64736a2ba99110712fdee5f2505c4",
+                "sha256:0ef488305fdce2580c8b2708f22d7785ae222d9825d3094ab073e22e93dfe51f",
+                "sha256:15f351bed09897fbda218e4db5a3d5c06328862f6198d4fb385f3e14e19decb3",
+                "sha256:22399ff4870fb4c7ef19fff6eeb20a8bbf15571913c181c78cb361024d574579",
+                "sha256:23e5d2040367322824605bc29ae8ee9175200b92cb5483ac7d466927a9b3d537",
+                "sha256:2791f68edc5749024b4722500e86303a10d342527e1e3bcac47f35fbd25b764e",
+                "sha256:2f9674623ca39c9ebe38afa3da402e9326c245f0f5ceff0623dccdac15023e05",
+                "sha256:3363e77a6176afb8823b6e06db78c46dbc4c7813b00a41300a4873b6ba63b171",
+                "sha256:33c6cdc071ba5cd6d96769c8969a0531be2d08c2628a0143a10a7dcffa9719ca",
+                "sha256:3b8eaf915ddc0709779889c472e553f0d3e8b7bdf62dab764c8921b09bf94522",
+                "sha256:3cb3e1b9ec43256c4e0f8d2837267a70b0e1ca8c4f456685508ae6106b1f504c",
+                "sha256:3eeeb0405fd145e714f7633a5173318bd88d8bbfc3dd0a5751f8c4f70ae629bc",
+                "sha256:44f60519595eaca110f248e5017363d751b12782a6f2bd6a7041cba275215f5d",
+                "sha256:4d7c26bfc1ea9f92084a1d75e11999e97b62d63128bcc90c3624d07813c52808",
+                "sha256:529c4ed2e10437c205f38f3691a68be66c39197d01062618c55f74294a4a4828",
+                "sha256:6642f15ad963b5092d65aed022d033c77763515fdc07095208f15d3563003869",
+                "sha256:85ba797e1de5b48aa5a8427b6ba62cf69607c18c5d4eb747604b7302f1ec382d",
+                "sha256:8f0f1e499e4000c4c347a124fa6a27d37608ced4fe9f7d45070563b7c4c370c9",
+                "sha256:a624fae282e81ad2e4871bdb767e2c914d0539708c0f078b5b355258293c98b0",
+                "sha256:b0358e6fefc74a16f745afa366acc89f979040e0cbc4eec55ab26ad1f6a9bfbc",
+                "sha256:bbd2f4dfee1079f76943767fce837ade3087b578aeb9f69aec7857d5bf25db15",
+                "sha256:bf39a9e19ce7298f1bd6a9758fa99707e9e5b1ebe5e90f2c3913a47bc548747c",
+                "sha256:c11579638288e53fc94ad60022ff1b67865363e730ee41ad5e6f0a17188b327a",
+                "sha256:c150eaa3dadbb2b5339675b88d4573c1be3cb6f2c33a6c83387e10cc0bf05bd3",
+                "sha256:c53af463f4a40de78c58b8b2710ade243c81cbca641e34debf3396a9640d6ec1",
+                "sha256:cb763ceceae04803adcc4e2d80d611ef201c73da32d8f2722e9d0ab0c7f10768",
+                "sha256:cc75f58cdaf043fe6a7a6c04b3b5a0e694c6a9e24050967747251fb80d7bce0d",
+                "sha256:d80998ed59176e8cba74028762fbd9b9153b9afc71ea118e63bbf5d4d0f9552b",
+                "sha256:de31b5164d44ef4943db155b3e8e17929707cac1e5bd2f363e67a56e3af4af6e",
+                "sha256:e66399cf0fc07de4dce4f588fc25bfe84a6d1285cc544e67987d22663393926d",
+                "sha256:f0620511387790860b249b9241c2f13c3a80e21a73e0b861a2df24e9d6f56730",
+                "sha256:f4eae045e6ab2bb54ca279733fe4eb85f1effda392666308250714e01907f394",
+                "sha256:f92cdecb618e5fa4658aeb97d5eb3d2f47aa94ac6477c6daf0f306c5a3b9e6b1",
+                "sha256:f92f789e4f9241cd262ad7a555ca2c648a98178a953af117ef7fad46aa1d5591"
+            ],
+            "version": "==1.14.3"
         },
         "cfgv": {
             "hashes": [
                 "sha256:32e43d604bbe7896fe7c248a9c2276447dbef840feb28fe20494f62af110211d",
                 "sha256:cf22deb93d4bcf92f345a5c3cd39d3d41d6340adc60c78bbbd6588c384fda6a1"
             ],
-            "markers": "python_full_version >= '3.6.1'",
             "version": "==3.2.0"
         },
         "chardet": {
@@ -400,11 +402,10 @@
         },
         "colorama": {
             "hashes": [
-                "sha256:7d73d2a99753107a36ac6b455ee49046802e59d9d076ef8e47b61499fa29afff",
-                "sha256:e96da0d330793e2cb9485e9ddfd918d456036c7149416295932478192f4436a1"
+                "sha256:5941b2b48a20143d2267e95b1c2a7603ce057ee39fd88e7329b0c292aa16869b",
+                "sha256:9f47eda37229f68eee03b24b9748937c7dc3868f906e8ba69fbcbdd3bc5dc3e2"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
-            "version": "==0.4.3"
+            "version": "==0.4.4"
         },
         "commonmark": {
             "hashes": [
@@ -455,31 +456,31 @@
         },
         "cryptography": {
             "hashes": [
-                "sha256:10c9775a3f31610cf6b694d1fe598f2183441de81cedcf1814451ae53d71b13a",
-                "sha256:180c9f855a8ea280e72a5d61cf05681b230c2dce804c48e9b2983f491ecc44ed",
-                "sha256:247df238bc05c7d2e934a761243bfdc67db03f339948b1e2e80c75d41fc7cc36",
-                "sha256:26409a473cc6278e4c90f782cd5968ebad04d3911ed1c402fc86908c17633e08",
-                "sha256:2a27615c965173c4c88f2961cf18115c08fedfb8bdc121347f26e8458dc6d237",
-                "sha256:2e26223ac636ca216e855748e7d435a1bf846809ed12ed898179587d0cf74618",
-                "sha256:321761d55fb7cb256b771ee4ed78e69486a7336be9143b90c52be59d7657f50f",
-                "sha256:4005b38cd86fc51c955db40b0f0e52ff65340874495af72efabb1bb8ca881695",
-                "sha256:4b9e96543d0784acebb70991ebc2dbd99aa287f6217546bb993df22dd361d41c",
-                "sha256:548b0818e88792318dc137d8b1ec82a0ab0af96c7f0603a00bb94f896fbf5e10",
-                "sha256:725875681afe50b41aee7fdd629cedbc4720bab350142b12c55c0a4d17c7416c",
-                "sha256:7a63e97355f3cd77c94bd98c59cb85fe0efd76ea7ef904c9b0316b5bbfde6ed1",
-                "sha256:94191501e4b4009642be21dde2a78bd3c2701a81ee57d3d3d02f1d99f8b64a9e",
-                "sha256:969ae512a250f869c1738ca63be843488ff5cc031987d302c1f59c7dbe1b225f",
-                "sha256:9f734423eb9c2ea85000aa2476e0d7a58e021bc34f0a373ac52a5454cd52f791",
-                "sha256:b45ab1c6ece7c471f01c56f5d19818ca797c34541f0b2351635a5c9fe09ac2e0",
-                "sha256:cc6096c86ec0de26e2263c228fb25ee01c3ff1346d3cfc219d67d49f303585af",
-                "sha256:dc3f437ca6353979aace181f1b790f0fc79e446235b14306241633ab7d61b8f8",
-                "sha256:e7563eb7bc5c7e75a213281715155248cceba88b11cb4b22957ad45b85903761",
-                "sha256:e7dad66a9e5684a40f270bd4aee1906878193ae50a4831922e454a2a457f1716",
-                "sha256:eb80a288e3cfc08f679f95da72d2ef90cb74f6d8a8ba69d2f215c5e110b2ca32",
-                "sha256:fa7fbcc40e2210aca26c7ac8a39467eae444d90a2c346cbcffd9133a166bcc67"
-            ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
-            "version": "==3.1"
+                "sha256:22f8251f68953553af4f9c11ec5f191198bc96cff9f0ac5dd5ff94daede0ee6d",
+                "sha256:284e275e3c099a80831f9898fb5c9559120d27675c3521278faba54e584a7832",
+                "sha256:3e17d02941c0f169c5b877597ca8be895fca0e5e3eb882526a74aa4804380a98",
+                "sha256:52a47e60953679eea0b4d490ca3c241fb1b166a7b161847ef4667dfd49e7699d",
+                "sha256:57b8c1ed13b8aa386cabbfde3be175d7b155682470b0e259fecfe53850967f8a",
+                "sha256:6a8f64ed096d13f92d1f601a92d9fd1f1025dc73a2ca1ced46dcf5e0d4930943",
+                "sha256:6e8a3c7c45101a7eeee93102500e1b08f2307c717ff553fcb3c1127efc9b6917",
+                "sha256:7ef41304bf978f33cfb6f43ca13bb0faac0c99cda33693aa20ad4f5e34e8cb8f",
+                "sha256:87c2fffd61e934bc0e2c927c3764c20b22d7f5f7f812ee1a477de4c89b044ca6",
+                "sha256:88069392cd9a1e68d2cfd5c3a2b0d72a44ef3b24b8977a4f7956e9e3c4c9477a",
+                "sha256:8a0866891326d3badb17c5fd3e02c926b635e8923fa271b4813cd4d972a57ff3",
+                "sha256:8f0fd8b0751d75c4483c534b209e39e918f0d14232c0d8a2a76e687f64ced831",
+                "sha256:9a07e6d255053674506091d63ab4270a119e9fc83462c7ab1dbcb495b76307af",
+                "sha256:9a8580c9afcdcddabbd064c0a74f337af74ff4529cdf3a12fa2e9782d677a2e5",
+                "sha256:bd80bc156d3729b38cb227a5a76532aef693b7ac9e395eea8063ee50ceed46a5",
+                "sha256:d1cbc3426e6150583b22b517ef3720036d7e3152d428c864ff0f3fcad2b97591",
+                "sha256:e15ac84dcdb89f92424cbaca4b0b34e211e7ce3ee7b0ec0e4f3c55cee65fae5a",
+                "sha256:e4789b84f8dedf190148441f7c5bfe7244782d9cbb194a36e17b91e7d3e1cca9",
+                "sha256:f01c9116bfb3ad2831e125a73dcd957d173d6ddca7701528eff1e7d97972872c",
+                "sha256:f0e3986f6cce007216b23c490f093f35ce2068f3c244051e559f647f6731b7ae",
+                "sha256:f2aa3f8ba9e2e3fd49bd3de743b976ab192fbf0eb0348cebde5d2a9de0090a9f",
+                "sha256:fb70a4cedd69dc52396ee114416a3656e011fb0311fca55eb55c7be6ed9c8aef"
+            ],
+            "index": "pypi",
+            "version": "==3.2"
         },
         "distlib": {
             "hashes": [
@@ -491,7 +492,6 @@
         "docutils": {
             "hashes": [
                 "sha256:54a349c622ff31c91cbec43b0b512f113b5b24daf00e2ea530bb1bd9aac14849",
-                "sha256:ba4584f9107571ced0d2c7f56a5499c696215ba90797849c92d395979da68521",
                 "sha256:d2ddba74835cb090a1b627d3de4e7835c628d07ee461f7b4480f51af2fe4d448"
             ],
             "index": "pypi",
@@ -530,18 +530,16 @@
         },
         "identify": {
             "hashes": [
-                "sha256:c770074ae1f19e08aadbda1c886bc6d0cb55ffdc503a8c0fe8699af2fc9664ae",
-                "sha256:d02d004568c5a01261839a05e91705e3e9f5c57a3551648f9b3fb2b9c62c0f62"
+                "sha256:3139bf72d81dfd785b0a464e2776bd59bdc725b4cc10e6cf46b56a0db931c82e",
+                "sha256:969d844b7a85d32a5f9ac4e163df6e846d73c87c8b75847494ee8f4bd2186421"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==1.5.3"
+            "version": "==1.5.6"
         },
         "idna": {
             "hashes": [
                 "sha256:b307872f855b18632ce0c21c5e45be78c0ea7ae4c15c828c20788b26921eb3f6",
                 "sha256:b97d804b1e9b523befed77c48dacec60e6dcb0b5391d57af6a65a312a90648c0"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==2.10"
         },
         "imagesize": {
@@ -549,7 +547,6 @@
                 "sha256:6965f19a6a2039c7d48bca7dba2473069ff854c36ae6f19d2cde309d998228a1",
                 "sha256:b1f6b5a4eab1f73479a50fb79fcf729514a900c341d8503d62a62dbc4127a2b1"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==1.2.0"
         },
         "jeepney": {
@@ -565,7 +562,6 @@
                 "sha256:89aab215427ef59c34ad58735269eb58b1a5808103067f7bb9d5836c651b3bb0",
                 "sha256:f0a4641d3cf955324a89c04f3d94663aa4d638abe8f733ecd3582848e1c37035"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
             "version": "==2.11.2"
         },
         "keyring": {
@@ -573,7 +569,6 @@
                 "sha256:4e34ea2fdec90c1c43d6610b5a5fafa1b9097db1802948e90caf5763974b8f8d",
                 "sha256:9aeadd006a852b78f4b4ef7c7556c2774d2432bbef8ee538a3e9089ac8b11466"
             ],
-            "markers": "python_version >= '3.6'",
             "version": "==21.4.0"
         },
         "markupsafe": {
@@ -612,7 +607,6 @@
                 "sha256:e249096428b3ae81b08327a63a485ad0878de3fb939049038579ac0ef61e17e7",
                 "sha256:e8313f01ba26fbbe36c7be1966a7b7424942f670f38e666995b88d012765b9be"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==1.1.1"
         },
         "mccabe": {
@@ -642,7 +636,6 @@
                 "sha256:fcfbb44c59af3f8ea984de67ec7c306f618a3ec771c2843804069917a8f2e255",
                 "sha256:feed85993dbdb1dbc29102f50bca65bdc68f2c0c8d352468c25b54874f23c39d"
             ],
-            "markers": "python_version >= '3.5'",
             "version": "==4.7.6"
         },
         "mypy": {
@@ -685,7 +678,6 @@
                 "sha256:4357f74f47b9c12db93624a82154e9b120fa8293699949152b22065d556079f8",
                 "sha256:998416ba6962ae7fbd6596850b80e17859a5753ba17c32284f67bfff33784181"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==20.4"
         },
         "pathspec": {
@@ -698,10 +690,10 @@
         },
         "pkginfo": {
             "hashes": [
-                "sha256:7424f2c8511c186cd5424bbf31045b77435b37a8d604990b79d4e70d741148bb",
-                "sha256:a6d9e40ca61ad3ebd0b72fbadd4fba16e4c0e4df0428c041e01e06eb6ee71f32"
+                "sha256:a6a4ac943b496745cec21f14f021bbd869d5e9b4f6ec06918cffea5a2f4b9193",
+                "sha256:ce14d7296c673dc4c61c759a0b6c14bae34e34eb819c0017bb6ca5b7292c56e9"
             ],
-            "version": "==1.5.0.1"
+            "version": "==1.6.1"
         },
         "pre-commit": {
             "hashes": [
@@ -716,7 +708,6 @@
                 "sha256:2295e7b2f6b5bd100585ebcb1f616591b652db8a741695b3d8f5d28bdc934367",
                 "sha256:c58a7d2815e0e8d7972bf1803331fb0152f867bd89adf8a01dfd55085434192e"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==2.6.0"
         },
         "pycparser": {
@@ -724,7 +715,6 @@
                 "sha256:2d475327684562c3a96cc71adf7dc8c4f0565175cf86b6d7a404ff4c771f15f0",
                 "sha256:7582ad22678f0fcd81102833f60ef8d0e57288b6b5fb00323d101be910e35705"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==2.20"
         },
         "pyflakes": {
@@ -732,23 +722,20 @@
                 "sha256:0d94e0e05a19e57a99444b6ddcf9a6eb2e5c68d3ca1e98e90707af8152c90a92",
                 "sha256:35b2d75ee967ea93b55750aa9edbbf72813e06a66ba54438df2cfac9e3c27fc8"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==2.2.0"
         },
         "pygments": {
             "hashes": [
-                "sha256:307543fe65c0947b126e83dd5a61bd8acbd84abec11f43caebaf5534cbc17998",
-                "sha256:926c3f319eda178d1bd90851e4317e6d8cdb5e292a3386aac9bd75eca29cf9c7"
+                "sha256:381985fcc551eb9d37c52088a32914e00517e57f4a21609f48141ba08e193fa0",
+                "sha256:88a0bbcd659fcb9573703957c6b9cff9fab7295e6e76db54c9d00ae42df32773"
             ],
-            "markers": "python_version >= '3.5'",
-            "version": "==2.7.1"
+            "version": "==2.7.2"
         },
         "pyparsing": {
             "hashes": [
                 "sha256:c203ec8783bf771a155b207279b9bccb8dea02d8f0c9e5f8ead507bc3246ecc1",
                 "sha256:ef9d7589ef3c200abe66653d3f1ab1033c3c419ae9b9bdb1240a85b024efc88b"
             ],
-            "markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==2.4.7"
         },
         "pytz": {
@@ -822,7 +809,6 @@
                 "sha256:b3559a131db72c33ee969480840fff4bb6dd111de7dd27c8ee1f820f4f00231b",
                 "sha256:fe75cc94a9443b9246fc7049224f75604b113c36acb93f87b80ed42c44cbb898"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
             "version": "==2.24.0"
         },
         "requests-toolbelt": {
@@ -849,16 +835,10 @@
         },
         "setuptools-scm": {
             "hashes": [
-                "sha256:09c659d1d6680811c43f476a33c6d3d9872416580786e96bd29ea03e6a818e41",
                 "sha256:69258e2eeba5f7ce1ed7a5f109519580fa3578250f8e4d6684859f86d1b15826",
-                "sha256:731550a27e3901ee501c3bf99140b5436b8eeba341a9d19911cf364b8d573293",
-                "sha256:892e63b4983f9e30f9e8bf89ad03d2a02a47e6e5ced09b03ae6fe952ade8a579",
-                "sha256:a8994582e716ec690f33fec70cca0f85bd23ec974e3f783233e4879090a7faa8",
-                "sha256:b42c150c34d6120babf3646abd7513e032be2e230b3d2034f27404c65aa0c977",
-                "sha256:eaaec16b7af25c5f532b5af2332213bb6223d15cca4518f6dbc4c055641c86fd",
-                "sha256:efc928d6a64162c88cdc85fa4b84adfbd6dbf9f9b04319bc495eb16dcfaae00a"
-            ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
+                "sha256:a8994582e716ec690f33fec70cca0f85bd23ec974e3f783233e4879090a7faa8"
+            ],
+            "index": "pypi",
             "version": "==4.1.2"
         },
         "six": {
@@ -866,7 +846,6 @@
                 "sha256:30639c035cdb23534cd4aa2dd52c3bf48f06e5f4a941509c8bafd8ce11080259",
                 "sha256:8b74bedcbbbaca38ff6d7491d76f2b06b3592611af620f8426e82dddb04a5ced"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==1.15.0"
         },
         "snowballstemmer": {
@@ -889,7 +868,6 @@
                 "sha256:806111e5e962be97c29ec4c1e7fe277bfd19e9652fb1a4392105b43e01af885a",
                 "sha256:a072735ec80e7675e3f432fcae8610ecf509c5f1869d17e2eecff44389cdbc58"
             ],
-            "markers": "python_version >= '3.5'",
             "version": "==1.0.2"
         },
         "sphinxcontrib-devhelp": {
@@ -897,7 +875,6 @@
                 "sha256:8165223f9a335cc1af7ffe1ed31d2871f325254c0423bc0c4c7cd1c1e4734a2e",
                 "sha256:ff7f1afa7b9642e7060379360a67e9c41e8f3121f2ce9164266f61b9f4b338e4"
             ],
-            "markers": "python_version >= '3.5'",
             "version": "==1.0.2"
         },
         "sphinxcontrib-htmlhelp": {
@@ -905,7 +882,6 @@
                 "sha256:3c0bc24a2c41e340ac37c85ced6dafc879ab485c095b1d65d2461ac2f7cca86f",
                 "sha256:e8f5bb7e31b2dbb25b9cc435c8ab7a79787ebf7f906155729338f3156d93659b"
             ],
-            "markers": "python_version >= '3.5'",
             "version": "==1.0.3"
         },
         "sphinxcontrib-jsmath": {
@@ -913,7 +889,6 @@
                 "sha256:2ec2eaebfb78f3f2078e73666b1415417a116cc848b72e5172e596c871103178",
                 "sha256:a9925e4a4587247ed2191a22df5f6970656cb8ca2bd6284309578f2153e0c4b8"
             ],
-            "markers": "python_version >= '3.5'",
             "version": "==1.0.1"
         },
         "sphinxcontrib-qthelp": {
@@ -921,7 +896,6 @@
                 "sha256:4c33767ee058b70dba89a6fc5c1892c0d57a54be67ddd3e7875a18d14cba5a72",
                 "sha256:bd9fc24bcb748a8d51fd4ecaade681350aa63009a347a8c14e637895444dfab6"
             ],
-            "markers": "python_version >= '3.5'",
             "version": "==1.0.3"
         },
         "sphinxcontrib-serializinghtml": {
@@ -929,26 +903,22 @@
                 "sha256:eaa0eccc86e982a9b939b2b82d12cc5d013385ba5eadcc7e4fed23f4405f77bc",
                 "sha256:f242a81d423f59617a8e5cf16f5d4d74e28ee9a66f9e5b637a18082991db5a9a"
             ],
-            "markers": "python_version >= '3.5'",
             "version": "==1.1.4"
         },
         "toml": {
             "hashes": [
-                "sha256:235682dd292d5899d361a811df37e04a8828a5b1da3115886b73cf81ebc9100e",
-                "sha256:bda89d5935c2eac546d648028b9901107a595863cb36bae0c73ac804a9b4ce88",
                 "sha256:926b612be1e5ce0634a2ca03470f95169cf16f939018233a670519cb4ac58b0f",
-                "sha256:229f81c57791a41d65e399fc06bf0848bab550a9dfd5ed66df18ce5f05e73d5c"
+                "sha256:bda89d5935c2eac546d648028b9901107a595863cb36bae0c73ac804a9b4ce88"
             ],
             "index": "pypi",
             "version": "==0.10.1"
         },
         "tqdm": {
             "hashes": [
-                "sha256:8f3c5815e3b5e20bc40463fa6b42a352178859692a68ffaa469706e6d38342a5",
-                "sha256:faf9c671bd3fad5ebaeee366949d969dca2b2be32c872a7092a1e1a9048d105b"
+                "sha256:9ad44aaf0fc3697c06f6e05c7cf025dd66bc7bcb7613c66d85f4464c47ac8fad",
+                "sha256:ef54779f1c09f346b2b5a8e5c61f96fbcb639929e640e59f8cf810794f406432"
             ],
-            "markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==4.49.0"
+            "version": "==4.51.0"
         },
         "twine": {
             "hashes": [
@@ -962,9 +932,11 @@
             "hashes": [
                 "sha256:0666aa36131496aed8f7be0410ff974562ab7eeac11ef351def9ea6fa28f6355",
                 "sha256:0c2c07682d61a629b68433afb159376e24e5b2fd4641d35424e462169c0a7919",
+                "sha256:0d8110d78a5736e16e26213114a38ca35cb15b6515d535413b090bd50951556d",
                 "sha256:249862707802d40f7f29f6e1aad8d84b5aa9e44552d2cc17384b209f091276aa",
                 "sha256:24995c843eb0ad11a4527b026b4dde3da70e1f2d8806c99b7b4a7cf491612652",
                 "sha256:269151951236b0f9a6f04015a9004084a5ab0d5f19b57de779f908621e7d8b75",
+                "sha256:3742b32cf1c6ef124d57f95be609c473d7ec4c14d0090e5a5e05a15269fb4d0c",
                 "sha256:4083861b0aa07990b619bd7ddc365eb7fa4b817e99cf5f8d9cf21a42780f6e01",
                 "sha256:498b0f36cc7054c1fead3d7fc59d2150f4d5c6c56ba7fb150c013fbc683a8d2d",
                 "sha256:4e3e5da80ccbebfff202a67bf900d081906c358ccc3d5e3c8aea42fdfdfd51c1",
@@ -973,12 +945,16 @@
                 "sha256:73d785a950fc82dd2a25897d525d003f6378d1cb23ab305578394694202a58c3",
                 "sha256:8c8aaad94455178e3187ab22c8b01a3837f8ee50e09cf31f1ba129eb293ec30b",
                 "sha256:8ce678dbaf790dbdb3eba24056d5364fb45944f33553dd5869b7580cdbb83614",
+                "sha256:92c325624e304ebf0e025d1224b77dd4e6393f18aab8d829b5b7e04afe9b7a2c",
                 "sha256:aaee9905aee35ba5905cfb3c62f3e83b3bec7b39413f0a7f19be4e547ea01ebb",
+                "sha256:b52ccf7cfe4ce2a1064b18594381bccf4179c2ecf7f513134ec2f993dd4ab395",
                 "sha256:bcd3b13b56ea479b3650b82cabd6b5343a625b0ced5429e4ccad28a8973f301b",
                 "sha256:c9e348e02e4d2b4a8b2eedb48210430658df6951fa484e59de33ff773fbd4b41",
                 "sha256:d205b1b46085271b4e15f670058ce182bd1199e56b317bf2ec004b6a44f911f6",
                 "sha256:d43943ef777f9a1c42bf4e552ba23ac77a6351de620aa9acf64ad54933ad4d34",
                 "sha256:d5d33e9e7af3b34a40dc05f498939f0ebf187f07c385fd58d591c533ad8562fe",
+                "sha256:d648b8e3bf2fe648745c8ffcee3db3ff903d0817a01a12dd6a6ea7a8f4889072",
+                "sha256:fac11badff8313e23717f3dada86a15389d0708275bddf766cca67a84ead3e91",
                 "sha256:fc0fea399acb12edbf8a628ba8d2312f583bdbdb3335635db062fa98cf71fca4",
                 "sha256:fe460b922ec15dd205595c9b5b99e2f056fd98ae8f9f56b888e7a17dc2b757e7"
             ],
@@ -996,19 +972,17 @@
         },
         "urllib3": {
             "hashes": [
-                "sha256:91056c15fa70756691db97756772bb1eb9678fa585d9184f24534b100dc60f4a",
-                "sha256:e7983572181f5e1522d9c98453462384ee92a0be7fac5f1413a1e35c56cc0461"
+                "sha256:8d7eaa5a82a1cac232164990f04874c594c9453ec55eef02eab885aa02fc17a2",
+                "sha256:f5321fbe4bf3fefa0efd0bfe7fb14e90909eb62a48ccda331726b4319897dd5e"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4' and python_version < '4'",
-            "version": "==1.25.10"
+            "version": "==1.25.11"
         },
         "virtualenv": {
             "hashes": [
-                "sha256:43add625c53c596d38f971a465553f6318decc39d98512bc100fa1b1e839c8dc",
-                "sha256:e0305af10299a7fb0d69393d8f04cb2965dda9351140d11ac8db4e5e3970451b"
+                "sha256:b0011228208944ce71052987437d3843e05690b2f23d1c7da4263fde104c97a2",
+                "sha256:b8d6110f493af256a40d65e29846c69340a947669eec8ce784fcf3dd3af28380"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==20.0.31"
+            "version": "==20.1.0"
         },
         "webencodings": {
             "hashes": [
@@ -1027,26 +1001,41 @@
         },
         "yarl": {
             "hashes": [
-                "sha256:040b237f58ff7d800e6e0fd89c8439b841f777dd99b4a9cca04d6935564b9409",
-                "sha256:17668ec6722b1b7a3a05cc0167659f6c95b436d25a36c2d52db0eca7d3f72593",
-                "sha256:3a584b28086bc93c888a6c2aa5c92ed1ae20932f078c46509a66dce9ea5533f2",
-                "sha256:4439be27e4eee76c7632c2427ca5e73703151b22cae23e64adb243a9c2f565d8",
-                "sha256:48e918b05850fffb070a496d2b5f97fc31d15d94ca33d3d08a4f86e26d4e7c5d",
-                "sha256:9102b59e8337f9874638fcfc9ac3734a0cfadb100e47d55c20d0dc6087fb4692",
-                "sha256:9b930776c0ae0c691776f4d2891ebc5362af86f152dd0da463a6614074cb1b02",
-                "sha256:b3b9ad80f8b68519cc3372a6ca85ae02cc5a8807723ac366b53c0f089db19e4a",
-                "sha256:bc2f976c0e918659f723401c4f834deb8a8e7798a71be4382e024bcc3f7e23a8",
-                "sha256:c22c75b5f394f3d47105045ea551e08a3e804dc7e01b37800ca35b58f856c3d6",
-                "sha256:c52ce2883dc193824989a9b97a76ca86ecd1fa7955b14f87bf367a61b6232511",
-                "sha256:ce584af5de8830d8701b8979b18fcf450cef9a382b1a3c8ef189bedc408faf1e",
-                "sha256:da456eeec17fa8aa4594d9a9f27c0b1060b6a75f2419fe0c00609587b2695f4a",
-                "sha256:db6db0f45d2c63ddb1a9d18d1b9b22f308e52c83638c26b422d520a815c4b3fb",
-                "sha256:df89642981b94e7db5596818499c4b2219028f2a528c9c37cc1de45bf2fd3a3f",
-                "sha256:f18d68f2be6bf0e89f1521af2b1bb46e66ab0018faafa81d70f358153170a317",
-                "sha256:f379b7f83f23fe12823085cd6b906edc49df969eb99757f58ff382349a3303c6"
-            ],
-            "markers": "python_version >= '3.5'",
-            "version": "==1.5.1"
+                "sha256:03b7a44384ad60be1b7be93c2a24dc74895f8d767ea0bce15b2f6fc7695a3843",
+                "sha256:076157404db9db4bb3fa9db22db319bbb36d075eeab19ba018ce20ae0cacf037",
+                "sha256:1c05ae3d5ea4287470046a2c2754f0a4c171b84ea72c8a691f776eb1753dfb91",
+                "sha256:2467baf8233f7c64048df37e11879c553943ffe7f373e689711ec2807ea13805",
+                "sha256:2bb2e21cf062dfbe985c3cd4618bae9f25271efcad9e7be1277861247eee9839",
+                "sha256:311effab3b3828ab34f0e661bb57ff422f67d5c33056298bda4c12195251f8dd",
+                "sha256:3526cb5905907f0e42bee7ef57ae4a5f02bc27dcac27859269e2bba0caa4c2b6",
+                "sha256:39b1e586f34b1d2512c9b39aa3cf24c870c972d525e36edc9ee19065db4737bb",
+                "sha256:4bed5cd7c8e69551eb19df15295ba90e62b9a6a1149c76eb4a9bab194402a156",
+                "sha256:51c6d3cf7a1f1fbe134bb92f33b7affd94d6de24cd64b466eb12de52120fb8c6",
+                "sha256:59f78b5da34ddcffb663b772f7619e296518712e022e57fc5d9f921818e2ab7c",
+                "sha256:6f29115b0c330da25a04f48612d75333bca04521181a666ca0b8761005a99150",
+                "sha256:73d4e1e1ef5e52d526c92f07d16329e1678612c6a81dd8101fdcae11a72de15c",
+                "sha256:9b48d31f8d881713fd461abfe7acbb4dcfeb47cec3056aa83f2fbcd2244577f7",
+                "sha256:a1fd575dd058e10ad4c35065e7c3007cc74d142f622b14e168d8a273a2fa8713",
+                "sha256:b3dd1052afd436ba737e61f5d3bed1f43a7f9a33fc58fbe4226eb919a7006019",
+                "sha256:b99c25ed5c355b35d1e6dae87ac7297a4844a57dc5766b173b88b6163a36eb0d",
+                "sha256:c056e86bff5a0b566e0d9fab4f67e83b12ae9cbcd250d334cbe2005bbe8c96f2",
+                "sha256:c45b49b59a5724869899798e1bbd447ac486215269511d3b76b4c235a1b766b6",
+                "sha256:cd623170c729a865037828e3f99f8ebdb22a467177a539680dfc5670b74c84e2",
+                "sha256:d25d3311794e6c71b608d7c47651c8f65eea5ab15358a27f29330b3475e8f8e5",
+                "sha256:d695439c201ed340745250f9eb4dfe8d32bf1e680c16477107b8f3ce4bff4fdb",
+                "sha256:d77f6c9133d2aabb290a7846aaa74ec14d7b5ab35b01591fac5a70c4a8c959a2",
+                "sha256:d894a2442d2cd20a3b0b0dce5a353d316c57d25a2b445e03f7eac90eee27b8af",
+                "sha256:db643ce2b58a4bd11a82348225c53c76ecdd82bb37cf4c085e6df1b676f4038c",
+                "sha256:e3a0c43a26dfed955b2a06fdc4d51d2c51bc2200aff8ce8faf14e676ea8c8862",
+                "sha256:e77bf79ad1ccae672eab22453838382fe9029fc27c8029e84913855512a587d8",
+                "sha256:f2f0174cb15435957d3b751093f89aede77df59a499ab7516bbb633b77ead13a",
+                "sha256:f3031c78edf10315abe232254e6a36b65afe65fded41ee54ed7976d0b2cdf0da",
+                "sha256:f4c007156732866aa4507d619fe6f8f2748caabed4f66b276ccd97c82572620c",
+                "sha256:f4f27ff3dd80bc7c402def211a47291ea123d59a23f59fe18fc0e81e3e71f385",
+                "sha256:f57744fc61e118b5d114ae8077d8eb9df4d2d2c11e2af194e21f0c11ed9dcf6c",
+                "sha256:f835015a825980b65356e9520979a1564c56efea7da7d4b68a14d4a07a3a7336"
+            ],
+            "version": "==1.6.2"
         }
     }
 }

From 8c8af4f1612dc29358490a7d04dd4ff2f5d4939d Mon Sep 17 00:00:00 2001
From: Abdullah Selek <abdullahselek@users.noreply.github.com>
Date: Fri, 30 Oct 2020 15:24:18 +0000
Subject: [PATCH 0042/1034] Start using Python 3.9 on Travis (#1790)

* Start using Python 3.9 on Travis

* Remove allow_failures
---
 .travis.yml | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/.travis.yml b/.travis.yml
index f035343c6fb..e8d2975c5ff 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -28,9 +28,7 @@ matrix:
     - name: "3.8"
       python: 3.8
     - name: "3.9"
-      python: 3.9-dev
-  allow_failures:
-    - python: 3.9-dev
+      python: 3.9
 before_deploy:
   - pip install pyinstaller
   - pyinstaller --clean -F --add-data src/blib2to3/:blib2to3 src/black/__init__.py

From 6c3f8181854160f3db354f6f6ef3315ef05db8e7 Mon Sep 17 00:00:00 2001
From: Bryan Bugyi <bryanbugyi34@gmail.com>
Date: Sat, 31 Oct 2020 13:42:36 -0400
Subject: [PATCH 0043/1034] Fix bug where black tries to split string on
 escaped space (#1799)

Closes #1505.
---
 src/black/__init__.py                  | 17 ++++++++++--
 tests/data/long_strings__regression.py | 37 ++++++++++++++++++++++++++
 2 files changed, 52 insertions(+), 2 deletions(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index 24e9d4edaaa..e09838d866a 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -3590,7 +3590,8 @@ class StringSplitter(CustomSplitMapMixin, BaseStringSplitter):
         MIN_SUBSTR_SIZE characters.
 
         The string will ONLY be split on spaces (i.e. each new substring should
-        start with a space).
+        start with a space). Note that the string will NOT be split on a space
+        which is escaped with a backslash.
 
         If the string is an f-string, it will NOT be split in the middle of an
         f-expression (e.g. in f"FooBar: {foo() if x else bar()}", {foo() if x
@@ -3930,11 +3931,23 @@ def passes_all_checks(i: Index) -> bool:
                 section of this classes' docstring would be be met by returning @i.
             """
             is_space = string[i] == " "
+
+            is_not_escaped = True
+            j = i - 1
+            while is_valid_index(j) and string[j] == "\\":
+                is_not_escaped = not is_not_escaped
+                j -= 1
+
             is_big_enough = (
                 len(string[i:]) >= self.MIN_SUBSTR_SIZE
                 and len(string[:i]) >= self.MIN_SUBSTR_SIZE
             )
-            return is_space and is_big_enough and not breaks_fstring_expression(i)
+            return (
+                is_space
+                and is_not_escaped
+                and is_big_enough
+                and not breaks_fstring_expression(i)
+            )
 
         # First, we check all indices BELOW @max_break_idx.
         break_idx = max_break_idx
diff --git a/tests/data/long_strings__regression.py b/tests/data/long_strings__regression.py
index 8290a4cbc1c..9bfb1eedd5a 100644
--- a/tests/data/long_strings__regression.py
+++ b/tests/data/long_strings__regression.py
@@ -353,6 +353,24 @@ def xxxxxxx_xxxxxx(xxxx):
     key
 ] = "test"  # set some Thrift field to non-None in the struct aa bb cc dd ee
 
+RE_ONE_BACKSLASH = {
+    "asdf_hjkl_jkl": re.compile(
+        r"(?<!([0-9]\ ))(?<=(^|\ ))([A-Z]+(\ )?|[0-9](\ )|[a-z](\ )){4,7}([A-Z]|[0-9]|[a-z])($|\b)(?!(\ ?([0-9]\ )|(\.)))"
+    ),
+}
+
+RE_TWO_BACKSLASHES = {
+    "asdf_hjkl_jkl": re.compile(
+        r"(?<!([0-9]\ ))(?<=(^|\ ))([A-Z]+(\ )?|[0-9](\ )|[a-z](\\ )){4,7}([A-Z]|[0-9]|[a-z])($|\b)(?!(\ ?([0-9]\ )|(\.)))"
+    ),
+}
+
+RE_THREE_BACKSLASHES = {
+    "asdf_hjkl_jkl": re.compile(
+        r"(?<!([0-9]\ ))(?<=(^|\ ))([A-Z]+(\ )?|[0-9](\ )|[a-z](\\\ )){4,7}([A-Z]|[0-9]|[a-z])($|\b)(?!(\ ?([0-9]\ )|(\.)))"
+    ),
+}
+
 # output
 
 
@@ -793,3 +811,22 @@ def xxxxxxx_xxxxxx(xxxx):
 value.__dict__[
     key
 ] = "test"  # set some Thrift field to non-None in the struct aa bb cc dd ee
+
+RE_ONE_BACKSLASH = {
+    "asdf_hjkl_jkl": re.compile(
+        r"(?<!([0-9]\ ))(?<=(^|\ ))([A-Z]+(\ )?|[0-9](\ )|[a-z](\ )){4,7}([A-Z]|[0-9]|[a-z])($|\b)(?!(\ ?([0-9]\ )|(\.)))"
+    ),
+}
+
+RE_TWO_BACKSLASHES = {
+    "asdf_hjkl_jkl": re.compile(
+        r"(?<!([0-9]\ ))(?<=(^|\ ))([A-Z]+(\ )?|[0-9](\ )|[a-z](\\"
+        r" )){4,7}([A-Z]|[0-9]|[a-z])($|\b)(?!(\ ?([0-9]\ )|(\.)))"
+    ),
+}
+
+RE_THREE_BACKSLASHES = {
+    "asdf_hjkl_jkl": re.compile(
+        r"(?<!([0-9]\ ))(?<=(^|\ ))([A-Z]+(\ )?|[0-9](\ )|[a-z](\\\ )){4,7}([A-Z]|[0-9]|[a-z])($|\b)(?!(\ ?([0-9]\ )|(\.)))"
+    ),
+}

From 74e51e6a829d48db1b4da4f1eac935647d1655cc Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Sun, 1 Nov 2020 16:17:23 -0500
Subject: [PATCH 0044/1034] Automatically build and upload binaries on release
 (#1743)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This commit adds a new GitHub Actions workflow that builds self-contained
binaries / executables and uploads them as release assets to the triggering
release. Publishing a release, drafting one doesn't count, will trigger this
workflow.

I personally used GitHub Actions only because it's the CI/CD platform(?)
I am familiar with. Only Windows and Linux binaries are supported since
I don't have any systems running Mac OS.

For Linux, I had originally planned to use the manylinux2010 docker image
the PyPA provides for highly compatible wheel building, but unfortunately
it wasn't feasible due to GitHub Actions and PyInstaller incompatibilities.
As a stopgap the oldest versions of Linux and Windows are used although
Windows Server 2019 isn't that old nor is Ubuntu 16.04! I guess someone
(maybe me) could work out something else if compatibility is big problem.

A few things you should know about the workflow:
 - You don't need to set the `GITHUB_TOKEN` secret as it is automatically
   provided by GitHub.
 - matrix.pathsep is used because PyInstaller configuration's format is OS
   dependent for some reason ...

Also it's worth mentioning that Black once had Travis CI and AppVeyor
configuration that did the same thing as this commit. They were committed
in mid 2018 and worked (somewhat) well. Eventually we stopped using AppVeyor
and the refactor to packages broke the Travis CI config. This commit
replaces the still existing and broken Travis CI config wholesale.

Co-authored-by: Anders Fredrik Kiær <31612826+anders-kiaer@users.noreply.github.com>

 - Anders told me that I could get the release asset upload URL directly
   from the github.event.release payload. I originally planned to use
   bruceadams/get-release to get such URL.
---
 .github/workflows/upload_binary.yml | 51 +++++++++++++++++++++++++++++
 .travis.yml                         | 14 --------
 CHANGES.md                          |  5 +++
 3 files changed, 56 insertions(+), 14 deletions(-)
 create mode 100644 .github/workflows/upload_binary.yml

diff --git a/.github/workflows/upload_binary.yml b/.github/workflows/upload_binary.yml
new file mode 100644
index 00000000000..46d92ab2149
--- /dev/null
+++ b/.github/workflows/upload_binary.yml
@@ -0,0 +1,51 @@
+name: Upload self-contained binaries
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: [3.7]
+        os: [ubuntu-16.04, windows-2019]
+        include:
+          - os: windows-2019
+            pathsep: ";"
+            executable_suffix: ".exe"
+            executable_mime: "application/vnd.microsoft.portable-executable"
+          - os: ubuntu-16.04
+            pathsep: ":"
+            executable_suffix: ".elf"
+            executable_mime: "application/x-executable"
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip wheel setuptools
+          python -m pip install .
+          python -m pip install pyinstaller
+
+      - name: Build binary
+        run: |
+          python -m PyInstaller -F --name black${{ matrix.executable_suffix }} --add-data 'src/blib2to3${{ matrix.pathsep }}blib2to3' src/black/__main__.py
+
+      - name: Upload binary as release asset
+        uses: actions/upload-release-asset@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          upload_url: ${{ github.event.release.upload_url }}
+          asset_path: dist/black${{ matrix.executable_suffix }}
+          asset_name: black${{ matrix.executable_suffix }}
+          asset_content_type: ${{ matrix.executable_mime }}
diff --git a/.travis.yml b/.travis.yml
index e8d2975c5ff..e782272e813 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -29,17 +29,3 @@ matrix:
       python: 3.8
     - name: "3.9"
       python: 3.9
-before_deploy:
-  - pip install pyinstaller
-  - pyinstaller --clean -F --add-data src/blib2to3/:blib2to3 src/black/__init__.py
-deploy:
-  provider: releases
-  api_key:
-    secure: chYvcmnRqRKtfBcAZRj62rEv0ziWuHMl6MnfQbd1MOVQ4njntI8+CCPk118dW6MWSfwTqyMFy+t9gAgQYhjkLEHMS2aK9Z2wCWki1MkBrkMw5tYoLFvPu0KQ9rIVihxsr93a/am6Oh/Hp+1uuc4zWPUf1ubX+QlCzsxjCzVso1kTJjjdN04UxvkcFR+sY2d9Qyy9WcdifChnLwdmIJKIoVOE7Imm820nzImJHkJh8iSnjBjL98gvPPeC/nWTltsbErvf2mCv4NIjzjQZvHa87c7rSJGbliNrAxCSyyvBX+JNeS8U2fGLE83do0HieyjdPbTuc27e2nsrrihgPh+hXbiJerljclfp5hsJ5qGz5sS9MU1fR7sSLiQQ2v0TYB5RRwd34TgGiLwFAZZmgZOfMUCtefCKvP8qvELMSNd99+msfPEHiuhADF0bKPTbCUa6BgUHNr6woOLmHerjPHd6NI/a8Skz/uQB4xr3spLSmfUmX0fEqyYUDphkGPNH8IsvC1/F2isecW9kOzEWmB5oCmpMTGm4TIf3C01Nx+9PVwB2Z+30hhbfIEBxD4loRFmh/hU5TIQEpneF8yoIfe9EnMaoZbq86xhADZXvLIZvpXUdm1NQZDG6na2S1fwyOUKQsW6BWLcfoZZwZlrXrViD1jBsHBV++s+lxShTeTCszlo=
-  file:
-    - dist/black
-  skip_cleanup: true
-  on:
-    condition: $TRAVIS_PYTHON_VERSION == '3.6'
-    repo: psf/black
-    tags: true
diff --git a/CHANGES.md b/CHANGES.md
index dfc54224b41..240abe302a4 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -21,6 +21,11 @@
 
 - Added support for PEP 614 relaxed decorator syntax on python 3.9 (#1711)
 
+#### _Packaging_
+
+- Self-contained native _Black_ binaries are now provided for releases via GitHub
+  Releases (#1743)
+
 ### 20.8b1
 
 #### _Packaging_

From edf1c9dc0f20239b9d5351d8b0607c9e936dd43f Mon Sep 17 00:00:00 2001
From: Bryan Bugyi <bryanbugyi34@gmail.com>
Date: Fri, 6 Nov 2020 19:17:23 -0500
Subject: [PATCH 0045/1034] Fix bug which causes f-expressions to be split
 (#1809)

Closes #1807.
---
 src/black/__init__.py                  |  5 +++--
 tests/data/long_strings__regression.py | 14 ++++++++++++++
 2 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index e09838d866a..7a7456ad78b 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -3611,13 +3611,14 @@ class StringSplitter(CustomSplitMapMixin, BaseStringSplitter):
     MIN_SUBSTR_SIZE = 6
     # Matches an "f-expression" (e.g. {var}) that might be found in an f-string.
     RE_FEXPR = r"""
-    (?<!\{)\{
+    (?<!\{) (?:\{\{)* \{ (?!\{)
         (?:
             [^\{\}]
             | \{\{
             | \}\}
+            | (?R)
         )+?
-    (?<!\})(?:\}\})*\}(?!\})
+    (?<!\}) \} (?:\}\})* (?!\})
     """
 
     def do_splitter_match(self, line: Line) -> TMatchResult:
diff --git a/tests/data/long_strings__regression.py b/tests/data/long_strings__regression.py
index 9bfb1eedd5a..7065b2fcef8 100644
--- a/tests/data/long_strings__regression.py
+++ b/tests/data/long_strings__regression.py
@@ -371,6 +371,10 @@ def xxxxxxx_xxxxxx(xxxx):
     ),
 }
 
+# We do NOT split on f-string expressions.
+print(f"Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam. {[f'{i}' for i in range(10)]}")
+x = f"This is a long string which contains an f-expr that should not split {{{[i for i in range(5)]}}}."
+
 # output
 
 
@@ -830,3 +834,13 @@ def xxxxxxx_xxxxxx(xxxx):
         r"(?<!([0-9]\ ))(?<=(^|\ ))([A-Z]+(\ )?|[0-9](\ )|[a-z](\\\ )){4,7}([A-Z]|[0-9]|[a-z])($|\b)(?!(\ ?([0-9]\ )|(\.)))"
     ),
 }
+
+# We do NOT split on f-string expressions.
+print(
+    "Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam."
+    f" {[f'{i}' for i in range(10)]}"
+)
+x = (
+    "This is a long string which contains an f-expr that should not split"
+    f" {{{[i for i in range(5)]}}}."
+)

From 1d8b4d766d912c7b9e91fa885419730c334345ef Mon Sep 17 00:00:00 2001
From: Justin Prieto <density@users.noreply.github.com>
Date: Mon, 9 Nov 2020 14:58:23 -0500
Subject: [PATCH 0046/1034] Correctly handle inline tabs in docstrings (#1810)

The `fix_docstring` function expanded all tabs, which caused a
difference in the AST representation when those tabs were inline and not
leading. This changes the function to only expand leading tabs so inline
tabs are preserved.

Fixes #1601.
---
 src/black/__init__.py   | 26 +++++++++++++++++---
 tests/data/docstring.py | 53 ++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 75 insertions(+), 4 deletions(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index 7a7456ad78b..7e13a5d33f5 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -6744,13 +6744,33 @@ def is_docstring(leaf: Leaf) -> bool:
     return False
 
 
+def lines_with_leading_tabs_expanded(s: str) -> List[str]:
+    """
+    Splits string into lines and expands only leading tabs (following the normal
+    Python rules)
+    """
+    lines = []
+    for line in s.splitlines():
+        # Find the index of the first non-whitespace character after a string of
+        # whitespace that includes at least one tab
+        match = re.match(r"\s*\t+\s*(\S)", line)
+        if match:
+            first_non_whitespace_idx = match.start(1)
+
+            lines.append(
+                line[:first_non_whitespace_idx].expandtabs()
+                + line[first_non_whitespace_idx:]
+            )
+        else:
+            lines.append(line)
+    return lines
+
+
 def fix_docstring(docstring: str, prefix: str) -> str:
     # https://www.python.org/dev/peps/pep-0257/#handling-docstring-indentation
     if not docstring:
         return ""
-    # Convert tabs to spaces (following the normal Python rules)
-    # and split into a list of lines:
-    lines = docstring.expandtabs().splitlines()
+    lines = lines_with_leading_tabs_expanded(docstring)
     # Determine minimum indentation (first line doesn't count):
     indent = sys.maxsize
     for line in lines[1:]:
diff --git a/tests/data/docstring.py b/tests/data/docstring.py
index 2d3d73a101c..5c6985d0e08 100644
--- a/tests/data/docstring.py
+++ b/tests/data/docstring.py
@@ -110,6 +110,32 @@ def ignored_docstring():
     """a => \
 b"""  
 
+
+def docstring_with_inline_tabs_and_space_indentation():
+    """hey
+
+    tab	separated	value
+    	tab at start of line and then a tab	separated	value
+    				multiple tabs at the beginning	and	inline
+    	 	  	mixed tabs and spaces at beginning. next line has mixed tabs and spaces only.
+    			 	  		
+    line ends with some tabs		
+    """
+
+
+def docstring_with_inline_tabs_and_tab_indentation():
+	"""hey
+
+	tab	separated	value
+		tab at start of line and then a tab	separated	value
+					multiple tabs at the beginning	and	inline
+		 	  	mixed tabs and spaces at beginning. next line has mixed tabs and spaces only.
+				 	  		
+	line ends with some tabs		
+	"""
+	pass
+        
+
 # output
 
 class MyClass:
@@ -222,4 +248,29 @@ def believe_it_or_not_this_is_in_the_py_stdlib():
 
 def ignored_docstring():
     """a => \
-b"""
\ No newline at end of file
+b"""
+
+
+def docstring_with_inline_tabs_and_space_indentation():
+    """hey
+
+    tab	separated	value
+        tab at start of line and then a tab	separated	value
+                                multiple tabs at the beginning	and	inline
+                        mixed tabs and spaces at beginning. next line has mixed tabs and spaces only.
+
+    line ends with some tabs
+    """
+
+
+def docstring_with_inline_tabs_and_tab_indentation():
+    """hey
+
+    tab	separated	value
+            tab at start of line and then a tab	separated	value
+                                    multiple tabs at the beginning	and	inline
+                            mixed tabs and spaces at beginning. next line has mixed tabs and spaces only.
+
+    line ends with some tabs
+    """
+    pass

From 7d032fa848c8910007a0a41c1ba61d70d2846f48 Mon Sep 17 00:00:00 2001
From: Casper Weiss Bang <c@cwb.dk>
Date: Fri, 13 Nov 2020 16:25:17 +0100
Subject: [PATCH 0047/1034] Use lowercase hex numbers fixes #1692 (#1775)

* Made hex lower case

* Refactored numeric formatting section

* Redid some refactoring and removed bloat

* Removed additions from test_requirements.txt

* Primer now expects expected changes

* Undid some refactoring

* added to changelog

* Update src/black/__init__.py

Co-authored-by: Zsolt Dollenstein <zsol.zsol@gmail.com>

Co-authored-by: Zsolt Dollenstein <zsol.zsol@gmail.com>
Co-authored-by: Cooper Lees <me@cooperlees.com>
---
 .gitignore                                    |  3 +-
 CHANGES.md                                    |  2 +
 src/black/__init__.py                         | 57 +++++++++++++------
 src/black_primer/primer.json                  | 10 ++--
 src/blib2to3/pytree.py                        |  2 +-
 test_requirements.txt                         |  2 +-
 tests/data/numeric_literals.py                |  4 +-
 tests/data/numeric_literals_py2.py            |  4 +-
 .../data/numeric_literals_skip_underscores.py |  6 +-
 9 files changed, 57 insertions(+), 33 deletions(-)

diff --git a/.gitignore b/.gitignore
index 3207e72ae28..30225ec7764 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,4 @@
+.venv
 .coverage
 _build
 .DS_Store
@@ -15,4 +16,4 @@ src/_black_version.py
 .dmypy.json
 *.swp
 .hypothesis/
-venv/
\ No newline at end of file
+venv/
diff --git a/CHANGES.md b/CHANGES.md
index 240abe302a4..67697bd7b07 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -21,6 +21,8 @@
 
 - Added support for PEP 614 relaxed decorator syntax on python 3.9 (#1711)
 
+- use lowercase hex strings (#1692)
+
 #### _Packaging_
 
 - Self-contained native _Black_ binaries are now provided for releases via GitHub
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 7e13a5d33f5..44edeb0d9f1 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -5192,31 +5192,52 @@ def normalize_numeric_literal(leaf: Leaf) -> None:
         # Leave octal and binary literals alone.
         pass
     elif text.startswith("0x"):
-        # Change hex literals to upper case.
-        before, after = text[:2], text[2:]
-        text = f"{before}{after.upper()}"
+        text = format_hex(text)
     elif "e" in text:
-        before, after = text.split("e")
-        sign = ""
-        if after.startswith("-"):
-            after = after[1:]
-            sign = "-"
-        elif after.startswith("+"):
-            after = after[1:]
-        before = format_float_or_int_string(before)
-        text = f"{before}e{sign}{after}"
+        text = format_scientific_notation(text)
     elif text.endswith(("j", "l")):
-        number = text[:-1]
-        suffix = text[-1]
-        # Capitalize in "2L" because "l" looks too similar to "1".
-        if suffix == "l":
-            suffix = "L"
-        text = f"{format_float_or_int_string(number)}{suffix}"
+        text = format_long_or_complex_number(text)
     else:
         text = format_float_or_int_string(text)
     leaf.value = text
 
 
+def format_hex(text: str) -> str:
+    """
+    Formats a hexadecimal string like "0x12b3"
+
+    Uses lowercase because of similarity between "B" and "8", which
+    can cause security issues.
+    see: https://github.com/psf/black/issues/1692
+    """
+
+    before, after = text[:2], text[2:]
+    return f"{before}{after.lower()}"
+
+
+def format_scientific_notation(text: str) -> str:
+    """Formats a numeric string utilizing scentific notation"""
+    before, after = text.split("e")
+    sign = ""
+    if after.startswith("-"):
+        after = after[1:]
+        sign = "-"
+    elif after.startswith("+"):
+        after = after[1:]
+    before = format_float_or_int_string(before)
+    return f"{before}e{sign}{after}"
+
+
+def format_long_or_complex_number(text: str) -> str:
+    """Formats a long or complex string like `10L` or `10j`"""
+    number = text[:-1]
+    suffix = text[-1]
+    # Capitalize in "2L" because "l" looks too similar to "1".
+    if suffix == "l":
+        suffix = "L"
+    return f"{format_float_or_int_string(number)}{suffix}"
+
+
 def format_float_or_int_string(text: str) -> str:
     """Formats a float string like "1.0"."""
     if "." not in text:
diff --git a/src/black_primer/primer.json b/src/black_primer/primer.json
index cdc863ca032..32df01571a7 100644
--- a/src/black_primer/primer.json
+++ b/src/black_primer/primer.json
@@ -10,7 +10,7 @@
     },
     "attrs": {
       "cli_arguments": [],
-      "expect_formatting_changes": false,
+      "expect_formatting_changes": true,
       "git_clone_url": "https://github.com/python-attrs/attrs.git",
       "long_checkout": false,
       "py_versions": ["all"]
@@ -47,7 +47,7 @@
     },
     "hypothesis": {
       "cli_arguments": [],
-      "expect_formatting_changes": false,
+      "expect_formatting_changes": true,
       "git_clone_url": "https://github.com/HypothesisWorks/hypothesis.git",
       "long_checkout": false,
       "py_versions": ["all"]
@@ -63,7 +63,7 @@
     },
     "pillow": {
       "cli_arguments": [],
-      "expect_formatting_changes": false,
+      "expect_formatting_changes": true,
       "git_clone_url": "https://github.com/python-pillow/Pillow.git",
       "long_checkout": false,
       "py_versions": ["all"]
@@ -77,7 +77,7 @@
     },
     "pyramid": {
       "cli_arguments": [],
-      "expect_formatting_changes": false,
+      "expect_formatting_changes": true,
       "git_clone_url": "https://github.com/Pylons/pyramid.git",
       "long_checkout": false,
       "py_versions": ["all"]
@@ -112,7 +112,7 @@
     },
     "virtualenv": {
       "cli_arguments": [],
-      "expect_formatting_changes": false,
+      "expect_formatting_changes": true,
       "git_clone_url": "https://github.com/pypa/virtualenv.git",
       "long_checkout": false,
       "py_versions": ["all"]
diff --git a/src/blib2to3/pytree.py b/src/blib2to3/pytree.py
index 4b841b768e7..6dba3c7bb15 100644
--- a/src/blib2to3/pytree.py
+++ b/src/blib2to3/pytree.py
@@ -34,7 +34,7 @@
 import sys
 from io import StringIO
 
-HUGE: int = 0x7FFFFFFF  # maximum repeat count, default max
+HUGE: int = 0x7fffffff  # maximum repeat count, default max
 
 _type_reprs: Dict[int, Union[Text, int]] = {}
 
diff --git a/test_requirements.txt b/test_requirements.txt
index 3e65cdb669f..9f69b8edf83 100644
--- a/test_requirements.txt
+++ b/test_requirements.txt
@@ -2,4 +2,4 @@ pytest >= 6.1.1
 pytest-mock >= 3.3.1
 pytest-cases >= 2.3.0
 coverage >= 5.3
-parameterized >= 0.7.4
\ No newline at end of file
+parameterized >= 0.7.4
diff --git a/tests/data/numeric_literals.py b/tests/data/numeric_literals.py
index 254da68d330..06b7f7758ee 100644
--- a/tests/data/numeric_literals.py
+++ b/tests/data/numeric_literals.py
@@ -12,7 +12,7 @@
 x = 123456789E123456789
 x = 123456789J
 x = 123456789.123456789J
-x = 0XB1ACC
+x = 0Xb1aCc
 x = 0B1011
 x = 0O777
 x = 0.000000006
@@ -36,7 +36,7 @@
 x = 123456789e123456789
 x = 123456789j
 x = 123456789.123456789j
-x = 0xB1ACC
+x = 0xb1acc
 x = 0b1011
 x = 0o777
 x = 0.000000006
diff --git a/tests/data/numeric_literals_py2.py b/tests/data/numeric_literals_py2.py
index 8f85c43f265..8b2c7faa306 100644
--- a/tests/data/numeric_literals_py2.py
+++ b/tests/data/numeric_literals_py2.py
@@ -3,7 +3,7 @@
 x = 123456789L
 x = 123456789l
 x = 123456789
-x = 0xb1acc
+x = 0xB1aCc
 
 # output
 
@@ -13,4 +13,4 @@
 x = 123456789L
 x = 123456789L
 x = 123456789
-x = 0xB1ACC
+x = 0xb1acc
diff --git a/tests/data/numeric_literals_skip_underscores.py b/tests/data/numeric_literals_skip_underscores.py
index e345bb90276..f83e23312f2 100644
--- a/tests/data/numeric_literals_skip_underscores.py
+++ b/tests/data/numeric_literals_skip_underscores.py
@@ -3,7 +3,7 @@
 x = 123456789
 x = 1_2_3_4_5_6_7
 x = 1E+1
-x = 0xb1acc
+x = 0xb1AcC
 x = 0.00_00_006
 x = 12_34_567J
 x = .1_2
@@ -16,8 +16,8 @@
 x = 123456789
 x = 1_2_3_4_5_6_7
 x = 1e1
-x = 0xB1ACC
+x = 0xb1acc
 x = 0.00_00_006
 x = 12_34_567j
 x = 0.1_2
-x = 1_2.0
\ No newline at end of file
+x = 1_2.0

From dea81b7ad5cfa04c3572771c34af823449d0a8f3 Mon Sep 17 00:00:00 2001
From: Thiago Bellini Ribeiro <hackedbellini@gmail.com>
Date: Fri, 13 Nov 2020 12:26:07 -0300
Subject: [PATCH 0048/1034] Provide a stdin-filename to allow stdin to respect
 force-exclude rules (#1780)

* Provide a stdin-filename to allow stdin to respect exclude/force-exclude rules

This will allow automatic tools to enforce the project's
exclude/force-exclude rules even if they pass the file through stdin to
update its buffer.

This is a similar solution to --stdin-display-name in flake8.

* Update src/black/__init__.py

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>

* --stdin-filename should only respect --exclude-filename

* Update README with the new --stdin-filename option

* Write some tests for the new stdin-filename functionality

* Apply suggestions from code review

Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>

* Force stdin output when we asked for stdin even if the file exists

* Add an entry in the changelog regarding --stdin-filename

* Reduce disk reads if possible

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>

* Check for is_stdin and p.is_file before checking for p.is_dir()

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
---
 README.md             |   5 ++
 docs/change_log.md    |   3 +
 src/black/__init__.py |  67 +++++++++++++-----
 tests/test_black.py   | 159 ++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 217 insertions(+), 17 deletions(-)

diff --git a/README.md b/README.md
index d34ce146e0d..a557a6fc6c8 100644
--- a/README.md
+++ b/README.md
@@ -135,6 +135,11 @@ Options:
                                   matching this regex will be excluded even
                                   when they are passed explicitly as arguments.
 
+  --stdin-filename TEXT           The name of the file when passing it through
+                                  stdin. Useful to make sure Black will respect
+                                  --force-exclude option on some editors that
+                                  rely on using stdin.
+
   -q, --quiet                     Don't emit non-error messages to stderr.
                                   Errors are still emitted; silence those with
                                   2>/dev/null.
diff --git a/docs/change_log.md b/docs/change_log.md
index 1ee35a4d8f9..e6afefbf686 100644
--- a/docs/change_log.md
+++ b/docs/change_log.md
@@ -23,6 +23,9 @@
 
 - Added support for PEP 614 relaxed decorator syntax on python 3.9 (#1711)
 
+- Added `--stdin-filename` argument to allow stdin to respect `--force-exclude` rules.
+  Works very alike to flake8's `--stdin-display-name` (#1780)
+
 ### 20.8b1
 
 #### _Packaging_
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 44edeb0d9f1..48690573810 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -68,6 +68,7 @@
 DEFAULT_EXCLUDES = r"/(\.direnv|\.eggs|\.git|\.hg|\.mypy_cache|\.nox|\.tox|\.venv|\.svn|_build|buck-out|build|dist)/"  # noqa: B950
 DEFAULT_INCLUDES = r"\.pyi?$"
 CACHE_DIR = Path(user_cache_dir("black", version=__version__))
+STDIN_PLACEHOLDER = "__BLACK_STDIN_FILENAME__"
 
 STRING_PREFIX_CHARS: Final = "furbFURB"  # All possible string prefix characters.
 
@@ -457,6 +458,15 @@ def target_version_option_callback(
         "excluded even when they are passed explicitly as arguments."
     ),
 )
+@click.option(
+    "--stdin-filename",
+    type=str,
+    help=(
+        "The name of the file when passing it through stdin. Useful to make "
+        "sure Black will respect --force-exclude option on some "
+        "editors that rely on using stdin."
+    ),
+)
 @click.option(
     "-q",
     "--quiet",
@@ -516,6 +526,7 @@ def main(
     include: str,
     exclude: str,
     force_exclude: Optional[str],
+    stdin_filename: Optional[str],
     src: Tuple[str, ...],
     config: Optional[str],
 ) -> None:
@@ -548,6 +559,7 @@ def main(
         exclude=exclude,
         force_exclude=force_exclude,
         report=report,
+        stdin_filename=stdin_filename,
     )
 
     path_empty(
@@ -587,6 +599,7 @@ def get_sources(
     exclude: str,
     force_exclude: Optional[str],
     report: "Report",
+    stdin_filename: Optional[str],
 ) -> Set[Path]:
     """Compute the set of files to be formatted."""
     try:
@@ -613,22 +626,14 @@ def get_sources(
     gitignore = get_gitignore(root)
 
     for s in src:
-        p = Path(s)
-        if p.is_dir():
-            sources.update(
-                gen_python_files(
-                    p.iterdir(),
-                    root,
-                    include_regex,
-                    exclude_regex,
-                    force_exclude_regex,
-                    report,
-                    gitignore,
-                )
-            )
-        elif s == "-":
-            sources.add(p)
-        elif p.is_file():
+        if s == "-" and stdin_filename:
+            p = Path(stdin_filename)
+            is_stdin = True
+        else:
+            p = Path(s)
+            is_stdin = False
+
+        if is_stdin or p.is_file():
             normalized_path = normalize_path_maybe_ignore(p, root, report)
             if normalized_path is None:
                 continue
@@ -643,6 +648,23 @@ def get_sources(
                 report.path_ignored(p, "matches the --force-exclude regular expression")
                 continue
 
+            if is_stdin:
+                p = Path(f"{STDIN_PLACEHOLDER}{str(p)}")
+
+            sources.add(p)
+        elif p.is_dir():
+            sources.update(
+                gen_python_files(
+                    p.iterdir(),
+                    root,
+                    include_regex,
+                    exclude_regex,
+                    force_exclude_regex,
+                    report,
+                    gitignore,
+                )
+            )
+        elif s == "-":
             sources.add(p)
         else:
             err(f"invalid path: {s}")
@@ -670,7 +692,18 @@ def reformat_one(
     """
     try:
         changed = Changed.NO
-        if not src.is_file() and str(src) == "-":
+
+        if str(src) == "-":
+            is_stdin = True
+        elif str(src).startswith(STDIN_PLACEHOLDER):
+            is_stdin = True
+            # Use the original name again in case we want to print something
+            # to the user
+            src = Path(str(src)[len(STDIN_PLACEHOLDER) :])
+        else:
+            is_stdin = False
+
+        if is_stdin:
             if format_stdin_to_stdout(fast=fast, write_back=write_back, mode=mode):
                 changed = Changed.YES
         else:
diff --git a/tests/test_black.py b/tests/test_black.py
index b0cf6ed5caa..a688c8780ef 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -1336,10 +1336,169 @@ def test_exclude_for_issue_1572(self) -> None:
                 exclude=exclude,
                 force_exclude=None,
                 report=report,
+                stdin_filename=None,
             )
         )
         self.assertEqual(sorted(expected), sorted(sources))
 
+    @patch("black.find_project_root", lambda *args: THIS_DIR.resolve())
+    def test_get_sources_with_stdin(self) -> None:
+        include = ""
+        exclude = r"/exclude/|a\.py"
+        src = "-"
+        report = black.Report()
+        expected = [Path("-")]
+        sources = list(
+            black.get_sources(
+                ctx=FakeContext(),
+                src=(src,),
+                quiet=True,
+                verbose=False,
+                include=include,
+                exclude=exclude,
+                force_exclude=None,
+                report=report,
+                stdin_filename=None,
+            )
+        )
+        self.assertEqual(sorted(expected), sorted(sources))
+
+    @patch("black.find_project_root", lambda *args: THIS_DIR.resolve())
+    def test_get_sources_with_stdin_filename(self) -> None:
+        include = ""
+        exclude = r"/exclude/|a\.py"
+        src = "-"
+        report = black.Report()
+        stdin_filename = str(THIS_DIR / "data/collections.py")
+        expected = [Path(f"__BLACK_STDIN_FILENAME__{stdin_filename}")]
+        sources = list(
+            black.get_sources(
+                ctx=FakeContext(),
+                src=(src,),
+                quiet=True,
+                verbose=False,
+                include=include,
+                exclude=exclude,
+                force_exclude=None,
+                report=report,
+                stdin_filename=stdin_filename,
+            )
+        )
+        self.assertEqual(sorted(expected), sorted(sources))
+
+    @patch("black.find_project_root", lambda *args: THIS_DIR.resolve())
+    def test_get_sources_with_stdin_filename_and_exclude(self) -> None:
+        # Exclude shouldn't exclude stdin_filename since it is mimicing the
+        # file being passed directly. This is the same as
+        # test_exclude_for_issue_1572
+        path = THIS_DIR / "data" / "include_exclude_tests"
+        include = ""
+        exclude = r"/exclude/|a\.py"
+        src = "-"
+        report = black.Report()
+        stdin_filename = str(path / "b/exclude/a.py")
+        expected = [Path(f"__BLACK_STDIN_FILENAME__{stdin_filename}")]
+        sources = list(
+            black.get_sources(
+                ctx=FakeContext(),
+                src=(src,),
+                quiet=True,
+                verbose=False,
+                include=include,
+                exclude=exclude,
+                force_exclude=None,
+                report=report,
+                stdin_filename=stdin_filename,
+            )
+        )
+        self.assertEqual(sorted(expected), sorted(sources))
+
+    @patch("black.find_project_root", lambda *args: THIS_DIR.resolve())
+    def test_get_sources_with_stdin_filename_and_force_exclude(self) -> None:
+        # Force exclude should exclude the file when passing it through
+        # stdin_filename
+        path = THIS_DIR / "data" / "include_exclude_tests"
+        include = ""
+        force_exclude = r"/exclude/|a\.py"
+        src = "-"
+        report = black.Report()
+        stdin_filename = str(path / "b/exclude/a.py")
+        sources = list(
+            black.get_sources(
+                ctx=FakeContext(),
+                src=(src,),
+                quiet=True,
+                verbose=False,
+                include=include,
+                exclude="",
+                force_exclude=force_exclude,
+                report=report,
+                stdin_filename=stdin_filename,
+            )
+        )
+        self.assertEqual([], sorted(sources))
+
+    def test_reformat_one_with_stdin(self) -> None:
+        with patch(
+            "black.format_stdin_to_stdout",
+            return_value=lambda *args, **kwargs: black.Changed.YES,
+        ) as fsts:
+            report = MagicMock()
+            path = Path("-")
+            black.reformat_one(
+                path,
+                fast=True,
+                write_back=black.WriteBack.YES,
+                mode=DEFAULT_MODE,
+                report=report,
+            )
+            fsts.assert_called_once()
+            report.done.assert_called_with(path, black.Changed.YES)
+
+    def test_reformat_one_with_stdin_filename(self) -> None:
+        with patch(
+            "black.format_stdin_to_stdout",
+            return_value=lambda *args, **kwargs: black.Changed.YES,
+        ) as fsts:
+            report = MagicMock()
+            p = "foo.py"
+            path = Path(f"__BLACK_STDIN_FILENAME__{p}")
+            expected = Path(p)
+            black.reformat_one(
+                path,
+                fast=True,
+                write_back=black.WriteBack.YES,
+                mode=DEFAULT_MODE,
+                report=report,
+            )
+            fsts.assert_called_once()
+            # __BLACK_STDIN_FILENAME__ should have been striped
+            report.done.assert_called_with(expected, black.Changed.YES)
+
+    def test_reformat_one_with_stdin_and_existing_path(self) -> None:
+        with patch(
+            "black.format_stdin_to_stdout",
+            return_value=lambda *args, **kwargs: black.Changed.YES,
+        ) as fsts:
+            report = MagicMock()
+            # Even with an existing file, since we are forcing stdin, black
+            # should output to stdout and not modify the file inplace
+            p = Path(str(THIS_DIR / "data/collections.py"))
+            # Make sure is_file actually returns True
+            self.assertTrue(p.is_file())
+            path = Path(f"__BLACK_STDIN_FILENAME__{p}")
+            expected = Path(p)
+            black.reformat_one(
+                path,
+                fast=True,
+                write_back=black.WriteBack.YES,
+                mode=DEFAULT_MODE,
+                report=report,
+            )
+            fsts.assert_called_once()
+            # __BLACK_STDIN_FILENAME__ should have been striped
+            report.done.assert_called_with(expected, black.Changed.YES)
+
     def test_gitignore_exclude(self) -> None:
         path = THIS_DIR / "data" / "include_exclude_tests"
         include = re.compile(r"\.pyi?$")

From 4d03716eaea58ee38d77cf2bba0a72b7a27ec9fa Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Tue, 24 Nov 2020 04:39:25 -0500
Subject: [PATCH 0049/1034] Allow same RHS expressions in annotated assignments
 as in regular assignments (#1835)

---
 CHANGES.md               |  3 +++
 src/blib2to3/Grammar.txt |  2 +-
 tests/data/python38.py   | 18 ++++++++++++++++++
 3 files changed, 22 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index 67697bd7b07..ca8a0472a3b 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -21,6 +21,9 @@
 
 - Added support for PEP 614 relaxed decorator syntax on python 3.9 (#1711)
 
+- Added parsing support for unparenthesized tuples and yield expressions in annotated
+  assignments (#1835)
+
 - use lowercase hex strings (#1692)
 
 #### _Packaging_
diff --git a/src/blib2to3/Grammar.txt b/src/blib2to3/Grammar.txt
index eafaee84cb3..69b9af96608 100644
--- a/src/blib2to3/Grammar.txt
+++ b/src/blib2to3/Grammar.txt
@@ -77,7 +77,7 @@ small_stmt: (expr_stmt | print_stmt  | del_stmt | pass_stmt | flow_stmt |
              import_stmt | global_stmt | exec_stmt | assert_stmt)
 expr_stmt: testlist_star_expr (annassign | augassign (yield_expr|testlist) |
                      ('=' (yield_expr|testlist_star_expr))*)
-annassign: ':' test ['=' test]
+annassign: ':' test ['=' (yield_expr|testlist_star_expr)]
 testlist_star_expr: (test|star_expr) (',' (test|star_expr))* [',']
 augassign: ('+=' | '-=' | '*=' | '@=' | '/=' | '%=' | '&=' | '|=' | '^=' |
             '<<=' | '>>=' | '**=' | '//=')
diff --git a/tests/data/python38.py b/tests/data/python38.py
index 1a7f76167d9..63b0588bc27 100644
--- a/tests/data/python38.py
+++ b/tests/data/python38.py
@@ -11,6 +11,14 @@ def starred_yield():
     yield "value1", *my_list
 
 
+# all right hand side expressions allowed in regular assignments are now also allowed in
+# annotated assignments
+a : Tuple[ str, int] = "1", 2
+a: Tuple[int , ... ] = b,  *c, d
+def t():
+    a : str =  yield "a"
+
+
 # output
 
 
@@ -25,3 +33,13 @@ def starred_return():
 def starred_yield():
     my_list = ["value2", "value3"]
     yield "value1", *my_list
+
+
+# all right hand side expressions allowed in regular assignments are now also allowed in
+# annotated assignments
+a: Tuple[str, int] = "1", 2
+a: Tuple[int, ...] = b, *c, d
+
+
+def t():
+    a: str = yield "a"

From 7f75fe3669ebf0627b1b0476a6d02047e909b959 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Wed, 25 Nov 2020 19:26:35 -0500
Subject: [PATCH 0050/1034] Switch back to Python 3.8 for ReadTheDocs (#1839)

ReadTheDocs doesn't support Python 3.9 yet.
---
 readthedocs.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/readthedocs.yml b/readthedocs.yml
index 32bcf1fa50e..15065033d0f 100644
--- a/readthedocs.yml
+++ b/readthedocs.yml
@@ -1,6 +1,6 @@
 version: 2
 python:
-  version: 3.9
+  version: 3.8
   install:
     - requirements: docs/requirements.txt
     - method: setuptools

From 2989dc1bf822b1b2a6bd250cea37bbf20c237764 Mon Sep 17 00:00:00 2001
From: Noel Evans <noelevans@gmail.com>
Date: Wed, 9 Dec 2020 23:40:45 +0000
Subject: [PATCH 0051/1034] vim plugin: Add quiet flag so non-error actions go
 unreported (#1733)

---
 docs/editor_integration.md |  1 +
 plugin/black.vim           | 11 +++++++++--
 2 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/docs/editor_integration.md b/docs/editor_integration.md
index 21a6865d60e..037b265b9a0 100644
--- a/docs/editor_integration.md
+++ b/docs/editor_integration.md
@@ -123,6 +123,7 @@ Configuration:
 - `g:black_linelength` (defaults to `88`)
 - `g:black_skip_string_normalization` (defaults to `0`)
 - `g:black_virtualenv` (defaults to `~/.vim/black` or `~/.local/share/nvim/black`)
+- `g:black_quiet` (defaults to `0`)
 
 To install with [vim-plug](https://github.com/junegunn/vim-plug):
 
diff --git a/plugin/black.vim b/plugin/black.vim
index 3dd3f2151c3..c5f0313f4ac 100644
--- a/plugin/black.vim
+++ b/plugin/black.vim
@@ -48,6 +48,9 @@ if !exists("g:black_string_normalization")
     let g:black_string_normalization = 1
   endif
 endif
+if !exists("g:black_quiet")
+  let g:black_quiet = 0
+endif
 
 python3 << EndPython3
 import collections
@@ -74,6 +77,7 @@ FLAGS = [
   Flag(name="line_length", cast=int),
   Flag(name="fast", cast=strtobool),
   Flag(name="string_normalization", cast=strtobool),
+  Flag(name="quiet", cast=strtobool),
 ]
 
 
@@ -156,6 +160,7 @@ def Black():
     string_normalization=configs["string_normalization"],
     is_pyi=vim.current.buffer.name.endswith('.pyi'),
   )
+  quiet = configs["quiet"]
 
   buffer_str = '\n'.join(vim.current.buffer) + '\n'
   try:
@@ -165,7 +170,8 @@ def Black():
       mode=mode,
     )
   except black.NothingChanged:
-    print(f'Already well formatted, good job. (took {time.time() - start:.4f}s)')
+    if not quiet:
+      print(f'Already well formatted, good job. (took {time.time() - start:.4f}s)')
   except Exception as exc:
     print(exc)
   else:
@@ -183,7 +189,8 @@ def Black():
         window.cursor = cursor
       except vim.error:
         window.cursor = (len(window.buffer), 0)
-    print(f'Reformatted in {time.time() - start:.4f}s.')
+    if not quiet:
+      print(f'Reformatted in {time.time() - start:.4f}s.')
 
 def get_configs():
   path_pyproject_toml = black.find_pyproject_toml(vim.eval("fnamemodify(getcwd(), ':t')"))

From a522aa45c65bb896637d0add27b4c2a9fec6b976 Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Sun, 13 Dec 2020 23:20:25 -0800
Subject: [PATCH 0052/1034] Remove all trace of flake8-mypy (#1867)

flake8-mypy is long dead and shouldn't be used, see
https://github.com/ambv/flake8-mypy. We appear to use pre-commit to run
mypy now anyway.

I ran `pipenv uninstall flake8-mypy`, which seems to have made several
changes to Pipfile.lock. Let me know if there's a better way to do this.

Co-authored-by: hauntsaninja <>
---
 Pipfile      |   1 -
 Pipfile.lock | 842 +++++++++++++++++++++++++++++----------------------
 mypy.ini     |   1 -
 3 files changed, 473 insertions(+), 371 deletions(-)

diff --git a/Pipfile b/Pipfile
index 1ced1ed096b..ba596b3d738 100644
--- a/Pipfile
+++ b/Pipfile
@@ -9,7 +9,6 @@ coverage = "*"
 docutils = "==0.15"  # not a direct dependency, see https://github.com/pypa/pipenv/issues/3865
 flake8 = "*"
 flake8-bugbear = "*"
-flake8-mypy = "*"
 mypy = ">=0.782"
 pre-commit = "*"
 readme_renderer = "*"
diff --git a/Pipfile.lock b/Pipfile.lock
index 95b7613114a..a5c38aa0777 100644
--- a/Pipfile.lock
+++ b/Pipfile.lock
@@ -1,7 +1,7 @@
 {
     "_meta": {
         "hash": {
-            "sha256": "46390803c9b9e1b77a1b4a29de602d864dea188488d3aee6361030c91529611c"
+            "sha256": "21836c0a63b6e3e1eacd0adec7dea61d2d5989e38225edd976ff144e499f0426"
         },
         "pipfile-spec": 6,
         "requires": {},
@@ -16,21 +16,46 @@
     "default": {
         "aiohttp": {
             "hashes": [
-                "sha256:1e984191d1ec186881ffaed4581092ba04f7c61582a177b187d3a2f07ed9719e",
-                "sha256:259ab809ff0727d0e834ac5e8a283dc5e3e0ecc30c4d80b3cd17a4139ce1f326",
-                "sha256:2f4d1a4fdce595c947162333353d4a44952a724fba9ca3205a3df99a33d1307a",
-                "sha256:32e5f3b7e511aa850829fbe5aa32eb455e5534eaa4b1ce93231d00e2f76e5654",
-                "sha256:344c780466b73095a72c616fac5ea9c4665add7fc129f285fbdbca3cccf4612a",
-                "sha256:460bd4237d2dbecc3b5ed57e122992f60188afe46e7319116da5eb8a9dfedba4",
-                "sha256:4c6efd824d44ae697814a2a85604d8e992b875462c6655da161ff18fd4f29f17",
-                "sha256:50aaad128e6ac62e7bf7bd1f0c0a24bc968a0c0590a726d5a955af193544bcec",
-                "sha256:6206a135d072f88da3e71cc501c59d5abffa9d0bb43269a6dcd28d66bfafdbdd",
-                "sha256:65f31b622af739a802ca6fd1a3076fd0ae523f8485c52924a89561ba10c49b48",
-                "sha256:ae55bac364c405caa23a4f2d6cfecc6a0daada500274ffca4a9230e7129eac59",
-                "sha256:b778ce0c909a2653741cb4b1ac7015b5c130ab9c897611df43ae6a58523cb965"
+                "sha256:0b795072bb1bf87b8620120a6373a3c61bfcb8da7e5c2377f4bb23ff4f0b62c9",
+                "sha256:0d438c8ca703b1b714e82ed5b7a4412c82577040dadff479c08405e2a715564f",
+                "sha256:16a3cb5df5c56f696234ea9e65e227d1ebe9c18aa774d36ff42f532139066a5f",
+                "sha256:1edfd82a98c5161497bbb111b2b70c0813102ad7e0aa81cbeb34e64c93863005",
+                "sha256:2406dc1dda01c7f6060ab586e4601f18affb7a6b965c50a8c90ff07569cf782a",
+                "sha256:2858b2504c8697beb9357be01dc47ef86438cc1cb36ecb6991796d19475faa3e",
+                "sha256:2a7b7640167ab536c3cb90cfc3977c7094f1c5890d7eeede8b273c175c3910fd",
+                "sha256:3228b7a51e3ed533f5472f54f70fd0b0a64c48dc1649a0f0e809bec312934d7a",
+                "sha256:328b552513d4f95b0a2eea4c8573e112866107227661834652a8984766aa7656",
+                "sha256:39f4b0a6ae22a1c567cb0630c30dd082481f95c13ca528dc501a7766b9c718c0",
+                "sha256:3b0036c978cbcc4a4512278e98e3e6d9e6b834dc973206162eddf98b586ef1c6",
+                "sha256:3ea8c252d8df5e9166bcf3d9edced2af132f4ead8ac422eac723c5781063709a",
+                "sha256:41608c0acbe0899c852281978492f9ce2c6fbfaf60aff0cefc54a7c4516b822c",
+                "sha256:59d11674964b74a81b149d4ceaff2b674b3b0e4d0f10f0be1533e49c4a28408b",
+                "sha256:5e479df4b2d0f8f02133b7e4430098699450e1b2a826438af6bec9a400530957",
+                "sha256:684850fb1e3e55c9220aad007f8386d8e3e477c4ec9211ae54d968ecdca8c6f9",
+                "sha256:6ccc43d68b81c424e46192a778f97da94ee0630337c9bbe5b2ecc9b0c1c59001",
+                "sha256:6d42debaf55450643146fabe4b6817bb2a55b23698b0434107e892a43117285e",
+                "sha256:710376bf67d8ff4500a31d0c207b8941ff4fba5de6890a701d71680474fe2a60",
+                "sha256:756ae7efddd68d4ea7d89c636b703e14a0c686688d42f588b90778a3c2fc0564",
+                "sha256:77149002d9386fae303a4a162e6bce75cc2161347ad2ba06c2f0182561875d45",
+                "sha256:78e2f18a82b88cbc37d22365cf8d2b879a492faedb3f2975adb4ed8dfe994d3a",
+                "sha256:7d9b42127a6c0bdcc25c3dcf252bb3ddc70454fac593b1b6933ae091396deb13",
+                "sha256:8389d6044ee4e2037dca83e3f6994738550f6ee8cfb746762283fad9b932868f",
+                "sha256:9c1a81af067e72261c9cbe33ea792893e83bc6aa987bfbd6fdc1e5e7b22777c4",
+                "sha256:c1e0920909d916d3375c7a1fdb0b1c78e46170e8bb42792312b6eb6676b2f87f",
+                "sha256:c68fdf21c6f3573ae19c7ee65f9ff185649a060c9a06535e9c3a0ee0bbac9235",
+                "sha256:c733ef3bdcfe52a1a75564389bad4064352274036e7e234730526d155f04d914",
+                "sha256:c9c58b0b84055d8bc27b7df5a9d141df4ee6ff59821f922dd73155861282f6a3",
+                "sha256:d03abec50df423b026a5aa09656bd9d37f1e6a49271f123f31f9b8aed5dc3ea3",
+                "sha256:d2cfac21e31e841d60dc28c0ec7d4ec47a35c608cb8906435d47ef83ffb22150",
+                "sha256:dcc119db14757b0c7bce64042158307b9b1c76471e655751a61b57f5a0e4d78e",
+                "sha256:df3a7b258cc230a65245167a202dd07320a5af05f3d41da1488ba0fa05bc9347",
+                "sha256:df48a623c58180874d7407b4d9ec06a19b84ed47f60a3884345b1a5099c1818b",
+                "sha256:e1b95972a0ae3f248a899cdbac92ba2e01d731225f566569311043ce2226f5e7",
+                "sha256:f326b3c1bbfda5b9308252ee0dcb30b612ee92b0e105d4abec70335fab5b1245",
+                "sha256:f411cb22115cb15452d099fec0ee636b06cf81bfb40ed9c02d30c8dc2bc2e3d1"
             ],
             "index": "pypi",
-            "version": "==3.6.2"
+            "version": "==3.7.3"
         },
         "aiohttp-cors": {
             "hashes": [
@@ -53,14 +78,16 @@
                 "sha256:0c3c816a028d47f659d6ff5c745cb2acf1f966da1fe5c19c77a70282b25f4c5f",
                 "sha256:4291ca197d287d274d0b6cb5d6f8f8f82d434ed288f962539ff18cc9012f9ea3"
             ],
+            "markers": "python_full_version >= '3.5.3'",
             "version": "==3.0.1"
         },
         "attrs": {
             "hashes": [
-                "sha256:26b54ddbbb9ee1d34d5d3668dd37d6cf74990ab23c828c2888dccdceee395594",
-                "sha256:fce7fc47dfc976152e82d53ff92fa0407700c21acd20886a13777a0d20e655dc"
+                "sha256:31b2eced602aa8423c2aea9c76a724617ed67cf9513173fd3a4f03e3a929c7e6",
+                "sha256:832aa3cde19744e49938b91fea06d69ecb9e649c93ba974535d08ad92164f700"
             ],
-            "version": "==20.2.0"
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
+            "version": "==20.3.0"
         },
         "black": {
             "editable": true,
@@ -90,36 +117,60 @@
                 "sha256:6988bd2b895eef432d562370bb707d540f32f7360ab13da45340101bc2307d84"
             ],
             "index": "pypi",
-            "version": "==0.6"
+            "python_version <": "3.7",
+            "version": "==0.6",
+            "version >": "0.6"
         },
         "idna": {
             "hashes": [
                 "sha256:b307872f855b18632ce0c21c5e45be78c0ea7ae4c15c828c20788b26921eb3f6",
                 "sha256:b97d804b1e9b523befed77c48dacec60e6dcb0b5391d57af6a65a312a90648c0"
             ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==2.10"
         },
         "multidict": {
             "hashes": [
-                "sha256:1ece5a3369835c20ed57adadc663400b5525904e53bae59ec854a5d36b39b21a",
-                "sha256:275ca32383bc5d1894b6975bb4ca6a7ff16ab76fa622967625baeebcf8079000",
-                "sha256:3750f2205b800aac4bb03b5ae48025a64e474d2c6cc79547988ba1d4122a09e2",
-                "sha256:4538273208e7294b2659b1602490f4ed3ab1c8cf9dbdd817e0e9db8e64be2507",
-                "sha256:5141c13374e6b25fe6bf092052ab55c0c03d21bd66c94a0e3ae371d3e4d865a5",
-                "sha256:51a4d210404ac61d32dada00a50ea7ba412e6ea945bbe992e4d7a595276d2ec7",
-                "sha256:5cf311a0f5ef80fe73e4f4c0f0998ec08f954a6ec72b746f3c179e37de1d210d",
-                "sha256:6513728873f4326999429a8b00fc7ceddb2509b01d5fd3f3be7881a257b8d463",
-                "sha256:7388d2ef3c55a8ba80da62ecfafa06a1c097c18032a501ffd4cabbc52d7f2b19",
-                "sha256:9456e90649005ad40558f4cf51dbb842e32807df75146c6d940b6f5abb4a78f3",
-                "sha256:c026fe9a05130e44157b98fea3ab12969e5b60691a276150db9eda71710cd10b",
-                "sha256:d14842362ed4cf63751648e7672f7174c9818459d169231d03c56e84daf90b7c",
-                "sha256:e0d072ae0f2a179c375f67e3da300b47e1a83293c554450b29c900e50afaae87",
-                "sha256:f07acae137b71af3bb548bd8da720956a3bc9f9a0b87733e0899226a2317aeb7",
-                "sha256:fbb77a75e529021e7c4a8d4e823d88ef4d23674a202be4f5addffc72cbb91430",
-                "sha256:fcfbb44c59af3f8ea984de67ec7c306f618a3ec771c2843804069917a8f2e255",
-                "sha256:feed85993dbdb1dbc29102f50bca65bdc68f2c0c8d352468c25b54874f23c39d"
-            ],
-            "version": "==4.7.6"
+                "sha256:018132dbd8688c7a69ad89c4a3f39ea2f9f33302ebe567a879da8f4ca73f0d0a",
+                "sha256:051012ccee979b2b06be928a6150d237aec75dd6bf2d1eeeb190baf2b05abc93",
+                "sha256:05c20b68e512166fddba59a918773ba002fdd77800cad9f55b59790030bab632",
+                "sha256:07b42215124aedecc6083f1ce6b7e5ec5b50047afa701f3442054373a6deb656",
+                "sha256:0e3c84e6c67eba89c2dbcee08504ba8644ab4284863452450520dad8f1e89b79",
+                "sha256:0e929169f9c090dae0646a011c8b058e5e5fb391466016b39d21745b48817fd7",
+                "sha256:1ab820665e67373de5802acae069a6a05567ae234ddb129f31d290fc3d1aa56d",
+                "sha256:25b4e5f22d3a37ddf3effc0710ba692cfc792c2b9edfb9c05aefe823256e84d5",
+                "sha256:2e68965192c4ea61fff1b81c14ff712fc7dc15d2bd120602e4a3494ea6584224",
+                "sha256:2f1a132f1c88724674271d636e6b7351477c27722f2ed789f719f9e3545a3d26",
+                "sha256:37e5438e1c78931df5d3c0c78ae049092877e5e9c02dd1ff5abb9cf27a5914ea",
+                "sha256:3a041b76d13706b7fff23b9fc83117c7b8fe8d5fe9e6be45eee72b9baa75f348",
+                "sha256:3a4f32116f8f72ecf2a29dabfb27b23ab7cdc0ba807e8459e59a93a9be9506f6",
+                "sha256:46c73e09ad374a6d876c599f2328161bcd95e280f84d2060cf57991dec5cfe76",
+                "sha256:46dd362c2f045095c920162e9307de5ffd0a1bfbba0a6e990b344366f55a30c1",
+                "sha256:4b186eb7d6ae7c06eb4392411189469e6a820da81447f46c0072a41c748ab73f",
+                "sha256:54fd1e83a184e19c598d5e70ba508196fd0bbdd676ce159feb412a4a6664f952",
+                "sha256:585fd452dd7782130d112f7ddf3473ffdd521414674c33876187e101b588738a",
+                "sha256:5cf3443199b83ed9e955f511b5b241fd3ae004e3cb81c58ec10f4fe47c7dce37",
+                "sha256:6a4d5ce640e37b0efcc8441caeea8f43a06addace2335bd11151bc02d2ee31f9",
+                "sha256:7df80d07818b385f3129180369079bd6934cf70469f99daaebfac89dca288359",
+                "sha256:806068d4f86cb06af37cd65821554f98240a19ce646d3cd24e1c33587f313eb8",
+                "sha256:830f57206cc96ed0ccf68304141fec9481a096c4d2e2831f311bde1c404401da",
+                "sha256:929006d3c2d923788ba153ad0de8ed2e5ed39fdbe8e7be21e2f22ed06c6783d3",
+                "sha256:9436dc58c123f07b230383083855593550c4d301d2532045a17ccf6eca505f6d",
+                "sha256:9dd6e9b1a913d096ac95d0399bd737e00f2af1e1594a787e00f7975778c8b2bf",
+                "sha256:ace010325c787c378afd7f7c1ac66b26313b3344628652eacd149bdd23c68841",
+                "sha256:b47a43177a5e65b771b80db71e7be76c0ba23cc8aa73eeeb089ed5219cdbe27d",
+                "sha256:b797515be8743b771aa868f83563f789bbd4b236659ba52243b735d80b29ed93",
+                "sha256:b7993704f1a4b204e71debe6095150d43b2ee6150fa4f44d6d966ec356a8d61f",
+                "sha256:d5c65bdf4484872c4af3150aeebe101ba560dcfb34488d9a8ff8dbcd21079647",
+                "sha256:d81eddcb12d608cc08081fa88d046c78afb1bf8107e6feab5d43503fea74a635",
+                "sha256:dc862056f76443a0db4509116c5cd480fe1b6a2d45512a653f9a855cc0517456",
+                "sha256:ecc771ab628ea281517e24fd2c52e8f31c41e66652d07599ad8818abaad38cda",
+                "sha256:f200755768dc19c6f4e2b672421e0ebb3dd54c38d5a4f262b872d8cfcc9e93b5",
+                "sha256:f21756997ad8ef815d8ef3d34edd98804ab5ea337feedcd62fb52d22bf531281",
+                "sha256:fc13a9524bc18b6fb6e0dbec3533ba0496bbed167c56d0aabefd965584557d80"
+            ],
+            "markers": "python_version >= '3.6'",
+            "version": "==5.1.0"
         },
         "mypy-extensions": {
             "hashes": [
@@ -131,46 +182,80 @@
         },
         "pathspec": {
             "hashes": [
-                "sha256:7d91249d21749788d07a2d0f94147accd8f845507400749ea19c1ec9054a12b0",
-                "sha256:da45173eb3a6f2a5a487efba21f050af2b41948be6ab52b6a1e3ff22bb8b7061"
+                "sha256:86379d6b86d75816baba717e64b1a3a3469deb93bb76d613c9ce79edc5cb68fd",
+                "sha256:aa0cb481c4041bf52ffa7b0d8fa6cd3e88a2ca4879c533c9153882ee2556790d"
             ],
             "index": "pypi",
-            "version": "==0.8.0"
+            "version": "==0.8.1"
         },
         "regex": {
             "hashes": [
-                "sha256:0dc64ee3f33cd7899f79a8d788abfbec168410be356ed9bd30bbd3f0a23a7204",
-                "sha256:1269fef3167bb52631ad4fa7dd27bf635d5a0790b8e6222065d42e91bede4162",
-                "sha256:14a53646369157baa0499513f96091eb70382eb50b2c82393d17d7ec81b7b85f",
-                "sha256:3a3af27a8d23143c49a3420efe5b3f8cf1a48c6fc8bc6856b03f638abc1833bb",
-                "sha256:46bac5ca10fb748d6c55843a931855e2727a7a22584f302dd9bb1506e69f83f6",
-                "sha256:4c037fd14c5f4e308b8370b447b469ca10e69427966527edcab07f52d88388f7",
-                "sha256:51178c738d559a2d1071ce0b0f56e57eb315bcf8f7d4cf127674b533e3101f88",
-                "sha256:5ea81ea3dbd6767873c611687141ec7b06ed8bab43f68fad5b7be184a920dc99",
-                "sha256:6961548bba529cac7c07af2fd4d527c5b91bb8fe18995fed6044ac22b3d14644",
-                "sha256:75aaa27aa521a182824d89e5ab0a1d16ca207318a6b65042b046053cfc8ed07a",
-                "sha256:7a2dd66d2d4df34fa82c9dc85657c5e019b87932019947faece7983f2089a840",
-                "sha256:8a51f2c6d1f884e98846a0a9021ff6861bdb98457879f412fdc2b42d14494067",
-                "sha256:9c568495e35599625f7b999774e29e8d6b01a6fb684d77dee1f56d41b11b40cd",
-                "sha256:9eddaafb3c48e0900690c1727fba226c4804b8e6127ea409689c3bb492d06de4",
-                "sha256:bbb332d45b32df41200380fff14712cb6093b61bd142272a10b16778c418e98e",
-                "sha256:bc3d98f621898b4a9bc7fecc00513eec8f40b5b83913d74ccb445f037d58cd89",
-                "sha256:c11d6033115dc4887c456565303f540c44197f4fc1a2bfb192224a301534888e",
-                "sha256:c50a724d136ec10d920661f1442e4a8b010a4fe5aebd65e0c2241ea41dbe93dc",
-                "sha256:d0a5095d52b90ff38592bbdc2644f17c6d495762edf47d876049cfd2968fbccf",
-                "sha256:d6cff2276e502b86a25fd10c2a96973fdb45c7a977dca2138d661417f3728341",
-                "sha256:e46d13f38cfcbb79bfdb2964b0fe12561fe633caf964a77a5f8d4e45fe5d2ef7"
+                "sha256:02951b7dacb123d8ea6da44fe45ddd084aa6777d4b2454fa0da61d569c6fa538",
+                "sha256:0d08e71e70c0237883d0bef12cad5145b84c3705e9c6a588b2a9c7080e5af2a4",
+                "sha256:1862a9d9194fae76a7aaf0150d5f2a8ec1da89e8b55890b1786b8f88a0f619dc",
+                "sha256:1ab79fcb02b930de09c76d024d279686ec5d532eb814fd0ed1e0051eb8bd2daa",
+                "sha256:1fa7ee9c2a0e30405e21031d07d7ba8617bc590d391adfc2b7f1e8b99f46f444",
+                "sha256:262c6825b309e6485ec2493ffc7e62a13cf13fb2a8b6d212f72bd53ad34118f1",
+                "sha256:2a11a3e90bd9901d70a5b31d7dd85114755a581a5da3fc996abfefa48aee78af",
+                "sha256:2c99e97d388cd0a8d30f7c514d67887d8021541b875baf09791a3baad48bb4f8",
+                "sha256:3128e30d83f2e70b0bed9b2a34e92707d0877e460b402faca908c6667092ada9",
+                "sha256:38c8fd190db64f513fe4e1baa59fed086ae71fa45083b6936b52d34df8f86a88",
+                "sha256:3bddc701bdd1efa0d5264d2649588cbfda549b2899dc8d50417e47a82e1387ba",
+                "sha256:4902e6aa086cbb224241adbc2f06235927d5cdacffb2425c73e6570e8d862364",
+                "sha256:49cae022fa13f09be91b2c880e58e14b6da5d10639ed45ca69b85faf039f7a4e",
+                "sha256:56e01daca75eae420bce184edd8bb341c8eebb19dd3bce7266332258f9fb9dd7",
+                "sha256:5862975b45d451b6db51c2e654990c1820523a5b07100fc6903e9c86575202a0",
+                "sha256:6a8ce43923c518c24a2579fda49f093f1397dad5d18346211e46f134fc624e31",
+                "sha256:6c54ce4b5d61a7129bad5c5dc279e222afd00e721bf92f9ef09e4fae28755683",
+                "sha256:6e4b08c6f8daca7d8f07c8d24e4331ae7953333dbd09c648ed6ebd24db5a10ee",
+                "sha256:717881211f46de3ab130b58ec0908267961fadc06e44f974466d1887f865bd5b",
+                "sha256:749078d1eb89484db5f34b4012092ad14b327944ee7f1c4f74d6279a6e4d1884",
+                "sha256:7913bd25f4ab274ba37bc97ad0e21c31004224ccb02765ad984eef43e04acc6c",
+                "sha256:7a25fcbeae08f96a754b45bdc050e1fb94b95cab046bf56b016c25e9ab127b3e",
+                "sha256:83d6b356e116ca119db8e7c6fc2983289d87b27b3fac238cfe5dca529d884562",
+                "sha256:8b882a78c320478b12ff024e81dc7d43c1462aa4a3341c754ee65d857a521f85",
+                "sha256:8f6a2229e8ad946e36815f2a03386bb8353d4bde368fdf8ca5f0cb97264d3b5c",
+                "sha256:9801c4c1d9ae6a70aeb2128e5b4b68c45d4f0af0d1535500884d644fa9b768c6",
+                "sha256:a15f64ae3a027b64496a71ab1f722355e570c3fac5ba2801cafce846bf5af01d",
+                "sha256:a3d748383762e56337c39ab35c6ed4deb88df5326f97a38946ddd19028ecce6b",
+                "sha256:a63f1a07932c9686d2d416fb295ec2c01ab246e89b4d58e5fa468089cab44b70",
+                "sha256:b2b1a5ddae3677d89b686e5c625fc5547c6e492bd755b520de5332773a8af06b",
+                "sha256:b2f4007bff007c96a173e24dcda236e5e83bde4358a557f9ccf5e014439eae4b",
+                "sha256:baf378ba6151f6e272824b86a774326f692bc2ef4cc5ce8d5bc76e38c813a55f",
+                "sha256:bafb01b4688833e099d79e7efd23f99172f501a15c44f21ea2118681473fdba0",
+                "sha256:bba349276b126947b014e50ab3316c027cac1495992f10e5682dc677b3dfa0c5",
+                "sha256:c084582d4215593f2f1d28b65d2a2f3aceff8342aa85afd7be23a9cad74a0de5",
+                "sha256:d1ebb090a426db66dd80df8ca85adc4abfcbad8a7c2e9a5ec7513ede522e0a8f",
+                "sha256:d2d8ce12b7c12c87e41123997ebaf1a5767a5be3ec545f64675388970f415e2e",
+                "sha256:e32f5f3d1b1c663af7f9c4c1e72e6ffe9a78c03a31e149259f531e0fed826512",
+                "sha256:e3faaf10a0d1e8e23a9b51d1900b72e1635c2d5b0e1bea1c18022486a8e2e52d",
+                "sha256:f7d29a6fc4760300f86ae329e3b6ca28ea9c20823df123a2ea8693e967b29917",
+                "sha256:f8f295db00ef5f8bae530fc39af0b40486ca6068733fb860b42115052206466f"
             ],
             "index": "pypi",
-            "version": "==2020.7.14"
+            "version": "==2020.11.13"
+        },
+        "setuptools-scm": {
+            "hashes": [
+                "sha256:1fc4e25df445351d172bb4788f4d07f9e9ce0e8b7dee6b19584e46110172ca13",
+                "sha256:48b31488d089270500f120efea723968c01abd85fd4876043a3b7c7ef7d0b761",
+                "sha256:62fa535edb31ece9fa65dc9dcb3056145b8020c8c26c0ef1018aef33db95c40d",
+                "sha256:b928021c4381f96d577847d540d6e03065f8f8851c768a0c9bc552d463bae0d4",
+                "sha256:c85b6b46d0edd40d2301038cdea96bb6adc14d62ef943e75afb08b3e7bcf142a",
+                "sha256:db4ab2e0c2644ba71b1e5212b14ff65dbf0af465796d314a75e0cf6128f605f7",
+                "sha256:e878036c2527dfd05818727846338be86b2be6955741b85fab2625f63d001021",
+                "sha256:eb19b46816fc106a4c2d4180022687eab40f9773cf61390b845afb093d1f4ecd"
+            ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
+            "version": "==5.0.1"
         },
         "toml": {
             "hashes": [
-                "sha256:926b612be1e5ce0634a2ca03470f95169cf16f939018233a670519cb4ac58b0f",
-                "sha256:bda89d5935c2eac546d648028b9901107a595863cb36bae0c73ac804a9b4ce88"
+                "sha256:806143ae5bfb6a3c6e736a764057db0e6a0e05e338b5630894a5f779cabb4f9b",
+                "sha256:b3bda1d108d5dd99f4a20d24d9c348e91c4db7ab1b749200bded2f839ccbe68f"
             ],
             "index": "pypi",
-            "version": "==0.10.1"
+            "version": "==0.10.2"
         },
         "typed-ast": {
             "hashes": [
@@ -187,6 +272,7 @@
                 "sha256:6daac9731f172c2a22ade6ed0c00197ee7cc1221aa84cfdf9c31defeb059a907",
                 "sha256:715ff2f2df46121071622063fc7543d9b1fd19ebfc4f5c8895af64a77a8c852c",
                 "sha256:73d785a950fc82dd2a25897d525d003f6378d1cb23ab305578394694202a58c3",
+                "sha256:7e4c9d7658aaa1fc80018593abdf8598bf91325af6af5cce4ce7c73bc45ea53d",
                 "sha256:8c8aaad94455178e3187ab22c8b01a3837f8ee50e09cf31f1ba129eb293ec30b",
                 "sha256:8ce678dbaf790dbdb3eba24056d5364fb45944f33553dd5869b7580cdbb83614",
                 "sha256:92c325624e304ebf0e025d1224b77dd4e6393f18aab8d829b5b7e04afe9b7a2c",
@@ -198,8 +284,10 @@
                 "sha256:d43943ef777f9a1c42bf4e552ba23ac77a6351de620aa9acf64ad54933ad4d34",
                 "sha256:d5d33e9e7af3b34a40dc05f498939f0ebf187f07c385fd58d591c533ad8562fe",
                 "sha256:d648b8e3bf2fe648745c8ffcee3db3ff903d0817a01a12dd6a6ea7a8f4889072",
+                "sha256:f208eb7aff048f6bea9586e61af041ddf7f9ade7caed625742af423f6bae3298",
                 "sha256:fac11badff8313e23717f3dada86a15389d0708275bddf766cca67a84ead3e91",
                 "sha256:fc0fea399acb12edbf8a628ba8d2312f583bdbdb3335635db062fa98cf71fca4",
+                "sha256:fcf135e17cc74dbfbc05894ebca928ffeb23d9790b3167a674921db19082401f",
                 "sha256:fe460b922ec15dd205595c9b5b99e2f056fd98ae8f9f56b888e7a17dc2b757e7"
             ],
             "index": "pypi",
@@ -216,61 +304,91 @@
         },
         "yarl": {
             "hashes": [
-                "sha256:03b7a44384ad60be1b7be93c2a24dc74895f8d767ea0bce15b2f6fc7695a3843",
-                "sha256:076157404db9db4bb3fa9db22db319bbb36d075eeab19ba018ce20ae0cacf037",
-                "sha256:1c05ae3d5ea4287470046a2c2754f0a4c171b84ea72c8a691f776eb1753dfb91",
-                "sha256:2467baf8233f7c64048df37e11879c553943ffe7f373e689711ec2807ea13805",
-                "sha256:2bb2e21cf062dfbe985c3cd4618bae9f25271efcad9e7be1277861247eee9839",
-                "sha256:311effab3b3828ab34f0e661bb57ff422f67d5c33056298bda4c12195251f8dd",
-                "sha256:3526cb5905907f0e42bee7ef57ae4a5f02bc27dcac27859269e2bba0caa4c2b6",
-                "sha256:39b1e586f34b1d2512c9b39aa3cf24c870c972d525e36edc9ee19065db4737bb",
-                "sha256:4bed5cd7c8e69551eb19df15295ba90e62b9a6a1149c76eb4a9bab194402a156",
-                "sha256:51c6d3cf7a1f1fbe134bb92f33b7affd94d6de24cd64b466eb12de52120fb8c6",
-                "sha256:59f78b5da34ddcffb663b772f7619e296518712e022e57fc5d9f921818e2ab7c",
-                "sha256:6f29115b0c330da25a04f48612d75333bca04521181a666ca0b8761005a99150",
-                "sha256:73d4e1e1ef5e52d526c92f07d16329e1678612c6a81dd8101fdcae11a72de15c",
-                "sha256:9b48d31f8d881713fd461abfe7acbb4dcfeb47cec3056aa83f2fbcd2244577f7",
-                "sha256:a1fd575dd058e10ad4c35065e7c3007cc74d142f622b14e168d8a273a2fa8713",
-                "sha256:b3dd1052afd436ba737e61f5d3bed1f43a7f9a33fc58fbe4226eb919a7006019",
-                "sha256:b99c25ed5c355b35d1e6dae87ac7297a4844a57dc5766b173b88b6163a36eb0d",
-                "sha256:c056e86bff5a0b566e0d9fab4f67e83b12ae9cbcd250d334cbe2005bbe8c96f2",
-                "sha256:c45b49b59a5724869899798e1bbd447ac486215269511d3b76b4c235a1b766b6",
-                "sha256:cd623170c729a865037828e3f99f8ebdb22a467177a539680dfc5670b74c84e2",
-                "sha256:d25d3311794e6c71b608d7c47651c8f65eea5ab15358a27f29330b3475e8f8e5",
-                "sha256:d695439c201ed340745250f9eb4dfe8d32bf1e680c16477107b8f3ce4bff4fdb",
-                "sha256:d77f6c9133d2aabb290a7846aaa74ec14d7b5ab35b01591fac5a70c4a8c959a2",
-                "sha256:d894a2442d2cd20a3b0b0dce5a353d316c57d25a2b445e03f7eac90eee27b8af",
-                "sha256:db643ce2b58a4bd11a82348225c53c76ecdd82bb37cf4c085e6df1b676f4038c",
-                "sha256:e3a0c43a26dfed955b2a06fdc4d51d2c51bc2200aff8ce8faf14e676ea8c8862",
-                "sha256:e77bf79ad1ccae672eab22453838382fe9029fc27c8029e84913855512a587d8",
-                "sha256:f2f0174cb15435957d3b751093f89aede77df59a499ab7516bbb633b77ead13a",
-                "sha256:f3031c78edf10315abe232254e6a36b65afe65fded41ee54ed7976d0b2cdf0da",
-                "sha256:f4c007156732866aa4507d619fe6f8f2748caabed4f66b276ccd97c82572620c",
-                "sha256:f4f27ff3dd80bc7c402def211a47291ea123d59a23f59fe18fc0e81e3e71f385",
-                "sha256:f57744fc61e118b5d114ae8077d8eb9df4d2d2c11e2af194e21f0c11ed9dcf6c",
-                "sha256:f835015a825980b65356e9520979a1564c56efea7da7d4b68a14d4a07a3a7336"
-            ],
-            "version": "==1.6.2"
+                "sha256:00d7ad91b6583602eb9c1d085a2cf281ada267e9a197e8b7cae487dadbfa293e",
+                "sha256:0355a701b3998dcd832d0dc47cc5dedf3874f966ac7f870e0f3a6788d802d434",
+                "sha256:15263c3b0b47968c1d90daa89f21fcc889bb4b1aac5555580d74565de6836366",
+                "sha256:2ce4c621d21326a4a5500c25031e102af589edb50c09b321049e388b3934eec3",
+                "sha256:31ede6e8c4329fb81c86706ba8f6bf661a924b53ba191b27aa5fcee5714d18ec",
+                "sha256:324ba3d3c6fee56e2e0b0d09bf5c73824b9f08234339d2b788af65e60040c959",
+                "sha256:329412812ecfc94a57cd37c9d547579510a9e83c516bc069470db5f75684629e",
+                "sha256:4736eaee5626db8d9cda9eb5282028cc834e2aeb194e0d8b50217d707e98bb5c",
+                "sha256:4953fb0b4fdb7e08b2f3b3be80a00d28c5c8a2056bb066169de00e6501b986b6",
+                "sha256:4c5bcfc3ed226bf6419f7a33982fb4b8ec2e45785a0561eb99274ebbf09fdd6a",
+                "sha256:547f7665ad50fa8563150ed079f8e805e63dd85def6674c97efd78eed6c224a6",
+                "sha256:5b883e458058f8d6099e4420f0cc2567989032b5f34b271c0827de9f1079a424",
+                "sha256:63f90b20ca654b3ecc7a8d62c03ffa46999595f0167d6450fa8383bab252987e",
+                "sha256:68dc568889b1c13f1e4745c96b931cc94fdd0defe92a72c2b8ce01091b22e35f",
+                "sha256:69ee97c71fee1f63d04c945f56d5d726483c4762845400a6795a3b75d56b6c50",
+                "sha256:6d6283d8e0631b617edf0fd726353cb76630b83a089a40933043894e7f6721e2",
+                "sha256:72a660bdd24497e3e84f5519e57a9ee9220b6f3ac4d45056961bf22838ce20cc",
+                "sha256:73494d5b71099ae8cb8754f1df131c11d433b387efab7b51849e7e1e851f07a4",
+                "sha256:7356644cbed76119d0b6bd32ffba704d30d747e0c217109d7979a7bc36c4d970",
+                "sha256:8a9066529240171b68893d60dca86a763eae2139dd42f42106b03cf4b426bf10",
+                "sha256:8aa3decd5e0e852dc68335abf5478a518b41bf2ab2f330fe44916399efedfae0",
+                "sha256:97b5bdc450d63c3ba30a127d018b866ea94e65655efaf889ebeabc20f7d12406",
+                "sha256:9ede61b0854e267fd565e7527e2f2eb3ef8858b301319be0604177690e1a3896",
+                "sha256:b2e9a456c121e26d13c29251f8267541bd75e6a1ccf9e859179701c36a078643",
+                "sha256:b5dfc9a40c198334f4f3f55880ecf910adebdcb2a0b9a9c23c9345faa9185721",
+                "sha256:bafb450deef6861815ed579c7a6113a879a6ef58aed4c3a4be54400ae8871478",
+                "sha256:c49ff66d479d38ab863c50f7bb27dee97c6627c5fe60697de15529da9c3de724",
+                "sha256:ce3beb46a72d9f2190f9e1027886bfc513702d748047b548b05dab7dfb584d2e",
+                "sha256:d26608cf178efb8faa5ff0f2d2e77c208f471c5a3709e577a7b3fd0445703ac8",
+                "sha256:d597767fcd2c3dc49d6eea360c458b65643d1e4dbed91361cf5e36e53c1f8c96",
+                "sha256:d5c32c82990e4ac4d8150fd7652b972216b204de4e83a122546dce571c1bdf25",
+                "sha256:d8d07d102f17b68966e2de0e07bfd6e139c7c02ef06d3a0f8d2f0f055e13bb76",
+                "sha256:e46fba844f4895b36f4c398c5af062a9808d1f26b2999c58909517384d5deda2",
+                "sha256:e6b5460dc5ad42ad2b36cca524491dfcaffbfd9c8df50508bddc354e787b8dc2",
+                "sha256:f040bcc6725c821a4c0665f3aa96a4d0805a7aaf2caf266d256b8ed71b9f041c",
+                "sha256:f0b059678fd549c66b89bed03efcabb009075bd131c248ecdf087bdb6faba24a",
+                "sha256:fcbb48a93e8699eae920f8d92f7160c03567b421bc17362a9ffbbd706a816f71"
+            ],
+            "markers": "python_version >= '3.6'",
+            "version": "==1.6.3"
         }
     },
     "develop": {
         "aiohttp": {
             "hashes": [
-                "sha256:1e984191d1ec186881ffaed4581092ba04f7c61582a177b187d3a2f07ed9719e",
-                "sha256:259ab809ff0727d0e834ac5e8a283dc5e3e0ecc30c4d80b3cd17a4139ce1f326",
-                "sha256:2f4d1a4fdce595c947162333353d4a44952a724fba9ca3205a3df99a33d1307a",
-                "sha256:32e5f3b7e511aa850829fbe5aa32eb455e5534eaa4b1ce93231d00e2f76e5654",
-                "sha256:344c780466b73095a72c616fac5ea9c4665add7fc129f285fbdbca3cccf4612a",
-                "sha256:460bd4237d2dbecc3b5ed57e122992f60188afe46e7319116da5eb8a9dfedba4",
-                "sha256:4c6efd824d44ae697814a2a85604d8e992b875462c6655da161ff18fd4f29f17",
-                "sha256:50aaad128e6ac62e7bf7bd1f0c0a24bc968a0c0590a726d5a955af193544bcec",
-                "sha256:6206a135d072f88da3e71cc501c59d5abffa9d0bb43269a6dcd28d66bfafdbdd",
-                "sha256:65f31b622af739a802ca6fd1a3076fd0ae523f8485c52924a89561ba10c49b48",
-                "sha256:ae55bac364c405caa23a4f2d6cfecc6a0daada500274ffca4a9230e7129eac59",
-                "sha256:b778ce0c909a2653741cb4b1ac7015b5c130ab9c897611df43ae6a58523cb965"
+                "sha256:0b795072bb1bf87b8620120a6373a3c61bfcb8da7e5c2377f4bb23ff4f0b62c9",
+                "sha256:0d438c8ca703b1b714e82ed5b7a4412c82577040dadff479c08405e2a715564f",
+                "sha256:16a3cb5df5c56f696234ea9e65e227d1ebe9c18aa774d36ff42f532139066a5f",
+                "sha256:1edfd82a98c5161497bbb111b2b70c0813102ad7e0aa81cbeb34e64c93863005",
+                "sha256:2406dc1dda01c7f6060ab586e4601f18affb7a6b965c50a8c90ff07569cf782a",
+                "sha256:2858b2504c8697beb9357be01dc47ef86438cc1cb36ecb6991796d19475faa3e",
+                "sha256:2a7b7640167ab536c3cb90cfc3977c7094f1c5890d7eeede8b273c175c3910fd",
+                "sha256:3228b7a51e3ed533f5472f54f70fd0b0a64c48dc1649a0f0e809bec312934d7a",
+                "sha256:328b552513d4f95b0a2eea4c8573e112866107227661834652a8984766aa7656",
+                "sha256:39f4b0a6ae22a1c567cb0630c30dd082481f95c13ca528dc501a7766b9c718c0",
+                "sha256:3b0036c978cbcc4a4512278e98e3e6d9e6b834dc973206162eddf98b586ef1c6",
+                "sha256:3ea8c252d8df5e9166bcf3d9edced2af132f4ead8ac422eac723c5781063709a",
+                "sha256:41608c0acbe0899c852281978492f9ce2c6fbfaf60aff0cefc54a7c4516b822c",
+                "sha256:59d11674964b74a81b149d4ceaff2b674b3b0e4d0f10f0be1533e49c4a28408b",
+                "sha256:5e479df4b2d0f8f02133b7e4430098699450e1b2a826438af6bec9a400530957",
+                "sha256:684850fb1e3e55c9220aad007f8386d8e3e477c4ec9211ae54d968ecdca8c6f9",
+                "sha256:6ccc43d68b81c424e46192a778f97da94ee0630337c9bbe5b2ecc9b0c1c59001",
+                "sha256:6d42debaf55450643146fabe4b6817bb2a55b23698b0434107e892a43117285e",
+                "sha256:710376bf67d8ff4500a31d0c207b8941ff4fba5de6890a701d71680474fe2a60",
+                "sha256:756ae7efddd68d4ea7d89c636b703e14a0c686688d42f588b90778a3c2fc0564",
+                "sha256:77149002d9386fae303a4a162e6bce75cc2161347ad2ba06c2f0182561875d45",
+                "sha256:78e2f18a82b88cbc37d22365cf8d2b879a492faedb3f2975adb4ed8dfe994d3a",
+                "sha256:7d9b42127a6c0bdcc25c3dcf252bb3ddc70454fac593b1b6933ae091396deb13",
+                "sha256:8389d6044ee4e2037dca83e3f6994738550f6ee8cfb746762283fad9b932868f",
+                "sha256:9c1a81af067e72261c9cbe33ea792893e83bc6aa987bfbd6fdc1e5e7b22777c4",
+                "sha256:c1e0920909d916d3375c7a1fdb0b1c78e46170e8bb42792312b6eb6676b2f87f",
+                "sha256:c68fdf21c6f3573ae19c7ee65f9ff185649a060c9a06535e9c3a0ee0bbac9235",
+                "sha256:c733ef3bdcfe52a1a75564389bad4064352274036e7e234730526d155f04d914",
+                "sha256:c9c58b0b84055d8bc27b7df5a9d141df4ee6ff59821f922dd73155861282f6a3",
+                "sha256:d03abec50df423b026a5aa09656bd9d37f1e6a49271f123f31f9b8aed5dc3ea3",
+                "sha256:d2cfac21e31e841d60dc28c0ec7d4ec47a35c608cb8906435d47ef83ffb22150",
+                "sha256:dcc119db14757b0c7bce64042158307b9b1c76471e655751a61b57f5a0e4d78e",
+                "sha256:df3a7b258cc230a65245167a202dd07320a5af05f3d41da1488ba0fa05bc9347",
+                "sha256:df48a623c58180874d7407b4d9ec06a19b84ed47f60a3884345b1a5099c1818b",
+                "sha256:e1b95972a0ae3f248a899cdbac92ba2e01d731225f566569311043ce2226f5e7",
+                "sha256:f326b3c1bbfda5b9308252ee0dcb30b612ee92b0e105d4abec70335fab5b1245",
+                "sha256:f411cb22115cb15452d099fec0ee636b06cf81bfb40ed9c02d30c8dc2bc2e3d1"
             ],
             "index": "pypi",
-            "version": "==3.6.2"
+            "version": "==3.7.3"
         },
         "aiohttp-cors": {
             "hashes": [
@@ -300,21 +418,24 @@
                 "sha256:0c3c816a028d47f659d6ff5c745cb2acf1f966da1fe5c19c77a70282b25f4c5f",
                 "sha256:4291ca197d287d274d0b6cb5d6f8f8f82d434ed288f962539ff18cc9012f9ea3"
             ],
+            "markers": "python_full_version >= '3.5.3'",
             "version": "==3.0.1"
         },
         "attrs": {
             "hashes": [
-                "sha256:26b54ddbbb9ee1d34d5d3668dd37d6cf74990ab23c828c2888dccdceee395594",
-                "sha256:fce7fc47dfc976152e82d53ff92fa0407700c21acd20886a13777a0d20e655dc"
+                "sha256:31b2eced602aa8423c2aea9c76a724617ed67cf9513173fd3a4f03e3a929c7e6",
+                "sha256:832aa3cde19744e49938b91fea06d69ecb9e649c93ba974535d08ad92164f700"
             ],
-            "version": "==20.2.0"
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
+            "version": "==20.3.0"
         },
         "babel": {
             "hashes": [
-                "sha256:1aac2ae2d0d8ea368fa90906567f5c08463d98ade155c0c4bfedd6a0f7160e38",
-                "sha256:d670ea0b10f8b723672d3a6abeb87b565b244da220d76b4dba1b66269ec152d4"
+                "sha256:9d35c22fcc79893c3ecc85ac4a56cde1ecf3f19c540bba0922308a6c06ca6fa5",
+                "sha256:da031ab54472314f210b0adcff1588ee5d1d1d0ba4dbd07b94dba82bde791e05"
             ],
-            "version": "==2.8.0"
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
+            "version": "==2.9.0"
         },
         "black": {
             "editable": true,
@@ -328,61 +449,22 @@
                 "sha256:52b5919b81842b1854196eaae5ca29679a2f2e378905c346d3ca8227c2c66080",
                 "sha256:9f8ccbeb6183c6e6cddea37592dfb0167485c1e3b13b3363bc325aa8bda3adbd"
             ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
             "version": "==3.2.1"
         },
         "certifi": {
             "hashes": [
-                "sha256:5930595817496dd21bb8dc35dad090f1c2cd0adfaf21204bf6732ca5d8ee34d3",
-                "sha256:8fc0819f1f30ba15bdb34cceffb9ef04d99f420f68eb75d901e9560b8749fc41"
-            ],
-            "version": "==2020.6.20"
-        },
-        "cffi": {
-            "hashes": [
-                "sha256:005f2bfe11b6745d726dbb07ace4d53f057de66e336ff92d61b8c7e9c8f4777d",
-                "sha256:09e96138280241bd355cd585148dec04dbbedb4f46128f340d696eaafc82dd7b",
-                "sha256:0b1ad452cc824665ddc682400b62c9e4f5b64736a2ba99110712fdee5f2505c4",
-                "sha256:0ef488305fdce2580c8b2708f22d7785ae222d9825d3094ab073e22e93dfe51f",
-                "sha256:15f351bed09897fbda218e4db5a3d5c06328862f6198d4fb385f3e14e19decb3",
-                "sha256:22399ff4870fb4c7ef19fff6eeb20a8bbf15571913c181c78cb361024d574579",
-                "sha256:23e5d2040367322824605bc29ae8ee9175200b92cb5483ac7d466927a9b3d537",
-                "sha256:2791f68edc5749024b4722500e86303a10d342527e1e3bcac47f35fbd25b764e",
-                "sha256:2f9674623ca39c9ebe38afa3da402e9326c245f0f5ceff0623dccdac15023e05",
-                "sha256:3363e77a6176afb8823b6e06db78c46dbc4c7813b00a41300a4873b6ba63b171",
-                "sha256:33c6cdc071ba5cd6d96769c8969a0531be2d08c2628a0143a10a7dcffa9719ca",
-                "sha256:3b8eaf915ddc0709779889c472e553f0d3e8b7bdf62dab764c8921b09bf94522",
-                "sha256:3cb3e1b9ec43256c4e0f8d2837267a70b0e1ca8c4f456685508ae6106b1f504c",
-                "sha256:3eeeb0405fd145e714f7633a5173318bd88d8bbfc3dd0a5751f8c4f70ae629bc",
-                "sha256:44f60519595eaca110f248e5017363d751b12782a6f2bd6a7041cba275215f5d",
-                "sha256:4d7c26bfc1ea9f92084a1d75e11999e97b62d63128bcc90c3624d07813c52808",
-                "sha256:529c4ed2e10437c205f38f3691a68be66c39197d01062618c55f74294a4a4828",
-                "sha256:6642f15ad963b5092d65aed022d033c77763515fdc07095208f15d3563003869",
-                "sha256:85ba797e1de5b48aa5a8427b6ba62cf69607c18c5d4eb747604b7302f1ec382d",
-                "sha256:8f0f1e499e4000c4c347a124fa6a27d37608ced4fe9f7d45070563b7c4c370c9",
-                "sha256:a624fae282e81ad2e4871bdb767e2c914d0539708c0f078b5b355258293c98b0",
-                "sha256:b0358e6fefc74a16f745afa366acc89f979040e0cbc4eec55ab26ad1f6a9bfbc",
-                "sha256:bbd2f4dfee1079f76943767fce837ade3087b578aeb9f69aec7857d5bf25db15",
-                "sha256:bf39a9e19ce7298f1bd6a9758fa99707e9e5b1ebe5e90f2c3913a47bc548747c",
-                "sha256:c11579638288e53fc94ad60022ff1b67865363e730ee41ad5e6f0a17188b327a",
-                "sha256:c150eaa3dadbb2b5339675b88d4573c1be3cb6f2c33a6c83387e10cc0bf05bd3",
-                "sha256:c53af463f4a40de78c58b8b2710ade243c81cbca641e34debf3396a9640d6ec1",
-                "sha256:cb763ceceae04803adcc4e2d80d611ef201c73da32d8f2722e9d0ab0c7f10768",
-                "sha256:cc75f58cdaf043fe6a7a6c04b3b5a0e694c6a9e24050967747251fb80d7bce0d",
-                "sha256:d80998ed59176e8cba74028762fbd9b9153b9afc71ea118e63bbf5d4d0f9552b",
-                "sha256:de31b5164d44ef4943db155b3e8e17929707cac1e5bd2f363e67a56e3af4af6e",
-                "sha256:e66399cf0fc07de4dce4f588fc25bfe84a6d1285cc544e67987d22663393926d",
-                "sha256:f0620511387790860b249b9241c2f13c3a80e21a73e0b861a2df24e9d6f56730",
-                "sha256:f4eae045e6ab2bb54ca279733fe4eb85f1effda392666308250714e01907f394",
-                "sha256:f92cdecb618e5fa4658aeb97d5eb3d2f47aa94ac6477c6daf0f306c5a3b9e6b1",
-                "sha256:f92f789e4f9241cd262ad7a555ca2c648a98178a953af117ef7fad46aa1d5591"
-            ],
-            "version": "==1.14.3"
+                "sha256:1a4995114262bffbc2413b159f2a1a480c969de6e6eb13ee966d470af86af59c",
+                "sha256:719a74fb9e33b9bd44cc7f3a8d94bc35e4049deebe19ba7d8e108280cfd59830"
+            ],
+            "version": "==2020.12.5"
         },
         "cfgv": {
             "hashes": [
                 "sha256:32e43d604bbe7896fe7c248a9c2276447dbef840feb28fe20494f62af110211d",
                 "sha256:cf22deb93d4bcf92f345a5c3cd39d3d41d6340adc60c78bbbd6588c384fda6a1"
             ],
+            "markers": "python_full_version >= '3.6.1'",
             "version": "==3.2.0"
         },
         "chardet": {
@@ -405,6 +487,7 @@
                 "sha256:5941b2b48a20143d2267e95b1c2a7603ce057ee39fd88e7329b0c292aa16869b",
                 "sha256:9f47eda37229f68eee03b24b9748937c7dc3868f906e8ba69fbcbdd3bc5dc3e2"
             ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
             "version": "==0.4.4"
         },
         "commonmark": {
@@ -454,34 +537,6 @@
             "index": "pypi",
             "version": "==5.3"
         },
-        "cryptography": {
-            "hashes": [
-                "sha256:22f8251f68953553af4f9c11ec5f191198bc96cff9f0ac5dd5ff94daede0ee6d",
-                "sha256:284e275e3c099a80831f9898fb5c9559120d27675c3521278faba54e584a7832",
-                "sha256:3e17d02941c0f169c5b877597ca8be895fca0e5e3eb882526a74aa4804380a98",
-                "sha256:52a47e60953679eea0b4d490ca3c241fb1b166a7b161847ef4667dfd49e7699d",
-                "sha256:57b8c1ed13b8aa386cabbfde3be175d7b155682470b0e259fecfe53850967f8a",
-                "sha256:6a8f64ed096d13f92d1f601a92d9fd1f1025dc73a2ca1ced46dcf5e0d4930943",
-                "sha256:6e8a3c7c45101a7eeee93102500e1b08f2307c717ff553fcb3c1127efc9b6917",
-                "sha256:7ef41304bf978f33cfb6f43ca13bb0faac0c99cda33693aa20ad4f5e34e8cb8f",
-                "sha256:87c2fffd61e934bc0e2c927c3764c20b22d7f5f7f812ee1a477de4c89b044ca6",
-                "sha256:88069392cd9a1e68d2cfd5c3a2b0d72a44ef3b24b8977a4f7956e9e3c4c9477a",
-                "sha256:8a0866891326d3badb17c5fd3e02c926b635e8923fa271b4813cd4d972a57ff3",
-                "sha256:8f0fd8b0751d75c4483c534b209e39e918f0d14232c0d8a2a76e687f64ced831",
-                "sha256:9a07e6d255053674506091d63ab4270a119e9fc83462c7ab1dbcb495b76307af",
-                "sha256:9a8580c9afcdcddabbd064c0a74f337af74ff4529cdf3a12fa2e9782d677a2e5",
-                "sha256:bd80bc156d3729b38cb227a5a76532aef693b7ac9e395eea8063ee50ceed46a5",
-                "sha256:d1cbc3426e6150583b22b517ef3720036d7e3152d428c864ff0f3fcad2b97591",
-                "sha256:e15ac84dcdb89f92424cbaca4b0b34e211e7ce3ee7b0ec0e4f3c55cee65fae5a",
-                "sha256:e4789b84f8dedf190148441f7c5bfe7244782d9cbb194a36e17b91e7d3e1cca9",
-                "sha256:f01c9116bfb3ad2831e125a73dcd957d173d6ddca7701528eff1e7d97972872c",
-                "sha256:f0e3986f6cce007216b23c490f093f35ce2068f3c244051e559f647f6731b7ae",
-                "sha256:f2aa3f8ba9e2e3fd49bd3de743b976ab192fbf0eb0348cebde5d2a9de0090a9f",
-                "sha256:fb70a4cedd69dc52396ee114416a3656e011fb0311fca55eb55c7be6ed9c8aef"
-            ],
-            "index": "pypi",
-            "version": "==3.2"
-        },
         "distlib": {
             "hashes": [
                 "sha256:8c09de2c67b3e7deef7184574fc060ab8a793e7adbb183d942c389c8b13c52fb",
@@ -492,6 +547,7 @@
         "docutils": {
             "hashes": [
                 "sha256:54a349c622ff31c91cbec43b0b512f113b5b24daf00e2ea530bb1bd9aac14849",
+                "sha256:ba4584f9107571ced0d2c7f56a5499c696215ba90797849c92d395979da68521",
                 "sha256:d2ddba74835cb090a1b627d3de4e7835c628d07ee461f7b4480f51af2fe4d448"
             ],
             "index": "pypi",
@@ -506,40 +562,34 @@
         },
         "flake8": {
             "hashes": [
-                "sha256:15e351d19611c887e482fb960eae4d44845013cc142d42896e9862f775d8cf5c",
-                "sha256:f04b9fcbac03b0a3e58c0ab3a0ecc462e023a9faf046d57794184028123aa208"
+                "sha256:749dbbd6bfd0cf1318af27bf97a14e28e5ff548ef8e5b1566ccfb25a11e7c839",
+                "sha256:aadae8761ec651813c24be05c6f7b4680857ef6afaae4651a4eccaef97ce6c3b"
             ],
             "index": "pypi",
-            "version": "==3.8.3"
+            "version": "==3.8.4"
         },
         "flake8-bugbear": {
             "hashes": [
-                "sha256:a3ddc03ec28ba2296fc6f89444d1c946a6b76460f859795b35b77d4920a51b63",
-                "sha256:bd02e4b009fb153fe6072c31c52aeab5b133d508095befb2ffcf3b41c4823162"
-            ],
-            "index": "pypi",
-            "version": "==20.1.4"
-        },
-        "flake8-mypy": {
-            "hashes": [
-                "sha256:47120db63aff631ee1f84bac6fe8e64731dc66da3efc1c51f85e15ade4a3ba18",
-                "sha256:cff009f4250e8391bf48990093cff85802778c345c8449d6498b62efefeebcbc"
+                "sha256:528020129fea2dea33a466b9d64ab650aa3e5f9ffc788b70ea4bc6cf18283538",
+                "sha256:f35b8135ece7a014bc0aee5b5d485334ac30a6da48494998cc1fabf7ec70d703"
             ],
             "index": "pypi",
-            "version": "==17.8.0"
+            "version": "==20.11.1"
         },
         "identify": {
             "hashes": [
-                "sha256:3139bf72d81dfd785b0a464e2776bd59bdc725b4cc10e6cf46b56a0db931c82e",
-                "sha256:969d844b7a85d32a5f9ac4e163df6e846d73c87c8b75847494ee8f4bd2186421"
+                "sha256:943cd299ac7f5715fcb3f684e2fc1594c1e0f22a90d15398e5888143bd4144b5",
+                "sha256:cc86e6a9a390879dcc2976cef169dd9cc48843ed70b7380f321d1b118163c60e"
             ],
-            "version": "==1.5.6"
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
+            "version": "==1.5.10"
         },
         "idna": {
             "hashes": [
                 "sha256:b307872f855b18632ce0c21c5e45be78c0ea7ae4c15c828c20788b26921eb3f6",
                 "sha256:b97d804b1e9b523befed77c48dacec60e6dcb0b5391d57af6a65a312a90648c0"
             ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==2.10"
         },
         "imagesize": {
@@ -547,29 +597,24 @@
                 "sha256:6965f19a6a2039c7d48bca7dba2473069ff854c36ae6f19d2cde309d998228a1",
                 "sha256:b1f6b5a4eab1f73479a50fb79fcf729514a900c341d8503d62a62dbc4127a2b1"
             ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==1.2.0"
         },
-        "jeepney": {
-            "hashes": [
-                "sha256:3479b861cc2b6407de5188695fa1a8d57e5072d7059322469b62628869b8e36e",
-                "sha256:d6c6b49683446d2407d2fe3acb7a368a77ff063f9182fe427da15d622adc24cf"
-            ],
-            "markers": "sys_platform == 'linux'",
-            "version": "==0.4.3"
-        },
         "jinja2": {
             "hashes": [
                 "sha256:89aab215427ef59c34ad58735269eb58b1a5808103067f7bb9d5836c651b3bb0",
                 "sha256:f0a4641d3cf955324a89c04f3d94663aa4d638abe8f733ecd3582848e1c37035"
             ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
             "version": "==2.11.2"
         },
         "keyring": {
             "hashes": [
-                "sha256:4e34ea2fdec90c1c43d6610b5a5fafa1b9097db1802948e90caf5763974b8f8d",
-                "sha256:9aeadd006a852b78f4b4ef7c7556c2774d2432bbef8ee538a3e9089ac8b11466"
+                "sha256:12de23258a95f3b13e5b167f7a641a878e91eab8ef16fafc077720a95e6115bb",
+                "sha256:207bd66f2a9881c835dad653da04e196c678bf104f8252141d2d3c4f31051579"
             ],
-            "version": "==21.4.0"
+            "markers": "python_version >= '3.6'",
+            "version": "==21.5.0"
         },
         "markupsafe": {
             "hashes": [
@@ -607,6 +652,7 @@
                 "sha256:e249096428b3ae81b08327a63a485ad0878de3fb939049038579ac0ef61e17e7",
                 "sha256:e8313f01ba26fbbe36c7be1966a7b7424942f670f38e666995b88d012765b9be"
             ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==1.1.1"
         },
         "mccabe": {
@@ -618,45 +664,66 @@
         },
         "multidict": {
             "hashes": [
-                "sha256:1ece5a3369835c20ed57adadc663400b5525904e53bae59ec854a5d36b39b21a",
-                "sha256:275ca32383bc5d1894b6975bb4ca6a7ff16ab76fa622967625baeebcf8079000",
-                "sha256:3750f2205b800aac4bb03b5ae48025a64e474d2c6cc79547988ba1d4122a09e2",
-                "sha256:4538273208e7294b2659b1602490f4ed3ab1c8cf9dbdd817e0e9db8e64be2507",
-                "sha256:5141c13374e6b25fe6bf092052ab55c0c03d21bd66c94a0e3ae371d3e4d865a5",
-                "sha256:51a4d210404ac61d32dada00a50ea7ba412e6ea945bbe992e4d7a595276d2ec7",
-                "sha256:5cf311a0f5ef80fe73e4f4c0f0998ec08f954a6ec72b746f3c179e37de1d210d",
-                "sha256:6513728873f4326999429a8b00fc7ceddb2509b01d5fd3f3be7881a257b8d463",
-                "sha256:7388d2ef3c55a8ba80da62ecfafa06a1c097c18032a501ffd4cabbc52d7f2b19",
-                "sha256:9456e90649005ad40558f4cf51dbb842e32807df75146c6d940b6f5abb4a78f3",
-                "sha256:c026fe9a05130e44157b98fea3ab12969e5b60691a276150db9eda71710cd10b",
-                "sha256:d14842362ed4cf63751648e7672f7174c9818459d169231d03c56e84daf90b7c",
-                "sha256:e0d072ae0f2a179c375f67e3da300b47e1a83293c554450b29c900e50afaae87",
-                "sha256:f07acae137b71af3bb548bd8da720956a3bc9f9a0b87733e0899226a2317aeb7",
-                "sha256:fbb77a75e529021e7c4a8d4e823d88ef4d23674a202be4f5addffc72cbb91430",
-                "sha256:fcfbb44c59af3f8ea984de67ec7c306f618a3ec771c2843804069917a8f2e255",
-                "sha256:feed85993dbdb1dbc29102f50bca65bdc68f2c0c8d352468c25b54874f23c39d"
-            ],
-            "version": "==4.7.6"
+                "sha256:018132dbd8688c7a69ad89c4a3f39ea2f9f33302ebe567a879da8f4ca73f0d0a",
+                "sha256:051012ccee979b2b06be928a6150d237aec75dd6bf2d1eeeb190baf2b05abc93",
+                "sha256:05c20b68e512166fddba59a918773ba002fdd77800cad9f55b59790030bab632",
+                "sha256:07b42215124aedecc6083f1ce6b7e5ec5b50047afa701f3442054373a6deb656",
+                "sha256:0e3c84e6c67eba89c2dbcee08504ba8644ab4284863452450520dad8f1e89b79",
+                "sha256:0e929169f9c090dae0646a011c8b058e5e5fb391466016b39d21745b48817fd7",
+                "sha256:1ab820665e67373de5802acae069a6a05567ae234ddb129f31d290fc3d1aa56d",
+                "sha256:25b4e5f22d3a37ddf3effc0710ba692cfc792c2b9edfb9c05aefe823256e84d5",
+                "sha256:2e68965192c4ea61fff1b81c14ff712fc7dc15d2bd120602e4a3494ea6584224",
+                "sha256:2f1a132f1c88724674271d636e6b7351477c27722f2ed789f719f9e3545a3d26",
+                "sha256:37e5438e1c78931df5d3c0c78ae049092877e5e9c02dd1ff5abb9cf27a5914ea",
+                "sha256:3a041b76d13706b7fff23b9fc83117c7b8fe8d5fe9e6be45eee72b9baa75f348",
+                "sha256:3a4f32116f8f72ecf2a29dabfb27b23ab7cdc0ba807e8459e59a93a9be9506f6",
+                "sha256:46c73e09ad374a6d876c599f2328161bcd95e280f84d2060cf57991dec5cfe76",
+                "sha256:46dd362c2f045095c920162e9307de5ffd0a1bfbba0a6e990b344366f55a30c1",
+                "sha256:4b186eb7d6ae7c06eb4392411189469e6a820da81447f46c0072a41c748ab73f",
+                "sha256:54fd1e83a184e19c598d5e70ba508196fd0bbdd676ce159feb412a4a6664f952",
+                "sha256:585fd452dd7782130d112f7ddf3473ffdd521414674c33876187e101b588738a",
+                "sha256:5cf3443199b83ed9e955f511b5b241fd3ae004e3cb81c58ec10f4fe47c7dce37",
+                "sha256:6a4d5ce640e37b0efcc8441caeea8f43a06addace2335bd11151bc02d2ee31f9",
+                "sha256:7df80d07818b385f3129180369079bd6934cf70469f99daaebfac89dca288359",
+                "sha256:806068d4f86cb06af37cd65821554f98240a19ce646d3cd24e1c33587f313eb8",
+                "sha256:830f57206cc96ed0ccf68304141fec9481a096c4d2e2831f311bde1c404401da",
+                "sha256:929006d3c2d923788ba153ad0de8ed2e5ed39fdbe8e7be21e2f22ed06c6783d3",
+                "sha256:9436dc58c123f07b230383083855593550c4d301d2532045a17ccf6eca505f6d",
+                "sha256:9dd6e9b1a913d096ac95d0399bd737e00f2af1e1594a787e00f7975778c8b2bf",
+                "sha256:ace010325c787c378afd7f7c1ac66b26313b3344628652eacd149bdd23c68841",
+                "sha256:b47a43177a5e65b771b80db71e7be76c0ba23cc8aa73eeeb089ed5219cdbe27d",
+                "sha256:b797515be8743b771aa868f83563f789bbd4b236659ba52243b735d80b29ed93",
+                "sha256:b7993704f1a4b204e71debe6095150d43b2ee6150fa4f44d6d966ec356a8d61f",
+                "sha256:d5c65bdf4484872c4af3150aeebe101ba560dcfb34488d9a8ff8dbcd21079647",
+                "sha256:d81eddcb12d608cc08081fa88d046c78afb1bf8107e6feab5d43503fea74a635",
+                "sha256:dc862056f76443a0db4509116c5cd480fe1b6a2d45512a653f9a855cc0517456",
+                "sha256:ecc771ab628ea281517e24fd2c52e8f31c41e66652d07599ad8818abaad38cda",
+                "sha256:f200755768dc19c6f4e2b672421e0ebb3dd54c38d5a4f262b872d8cfcc9e93b5",
+                "sha256:f21756997ad8ef815d8ef3d34edd98804ab5ea337feedcd62fb52d22bf531281",
+                "sha256:fc13a9524bc18b6fb6e0dbec3533ba0496bbed167c56d0aabefd965584557d80"
+            ],
+            "markers": "python_version >= '3.6'",
+            "version": "==5.1.0"
         },
         "mypy": {
             "hashes": [
-                "sha256:2c6cde8aa3426c1682d35190b59b71f661237d74b053822ea3d748e2c9578a7c",
-                "sha256:3fdda71c067d3ddfb21da4b80e2686b71e9e5c72cca65fa216d207a358827f86",
-                "sha256:5dd13ff1f2a97f94540fd37a49e5d255950ebcdf446fb597463a40d0df3fac8b",
-                "sha256:6731603dfe0ce4352c555c6284c6db0dc935b685e9ce2e4cf220abe1e14386fd",
-                "sha256:6bb93479caa6619d21d6e7160c552c1193f6952f0668cdda2f851156e85186fc",
-                "sha256:81c7908b94239c4010e16642c9102bfc958ab14e36048fa77d0be3289dda76ea",
-                "sha256:9c7a9a7ceb2871ba4bac1cf7217a7dd9ccd44c27c2950edbc6dc08530f32ad4e",
-                "sha256:a4a2cbcfc4cbf45cd126f531dedda8485671545b43107ded25ce952aac6fb308",
-                "sha256:b7fbfabdbcc78c4f6fc4712544b9b0d6bf171069c6e0e3cb82440dd10ced3406",
-                "sha256:c05b9e4fb1d8a41d41dec8786c94f3b95d3c5f528298d769eb8e73d293abc48d",
-                "sha256:d7df6eddb6054d21ca4d3c6249cae5578cb4602951fd2b6ee2f5510ffb098707",
-                "sha256:e0b61738ab504e656d1fe4ff0c0601387a5489ca122d55390ade31f9ca0e252d",
-                "sha256:eff7d4a85e9eea55afa34888dfeaccde99e7520b51f867ac28a48492c0b1130c",
-                "sha256:f05644db6779387ccdb468cc47a44b4356fc2ffa9287135d05b70a98dc83b89a"
+                "sha256:0a0d102247c16ce93c97066443d11e2d36e6cc2a32d8ccc1f705268970479324",
+                "sha256:0d34d6b122597d48a36d6c59e35341f410d4abfa771d96d04ae2c468dd201abc",
+                "sha256:2170492030f6faa537647d29945786d297e4862765f0b4ac5930ff62e300d802",
+                "sha256:2842d4fbd1b12ab422346376aad03ff5d0805b706102e475e962370f874a5122",
+                "sha256:2b21ba45ad9ef2e2eb88ce4aeadd0112d0f5026418324176fd494a6824b74975",
+                "sha256:72060bf64f290fb629bd4a67c707a66fd88ca26e413a91384b18db3876e57ed7",
+                "sha256:af4e9ff1834e565f1baa74ccf7ae2564ae38c8df2a85b057af1dbbc958eb6666",
+                "sha256:bd03b3cf666bff8d710d633d1c56ab7facbdc204d567715cb3b9f85c6e94f669",
+                "sha256:c614194e01c85bb2e551c421397e49afb2872c88b5830e3554f0519f9fb1c178",
+                "sha256:cf4e7bf7f1214826cf7333627cb2547c0db7e3078723227820d0a2490f117a01",
+                "sha256:da56dedcd7cd502ccd3c5dddc656cb36113dd793ad466e894574125945653cea",
+                "sha256:e86bdace26c5fe9cf8cb735e7cedfe7850ad92b327ac5d797c656717d2ca66de",
+                "sha256:e97e9c13d67fbe524be17e4d8025d51a7dca38f90de2e462243ab8ed8a9178d1",
+                "sha256:eea260feb1830a627fb526d22fbb426b750d9f5a47b624e8d5e7e004359b219c"
             ],
             "index": "pypi",
-            "version": "==0.782"
+            "version": "==0.790"
         },
         "mypy-extensions": {
             "hashes": [
@@ -675,18 +742,19 @@
         },
         "packaging": {
             "hashes": [
-                "sha256:4357f74f47b9c12db93624a82154e9b120fa8293699949152b22065d556079f8",
-                "sha256:998416ba6962ae7fbd6596850b80e17859a5753ba17c32284f67bfff33784181"
+                "sha256:24e0da08660a87484d1602c30bb4902d74816b6985b93de36926f5bc95741858",
+                "sha256:78598185a7008a470d64526a8059de9aaa449238f280fc9eb6b13ba6c4109093"
             ],
-            "version": "==20.4"
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
+            "version": "==20.8"
         },
         "pathspec": {
             "hashes": [
-                "sha256:7d91249d21749788d07a2d0f94147accd8f845507400749ea19c1ec9054a12b0",
-                "sha256:da45173eb3a6f2a5a487efba21f050af2b41948be6ab52b6a1e3ff22bb8b7061"
+                "sha256:86379d6b86d75816baba717e64b1a3a3469deb93bb76d613c9ce79edc5cb68fd",
+                "sha256:aa0cb481c4041bf52ffa7b0d8fa6cd3e88a2ca4879c533c9153882ee2556790d"
             ],
             "index": "pypi",
-            "version": "==0.8.0"
+            "version": "==0.8.1"
         },
         "pkginfo": {
             "hashes": [
@@ -697,64 +765,63 @@
         },
         "pre-commit": {
             "hashes": [
-                "sha256:810aef2a2ba4f31eed1941fc270e72696a1ad5590b9751839c90807d0fff6b9a",
-                "sha256:c54fd3e574565fe128ecc5e7d2f91279772ddb03f8729645fa812fe809084a70"
+                "sha256:6c86d977d00ddc8a60d68eec19f51ef212d9462937acf3ea37c7adec32284ac0",
+                "sha256:ee784c11953e6d8badb97d19bc46b997a3a9eded849881ec587accd8608d74a4"
             ],
             "index": "pypi",
-            "version": "==2.7.1"
+            "version": "==2.9.3"
         },
         "pycodestyle": {
             "hashes": [
                 "sha256:2295e7b2f6b5bd100585ebcb1f616591b652db8a741695b3d8f5d28bdc934367",
                 "sha256:c58a7d2815e0e8d7972bf1803331fb0152f867bd89adf8a01dfd55085434192e"
             ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==2.6.0"
         },
-        "pycparser": {
-            "hashes": [
-                "sha256:2d475327684562c3a96cc71adf7dc8c4f0565175cf86b6d7a404ff4c771f15f0",
-                "sha256:7582ad22678f0fcd81102833f60ef8d0e57288b6b5fb00323d101be910e35705"
-            ],
-            "version": "==2.20"
-        },
         "pyflakes": {
             "hashes": [
                 "sha256:0d94e0e05a19e57a99444b6ddcf9a6eb2e5c68d3ca1e98e90707af8152c90a92",
                 "sha256:35b2d75ee967ea93b55750aa9edbbf72813e06a66ba54438df2cfac9e3c27fc8"
             ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==2.2.0"
         },
         "pygments": {
             "hashes": [
-                "sha256:381985fcc551eb9d37c52088a32914e00517e57f4a21609f48141ba08e193fa0",
-                "sha256:88a0bbcd659fcb9573703957c6b9cff9fab7295e6e76db54c9d00ae42df32773"
+                "sha256:ccf3acacf3782cbed4a989426012f1c535c9a90d3a7fc3f16d231b9372d2b716",
+                "sha256:f275b6c0909e5dafd2d6269a656aa90fa58ebf4a74f8fcf9053195d226b24a08"
             ],
-            "version": "==2.7.2"
+            "markers": "python_version >= '3.5'",
+            "version": "==2.7.3"
         },
         "pyparsing": {
             "hashes": [
                 "sha256:c203ec8783bf771a155b207279b9bccb8dea02d8f0c9e5f8ead507bc3246ecc1",
                 "sha256:ef9d7589ef3c200abe66653d3f1ab1033c3c419ae9b9bdb1240a85b024efc88b"
             ],
+            "markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==2.4.7"
         },
         "pytz": {
             "hashes": [
-                "sha256:a494d53b6d39c3c6e44c3bec237336e14305e4f29bbf800b599253057fbb79ed",
-                "sha256:c35965d010ce31b23eeb663ed3cc8c906275d6be1a34393a1d73a41febf4a048"
+                "sha256:3e6b7dd2d1e0a59084bcee14a17af60c5c562cdc16d828e8eba2e683d3a7e268",
+                "sha256:5c55e189b682d420be27c6995ba6edce0c0a77dd67bfbe2ae6607134d5851ffd"
             ],
-            "version": "==2020.1"
+            "version": "==2020.4"
         },
         "pyyaml": {
             "hashes": [
                 "sha256:06a0d7ba600ce0b2d2fe2e78453a470b5a6e000a985dd4a4e54e436cc36b0e97",
                 "sha256:240097ff019d7c70a4922b6869d8a86407758333f02203e0fc6ff79c5dcede76",
                 "sha256:4f4b913ca1a7319b33cfb1369e91e50354d6f07a135f3b901aca02aa95940bd2",
+                "sha256:6034f55dab5fea9e53f436aa68fa3ace2634918e8b5994d82f3621c04ff5ed2e",
                 "sha256:69f00dca373f240f842b2931fb2c7e14ddbacd1397d57157a9b005a6a9942648",
                 "sha256:73f099454b799e05e5ab51423c7bcf361c58d3206fa7b0d555426b1f4d9a3eaf",
                 "sha256:74809a57b329d6cc0fdccee6318f44b9b8649961fa73144a98735b0aaf029f1f",
                 "sha256:7739fc0fa8205b3ee8808aea45e968bc90082c10aef6ea95e855e10abf4a37b2",
                 "sha256:95f71d2af0ff4227885f7a6605c37fd53d3a106fcab511b8860ecca9fcf400ee",
+                "sha256:ad9c67312c84def58f3c04504727ca879cb0013b2517c85a9a253f0cb6380c0a",
                 "sha256:b8eac752c5e14d3eca0e6dd9199cd627518cb5ec06add0de9d32baeee6fe645d",
                 "sha256:cc8955cfbfc7a115fa81d85284ee61147059a753344bc51098f3ccd69b0d7e0c",
                 "sha256:d13155f591e6fcc1ec3b30685d50bf0711574e2c0dfffd7644babf8b5102ca1a"
@@ -763,11 +830,11 @@
         },
         "readme-renderer": {
             "hashes": [
-                "sha256:cbe9db71defedd2428a1589cdc545f9bd98e59297449f69d721ef8f1cfced68d",
-                "sha256:cc4957a803106e820d05d14f71033092537a22daa4f406dfbdd61177e0936376"
+                "sha256:267854ac3b1530633c2394ead828afcd060fc273217c42ac36b6be9c42cd9a9d",
+                "sha256:6b7e5aa59210a40de72eb79931491eaf46fefca2952b9181268bd7c7c65c260a"
             ],
             "index": "pypi",
-            "version": "==26.0"
+            "version": "==28.0"
         },
         "recommonmark": {
             "hashes": [
@@ -779,37 +846,58 @@
         },
         "regex": {
             "hashes": [
-                "sha256:0dc64ee3f33cd7899f79a8d788abfbec168410be356ed9bd30bbd3f0a23a7204",
-                "sha256:1269fef3167bb52631ad4fa7dd27bf635d5a0790b8e6222065d42e91bede4162",
-                "sha256:14a53646369157baa0499513f96091eb70382eb50b2c82393d17d7ec81b7b85f",
-                "sha256:3a3af27a8d23143c49a3420efe5b3f8cf1a48c6fc8bc6856b03f638abc1833bb",
-                "sha256:46bac5ca10fb748d6c55843a931855e2727a7a22584f302dd9bb1506e69f83f6",
-                "sha256:4c037fd14c5f4e308b8370b447b469ca10e69427966527edcab07f52d88388f7",
-                "sha256:51178c738d559a2d1071ce0b0f56e57eb315bcf8f7d4cf127674b533e3101f88",
-                "sha256:5ea81ea3dbd6767873c611687141ec7b06ed8bab43f68fad5b7be184a920dc99",
-                "sha256:6961548bba529cac7c07af2fd4d527c5b91bb8fe18995fed6044ac22b3d14644",
-                "sha256:75aaa27aa521a182824d89e5ab0a1d16ca207318a6b65042b046053cfc8ed07a",
-                "sha256:7a2dd66d2d4df34fa82c9dc85657c5e019b87932019947faece7983f2089a840",
-                "sha256:8a51f2c6d1f884e98846a0a9021ff6861bdb98457879f412fdc2b42d14494067",
-                "sha256:9c568495e35599625f7b999774e29e8d6b01a6fb684d77dee1f56d41b11b40cd",
-                "sha256:9eddaafb3c48e0900690c1727fba226c4804b8e6127ea409689c3bb492d06de4",
-                "sha256:bbb332d45b32df41200380fff14712cb6093b61bd142272a10b16778c418e98e",
-                "sha256:bc3d98f621898b4a9bc7fecc00513eec8f40b5b83913d74ccb445f037d58cd89",
-                "sha256:c11d6033115dc4887c456565303f540c44197f4fc1a2bfb192224a301534888e",
-                "sha256:c50a724d136ec10d920661f1442e4a8b010a4fe5aebd65e0c2241ea41dbe93dc",
-                "sha256:d0a5095d52b90ff38592bbdc2644f17c6d495762edf47d876049cfd2968fbccf",
-                "sha256:d6cff2276e502b86a25fd10c2a96973fdb45c7a977dca2138d661417f3728341",
-                "sha256:e46d13f38cfcbb79bfdb2964b0fe12561fe633caf964a77a5f8d4e45fe5d2ef7"
+                "sha256:02951b7dacb123d8ea6da44fe45ddd084aa6777d4b2454fa0da61d569c6fa538",
+                "sha256:0d08e71e70c0237883d0bef12cad5145b84c3705e9c6a588b2a9c7080e5af2a4",
+                "sha256:1862a9d9194fae76a7aaf0150d5f2a8ec1da89e8b55890b1786b8f88a0f619dc",
+                "sha256:1ab79fcb02b930de09c76d024d279686ec5d532eb814fd0ed1e0051eb8bd2daa",
+                "sha256:1fa7ee9c2a0e30405e21031d07d7ba8617bc590d391adfc2b7f1e8b99f46f444",
+                "sha256:262c6825b309e6485ec2493ffc7e62a13cf13fb2a8b6d212f72bd53ad34118f1",
+                "sha256:2a11a3e90bd9901d70a5b31d7dd85114755a581a5da3fc996abfefa48aee78af",
+                "sha256:2c99e97d388cd0a8d30f7c514d67887d8021541b875baf09791a3baad48bb4f8",
+                "sha256:3128e30d83f2e70b0bed9b2a34e92707d0877e460b402faca908c6667092ada9",
+                "sha256:38c8fd190db64f513fe4e1baa59fed086ae71fa45083b6936b52d34df8f86a88",
+                "sha256:3bddc701bdd1efa0d5264d2649588cbfda549b2899dc8d50417e47a82e1387ba",
+                "sha256:4902e6aa086cbb224241adbc2f06235927d5cdacffb2425c73e6570e8d862364",
+                "sha256:49cae022fa13f09be91b2c880e58e14b6da5d10639ed45ca69b85faf039f7a4e",
+                "sha256:56e01daca75eae420bce184edd8bb341c8eebb19dd3bce7266332258f9fb9dd7",
+                "sha256:5862975b45d451b6db51c2e654990c1820523a5b07100fc6903e9c86575202a0",
+                "sha256:6a8ce43923c518c24a2579fda49f093f1397dad5d18346211e46f134fc624e31",
+                "sha256:6c54ce4b5d61a7129bad5c5dc279e222afd00e721bf92f9ef09e4fae28755683",
+                "sha256:6e4b08c6f8daca7d8f07c8d24e4331ae7953333dbd09c648ed6ebd24db5a10ee",
+                "sha256:717881211f46de3ab130b58ec0908267961fadc06e44f974466d1887f865bd5b",
+                "sha256:749078d1eb89484db5f34b4012092ad14b327944ee7f1c4f74d6279a6e4d1884",
+                "sha256:7913bd25f4ab274ba37bc97ad0e21c31004224ccb02765ad984eef43e04acc6c",
+                "sha256:7a25fcbeae08f96a754b45bdc050e1fb94b95cab046bf56b016c25e9ab127b3e",
+                "sha256:83d6b356e116ca119db8e7c6fc2983289d87b27b3fac238cfe5dca529d884562",
+                "sha256:8b882a78c320478b12ff024e81dc7d43c1462aa4a3341c754ee65d857a521f85",
+                "sha256:8f6a2229e8ad946e36815f2a03386bb8353d4bde368fdf8ca5f0cb97264d3b5c",
+                "sha256:9801c4c1d9ae6a70aeb2128e5b4b68c45d4f0af0d1535500884d644fa9b768c6",
+                "sha256:a15f64ae3a027b64496a71ab1f722355e570c3fac5ba2801cafce846bf5af01d",
+                "sha256:a3d748383762e56337c39ab35c6ed4deb88df5326f97a38946ddd19028ecce6b",
+                "sha256:a63f1a07932c9686d2d416fb295ec2c01ab246e89b4d58e5fa468089cab44b70",
+                "sha256:b2b1a5ddae3677d89b686e5c625fc5547c6e492bd755b520de5332773a8af06b",
+                "sha256:b2f4007bff007c96a173e24dcda236e5e83bde4358a557f9ccf5e014439eae4b",
+                "sha256:baf378ba6151f6e272824b86a774326f692bc2ef4cc5ce8d5bc76e38c813a55f",
+                "sha256:bafb01b4688833e099d79e7efd23f99172f501a15c44f21ea2118681473fdba0",
+                "sha256:bba349276b126947b014e50ab3316c027cac1495992f10e5682dc677b3dfa0c5",
+                "sha256:c084582d4215593f2f1d28b65d2a2f3aceff8342aa85afd7be23a9cad74a0de5",
+                "sha256:d1ebb090a426db66dd80df8ca85adc4abfcbad8a7c2e9a5ec7513ede522e0a8f",
+                "sha256:d2d8ce12b7c12c87e41123997ebaf1a5767a5be3ec545f64675388970f415e2e",
+                "sha256:e32f5f3d1b1c663af7f9c4c1e72e6ffe9a78c03a31e149259f531e0fed826512",
+                "sha256:e3faaf10a0d1e8e23a9b51d1900b72e1635c2d5b0e1bea1c18022486a8e2e52d",
+                "sha256:f7d29a6fc4760300f86ae329e3b6ca28ea9c20823df123a2ea8693e967b29917",
+                "sha256:f8f295db00ef5f8bae530fc39af0b40486ca6068733fb860b42115052206466f"
             ],
             "index": "pypi",
-            "version": "==2020.7.14"
+            "version": "==2020.11.13"
         },
         "requests": {
             "hashes": [
-                "sha256:b3559a131db72c33ee969480840fff4bb6dd111de7dd27c8ee1f820f4f00231b",
-                "sha256:fe75cc94a9443b9246fc7049224f75604b113c36acb93f87b80ed42c44cbb898"
+                "sha256:7f1a0b932f4a60a1a65caa4263921bb7d9ee911957e0ae4a23a6dd08185ad5f8",
+                "sha256:e786fa28d8c9154e6a4de5d46a1d921b8749f8b74e28bde23768e5e16eece998"
             ],
-            "version": "==2.24.0"
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
+            "version": "==2.25.0"
         },
         "requests-toolbelt": {
             "hashes": [
@@ -825,27 +913,26 @@
             ],
             "version": "==1.4.0"
         },
-        "secretstorage": {
-            "hashes": [
-                "sha256:15da8a989b65498e29be338b3b279965f1b8f09b9668bd8010da183024c8bff6",
-                "sha256:b5ec909dde94d4ae2fa26af7c089036997030f0cf0a5cb372b4cccabd81c143b"
-            ],
-            "markers": "sys_platform == 'linux'",
-            "version": "==3.1.2"
-        },
         "setuptools-scm": {
             "hashes": [
-                "sha256:69258e2eeba5f7ce1ed7a5f109519580fa3578250f8e4d6684859f86d1b15826",
-                "sha256:a8994582e716ec690f33fec70cca0f85bd23ec974e3f783233e4879090a7faa8"
+                "sha256:1fc4e25df445351d172bb4788f4d07f9e9ce0e8b7dee6b19584e46110172ca13",
+                "sha256:48b31488d089270500f120efea723968c01abd85fd4876043a3b7c7ef7d0b761",
+                "sha256:62fa535edb31ece9fa65dc9dcb3056145b8020c8c26c0ef1018aef33db95c40d",
+                "sha256:b928021c4381f96d577847d540d6e03065f8f8851c768a0c9bc552d463bae0d4",
+                "sha256:c85b6b46d0edd40d2301038cdea96bb6adc14d62ef943e75afb08b3e7bcf142a",
+                "sha256:db4ab2e0c2644ba71b1e5212b14ff65dbf0af465796d314a75e0cf6128f605f7",
+                "sha256:e878036c2527dfd05818727846338be86b2be6955741b85fab2625f63d001021",
+                "sha256:eb19b46816fc106a4c2d4180022687eab40f9773cf61390b845afb093d1f4ecd"
             ],
-            "index": "pypi",
-            "version": "==4.1.2"
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
+            "version": "==5.0.1"
         },
         "six": {
             "hashes": [
                 "sha256:30639c035cdb23534cd4aa2dd52c3bf48f06e5f4a941509c8bafd8ce11080259",
                 "sha256:8b74bedcbbbaca38ff6d7491d76f2b06b3592611af620f8426e82dddb04a5ced"
             ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==1.15.0"
         },
         "snowballstemmer": {
@@ -857,17 +944,18 @@
         },
         "sphinx": {
             "hashes": [
-                "sha256:321d6d9b16fa381a5306e5a0b76cd48ffbc588e6340059a729c6fdd66087e0e8",
-                "sha256:ce6fd7ff5b215af39e2fcd44d4a321f6694b4530b6f2b2109b64d120773faea0"
+                "sha256:1e8d592225447104d1172be415bc2972bd1357e3e12fdc76edf2261105db4300",
+                "sha256:d4e59ad4ea55efbb3c05cde3bfc83bfc14f0c95aa95c3d75346fcce186a47960"
             ],
             "index": "pypi",
-            "version": "==3.2.1"
+            "version": "==3.3.1"
         },
         "sphinxcontrib-applehelp": {
             "hashes": [
                 "sha256:806111e5e962be97c29ec4c1e7fe277bfd19e9652fb1a4392105b43e01af885a",
                 "sha256:a072735ec80e7675e3f432fcae8610ecf509c5f1869d17e2eecff44389cdbc58"
             ],
+            "markers": "python_version >= '3.5'",
             "version": "==1.0.2"
         },
         "sphinxcontrib-devhelp": {
@@ -875,6 +963,7 @@
                 "sha256:8165223f9a335cc1af7ffe1ed31d2871f325254c0423bc0c4c7cd1c1e4734a2e",
                 "sha256:ff7f1afa7b9642e7060379360a67e9c41e8f3121f2ce9164266f61b9f4b338e4"
             ],
+            "markers": "python_version >= '3.5'",
             "version": "==1.0.2"
         },
         "sphinxcontrib-htmlhelp": {
@@ -882,6 +971,7 @@
                 "sha256:3c0bc24a2c41e340ac37c85ced6dafc879ab485c095b1d65d2461ac2f7cca86f",
                 "sha256:e8f5bb7e31b2dbb25b9cc435c8ab7a79787ebf7f906155729338f3156d93659b"
             ],
+            "markers": "python_version >= '3.5'",
             "version": "==1.0.3"
         },
         "sphinxcontrib-jsmath": {
@@ -889,6 +979,7 @@
                 "sha256:2ec2eaebfb78f3f2078e73666b1415417a116cc848b72e5172e596c871103178",
                 "sha256:a9925e4a4587247ed2191a22df5f6970656cb8ca2bd6284309578f2153e0c4b8"
             ],
+            "markers": "python_version >= '3.5'",
             "version": "==1.0.1"
         },
         "sphinxcontrib-qthelp": {
@@ -896,6 +987,7 @@
                 "sha256:4c33767ee058b70dba89a6fc5c1892c0d57a54be67ddd3e7875a18d14cba5a72",
                 "sha256:bd9fc24bcb748a8d51fd4ecaade681350aa63009a347a8c14e637895444dfab6"
             ],
+            "markers": "python_version >= '3.5'",
             "version": "==1.0.3"
         },
         "sphinxcontrib-serializinghtml": {
@@ -903,22 +995,24 @@
                 "sha256:eaa0eccc86e982a9b939b2b82d12cc5d013385ba5eadcc7e4fed23f4405f77bc",
                 "sha256:f242a81d423f59617a8e5cf16f5d4d74e28ee9a66f9e5b637a18082991db5a9a"
             ],
+            "markers": "python_version >= '3.5'",
             "version": "==1.1.4"
         },
         "toml": {
             "hashes": [
-                "sha256:926b612be1e5ce0634a2ca03470f95169cf16f939018233a670519cb4ac58b0f",
-                "sha256:bda89d5935c2eac546d648028b9901107a595863cb36bae0c73ac804a9b4ce88"
+                "sha256:806143ae5bfb6a3c6e736a764057db0e6a0e05e338b5630894a5f779cabb4f9b",
+                "sha256:b3bda1d108d5dd99f4a20d24d9c348e91c4db7ab1b749200bded2f839ccbe68f"
             ],
             "index": "pypi",
-            "version": "==0.10.1"
+            "version": "==0.10.2"
         },
         "tqdm": {
             "hashes": [
-                "sha256:9ad44aaf0fc3697c06f6e05c7cf025dd66bc7bcb7613c66d85f4464c47ac8fad",
-                "sha256:ef54779f1c09f346b2b5a8e5c61f96fbcb639929e640e59f8cf810794f406432"
+                "sha256:38b658a3e4ecf9b4f6f8ff75ca16221ae3378b2e175d846b6b33ea3a20852cf5",
+                "sha256:d4f413aecb61c9779888c64ddf0c62910ad56dcbe857d8922bb505d4dbff0df1"
             ],
-            "version": "==4.51.0"
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
+            "version": "==4.54.1"
         },
         "twine": {
             "hashes": [
@@ -943,6 +1037,7 @@
                 "sha256:6daac9731f172c2a22ade6ed0c00197ee7cc1221aa84cfdf9c31defeb059a907",
                 "sha256:715ff2f2df46121071622063fc7543d9b1fd19ebfc4f5c8895af64a77a8c852c",
                 "sha256:73d785a950fc82dd2a25897d525d003f6378d1cb23ab305578394694202a58c3",
+                "sha256:7e4c9d7658aaa1fc80018593abdf8598bf91325af6af5cce4ce7c73bc45ea53d",
                 "sha256:8c8aaad94455178e3187ab22c8b01a3837f8ee50e09cf31f1ba129eb293ec30b",
                 "sha256:8ce678dbaf790dbdb3eba24056d5364fb45944f33553dd5869b7580cdbb83614",
                 "sha256:92c325624e304ebf0e025d1224b77dd4e6393f18aab8d829b5b7e04afe9b7a2c",
@@ -954,8 +1049,10 @@
                 "sha256:d43943ef777f9a1c42bf4e552ba23ac77a6351de620aa9acf64ad54933ad4d34",
                 "sha256:d5d33e9e7af3b34a40dc05f498939f0ebf187f07c385fd58d591c533ad8562fe",
                 "sha256:d648b8e3bf2fe648745c8ffcee3db3ff903d0817a01a12dd6a6ea7a8f4889072",
+                "sha256:f208eb7aff048f6bea9586e61af041ddf7f9ade7caed625742af423f6bae3298",
                 "sha256:fac11badff8313e23717f3dada86a15389d0708275bddf766cca67a84ead3e91",
                 "sha256:fc0fea399acb12edbf8a628ba8d2312f583bdbdb3335635db062fa98cf71fca4",
+                "sha256:fcf135e17cc74dbfbc05894ebca928ffeb23d9790b3167a674921db19082401f",
                 "sha256:fe460b922ec15dd205595c9b5b99e2f056fd98ae8f9f56b888e7a17dc2b757e7"
             ],
             "index": "pypi",
@@ -972,17 +1069,19 @@
         },
         "urllib3": {
             "hashes": [
-                "sha256:8d7eaa5a82a1cac232164990f04874c594c9453ec55eef02eab885aa02fc17a2",
-                "sha256:f5321fbe4bf3fefa0efd0bfe7fb14e90909eb62a48ccda331726b4319897dd5e"
+                "sha256:19188f96923873c92ccb987120ec4acaa12f0461fa9ce5d3d0772bc965a39e08",
+                "sha256:d8ff90d979214d7b4f8ce956e80f4028fc6860e4431f731ea4a8c08f23f99473"
             ],
-            "version": "==1.25.11"
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4' and python_version < '4'",
+            "version": "==1.26.2"
         },
         "virtualenv": {
             "hashes": [
-                "sha256:b0011228208944ce71052987437d3843e05690b2f23d1c7da4263fde104c97a2",
-                "sha256:b8d6110f493af256a40d65e29846c69340a947669eec8ce784fcf3dd3af28380"
+                "sha256:54b05fc737ea9c9ee9f8340f579e5da5b09fb64fd010ab5757eb90268616907c",
+                "sha256:b7a8ec323ee02fb2312f098b6b4c9de99559b462775bc8fe3627a73706603c1b"
             ],
-            "version": "==20.1.0"
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
+            "version": "==20.2.2"
         },
         "webencodings": {
             "hashes": [
@@ -993,49 +1092,54 @@
         },
         "wheel": {
             "hashes": [
-                "sha256:497add53525d16c173c2c1c733b8f655510e909ea78cc0e29d374243544b77a2",
-                "sha256:99a22d87add3f634ff917310a3d87e499f19e663413a52eb9232c447aa646c9f"
+                "sha256:78b5b185f0e5763c26ca1e324373aadd49182ca90e825f7853f4b2509215dc0e",
+                "sha256:e11eefd162658ea59a60a0f6c7d493a7190ea4b9a85e335b33489d9f17e0245e"
             ],
             "index": "pypi",
-            "version": "==0.35.1"
+            "version": "==0.36.2"
         },
         "yarl": {
             "hashes": [
-                "sha256:03b7a44384ad60be1b7be93c2a24dc74895f8d767ea0bce15b2f6fc7695a3843",
-                "sha256:076157404db9db4bb3fa9db22db319bbb36d075eeab19ba018ce20ae0cacf037",
-                "sha256:1c05ae3d5ea4287470046a2c2754f0a4c171b84ea72c8a691f776eb1753dfb91",
-                "sha256:2467baf8233f7c64048df37e11879c553943ffe7f373e689711ec2807ea13805",
-                "sha256:2bb2e21cf062dfbe985c3cd4618bae9f25271efcad9e7be1277861247eee9839",
-                "sha256:311effab3b3828ab34f0e661bb57ff422f67d5c33056298bda4c12195251f8dd",
-                "sha256:3526cb5905907f0e42bee7ef57ae4a5f02bc27dcac27859269e2bba0caa4c2b6",
-                "sha256:39b1e586f34b1d2512c9b39aa3cf24c870c972d525e36edc9ee19065db4737bb",
-                "sha256:4bed5cd7c8e69551eb19df15295ba90e62b9a6a1149c76eb4a9bab194402a156",
-                "sha256:51c6d3cf7a1f1fbe134bb92f33b7affd94d6de24cd64b466eb12de52120fb8c6",
-                "sha256:59f78b5da34ddcffb663b772f7619e296518712e022e57fc5d9f921818e2ab7c",
-                "sha256:6f29115b0c330da25a04f48612d75333bca04521181a666ca0b8761005a99150",
-                "sha256:73d4e1e1ef5e52d526c92f07d16329e1678612c6a81dd8101fdcae11a72de15c",
-                "sha256:9b48d31f8d881713fd461abfe7acbb4dcfeb47cec3056aa83f2fbcd2244577f7",
-                "sha256:a1fd575dd058e10ad4c35065e7c3007cc74d142f622b14e168d8a273a2fa8713",
-                "sha256:b3dd1052afd436ba737e61f5d3bed1f43a7f9a33fc58fbe4226eb919a7006019",
-                "sha256:b99c25ed5c355b35d1e6dae87ac7297a4844a57dc5766b173b88b6163a36eb0d",
-                "sha256:c056e86bff5a0b566e0d9fab4f67e83b12ae9cbcd250d334cbe2005bbe8c96f2",
-                "sha256:c45b49b59a5724869899798e1bbd447ac486215269511d3b76b4c235a1b766b6",
-                "sha256:cd623170c729a865037828e3f99f8ebdb22a467177a539680dfc5670b74c84e2",
-                "sha256:d25d3311794e6c71b608d7c47651c8f65eea5ab15358a27f29330b3475e8f8e5",
-                "sha256:d695439c201ed340745250f9eb4dfe8d32bf1e680c16477107b8f3ce4bff4fdb",
-                "sha256:d77f6c9133d2aabb290a7846aaa74ec14d7b5ab35b01591fac5a70c4a8c959a2",
-                "sha256:d894a2442d2cd20a3b0b0dce5a353d316c57d25a2b445e03f7eac90eee27b8af",
-                "sha256:db643ce2b58a4bd11a82348225c53c76ecdd82bb37cf4c085e6df1b676f4038c",
-                "sha256:e3a0c43a26dfed955b2a06fdc4d51d2c51bc2200aff8ce8faf14e676ea8c8862",
-                "sha256:e77bf79ad1ccae672eab22453838382fe9029fc27c8029e84913855512a587d8",
-                "sha256:f2f0174cb15435957d3b751093f89aede77df59a499ab7516bbb633b77ead13a",
-                "sha256:f3031c78edf10315abe232254e6a36b65afe65fded41ee54ed7976d0b2cdf0da",
-                "sha256:f4c007156732866aa4507d619fe6f8f2748caabed4f66b276ccd97c82572620c",
-                "sha256:f4f27ff3dd80bc7c402def211a47291ea123d59a23f59fe18fc0e81e3e71f385",
-                "sha256:f57744fc61e118b5d114ae8077d8eb9df4d2d2c11e2af194e21f0c11ed9dcf6c",
-                "sha256:f835015a825980b65356e9520979a1564c56efea7da7d4b68a14d4a07a3a7336"
-            ],
-            "version": "==1.6.2"
+                "sha256:00d7ad91b6583602eb9c1d085a2cf281ada267e9a197e8b7cae487dadbfa293e",
+                "sha256:0355a701b3998dcd832d0dc47cc5dedf3874f966ac7f870e0f3a6788d802d434",
+                "sha256:15263c3b0b47968c1d90daa89f21fcc889bb4b1aac5555580d74565de6836366",
+                "sha256:2ce4c621d21326a4a5500c25031e102af589edb50c09b321049e388b3934eec3",
+                "sha256:31ede6e8c4329fb81c86706ba8f6bf661a924b53ba191b27aa5fcee5714d18ec",
+                "sha256:324ba3d3c6fee56e2e0b0d09bf5c73824b9f08234339d2b788af65e60040c959",
+                "sha256:329412812ecfc94a57cd37c9d547579510a9e83c516bc069470db5f75684629e",
+                "sha256:4736eaee5626db8d9cda9eb5282028cc834e2aeb194e0d8b50217d707e98bb5c",
+                "sha256:4953fb0b4fdb7e08b2f3b3be80a00d28c5c8a2056bb066169de00e6501b986b6",
+                "sha256:4c5bcfc3ed226bf6419f7a33982fb4b8ec2e45785a0561eb99274ebbf09fdd6a",
+                "sha256:547f7665ad50fa8563150ed079f8e805e63dd85def6674c97efd78eed6c224a6",
+                "sha256:5b883e458058f8d6099e4420f0cc2567989032b5f34b271c0827de9f1079a424",
+                "sha256:63f90b20ca654b3ecc7a8d62c03ffa46999595f0167d6450fa8383bab252987e",
+                "sha256:68dc568889b1c13f1e4745c96b931cc94fdd0defe92a72c2b8ce01091b22e35f",
+                "sha256:69ee97c71fee1f63d04c945f56d5d726483c4762845400a6795a3b75d56b6c50",
+                "sha256:6d6283d8e0631b617edf0fd726353cb76630b83a089a40933043894e7f6721e2",
+                "sha256:72a660bdd24497e3e84f5519e57a9ee9220b6f3ac4d45056961bf22838ce20cc",
+                "sha256:73494d5b71099ae8cb8754f1df131c11d433b387efab7b51849e7e1e851f07a4",
+                "sha256:7356644cbed76119d0b6bd32ffba704d30d747e0c217109d7979a7bc36c4d970",
+                "sha256:8a9066529240171b68893d60dca86a763eae2139dd42f42106b03cf4b426bf10",
+                "sha256:8aa3decd5e0e852dc68335abf5478a518b41bf2ab2f330fe44916399efedfae0",
+                "sha256:97b5bdc450d63c3ba30a127d018b866ea94e65655efaf889ebeabc20f7d12406",
+                "sha256:9ede61b0854e267fd565e7527e2f2eb3ef8858b301319be0604177690e1a3896",
+                "sha256:b2e9a456c121e26d13c29251f8267541bd75e6a1ccf9e859179701c36a078643",
+                "sha256:b5dfc9a40c198334f4f3f55880ecf910adebdcb2a0b9a9c23c9345faa9185721",
+                "sha256:bafb450deef6861815ed579c7a6113a879a6ef58aed4c3a4be54400ae8871478",
+                "sha256:c49ff66d479d38ab863c50f7bb27dee97c6627c5fe60697de15529da9c3de724",
+                "sha256:ce3beb46a72d9f2190f9e1027886bfc513702d748047b548b05dab7dfb584d2e",
+                "sha256:d26608cf178efb8faa5ff0f2d2e77c208f471c5a3709e577a7b3fd0445703ac8",
+                "sha256:d597767fcd2c3dc49d6eea360c458b65643d1e4dbed91361cf5e36e53c1f8c96",
+                "sha256:d5c32c82990e4ac4d8150fd7652b972216b204de4e83a122546dce571c1bdf25",
+                "sha256:d8d07d102f17b68966e2de0e07bfd6e139c7c02ef06d3a0f8d2f0f055e13bb76",
+                "sha256:e46fba844f4895b36f4c398c5af062a9808d1f26b2999c58909517384d5deda2",
+                "sha256:e6b5460dc5ad42ad2b36cca524491dfcaffbfd9c8df50508bddc354e787b8dc2",
+                "sha256:f040bcc6725c821a4c0665f3aa96a4d0805a7aaf2caf266d256b8ed71b9f041c",
+                "sha256:f0b059678fd549c66b89bed03efcabb009075bd131c248ecdf087bdb6faba24a",
+                "sha256:fcbb48a93e8699eae920f8d92f7160c03567b421bc17362a9ffbbd706a816f71"
+            ],
+            "markers": "python_version >= '3.6'",
+            "version": "==1.6.3"
         }
     }
 }
diff --git a/mypy.ini b/mypy.ini
index 295bab4e302..589fbf65139 100644
--- a/mypy.ini
+++ b/mypy.ini
@@ -5,7 +5,6 @@
 python_version=3.6
 platform=linux
 
-# flake8-mypy expects the two following for sensible formatting
 show_column_numbers=True
 
 # show error messages from unrelated files

From c3df2c1a69c687d34f41478235c869d0526a46bd Mon Sep 17 00:00:00 2001
From: nikkie <takuyafjp+develop@gmail.com>
Date: Mon, 28 Dec 2020 00:18:35 +0900
Subject: [PATCH 0053/1034] fix format_str() docstring to prevent users from
 running into NameError (#1885)

---
 src/black/__init__.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index 48690573810..5f0f89719f9 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -986,7 +986,7 @@ def format_str(src_contents: str, *, mode: Mode) -> FileContent:
     allowed.  Example:
 
     >>> import black
-    >>> print(black.format_str("def f(arg:str='')->None:...", mode=Mode()))
+    >>> print(black.format_str("def f(arg:str='')->None:...", mode=black.Mode()))
     def f(arg: str = "") -> None:
         ...
 

From e7ddcb8686859cf3033b2a5d1a2934426abdae9d Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Sun, 27 Dec 2020 10:19:08 -0500
Subject: [PATCH 0054/1034] Fuzz on Python 3.9 too (#1882)

Fuzzing on Python 3.9 used to cause errors but now they have disappeared
on more modern Python 3.9 and Hypothesmith.
---
 .github/workflows/fuzz.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/fuzz.yml b/.github/workflows/fuzz.yml
index 343eed10df8..0153767509a 100644
--- a/.github/workflows/fuzz.yml
+++ b/.github/workflows/fuzz.yml
@@ -8,7 +8,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: [3.6, 3.7, 3.8] # Python3.9 should be added after fixing [https://github.com/Zac-HD/hypothesmith/issues/11].
+        python-version: [3.6, 3.7, 3.8, 3.9]
 
     steps:
       - uses: actions/checkout@v2

From a497570fcb364b40e0d952d3133e8d4f2d329fea Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Sun, 27 Dec 2020 21:38:11 -0500
Subject: [PATCH 0055/1034] Bump mypy to 0.780 in pre-commit config (#1887)

To avoid hitting a mypy bug causes pre-commit to always fail on CPython
3.9. Even though it's still an outdated version, the bug effectively
blocks development on CPython 3.9 so that's why this commit exists
instead of waiting for cooperlees to finish his bump to 0.790 PR.

Also this fixes primer to ensure it always raises CalledProcessError
with an int error code. I stole the patch from cooperlees's mypy bump
PR.

It's funny how mypy 0.790 is already asked for in our
Pipfile.lock file, but oh well mypy is probably more commonly run
through pre-commit than standalone I guess.

Oh and if you're curious why the bug doesn't up on CPython 3.8 or lower:
there was some subscription AST changes in CPython 3.9.
---
 .pre-commit-config.yaml | 2 +-
 src/black_primer/lib.py | 8 +++++---
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 667b22d6328..4e12e46f8d8 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -18,7 +18,7 @@ repos:
         additional_dependencies: [flake8-bugbear]
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v0.770
+    rev: v0.780
     hooks:
       - id: mypy
         exclude: ^docs/conf.py
diff --git a/src/black_primer/lib.py b/src/black_primer/lib.py
index afeb0721cc4..5c5576e1ff3 100644
--- a/src/black_primer/lib.py
+++ b/src/black_primer/lib.py
@@ -59,10 +59,12 @@ async def _gen_check_output(
         raise
 
     if process.returncode != 0:
+        returncode = process.returncode
+        if returncode is None:
+            returncode = 69
+
         cmd_str = " ".join(cmd)
-        raise CalledProcessError(
-            process.returncode, cmd_str, output=stdout, stderr=stderr
-        )
+        raise CalledProcessError(returncode, cmd_str, output=stdout, stderr=stderr)
 
     return (stdout, stderr)
 

From e912c7ff54c392e92a765c5eff0bd2ca3bb05b47 Mon Sep 17 00:00:00 2001
From: Bryan Bugyi <bryanbugyi34@gmail.com>
Date: Mon, 28 Dec 2020 15:30:23 -0500
Subject: [PATCH 0056/1034] Fix INTERNAL ERROR caused by removing parens from
 pointless string (#1888)

Fixes #1846.
---
 src/black/__init__.py                  | 11 ++++++-
 tests/data/long_strings__regression.py | 42 ++++++++++++++++++++++++++
 2 files changed, 52 insertions(+), 1 deletion(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index 5f0f89719f9..c7c5d724a9f 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -3271,7 +3271,8 @@ class StringParenStripper(StringTransformer):
 
     Requirements:
         The line contains a string which is surrounded by parentheses and:
-            - The target string is NOT the only argument to a function call).
+            - The target string is NOT the only argument to a function call.
+            - The target string is NOT a "pointless" string.
             - If the target string contains a PERCENT, the brackets are not
               preceeded or followed by an operator with higher precedence than
               PERCENT.
@@ -3295,6 +3296,14 @@ def do_match(self, line: Line) -> TMatchResult:
             if leaf.type != token.STRING:
                 continue
 
+            # If this is a "pointless" string...
+            if (
+                leaf.parent
+                and leaf.parent.parent
+                and leaf.parent.parent.type == syms.simple_stmt
+            ):
+                continue
+
             # Should be preceded by a non-empty LPAR...
             if (
                 not is_valid_index(idx - 1)
diff --git a/tests/data/long_strings__regression.py b/tests/data/long_strings__regression.py
index 7065b2fcef8..2e7f2483b63 100644
--- a/tests/data/long_strings__regression.py
+++ b/tests/data/long_strings__regression.py
@@ -375,6 +375,27 @@ def xxxxxxx_xxxxxx(xxxx):
 print(f"Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam. {[f'{i}' for i in range(10)]}")
 x = f"This is a long string which contains an f-expr that should not split {{{[i for i in range(5)]}}}."
 
+# The parens should NOT be removed in this case.
+(
+    "my very long string that should get formatted if I'm careful to make sure it goes"
+    " over 88 characters which it has now"
+)
+
+# The parens should NOT be removed in this case.
+(
+    "my very long string that should get formatted if I'm careful to make sure it goes over 88 characters which"
+    " it has now"
+)
+
+# The parens should NOT be removed in this case.
+(
+    "my very long string"
+    " that should get formatted"
+    " if I'm careful to make sure"
+    " it goes over 88 characters which"
+    " it has now"
+)
+
 # output
 
 
@@ -844,3 +865,24 @@ def xxxxxxx_xxxxxx(xxxx):
     "This is a long string which contains an f-expr that should not split"
     f" {{{[i for i in range(5)]}}}."
 )
+
+# The parens should NOT be removed in this case.
+(
+    "my very long string that should get formatted if I'm careful to make sure it goes"
+    " over 88 characters which it has now"
+)
+
+# The parens should NOT be removed in this case.
+(
+    "my very long string that should get formatted if I'm careful to make sure it goes"
+    " over 88 characters which it has now"
+)
+
+# The parens should NOT be removed in this case.
+(
+    "my very long string"
+    " that should get formatted"
+    " if I'm careful to make sure"
+    " it goes over 88 characters which"
+    " it has now"
+)

From d34eb7fea38384cd1cd029179298116fabdbccd4 Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <hugovk@users.noreply.github.com>
Date: Thu, 31 Dec 2020 19:03:39 +0200
Subject: [PATCH 0057/1034] As long as it's black (#1893)

Make background transparent for dark mode
---
 docs/_static/logo2-readme.png | Bin 80754 -> 99591 bytes
 1 file changed, 0 insertions(+), 0 deletions(-)

diff --git a/docs/_static/logo2-readme.png b/docs/_static/logo2-readme.png
index ec5dafb64958d222ecbe9a29e9e13963acc6d73d..7704ec01ed98a803f59465020422ff6cd24c0958 100644
GIT binary patch
literal 99591
zcmeFY<wG0&7B$*JDJ@W-#fnqh1I4|RQrumGySr1M6nEF)PH=}%ptuzc4#hpi9qv5m
zyyu+v{s;HN%?FYUlbN4vS!?e#VT$q+Z_tR)o;`c^MoRLF^0Q|zs-Hc3-u&t%a70a-
z3<Y?5?yM~F`5APKWDoePWvQy^qA4fKZ)|VNYG`6_WXkGc>j0ef?3thkKk(7k)Wwj(
z!`8;mncqW*@?U501E2pn45Fm?*C{U6LX?_viWFk@PNo!GtemWDl)`8f6cmC^CT9G~
zU%vjIp99~7C@oxE9QZ*XcXxMIcMev2Cvy-xA0Hox?IY;pM;71=7H3a87efygJ7=nY
zU*td6`C{s9>}2WSVrg$j@y~S)jqF`rgeWQhxzT@L{~o7{rP=@PWas>UrUgt8^v{1l
z?5u2{|6UvTso+0H`4yZjO@TZAbA4fU!GE3k|2p=6?js2L=jQ*{VE#SRe;oy;DvTxw
z`tPy{qseyDX+3)$q$~ABRMlhQaM?E0)ZF*k-*k)L>Wg_sWtGa(RFVx3lLWYxwr?NI
z8Z@=(3lk|-wJjzlm3Ko7{>t?FFa%TLPArey9dx)Kk1Wlnk(%$Au9_tr9WH124vx{b
z3AANk<0Pb}&UoAk?kt@-A+n;vqPW63$?y3PJHk7eJD5u%Pdg*y_Za`$)Bpd^|A$sU
zB#&B3pJ4sct<AT8YdB@~d^bM^wzatWc&S6~xfut(oo#|$WHV_%+piAi>pEQ@?{BcO
z1>BE~4Ifp^L75MAY!BtwkT)k+h7TfH0!<J0hF%JqkJ6z}7<W(Zp}9xSJ73p1D~Nf0
zZ_j_GahP9*JY0rs`F?<rQ8D|o9FrG4;l*I>+#01m9<&@eKmERm>|9z|d7Q$AVBGl%
z{*vfvUF~rA(|u>Z)O=!{JBsi+9i&^uhi<TZSixO?bCSN^;Mx7pYF0h-d}n2Dz7vHd
ze7y$JZFSkpGW602U0qpNxV`S{>jRSr`&^?N-X^h;YJ$OFEgc<i4@bwno8aK!f=KmA
ztKfl@p8KUkn@O7=p;Pl_ABl_RTW$Q@xFKe7RiH+mVcR-q=PjSPl?of{OA?)I|Hh@N
zd1n}QO-D^-rTk*VO|Xrhqa(YPo?ge>Dn8vic#lvs-LIW!628+t96I@Xzh((?UgzzR
zs^jBh*h8EInWuAejC*8cq@>?-VD$HFSq0Mv#>!jky%Fxhe}5t)I-VZyL~x7zYg<}w
zV#>?QpK3fDY8tAm9WH(bAX}amF*zpE1%_MJN#brT?rd-Cvu*F}3|qKTjx=o#-{?q`
zr`k904_B(MI#y=;Mi^i5`j;PMZuz*k-K7kF*Pv;cO|m$UZygPG?(-&E?^|DA-ya$p
z(ug4!c?<@I>qGkswa2;nU~@15F}J+@Fdu}91=FuZ2S(~K8aAWMepA!X;A$RvmBsJ6
zkA+1pd=F=0VghUH>u1|FXk+nYa14&fhJK~8{FQ21FdUU;<Ex#-nIfKEk_JkUzqya0
z+kUd|AMb2-#)sn>Up^K4p4EA;wlTNNc#>s>j#CR~`1sBtx+hO3uXDvhj>E=J{pB;S
z=K$*wuI}h~fF8iBo^*Y-y@Y}B{0;wIn%SDaY}d*4s|tAeySTbu*e9o?AhIA3FeD?R
zjgZOLjEF<3Lmx{?X1@VD%8Q0CNeyK*cu!ZKfh&W?b!aGe$f0%HX569Oj2#111!GJZ
zW~^|5wZiOI&D<~4>z?lGgznt1o-Z8;niAg%3ka<qX76MlS*tXVX5Gx&JlMcpxg!3A
zcN|%}mDRQ`2rv4RnyTrTzA|A4H?qj^nhjQd&0q0^%{w10^%U=H?`Wf9k+qxK+8&Mb
zaC7^C&f~5!Mf@Lkj2p7-vHqD+ZP*Ow;^Lxx7(#wwY3Y7oB40wJt-k(z=H})Gojp#e
zJY_J#iu2T}tUj+yWfTX8+*6g&Cw;Hc2V%pge#hy3IecX~HgaBJf9wm*-e|pKcxUl&
z$IUd@uz$HNJ71LN+v`-<+0hib?-_o%H9Y!g-8$0%GvEX_%jv=Or1XzmA+?qq*6yn(
zTaKe?X04g(zqxABTCeY|8@%YO#GhXEFJ)$A2(&jhd)Qa3^ZVUjhZqMkeevOe+rm77
z@qbE5WeXMSG>R`<wtJcYTyG~OB}D?TQL+fBkkY+96Dupms693aZ6(o#Q8Sn*>ARZn
zVMXN1RtksRgVx2^@1{pvjwa#p5gFU7mAjGqP&mh#Sag=>+oQBJ%lr3;tIGUGN@(ST
zlue<UXVy@qcI6>hWlBYg<-EqM&ePS=5r`9@$D_dnI+5CjhKu8C2vtYWKc=gH7gn~o
z;n0~trvUQ@mY-wwew(Lr$*MuVck{EXtem_&t;z@5V%j<rH5S@(D=jBVb+wr~%gSuE
zDHjR%V7XQ(M<oFs?{fdll<&}uSB-t;ov!18*0Hc#RijH)Il+_{zGsr=*0oK`%FJbL
zdc}mE-s}LJE1X(Cy_tb={M0qcs$OVpX6|4q$-7-+n$Z^Y!vx<J+Sukb+F--C+N910
zbAp`h#2z=noy(S1q1+c2K|^(ei_@;z$Bnc54INcna+&glzU-I7@23p;R#xZd=QoCj
zhr!xfS~nY`qoY^7PhU%|{xwz8W7ysC;(B%G-=0S(l|;0Um8Iq0%J#@e;a(}T6c;;R
zoUFVoZdgEGZJGLTygGaLsf+!uqZ_|Hr<O|f`Qq6&Xz0+%4IksqXiTZ=WvLvzH5!DY
zW2#)x6s2-P)N>&#pA1i-*)E#2&VI!%ESxQF4$~xP(uih=mO)II6iZvwmf)u!Qs2=s
z4R75J3Ewz5j*a=LB<-1)t`3%-a`2B^=1tCqt?Ze&>FM=rWZMc}O}kv`7BgMdr+X|N
z=(`DZj@2}*+^oPRu11R5#`UCJ@O&$IxdmYEPkX@Sd`pFkJ&qjpI`mhwA&{r5nVA`d
zY+>J9=ryTg%|Gz6>e)%~9J~tbFVVLA_!lt3PG)9il4!h7?1UWr{K=6~QFwz<f?X;Y
za4$mR)>O!`*4U5WLUyh!^@($GFs-oBJ1WxJxrC9h!3+<U{QP{&UpFW3H|9C@Fz<dj
zbMim2S9zRx?3iu>VQ;X;xIccQKZY(NBg2wpyx4I00V`9M%;#^{W^M?XG*rJMUAN6m
z==Iel9e!I|+h9*FOO2e4j*i~ZaTGA_^Ujakpw@BlNOnh1S@LB-P0b<M_7!6XBx?XJ
zC!ZKrmG`bHzMeTGLEfDvvGumwWvivrpwpAxm)%Ex34{>weW*N5o6>s6)(Q0xVi%pY
zYDmT+<v+i1z!GseS??9-@%0JnB>5+<7*E<YA$Ywn4?*MtZimJvoo!r1QRpYA-uJn}
z{F73L1!{a7TERoA>U@cG)wKLG8aO!1akSx#Ny4VV>MhU;i*))i6}t>(#x`17+Nspc
z-IZiD#-zcxlasKIaqkv{1O+oO-n=Pf|M)RpjX{ku7?XrImevxJTsZTq>=(UehYu}Y
z7t&5!r(2stNyC<tdo}%JGTA<-gPVKB5czE1?fK0#^K7Y&d2@&y?CAkPSEV*C^5o+c
zb#oz%v)y@?g($dMKj|k|aC5H;_IBZFAwj4$n+pgC42I#*O?rE74#b(*+OoX%Wh9+_
ze<!Q`fSWxvH)nCF`y*u19QRJMA<(wA*r*cJdaLE%d9bX0IHjVNd{sHPUo*22;ivm>
zI4Hl)D&y1V$HmQ`oXvDzT8@s64%P>QpMKq(?fBF9HQfgTx%yiQJ#5O{-Tmt51ZDQ0
ztY^cWk+L3hI`NlE@DY2wJoc1Yk*}SZSesioj;6M+|IE^KR~PJJFEbv8)s(S|Q7N-C
zoa?rCBM=6?cRnr4j+>~-%cAP(v0SIJcP27~q|$3?YD!YkDi{S%%-5MG9335Pu8+x|
zUgIbfNR<?4dogCMwBP8ae+v&w7xdG9SVI-@m>)}69rm!dUujRH?Euc8eFl+E0H=UN
zGKCYaZ5EE)oX&SAOaOf1YgaSGB$r(@&MAZa#y#6TTaolg@Ty+h&ZuHn1}Do;g>*7)
z)cw}JVRie#p?#8|+_&EPDLZwS%q)$re#i<|0qOH4j_PYDEG(?Dv9t4ApDdI?M9xG#
zz5`a~Q(A?WUfZ(Y+2!S>J(-Z#xpSquHP_=Oav~!6m#C;y)Qa%xmLbLJ$6a#TS-g!b
z-@dym@&i7EhofxTtAVCoYH^#zpFa&g@^Y$Dvl?xwJ}RGWZEe*nGpb+zdZ9*=?*6dQ
zu&EuInmU9-FS7R~ntDz~guBnZ^KN;wFX~|Ltleo#+G+bd?Qca)(YT=cFc1w1!2@LF
zEk>WMEiBj$rYsAW4L*_-v3IE*Rk6RGSq5M2_iQxnUTx_4y8E<0-LbF0`}^x2`ufAE
zbr0cUL1KHCKt{0wQUydIi~j;JHG$6EEN#G-?m1~H?9fH7SMmLJpSrrcyE~?)8u}%=
zvF^K4F^Jv|#H-gh(Nw*Y^4E+>#*@wZqv-i-^QWXPLAliFQGOCyYWuAvwMb)ahcXS0
z2pwk4kchhnHSw(bsxR^&%=fP697Z|8#>10R0fo{W92^YpO&xItyxj<+%clQP^T4Sg
z6^AQEWK5&s1JNXbHFx-O&%g4ez0BZc=2Qsp6YjM4pY8v_|9S$7_%u-^;M+b~HRUR_
z8dFgf<8pf|>5gK+5An4>eQ1q7QhnWL+au<g=SE?xVu3izMPLPA`g>VhA1s&E1Jm?i
z0j3#)nCEjloHN(1ob|X4xc5=&;AES-2ofUxp@!K@L`cZG9m3RevVQC0u_F1@=;6ap
zTAJ<5OFYY?jd?*tLL%*-+8-Jg^d30~*)n5Y_=IN7u|(5HV{&h*c*<SA_k~(Tw%2is
zlO%cj^p$I`$MN>4i-(1*gI=o(!;x`uV`DsEYc3u}vUY_J96lPyGIti-BEL&xhdRkE
z<I5HhAy<!MxU1!Hf<s&P%`29!I*-|ng1LAJqmDWq`XV(j*rWT-SeEzd*w`5HLof2P
zXKQL7?n^p+y}j@B*bQCReg>FTXfAa6``6m9!p=hwilzg4kL#z<_bb+Z&HjsIZ<)T<
z`u>=@*^fDHf5X1+Q^6UAm<jJ`$0X%X#JmvjfAqOsMUeTPPi%Ux-mO@BrRodg9?!T$
zRrPT{l}JJ9CR4@{v?*j>^bZOVHC9Ztjq7YPyyqa=h9Th&5gD6af23HtvLE`_ZSnpJ
zlLXUOw#0sa5c3Y6(OuF4MxUALPrCm>P>V;G_TOdVej@?nPx^D*hJYRY!xYH)oHkWP
z&5ZdUJ)(PZVJA`cs`2VUmcPDCuC0ACUnuP!+CfF-$D>QKEMB0hnjMN6XHq$}^o!O^
zd&g9|j<sL)1oDPIrxtI3O1;DVqR1W)rp#upG##(AUMGEmmWr+a`ug1QqV&BYE^Fv(
ze3Qws!?D`Bwz>cm6HxUxEaotovFdKBc5!+|8K-9LA2KrnRh^x82;r$I4grT0hl{7O
z$Ng-~Vucm{Rlg_y@CY?WLAwOCv+Xp28__)^cc@qhrqXY_UmtHZVwP12zDLVrW`((Z
z+-IA)NkgN5^5ec`PW<Me70ihJYqmQWUA8xw{bl$B;!V#Shg$G^0vwz~mD^^+nGbCU
z+GrNv3i;~(Y~SgX4f8(YRhD4F4e}G1*;s0eF^~k2o9vbsMBM~%U%fyI_(XvXymc}3
z0-ly$1@45MEwwm1GcqzhDw(lp4i8C>Y6`bYnh^*M%f*b39`qrc9`)?nPU2d0?{=4+
zLIxNi2Jx!bW>QkG331G(7>nbSO^?zWa3T94Lf#cw_m3xSZZ~4{*oyaeh)%jKc}C=u
z0MZLZiHaY@A5B8{S326f_DhSW6BLB^EccF0Z*|MO_2D-}(LlUZ1i`K;8$c+-RTb3m
zvE?>*xVHWh>dBe6oqKZ~<;rXTGO7jq*Z#iM#f%16>6vFFO_ifjbpI(ekGAuD5?zeQ
zUDMW>=CN0QYYN+Ol=bD3qW0GpXBAp?>J@rzm#a~3q8ODgKW3o)cM$?|#=aShX7Jd<
z%;sxNk&DMuVZ`W@9!k1+DY!Uszsl(PM^?9zPcEG9G>=cBO}EAz0~-|0YRl-!G{nWl
z3)lkIk)K!ZjAaz7S85l!9WP0JM+r2CgxT5Cl{G)VX*3<iUzl;2$P<69uBKMl7e!qB
z1B)EG;&UeF+E40Ul3~{>wd`{?%5c<2Y_CcH_NlS@ofE*nlj%GSV1UXo{sU&UPCwsP
zH(H|8*=j?vA*R!%W=G?hGBqaGo;N%NEC(!2OP?>EpIYz!&b2z6tNC*1F|(1*Wjzfr
zCWYpwOicLKTm5u}z<OXQL2rF2?(x-GsGGE!Uj>eY_eWR={vk1rl%gAVOdA_Y=x-Lr
z+I4<0O4`TE%D#<xm}xQXI|vN9?QpfTGkB!_KXwC{53ilga%)3xI3Cj@CqU`Zm~Coy
znVA_?dmX2QEZgxE(9o4t4F8bqd8HK&)I#e{^GB48cM<W9K4rBh=d1%Yfq_VP5xu*Q
zi46WK=-cDPnral~Ye=tV!U!xK%0gdc)en6C`CD)Oll;*_gN*G$eHi{F)z?Txh|lTk
z`GGj9u-N^{!id(LZ13qL4gJz|9((AR(ACll>xsNzq|Q)pUevcqVO&<zp#wQ*V*)Xu
z6a_P<OUY%X!yIr$;W5NXBHqhMbki?-xl8&Nb47B*u2;+M<#)$z3Ks`(1>gIVemCzN
zTPG){>D!BgL0hbX^^<0vecw%&wv50WWF=G{?O(In)dtUd1A68*PF@DSFHoQNu+E%p
zZs@a46VCQ*PoW(_795kgVAof-8hvf*w#4d_UtJw5$*G(1(RAoaCYjkYzo@84h}%C_
zOY>j8_-~h#`X&%lQ_@jUR<<uftMIt!#%xqm{e6E>_jhtx{N%eH5_js__4r?_4l0aN
zupd`4GSap@v>!Kk{87=hrotsF*^T=!8f<PphHIg~>0{L#lK7{L@koVzQkTxx#zL02
za;^gw7po0>2ILR`;H33FpOBa_P0=f2ZP|QBnUljAI20N+n2gTa{Owh;*=YKNebXPW
zsUkV4q!&G&wm)`qth#v|UJN1|mAD?vO3k7ruj?OZAM?!)$q##u^DB6DCOx!g3l9x?
z{@}8l{KcwJXZC|jT!>SKktut_OG+bzqGb#~vy{WJuoZj@;&!Ypq6PF{lucAi#HbkW
z4X);G7aQlH5sD&Ndv@jZRO|MgN}ZLZH(<(!YGgXxXwJtsOce2@zm?^aQccvgO8eit
z_jyT$xvg@U$I2L&-e8QQaAIkq4L2KxLb%MwGP_xH8kek1>e5Dj|Ic#&_5+;T4k)Cx
zmX(!NgolTNwF0`()i7UWO|JJgh!_)wLMN3u<b3EvL?DsN&pYo=Wpwmh|E_h_qdz5x
z8=0oF26l>dAzg92_#v@US6e&1))f?%8fd*(*|bu|?{+Bp>s4Dvi{3`g<8uZi)3=h0
zdXC?{DZrl=e&(bbS<jW^Iz!|1B+*w7f9HxxAI#-a2?YrXU(Olt1Gr!9;qFR9EB|XL
zu#F{v|I!f-ZM!bF^Jqs&IgYcRJut()U5?Wlo!=lL35CAC@p*8isv1|6Wo|}o9iE>k
zuju3W$6F{~5eFo$x7zGZGqf=Vj`W-zH?B1z<@Oce6SwgMz6#RDw8et=%4hMHHm!Kc
z_+I}BQ6x|T2QbmEtBUrbe7<yPqb-uoP}5e-0-|D!+xzd6Wj|BNPv7*sXJw6Ee1V6X
zV7c>6b{mIsXtagWZWM>ThfQQ8OTb+YC_1S~M3Y#WnpD9?R{pOg7eIAG(rI%$BIPh2
z8wojm{v9ur+F4Xvb`vkH5cVlE)8j2M?z<no5zGxQL<pK@h#X}a)JzIRp&`M+xaABy
zJkmRwBR#IK_se|mF5iA|DO)a|^u^jF#6Tl@At=FS6N?S;yJaXX;dei-fObB5O<h1u
zWhg<PxY_q!ynFE-udRw*v={1UBbUzIfG7S1YC(;+C{CdF#bkskM)0%fXzn$8W%0fx
z3BU@aSnWekULc`e=oq}k&{x+qSOT%laBkLG_R>o`?9@*?QjjD-Atjbp8Slo;r6*z5
z+cS~*-~FVwWa%}Wv?j=dx+qFlU*4O3Qhrb(CAxrD>hMrzE;QQ89Bt2FF3HO}I1;bx
z+8cKqIsW20$0`Vb1@4GCb#c{O!=anmuf+H|A8)P0HC%x>UjK0BQiAROctb#$+ytL4
zDU?Z$UBGzZ#+hDxdU{#{#?#tZ&ZNrZdwv$oSA}aiu6Y%{eo4}ECKtyA|Ev4G(d`w2
z*G+e+!{_Fd!2Nj1vnE#S|K5?nngMHNJ-vsYk!c*oy-_F>1JtyYByb@RlcIQVx;Hs~
z+O7TY7M27vZ<^|-1<mPof$KK}{PYUkc1w~4zpH>%{@ScA`W#t9q}k^~sJpm$@ac`u
zrM!m**q5s%GQh(i@U=v9{h##X_`YK+SzWfUE;NRA^waJmefNu*BefJ(f8~eU3z~*8
zV*7T>IbvMogQKQZb*=n5RX5&@{baq$C1?hT7zX3}jBoW)K_*kL`xh2O9v(jDi{Q@Q
zVx);@Dv_6N=^S&S>)y~ah8HtuEGmMdhtosa$_vpVH@}n|t$HJbE@<~xt&r;nhe1!`
zLic}r3Mv9Ka##FzQ7v}7(gliE9$U+)%IiN_eIPw1Cs8E#J(`pO(U_8ia$(ym3I`kp
z%TO{WP@K_atbM+Hg&o7|qL=_glt@X-SecE}zKOYh670I|l;+v-lGT<)82wHAz)b(O
zkg_SErLmnTB%R-M=no!~db{nB6}?IFzY*6zQU1RCxinJ`|0s~8iSTzPmUOi>Y0K4&
z$QViOFXTrq1VOwtno(c#8R6G2arNd*{|?WC<MUo@VjCT1LUU#?V$JTZ5Oh4^&G#R8
zuMVm@p~vlK@=j97o<F4--QFN~Jww4Aco~bSs2T9>8DSw}q2JDrf<5O~%l+x_j4NEv
zoH#J(YHv#74H0Lks<OkNaZ|ekuMJaPyKY&k$>)wD4*Lc*QE8fF<6z6X&wAR-Zh?rF
zXcPv&Vg)MS2lkfrqXqn8ufPRKdy&j1*Ez7-D$I8#2urvG+Ij4i-yxu!(PY26vddG6
zV-z)0{5bi0MeS_?etGj+`YQtQbI`E{MHla`AfhDHK41>Xu-;`)+3Bo2YMLJ}oF%sF
zJ(!|?dmN%r!1ao5MBvr8aTD&|>9RrvlLhGR>P^An2#vDK?fG7aMwR}<kGL3_;E{L#
z1+#%1@B8v9CxAt@tE#9V!79XMA#-+?#1ln#EupM1hS@3__a3g+Xu^C&{_qXY#748L
zJb!*lLl-ZGmZDW>UVd>f`_>R8<>!=?=7%+JIk_kxJy7QTS$1Dl!xH@atun`O1~(L0
zedwF)nx+Iv6Pk&-P{g<2K@}TW<<M5?W!IgovOApR8359XhgTBldx*Xv7uLOb@GE0d
zZYBH?>{GMFUC0zaw;Z#~n_!dK-*B(Fu*$xudqg6WBp;dWS{(P7VR_uE3pYCEoGQRO
z8=|`!)(l@I+v|-#2)%V>7Lns4F%C9zB0_O%+v{U>+=#3(Y4jA1ii#1wRqO!v7Pl!v
z)mO;7%v-=+os{22)tvZ22J0Po+)2q~673;oBkvE-mCA7wMXLiAv|^6$ZNO%YGo>5u
zQmrX^Z#BQ3V}nPNSTpL=c#)jdaeE7zKw6;1(AXGl?PA4vs`+9Ohx21N&0}<0nL;yt
z5OYt%U;-1SI*a~27zmn{RR6bmXFh+=ZuBJx$Q@u6Ev>XSTS)j0Ey)XL5tjO@kkCDJ
zuL8o?5~|eia#s^*<tR}GcvgM#{Q$%jiKGm{AmMZRax_;X=6ljhkl4S{;hoS%FwH#I
z6*HsUKAh>jBOHr#h@?IqE*|WysQl-K+jgM@U>IOm#ERG(pwgy0wBos=cL5;hQU~e^
zG$WMgHkwiy*@i@UVI^V*?}FNP*+m-A*(Grb<kD}Y83#e!;NNx$)6jYRIPC7%?OC}>
z)6Fg3>KVFI&?L3uxH<e`C{^=Aiqx|27+a(QcBa@5j9l0YF^Ag_GB3#nTlkop(q^;P
z637vnP`TT~cCPaNN-tAPE>t)|?;YPaK}i;D>Ea$&g4Gwf!Polb8dd63Me;PCIp~bW
z=t^)Brk%El5tpOCPe*QsRQ<NPxIFrYl9(VX01-#OiTLmjL;E)>EPgKnM6Y0U0#={O
zii$&oqW2d{LxG&y#XQdyxC$YN+S!Sc5f^RZGtQ>0scE5hlO0QM)Mt!L6;cCIyKfF@
z+U*|fEUKRHPV1_UWK{;uIkC~eUg3dqbWnRNu9{*kTU;TNz5{0Wvl?hM6FG+H0xHI}
zg7)<krnj+helJ^S4ASVEH=U!cQIqQ#`zyThTjCA3(_{G){$+ad$>L{uD_6>!DUf2P
zwxKwsv^=_ag}Urz_=wN+%1*wz-&2d%&|fVU5wq3bx1r+UY1An#2XqPMevla4pgHC>
zfW@heU+fp!wH<Nqr@(cc-^7(tRPJlBh8@Df{V)RYeY2!A+=5Z|g57`jBRa11!>hR6
z4mHEe8vw9aZ#CGeXz5w_{4@IT4~iK8v5MCWDDrd}geF=GqR!~|Ped-f{Gv`Tkg;72
z)Dc1KutgNs*;9=#|AXA}?_dv?i)LzSYW~@5hTZDgiNT)>4AxMb?4YGE{tpq`%0!Y_
zT@`Vc1yVQ+*ZjEhidtD#7cbp}02qy2s)1dF22~CP{R*h7F+jBpc3#25ME5Mw*l*K)
za`=@;R`b18cqwU`!QrL{(?RhU+x$<v#0t0d19?3y*USy5*iKqWxm~`=M7=9SXPCnU
z>n3!&=w6;b!fTU*z0zX6qo7u6HQFnM&$g3)LU=DtpOXR6y0z&Ar)e;(Z@f2CCv*4P
zFY>`841)DTbC#agysjoB$V=h+zH&l$haCGrrMURoR#De+gn5N62WBXj&e`BD`HT0@
z&r{j$b+RRc8e&S-2uc5&)2)K|Q_3v)qTvscoU!Y}l?H!Hup*^42kiuoQd=wY!i*Ca
z`#)lzcEw7?2XJO^n9IA#$;o*;vj4A|5Xk=wUjwM+lNKpJ^ndhfvb`?|CT&|OXw=2a
z&A-rvI)jW_2#soDdPycRULd<*!hf0$C*xS6^iGw&dN#UWhJf8gCw`z`bRHKf20E%=
zM5nb}1ABP`_3G{tJEn9tXdBD%Ua?^7DjERrND1H{au<kIa0fu|tN`j;&t?XvTw#|3
zV-#1ZRAN#=t>4C&UoVv%$WF<pY@cMn-Kn6)Wgov<`3uXnIH?qAq?k$_E?TZmof3ta
z%t0Ag@){gjkBm~69^cksQbOCm=sr+I?G=!|)lK$7-+6Al<oCA=b-D@cxrL{U^|>Y(
z=D*@uDN6|_BDg&c74-XLW+*sQXJjv06Usi7FM$P6PkJtZi!F*@t3DqZ6Y{?NhcT5}
zPBE5dra}w~UN-DNNABdPbM@q!#7A;JM2y_tpN(HtX*ZOub_Jo1Cw21v53M<5eriuf
zLB~Ij=-)tn@Ph!g3pWhL{_Y_c^2k()gQZ7Xh{U0L%{981>DCn!WL&{280ZGX-y*%3
z1llt4VYf)D0Rj|m%sqB?6lvAO6o_+F@z(?N*qRgtOLpI6H4Wod8f|ry%|zuUpMoFv
zAFfu5Ngs2lH&8(3Jk55p5p%9TJk(!b6v98iy?H;oru=^Sr&=9u7;_ocyzt@Biulow
z`b6jLLq^!%+>P8mmbzy<)Or<N;@xoWPQQH5hVW@@ELIyhI4i&WJ`-N8f9ycrQl;%m
z?AAdnr3Q-I^m5wyaHxde;oGsuT$4>ns6BTeAa${)SLDF!OW33Rgkk*vH0680b8f#r
z_qCz@_VZY;&5efO7ZbF(o3?yki@jm)O`MvxgV3+InegW5W!$&l$-c~=?@i5I9xYlX
zd{0<+y7nL3>zZ)@5NE*%<>VMWc^}uS5)x}c0aw!5K6ZFq+i}lp*XUbhz8{=%kATAC
z$-6(Al!q8%PvIZ@pCF7BK!H+ip$*WOQ6O=p2cx9hS4ioa5~H)<kBwn!N%VI^SEcY9
zvpFW&2%5Ccz4xa}tuE4MaOdVD>dUMt2JWDGZ5An<FRJ^X-zc)yhQ8-*3_LG$9P64r
zu<V-QD;fs?uzXEb&g5r<i#RHYbaZWX^Vp$Y>KBrhqE_f<sbyqBEQx#0^Jzlvx|W4c
zZuH9!7^gV=(SpJ9y8;bxy=#*hLsCsi>$|^>vv5ba<L;Mzio=^XS(3)$AI9E}A9Y-<
zY5@8ZB?ZBg7ri}!cOP)N51kgTEBY>3Ge^fQ?GQepj;NF9-|<(1*RAibPjLH(B7T=y
zPZA#whhUMbXK>r*y&<mFF->MqVNb)u4B@Cat1gfE!Cd>%rrtAlJ;*RSvVX%LTyHTU
zlQ;A~T!!=})RxQt@qWeA(-XDkTX$Zho>_GX+T;YMQ*lkq7{`YrLRxS&wwTu(JJt@+
zl~ylTucRc%N|4hIs9tDuulk4|u-O=rDx~P)FhWKz=n&n@-d__~(;9B9+eNw$Z97&T
zzw}BTV2lMD*C6NA>~a$96io)cVywjcT+(Skf0M2r<0E2`c2==byIJtZ3+_c*L)y;r
z{=C^t4?ZRBrO}Bm%bM{RogI>stpA%sq3f4$K3rVcGjlZ&%mNmzatSKkAHT3;YZ;mU
zfbfzY^EToiyx4~J<Vdu3CEDV;Y;oaY%p0?A5=9(eu5-H<6G%_=AM(o$sIZB9wjXer
z&JU7k@Fh%te9h9yPL4s$EeqgoNuj6vv;8hqa_R=Ez5;oYMZ4BMk6zbEsrLzE9;h{Y
zIlqx=zQ5P*1oDy;L?@a|s0{YlnyzX{kG0J=g6;=d%|;gMI)4~EhA;J3?)*vLyCQbp
zF*hz<F&jx`w*@Shlv@3NeB)XSDI)i1v8jmz-(bSQO*4v6C_OYAJAtz68`_J&FM=q8
z6=ykOnW<MdUO)9CyJ$ex)AZW0Nl8hig)%Ae-W2$Lt}Qw_#3B#pI1JRZvZ<d;aEvq?
zfLihjDRvp=eP1^L`np$oE!vKQW4E291I^(~c}h*QUxv}i^}Vo!W8g=tEzB49+IpH7
zJy(JEk<LQzUs)h%wb$FsvR+mmJRc79y3@Quel9Oy(YaGl>`#??FT})hmpS$NMZyCA
zE^Ev~bOP+|Cg;HWd8MFRi}I$pf4?lq;HtskCqwbFM8oabkn<<R)N924ICU~pE@p+M
zt-kGnE__OABxOoC%(O`Ggk#BX;Tny08lujlO8{-%@P568LE9MTH>w9e=4QLoGHQL!
z@{lu&h3rK>J!Cjer|p-z>o}d3&md2-<oT8Y29)T(D9%hRVS0`jVe~W*Y!G&`XaCto
zckfNn_X?ZTt22w@ciC0UY9;pSa9{iRJUmTJi9KzAdBk5aJx`Y6?}*o5x=7UG4&BZM
z;qD8Cr)Pgrv6-x|e!L-W9mM?c-#EV(^I4Zmv({wrLA+NyBbR8P)`-h6ceA)zRhYl_
zgL=|x>-H2>;Of4<Ik4@6?p`fWd;0YnX9j?bQkKCv1Fl;O8-4`e-v@RmWN=66hJVuh
zK!%4J+LxEChvW!wfbV$yYtOYV2B@BjysrG@-;fEW;!m^^6Ts2oZ)RfDB|<j};lU~*
zy5_=g*B#PMwWedvWlN8YadwEv9<l!3b-h!854X6s8=o)P&1s<@sPvG`m)_Pd9tOFu
z7>B^_g~#iC+#ZU{o4)mPLHgZ&FJ0Z2r}Z0u)%%n#_JVZ;yi>ZMb*io@W%jpOwKV7X
z1vfuaYBPnaxTh!2Ew|(-8rHgP3ixd19A=vAMJ{##<Z=?lUV-okrRoz%Or$8uo$dDM
z=b~r*bG%q*uAru^UB+#{QsH;Am6A|2V#Lz}v;??Z_c<vKg>N=hl+9^oYe03ab<i`C
z?=3`|nvcznb6tOffXvYl-)ZrmHSc<=b1!6f!qr;P?FoOVS@;vL^@%y<8+#j>AsbQj
z^8l?h(gM@(AzkmWF>2Y17U!1rwDe}OmXnsXpf(zdNW{q8>zu<h)T|$DB5kYTOGWI~
zCTvJlcE3Jo=|<r9ZeM+*;-EY&VRZL4|KSP29b$@hH%(kA_lS#xkTwFXHUz*{S@jxi
z=H*|cVVC5(h^_{dVZk4qJ<ky{LDo+7`&~j_WZ5$PL&T>R!SB!}_kb3IIQY%oiND{H
ztvsc=)`vGIjf-|TK-+-b7Bed8y@T1?`uMT(B@R@~N*5O;EHJ+SqMc#AOhk_cEf{G6
zW^uAkPb0&B&sf#tQjy?ef-RFI<p8P>yXwAE{;~g1;;Sn`S`Lk5asALAd6By-T}T()
z*K8|PCg%IzWqPaQwwgP8(^)gWhHUs(PF1!AlPPaz4o`B%XGo%sujU^;Tb|77(bT7E
zIY}Mmm&&kHSeFXgsxo=cP->cQc|8`Ks}<+s#|3{J^q}X>;&h0y?+l(+?<wXHV{O_W
z$sN}j%pV6t_5lwV{YO-HvO`{)No_^~?Bx7H7p;cm+TOuqhT@%uf4>$<P<jO6uJAc;
z|0ckCThWKcOqjajjp)d8*MHeyGQ<|B0|-&BRv*qv#(`?SIdqI@3U~Vru?4i-C!*!6
z-;(Idl7i(Kt{b}5D@|_Kc;ws9KM??G_P1DUw0#=c3&waE)Mdc-9^>Uk6&X38U;#nA
z_8Cwyr`Fae_(YsK@e7KWF|JCavq6#L4<G9t=$#B|CeeJm-hOFa891OazAU|~$I}MH
zp#^w)4v*ONfgEVXYA*|8Z&A(F-l#{RU)As*R`<|XzQP1uF6JhF;*E_!Mtvt3#FM1)
zmvu`;15r3oY`3Bzz2JLjou6Iqy5HyQy40LKQABnydI(yhf@xGS3C?VJ(2jP!ZzVBd
z>t5rr)g5hIXWuW%G96$}))6WaD>O6|nlUSllJ?dFt!u>@3W+Ji!zDXi6B<)_j!3oN
z57AnI6&fouc4}nLY>S~UI92-8cPp6M;VLerog1!tPvKc<Zo~((u~naC_{qPDghyHO
z$F_1@OV%lHT?f_gWM`8(?w#)$t^We6+=8}$IDT#Y<9CPRZT?}7rjs@NPNhgT_Y&Z{
z_&~pA&`yTq{!a+`uSNS#7BbJxx7vD*KOrJ|6(id3Ulb#){HVVIdu!Ak_Ec@OvW`al
zBVEP!j~u+e`23%J2s+USsnlsAgE?&th5R9*ock`M^#ePUi0Cwe059g!nlNuhwX1H8
zFOza9<;p>bZS5L!DyJDB2E9P<$`V0PFuDuQBhRSvH@raNHqGX-C$r6q9-W>6#Sc;>
z>-q+`eB!P2h`xQLIhyVoRier$8g8<C&Pt*!+3sb?A6<MRSTJB7N@9W=A4dskj#4)9
z&rUfMtE4imTmt;Y@%0wuV{~z&6d_ocV=?0bhx5zF*OqaD9{a9-VSRr;6JZc~6x|Cd
zBxEp{C#9s0$IgCucz>2Nz!7|v`n3=`dlfs`wAqEjrBJvk^PBvtY8b9!@^)&A#${g|
zky(l}H71*N;AReMs<AQFQQsr^xRo*4#OGH=LP=z#*KbU1t6G^73*kwOEx*<OVyvX7
zS2WL(_tQ(~PM6(wfzxr@-v3~n5LG$Hs;c8M5@{h7w7C@U2_H?}PCk`QRM)W=Zyj)*
zLbZbJc5e09jLud6r-xt2+r`?p&rzy>{J^(53rI<gNpOoaz#n@%&^@#O6f}Ld$46Bj
zaxd4xqW{|=0`!77K*>wu-GAg>A@O_Y0$rWN5P>UAjG=;ha^qfwzmjj>)lw0(<4{!n
z_HOOxxAzV&>95b`jAOz`0U=g$m5<>}cR#tmY&mZA^Sgf(PJ1G+q|?CYzl2&&_%p|Y
zFoiWUU1zn7wnx(P+S)Qmw9?3Evh)WbL&e3yXI627f;YM?<PANpc_IqlnDa$Zma|vy
zyk2En+IHkfcA(TBa1L{4YYdZ3q4y8RO2jMl(BifhjJ~Lizuf3`DLwc63Q_hug^4Nz
zqJj!BZ?D!J)ovtO-yC>wsa5g&X3vjJxf%_9Fhnhr9ck5P=9z*iZ$SsR{Uoe^U|QXH
zond51&8bWKYkMoe<G8`pcU-pQrlPh1hN}&#-pQ9G^TC$J%I4WAMj6?Z2`Ea>aLZwA
z8h?nud|z7sApEWniFWirfjgL~UXiVsVi|iJ`@IC($9;Xbc~jhx?xE7<lU~*HFg5VF
z@D)iR80-41f@AIX64$0DgL9;?i22@>Yxy)B5FvHWH#=^)to+UTclZLL*nKYw)JMW}
zeaQQmFyJik9dAOe3gNLzVRi;ebiz_T%FZ>jP@n<O1}dMcx5TMzTp-;GfcQW1q4ZUg
z<8fR5;0U9@Batb1IdtGCZACE|5Y4|&f0D79xh+rvkJ~_PtqBkCs0b{!qOCGkv1)7b
z7t?T<47xLxkYNdFDyW=Je_xyo?o1Y!U^>@u?yGDVFrO<*E)3c>(Luk!Nus?eHJ#M8
zmOU#mnQQfhyX^?5PI*dZ6<eXFw}q^agHMCrIVBNrt3X8jVX6GCWxPO_%n~H%D&O_i
z8B;l4$;1Ku3_}>Z22ecR8hqyqIg(D#oqxFp&j2qnAH#O+@;b*Gd!JRNUxZ5V@xap)
z8LpwN(31132%zrpaNdm$8aWA>Pw{6U{7=B|gK#-q+#XaxybdaxU;=Bro7FGI<daBJ
zt#$`;oBz1FV2tY(uB`o}IC_mN@d|vo2=f&<TK%|?leAa;=ivJ;IfKA88pWh1c1gDq
zwEnhN_%2lFYK}^qB_K&1pp5Sb9{YpyIy!`w#+f7`rMKtO`bOE*odL|d*_$(JrtgNu
zlj3xeoRn@kO;g`<#9FIXm95Ck_B+dAeHDS~%(!T}y85nrelZ`A`5m)Td^=J})UFzI
zJ5vpsuktZlkPJjsv9ntWA)ZuHyHkbgiIc}4Tg@ES5s|88>)E!Kac5f(EF8jTHdWO6
z!c6f_AZEl?B0q#$;$VOasH>$BJF%UET~$oLTsN`{S(g>*K6EDDDyy__pw|1~%i_7n
zOV(ZI2;qKJJmLg#Uy02*wIBjDyVfORuMu<Tih3g!vau7g%Zm{Z&`EaeBQ#g^`iP_{
zDYjx9!#jgrUgHp*C?+U!yPMCzbrUUcjE!hN!?c|iRtIY)f!TrLCRXphT6u3gjf_Q)
zS3d+U>P=1Fl%5zwylB}_HvS-g-R7_n#q)SR!ZBXoakb*@-`|<}pKW`&@x<lO;CZ$!
z#iYJ;DPK4Vy1ipEGB8lYxQ#|f5=a!@#hfe)66I-DhYTX^pq4jOFQDylUoWH}HWjUg
zH4)E)lGK4JI(=mz?{=!OMG`W}*MegTg9ZewlY&mE==!JQFSH7vpb{=q1g7NY7g$d+
zHT=oAX3f?`a3b_xq_~yn3F?TkwSh^C$e=mwSL>H#fR>@l(P^DC+CEtGSnI-V%VI=%
zLPBDT2EG=MEZ2MOIk~A+p~j!a?7lv>J}16RPqb{s7&KIvYbl=@W`S1l<QxoxkYDRB
zOTL6k`QsEacqt#1ycMxiU3$sAZnj_%o;h_$F{u|$N`1?7)H`#Y51~7n;94Q)*;=+Z
zAKMy#)8*W<fV<Ocq@?RQqqbf@C7*AAAGntq#72-i&~eFTKKLzJmZKf0xY4I_Ev%_6
z=xbd&^qy`FTlxWoAXP?8lxk`)dnX?^p0F4N`ooe#Pn3x5T(u!9YApbZ{*8|M?67pB
zA|vl_0SdnGGURK~&0xJ~9Y)bo5EXJi>dsd7M_bBvpuJP$xbgCKVO6u}mEY6DRia-g
z`?&C(jT1)AI7aj<`N66HDf73_D}ylkLoYjT9}pm1y<n&TI2EN!qb)P`F~9-LN*943
zNwerBw18%7znrlyzPL=Ik#ffOmshFZS{f#Fu168gE$Vmq%9Ff-5y|(EpT|@yP;5zz
z=JB4S!;Yl5&@-oD{g90BiEzjuTsO$TFDcNxP`N3U-S{QS7#80qw)O*I#mGX?HvI_L
zD*XeJPHNTP;3>6o^)OK9y_2klsbOaq&x(iGlHc9Ymtx%{ap!9TbVN9qEyM`c&$vh<
zlYGB9K3aGG;qnhy{l5v3y(pkO1?=b9U28i0xY+1D_`Iw0B#~@gfLi+m!I!iK6QdCf
z2_l~D4-a~j?(|p-K;4bdF^;3952#NEIwC5}`t6#TfJmx7Pt-1vc?x+(Ztm^R?wup0
ztGtM!I4Vg@8kG5$RJW$j$sc~1{{+(%@-A>RbR<TIxiTi<hvQsT0=mZ9U580al|?>&
zTlqjNx(4#7%iVSnJ=*Amo)kMV`M@#1sFixJ*YkNIbmDH&+T(*BMf>z}Kjg)3)IVAd
zL&>AIc57WZweKgZ&UXq1dIodh6Q;+Uv1$2He+s6k`fW^x8MxOhxbY#yC+n)G=a#2%
z;CZKv>4mF)xP11p)8;ZnK4D{XK0wSlS~jYlIRc<7qYn4iVtEF4&1{ugMS{b)7KfuD
zKM91XPxi~J!tFaB+(rVmG~Y%f)hGyE;1*)yR|M`N5LhnwL$BacX|y{ExcAQk)tVyk
zS#JOAH7Gm<bZQU$3#tEOl3$|$HojM#VGr~4RcK-M^70Y~gGKll<&t2q0Y`?rqd%H|
zR<G$GKJk~@H+%m5ta8|6c*-xT+E0h*ErL~vaVxZAnFtHcLZ(Fz{asJUpXj&8GbGL_
zkAjg@VP}NDR~4cyT(XqnKkfklqH{%~5JfA!@ZFV~(y`cVmnRJjZ21XJFHIBtL$yVf
zu}$zRWD*P^sl%HO7Jbb?poZzo@^`K|d)jf#Sxh5Iee*ZGc#plD1;yawvBVM6LyK=g
zlgw$p(1A>y`#>|O0^T%yIdiS2ICgjIw3R*IXjuBiP1kZyXf!8Z6#UA<uooXmR8LQD
z{d5>akU$4vyj=D7N7FWB?aBP{Ga19k&=h}63AJ1v(R#pon_$4KQX3cD;daFT0%9TG
zzXTl@+H=b}_~?Q4_7~&L(E|+Tcigh`IEwI7c$_i)hxz==#aaFUmEfm-pw+cYR&bLv
zR5%cj+<RQta8Up51ys7;kp0rf6X@G9{N_~uIaH~k?-|_3|8PE)4|-`tgT$>D!}Apr
zNyFi|`t9lTS#kJf%TYbrr<WBr0&_bwG30_09c$XNNA~m~=kdbo{u~!~3H1wnoYqG)
z4{m+DZew*{AUEyj^Ovkcv>}a3LmDY5LfjjRS`SS1l3J0<w2fJ#<+d^EeQwamBfTQf
zBAHFwg=4&P%vk5`lDu{Cq~RjVf*O@~-Puh|l((BU>7oa@EgBMvvl?Xg@DLkNG~v+Q
z?`z;zqy#V%j>I!e@=E;m>;C@Q=y<7R9S}wpfiR<I%9zg^{2si}Og=OK<r;?2ttqP}
zgPoEXwGN9;Kvm)1WV?6?(!3b%?EX(od`U$xrwe2!gzK87CW_4YLdOK{fl^J<S@zl-
z4p|UI42##0kkLxJXP$mlLPC&SKtCF}?|Iz6s0tweVZa2q&o0jSM{z|vKjy0_zS9A!
zUeBE@I%t-Vz)~cy=4*;6&3C=Wa-CR@dCnay%1ovL0{K~46Xw6i<b@G~Mfq^|>yMDF
z=mfuI<5QD^@r3$CmKcz2eu}g`^;5R`jpT1b^WnxOLcK<cIugP;&j+6Al&tsTV|hK%
zTl2(2zsDv*mM4ANJm)!Czyjcxgl;SOf^|u)LUIeR4s@@EqnerzZ76A%=bU!slXOoc
zKWluCbsf7<2tsib1mgm)_S-|&@YHjR<iChMd)iD;C~83fq9~%en`=O;i=)$M^R{Wp
z3Eh_(xx6;eebG)@U8qB7V(Is?9>A1=hb|l4OiVT**92+*g|F1#rlT6H;g4Oe%j7ji
zXip_QO5ZsG)HHdEtx3GS*AJYuoarYT^Xn4050?RL<U0A2UT=)ZqvTzyK_pc)Zy*WB
zi;BOco*d%X(Il4*>4KiM&FkSzUo^}$s`<rU$_}xMq!q%~>O>!$T8bSZQ48;EZ|n3u
z$(BJpIi;C4i@0yLzKD1V@+>xCD0gL77%92jTq?anhYs_#zS@l6<dK^ts@&3a?|9wv
zA|Oszi{7~GmY&C$M=nu+P;9OV!-$jPE8=}5M9&MS*2b^h>8FC$jEaF+x}Zv*%HsL<
z-sgSfk7!$}+^#B^dw&<jyP&il@=eIgkLir2rjHgyepQBT9YSxHTezX^V9mIBy?uN@
zT+_gNmFY}h67y|_m!=onnQ~jELbjJr-EK5nNT))-gTF>&)`Hu||EK}}3&=bcAkhM$
z&!F>=uju@ri0?g-mPG)YYVrZx_U;74`R_~)csqs7eC^gRVtmlb#QcP4z)L4VC27+q
ze%|6c)%&yKYI#kbSGro~2m$U-Au1+*Z>%|=j_>3nn=covdjV!If7eDKj$QtGEp?Dn
zl-Jr}ta@P|=w=bv+S-2MP%n|ZrP9Y;Q1g>94Tje`k=qUzmP92+c_q3^ON*Fp=vqV6
zanq%9D>im$Oa)ytmBYu7w71Tjekly*Ftlr+O@7&`oA#s9qUTn^+%g(Ki>9+dl6RHp
z_vv)`0tOKi5#=RPk<^rSs?}Tcew9ivWe!s2(=)4;R~D|xHWiB6Q6BsabksM&b$3qL
zD;O(co?l%o>PuRGn`W{e#P^ADaB`Ma?P<(pQQp;lc9;4?w@miN)9i0v2Y5?a+TXNS
zSVpb`Wa*QvN~UZ{Z#q?QY7Ofz<m^aHbf<w_aq>$SEjg`p>}qFJ;imVvV|KOPoNY%$
zu(nE)xZgXje?z{ELDF(EWej|hWdE{89`FbV{;6CQd@kqB+cLFFW+kkyB0w<7a{E23
zH%||!w&{nP0-34Ec#Ef=`@4rfe_V=Gf;%5SuI&Do(p?kx%~tC8d!CK*h(xcc<d!p`
z5xEewF_h$_P%ifi)4Y;Z{M`k*R-Vn|bN*7<_^CptP5uzjc29%fy#O9y_+Zz%N9#Dm
zP#l{d{4;5(MDzHHQiFiRYd3d2(|Ifx?^TWhzfAmCg)%2%@OG_6Y1!<q;8EG6bQxrJ
zt~Nqeo+>W3RFrtrE-8qgBrI9wxnYXyj4`KRu2F1ZZ(pohn8bv5OZ;S=?*Zs(d*NVz
zx#xq3&Zq3?=9SxRb#?%VYm92IgX3HoV)~52<s+gNxu)I2kHh&|Ws~E%<!ef7YF)E*
zq$~G0o!gDvkr#)UdW%+bIR#i71@)ICY$SS<w^W&<lVe`CGUB`Ik!vALT5u~4Pj`Ou
zIYaSOiskVDNj1qRWPhpDFAGnU^)M-z`w@ZUJL+2h(>r?l^T-D97)#zTgaG@SHS@3s
zD-tL<m_oDoJ(2eHgbb*IGtR%|KV&en^FxJBlO2LC+oJ-f9L&G%{-O&V&4L;oN!7)!
zcgKOgW&w>DnM(5Hux|X=X>I6UwGEN;`;m3dhI9;1UF}aOu4o0>djh|&WaY2qdH=is
zsxjiY%wa+H{71=2y&6jX_@`zQ4TXu{u3TC)YkVfd)kZArCp;#uzmi+Ay^?n=#mx>8
zjd77^OMUyDQT&LCFljnRt*L0|*IPmE>Nn?MN%(NENQ}A;vtF&L%|gAD4<ML<$rB57
z1JBR6H@nNT>m+|*iDMyx54IAzRqT#c5L~2iaW81~?n++b&C9S)%_{HJ;_3`|?wnqu
zx!@c`Kv{yx@)0gV+7rC&56gSCHR1D@b~IHRCzYzgqmGp$!j*r0<qjm^qRE*?glU(t
zlf~RSX)ao$dpwRHv6p<@nL-fFJ!fg^^3?HThhChOVHr@?2cS>-rCei6F#Hp~GTIiI
z7H>4Ui2g`AmkglCH<O)2kJAo4M*s-=xBbh@uZhkvR#j!~%v%qM&is?_*cB=?Yt~Py
zV7L3^*D0C*Neb6##%J53PpuXcdE;x6Ymg&~0b?aJg8*pHLs+->T*UWF=6%LkoB&_B
z1!!CJC6_1gth_s)nxdX#u>T!U+wgRJxPYrzp{t`&I0UPTR#e9m;~@T!WAXm|gr+;1
z${s{Q<P_-Bx(Sm;kvV-kY5UiN0p2B)q*0i4+KxRGiniR8=au}CY><&e>=Ly_s?~(t
zVXif4O^MwGc|MSi*CQ4M$r*lAiz!W<blJ$QJ^Ibq`%ah9d8aYKIP^`{mTMb0WWS*)
z4z^Gd!#7QEEB@s0^3R-`o7>x{Nd|5WO0Bn1$*d8-Tl(j6NHch2A|rqMnMSG4N!ctm
z%3)w&eA$SXrMl5s@DyDrosRM%8xol;%=6dMC^yDCzs-H<cQdlAFS(7j`I;2+HQ!1?
z{qvI-*pM7$hSe3usiT&i@nDIlES$1psI5!9()KM{VbUDpm5xIsn6^`i>M($_xaIK6
z4ikmZUSiewT)6)~OubcDm0`CwD&38AgM@T<x0HZ1Ou9iDnWQw5(jqWvP`bOjySux)
z*{|zgYk%Lx(LCgRYK*%^9YtTQiI2^hF(sKoPFCjN;&_R%X%hQaE)3i+#Een`Q(%of
zT=UX$Tr%#baC6Pi`_qpacJwx72Lh*ti`j+b))<#BzxiGA`3`d9yD7K&WW5ju`89nz
zFpEG~!<|B2KtmYe(E4C8eI=xZf;C^NS@fFb|4<MZkY}JtDQyYY<-X-IY#=8Ks<If#
zDE~(NR>=8(#i=N#_v1l<-@iiaEujO84;E3t)y+M8^qjz8$V(N81oc=Fj&2_?i(wl2
z+|2xWOX-6@!w`Kg|HWaBZ2yr-3%dPB+*8ect~w?Pab1SjX~X7k+tREAif2hy7?C)4
zSd*Xm*b}RSByOMp0fQf2PDnfynuk9XH(wj4UCh%;B|c+TtC`b1rLD0W4x_-RSCyr_
z_#GP{mE%hPmYHxOWDmhS`<x=y!-gn^iUj8%{rP-1ZtDUxWzhT;#J!@#jh)4DxZbf}
z|Gh7K6X|0SCWQbpU%;nzPgHEdfI1_B7`RYrcmwWbc3S77ry>qUPR1g`Z*2%&cH88!
zsxvy^XDth@*PFeJ?VWcJ2{Mmp54JGM5CT=ipl2YsqEb2nuc9XczY5@QD*<XKwnV=n
zt^{!4zFfqVRdU<Tjw8jKf7fgC74`yfE_z21-!h%1S=PIcUI3T25RMNr0_+JFOW>qM
zJ;37N1+=E~0OX?ZqKeAtSAn?lJr=bio$jgL>3P}P?D}IORTsW*mmIuMo!!DGGS?Xv
ziwY&Alk3Bo2tb~bq5Q*@gl>H3GXl(lwDaff{v8nd_NaMTzhsi7j%|URmC9V;0Tx+h
z@sMXaCPpdUPGzyI?vi<6E0R!7<0l^^%lKFLn?dBV1gFd!Jr=tCS2WMmNrK7Upi0`%
zOotyBQ+ez(_l7)|I@PSnQ`S?5iD+ATk$%ArL}xwv9Zw8&qeub1^7uoSBx=!D=8fWp
zCY9Ts*;@r$s?m?@m#D64TNyM@&H-sVUS!|Udrxf38bWRkh|`Sdi7VMKy264R2=308
z1N@2T+GmOBB4C;uSAF;FyK7ArcJ0L0&^q*WlqWGL=Qu{Nekm9izpb44*4^a9hzRt&
zb^%|mBLI->Flm>czrB0D>4f^%XZ90vT0E1Y;KAAy^k9Nl6Arq?V(`8|wCSlFzkdEI
zK=^Svsr~!Kvdh~j@KjHnvR<4o2B=y9>ZWb$;FIrsN|>wf*fiac>uO0nt+ZwVnGui8
zv=v7Jtl>cp9CIK4In^b-GV+d>G1=Ql{9e!5PEj{b3sVjABhrwkx$*KAM136xy5D7t
zVI55pV{^V;+x5-ouA(5r_cyBQxj@%n1HMV$r`r>|JHxk6dhA$&@F2x=#XwcW=Av&E
z^jG9aCs`|PFK263lt|Q@5MeL+?^j98dh@$VsS6oA&p%pj$Q@$+k1<$Z{I_3$>c0|b
z9K%LZI75Z#9plJR?ZceZ6`D!9c_e-MZ`K3REkd6+F|me@r9?4=f_yzCYV}*q<!1{~
z|3;1*Xe2j?&|fADc^0z#m7n}uS*$1TnU{oLf4E~#n&>uvMPqPF^_y$?=Joxn9N+!}
zR<v`*4t=8V4!GgC=V5oiMW!KJf3xx;vbukZp^$vMEXLG^I(Opg8Z4Gr)EOG&#VSq?
z5HjXEJxcjYj0z_nHV*{$?4U%r5(`o$h0C~o-h>;WsrqwV!hWBh>_Zt%pQb+9b>3eT
z8@Bmw-wcY980niRhhU*R)ZZRVg+{LZDqFPef4psSuqF$-+et`b*qF~K9nX)Z)DShU
zXT%FHULPxaeH(c3jc+S|yZ^T*{&#ac$4dY<(~YY)`&U7>TqCFNI2-FX0VTv8+|3wQ
z6>RGdY*dbtsHpD&?F}|cqAnhjvkrkJ@XdPx3z@PEqxZtuY)R^Q?Pf=C6WMIy&B;<s
z6scfzq^R~E59l@efqSZ?WV(s$gq+IBmSGqhYDHtO-qz>6Jhl3rXd$A2HAJH^;ly$H
z&5>pB9;sbNfb2W~0S?IB^xzx*+`w3JT)b5K#3AH{TV25X^;zPbI{~G!RZ*>ILI%K~
zft}l{0`a=rjynauiHsZ4e9I4Z2BhGU!Z%b4p0UMW9z1_XdXVarPIb2w?91!7hKqm;
zmk;U+4vFW8H4q9IUOuOPzN31%%60lPb0tI#5+H-t3dScog*1?+qpQq<nb)qS1wOtw
z2?;sqDvFTp#o|w9UJM5rcH_Vp{2tz^gz&ga`;0Az3Y<w_Aru(wRPc;Bwp<G3EDNR2
zrHzFY(H(rpAC-ipdFZ|0K2nN^NtTNiAcg$o%|J2c>#WMpr**$wfLQ=CXc%@)MR-kz
zsf?c?E~ETr{fiAQmQ8z<9&W+_-M}^1^%Rdf50Q28cZx&?OJ5tmwg9S}wxwq9)w`!L
zhyOd{Mjf4^SnWqPfFBO0oE{04@pZ_r-VHMX+73pt-98r^8<H5l5dif7Coq9QCP~cu
z)lBs5*`+CxmQ7#yW?J2DJX5^-UFTmdIW}F_xM+`mIQat5`1cXf@`RP0lQ?t=cWd+}
zV?&Yyz982%B!*vjN;@%!uZas96GB+;biyCIlYQ+f6bd+t8~7F2b$3To`yfE6v)Eea
zc9iT|3E~b(za@&l<#EOR%H|0uL#wt|pi-`wv-Nio$UNQ&9{$O(B4()lnB;AMW`;LV
zO+TO_#EADEe0dU8I2<k^Dz)iJk;oYG*nLAc8Nt>@U#A}a7`OCs@R9DwGAK38aC(s?
zME+ELVk%p|Ah%X0(p7UDH`@L|M@m+nkotpl+J1HTMc#&b99ZK^UyOdMc6jeEs#KFp
zKAaa@)7n2#V`}oJvi3Rj7vkqBM+qXyhz8+Da#Aj;om!nmxwSd{l12CzOv(<b6FNT(
zFTH7}Xhs}349!}!uEmLDFYA9^q~a09u%9VImWM;o2?u>ww&rX|Bt(r#Oi{aR@#yeJ
z(*=`jYHMq~PQN42*D9+(jz15JJmdeZOt5C|y&v6rV%D!ew<gbExm9Za-#Z&PpTRFA
zwf0N1J^)&CwxQrI5~=rv376iACBR<xu45Jj64L`+sx4%suv}Eus;jjQ@+qQ-#81|D
zMgr@1c)-EHW00V3y+3XGcBTxE3X8vMxERs%j#b#{+1QK`w@WC2Ib`l9i}E+%hPvr=
zmp1qtRgU4I=}&$xCOOOuDVLL2riU$CYX);J)f}}Q1Tmuwd}od;NOMMJ_IO~hOz*@Q
zKlfVC^r!iD>eR8LjVqvwc%5K~a>)IWctCewo;|Lp5aGg7waL5L%9HLucH&RGZbSB}
zjGUynFDTMghd5Q$Z-PK$Na|YFREG#AO@>(|5(Xwp{7F?W|CRqMhp#lD=nr3<vS22@
zsGa~PMLZPvhkcJv&GAkV9%Y*!cVVTq%wFiN_=sFH|6CYU7ff1oH(C91;PM{13AZ5*
zaYkN|##xnSr;Tj<J25Csc>%S(Xj^6uu)9KFkXu|W-X<^kREyW$>Cckjd4VYAVE`6V
zu<9Qyx{{DiM=T9v{TC9I!2?KvN`0vR@2&(cO=D454}%ij8XJ;;4HE@o(Vl3~sT11N
z7v>JRKsabruJezbs(XNl!*-4e)+zB`Q~cB|FgUuI6pp@Y>mMLN2LtaT&x&h$Uz3h(
z4DHjw%@^fh<4BaD_SHsPc@IkYJoOV9@;bgpta8B*UTrzy*ZZyG^lz(KB`or*RwozQ
zi^NN?f{i1dP)le&Ei?x02Nte_I(1)*9oky$HoJeAP=4H2W!tyzpmF)DpOu-!Kr_co
zbD-*f6q8HG<&Heymg{WMlHf=$XO0rWV^aT~iliGU{{1<9H<<4HV?Wo2>8OiovCx3z
z5U;GyDQ(Vg!4gZC<A?h~=-X<4gjfN2zkE6^zw_##=a;Kz&Y9t*S`SF>5PNzW5rj#X
z?Q$th*2K5Js&ks)EUr)5h$(>bsB(zK6zE^6z-AW>Bv*W!1XLZFZUE9d+fwrxQno%2
z4kN;bV99|F)*le!oEWoy*E+u#)i?(DXw`v6>4EYV?LYS$a2{X*$<nKW-$XfbLA`Mn
z)EFZ&#p!OB*yaNTM8jibFHfj0coVYB{ls#+2c$)XO?)Z2kYquKVTPqou0!rL>JToy
z&)x$FfAeI0j$g{@TOqX+`(TJ8yf4XHbCBp*a(t%rb}$#?-9zSyH)wjpdqc~km^<%x
zzsEmw?$i%Iy;^T^|IxdfSz*X})H{d?%5L47uL4q=F>WVkgI!5)p^yD?0BD1z8!+U=
z830wkzgBP?;>^y^IoE_CrGBmWbVh_>eDh0PJzC*@g~yzugy_%&x@2+Uhd(OIjAK_=
zqo2sZS}51#4xAZUOS`5EBUkKL6HMoWO*Z_5<Q=kZib$`>-rKc&ZCCKCJ8;q7#RGg-
zBCyJf_wPNN3F|pZ)lw_muRa;fxuH47E=G=EU}t=2X!t6U&-+M%6A!ni0!sC|Bq}qI
zw*aqNf_fxN84uh*ap|`0BQw|PW8cjAw`bTl2L)({q+eqYugtr~%Qw1o#vsBtb$Fdi
zNe;{j!j*?9sjYw^^>!Twqf-8_{40sD^oBhb{=TbBb9-o5s^zGZU9s=2(tj_TA6xT9
zFEPy5`i+nbBUBqFJu81KeFFhu%(j)Jb>7p0^>6j`;%P+;4J2L%dC4|B)BO>s1nT3x
zJIRL1PO88mdd+LasYQOg3nlmEYr4;l_-jbOTHa6L4L8cX=%6(aSb^pdu@=%;s!8`r
zRfPAPKb~$1y3dKWDuvUpOS4$JqxS2{pfAv?x%WjEno&qZGI`LiOSJ;9Zl}U`;frpZ
z<5@k24-VBxIJD(}TD=mBTIT0m7htMg2*wBXvo!8g2{c@UGnN|78GIvcdVM_lCvwm>
zHKitm!D_O&Jzf9`7r0{pJ*Nzu0JtCd2(dH{L>O&mI`~tx`IaZ*?DyVdJC)U#+yhH9
z+g}s@ipvIYNf#d32yDO)M9sN;Aa&NGG2px&b8<#I+20Agm{o(KTaC6I-!k)Y|Iqxm
z*|xV!sdK@e{d$9Fzwmn?abHW%_ohjRX6Wfk66}HtSiZWkRFzhqp;WY#>l<t%#aQgu
zuq|9+R$4~R^wOh`J3Bm)kJwYGpADDs-m4g(>x!0&u;^=L&nXdD9{S`y?KZ>{R~hZM
z9TpbNJN1$F0Th5y1v7z5YjX`I0;iEk=dya)1<4yL;Cz9IwkcWu{Sv;Dzn%LQEr;+>
zKWPr9uezGCc6OV3WVc52pTbgmzHhxPj2y7nP5K3Qz#y@n@`aO-Y0D#lWVENbo>;Hh
zJSiYkmKi>pSDg|pp%iCU_ytI0&i#}X>Tv!am8(1dYWx!{z@re1e%x4`_+f>C&vkH3
zql=grK4sN3^v`mo)m&D44_`*@q2dD|EM{_^fIs4(-{Tt1^vm1p%YYsfnaw&WUVuDO
zgv6&ypI@Jo4P(n4yWdC16X2+bzPKVsW8~oDIRnHhHQat^@&dpR42e9SOLFAb^f_vw
zw1?exhT}g6n@20TL$3sX3s!a4S6LiC!Bh49q_K0?G(G8?rk7v+rH@*D%|0qa*ZME=
z+O2SmBj@l32@G8U+`UEf?7f<4DZQ7!c_VwwZdcT@jUf#rOEbnsvXM+awprdbl)Gdk
z?h|AfYi-Xvwzojv99Ka`E<Wy8TJnbVx;%$4+yq=ZYjm$^-a$Tr|NRP)cK|Qh^2@DG
zl}OiY8xv^!1s9eGqm;if<gQ^q93R|G+FAQ^4&)WpYBz@>f?k}J<xlD|%w8?#PZ{F(
zV-KFGyS{Nf0L5zKT^H74a$q)2bc5Z`T<`UaEikryLvd2_kQzh{G@h=pFKcsc9lC)I
z`s7gR6@T)$n~Kh@-GO)u5L9YEzg<I>{pB3x3*78&FAs$yyYJo#a0<l11D|Vuza#QM
z3dG~pz2NBNdr$OdpR3L9VAHT^yq1*zqD1J=m@t)x?_6o<r0{mo+WuV-j<OLzIlE}U
zGbsxW*2?<5LktoHyeo^HMEf!{Ma49AVk*wRPhri2d{I`A%viS_Y#9GysEV!{Do^rr
ziw<+vCPugl>52E5p6qUJ(b#@0nglhVft$M@=m+<P&0Ub!s61V~?RKF(ooSncg`ANc
z-1M_WoYf#aw^81)_jZ%<#o`um&#4VU^{0p}s(WfVs8#$fOO3ueA8T^1bmJ{Yb1~k#
zN^}Vp9OacR&Ft&26db6skoc(wQQGdCOX|ds33ty*yc)Le2@d-JG~@@br<1y+nqWfs
zZ^K%E6cpn|Ih&DgDp~y%<7Z3^{rMLkU}0Hn9kBna6FWB72I5iR9=u=A*pT7;=Tb-H
zJwx#Cu5-Ck*W1p=(gjtJCP76V7I&vBxJ$5fLvF}0_m`|^%Uj6cut2yj*jksYw_Q6D
z*=WDnd&Q@c1Ptq;!m%AsZ%SkmpoafU3TyfX>@b^Ku0pf&04xh2j^#K%^=tNt58I+s
z8O%Af|Bx|F=Vp|b&IaM$`_leCmvgibmTD&;B&CvbOeh}pdmw`0U<fK<XUL;<n4Irw
zp5%O<WB_ao%lY##lw~E5`c@7RR>{^jU5VifsQn6!upTTjPL7w@4)gNQ_`J=a$^8B6
zK6$Obb4<9Wao;WJHWs`o{lUO??G1ma=wcO<$}3eZKig;en<`bG_|u-pEL+EZ@gDYq
zEs7N!vPzaCSM&HA5kl5gizFpYh&khWyhf>xf8g+tU25~*i={b4?s?dG)wWX2YPeR(
zG;J37c|fL_dyv}}V)*euY_ck>)y}+?c&YFUOB@C-K@Y@osaH_`cEQfYjzzhfF_nAM
z+!G$uZi@m@o&OZgA35f*{4<yz{q6nzJ`^=}t?eAjd|bWN1eG7z?{1<Oe#mY#tgi)k
z1C%U{-zwyU*Dceh=)X>ARv;AXB7k9~M9qtPJoFCnt%+zeYy|sANW!d?c^HF7K%C1S
zFp_X4+?21_sN`%Rjw)ndn<Ye0S%Hv1Toh!IV3w_|Fa9n&(<J%l->R;MonS}U^gE0~
zb7m^WJMbEG1AnCsQY1|S>g{>^x)qs=0;B%GZ%}vc0Ud=vRcpo;7n6R5+Z*N&g@nTA
zA)Iyk9SVkibmosLHADXU^CWY858OX`d5${}1oeBLed~67n>60&F+UGTmi@K=yF)g2
zN**-j@A?hS=1M{fHMaO*c1MRM!PELc*Br7KWY8X9`nG6GztQ8VFs33j!F@R0`^&G`
zyBDo)PHf?$x#)J-H?dG4WL=6rx10O?B6&M1GMOITnfE|GQuTTFIS@(6r$YKstL=~$
zRr?nLyF<HGbOYAd-f)T}9r`Q^@tR+T(pCP1KFPJ=fuCd#{%ZXlpbCAQot<U5MeF*n
z1_?a?2z_vGIT{t@H5r2S5k@!tzV6}l%B`a!q}=~&!gM~Z!DVU3Eto(xM<yzp`Kxy-
z5pX5_qGQuHaJk{`{7&WQ#4*4ZUZfa<vnz=0LzFIJA3Y31mx+%A5zmp0vEW_tz#+6;
zXP+he-hr_MZ467yX@PpQ(!@(xV8%+@%8UtK{tO3kbO`i)d8`nJL5K~-bL{$|+b(R&
zAz<9`+X+@!-rHqylVJv<)ElbrDS%A)5)qowPb+aFT=WePob*3MOreU1y<Y8&Iou6|
zti6rh9dA5fsK4`CC!WYX_%45EDzF<SB-<E6C!64u+w4k9dNHZ`K=iEn<X&Cr<b!q@
zB*fhyp`23vMU#e3lgIRDOHLG87In7hOG?hP>fon(bqMtp1DGjwzfi`|oQ(e2DJ}d;
zkA$3#Ma$sSTEnp0MYfB2tNZAqcY>2671(^*J!(sfbx+QF>Y6TH&d}UvH0V(;aX4r>
zEvPmv+@5dpnRzOL9Tj8V$+S-uRpfz2cQ}Ua@v0;^Y^=^^rm%4@2Jjh{12*Bf3vwBT
z-;$&TmNo3eqY*enwB-Qt=vU>m)w^|^8uI^e$^XHiPJ#fvb>?0qA!n<@IsR?+ANhip
z1mpO98@bm_IKyP)-1Z?MWrX6Mqfa2I^;{v?Cz<acZ~oAUfIglBTu(ewpKErz`JFDS
z2r41@fZ*)tIhw{vXbycT=rIabW~)zh6S$K-XD}jW-NJa(&)cnPf4f&bUZULL%n{l!
zw@?Z!JFMVh0PBxX@x6QdXgUV=^ZqgGcq5rRfnfF%R<#kafEhhFy8{ObMW`RPml_<4
z0MW?hr!?n~7aAmZ;QOJh>ncaLE?nbzb66P2aJ7dh6=O8QW)k4uN)U{N0y3Nby#S)d
zQ?_irySsagSgi<RP4=QK84{T+id1IZv;W}B(8f8?XfbWx;=A-{lVDs^`L#+>>MZw@
zkEKl)yE;rXsU$)M`R4V2r~cos$G_!wb#~Tv!3<OIN-2sp&;5T)dE`Yo6Tw={Dme{V
zJUZrun+7}V-@zD<NMkA<Y0hO|zHaYTRIE=#Nb&%EUyBpc%iAY`M91NqIpXbD`DfNF
z{>2Ojkl)Kq)d_Lve=Un!=VFa*XoqcnmN6AGt&w+F+^yhy{R=g82ZrwVi`CZZ2C~Up
z34Cwn5TOvG`hbZLR-yV1_>c(B$BYiz$P6*VI({++xW1O;b?e|Bgx1EcBBYC7NvwvT
zDR<m-IzVro$)~dpE(5hly>lf?{j|#QgV6&9qX<HmE(L<6mWihEhQ@%U<6y!xRFja2
z9aiJMU?z>PD~4exu@l&gkI!Nb3icM)q0lVC3A+l`*4H*0>}5PR0~CUG&p{W%SIzET
zO&0{VoPM0~wXkr_3g04IgP!F-TvX+#H8wgQd_2rktEtn&SJoar%W<-uoEUU2$}gD~
z=@qu0E@{bA|Len&>Ka;y<iP3s_)$6UgvOq6n;f2P4zfL#H(&U=6(c&!?Ps_4YIqFs
zIyE-!i#CmlQsN5DwSp++GyJktyY8?A9$4$P6qw_s|Ng2P5(H<5vlp*aWE~~O`*Pge
zu}(pB%?Z5R7tgpay~$=ITIkfn07>*YnX;g!CULPZAi!(MHEvVim=Q4`D29mpH!7F*
zJE?oF9(81f_cT*iHtOMP2-Q>_T}Xzb$;^5(;yy<!zR)o=)h>(H1wT%hT?Y-5S)|&$
zv+;cY86oU|puOX8#*la?)mzj}=ZOoI8hNeBDw@_jT*xm-fdmZUJ(uk)Q@Ei<5xYxQ
z2pWw8!NvCaRoE4`Nq1O#YKKaF=&Bp6-CAq9Qo2B5^C51_C+lmvb5`^9z`?l$9ZPkk
ztgkcKG4IuKkm}_8aF!G`;_OY|^Ksd@5huDMB8YN-YW_5E@BDh6fIKL>#eZ0!+Dj*n
z&QbC=fhBqHO5zJINOLCYOYvD){+Fe#&$e@aV4~zbEq-dnvE(iGQsy0ix%ub@C}%95
zlnU)?oZ>hJ3RH7i28#C{wb4WbatCm(i>pSnnS(B6v3!5QVK)l{(X)nk2)_X1^TP`)
zsNt<|wWd#7wfF(*>#4=uc4LtY7Ax}c<K_#dlqvxkOq%T20RX|KO}UJw5Q>>jN0@AG
zmC8utG|$O$^;7u~lJ|>-;ge%Z=X7d({xYsZxDY0u6L(M5%G+q=`J}ZnV*vccaBeA$
zKgO~8D2o;Xym3)kQR{1KSyFw7H|P~CaNy>#Tndo-i5w;jpEJe$q2Z8m=|BG*_PA-{
zF4A%c_D3`fVu<U>_6dp&7slw`CI)HsA5{1}xjR&5SWLbF`%agb$F96Ln)K*Ivo8b%
zS~ikEyt#5eNK{Uici(J0hg6nVRGta`)Mao3-^z*+j~4MFup)=>yVe9ipxGKYcEIJf
zunnuSGCt?qlXIBSvu{TcaSz(0PkllS+J||(fw0(!GomdWpPph>XBGUtMZmh@zZ^e0
z4~|89%mAHz<qEq%{t@?AoKxxY5pc4_I?4@_+cXCtz@cg?B#Xm)gM;R#^&DEb>1B%B
z+OEG9E$g@soknlyV7J1*ep5I_x@_akZeE3T3pqVdnjTwqQCz!4K0SzzO<X0bU>Y=^
zOx{~1SbRRJe8tK*J4u{lwpHL|9<p^ojZ$2xe4OWy+zKU?z4bVYww5eYv<PbR%5%Mw
z8FXPSfZ4o}`IZR*Rc67IDL{MX>Pe`prR-U~9}@8K+iz6vL_P??yp}|AWm^@UA2<gb
zYqpPDu+I1(uMuu3%O~fR5rWNmr`;osILV6;VzPe?J{vc+>i@q&nPOj?ANK&_@|iah
z{g-~%Q#ccZ{?_&CttoxLL!4Dx%h09f=Jn}}H}MbYKm%3)0u1_%h>dY;WY>32-)BA(
zu1h@Ez%b$M`JW(%`ML6U;++QP@EbN>tMl=TO{n}yMhOkQpy~DqWEn#5o6tJK)L&%w
zy?)!T625dy)#LcxR&z%LSWPLd{sowkTK}3t*7gjU!Y5MD%}-JS##@Qw*qaz_AfZE2
z9ijzD3$Hri|1zaHb|U3sq`5y<XDKs1|5M$Vppw#41nmP*M)hzhOY$1hVzh|$d9!Wq
zc1Bv6{L>%0tl_&{0^*e)U`%FSG%$bEueV5VG;~qo<+Goq@t5h~(uv&C1FShLLlAWe
zD(w!`=}D~q*#ViWa4MpgC%jv+N1IM7SK8HeAgTzJ7(yM}#=`i>^brm@leR-KmnS*p
z01z@&gB<Lx#oK#_#clErAzONSdh#o?p#66a{`YgkwnOO2>r8sWRg7KRC6HyX6sw(b
z=g)lwQQV$+P`h;NPDNO)!9>(>sKoz7^X$9h=V;qLHpX$sRCMxQUV<sp2nQGC6F)(=
zY<)7qjw)Sm21OBmFctR<cnV1i=DL6kQ2sp`Qair)c3&sDC!$Xmz8?`)zwe8z*Tsxq
zZzN$-zI71jaR#&~BB3|Y2w+zOCP*Niew5y|xu2IG`a}C&D)z4>2SDePu@?ZepQ?Ke
z;O#0xB6g057wt#K#h4CoglHd{GC;upCw|fC37}fV7h8St&)of0Jy%tfd0DCsA>TIk
zj1nSG5N<u0#c~)q(I)P#?%if-%;$11r_Or~%8Pf+Ls^?B3A;GJyN7nL5QqDh4>Oc7
zV%O@_`D@?@;|ki?yx+N{?=sZS7jq~nG5A0;(9ZnruTes4Kd<en{Xw?<Zlrllnp<a~
zlqdqWn?XpceK?QoP{twSQ*3E#fRy~NGfAcA2_R6QkYU)DzMP;Gvt-V!a#E>L6Sum5
z1LPhj1l*GUbq3mlfpEB(Lxaj~1jX_Js(BeEcbn@v;f7MThd1_y5OD+u8z8JNuFKIU
zy1(Cw8IU3!nD=MfE+>;aZ)`N0Wx~b_k(MdZj5kVuGb}?nyTZF)Zm9`#w#@}q*<hPa
z0x6Ovq(UBS8p^md=CZ#iv43_Ez`&3$2G>?@#MZm-rdVRbXw4X`{|we<{w?x}TBsUR
zAan)g?K#7b7W{<-GLs_W3f4%z3TJV)MLI00@~+D`aJCk&M|I9OmMyi2)bc=w7b4=3
zdvFDM+Bi6hW`ZEDne<2F&(f_W9p{|^eI$5wfL^ehnjOiI-W|#OGey&lktpmFQ~x&^
z_amfUNqzp<xki)0gUw#m^a-5j`@_u#wV2GjB1ZjIR8zAWP+90{3EgRzr}k+4Y|rFw
zZ2?Qx+MK*WfRl!bxC1kL*|UIIV`cB1DO1MbfU66RGtrP`esd|GFc1*MO~MRno>#b3
zUX#B61MLI5A`B$j#;p~mENjoVZvrT~i->ahS#{&Kk9kJuoKwS>N7sK6q(Y02|2a3l
zSL1VYyf>9VfS571nZGq_y@Zv3tYUr>v0LQ_e%f`!PzAvs2u7jeGy}nN?<2L2O`zZ-
zR12c0nud(AS#v`rGc1C<+-4fFg>d}yr$$3k+mPT>0Q+j+>8GB{_4AFcSxF3GGaytc
zhRN5cT*8B9WDB+%>^(y+cxzYGGJZ;!Lqeojz|4;Lx_t%SBy`;F$5P|HRN6U#!+xA<
z7(*4d<dB_e`HFmcgblgc>0lho$G;BLLWIi;X{~nl$NX|0xnf@)ye%U5L03da;4s=d
zpF4Bl@yZ{8i~>b>drzK9@bYN)9b{*TKp;b6ccc_5I;P)K>8lX5t^5H;julU8ennEk
z+m8veUgau*Ud0(LyNuMp*=Shjy%}5D(;`FEk?qE?9Q8q4^+NTmzVa;i=8Aom;A=@3
zAqm+SGNn}{E-rzS&{P1r9~|7RtZgkrSu_q=b@&OR_vX_8G}T)(k<$PBU}uVTIN$*R
zsv}qO*(WBkib)$UT{#CNN_$}g-0rRaAmS3hv7g5S?+xHUvw6uN8`5vfPG;=wA-3!H
z2v5sk&M|6`3Y#Vnu`S`+(M7LV<kR|5gtZr0UAd=pieKeu)Qn^Hk}*loYi&98-d0co
zt^#M3e=kiE^@}UMIFBNxO!1Vm@W}5e0R+QYc@Gp+sOr~3`Gc^0aun_$FX&jNU!7eT
zqKcho<qDL|^in5yi4MQ1e38wdw2h<9{1I7egs?H<*?PHp89mA4HtK3?u~`w^>%@c5
z)V4JKyiyqO#I+7tl+@gn)S!@i5CHmGU%AVlHKXYY&HVR`<~}=v@97HiuYF~|jyM`>
z{1N)~!z>^%Lv8^n$$^JAi7$nFWdDf~CWr9umqlfT{imbE12nKsaVdLXGe;4_wUS1*
zp^`Cwz8u+b*e$jI<EDUwfb^<XqS2dH;e}AnT|EcI^amz#_49tkM@4BC7z^%!UpKKt
z@r#RiaX-J#auPHm2_T1k>wbNCQa{2CT3Q3Zv~6m%>w4?UMs6u$*OrkslZyK`pvodG
zwP5+L^WieSwkAq$m>Q8sl|u7PQy^Vhp(jO3OCJWqz@t6vJJQ{WUrRbc_N3=LMK@YQ
zu@wO+u|#MO)TL2JYMA0Kqej^&Jq^Ef|JnJA{LnhY313&czF4<r@Ly~WP7PX?SHBbV
z8D(|Mu981igwmjh#W2ApIE0j}LJWIyf+4$v$c9>oz5M%Q8Mke{??1ESUmP;nYT;Z5
z(<MmInsMW};m?S+=Nr~pKw~|V5W5dh36wkE9keOb8u+a5<!NXzBfty>Gi(kN`0K0^
zd<e+@@-WyNsqj;$EYp#87%2Q^zAI`nZmt18Y8HomD%mGeJc~U{i`BVS3z4i&aHCtg
zpHU%YnsEj(TW;J3zsw#mOF6#|gH8Vub?DU<+YmL#Q7}THRWez(uC2KJg*0)d78ksU
zQ@j7%iqna|MP{)1PbqNm;<>))Sf)!~67%F}k@-D4T`JQEL=*fKpf)G-Ea_r<J^Nb#
z5zrVh`p<*@Y_Sd`%ZwTV3enqc9lH2kXS#Al+J5owZbJBEKq?mNt=x~2(CyI!lC6hx
z7BcR{urqEhHJT?B{o1VYF}YdZ6F14Ulun#rE9itNu|!|QVa4T6_{X<V$v=x9lJzAz
zp{)N<M7mV_oO2NKJLhscyb7sd;3;~qywA7KEMm$^-9y8!Gu^lX0=u1EMV^+ca#yQH
zg@zm~b-sZ3N&SYNUFeC00x$kWxlqacsg_Y%MiJ=}gZ)iOoZvA39<{-woDFY^RdzgB
zpJ%Dgfjogt;`kIXr)akHL)^q@rnd$>MNuHd+23+~<<UK;DT5zOf#g*%Bv%Yew0+L;
zK5EvLt>KO&NeKF114LNq2yF+hKLxjdL_YOGC#rf4kNxHz5}2JmnGS=?r93~U??s5Q
z5IGil8J_A6n^^@>kYjC{;d*M#MP>YBME$fl3IC^O_@7#-&2zr#n}eW)5VEH~6YbAE
z`LI(dUDo|>>H~nel505+l|}DFGoChXvHf%RzOxH&(Y#9zYAZGYFT96}AO4IPAv#tY
zeJ;?Q$^ko40yr>A)$hb1MSyrbtlIySUTz728dU;rqefD=ltj`fWg4rvZTJQ6JZqR-
zoVB^^w0;XcM$>b-!W7}+nMl|M*IK=SX`{$Mvtc-4WU^fd216LDMO(3!*{({n45TD9
z{yR94QOi^QNoVVQ^Tqh6TAauS?cM#c9p@m?Kq$FZA@6%fTfkdQqGXOV79f;(E3POg
zrLCxqo>ih9H-z1h{SyRE+2o-mY}!Et<E<Lv)$!_Ur5LfB>zVmTzYQ&Y*<DgsR<lgm
z_{LA_b6f?z(s5NwvZDNhB&64azm>elO~40hSDroCj;*oaSAc8<S8~hcR-Y+9m#^`k
zK=GIBH@@_th+yiOH@4j=$5Wa!OwTbOn!FgYN@jbJEv-o>0Y`0?&@3qsu9?+x4!pjp
ziC7B%c@N6)A0HogDZdnqub#4ChMUE%lMq(Z^-s%H@>R_*HrQGoO1}Z9sd6h5_1t^g
zw0E8A2iH?7bcX5dl(Lh{m}sa;Qe2Dk##29flFuP(@@h$MsF*i7>6sffb07sE_nl4n
zm<dr53)O{--z%cYbf#bQb>g?+H<rJB?7E3mOIndRE#2f7iDYCl(@)_BsQ>a9Ay|kg
zR1TB`#W|9r1=xLC=%=FG?Z&*NKpVqVvqYYE1F$%?%0d@XRMf8Gh%xZTz1r?A!vS20
zQr=kO$s-oU9~6>x|Jm^~w>tuwsfH61H3ULF<yrAFf7rhp7j{n}?LoIl3-7aG$VLw(
z+e?Y2amEi$K#y$>>(yl_Z8p0}%H87o%}VP3B-fUxEs`kVjeF1?7gR?|isbP=^Mi5*
zTpyT$GG^1`!&GpV*C*AxrphnKX^e>kzCCl)@l%d^(gNiP`zzyE8p(5`YD^9RFPiRX
zd7PFITY$`JbEFJrGcvyV@mIaze=7PC)1NTq1x<aw+l-(t=C@s|VXq#Z$6^2t6#;kE
zf2!E?qCg<RSIN+Zb^qdh3d_D(m^74-5gwDi(aCCyV2$x65avyZ;_E?UthUw}gi57&
zoMt`sbBOwj1Bt<iX+2BOT1S1gW0vVQ7;pn)e;{fD94IX$T5Q7=_JI>thY1WxSw}&k
zN)tA0T=3SXj#e_z_kw4QQ;!dO8IoMLH#hu(Wav+%7q8iZ4810*z9SURhZH^`A^{i3
z@?i&~k=EacVcYL{Mv`D`nzJL?|HUJY+c{o#^aqQ5m2wU;XdTa25qU6chi4+_C})#?
z>zrSROe2E%X_(Vxr90YnY5pu>su<McXJjyOL&Wf4jtZS2<%X9^UqGNx#g6FARqq^I
zo8Dsrd*)klVNqW#lk7ksl+IQQh$K^k&}-Sqdd|Bgv?;G)J5K^vE1b@ffd(s##?i1I
zP+Zc*#Ea{PV%Y-ePSi7~vj4U9;crh@1d~EEj5mvpLLwRiL*9rZ+Ik{5XN#{a!GcU5
zxIa^{pESB1$&Jzx6wdz?plG%?`oho%k6h-9hxW$%ErybR(raMCAz3^o+Y?!UT>{8*
z9@DKf`*8y#RE;MFx%yuKYEEZx^Say2rmuhKhWTdhkM4aflO+qblky2RSI8OVqv@hm
zvZ@uUHe5;i68I+^4U24R5~XB_Zb^yD^6TtMqYhW6^Y=9@uI%F3hLTx8VPZ-OycO1g
z<AD0qMhPOcuryQDvy$%A8|gA&g8d@7&+S?f>FA?_If&6oXIw0OZ&)S6gUp5t0DcYs
zV(@?XM{Sc=fz1%_yVFr7Sz{jpAereLTmhG+K|`GLkJ4NON^{JleNYV+XPi>alOJA~
z6QQV|^~55?dkr$bQhy4ed9fsb65dLdHRqlu!*W2aTQL?uRTh;_q};A5G7J*n%zQF&
zvlk1cO%kW3Af9}RvU<Vi7C{BHr3uRfv0GyW!i{G-G%}ZVvjSU@ob@9DnSJNJ?Xp3P
zWzCb1fGbn|AfwCBTfFlrtLuWrcxnA=E|#2tW+G!jaW^!Im=|4(lk`6?iL7ul;2NYh
zP6)UNXE_d@Usa~vK~zfh9d)%mgS7l@E^P&3p=|+iq1h&SE{-P;IWFz<uOJ0$L`s*k
z@9shLgOC|G^Mg}PtG#1>mtxPB4e&lJKEbu9J5|u!`?%_^D`dm@1;-8`n>OWGB&_U#
z<5f+!dk${T^}@l!5^#<!HExXx=Alq+lS(3zHADZb`a#g*isW}=^?HPAugx`LZU4b-
z3ifV<Rt7<|L-w!(Udn?E&n#13g^B#qtHbts2vEww+qFYyGL7?FPtut5D-23nlZTcb
zeO<cwVw$tECGHjO^u9wjy&##Jg2oodt96AzOGQS~%WR>;WfQRc6r}3kSrx#Ow2gQ=
zM#3LnoKBEVFFY;=Zpq_Eg58&ooWW6tmg(g2^f7ZjSR6S|)xqXNysHDfKIKdXngye`
zhT4WlN>PB)!1qASfWp&n-^o)8KUsc_db*y=coQ~zO!wDMiG3c5Rqpd}rJO)uZi&=k
z3V2oVvUzUKvpl^Ol}Ug8b_Gz@zABA){HJsxsd2nN-w<Vbo62Yn6o-iiS=Ldrn^2)|
zy%#cdKUqv%%z-BZ{i>(-&h9}eA~r!I7MT9c=akKh6sm=)=Rg^dpZ^&JGSz?T#23?O
zJl=5LxuBV+`+<^JwYLZc0Ua}kI8xjSzp05LQU_35)Ly!$Xy^7$z!4!2JM8_6#>j*t
zvwL}YnQXlWN+&r%aYhO51CwtQLf<0AuS$UWbm6h_#|pfT2cYO`Zq{<`K%h2a$+(J)
z`&*7Fw8zR~eEhUz>PMU)bt*THp(`6hC}~EoZRk?TKVB;{pm%kHdiV=>V)*dguIFc7
zE0|)z<>-K45X4r2kQ!GXt$W$4`570JM+7ws%HQtxjzcebj^#TI?ft0SG#!$h^<6BT
zdlwh*Al>;A9wk1?NbUKDIsh^!818W{bUK^y7I_038m_V1?B@I*%$m9WC-C+4b<ObG
zirZNYv$hy*J)*<bXP0Q#iTccvk>4EV;WaLnjX@{Beo<%fw~A3GM2DcD6K)<e@d8=|
zzkm|{8ym5tB>nZa-q+dAYJ{^NVo|l6WwB-Fdl`Nr>@w|DpK3kc*)7*k2mtz4c@T~f
z%9R@_Wt`lk@{+W*EGdz!!>I7%9v8mwD_v&lv@tav=ll%24Hhg6-Xo5ya=^wo=-Mg>
zJ&C1_^$%*;!yZB6=QAKxan4o3_0t&;$@zmFr&0oEjok0~qT3XeYw9+9r@cS}<)%eu
zTgub}xe+VmYCRAGJsb)JWV-K1vtQ7g#MTB|tpGl%OT2a12amL|#C^-a|9!4|JwJY*
zlS{I}H|?P_E9K0zg+cn%pdY5G6dwaqNH<?uy*`h8$;M!#%d}Qa;ZOs6WAj^I%lfzW
zSGguGKN7ab58-V@LyStxbGk;}5B4`t(nAW@ad@YFMybLrEK`hW%T^ME6B5m%3g(jY
zvQYfy*5^APeneVLz82WeakZTpPyZHmAY&h`YQo)If$G8&`k4XVP5C0Q2RIQa$P>@e
zgT+C!Wn%j@%T0hQ^bQzccCKOrpZj0y2<3Gu=(;nQ$lBf?fW*^@P+>IO5Ye0VB$(`m
zifdnbVFQTP{-R<7gIuz?zb^Bc{K;;J{1b~1g5=R|WO6c1{AURixw|aQppfC`5Z#d6
zl7x{!E%63nddT>|FIkS+ei{x0PA2)H^_6-8(KL(?p6F7)DD3f3S#f9;DR$Iacb&ly
zo+Ql}5K`3kLVYdYOHeu4xJs95HmbJvaVCZsBRi^-+wL#VE3!5h@z*6;p$M~{p=3j2
z)_in~{&zvoRzu0GbTZ0D5vi>3@X{ZtDThPNyZFhIeo&CB(hkaS>~y^I$nf9Y=nB<K
z=}AE(99G!jagA=sXo_ANCZOnRzsHJ7o&GiEC3L%^I=bhW3VpZjqDTln(}ggrbR%G~
z!t6DBT|z(f_f076h|nFt$Un`$ZjA0VwC*m^#RkG&#;J&@<CZ*N`c!&dMMjT=K60`i
z<TQVd0lcb_Dz^1!5@!gievVr~ek`mBsbNk7)je~RR797}zGEo+Ba(aDKiJ90`R4E7
zeYZ&YO}Y_nZw_accZuaYkyJ6bP0S@ZI<GK@?U)Q2aapFjrWNJ>Q!7juH4`}lrmM1a
zw+^Ph@9`tL3z1O^s2!0{#7%!U82OqDfb8C{{~~q&;$8ovI+Xc$a4q`;d9(P@(g}oZ
z5@u@4qo!j#Nr=(}4*d44-YnS^%CKC|M(VE-AO&}mw@!1-JeKlaSexu_gI}<D?tvg~
zc{FFl;N!zXDtn`EeO+(y$^t)V&S@j?l6^nre9LuJBdR2fLC;`mdr488J;87i+;<=_
zrBx(w0Cc|L1Oagb<zi3u6{bin)g&39<Tn;I5w9ByP8uP&6N6gC<B}viAOc(pRjZH8
ztGMn@U?{N=adT~@_rN6e*i<AV2BEm<lXK#S6B+dK(77^lT$tH^vc~=1QB$`2Nr9Kw
zK{hTk!jyCH?>ujGp;V-37)=PYX<r#5j=&gb3o>TGM`lULKf+dde8G{r;X#;0URyTr
zOkbj-Ja%6>N@C#au_ZKAN2f3buKc~@p?ssmBWIfwiw582ZL&mUg%PoUx~7%#4#-b`
zU{^Nh>56iK;JYrHcX`Iz`^_eUHQg&Aqe%TYvVPj|`wp?7!OE9@kg03Ais5VlYi662
zCsQicffy*MN?ZqJ0CsIoVr6XdII557?dygsPnm-E%1GqUcgQIGy_|LC*|K~*oy)+A
z6R`h+vez8D&_HAzG+Fca>j8Jz7Z$Z{Ub}A#O_K!t;Y=q`oE#Pwn$RwC<?BnJr7fOQ
zcQ<p*xtT;DgGej@3TD^B*F&6%x3>FJc~T@MVl`WFxtTHi!Y(#^DzOte473YV5-L}(
zoDp%yAU1p#B8}MK2rCEmW>2h!&dSIIH3WCCa5ysTn`QS9er&gl##{NX2X&z-;4;{J
zV#jl&ra}O26i0vwg+XYu_5h@VDhyhK&g*M-m8MmRB=K(q_f(Q7DOxM1;2PsD_*w_7
z0IX*vPD24c^TCAj39HK639b0+v9}25wBODF0cGTuPkPOz^=;<U?@xI7eRK^cuokph
z&nn730i#eDxjll*?kI`TQq1Pp!V$_gKLpBFv=p%MTh}6z5kX4u9!l1iIIJ90SGn|v
zgyRr?rEz6bn>7N#;?b4j?@(Ody#b-&eetX)Yabx_`eK$@>!C0(FdG2tAlrf@kko0!
zPhN>x-%3FdCJefVonDU_{~=Y1`)!ah0>s`b{kZqwdk-WV#mK)y5f@)aOUDRkOsnR}
zJN@Wd9Y&((-ZFDjCvPXV2wl*Yw-|pRc#v^dFyGXxRhYqClYZ|lku1$S{F(|sIy-5j
z>u60RR5dxh?HjO&wxJq-9`%UD5{hSEWImrlDJZE~D{x7)m$>a0F`qPemb80EGny-U
z+NEn@n7_95n)Bgxs`j8l`k`n-;X-2(??ly`COv%Z!+qYOYy7@Tk@=%!Ui6{u`&VrU
zGqlPE9U^3!MGw#SV_#A)>kJv%YK@}62074i7YLDW#BYe6JDUM_KhqMgZ7rua{j<4)
z11rjComWVvgIPwYPStMPa#%mGxc_gJ0i-r0G?Z>@NV^}iLktfFlweU6`y2ybk4Pj1
zqwlSOMqF!Yz|(IG&}MdoiDb=0qP~7SM#(<h+J>899q!Y9)D0}B*1dZs`l-hvA(mAs
z(+Y>!o<!HY53ICU17OtS3csm!Bktu^pC+uZEaF|N{lIr9YkerLq>k-S8^=0TfZKr1
zM_xZQDkNM>a&ypXr+Ke>;_<lk-ZStjxW6cN+~1BBmarm-SpgI2=?kSP<EoHH$j1na
zz<sGs_0GMlUd*W|e}Cvydi#||w=W%xptIdn2a9;#*F2W<_fX8e>K%+xF##CA$qs~a
z1;)QTXh*p|lb1c4PDAlc!?g-Un3QXBURN+Y(zzE*<mhjCu6?=Kdz{QY!CtZE;U@dM
zVseuUa@HF^DV4VyUI$B7<-yX`IIQ5M7OwIz+uH)(?pYI2<P3U)<}j~g*U#R3WnWfx
zTxBPi86@E{LTKaRZxEEwEU!G{=UYe}1mEaS3S+E3a#(2}F1U6V3jQ8NT<f-;eaN3s
zaGJZ(oMVt4)$e1vOdbosZL%4(3_6x1`_OWoV!F9Dix<@5{FZ%WsSa-KnG4a*MDfLC
zmFoR4gapPU8T$>)L=P2xy*ITGy#}sy_P6D^xjqm_CWZ!?O^0)5AH@4uikHLre-8D(
zbw5uH1g4FV*8}q7vX3*!#LXtG(OFrZd|%3{)^4`LI#`kjjQnWGng<0M3<02cC~X3u
zBIK^Gugg20KTnICMcfF|_zk(Ri@2Q#b$yc)jHx}m7Cr0@e%ZCJxHU6G3z7A<A4+2W
z+mX1jVVv|Mq;B(CegBuy_3aHU7up9t%*I2>fU@R4b3nkuwr*tAAckhy*UK<`*!6N(
zSmI2}5qF|u^vW_(<x~NUSf6y<k0`zvR?>dHS(yJu0ptv7Z$3-U67aCWi-I+YZ<Qns
z-K0+&$xy95X~3g5;{8pf7tC>UVig4F37=+*o4!H~`A`HR;h>|wT^ERQ_z)7=^tW<1
z%pTFcRy-dSLgtW|tpz@p6<t<ccP&jFsitN<7h>qRmMWLxcoov!DYRIZm3<`JZMmT&
ze#KSsTDoa8U^Pp1o7qKu-EU^QD4koHlCp0V#`w~#NTl?5Bo#vwa~RI#_ROcU|KJ%u
zrqomM^-9{UNo00pPrlJkNd)Pw;9NDQ<NOBibtY7?RrRTSKG>=Nl5ZGPi~CYs@T~bN
zThA4?+CFx1Jms{AkF1K>eQ3c?nbck-T=Dp%!=|v0nuxN&8gSwO7za>!CH{L^p^n`u
z0HvAMd2L-R?9WZ??mi04y#QTI;7c<9YhjzvL6ldYR^~}MiY}P0K3zw&W@AqW=C0j;
zYj;9Cv_nd2r)!`s!_n_~_&(Fst`8wrJ42do^x%xjTm*Q8<lo?6^T0n5Wl|GL`xoR-
zbWXoL$RlZGV!C6d7!Q6tj2^_^|8?zcI|?rj2oh};zK(erIN#|gJ_k6GO7pZ#)5B>7
z6DpkXSC|1WC*}_R<e`W%^C()|A6*(+20gU)-dpa+DLj1I5f@b6IUav1Rb2DQt{5{t
zOQ!SuyR+EvFVJq<fEjSAQ|AC)RQ1w`xot+M9T-^XW8Fpw`Av4@x;Q!qccR9V=4->a
zsV{cu<U{3*&eeiSp8<VHZYJ!+I-_oqjLXV`V^infgNNJJ?h{bXuwW==$1v`}XxHDX
zQW7P0pVl~;T*|pz_UpCxSnIE)eZ)B%BA0OH9!_(}G1tdujcwy89B04Gq4ogN_7?}E
zedFKCg&YYt8p6P|k8<-)%XFEKq7UAmee5#V?FN-s)wN!nG6(X=tlU4k<tjTOa*-Xj
zDH)UykJWx(pCzyf0vgEU2CBBnC&676$5X(Dbz;L$=`B?0e83ql62liW!5Uym_qxOS
zwp?X7M!qaJ@LyLqG%)Px{_Mf(doe~ixI+yZ7u7u$TmuZ*D5X6I<|Xn3Xc2rr6ZQ4x
z6Scu`_--rCjG8TSsGHG@sNa8cuOGEcUfwx6H~plcd%U-ajUWr8lXvh4t2}Mu+=l<_
z(H2sjfCWbi-UAn-`BQf!-ej%oQ_q=tZ@CDN^Nr-PWEtX4(n7l<b^-%osIRu+pHjqS
zv?ci57QaZ-!LI7I?PEL@7^%4~*}vgLzi+;o)!P6@O%DcWt}|D5jw7Tts|){;2NwxY
zmGyDZ2}oY&;7ucnZpmBwwPq-x_Cc@uz4_dlv+s*mV#NA?pu6<Xr<Ss`{Zh;QcaGZz
zhFf~9{@4~zaQCj3Iq>!>utt0e?|thW%~;^?aMm8BDJ=~a0ek=40?n#N8f(e!RvUi{
zEo^*G&|yeV-!!z~*?Zy-H-WjBZ#jo#b4^4WNLe2~UubO0T4Q^bJaHIk(R}rvNIFo#
zeVN)(S<3a9R`k=aTFm<7q7?5|pf=_GCkrD4WHT2)G~q*qpp<c4Ys+0Fd`OpzK3zPf
z=+xT#68W-_H#jdL`Pp<qyFt2PAABWi4lL`SToR7R)i5U$eg1suD85h(_1oH728u)D
zMgCjQ+>aHj|61KLWWXu+q{Z~qncIk`q!vqR!id<<bZkKIPmZ_&sNjBrGn;|<tD{PB
zGp3Cp4?AZeKE7<Vt_lIZ%}0$#QELR4TWKGk4dAGd|4a6>2d;2^B_LE*krvac<B}is
zRq&Qqo0NU^R$?*2>_;A5d`t?-Dj<9?U|#S7!b%90=D)!y+|e`7B(zT8L;GGIY3IP1
z;idsrAyf<|b~wKa!iU>OwJ5iMExno}#Tf~d>x?(}5l)NI?#UE(9ry<K6W#o?%&ni2
zv_ICx3qi>GjT5oD#QYj?27_~}cy-lfq_x}0tchj!%$ltnNQUDzK6#0S^3>0t?Q`8f
zp9CqmZJ%hUFP6Ah_Ko@$|IUtBS=XPrHk$S|`?*i)!!s>Vt$G9!v2GkE?5miJFTC-z
zE8u?6L)ovieI{v8f%TPrv@87GEHy5eaTmE0)ZZ<kQ(+>VzZ3Ml2oUwSqd>;VqRY%F
zCqf{R9yIAn+hEkM|0{dZNuF&mqm279z`cY`Y<xXN#5e^uTt6*k)z~ghQr5a?%K;Pq
z(MJ#Sq2^90-_bPw>@nm6l#c38Gu`5CtTi+pd^#Wh-c+pNW2|oQ(o*HAF)-mpm`u47
z>jPovCK-%m%>w%v2*Hpub`TQD$I3VNdac6uSI?O(%F@<DYGv36{~uFl6;(&DZfo2%
zxVr^{yF0;yyF(xZ_l0YKV8KIzySux)yF0<%7Ji#^?>&3J@x&O=UDZ|pob#KM0m!tp
zKr;30<3V6vx}ZN7Pzxa`jfjeqNLx;%4dn@#J>2q$(%!3iEHWZxq=~>05Eys11iPNr
zSuMI_hK(mF&$0#zi%9Kc%sSQ7&%lXDS`nTd{9Yni)q7LfgBIZ`IioTM7w4S#6X(9m
z&XzI@*$B61K?Gf7+W}X-{}SQ#=>p7iavRp868CnpjCtbiJ%PFPoSyCxXYeglLaMG$
zZg@%)z5X{Xk7)%?4;-gniOY1rM`V3<H863qSR$OGeTYFkcdY3^%5Ch*i*cwIqgzI|
zi%wrnSw`j2MCM$+jc`+3UW{BGw7p_RvQo{mee+w)Ih#$vv<}P1AuiI<E-iHv4sf=0
z7fa=y%cb9`yHiwp4<_tHyuw6L<SX)PMMVQks>fvS>|XFUogV&YKrY(iTF~!l=Z?VR
z`RPaT7~Dym9=`bG<l)h{5S990&-P>G-TC*o79K(rv(9n4>uU8Se;nvVz?EIiQwiY2
z#r~DX%aHjbC?-W&1WlbcIq%cNcl^vt=y6iF@~4o8EcX=X_t`rT9ucx|I^P|N?*S6p
z<gOcx=6mE=2wjY?aKuj>x3`~6<4vGhh)C0{iVi&fEGRw}2ht8=brsB&Xt}rHz4yEg
zu#bq&jHYnt=mq|$9=0zh>f45R`mm#Y>J`Ei2;A^vw*2!VH`(s?OyftL?w=D{Da1;O
zi}9X$0)4gX-|<Z`vgBw+uidI7Ffdt909#4%q|D~v>%EH@n&%7qRBR(T0wSM*$5zNz
z&4lns68hHfqF-Jr=YZV;>Futeqw3D3L+q(Ef7z5P{?&afg8j6BxM8ZSJb~tXIH_49
zh&l0||Ai`>D({rjm;E7`Ydz77OqV&Pbwj;F<80IH)|tV#)mmU<en0uN^_)B?+AVJi
znoR8@PRdxi(=fv*dKw@EIP$>{IPbpYraDLao)Np9Rrm>I)CFuRyAdOx>cf{5k9D41
ztmd<P>5r|zS_hcEOuUJ(7jsMRBM8{4-xbPL1cED-W1a7WP6Ca;o6^evdoxAzRRR7o
zysso)CxMkf4O{89VwEA-*bRspZUH)CI_O(>zT)3*su;nzPet)W^)Y5$2sU4%AUzrK
zl)p1vZOEoozqGTLGoI$Za3j;s0|^84il#eVGZsvx1wio_zBBHo4w!M>?1f(9Q}E@T
zpnj|M9sc&B=fG&W71d_Qyf8tlxZ!(ktJQ^TqaDrtivnJUqNX^_E)(oa;SD^S0qVt`
zhe*ZESf3CG+>K5WA~dsX%jxt$Bh~3M20hoz?mK|VL<FU5CWg$u%!>;D{CaOP5lA{8
z6P59;I_kDi5K4#vnW*2;YC`bkrqJT%cEKpLAl>sLvenALf%Y)=zLO>4uxFaf<4E&b
zV$G5--QSOvoi+N*t`iZQK1|2^!?etK+`_DLZwY0d6UgbXMRzLmD-AblXVY4F7n!NG
zI-~)k!v-TOwOt_R{SaW{tEDBsXX{UMK$q$Ob!}jA={-0Y<g_H7%rv-oq&JI4>M|+0
za~$k(wk;(&ufXK}4QC`cmQB;{TEAR+;h*$GFc24A-;@6GUk`{atiKfCIjw_QDzOm)
zh+qU*L0whqkumfhR1uMw?J=rJn>b196rV#NV8&X-MPUepZ2T1-zsL`Dim}i*2^pSg
zu^&Zv$=^NJy9rHL>d*kdeucctVa5t<0xjM^VWyDYzgOG-;X%{M(egzJayd>y#XPLP
zx(nhS$>a?ydv}327p{@=37n`v^}h>RvKtE4P{ib}9t55PIBwbvpknv8h2iB1Bhv=7
z{lh=-0I@R)a#HTG<j|(2>_r81M!1bA*4-75Wyi^}tmQO;@&=H}to)0<-{6&uA*<tH
z3sl*l(}&w=k{<deP%k!SqvJO@g<Bl}a9;$=M>l!AJ=kgi;|=YzkouZ!1xFl@BpWx~
z;m>|<ULTjr-5>1_WQOGAi`0(-;n!{o9#LeSiTLG{+*BX8AWLew<#BzJ`N988ht`!D
z_Wq1Z1c>y3$R#>*qZ!a&9=^!+k+|+lHv7yd@>q-;Tf^V4I-{?c{alhQ!s?Lw*A#H~
zh`te-`~@q1A2YoMa9EKc8w0gs4DYSf|Mu?y{cE&3W+$`uA(GU%^;77}3n(d%Ur_Mb
zk|*xJZW0llfFk*7_A$v^D*g+MkTwI#;D$<<F=_k*04@5u{+noI5THc!nk|tdCDHfB
zM?iA37WiagC%(bnWhi4WHEsLn*-foWJ7!8eJ*OA?W_7aLVMI0o+nU-pFW`T)^eTmL
zcG0l5h#sc=d-U}u)Pku>Px7{95#utwDq)0Xvj>CZRZm>jgI_vXIzW}T`S!WtVvq_*
z(|oB!*EBN9$c(xo;WVqR0U8HJ?H_8ofl{)8z>MdSAZ^cu4D*D(*3W@l-vs5S!ngem
z&Z#SQEF>}?0FO6OeC8_9vDbe9A(RR0_4%^B^l^x;Y*<K2%@6s|GxJC?V90vDbZKiw
z_HOR8)wZiJaHqztlp-f2FaQVA)7DCnh$t!}#|r%g<CHaXP4@pdb&KsA2l?5aeIGE&
z=?KiSmolAb%`hce;r7->va3avXo!%S6H!gqeVTt!X+F(8DnxacQm!-m@ch}f<ae}k
zOFL>B1Fpb<3eoZh;j2v?VRANI(R${jH41s809ulQ?CrlFHtcpZRJ@e1$M#*6(F3)y
zr1Cj7u#klx0rbI8<TVg*>ra0e#Fd}XU>ZqfcSUOV1j8BzH%%q{{~1p}PzDZw1`r;q
zCnz(zSaM=@6aJHFvLsP1g6DfRRFFd30CYr}*#B8lE!r({Y$cC~P%cEyW@+cMd+ykb
zcgAKh<n<+XHzGy85f-tFXvnI^vTr<&5Z<Q2;`lmd{^aldROT~8GEU_TN91_jNgViL
zGj@}vfU2wJ3pp4YDekLNMfFxiJEDWwUPNZf%-*$^N18{^7A&&od;hbG(3W^VWMCqK
zK7}5d{e@4=AU$wsQXM?#%0C4Y?r1|n<^6(Qd$L}>`DQaM4I=kY0L$+&ffEj}<_Mmo
zM}=pUnJC^HT7H`w8GisW9CS5Ni4TCo|KF&^GnQNC*6x$4@^hf?7#=_7NOtD5=H`Cx
zneh-lZPgp-cCNpA(GC()#k~LWW$M?VBao1;$s}7j(cS8(Sc08%6mKy4VyjW3w^j}t
z(@3`I8n$uaqfstwTR_gUdw1K8G)<ewM9&OMkpZ<;!%UTD`%^1mQ2J8hNP1JwAS9!j
zq+_#$f2X8T-ka+!<w6EGN~YT{#TL8Jj!-cBbx{j!G-*)*?hf33L;i8%@&|#%Tef5T
z`;eN^3`H@rYW<`UxK_`u$wDDeOPk*V$g8lC{YWORjL(VYm&@vTw87w2dy@iZ2|;@h
zA+&!wI8;e*sZ<6#!Q_HJoGYbhcM^>RRRw>rRrR?D7xd8F2j+t;&Qu@&Gu#y+lH8fy
zcsH3(jHPl#pe|S0pc$21XNxgFah~|O^lsu1$i@iYS^c9yP-!tmM<Z<Qj;r;kJne%v
zVPSUkvyR0=jlpqTzqT+iO5br6+@R{%@k-=wYZP+JeUXA~G)Wn_o)F29TLBow6Hu6g
zaD>U;nCM+-LlQ={j8E5C?Zu5A>8;~O^x#J%bQpWEy?F9IR(qxFs3<Sci$M!-F6H|7
z+w~A#M&+ZoneiZ5JdN_jn&p!9;**t$kv$mbgNf4F{J8^UuI;N)XZg@JAF|t}Ot*I*
zich?=YT_!=ld}bWMpHjiwZgx#F70@=MdAMP2_dH|fF01ci%qDjIBF|6Zq4seSKfZg
zO+(Pz^u)w5$NZ#Q8}=!J_|(_XAD+znmxZf?=XMO+D2|c!wW`Z<{!Y3n8LlA$QQZUb
z2BpNDpTl2lK}t84vrE^F9fs<x+S+5S#ghH+S5&THr$kq~ZVKfL&+0dwYCf=eBQxGX
z`HTsE>Hqvf{C4kEg{`mHevWN?XuAnV{U|)Hb}P16IZ32(R_uKs^Z}lMW2B~!!y@=q
z``=tDpAE=kUSUVcAN}`*g61o6Dz^{6*Ze`dzR$mh`M30|=lEJR{;j{4TWIMdk%7h>
zuPlbGyw5<mhTX#0Zml^{Xk~LBIblM$u1LJGvLX4>?tH!NZChINzdqKu9spV{rcYRT
zkhoivGp38>X$-y_#7*BP=?l0TNZ?zZ`R|rH%?;2Ew@x|Q^>^uP_f@R?PTbY63|-dE
zz?-D5SFw09Zs<q5vI0YV%WlF==?lwWo}z=a-nhNoJeDky^XwKQMzK!Ff*Y1RdZG{^
z?|yG%g|`;mrreLVf6#s4(hWwrN|(d3*K47TNpNF1iK4~U&L6tJ7$)r8zBkF>Xg|jW
z)L&yLs>7ei?4IcWdEKEDQmg@>f~s$Ev<rTAtUL}$C~zu^@-4jj=}H>k0gOarfL$D5
zybmQ!Q*I7%40ZBw2jqFm?)^Dv$X-Dt0R=caWthmclH3a3aE=J`>Lf{sHDG*^{0e`-
zxBE+C_BCAa>c{$ip7#fVu*1*0(k`jPx{JtL@`kAs5x&>z>*)on1;_U5*X9&&06UlT
zy4@ueTVUe5Z-2Jgs{NF(x|ildas!x2Hu(mbf6WkS{Gqk4A&%RnE!$@=992c2W+@(X
zvwCo@R!lse5^or~NG6pu=0d$dv6k_<@KL`LQ-1s63Q8v#xN8z&iPXEF8{$HUS0=;9
z7nUKkse*f4W%gCl!Q4Yntr{{rfiF-G)jl_4LE~Ebj#6LAATk12PEA3S>`X#I4WuKZ
z;t*ayx1xJXY~p`D3T&ZP`pp|aql24CXY?jAT)t<QF}~Nz=Hr{srBr?=JbUu5CJFcx
z@6E^)g4%GQNSl|eO~nfET87%|U$D;6cUu>YY|q8};B%095J0gBgjHt+ktN$~M*GCE
z{<2?iYZu8-a<&#q#M7~YI7R3r_8Fbp0*u~l*|K;^pVK|I!%ZK^tt3U6lpi76fK?5M
zq-KPT*-Ki3^AeNrp21W-6d4z63nJ_U?(~@@1(w1in#%xx<oBdY4=N9<0i;ON_(i9q
z-KfJvT^=H20bt9tnuX+p!DVUOg!(#>N;(Kf^t|6@19q8zSuK2^IHlnUd==P<C4y80
z6I$tQB+uJ3BS$m5(kx_%4LE5Uft?q%XhD&g=lXUqR}(|cgT%c92ucE{>bNe1CFIXh
zJnMyvNYSI3S0HHjkRST+>lT-O4~+nrmwHcX8fYmyWmCh^dHw5HJv9Dt90}?QG0gkL
z_1?#2M!EW9p_zA7Nhxi4v^`c%P_#5~2o7WWS$Y|O4rLt%mjjo|B^^(~)p=0aet|<G
zi3q9S9r%6Ls=9fE*8RNVOvqJvu588U>G<`zL`n7VY~@}v%^B#f<lj%{4{1W4G6rg#
z#`9t>+4q6u62i|ul`gvYRMCM=7gOFn0QtziQeOEV?g$Dt04Kh0VNfeTvV>11_54=1
z+<gc|*9}DH*4eCs%6GuFl0%(`VnELUIJ%*x+nA>|(Yj^rr(BrCUnJb&?T!O?#%rBN
zVIJm3p-(++wgE(`TCC$W2fgB?pe#}Jw6IWbLl5XRJ35a$U0sv{H?3yvZ+XXJ!U+<V
zB!theqZ<*#v}TT^wg3<ppSM;B<)Okj7bBfj^Jku^!%5Y^aQq1z>f&P<0xSQPqlX7?
z!*j03vb9tQpOoSidHqoEvxL(vP;i7o?f3+o;%F%|ezm4$CyI`&{z{5wUuD0q$t=m+
z7EHF{oDJ~}>WZv(-XCu#i8x-U!1D<dN3)Iu@qXbS`r5IRm8fD_GWQLoE_?sqzi$nB
zS2ZKrHVivXc9fROKF(fwes-jwvur$7&N}|p4b_hODSPXVTGbm2)G};?!}h-`QT3WD
zV0}3>-H&Pc{2^!V#B8)|p{PgLa{%2!D$<L$%&L@}5{U&0#!pvhI4~Pa*I*A+PW<M)
zi=3RrTO{BR7+p|ywf4^~l{S)IUqrZ2>~IHPYj-%6-{Pao{ol{Z##%c6VPC*OZEas^
z0aw%~(kYEv)_&6jB+8$apFiQqcbmiyU<QVqb%!ALb^m5bGO3LjO(!9u{*;$ym-p%N
z8x8M|M!;8_aX7u}>S`@eN@kxFtKFbBP9?c(e2kYyDHF^2DatSZF;Q7(S?H1~o8j;J
zV4)RKC?YYP8C!25*$^oBHHf%V6!LsZ8kTNc<JtIlzHDc^wHud<R|&Jp|89$^RK0lG
z>Zr~9vb1bakl6WP0~j_GSng*azB}SfE+|Z6h@0_=!qi!3rcZQe`G=s9BAo}JmBvo+
zDt+E>>vEKjvRHKCgN<$iZyriGGc{vh-ItwLXVegnBfv}Q{ohwImElyDo1U82H0*0z
z4#bDd7~B;@&c{f>=}QelBcd%F<9vICBr}PF#x2LIqP3K9L(XfR*Uy{pWc%OONJASF
zg4YUJ5{DM>h6u*(gKOt&HwJo%S*4y?-#0UJ*dn0PU{*IPH-O4Q=0CsiP@Jh<<dRa!
zKN4atZmn)EC%*Uk{@?Wz63_{Rz9)KtK|~EECsEcEE@39CIMG%%c7}G?{4pwK9k4w`
z>qo2rUIztUw?U8;h-Wj5+ziV#;_krfxhN^09$Ycx099ViS-ZdMTF1G^;h3f?Fb39X
z&4UwRZrlXk3Z*sRBGZkZwR;*S2x*JBj@omNj|aPe(rhM}_@;Kx4U0ZAA@lMhtkSps
z7Er-I{RWWvto6N@$4_T;k<436R?@beqFtK9mw`ZV01-NZvhzoQqM0|XVUf4p(F@B%
z|5@w=&5Kxuif~2B_UxzK(jy*KL^}3vOa!Xfdh{&g6`HAO&OsYF-#@f`CO4lS|1vDe
zM5i8Rbv2m}eW-G+H0mMNqu5%cekd4}tFx!nR|Q|NWlmWTC&!5>?g$l4(C!!T<Nh5(
zYqet+=Kh=F0bJcssa_Nfl>RoOS?4~n=aDrxEFhw%RVdCU9b&N{W4Hd%ar(WvWK$?;
z!;Nyvjpeg4_zQaaNyUiU%zN5f)gy1@cb4BDHsuGu#s-|7V74Zcp8f#73W&+BNt3Wn
z!k_4TqA+UgcXd@G;Ih%7WslG1O(~;^v~Bb11E|ZeX-_BdlF|}9Vgu>!>!1`qvfHvf
zpkSoh0es0evClo4_dDqIB2@nEYtDb|kvFJe?Yb8%$gf1Q#jZVAbckI#Yz-t*wyU58
zgC^YDMZ--{x@lpKaRgMhqOoA+x^xa{om#;J*bB^nbb;W9MT+|1XW*?m<rncpbX$0E
zkF-2%nYd4+!c2)z=+JF372!=ACft=x){j8!`gvUb#=#qK2mferD-)|_6}<H%8otIn
z$KVSTlv(_+tPHgc+_#bFNcboz;Kv%@j8iu`yNT=@9m&yROM~|verEdcPWs{y>X+{z
z<R~6?{8mnV+jjq{g<2Ow*o-12jhE^Ku#j36JU3WYfdQL%z6U2IaZt5i$}`<gK)?7J
zy_!?%(UloK*#XC}eFG5VYCi<9mhLby4y@3&p@GhS%!53ZST}Qdv1^4f`NfC|dZDH0
zJ{wM+|CnZu^4k-MGP*I6^PAQ1>9LUCo-^J_9{JKUi8do6moel;Sac@~KacZLco^at
z7{Po$EOh%rY=Kqy*oElk%aO>b=g*iwcFNajKGu)CQ}>Ytt{USHt69?{j$_+;x((8?
zHJ`R>`vY)-Tnv2xI+>|(@3YLxkE%~iSy73cBuA-ptdUvGCQ6(`&JxEWPS%Pkf;5Tf
z$gw)_?L}wA$@uqS`Xi}-zt{b$s0jpo+Jg;@%>RES!y@~1VF5w@-`<<lRco1~`~6vc
zbnQIbJkt*2#>ndFWgqYiJ+ibBW;7A8nSRD%<K51EaTl^F_~EvFXFX*fn^BOyNnR1I
z8k3&b0mxxqy#?O&`N9Q4IZ2-S?vfQmghY$N^?;8)dZlX;O)3K+D0k}fk$K~S*&k|q
zf;6svXOMlQe3S^wc@fcp(m|MqF5b}H<qtm~HQ~b-^94`JC<}c{fiedHEfyGHvV$Kx
z+DRJ@7*jo9b+T8rfN`^N?~12^@BDG`=#}v2_V3jO6|w}o6P=(C+aTa~B)@D_PyltC
z_xVa&Fp6^y3N$Z<T90XufBL1T&k@t&(6W_tGTzXkaaVk}OE)HY6oJQ%LuXI9jif>&
z;mCf3G$pa4e4HUEeS10b6kt`7_sF~zs%x1R6Y8nUGplAhKUbfECU;cC$V=xbo5+=i
zZq0Q{F!#IS8|P(JdfeKdk2|XA$GQTp`5ld^e{XV5ko#NsXJlQ2yys9n7})cVj$vY&
zxs!h>{c{?B%1ob+k=w9#nOC@mUTBl`qp|%9)<^y~oBgTPq2KH*&>Q^-0;%<&@!y~C
zz4B;;jFUMIR*04#b}-N5ITh=$jlLH(#l}2&>Y^2rEfPn7p!8}&7jgX#yjpvQ;;GO%
zDV1{vcS4_afmf?Hb-9=OE~N{VXZ7Nbfuqj<;)w7$Hg^H%_3OSprcX%2a#-{<GHwp5
z_qCmb7kDeQPdx2Pd@37X36d#Y(Uv}MxI?SY(pBl1;4Qj*%4ZJkR->h%0LP}IGbt3<
zxfg!lhoSiG$^>x0D)BF)1@ausvDK!G!8;q=>UPs@%O?6xggZ%eZPfr8J==a86hPUR
z#^=D6g{LDyp{NZglTxEqMtjdiJ31RuP&^Y@rczjC1wm{ogsAjdQ1}h`!aWB;!s&<{
zm(~OVL5JFN+aOlMWELZ4N|wPXK5Y9stg8>xY#2H!{SwWcd_t~AVqL)Xdn0-0XL^X5
zBY?n^RoDNFo?Vs6c(pl`h-<c?*>Vrkm?2AH|3VU0eo#_TY~7;4{iA7I{;*eR!E^dk
zT7_225W!iQ#X+$yaIkLrquL-FI&b~3+n%)TSa<9kCK-5*v=Z{(gdLEc{<s~%0tYyS
z;tMXajZ65*81sD#t(}c4%-ZAA)gE-QVw(lYaQ|^`f`EDr_f>J_3!sSyu??j_e=Kum
z^2afM-~<ppPqEW7{LkU19|kD-x)K3+8XEX#VQ>KfgUGlUVU1mXw*^-wD>a~Giyt(@
zvpkM74c!+^I}6l`)EOyLJdQl`8r)2@JC}fl#$;Hp`&XlU6QEZm24MgV_sO9W>??&2
zud?N_m&L{Mf@8Akx=nBq8sPH!upiMXZw9-|!?%~91{3A*rBfDO#?t(PtG7OOC3#Jl
zIht|Xkv@acI=p_Z3jy0{DIhtVBlAO|T-|p+gaUmqXi`iq2yp50f`O^TW3*~_(lAi(
z%fY+p51pH1Nk0w?{}4EpPE&(<7OUW%yeH?Kp<~GEW;w>s$-AHW`e6!-MfmB2!{kKb
zi~&<fDeuJATkH4g#35^b-5aA$?e|+b-@RFi#KN0mMo*T+XMT!!GWCDEJD1un%A{@j
zLj`90D9tae)qNwWHoB~LBny~&YXGsYC%}#*m;=R`F-AQYEoij6O7qa)InV5E>`+XJ
zeK<AuJd<Oqk<7H<gJ}!LKU@BjEF$G!nZ6#&l^(KESDoKF?-Y33&H?)0!0GVF|H7rj
zC;Wqpll8raHjqLvtHMI729Sx_!&Vpl-VnP09@@-YV@Q|poQ4(yT`6jxy|WB*&U7ZW
zv{&9eWd=`TvG4ifa%VRY@&y5hB@9psR+Pyw@(Uero3a@0rfUc)r#td5!MQbAtABhY
zWz-p1w-4_JLiT_$XVfj&z4@(aKOM_{ujv|r4z+u-#|@LW;c=)e5gwfv^YEr8i}wxJ
zD$?o>mW)0SDw=Q*K?(i3Col|E?ke(lGbTL70c^rZZKVsmW|6%35tt)b^}w)18{Z!r
zB=&;>MJgbsVnjlNz-zl@Lq{`jXI_*jDoC97?q^@zp!`CNqtXNgq~K%FV{kp3{6hsT
zSe9?1Q-q6j(RG8<uo-7VdBI@Js^w3A7M{?Qiq>uR0w?i{;jJl|ZA@LEXMqfH$%6-P
z{q}xK%q7tyG>c<8Af*TJR~-C8m#mzgHyMq%`H&gUq><-seRXVkUH>QU+&UUWouZe8
zOjlVJJlXPl<$_F!=oAhpZ1H9FzNqv7Z9X0PcDfdvz;wKv+6Mtm9M(oHP&NMpj(T50
zlUOH<Rc8E@48P71k(IC~2Hcf-AuuQc`?!?|9swRl3t>G=>qTJLaDZAUiW@fm2`iJ}
z?D>P~-+&3>Ljj!Hir0T{GtTLyF(T(9{B5(YF$M+Pah`E*7;OFsDe}xs)ZmOaF8hqk
zR$3Qo{#3GV@{8%lpN}-C#70J0D%+>uIiDi6+J|L^Dk?iCyQU8IRAouugf;!mj^4GI
zaYlUhu>78)$laSRw<`B_Ujck&{~p*MG*T=93t@1P9(zL#k5nO;DMr>FU}Hy0+_+Y%
zj|dAFWP7J_9>kZJXv~u#f`%0+R*cjreE8oS^e=-?GfkFjO@<^GDlQjueCZy&S$tyf
zVpJxmEo}r<UK|u8xPdmWses8Jr`Zm}m->dyCr^L$8Fxk(`l-ph+6$uPb?}G;+Viot
z`F)H?^oHI(DqEF)+483GHW%^eJ(l$QJwQcNQ*GG2V98nO$a2e+lXBRGP2!aLRP?0y
zeCItbamz6kuiMfpOly|P9OH1I{<8b@t=+2~m^HNP@`}Vi6_Oh5gj;Tgvz%)Th&S8C
z+;b6;Ev~x*f+6}SNXpe_ty$xMMOZUmDJ3q_uPp{!zfJOMEr@TcZonmQUdB6}b1;cz
zFYS`87unOm?*RsW6&hXeSH#^r;kp#EQ>!~;1nK6}%{GuD0<{|i{O22YfT&rn58@Gj
ztpd9W@o+v1ZH;z|W5J2wX7SRTR&m9+8Z>UBp32gtQR8+9Cd1*Lm+wd`g*1je3VF-u
zIkwojL<yAZ-=X*^J(G#Vui`C8P0VmGw`9zX9BUn+BCi|v1h`H~;aU89>%`nyjFUoR
zvRMkk6m1Nfz>f(gonza_e7zwn;OT>oVm7pVCW_{<(em03r+eh?$8d!2fgS&u1@>^2
zTq5T`CF|iH%p{0Wg9qI}E$6}Xutqjs{uCBRtKNwgP)fakZ|1RmoOq8*<L<Heff%$~
zfanWQ7c)YSyoLc6<uH5eJWak2S-;YGi0lm-XXLH;At8~1BD=8ja!O-HNs4aB1Wlbh
z<>8n&>QP=W6fm;O(Cn_n>sw{94>+%I&=!0lm27t5pbgA-v+ZF}g%8n_w~mUP&hrO2
zw@yDgoqjY+xgOv+L~t`8Fys7ZaO-Q<mfDa`U{n_kqoon!5zd@fRTOEd+%<Q*n$RBc
zxM9{BwsNU2Wl7%%sFMc~!5JUy*I9s9<4`J2*)6K!*ok1Ty5Oc|<bdP0;_vEC^S89K
zA`hpwv^cB<HCGT4nbwhVb2J{OgA>&>w{m)c;U=I>BjGaZ)88PEh2ryA6qJrBTZ>?<
z*~y^^<z?vSDGTk?l#g?0CDJjsxRAL}{(Giy`$$p$i>eq8t;x>ct5Yr3v(s7aD(aC<
zEB&&<l6-2B<@Dp|f3|gI1iU|fp{Y1CmZKOE@{(ut5lfSk{n<E5OvCWALmqyBLK0E~
z3F7#ny?v(>I{FiLGn(-#^2>|0*OdFM-*a@t552FBg`|cRJ?YB60))cEcs3=!`ONYM
z4`UN0kkFWRe|K+_!XnzxphXkmWYgr!=wDYmXg!GYeqiA>QoRkmrzAu~oZq@R#1p*+
zOoPk^;x}_&h%KOVV3cwI;iK40a-AFkO(iw3FFrUX5?k^HidYg}L6Dpmfb<6eUlInb
z={>;N3NN3`j5FomXPRJx&$$MWC`k4MDz4vSFI@mfh4K+XiNyDj)+5YqC@kJ-zmOf{
zwy9^gQ`Y>?P>}3b;#0!<X$skAph6%JID9yf>%nW4YEw{cg#qqqwD6ly+KFh|22O6`
zvO&k8LvyovlZ9Y3w#aa+QNF5n2W$f~YnG6b_yaPFQub$Ji%}ZeFJ9#%Pn{}Hl3mFj
zeTNFiSqY>Ljc3z01jk;X$Cv}T_9SH)#8U1@3nW32&2Vd<Zqq4~5tTKBPVyhSOk4(E
zoj5MET=H^!`d#^&BQLl~vSctopi#B~n0I7AXWAvu#hLK?EmJ~j`_AZ<66j6!6kK5U
z6#%Hm2KiJUbR0B5v;D&7M10XMDUSNiWUPF>Zr0@;^zf9#J`Ta|+gPt1&oO@3EJUnE
zxsQVVu-AL#1}#6`XubmDng4rZqQDb;d%l)I4VA9bR!<tqPS^=NZ;U=j0t(~Xj<-qC
zV3<CGvaPWtp~FAfmY#{>3{3f6zmc5Qn91(IFIUxFg;7OgAePkN9s%RAJnhw>Gt<w0
zs>$&+r<||Rf$=}|etwntM=I`u`G~~V^608g&L>2<f3PbiiIy--vxNa^56FA$<)8`=
z7<?%<iny@I@rUbuc%Y;KTdCKODi`3;lh>nkeMTM--2jWDVeEyJu{j)cg8I-|AkYIi
z!1;GsW(h(A^a70&T*Hd8@vxva^$#ln?|_m3-ilwVgfHmuTzp(xr9on))8@bIWpeu1
zMmlC13>{3<6Pz|<NoCT`v~GUK8zt|~8MO(PY#+GHF%-GU@wvvvH`vmF#=~Mb;0#?K
zHVWU;^ueY~rtRJM4?xrmuDnGUD3QoQXVs)vb?mmMMX*#wa;HN-RhlsKZ?_zF3+3<1
zAlP~y*moM<d9Ss$Ji=<OKdkV>X*O}G#TfaO6UjA;PSOfAD0!XA{r4i(t~MVU(N5@Q
z@DCA0LLs_r)Ba%p6EmO=m<W|4-@iBG^3?BM;Qz!D*a689&RWF&m7P_F`}!<oE%0Dy
zde6|Y^JFg62iCQzlmW}!PS<^yN+`gNsFLVJM53bV9t!Z5)<M2qv1?JBj3k!N$>|IB
zo2`#chsmf8Z+GImZ5g#nzUh;uuQvy7oW0Ay?eTO4L4p&?Nh(WZNG0GgRvq7kS?|t%
zr`;7psd0p*Lw^th4F)6Dy9O;$>An83vEs363>~e~7gA<`N|_KvgO}~_;DMsa$L-D7
z{LW_UdD23ASYpXxjGRMXbGUg`?jgpvM>Mta4F=PZo4)56;2~qw#!9FVkCLa>?~PUw
z8Zh>=r$(Y0^m`E$IF%+pfEh|AzBgh=EMHr+wM$xJ(};`|UH*}!6H?1{TzcWF)!OB6
zNX=Ip;8NuAD=*zv)pRwd1B!~9>Eq{B3p|IV4Hlez_EdkQT6xC#B&FCT2!>ny5(&LT
zC}2k`!bdmw@u_7}r}mbB|7239#&kc6-}e?&k=muT^ZaGpm)0*MaqJ3b+(*!lYz)32
z%}uu)!SLW4abwo8@D1Y4%*93RCg4>YX#eMPV*OtaRi+bBG|V(0h(Q+vFQn!N5^mZI
zdOCCDwOx~Qr4S-tu<_#6VEm98?LfboI-L(o_y$d$&@Cyx+vAJWw_xe}yo^2$DPN&m
z?`i2GZMpV=ALik2WVkk2!9nNBevkJG@bdr+Hy9duN~{kY<r`k76X#M~n~d)><ab$v
zf|us5K48UWjjSZyde}c-C&pU=z>*By)111A4<uSRB+Ou%^82r6#R5qL+z=l9p;KvD
zb1Q8tg&Ifz*r5=(NsPzA{dAee0}UF-DP|Cc`6;aVH|MwPgBAAVPe*>V@cQL*!VA7c
z7P2fk?4B3BSjs5vfR8(1vJLRBZnaVerN&Lkx5`t`I5H$9IF?LLg)r;TbyQGW$%9o@
z`<wXFYq_bF2yBy39t(Sq7!u<)9QAG@*E6h*5;)fqcxM{h<6NEERODO&qOs;^GUjd#
zj@0JDX$;}t00HSH*+zyRdZsz~#!8aRowV5XkGarylml=witW)={EdbRk-JI&*0=3m
z*{-9xk^w2L%?lJ8#r)L(3CG-Qmt5RAHZ>+!{QJB(cI5<=D<k$n+kdNFMza{_a#ETV
zkHqyt&TT&~W1h8vu5LRm;Z>Iz#X!3)?EEUmr%Y_A&XBh@0FZ{$Lit~Za!kOr?LnL^
zjo}j#LY)XDjGVL0kGqMTH~p=p6R@UIqv(?Qgq$z7Qy(#5Yrnwm)u=J-Hg&N6sUe;5
zgH5zM73tUx6$C3f01xOZ^K?}iQva|o)*Y4$uJb1QGA!P;eOYfblFg-ly^YSsIOEX>
zfOkYJz)brS;wyE7ligZL@(#xmiRiHcQbOH`)b+V&FXFuBzAwi>Ywa_cAL;!;g;F#l
z?*uN3AyXu)WM~(t&$-XvXp`hBxNGo)_OB{4Qclx3*N`|TE>gG75165`uQliNT<-%3
zYTlE|o?H%07jYhJnWxSr-X9T7{Z9G9^w?L|dcsD(9x0~PV2hx=PN8Rqp4dv1k@?d@
z#P8WEgl5w2VZ|f@){KaQR&i)zkk$?lmhJmyuS1yhfASrSIJRZJgjyLNQ~{$;6&n%K
zT2e7XQAzsC1C4`91w)+CYwfHGHjRU(j0fVPK?iL-5iv|ov2#GoFFd|G1t7@7c;@*{
zn9jo@CoL>WeyuCzga47lT!H~|^A2pQqEv1oE46mlUoA-^6J*hb-TAPKPM<}}u9)?H
zJzW!UrDup3j-L#>U7LZ5bn`Q=h2)cvbva|sfd@cwZ#UaQr6c<g@&=IIq#ymjTkv8c
z#M(77o&z*m1R9P(*XHvSp$K%{K!4Mdut9VruMJ7?4z!BpDj15)p%`1~;fW7IQ0mHU
z5Nj8ypZo(9i*_YBN7kzc6gVQjPE;hjvy<oo!Q=7(X7gtl^eTXJQYYXVJUIY#$Gj>{
z?3Krh^;;yZuS*i=YhL%H<9vb}9B{XkfrOG$A7~7>1+%QS=kTIDahfLBy89qa)u{=o
z99ykL`v?Z`Q=334moeF0kl2{&=~KOjS{<*N_r>K$<!5V8slo#yb#cRIYZ7zCz(-}_
z(NjYsu>9UVkLsim7fI^AYJhYE^`M9H9wL{I68%&hB27!v9!a@bc)j9qpe@0ZYJop@
zomvm0qk^Xh_0d%j{^9oSBX<_hx$xTGZc9JQm4rR-uU?DEef`7D^JG^Wf5+VNR-6?<
zFQ6g*6A1`+#&nVtA+P$U9dr>i#7Q6EeOF2NpxhSZBZ?hwiq1Y;##18r^u#gO#&Td*
z^ted0fOugLKi|ELt^twHUq%9#@_bvdKiL931DA8#;{|(OIRg|MXw?v90pJT10(SGk
zUs;k@a1nl~Y-aprkm5o56FO7_WAe5v6xHw$*!iDbf3}MU<HDW%7GIz$^9iBH7}rwT
zEtHz@3R-eI(SO#V$q*j%@%gj=`25`Dd&2bnJR)i4ERW<5d4%F$ZW^>%djKj4#j&YS
zyZ79>j~S9*0WAP-zHU?f8+;{hh<~%<7L}U)-nqjAe*#40-S#Ikly4z0X0W_%L!-%|
zkXz6IGk!x46uyZ8gJhD)Fd=wx#@U}1^rk}=8c~V7O=RCHHU)>Gy_M{aa~zwGOj#V{
z(q6%$VK4D=isf0PY@4<36aF|uG=n;bDiDH-+qk_Ca1Cvp`aws=%9U);#Ckf)@PDs{
zWmXDSbe5@DNLL=)SJ6(s3w$~k9zwfyt+y>IVrfJ3ksv>ZT)Ai;bv-(+Zg1-nuyuMf
zueO*eP<H3BUl*jlgTjn~sD!+^f`^b~$y*L~>!pRUO(>7?S#oJ$+0)m3^>JLGlrhQj
ztpov)uw!0f0OU`ygeIwXxE=!5{?WGzh}5Pju_^!iP$)iupuumFFtDgfdbak)OHO*H
zZmgX)ElNF(bc!Dv0X0`SYFpHN_;P?u8Cut0v%4#eRSd;DmS?yVPfr+aB4<_e!YDac
zu+`{oJ;^D0yaDV9?wE^vlfQ@eCTD4;+mzYL!TA@2z{PvPs9E~iMZf*w9}yHf?HONe
zDh9K}MY47W*tJ}~1t%8SUn&L<0$YZZPw#{&8Q$cPLiA6%@ey4R2iOTM6UtbJ6gk~8
z4>%}AfsH479gog_PvwN#j1jIuU1=G(CJH$JQ;37SA=<=YF<hsT(idB(;>HicJI%c_
zYqL3aF<gMxz1-216v^|#NYr9VT7AcV<g@K@kyrzn0&JSD7ouv2FUh$JpSsK@7m8Tw
z6WUYq->gZN+#Gz%eha>^Qxi>E=iPIKC)anE__gC)Fpjk6m3*%yZi*IL=U@4^l9r_F
zmb(^$g0;J%dQ#|89;Ec`R6(*qm*3araS7?vnNb!#+mo>kT|5QWDWcYh@ygDsF4x=B
z!cdRR2Vn!=m$Y)oW5dMkr=UA=<nrWu&4E8@wEC)TgGe)K0maZ~&zQsI(!6iUl0M%<
zeI#N*0+TydPj#HlAKT*fJlh~eD!>1xotVl8?+va3dvJa<X8Zap*J-u3yERO$)UiJa
zqKVObxq(+4LCXIu#{YQ%rl)~L+J+&DAn@J9dK%BfCPN4?3q&J}+AmdyxDmwRmAv$H
zyahnS)bFCGTGw;#Jy>ujzS*Ap#g7l9<8*A*<$D{6TXS>W_l_T4caamh_9lBN*vdan
zzZY-D5wjL5@6qh=DWSk*qx~ND80Xt>1Yp|$3bYW|;4se}+VNYVjDxBnH_6$*H_oR*
zdAQ7~$ULZ^q~`=1@d`uKRL<-<lzD{=1^`^8IAU^WkS9|%W4|)Kvf6j?P?d_6$t5?1
z{XdAF%W?}dU*$_`!UhWkTy=v%GogRs%7~ts{3T}-3nU(p8?=IjRX1$8dtT>Ijx+B@
z^1)=U(odq|88K^ALsHeqCQW70ccPzqCJIta<^ROlPOn6BJ|)>1{R#K(o8aP_klb5V
zq)dq=meAqmn4{4dANzWDwNi9Cr@+MV-QdAj(vafMb&6#MN%igZMHT#=+WIa;Y|D{X
zWlH9K8S`yX5HlCna?X;^--nl#Hxe$Vgvx+lbi(Ypr`uu9;KADl`PY9*a(%`=!gXk2
z5Hg0yc+C2i(qI4IrU^W!T9?~7Ek8ELZb>NmMMzti4t$3mlMDfOyMeky2yb$BiRkuj
zY{t@w-iLnG%~5XXfubdA+Ks<)x?@Q$OnW3v6;s68uTJe@zEGR@qZ|{t{Gvb=wNK@p
zR)-PyP}ZDO3aTeu_yQTEF+_pYZ~_BNoU1NxgP!MZtc=x9@?ql(BxBU}#(U3Z|HIs#
zrsEBOZi4`0F7qqDMDdI+t+!kg#MGOfh@s=&hokkS7t){efLl}&LMzL8VKg^X_H>On
z*!PkDpR!(WbjD;%E3u10%`(98DjFvS1vH0xuGt#2d@c(Z&W;sfiG$v#v;D>y8kVtJ
zop>!y`bk41N3j0Jb9FE$iV!;f)ZcvZ%M<JkB=?Q7*YnWJ)5e?SpbhQ`jGLv#0vfRp
zd7Cw7^@!l?{qs$Gq66s;R3rhIB;Y`;^<Ei}7<wI{R<Z!0PD>$gc1g~goFC8$^lQ-G
zxlI4>^Mnry>RrQQ(iRnscylH650@}1Vspiqq6SlX%7j|sNm8W&6l2aZIm1E12wN<K
zAa90=%|=XFF_6pJQ{u$+%Mq8%h3o`e$Cgj5<%4jMx6H>4$6ZU}aHDZ5CiI|t)uI!?
z*e`Yl{PWZ3<Bj}Y=Gp*W7vf2FQSiERSY(zbzp!$2cMa80F$FQRf}Z3P`4uem6Ci2C
zr{=ciL;_qJQfn4Tqwqrts@JIDe+G8|2dCX+=~j6i7Srf1wi62sJ*i8NyV`>$pkVWH
zGCZT!Ri`=c-B^j+5UOAKHDXdmW|~H3{*w%!8)0;|`*w4#d+ErS^deb~C)p|bE1{cD
z?JF^^uFT7o72N?__8Ga~x(Q}8#3u7{42c}OA8OHCAv<O>i#g>z&$#?Biz!ccJJvFz
zPSRG>kAzvLkX0P7&Fk@dets{Sp;gE3D|J3jb-vF&0;Ta-HBuDzTSBQuJ>Tdjf(48D
zvsS4tM+Ac(LaLLGah8SYc9*7xK917O`p9gHn3kAv8yVR*iEt4rwF-_s<xq6!Y4^uP
zR&Me=_5*pEKLQslGt+tUeK*VL<l;5DMIZ2S5(BI_F44Zzca$1c3v-%QpFfYgq<VBj
zESFsn6!{?-L@ih3>y<6bQGbN6jidl7xc*oNRYAgm#m%`zrw%+I$a0Le+)ox&IH@@Q
z|Jy(zfpogsRD((mL5|$+KRo`W%`hi`8ZM8_7i@Br`2x7xsX}q1%LGqLHA_N4^T)#e
zSdPs{H$)=mR^tnG6Hc#6;-pG)O;b)sVrw~|g~Jinw*hh@(Fu_xCRtdCO5EY$L`K<m
z?MXaxTw?#PHjiO%uz!f7jpaUMr}sw_V3j(%QlDDU2*86rjiUOShHIfqa#2i&=fM4X
zFEnUPkbm`*YyK85foKYxyFZ^;$!3NZ#8dml&_R^ESDu#&e{<^UzJ8xoX+M3<WPb*j
zWvgn+LW!bMZmrrPnF2}%6*1LlvE_3?3E4fjzwPGD_#>SsKS2y$zp_{CxNO+HmqnBB
zV<Y+yA&NrG@onmqY3Zirz1@2F&99NwVZPorvslU`l8LN1#MuTsDp1`D*D<A)6@}WW
zCm&B{J*(^O!gyjnRE(6IK_gX12Vcq0<2f?fILW<EI|>aYeYBXBa!PgitFP5rPVF@Y
z;=*3v^XhIrVtaK&^?{DfD**Yp(YrIRH9AtY!B2^RsUWhWyf5fv?OtV~zE~1wx6M2z
z&WN?kHskwLd~>ZbJpWDSUohnriF=OJdL9cP9@iX$eo0u4-#{|K^-&5Yl~q5DKb;fX
zNL&49Tg6_k-13X*BVQ`llnAADD87v70s|N2<Fn;kzanykd8(hxHmDat*M;y8uF0vJ
z?wJ$rvC|$dH~S3B7Srixz~ymvstVHB2{4Oek|Tt|A<k?;D0MAC@<On}7@cBT1Q(VZ
za^$xx82F_<0i|wxM=nE|sFY3P{KrgCVY_uBzW}=T=}@1$d8b)Aa-U@ufUs`@=(dfE
zeaOvyN+bdm4s!3>(>>s+m5n5Q$M>%SKQ6Ta>ijCuoIE+34z$LH7yW{Ut(v3-J{q~)
z!Ko0%vE>4Yk2}CVV`<!s{3WJ~T5{M2h=4Rn4N-KXs`2in%{oNBQZ7^O!%Pa4=vz0f
z1nged>HerML9I$Nbtp_Su(u{L*O0HOa9lAU3cN$Rc5$-NgVUVi!T1zjI0SG@Ob01H
zUsi25?nF~%l3?ZtiRDuI|MAo{BCt-wBrkp52p=qdY7Y=3*8&yut(ySW4wHdBxC`c9
z_^{uo6b25fRXhF7Z_oQa$YTg&zy5dg6-O7m=(NSRG1Ju?BeGhs=0<G<d1Aoj0;Ozj
z10nU8QQa!+LS5N)VZ4FP!L2qcZ+Xw(y@_dWQ%OiyMq`p~RtF|lw)y_XK(`l>)+aQO
z2%0VQg7_^<_LkkW-DB~{R=D;E$+X&xBtNy?Ov|VEQ}F_g4&|;DEob~tBI6=&-piNg
z0H@9!koT3;Zq|VYU?_v^8T~7V=3T*b?<-l|NK#w4FM&DVCw+JNqiOgkRZ&_POiv58
zbQ{w~K&N#J2nWy(eJUalnA&%@nV%rYArIbL%@9VfT>iMB_D25(^5kv+62RUm>5I$(
z{}qh3`(^;V>h7lTA<!?JTa;G&*||i@*g^3?FVnK#@I0}d;<$<A$Ut$1$3~~4&DmGo
zcxDYC{n<4`(cSbD*;BtH6-YoDm&rVeeVT{o^5L7VFn^UI+j%Wr#q;~IC)Y83J@sr(
zu)-x<?$kc*TvupY^_@-6e8pOreWISEipEWnRvgc!4_E58E9uB&VVk=ax61P4+tGDh
z;n|YoD~$3t+pqH8Va=bt5kQ~0|6bR8FE*sNH7;qD-&+#TcME(Co>>0b4xWI-E?V}L
zobBL#{{HzCHy<~r;(``lNQlbYp~W!y5$T$!%w7Mk)Kd4QV(7fPu<X}vtg(nS;`!K@
z{aN9ZTx9L|*aFNeY%_1_#daUB;?mbDm!kXiB_W6(5^ZAb`0krK;}*#VcliWa|2ed(
zS^;$?MkbwOYV#hMQ32nK>{<ApWHF^rsLgbVIzR6AKp=?5%GHU3Aa|=u+z#kv_aw0{
zzr?>@U)Ot%*XKR8S{A!Gr8nXoyV47O(Yb6jd!`3kvHYC_i`>CJ+>3L?M450#rvg4@
z<9{KdAz6ds{kh}u)?}Wd$aoBSKPs_m1XJPthzA-Z;r<8@9vACqN==~>KdC@Q3k*49
zd(m6lpwOhZ2U!yMiwW`lM0nU1%tj`-AwU7NP?@t?k++nq5NO&PxhXHiQ9^~{5FZ3!
z=#-VQ?lkhL2`UT_m5YCo+<!N$HQWk)a(0DqE$V;5IZ}^W4ztef(44u>^(wja?sJ|K
zs~4*airT)b+PMu|>d5uN@xq(XOZarDI@0T<p%=q?&iRyTOvN!&^T+N9Yq&%@qvY#8
z>P)rCKB+Hwi^8A<og1eU^$}@>lxdapn9*&&{lko2YX@hu<`}t%&R4D?Z;^@OyN6<P
zJ^sCj$4fXOAu$))6Psnb;7p!%@0kt!ULv#L+uMy9k7Qh=_=B9^GE}4V|5?r$m~IbZ
zFc_)cPR-B*m_eWYVYNkxV?R!aytTTq4!;?J_HdffMbXgBAtMLJtrmvH-7-FrXhE$n
zfk^bL^Sl|u1-A+FjXGt!MM>2dAm#Q5xDsV*ag^~|0q4s%Ix$|tsoQb~fXys9WyhIl
zcB1{$n$YfDVqXI;3e$K#-di%e>ec1oOr@+Zxr1y9n369Lv_nKlH!vztyfMcR29UGe
z;oAt!UA1_ri+s-i8e2eU#FW_|A?*Vv<nq3gD9j2S<Rz2YTAt7CMRJTQq)PK)bn|n)
zQ?(pE!_u!+p@DANtUAi6SFspMRLAm8dYc#1P7>3;Kh%!~rD?6>Bw7kEpPMKqLe@*w
zGXH50aLv0=YQCMvk+3$qgxt=KVE$k%u%tRMZtUqiEijp6lMJEfSHX?1a0MP{i8*CF
zLjUVCK;oXetfsKh-)#Q-2iY>V5nAgH{A^2L2+-O>Q1qYGU<&aay;LedjIQ0&)EWaW
zUNDm>`4geSd&Ou9rG>{4Og0y*1u{rGk#$15`s2_-t2s?-{DVR>3!9&OGTqhnb#3Wj
zo1xAWzxFmk`$YCPT;eF#X<51{&d%0?H&mF~?E`WJ*p>GKdlUrRWdf@lmFH?~j`Z}n
z@9s0`wo4t2mllX4WIq8HNmK!USW(0&;mMqI@++Bz=u+fW(qAG+pOKNwJ`tYdxxyBP
z2s*T#2=yp2D?;B!S8)@#4G=P!#Dam;_lFJQp~9nhrGZaI=b7K-ejel$R?v71m=3&0
zMIn7b(}2OaxHJN86a7&%Q#Uvx_jSPaiv{^Thy0CYInazduW@EST!r(GfKei@gz~$I
z%<Ns|Zgua2^(yn=t>)GIVZr$P;C?BJo5H7(4^;tMRqdZX$9&WzN0+yME3Nci6LRv>
z&L);m%t$n)QakaYzyCQbQ#;=L%%t&SHMElc8H~8I26&Br3)7?Iy%==(3M~=&zX+ld
z4cM4%pQlkbQ4gi<VNff2AsZ|lw9yM(+0|q(FgkS%ksp(9NkI4^Kn|j|I0B*8++pJL
z1mNh9;Q#S04eJW>3(7uQpBIoii68y^U+ZTI_|oh2nQr0xYtqO}BN0Cf(VfW}eSYV$
zsCUAs=o8b-U`bwKBZnCO(#HjDN7Ooexzvm1Kk4#GdTo8S(HYj_ecCI$j$t1jeyC0m
zf#AQuo?uK%1~*mXUr-SuJ3)8^NcCLif#?emX!#Js>OBEjzsME?6(${G+d)z-20NCs
z-?@Gm@@-Yx7dxE>*N*J$GdqOkB-I6KD8~08ZPgYUAa|#((vmdn`*aN&%G!OBUw18?
zfphqmpr%ZsF7%)S@gvNT8X_6Q80txRAH?K3O*2k3<pN?}MteM|nF#aa-P&>~6vA%O
z(L@L{Kdi|j9v*gH%X6xCW-{usZ;~J-dGt+rOAgwXXp6HA9gjX(*0r1{#rFE`;wM#a
z!T+kWU(3$&w7_UkZxnYjvR9t2IDP+<DTew*_M7}55%L&xZU1=LxASsA1R_3&Fv!Uf
zHym=MCV7xH8_Abr9nAe<gWXugf?<Ax6ZWmP?sMNk6X5E5gC>___UaUAxgitot~eWQ
zrq~6PPP~Qw_kyEb2Bd1gEqS_pir5|&8gEz<9^Y24#nPTt;A%kO3ef?K{ig6{NUPHB
z$Plrwud7W#GVwIgWrHBbt#)r!K@qo;;qcah^r~F1R!jLjc1Rir6v%eqn}rR5YqtTI
z+J6P;0C1_CCjccfgZuAY#1#NCdQc=71n`@3h8d9ojJ%+*&(*v9Fv#c7lkc{ZbM{+I
z6$OAH6QivM>jZ<JH{3Sk$5=I16h(EvL)^IvD3yDvp+J<Qk;<Lykoym6gF4eUkixtr
zqYk{h1=}rVY&_uEwJP7l$=0aE7gnyr_OI1~muFOC%wzuMBQo6pT=VA3)2?b}xfN^Z
z3}{OJKE)rI(ku!xKHKLlrb1AU=;Nie>l}Jp#D~naos{w#g+IGw@l@R>S$a*0uzvCY
zT#6EC?Pi`_j}*!zyJNJw=+sGxduv#VdC~X1>lz=ziW_{ADk(^wa(>9jPcIzQI7zac
zmjW;QdH(R*s`Er1y^i;Zn2&|<#T0DjBA~6Iu~TvV=cXpP4&g@&fx^2aWj`4c;8&!5
z<BndsbQT<r_3c-<0bINlFbdseGWNtpH@?)U>wN$f(UZ8#Re3@CvajiV{K^cUDb8)!
zJgDY7ze7Y0jVn2@NgCwnohbZxkh2CD!kgc1TTj5}MJ*TtLcEkO0ekKm5aXv3kp0zL
z+)lF#nNKExSolN}P_pT`KlXQ@)cd0A41iVii8n*|cr+U;o1@bIAF9qWEUT#9)-T=N
zjf8ZEfOL0vcZYOHqkwdWbcyr}(%s$CE#2LD7JHv_zP*3=&r7^mYp(gk828}O!xDgl
ziV0?H$xr=)IxZDp^af^G8IM5~=Bb48BK_>BKWN7`^CRDys3dxrFl%UX?#m-N-tlM}
zT%G|M?>72+x&&vCVr&G7+enKcWB*M={<CCsp-rCmnc|Pf9tfCyI*-Dn9VLFMixmr_
zyhl8aTL-_-HTr(p%}$<v{w{($_(s-H0xZt{?ltrtU0S?<h-bM69bF?aypw15MoLfn
z4)F%d7b>EGf7*y4)l_BO6BE;(c}{baZbb~iu*)CHI{pa}*O5ia4VInBa`pnEjl<o+
zP<@Gci40pH_Q0mP%#+q0N{}0jjNiEgnBNbV(v`gGVYgs?g~fX7Gd%^u%?<xpj`4G-
zasaD<|E~MRuK}huu@XqLKx7=@v!yn22A*o4qq_~&nR-7t!Y|UPT!BFjJ5!pHBXwCG
zMY-?bc0@E)dR(|cr9#CxN^>fue<3R$%*3rfKrA!^RXsx7yV9`5_rV3S`5nIE`TG2D
z3W$EKvp%jw-Uj~-<d4I{?4(Z$diEwsAhod)5uZB#myEVCyjNB}vna%jt~6)|Z0S1W
zu5mh5#X-&_phgk@bT_fTw?(zwNtfa?#BT3W({U8!cTmC34|pgZ_k-tD_L(uG0_2mJ
z-|emW4{7Vb@U{8tNgdu$RzcMyDm8>^ueWSMRpna}=ArJSpk7jEiPtNPi&rGJhNzlk
z$br(a@|D{_O`0g7Ji*Pip<|@#fFNV4(PTZqD<H1Tf*(Nyg$5fcB|2EpB{HFOQI5GQ
zF@Gl?dXa(sY5stRSc)u{Wv)Bym^!OI=r)cz_vb5M><T4r6<r4gM_0X^R@XQ+M^r7U
z^^eIjS1>ZKE3l9}QSAk?MbMwMWb0gOm}CONN_Q}SCmSnuAyIgElQ5pgyvdMLyahO}
z@<ABmP`H?Z-ifMj4wAP2X`RCX%xG;O1S6aEE$lS@H>kl*E)c!VI0(cD(nL0n#{b9C
zIEIRWmQ)bp>fvv?N4fXSj2flUxqL-xAc&Hf2U3Mb&I3KXSTru_GJ>KbKgo07{K=QL
z)#gYUJw`U@Zz1Fm0tgF4F$f>e1j@qy4WS))gx}~285ej2$~%wbKPS$X5}iROhV%9@
zRzkP={xrqB6+%J*BP6og)b1NaN1^Te45(nfbS&Sjo<SO$yil)EW4H&)WBbKjbIzdE
zk?j9G&c&f>L%%CM30<93z60z#JFv(A(=Zu#+zP}zgCc_#De@Wn=0$WrZ{8ndvVouP
zhyEkAA+g=-!W80L4XVh;{0WIi4Uy{;({iV>4t=FnXEu*f7mP~;b6Ap4hs~_vjdRg@
z9<*$oy(uB>wSAU-G9dMpYVn^xC_)|g?uV!~+CohDt@Pp6PtKB_8?by<MdGzu4P~A_
z1-E<?4Re6e#H_FRa=*6%{XKh;JG#x@RC7l)gvUT4uEblwZ6&{EME<f-qt{v1!9mks
z0oST_--sN&&Gzjfnhh*Z2^fXW+(s5@WP1K9WoNjXJeB9?EfeuA$zB*iO8UdS_DE}W
zQ*?|je9HYhPK-^`M5~V1tV%TljkeLzHjZ<ptU`8yHg&BmzPe1K9M^~n?D)<O5)XXR
z*H`M{f?o{|{FXG{^G<UuM)BUHsTNt{ZBH7D`&#C-m6XG%kpOA{*FHYYPl^8m+AmJo
zb0Y*9lJW59({{TNNmY_ZpFWZ|d=7+C`knL!(_zHXVWY*RXpFn$dcv8;a;_2C)t0}*
zZCBFQ$EPU&>Ecx=L1Y{d?r@az7Ek~V!+^8BcL^YjU${z(*;zv1x*?C~TU7s;4*|Z~
z6h@tzUeFx1HqWKUR%WS5H|`BjJ0J(hfCTe>E?6C&d7f4?g1VcL@go?38Y*7eZ}Wqq
z|C*zIX^ZJ)YR5>s04nVi%Y+N>{IQDWoCRf@@dL*bc3?P<0tN<hxLLiDh?a8GLqz3e
z@9J%ZK4@8F!JowaUmAO*Uc|`yClJBmNV690+NKbr2iT@d0?$C+Iak+Y_8T-(e`V$A
zplM}kO36fA>@i=i5PKt!&$Ttda&huE<Cnplt};}NMgaql$HPIN3W*8vy|Oxby6qm%
zmH0p$tzNeygs1*Au>oknCq&xk*E9YjubZg#yc?-20*4{EVckDN-yJZYtQnuKG<7A>
zsRaWaQmi@B3B)AGd*m*%`B(CHMqkk3H=C!ZBu^9sW&`BLp+}qN6OQp4n=Pp|o_Q@N
zU(PeMsvx*~FNh6j2P0bS0xxe<`|h;Abe&hgXId7Wq<Xb8;2a|mH`~cA%7&kdg2j(L
zlx)}?7<#}0_;0D@0j5Sc%2P_OK251r6S7ase{_pu@a+~K30eU^dp@PN+-Y~-s9o!c
znt9&br$%ol@+*7U&$+&FWZ5~aZ)OT0ygU9#C0MYsl<QdFD+Q>W=tOqx|2|N_2R8+5
z!(Strz|YFwVJ>|?43dAsf%y*Pc$hYLh4^ByRa7^6z1xd_wWcQdp707*5)NSOC;1!D
zqWiXe949!7NYZLsy99vnN!7UXVig(ul^V&9vk4D$cQza1gACeHfnmzV_~76j3~Xsd
zgH`bOVct=UvIp=&#CnbIn3TcSMRC<3&o=sxqS2};i^c#o!AhFdNg)tDCWlu)Nbev`
z3nXei%--&Dmm`41hLgP%os8;G%m{)oqt=0Lv>v+CRJYxiw+?OqS1z?dSJm+w<gu3D
zK`7z~XYZ;FSK~d<IKfzDI>XY99s3}rL*;65JmpQ(n8FCqJ+0u{8eqQkZG<fKD_bv8
zn16;?Yuf(V>hR@#<T&}Gde7+XscHkrqjvh89Zn60B&2;nPHLdFFacVc^Rj0Z7So8C
zoVS(C%(ldY!(UgdE#jS1FDfVWO?*+0cd$VIvHU9qAMfT!!zQ{1R|8bOpo{B_3<2Hk
z;0;`ywFkX`+h3etvQ<F)@5UXF{DSm)aW7<@2-zzI?FF-z+qN;D&dvStv66f3&uA|h
z#&o~@P;qHC9%C=7W(>(^ZjKn^vIF3{Ou?-o>6Rd>M%}vXcTnZnrGpjgVmL=eXw6|W
zgKdfqsrq7;E$GJ=#M9R8lQIz4>sxRsaiDeKi!+hB`>b2`Ys`kLBA_g=Z0M=<ath9+
z7la$bCREK}#R0<IIg-*$NIQBTX>=?n|NQT7!28D_9|-q(rO`8v|B4c%J(W*5jEnml
z3Ie>KLG$^cFzu?^o9TuC##rr2>1%4vh2eVa)qKtfZ6x9$M!=@k*4|A`uWz}mGV24g
z(TbkNJvp|3=Ev#47+VE3;>(AOu>h=caUGstxQtr$xJ(AkNsNJBVjz(BtSyrUuJ7WU
zzhui^ZAlKaGJa<UzqiZz@>xe+xgz{zED28HCE?wto7VDJvaFCAB>!A{P>(Kxp|c<`
zv2Q?roj~MW5;;?&bIG3FOLC_A<DXtbU_cYuc#aprDva412yA<vf&qCE7c^@Pj6SYO
zNH8$}?K}NO;i!bEUWO6Q3J@hX3StHGvjjWtHzR*dKi(YK{6V5UKE_Sy({uE6U%7A{
zP)&Y&Y#R(S5GKfl5pq85ghE4B6u6l&27YN>fI32+xdd!z%Wb&YA59b@0g(HMfl`)A
zh`3WP#;G)__*&_Y(2Q4kg_hCOr!T$>CSfYP_0U0DEhqIvIx=j=P~@y^M(Qu>-rYPQ
zugHP`2kA#S48~XHu`$$^xqLs#7-E?T<0!@5^tCG0r{7hB8EIeLbpAf&X41GU_26B_
zBO2#*1PZ;kB4Qw1Jy5CdQ)IYI<ClNkZ`BN3|Mh|YuP?ng;KBchC(1~!v-m?*f}Vd2
zQd=y{12*~mfmX<fx$uS6NbuHor_~!}!fT3UxO?ED?SkV%Ab%zE(_S(EfP3UP-NfTX
zz~fCi+|=9e)=eFwv5=Ad0q?;l-*mVRsfs_XQUWRNT$lfvAAQ;nIodTnj8=|@F3WDt
zsmV5<C+9$smgAX=HTOzmnB`{uv1Cdvy^g$&i?iM~wPD4zUwh$Htae*|S5?*N_!uhF
z=6M16Cd>=9-fD73K-I)qiU;$V+lyuS+m2>Df%cShW)`DoW>>IQj^8c8iQ$iCIZs+h
zR2ZkUoc7{tETduFW_h2X*R!vZWSWl^(qO9X&Lc4FXJB<141m`Jwd-s(M49zqHoL~+
zj*PG>l@GnTI!^(D8|;{q{UC^UAJ4di9?DQuaQ0#dA1m4}n^-RCLUfSR6aj)NunygW
z9>)3(V0@v2mt-FS0r=qe*e-$zd#j=e*@uf{XFY;HMdfri)4S2<LV^AuZ4fR5sv|;h
z5rr49N-kr0HQu7T%Hk9H?TW3()l-Af(!VJtQV{q7R0+7!GuDPKe%10S#E`%SjPYub
zAPFd?7esyCX|&BuJlUpmwZFF0HHH8=%|J$4sPEu`?4!hD`7Z}6Jc=y;-(_z8!y15=
zTe-9%Xp$GK%Ys)s96phQkdS<8@JqZ1wKu%!=#E-JQ}R10F$~@l<}~%DC0a2NmunGP
zG7|%_cvr39D)W?)s;jk#awF<uN1Q}71uCJghDLd7v*!UtWe`U_XSKe`h<hOL)A_z3
zW$f+L>QHa~V79aIEi1g7k`KR{CK|qomm-y6bJUdq=L@fVJa$WC2$S8sw@`-8@jV=>
zzaZ7*0XJ@@neBIgToY<i=5dopui78@>$D_}l%zpa^*Eh49!uXMa}nfg8R{`Qp#!z2
zZA&&~$YC$xk#d5XlU>r+ftB>22ABG%2ADFdA=!<$VmsF18M!6PRKEWWgA$d>F3qXq
zrT)Z^pe5DuZyicdm3K|$jhxYp!kSUZ=j;!t*xOWg#VsC_0G0qjyxVvF10#-!jd`%3
z<+5>1pTL*doKH@M=Kyhn`{fh}ZQ})u??@C{niy1BJ2N9ciJmjP!PA5K3ysJrJ!~Nm
zjDx)Wad<|))oe)RB%vd0VORm`2s^hv|Fg&vuLYR57s$rd6h9;wPBvjYzkm6_2QaPl
zVIYjI^32OXxMv9iNXO!r*Kg&Mg=>00aMpWWbsmaWmhCTRd|O+OoEQI&q-kZFKkT4}
zWc#d^=_#_DWHr%gR?6mKdH^g`r{o1KMlC>qMnV^6zX&4lsiMS7_r0FB_z=sY+?-3?
z-3^J0R^joPLaWl@DP&F7NvsA>N7t*%ESAZU=*-Cf!J;X|C=7lDwY~U8isetNchj9X
zqLYun&|wK--yOu+zn?IX42=g4HV;tfN}oFr@K_2Ro(i(=V2?DB<cNAx>G>p7uT4;3
zggMw?Er;t;hn=!gaUiFkU|6PNKPsl-^8=F>gwDb&W3+zsUNuS(Ytlcj0rjf9*Nl0o
zuYD|m66cVeUo`y=o8q|TfY=D~&ZyOl_|C0skI1Dz4J&ddLAU*Xz_&!wMCWZ^=!n@&
zzlHPe>`VlNq+<zGjo)t{Jbdqn<Anv|8*llmIpK8!{+pm|ttSX5?MOV9Y#S}x_e%G_
zOWtr`)A>TCZQor75doWIhf1p`E7}+*{$;VXk9)IQ7{X$NfYFq<@qSJwo?VNe^N+=q
zKJ~7QufdSs%%7FA`38MQ1HaMMI?lj5bsq*@-lty8Q~2@LB2Ut7&kvOtP8p~VCIqH^
z`YZwdZ6od$l;6X43~R#anjBeew|}STmA<nV&Hstvvf(HVqR@z~bsItdl6>nq^**u1
zn!z~LqQzp!2K$&9+jP>EInYaf{?5OVCJ2IL9VhSf`Mh1W=KU)4_4bA;gxI>pE`!-6
zGURE~cxeNmP|cXOxFZvYZWRq3)%5qsmOg8$dKut$ov2vW{`-c2)$Pgba9{~NHVH^6
z6i##EHKKDUuy*>N{y3vJK#`7jxcXZX^^g!$5B!WiNQN6WaG%w1+0*8o_`$6}6f*e{
zRCNycIfyAm7K4T{gc_`;C~6+Nz0&z6Gzp3CM!oac!+9kdkuQ0=ohQNEgGWvvtqaCE
zGB3k1tV?7=7M+@H`Tunsu$eDCw-$)CkyF338{wv4EZiI=sVNSv?$`liuP(rJtAM0w
zxX^-pyrETCqr7w=u=!IyLUp9WB5$MYjy;$1jlo-5I5+cBUPobP^x53|>xioJ^himn
zh5%V=(fl9-Wb?3TkYkEoS%8y1bF`Ie{NIOpJJQtT$Lo~8>(o^eXW}gogVt^|4Ibzo
ztHGa9^)B4q-GN4V&awZ^P{Yy(g_psOy{Il@>J)q%jCs@05e*M$@G?^LisaMTzXuZ5
zT)T|?xD+37{M{%KxCvnH7B#cqBQv1qz(*VC5T)i9+$nWy-+T{mSf31ZV(6}qQi@jo
zWl0e`L!Wrf(}O=Kn1tFxsRu<ec1AM>k5H6%dTG_E6i80FhU5W<@w>+@w9_oUS+o2t
zp`Sq6L<;p_pqc6;LmS2d?l7)!L0=@ETKO-{Nr3hd@^sdb<I&&a%+Wf)0s0FP&&}Lj
zz=|%iIH3f^I%77{AH5KC!uP`m%6L~lW&;V7#$!LZLh8FWtuU-fPT)3vi)kC>5g%;H
zIBBofxV;JNWx5W!lxjeeM}2~nj*6zcg1_sarQVZr5Y*T;Ty(-oPkc-Ej#)-~HUUL$
zxmiGH%L8mqybEk$?oE<X3lq>0pt=3rUpe#t&l@8~g<eA?OGMpY7VLa42m~0^VWv*H
zW94KCWmF*DPg^%!R3sAHga!h)=wsf3HKL-di`qoX!9ZnvgUgu4TI7|w(Y#lsqN+Fc
z&cETi7E3{Wmei4b%iURPmoXpuho2USXTaZAY0LXUuFSlI-_qj16ikf{cWeQ(?kr1i
zX?i~9AZn@qNdV2ciUw33g39-ssXBOrP^xR{#kRDyK){Qp6@b_kF==XL?g76`rIQ%J
z$k(M0D|zbeO_BleHM_sANS@v5z9zTt^}82larZI%T4lLwj%-DjIDUOswy;`_6T8?f
z16%j~Har72j1%EBiAK~la+H3^m>h3lr&Mx^j4e788`$0ITwQ+g*%9f}Cd;GKePk?h
zBigBEs)5I1ZWnj5=R!KBLvJpMX#$rRP^_ikdbH8yW@fP87Dr!!q&FOYWSz!Mq+4YZ
zJl`%mr9T^jjYYm3RW#IdetCM=nffY2HQ4R^dZ0?UlkP9@2wJ8MUT&C<z;uA}hP{uv
z{pV?Q*$@*&y_;M6deZNr#of<5E<`97I_-to1mmd09;fB0jhHW_jLcNv>-PcebC^3Y
zCs_aAP360i!gW6{EHuJhX&V-uxxM<FsfqfLFrsP{gm>5n-3+KKtW_ptb(QXkcM7%#
z-kjw-8vEbqnjrO6RELVLGW8p%M$#H%C)Cy|U2?o)<tu#~($P{CUI-P8V|gadB94CT
zsZCd2v`D<nvJbnYP&sk>Cr8~SyZQI-D9jb9%U)9L2B?2@G@3yJSuij`|11K!t)xH_
z%_NgLlS@`xjubMjtqMA=%Kq4U(uyp(Qhte!a&Zxz?;0j$A_ah`i`8Z7sG|3Tc{sHB
zF49Y6Ln=FY(iovDSBd8zv=3g3Sl*d!jn!>gf?ZNmQd|#J?3RC+RYc$K80A)}7~*t-
zjV2sTt#=Fa7hu^ZlggI_;SK`|s`;QS6q5AI1!aVU9|(yCpf2<n8!P)$1vbPIynNqo
zG-N=7)CKD)NrLnf1Y4*^P}bj#v^|-O+FLE2dj=xj6C!t^2C0Q-#ZY+*ZItnFRl~~$
zx|(L$czAJt4aVRXXPz%$wX6UMhrA6=`LQDPdQCl>09RY#MGR%dkQSH1c#6?(kR^f+
zKl}4trt2ZBos-9amLsKod2kc1Lx`vCR(qF}+W2;6(XEZUq1qm0HrA}!MR{gRpDQhz
z7l-`<cP~q$!Y_zuTLbcz4Z41DErI}i&Se0y0uhYT@V|P9e|#>3z=lOBf<*r}u|?O&
zFcLPLW?W5sq2PHZRBhn*8c}j_twPR}%mi3w@`(i4kJO2js&nonQNu$MQxIk4R@x97
z!fV@)7};kB2Qk6SYMH+YsXZ1ak5oGp>8(?BLwzPb>F&)u5<P_Ne3SsxnE(Sf7+7>V
za-AdMQo=iqc3Opf8KdLsi}lrEKRV+%xO3TXxeoJa`~$>6x)yFE<D5fU<Qd=O1;-d^
zr`oTzHdS2o=Wdr7b6l+?`;8FrOspnxqrV`%Aih|2fBWGO=?>Gm57hEhposM`BB<PP
z@Ga;*@X_>dVEM*6NOpspTRRvA4?<Jcw^OpeQ{Edj2L_G6IFP}B;S({4#|=2zBiv96
z@a@$%8h<p!frk$_#NU#3u$7?Z=^J}U1cN99zzyC_@AQ9&!~el`LTy--F=oG8?v{Ab
zTaD!;V8zG2H9?w5L$47N`2qy|^alWUO0#XcSbp<i{-A!@k&>XlF`g@XXN<-1m+#J~
zjN{tpO$Gh)$k)(VUGG}wt$yRGw%de2Bbfs{`wH*<G`5WbyZ>42P$}fFz4+1UwC^Q$
zZzScb(_$Ym2qnQm>y07xM;Od`!R75U9D`|DhO4NqlJ+uHhpY2vcn;eX0iw+>_36qZ
zI!*uWE4q1^1NfuC9m@t8ZK^K%livj~`S<(_$&SGPxHz{-J6El>P}w<-JVgaf;~`-_
z9ZoV`wg}rlsj=NzKu+@2P2Xkn%~nv9*RA&XW*e~+)>(4WL+_`$1TrF7%Pum}TuGht
zkjf#2x7zfZodW=DLcikZf|BUpC;7)R(pk=62@~+Tp2JkdfNg)x5eTVIvvz?dONQ-M
z|IJQ|+z-0GpV`v3^{2Rz#UkgU9`X`j#4+8o)^^-7?9FEG7QP&S6_vs@K8Y&=_)1~r
zzs~)y&1NDYno&)7LtF(`1!l&Tv#Y&@alt>W1g7C3w1F{E*6*?O`8ZczSc@2={xs@-
zs1zKkKzb0x5lop=sPPS4Bwa0KKzQc`kR-}$jHD14Nb8vn!RUbOn&79A9*~(&8N>%l
z_yWguG(51diY9yytW$IkOFy|EsvlM{%2`Xz6mR33RmSnIv;f;WxxhI_B-4KaulHNf
zOU8~i+=GI9Vg9{rje|Ii*mrUc`bk^*{l4k!9oAQc#7Lvw4TY<*x7%#QZ(S_DGsB4r
z+I*)qBg~vtrWJX+TDX;I0N|^yBFiKBKP{om^z*~jTZYG4>72PfapRM*3PLU{B7Ql}
zC442Oa#VHaz$RCX8||<*ds4Alp>O1{Hxn=Kz-C9{V{77LX5tNLyt0tTvS>PnJ>G>a
zdZ(WINgxr1N4y@e&*}S4Amra#yFh_HIymnffteXTye&>w#jkj&pZ^>j7ULDB^LC$^
zn4PMMs@2Pw&g*J<Zk6cBSOG~4B0UDwa4vgYAHE2n#OnNrzZu?0H#?shN<s@UiWz4a
zCp-D!0_+C`97;Zw^WLs{8tF*YYk%7eyO*zsFiI+pqm1JZBu)wvA))Q=<MX5LU@02W
zQ&JM?2a3h2&oEUTuRhC%@2*_Jva|;JFW<ROPEV(Y;n3md-@%;q5TW~e_@8GNw7{>j
z*Y3rnXOypVwkpbBqJ;1xbq!8|O{GD9&=GoNj5OdPA^VcOztwWuTvp4P<nFF&J~;J6
zw={+HMAa#IyqU%o(+X6EoG}{$-qmA2sX+>HMo}00G}0^C`j%334E<=woDu%nnu^d@
zVP9EyiLaZ2`bot7L5JHsn7c(WUlmDo*axI(EY{pHT_Xf{`6OTBL)}pm`60DmfJNW-
z9F!}aPLAe_I4^JLe67u2?nRvcF|&(KVK(qVUZLP$|BIK<T>&3~$Cz+_!xLNCxQXae
zWxS(pa4g4K7FPpSq@BFMITZcy)Gqyj#d^Ldf%Nqj+sE2j|AsP>13KY*k#NC<<HqLA
zq!=2;eWy`Q-5t$v0;5q-72OVfxH!LRfP?^|q<?RS=ySWM$X?OIX>bA@wk)kGU{A3w
z>r*0qcd##whh$}m-EfDLX;q`A5)GKn^OLly9_kn`qWfaBGUFoowBTQAqvyhUZ0R?-
zSm=2LFNlUCVI{W-JATSm_Ib#%fj&wFB;M|mXK>n3)I>6{j%ZJI$ij4&*0)SMzInOl
z>>tcv=sdR*2-@ucR=7jmCDH)P0sA0Z8;=RU>^0PfHxMe|16Y`@-}MD&d;sC#$oD*%
zzp-E!`tC)C>3f`Gq(p$>O&k7bCZ%5i4rPQoycRwR@9rWW)=o-6*v@<$T&W9R<v2g}
z3^YU^qJOLSW^8koI));ZaYDn(!v>!*&X6=6<H**ugI64TZaJ4xEF@k+(a4xr75_3;
z0h2@#SIXdwkO^X_%0-Xf0gB$Z9x1#U+GDnUc?)FDz2#9}(Uy+fsE&gx9jYD)h3slY
zd_GPWg=|h6RRg&ZfL8MDKBB2HH(G!VEMzsF`Sk?xKO_AFNx)UK4&jK_>IL12#T1NG
zyV0+x`ekC{o>E5^9b1Oh9$6ZExp1gnekH`>e&_bL{_6K0>DObCIqrM*HTyX07@J;A
zZB=Ky;gH)kQ^Rzh>*m4lzM3SFGXAukK|V@TjSW)In`M0UMN;4`4_Ks$0_EL8>fmN1
zL$)G+^;_i!>PeO3W)10oD(pC}=D*T5J}kLh|5jo0bXE(Rz*6E@0cFPrqsDEmdajSD
zo12V5fbw*-3Ti!jEEF{chbW}ug;4ZWgy(8swd9kJD2DI{Y=Y(f0!fP5Eg=WSL8-tp
zF`kIgT-2RFe3e|u#t+Smu#-^VsjiMB)$aCqaXR?NNXXr<VUN(~TX=9vMe4@dK=q<7
zLZxXj4{Tam*rB3J$l?aXME4>30}ZIPoQ?4G*d%L8G8`+pZws*0B?XUc88)uhn{L63
z6X6aJ-)CAN?#ME*4FB-i8Nw`&j!Pv(LcWsXa2UGlN=|^<@(f2&n`vL7e5^&}#39^h
z;e(?d-;1v6`wbYrpCOKZWjGF3Ab|wzQ>GYzNa?F@NFT<-`1$%OC;!v+*kD)Ev=o_=
zFcVgT`YEsxkkmjZUl2An8g*(-dP0q7eydDVBS*0BsiAk+t~Hg6`@x(9<mLJ132WGC
zJPJH)CnAUwl;?+#k16La%&M|{ZBQ9cs=*`tZR8oke?-UG3q||<Wy<)jgh@f!a9rR{
zf6Nrt==AHiX+ze-V3MkOq>=JwGl(xIm>?U=RU}@1ZgXP94>1^^Rs-mfA3v~Y5=>!%
znu-(%=#u>9j!@aP;{+C2jVCjW&KrBnY2%1aw%2{~swh>{7~rktmS}CN3{Pvac8E#G
z7u<K8`j_wA_XWed?xSgp<mjKqiZQVaOgFf^sZSy+_@?&x&Nkot+g8I{F)#kD&FFR1
z-Tk>;`dTG0Q(~~=udP($I$okyXLnMUU3csA`t<fp29ZiVYnAVx<i7Bo_<o#X&Qj<W
zklx!GLmLYV^KQv~&`#p&KtG~c_^42B%Z*h|zQ9u}SKROM^wYa|S=Hm^sFGwKzq-=C
zZbvf<kQ>^Q``rVUe(TW8`+zabo8o}_m%lk5w*#i}SdmP)5IePNcN^$F)_8QT6g(PD
z2W+>#_i$DKuC_UVrwZI#iZ6wjvLDfk>(%EeZWmoX;*jW%nh_obQF%tglqK8F&XPts
z+6G(@exfIzZx_tQR+8N|{7(_u+J(H8{xI0r{NkWl2SA4U9fAKsE4R0m-zEgfaN?)7
z%u#{Ghnrl77~pLNqOaBfMN~@7DeN<YOjzO=8<7mYTzFZ&lk;IoF)l0<EAv8JO^H^W
zSDd}SQY$V};qshGK)<chvd`+Xe5PE-{G)vtPWTKIaonM{M7nz=o+R`E=1JU#!e!Q_
zn5F3ykLaK4A-DBver5sv`g)&9StaI)&r+!tsL!gGDP||}bAXXW)3oYU8+08|K>oBu
zTR6}dbKF>}uS~S-KAS`3@`jJ_$Yhs@#G_o0=R?g6Jh-awNj>%_QFv70B!xUwp*|b?
zv`)Nm({o+WOwz@+zK6-1vOX0HfeZu)r9PcHO^ZJWW}HZtd`<sUU=mOpZ6w)_eI;^W
zb|7~kwOU-EE%FVxQ0;Qt#UGQ^S^lJJMaN6pu7dZJmLW;un}M0@!>}4WaB$sv1S@oo
z84f;eRpDw|+*OoQgJQs`-|{|%H+fx+eIl}qN13zEyL4Pvovk8+B>@S|vy667d=WsW
zHd4@nRAB#5GzMRI1{6qyt@$|sE17dlx!e>P;`)6jDg1W`)3IS*nSioC4C;0s_-Whx
z>j1u{Gzh=NI`|p}xv&OV`>TO*R!y0%<XxagKOybijECFVpf*hb*M~j+g4<RnDZ<dz
zy6+bt?LxAvN~l{MwPKdoK4CpxGFKvlPCz^s^{|@$-_II&=nY8*Krj{_I4=qmbUKCj
zDM=mk2=>?h9kxSbDx;2RZJsS3Q#rx<Gfj+UOERQRO^nLb*Rq+X9czzeVP%xWs6d76
z!#kq$!99dvuCjt<sc9?c^U`@rcwF6z%N!eOf4+6GKzzhxG(zJ+_G#bW*fiu;OfxCf
z%hIwDg-e}lJOE#gt49>{Y070&K*z7kJHgnrhNX8vf-~E#u;!o;i>-92i+{_fs%iJ<
zXhe3QoAWBr@q1IR18QIS#Gg3OZS>8rN$WSeWurzAcKBGJSO8~ZlPd^~l~il_EJdI5
zgRD-rHobmRZ`q;2VDD<;O~+<g`wcWi-BvbAXnoffSW`{|g799lepvzrEmZ@N?cl$%
zeV?>hWIpJ(`#yY|?+1R8b)2YhMr)nSslYx{e%6j|fsEOnpm+vEto1suqj@x(aFDD}
zCoI?DvmJ5|Is1j8{+l{^>gFZT77$9YANbbiK(_y*0iZCn_ASq`cI$u$*UVVEfNk^i
z@6^3OYx!H>T%cx`p9kk*qV8b(=3T41T;&en4dA3pzSZsZ36A5Ziv{?V8}uC<|2e0-
zwV&2~UFnHzxp(as7S)G8jFJo+;K3mAd+!X<WvFEjCX5$M{6(Iy$eQ>5Mzr}F^ZNz5
zsgUkm9B*=W9qM-@92oNcLy+u&N4-H+LsnJ8GS)HDkt=jx;#^uG)E2O!JoSVC122e`
zYEofMDk^$Ub;6<AQF&X8<uiu)vKcIqh0E^@ic!A##?P^qk9E7!f7PoJIV(gEmU?LO
zf-@^Dwq=bV)yb7lKDjGDX80#x7yYzc;FP^nT02^zX?goQyV>k&Kfmh1RU)QwmzNoP
z11A}YGDvV<I?G(gUCzy2I{)XLUIpc=K_L3HKfJiXc$5SEkp9BZjxQ*@K|`*PvTKY3
zYbM=^F7r0+%9bhC{97t*jhaur&6dj#Xjlouae~f_qc8=rUwgyu72Oa_w427IhCc<y
zt3Pk;0kaB&^bQra__Mv{#K7zoxsMgRG90<q3<sUw$ztzzoz)KRznqO^lEU<NMeK}n
zX<F(J$<=II$^X>G^6S81U#+M7Bz&{{&0bQ1QFP3@`NGeB>{_~@%4fHx+(rUBy;s@)
z{j^ToU7~EQ?L`;GYuGHYi0$JL%7bS(w3gJSrLPh=({%5lTV|uU`yN*=Ngk~@7QS3%
zTVe~>b-%$7U7puza^RXTzD34Zn=x7Z^QPyAKbN%!gd(Af7*L>$sk#M`a=+DSp<Tbr
z?38OM4n*0XQznmMImI|Fw<!c2`z-@Kh*sbLScDn#MPMhCCow`3#>h%C$#vN57lpGW
zF8pWcV}=_5$V!9szULRt3xCBlccFrqw;XBqIPy$g&)e%xQ%Gm;0}H}hK<@&xK^^*4
z>HeS@=~@@-)cvs=4oOxk_(6y&`G7D8@4r9woZliQ%CuSSAF@ujSZAZI)NoFKbv95Y
zK<vj?GT_kKA#~mT;`(Ij%2;1nTU(FqA0nxhEI;~g>NiH$<ue=GmCk1xb9>u-TfIXF
z`QDCgY_9D0W02c*ypr$to~nJTiG;$me4XKv8B*SINs@0)b|gZsIAB*@^V(8JtjdgR
zLg0`i#XKkQ{R+qclW&HA9!2$-p`ZGG+!<=WT5uJ(3U&W7Gr*)ZjovKSwDc?KO)d4f
zgG^OK;%|bu&_Y>{nMh$F^dY95nPvWP`mg_{*>!$iBYbgyQoVSRn8`jbb`OX?6}Y$?
zm|Hxx%fIM9E0ngv$pqhweDh0o3{Zpm_S~@?ruH&E`hPFg-7&piBpwSUZ%MK$9$<+L
zHpQL7(_fbWl81IBw>tqy8?~|T>@F>aY~=C6@>4o~qg1%tE1$3=$=~YsRLT)t-7i6o
zAPC0i407+x#UFCeQ<56-tDrP_tCh`$L*Yo1Byy;Yw<JU+>fCH8jA}(Vx08hnuSGM`
zvAfjOed@O~mL}4w(49?ZGYc&drUi-oa!Ni(oRqRoWaWjm2?WXXhw77!QU|N=lDU?X
zUAT@9?HxEl+!uD3x|VDB3rY-xAAIf)BF8p1IhZbjx*<_botnpr`wLrj%tgf|g(*du
z3C9{DJzH)|8b|oG69TRm9}sbum{FaC6^_;T=PJ<jQNwZxNtkEzrXEW{(ZY8UA-eT&
zV{RmSG%Z<npr+9fs&L~c=@WUQ2xqv<q)89CLaC~li(ki!=Ny$3XP1^MNvpu}#NWcw
zMJLMl2|otqBNdA0+a+gq)I)ST)Xi$b#+B<VnGQLpx{3Qw!vU;n7b~Db*OiKXN-3PX
zAZ<|=v1Qist^K)k$~66Jw)?QaB7!2WpM~yj7ebteWpXY*4jGNF*>1<yU+e!DLc2_V
z-}S#8vWp(vDfV$EP@qT!f5QzcxCvEvS?;r4>){E@!_S#jyr|qQr}G8t2$k=K&9N1N
zS`0TxVfcHkT|(Hez00hE+?69GSokPJjot9v?#Xg`NWa$L)g&SRoe?=Ue&}ybnCNc(
z5QyuLYmPoJCH*iZofi-u%jyVu_(B>=-ULE?eg<UrkEdtAEML<Oe`>EA<UDrJ+CKb9
zwkJ{?>Rb@Kn!6~v04UW82i7c+7q^T`U!vi`qh=BEz3{^acrthlwizc?KZ7{E$Hoo6
zo^YMlAx1X<R5<$Nh?K?gQ!a!^`0C4d<;wYIQtxeylM#y33J7)$rHZS}jE8}q7^`e=
z?p-nNtBA7-on(v$Z@`4;`Ht9-^^JMLv1z*xg-vWe!TplKeOiCym}OVh)W33f>6-<K
z12S-V;TGQ4&4B6rw-#}l2$mZtUq8VXCtwNGo`3i$utG`b2c)1ddxr~umB|^y{DT)#
z7YgbCwaFM^O*#QEhqEV=|52#uKLK>GS7AOe;!ecr+J)bk;2Js_zx+W%z=T9u!<3=#
zD(FY`sW*B-lKVcr+I#m6#oNeh(5kuP%D_5#a;?1hQG>{$s|5d}F7q#gm_XLXO3CBq
z9bJWvPu)GIXjg0dXOd>Uh0{ZOgg+*x$@ViK1TB+4k#SzZzu@|cT&q%9r>G|Y1hvlt
z;p8~1>Va^d<NnS&z?k+|jn>h;&?BBh+Z&hv=DYp62u#m&7lkQwmFQJEHgN2@9`*1E
z+2TZZW9}n%v~)xqdLRScX8$-UxAhlty$8lB?E#fL$-;AjE9ChP!<ay4%jX?@f*(}`
zmeJrn{LRIq{dU7vFK3GrDtF9&c=GbB(nav@S2s>mxDvhEu(|?SN$qTAELTNNL<PN`
z*P5<&>u4K%Wf*WOwt4M=v~vgn+&*&84X}Ma&2$~-C2XyRsG;&Ioi9A?dK~?VaXl_e
zAh4esa=i!Bn};%*N|9A$2xRN-WgpqM-OTA?zjie56^oLW%Li^GzqQoV=0FNZ;`<?g
zk*&BxaeYe=#BCc&=?kr$Z-H-(Scf~lh^X-V*JOd3!L5Dfunp3!SAy;cJ8=+yf?O&@
zDso%)0Yr|tw_Gqh3r1hU*B9r-)~C>b%7|z9Y!GNZ{_o-2(e(@{0g?!B1G+PVKbXPk
zJ>EEy_edJicUuqyp-`;YI~MhNuzMjvP8gf54Dv?2I+3Yr`l^2Fd<XY3Sm<mMm`=j~
zB?Og)aa)m5`sIjSxV0{S42IOEu^6e>vbYv1XMt3bc|k%g5<w4?qz|z0yKTK1N5VHp
zzzs%t9lrf5-K|9EjzSDti17Fe*0I^w$6%G49T&J=D7XR?7`J}@*K1T+b(U<xvJdhU
zoiPupo~V>7ieF9or0HkLA@D%#-&%@vb#`x}utzg|dcw;lczh)-W<Q#o5xb7Eh019B
z>22O}Ad;z2Ywqmb9?D{>Ul6tXh|<i`0Wehz+TuMB@6q*Ar3im`<2Y3n*2oZ&(X|ym
zXS+?y_*B4<r`iT{PvRRrL7}VrV(li{DFl~5smW{e*2M+&b@{NvQ=%lf^}TyocF1&W
z5>2s<;%XmwCM!jaNQQJ$4>g700vI$t<)p$1pYrl2u%VU1eWdKW@~60CXsY56w74Fe
z%;nz<r;OS)D@FO&4#j#06f=e+|MT(SygO&cu`Ht&dGs<gv|;%La9-kD6$Eg$q|Go5
z;y3i&+eA{=L!!NV>?hTvC?Ab_TB}U_KCWDcovD=mT9mAP19D;Tf6igaf8hKALN#{<
zF4(HSew?!UEk_)D=R;5O3-i!^(6E3~jDSxXszACFX$ds5%@tDHmEqVt#4Gt6jVsT@
zI6(^2OW%Q(=;!b_NSNsOg_e#H_(tBIC8z?E3MJcm*jG`#a~*u*m&YSOn^P>(WL|2}
z<~Y_Ozm610x*8VkMHZpV5g2Lk!70uUE;kT0F0h;1Yv(p7^odWbf5K~U?Za4Esk1K-
z8!Io-O4Vq2XJ;Uch!hS=f@&2Fu$lB5YI?^}s1rKcmLFAeHDN$0i(|?9YSEt*i5%(@
z`~Kr!?V#pD3q-`#n)c#x0T`f16Ol0#XK=y=9mXxMG>d@Vv#M_7TVCc*Pxc1F=;yCl
z1#i)0T=ry6+JY7nt3Jnu_#IZbzFL%L?SH>i66hCz%fCycQZod`|B4>RYp1YReDYNV
z{R51R+Pj{n@4fqfA0Jr)n{Utvsyhm^TY*7y-GoL4c9_Wsjb59jIw~hq%6GI)-X2hx
zQ+J_48eZoOnBY><Cz3B>k!vyab=*oCjFB~6w~j3*mfyCH_`H5B5$db0>PMnFs(YdQ
zyOHfQgYy#+T98`h>zHMkyPMItZp$YS1M`%>qIU>Sgbk-aGjdak*|oSqwJlm@B?GG(
z0B4=fDTI(Bul#${IJxFgl7Rg0Y1!|bzOaKtA;)_u$}|Cav3-1UYV>Ecez=!3|3&9Q
z=RA~eXg}2z@HPq<jToIlh>?@8GbL)#lJmJBJl-=MgSU+*17m%c7v<Z`GQA_QeWVkQ
zPC`Cl-^NfTi6|HDjOFmr^C`iPAdoGwIY?+j5VXMhm|*JxyvhE^){zZd1*_F{wEJpJ
zq1qD7QEm+jJl~Eubd?HonioR(;d2RdVVh`_xQ{{u&Cvw!HzrAClj?wMTlG5#^4d1d
z#jA>Qk?1zdlE#3RQ>3AXV}7MI&+lh){>4XshMm_j$c$GSRz38_bQvzY0Pn_M@P5L2
z&w4kZ0U&_H@Td7teNmAVFX;uWcKrU<$eP3Dikv4#vk;8|q<!T-0ukI5t#B%OQ(^H}
zFng-i9b<1t!_bBF?lXTK*rmq6P?f->A`g~t-R~|-u>d`b6iPb%sCwBcNZw?!qWl#F
z1dD@Ym@u!4_B4npKI%CWat1Sr6$%}dV?sEJI2|D=CbIoA`EkGwV7Qsd3d#8A3#cJ2
z;tdV!-H2}_?<rNkCgiMMNh8kG&Fg=5+r|0G7pT=OO(`8VCCz8j@%jjm7&BgzJJ+*6
zxhLOt-Sd|cktG3LmNuNRE<mzFg|gxr_Ff09_hWPDurVi4@o%5|d3{&2)gZrhdzFd)
zkrVtnA#i6c+^;xWyXRcvaBV?3<4^IuG%Cdy=N5QIhn!M$tR{d;aq4JMFv0MR39M~c
z1~ZR)Bf_+!RR@lP^M}?OO7@o}yal8OHmVFezWHzxh@A76IhLS_@Ovm@=bS{h<+Rwj
zf(MN%no|Q*Bbf?4OU6TIqlPylC4T%Lt5$~>U#$iF+nc%8+^^aePgFl7#$4zF>V<!q
z!5R&F*<U@*B(|#kzSoeheaYGU_kL7`PXE^#Th5n=w3L;VX1Y*svxEQvBr^XJVWkC5
z8I02!I0zMmYvFr>*NWr2eM)IpipJ8KUY~S3@u<(#oRygK`Rs-h_c@160r~!z;BZie
zY?Oz4hsYh=z)F*A^nMMBFi0A-kxQ^u1Eh{lBNz^GH9d)2Tt~aqi1K{0IE5L-Pl@d$
z#n{#8M6|U7<B)u~ZvO~bI%sA5#~w%&K;@2dc}oB5G<~+^3tf^)q-=w~fkUSQ=1Y^S
zwo_R&%lM=P!r_?*BE?j6o`8@5xmC%>e#_NulKR`fI9mEDzsuB<Aq<h?947ik+g&S_
zN{!n~R@mY=O#_br3*E1Nh+Ui|&4gdJ4T&C5f)vC?byYhrRrA%}K<We6NCjTbpixJ}
zOZzXMj+|XT$z)%H)4g}QH7w}}cm@*e>Av?c&<}~bb-ef|=lnD4e@z_!>qH1F0zQa-
zbk#aF&tnC~E|?(v;7-8p$FOo-pd<RjONK-m3iBV9FV0J4&ZZU25;r9!grc;KBZdSi
zE|2p;Q7Y^~B*k`lIpv}wS9PaYGNM=h8wULJ9;<8UA|Bvi`G&fk5cE6Tdg3S7$OA8Z
z5XSbV9x$i^CDCKyhrTf3bOYl%#&=;hACWy+gt5`W|H2aoa!nmXd9P#}-IvC8*+73N
zWRb>ljkh_Y!>3TVr2*5u5ctVI0Va1|6s)^wr`rD{{)SS0PT!S}rO4Bzz9)C%B&kQ$
zb{~wyy#IW({ze$F4q>nACZ^g=1Nr!Co^cinpK^Am(I^}>M*z1FBXLQF2!bf_p#L87
zJ3{GUY^z&?VIXsA-oe04OmwUQyu2!mU%8L&+je$=OaC;AaB1)p))wSe)NrDOYKG^c
z1zsZRscjXj%DUH9bj363|L8m?xIIr-Ixx@&gc<GBKI2B*V@B=R3@;pGVZ2r-1b$CO
zde%Nrg<iF*sPotZ%sGUFJR<Ha3-~4ED#_l5l`A5WbBT8eomyqHb3tUy`aLs{A=K4?
zA7@~?)b_&@G}sbI)O9~pj8}#J3<c^}<YmOswrbNV(jkW)EM)DvB={wX+Vy#!ELuqp
zim=cl*@P9lC_H|R21m%iFVDw32;MC80h(vG1{h4b2?7_lY`QqMKZw;Vb2zHbML(nU
zBeM8{*?zS~U;E>E4;mLG?ZK9JZuk8{Bkc5hl<pX}i;l*UetrB>KVdeUy`mRWOi*5F
zoV&*r)2HGkxGQwl^t%O{5H5zDIQpbA&5Ba-;&Wi3I6G@<<aeX-^2tvTkvw+}08D<4
z#ATX3R$1u7GVyg52zb4k3d;2(CHfR5QHDs+P>PSPM%}K3Gf~8-oK|fDAk6`VSt_a2
zMaXstzDYFDtXu`ev7WcE{Es(!8Tcr?!Ubo~GC?>NZ3ZEVe3Z{%H^xv}1dyNG!kv2B
zNFL_}mr!;Z^vR0upXL<WKKQ@f{9^@!$k1z3lfciyB1O}rBd|<dI0AlJ)&9=KLl}%$
z!Y_XC$#5t1Y8ejo>8D{-@O_OO%=3m{9T24hajF3@Npb1e&XWZHzN$nCTb?D75U_mY
z!S>?}-g+k!hiGvJk~;)BgS{>`+m|l^?B>xGH9?|9SA_Zcfhfwqrc;2&YV{-ykp)Z&
zNU!MkFd^6KX??gsamFchICn79%JZ3pI!^DKYzqhI+;@I>w3oM`5d*`{&sVBd#DAXi
zOX1u<)ji7Daj*>9)8PG4KUd>{3r2s!1kws`1G}|<=7xEma9@(m?JiqZX!Oe~exwz0
zAuYp^KLHko<740mHuFH(;jPo5IZoO?0>YlJuh}~z9f$TcLm#uMXZsPgol38Di;0g1
z-DKNcf}6bWl#?@lrrl!9!Ok7fsr|ABwG6@qJRZ=z7*pWOc@iG(TX&A0R+@!9W~KgT
z=#8NFN%;v*X%Z$)g}yD_q96cZq@^JKe$Oo?86615;bN;mrHR8}2M6cwok79bQ@Jab
zE)@ksCc}blC89$0PtuP$F`shLq)m7)da*ut+zg%4*%kiSfV+=e#lsxDB!q11{#K1r
zFIKapUm+EplGO2=rwoE@_j&&qSqu&N9PxIf`KYpN5zgbwcpW4U2G89{Oo*R^?8h#9
zk0pz0Nfk`}o?@Gh5oz!3W)Qd(1hGSG%>_Y9^+H2>UFyqi=7mzurvCV}-0GbiNOtMn
zd&}FfpEiq_mVe?Q*MVm|-uDRA3o(-==;yPpL7V8%_Aivk&1k8!S@ne-tWK{no!rmM
zKFyj81sI}5X<Cj`^c<&zRWVx=9)_(Z9?x=BZ92B35E<`CpEVa^6BI{R{(0_}>{qIM
zNZ6#rg24gcL7R$^?mQ{5Wtetth-C7Or&z;7A1lHn)C(bV)2~Y5kAYCCeA`kQ&Fp>t
zcO6#Km8@Y{TM1HGRK>3RACz0Xf~<Fcn}m1oS@Zv|TU!+tfL=bCX<pAsz~HtuCEm7k
zcLsNdd1+ErHY1msA(<66p+q;vFxJIi6U2y*5&~UmtQsd+qGL<vY(CpknLLaLt1&^*
zY3H_#efR?zrj>%HZ975E&8Sf|86OL>4`_aAa0aI(wb@H1nm}#x5Qm$B-Rr+?X$~So
zuqkLZvOhUx&xKe2g&n(h3$Y09WDNX0pY(axNZ*LLM@pRypSF((pFxWZ0X=X+tE575
zb{G)HiRXOkYmYeCE)f-RhCoq#9x;;lvBcRz(T2Akcvw9y^U8qcT(!(_-~$>HosUpI
z?$q1fgNn5HDw14N<?J+fZhj(iK2yCU$=0#nn~yJ-{8F!kqH-BSTM8EHF~tOx<XrT?
zc>qPCTTqC4@?hh+P{||~)AjkZ91DShIJIEeut2T~fpK2pMvqT6uj?=7SMsRpC1^Df
zjUR9yF9ji9$9cA*RA<Re=1zeZPI6%MhNL`%c=hJ8%70+z|E>IXD_F#0HvyvHbNE=X
zUg~d4e60P5#%Z&J&{w2Ua;={_O=I=LDE&q1&wyy>3DsABNf0^<%qlH_0b(I|Zv0-P
zfzT;Y1Syd$eWglZLpuyf&SMFL2B0fsF=mlyW7AEYobzdt85wYpO=eZ2^dp!q+{c|D
z(eutRXHo7{N*)|y$*BCqt8s=M8|}IK=B+XEI|8nyAmaLSpx7g`!Heq6XbpxYViZBD
zB9`d&zM8WEd`OjkQ%z0#S3vlA-8yFaZzr;@4F4&v4u-WHag}Nrw9e~ESg0^z15w4j
z?t7)(r*MIxiUCn|?gw2-lTeys6`n2Eti=>o^4n*&RW>MpxI|BaZw<hL?AsF^lh9dj
zK)%jvn<WUA{;bNRX%Z|UMn@ns)i>_5I7r4J=)~JlkjGQmIZ~P>hEbH~v-dQd{-|Bf
z!s5MnkAC3&HnEmIAg@wk(~3%#LFT&=jWxw!**Z82ZNch@fuY`th#|o_9R5?~o7}g?
z{LRoUOlCxgf|~H)!3{!AW?E5wVHj*YbZi{BH*^xL=#RF<i4S|fiUW$DPO2Vfc#BJ0
zN@s<}Gu*@l+e_7~j;;i6_$NlzGmhnUD%6*Go)i%qz)pSu10?;?c)IY1yXvI)&gA7p
zTFy?}Ht+{5#pC=P9)m(W9Q}jnw?PuU2FI6A+S<3hs<Xnxs0}tXkO;DqJ+kESRm80*
zLNv*<t$Mr!RO;*u2{s|ma3SkR%#Fe!So|EhK`t8N<!1E1eQQXPH8<PUVnlMfIq9b}
zXqifAc(2(GAFmH4NjZc7QQ>OZhC@&5g)E!~Zhg25A%+|zumAJ?uf!?IO~8uycc@7L
zm%0-cf!$x4D%U%Zz4WU~6(3!Ew0qHUr%h|l(#RHEF01$D_O}xLlT6@zX5WE@_W!1H
zSmDlDffP(PayawuKrE$(gfe7bQ0RZ-+AJx8=DIfHWo_dd0!9185U#u~)*~9A7WaYq
zS0#b;_0D_YyHC8mXu^_?^Rfa8D=lLsD!RXyAe~^C<9LeoYFT_<GDhw%bDpb+rN`&+
zI9^!kL+MRLBV#QA5j-H8s=sw;ogtb@w@>`E@Pin?TWzVj$nR(Q%ms+^Nk^$~v0CTj
z{tavaSL^%)^__BQydTF{W1CvSh`#BI(A6kM`rItw$;0~2F#7aIQ-=Ytg0wSc){1`n
ze~$$l6AT8l6Dv$qpqr07^eV7KL*Jz>rcD8uG~Y#K+xH2IF13Tuae)zsZDoESoa`3_
zWISj5v$6n&5EdrP#oLCCLtxM)!4<twAUYSr-VXyg;ll4oc&{Jj3xE=9rc|y8)2Kff
z`e-xqt;hCIN$96#@9<E9H8KdhBP|FD?vOsLg4+>pn_Oqt8}nFHgN4i&kd(Tvqs8Sa
zX)qtcyd)`*79OT+?Hnb|dmjMTwcIt<C_{hxR~Zag?Qn^)0vAX-2=-*p7X}Td4VKV<
ztm1LJxB_!PaaA*}aYgAb8)yx@b#=ip(jEJ95MUrzSIheAVio@1!ncHB@VfSBYqIPO
zCDty^EWri)pJ<LKMt?^uuml$we_<F<o;#ijn!M$(TSW9}RjdWb5;$~L{qRst1}}1N
z{DIpr*VNERkEC;JCpPtaGrJYCCAFE(1~?A3lI9gY1(!I@$|$~XGZRn`hE1=JM;tdW
zEQo-Y(IznTru`eF2dV#piI<T(8coIf>G<#G@x2eQz`jywj2{L@ECe-ujXmWH%9Ho~
zDZ?FRoDf-7*<5OQPGZ4!6vH8tWS~13L|`1%@Z3%>W6B?+GynvGxJ|eC+}N&u+?E1q
zg2+^oxhN6x{!APH*<CCZ`QsAyCf`t+C+JXosaE!Xn7XQfs@82ycb9Z`cXuvI0qK%%
zq?GP11r`m`A>G{|AdMi6Ai3!7zLR^;-sisX%$k3FV~j6g>BDMPd}EUW7Oiupb4HL;
z^zJa7NWii=aKCd5nVjULtA>4PiJEFnqA|eA5DY&vM4_bYgUk7~ABd@4fT`f0n||KE
zUH*Tpc1BFJ<7Lm&fyaOERS6o1QL_aC(_!xzb0(aRTx{JBeNFh~V#Kp}Rf|p&;x(iT
zYa#}Kn6NL6hOiP$*Dzd@UpI`!m1ea_3UlOR3Dxg`t&GcUAxRX-c8$e_Cb1rhTLC#9
zZ^HL_b1pW>>k3Lt=6aV@9l(P(jdhCRl{thk{`_+j)r#OL5vsl157f<>GDHzWC<A2-
zNk-+YKbjQt)>c^w!=HB`f!bZfETojS>fyZhXds!xJydv)F>zmTUzs-Xy>lTdgDF~_
z%mAu~%X}~ikOoJnxW%W6R}8qDZkJim886ZR9)Hg#>!JAnxzCWW^H0-&Y5jXri^^fI
zt3V|o2aMmZxt7I0B!*e=XN1e1$<=wl!lR~HG7=Fl=p_7}%TjfyJyYEQFF4$aOn2<7
zq_mc1j|Z0r=i2IcR_U&fKJD0@bxL$%b*<-Or=XxIs){)6V7@eum{9KVpJ+6079W>A
z9ID$9Dsb-&?*C+%WRjaO6+t$;CvSN^x<SV7R11?dHO<Kxe0$95$W3=lf>nYu8K8_2
z(TTT`ukXd7xY~qug?fKpj97ReIRkzwSYm^hbVt@kV`*FkHD&%Fa78krmb(*qHtd@D
zT!kLnnV-y86^aIfXg!dK7s8-Bz}PARej)2rYM{=oDHlhP8SQ*KpczI@Xd3ARvdnU;
zb1X)QXJNHE;ofgU33`5nP}gx8WCH%t<>@ZsQ6)9iPzt7{`0992lnG*@!zo(YFHCbx
z7g#;lKQNnjmK5$ffxzgwHU;Jb@nRgm-kSv=Im;yLcg<npNCCx`&POYwkr?QNE$*hK
z{aSV(sB2$lRC?dmvYsMNqMvaTFDroLA4tk({=fI;^+c`L0>LNZnvL9kIn+NMQ(#X{
z*BNFCLAJ<mwAR0ho`cXWS|nMMA+x5WgGFGX<QWIW$j6sgv){yX=Us@5#xQhyLiEQG
z1~<(wx5Fi}S5n&-4pClFzgB@TueR+vsVylDe{prT3F<@(6-6Xy!;LebXq=bq+wv@@
z4^q*(aw~&E2Sobe*CckI*S^Sa*qbM&`}O{TIUFGwGlEoB?webb5`IVfB_&DG!wA%r
z^T=9*>;Oo9I)S6b6|y0BqI_=^HltJ6Iu5na$GahHJ2q(rqsXfwl}Z(WXKtJYwCII{
z1RijTcL15dK5ZmS^k$frW=}kk@F$z#tAY%uV(Lr<u+n|&*&kny{xAERlkbwppkWaf
z(sgR%IHv)J%3<kiCgZm)P?pOV^*bOgxWWdn9UOZ*fD3ltdi4D1T4+TZzB(SA-KdTC
z%&^ZHhskGYwe%Z@cvADb{&xwfBKC6?itrb=M1F%jsGP@bU58A7bWxD~Tg5+D8kKYd
z>&WncCFzinVh}Cg5ORV*5f|!~q{?SuoVHNe?^68X$YxZwXTy7-X<%<1%Hns(<JfMi
zU>r_M6=mG?XnY-U5oJjx3zPeevKH+Lj05e-LGGu_!xNOY@VUIBRht2F;H~rSIywX9
z5IlLEx`W+H)!g5-9CDYa8e9u>Q5t6u(NgVA>b<eeDcWwHfagbIo{`y?5$Js619bO@
zO7t-rm8DH6sH2_9zyu(APW_`hO0DBEKYE`~P<PVjcLC?7$IU1u-}oIfx)d~oEB1R>
zuCbXX7tH`h1aWRuz2%lSo)lv=S5!5n{Ya}sxdnW$Rk}_c=GteA`_bV5(~ymrA<??(
zFB9U0<F{J)(9+b%h@W`BENh|oq;kOsx)S{ozzIxw?dXXG7CnNc&ccGx(R!Q?egn;5
z$rsXsyIYT<kp?TUU#@6{{PU|s!a6$#B(eCxB76DT6{6zvV0;^*uB0CJUh98x*8jdF
zDROr`i~MH&k=1RVPg3AG_eXL)c4ZD<9pr@4>C&r6KQ4>SCTK$7nmao;CbzgpQy!wz
zeNzOkMzkAQH0E*?^u%g9@bezQLSU2o`vvp3N+OJA>i8PY6d2<S^J>y;p^Zti3pp7(
zy1+yMXyuFbD7r9e>)<15^7obT8Y6tKlcgge`MOjSOk&6rZCId=C*^iB2pSD`2^1!G
z@aO%<aM}u#zillS6C%p=YUo%!e|t~w_P*z!>`CyfJ8sb=KgUzPIl7}ilHrH<8JZPG
zk^hAdh(h!p*Vz+b*Il(_Qf3`~zCFg@?hR+ac>=3`t?WQk-;QUucP<$5hV5{z<VmyF
zl)fbSTfRT(V`DNy-|1j=_z}o@DBt2a*ZhPp{|68`XoIeP0KL`^aU$jkaMp=n*JrXL
zIeuV-e0cW#n`<<}(&69k=TxeZ&jHDB;kG<op0*rv78L+S%e%qPVaN|G2aSxHcfJ!;
z|1Zk5@p4$K+pZ>+bWGmaI{KJuSNB$qe>L11U6+p5yRl#9j`?x%OA`Dg71zF27l8`r
zYIr*g1VMub<LIpa-K>{J>6q2Ndi|;q^WJ8mr~~WSpHd|*6h!+ieOfn9)ZV3a|Lgsj
zvaXS=eU(s~9lm+PL>m$)f(wS^JMH-w0#3Eh^tofLuhVt`8AfFjPjS<}(2O@g2$g#&
zVe!q>0Q5PGWFXzp>_)6yGWUFcK+LljP#tD%`T-5{T^AlYH%CV!UK4L%1_dcQW`f@R
z1b8*<+0(0bK80`ed7EJ@meCXN-I%_e>JofV8XyGu0@(6<`MV{6T8D_*FkvG??{_#~
z{ef!s8VMpwiN(F!|D3kbiYHg41Vpxd4P*dRgDLeVdzi6z^?`}p^PWNKvJyRNX4Og~
z0KOx63$We-&3un<jbqd7-Kw+k-HQ*NK{b;?JKr*VmqmaI-H@Hwz@Q=B>r0$&O3x^`
zY0BR=vraP+AG6bPG{p%2t;WAdipsyf<)~>H(q4urUn{Ugs%!c!GKqyvXx)*c=%;Gy
zm*ENZks~7fcTFY14IV=2UV!~o$Bn|iMri{A<2>E(<--!_;V*VGk1I)IrL>-Ov&a3M
z-S|PYC{9#vqSFrwvtZvP-E5Ai=Qju`!vtq_$C{mRJmT|&J2YPfrAMdr$2(q|Ny>ox
zj<L+DYDH>OQ<eVGLd8_epMa<PE50?A5DDgUr8kP+do*B;Ooc=^SN??a4A$tXmA3t^
z?%n(tlmtwee4vQ%zoLJB3js0QQdY>^tCz)QR4@?QJ+j8Bi@W8NdHs1Osa^VUQQh*7
zkuboZ-yZZNf$}gJ{iVH3YN|@*hC8Re8u)n&P9-DWB-6DS0Eo%U9nC4#D`Gpxp`wP_
zB=Q8T^h*g%);07tJh@d&Tpv@?Ba_~v2wJTC*lypSdH-(KL}fLQNsbN#m31pz=cjW<
zHqx0et+CL@p99_D#m=C6?AHpO(AVaY=eWSJGSW_AbPR<j8em3k8`LLh&ha28QRDoG
z`A-Rmbha#a2essQxjXfDfKDZ$D4G-*Z5VnsZCaPaRhNOPUsM=5gHfg}H9IX*0V|4o
zd)qHc0J1eCfHTIut#qi8_}S7DgXw!-mC|G9IdPf?{pls@a4aEtGfYJg5sXhL*IQ*-
zqgC!s??!tsEUn|Q9@rRv$c{RM*@n5-_jg^dYoC(AnT9>z1q%OPz#q8yXD{Mf29%@$
zK3p%QFh^i`RNL<Z(5$li{bi-5KMgbiji12_t6@tGy?uS{VJOq*D?Xh!Ffh@G`e4<K
z)G_XpgpsE>b1_(bptDhZ2}D;wG7v#Aa>ay1$s|Q4!JHzFfv~gi&>Dtrp*dvEJ<wq_
z@X*gdH`c-_=*y6aK`EZRxkXK4Tk;M^AUR}Le0ckG{f9j~dOn&1`!xj6sCULUBKt6r
z2`Y0>mSm6Wj@EClNW>4K{Mvu;&(FCPc=b<ZA2DecaI>8*ROHKLxro8FJRD_8_VMzE
z&^o?OrMYi@0FFq^;<3I?-YjA6Njp9P#+;A#f>Qszux`iASK2<qE~`4r&_SaU5_B|v
z0N5YJO7i`{<})A`^KKAVTShna>rz*jF8i?q@I+_kZ&q^nse7YBbjy(IKL>0;O0vI?
z30#hxH+6OXVekV?t&!c!$A)tNZJ1*h>+F6$D;N~R<t!&WYXmD!AE@{t@s_f@o^C-s
z*7iH836Ub%lN5dfV0V(DPZn67$ndV}ZdMi@BnJ<*adR;U6wvDkzmon`gX7JVzJ&gU
zGf;UE;<EKn6o#+pI;d)QZKjZD0L+k#Btno=n5@;qQEXy%(uO;tmD6>10;$2F0=R)D
zxB7d*cv|6<M~Cema@tX~?VhlUP>8yPO(>pc)(5kz%5jsx@C!`BYuX*^w`);P$E?m=
zEvon2rQAqOZvKuc99UtI8;3Ltz*bhJlG}7CE!yHFoa7^;h2u0LjeP8{qeh*l_isPY
zFR3hFDEWl73OKJx+K2Vridl-=bIzGQPx^-hP+klPq)vC>uxy_2$L-KznozqjqI%Lv
zJUBmGPX~rz&P|q$Ocs((J3*gYO*~F!_6;-ri)8yx2mmMW>|UylXVrQ#Ss22;UxM~^
z^5E!zWWqiLrsCa^%*X3F#priRi~#_->c*Cy0P%jp!q_q%mYE?wk)BF3#eN__2d&2o
zBaPs;1CK3+#-y|t3x_^q7ERw0@id-n3c%nJqEy)4K*07D50!E>_mIJuL?Z3)E}$N=
z`LV0bQym{l)mu-Os3$&V3ZW!_?*)7Pj<kn+N9V-2bJXu|v8BqZ;pL5fpboW|n|Abj
zC^P))pTHa)^{hMp6v|vTLAR9!OG%D*khpaE)qIM~9_<Q%?bQz!r)#~fu`3=YtCib+
zF#XO>5N2-k1*2j(-iZ#FTi0O(njZ}!b~PiJ_D9ruBA35pvT~#9loFqk#nM0E2euY`
z+D_IHe#r6!oW*$8vS#CRyau~Nj%dX7y>2)HwV(&{5iC~5*p{ft4ZT9#X`_V+t<KI@
zTmj*@olqTH+T`u{R8znI`-iV;{(oB-J4a|Y$2xlJW24LTddq>{v-C17EeqoOB+Gpe
zS30L@-*+it!hcJ^4UaG9K@G}6r2*BI$_COXg=lfu7`1`AIsW&y5E*W(9@-)+Io@RI
zg2?)BNo9m;KRgL}ZPfOFPkp(X(~Y<r+?tR1_sGW*c0`juMVnyH{LhZ!*wWcWa3_t^
zK@6NdXo!gnvxG9xJRh87_qYf}k@hC-Ia7X~(D27tOlBAhzSn4<o0ySewG%}aEqKlH
zN@o<e1_!E|+vk_=V8c7uWFfzxQgKS;CoBOK0uxEF_1Kc1B!f8y;g7bhM5t;sOfu1$
zTaNS9jwf^*=;Z?39@i6+4Qo8>ghkOqDED;bF(dGqmET|_K>mI|sh4JWiT;F!bimUc
z@x*62f>-Up$({YhrLUdY3CjIfmoP$#o$ptr_62*duTMA2-3<<l8s8r?tv>)#w>@Cq
z@=0f-p@!EK?3%Na9ni%I>$8=1xLAralGb2AXcdA<VF<f>4ksxbhP=;mR=TtrrkU^n
zeNE-^d3@?<x!E3}uER5m+l#r4P`gR2ZKR{jzZvS*b+W=7S}n#Y9m+&|t#zsUFty_9
z{6@Rv|1Z%^9FX+&`SRrN%L{MM7PL_R2`n-evd)~qLE5luTD7@ZDP!U{X`)ydFn6r?
z&EaC=h`fHgd*!tjb(G}s)Ln|6(Acb2^xw$#&^EU8(6c_C-%grth7C3e@0*fRKZhMg
z@4!LXgd1(a-awT?!7#E=bPL3?f+-!h{&X7Hf#<q(2CT#SZ*oI0m|qp|+Q(hVYxt`+
zw4QppeBu&$D9aVqvoa;>L^LK}u03L|GBq)2qPjPtSvtlDaCU%>S388sGWjf>+*k|O
zirJmtAWUr#*`3aBq!U-NG*+NXcsmDH<qsfLZ}iD9e*zlywl#_i(vR%;#1~`8V+}+s
z_h7M2r+^0o+n-;_R=K43ZD5WP${A(w9k%{zj86{q4HJ82k^wIB_)w#C>hAY<v#>gS
zcv}O#6ImjaKH*TMKx3h_R_kapEvf0MB$&Qt&q87pcSww*bqh?4bpT^ejmQEP^84F)
z16h4{x8_GDhef^Ft^lETQ@obW3?O#kPgA`touzoYD0V&F<)k9i#O|x!^%Jmi1p?Gr
z?GXwdnF3yX9R1{(4*9c90Rpvkc%sIC3mFNO4xquHV7I83gTVnC7$T-fPS;$t^q$7G
zuZ1B6nUwJdnwV=6OKRwhjwKWOcyB|S&kYK0Xd$)fX_cr`r&e@t6<zOkPxa!5l{Wi9
z;&ZYsV!2Ux=y(%Y=&w`Xk!7CI=;rGmI|>T=#wZv0mV@RAqB^eC)S0Ik8Wai>4MU!D
zfX0?-^71rJqt9qmCFsg<P3sQ}+c}6eU4ph2@SXxyx%cAr#zl7Joj_si(%>j9PyjNT
z1|4eD800-1^X#OTmLSDrnFqzHGm;TlQkVraGT{dOqRMe7=9_6rv`us@IWFjV(qfKu
z5)E`P=20keGDFD>5@i^+2vl*Ubaq3?SuS-E$yx)CdB0n%wIiIQGc>q^(54@+`@QsB
z=OF*K%(kq>_uHh_d$M9|4t(7=QDRf|3O4d@<FbqVpYHLSzH|M>tus#UQqUq)7rP=}
z(wE%U=wiVDs77#UKif|9`Fe8r?6oWHijWPl1J4id9^aa=GZ|3DL&RMcO$y}Tpt{oQ
zT_6>XRrTb$nZQNBLz0d1z3{(H%YYI_3e9Tna`#qAR*XrIbzM?x^Dwd_r8X(A2Dx_p
zZG&2}YDc2)P1s$n)i|*u7AtGbbr~FjUh+r+D1HI7v9M~)b>+yyAQ7<oGO17B1pLz~
zelsOO{DV_zHZk4Ngt5zD!y;eBnh~`TBilO~e}O=0`WV>2x2aCm!JK_?1$N0}Z*&C-
zd%J;RvbE4u4;F%qhOO9VI0#XP6?f2Z#AY(ghPox=v(rTXmH6EDcs}|Wzl9g_8%PDx
zH;@_T(lOS~P5GUCf@%}bu)cF+66K=WgA3gR57!rf!a<dgl`(k+sOge`A(PRCUE<j~
z@mLXcEF`_0Jv_bvmcA6~!1z?DRj(8(67ZffI=+5&56wtNg6jKh`5`KRv4k>!;6(bm
z*6(ITCnQXhFIg$M$%F&$7i@oQ85&8B#XG$Yq&rrFri%E_(UU~>z4}7$?~DmGuZ<xi
zE<edqmBks|Oo5Q+d+$pLzY*VfaRj_Sb(S%SpRZo2OLwffb+bO4<8Hqgb2q?c7iNV-
zi<Hnlc=C?<8r9o!*nXTJ{|I)Ow1@vz|9@x7@H7P&rN1-6U-acd<G@IGpls#*d-<Ji
z?aMH-(RoL7AuPcVKoZW1s+BcsHXA@ew}=Y(!kJo_pG5jc@oOj*%`n<alNq7mvnGqr
z*`8Lia{}CjyzhD8a8V_N!}tux7bVA2*}l-s{tsiJ1r5<rZ|{`!B|N?gO{#9lfE_O|
zV0?RXVr7X>VfN^?dZ88p1$TytVWSc^D5u)EQy<n!@1CKKTRiFW#IP@+h`R$j)&yJt
z&^gxwWb5DU=6N6FpDENZ?pV!DwWDHKxdlkD7{bSfR%N>u9YBrZgT!u^K#R);vnkW5
ztMy~YxCI4d3vhqB<Vh>uuCSfsS4q`I9K%OJ5)`Y(!Qrs9rcJ&<$cBB_(h>9xEQanJ
zbf>+T={+xA_hI-?UU$M@$Ay~SJr06^AgG6gzwm{_TkvlT-c&G%*UTE;*x~U8Q!#0b
zF(&@i`F_^gAu8$3q{VjOi9{Vi&{T{kyS7wg2wh?bz3V$A_hz=IszOVsAWc@o^881%
zU9Ld3rk-BFxm%BFVcT4%%;(i+WrG3Ci+CA~yPa$?pJ%+c^8YPopNA;5=M&!w?{zCC
zZE&M#d6a1LS)oU`6EgL2kHDzJ_ZU0(!rxP_4)>2xF4uR^L5N95ynM1}=MjalV=Dl6
zA2|j#TIRG1a7%pdz+V-6J;OU1rw6&{L50=lcYv8Nug9@rmTYtfEv6ccKPyfRXx00G
zElV((sd1E4kXbStM<~rol*iGT&g~Z5Ta%AN5OB>U6&>v<0hq+A)(e3q1`vlZHH$zj
zT6G!Z$jpIXJZtz+`yB!Q5nez#cQl)XAQ~C>28TX-SfB1~`l`;yMf_o*i$`Gkzy_yM
z$iZm}WS37KFe5HijXnlG(Ljz9!l>j)Ow$`(tDsz`b2`f<KV3J*8-5TgH;38e#<XEO
zlF5#Oa|Rqoy`AI`kR|)Fg<Ljd$9;`DJZrOM^jP@Jj3<p}BM*7Gb)(2SMLy*qA22x8
zyo2(lwsyNKp__9+vmj`tGiNmZ;6?lGM>zWL3-C#z?eAh+Hy<X>bue08cnMzF2Mddm
zRYEy*Pu8+6WfDncs0sO;H-mH>Z-9X#<7Y*#Ve7a8Ou(J-(<edf|5s7{cpb$Ek3<c;
z0L?QTGA&C86t(H}pU7`m&ajX`&RXB(G4NWt65*Q*sy$WZsxerJX<R}>z<M<G8ll(6
z`t}sNC<Nm^Cgs8;K881f7N-Z5q69E0wJC;^?+SF0BP3d0LNI@w&=K<nyU0llY-=C)
zgZPl`?x1B&gW^R6z@m-QxmmYBF45Iv0XRdGu72EL7Ov+z>zD*sYfIV-YNWyst{q*7
z>`=fUSumMOoj)g2+-zLq>Me70lQ5LKNgb3f5|o2I$L1gp3_TuGXY#Y0_AMZXnA6qy
z5~QP8-NiTvvg8O}PuIz?tz%#OVABkuuIK)Ul;+H1HTJ6~f>Q-|nrl1lrp*7S9$<1$
zl0eA^j&rZ7qxfhF>9%RmnqNRvTW^S=_@J~c_G~$1Jk?zQg~!3?J=jq#8T*-C4}3Zl
z(Vo+yd^?)S`&XiXgpUrfy<DS}eUQpc@Tu^G%(A>+iGU+apIbESJ}wQm0&U4uBvnFS
zKU~3r-7<%rL&Ti>eVz(9aIoKmgbs(MB&tbXJrW^8n-WV-MK(byRz~M<<H_Pq_WQ;N
zr+J}y|NUk#%A4cu>@uVFvg>BM%B%D@6vgH?FaA=&**EZI$Uy9CKx0)X9!i*Wo*E-w
zHxUp`yarG>ntbMl=se%7p!x4i*0w0t;?@ZQ{<QLbF627!J>^O3`OA>h8c8;*6A&^i
z0lQ|u8ho$g!!;S?1P5G3CW|hSGe=*>;XP{_q6)pwP=(c8Mp+0WS#zMPU87u^X8D~h
z%DbW(k9Y2?66$n`dcpqs^YdXkwPHl^29ESB#m_*u<P;&2x2rloN2QbRROa##3b7K9
zz=j>#f;k{OJ^XhpKe6w-55dEaJOuZe%l%bu1XB(wCLxgJFaV>>#6upR)TtLTzaX4+
zteubwxmr9g*;hAOipsqFy?Pq#zWAmgC99D-5BGD$qa(5;Bn@}SoF?IKS=sb4%?GGc
zV@Ht(t(A(RX`BeZ&)v3<8T=pJ&uLAEA6)6R^c0hF!tB4zcZ|1fS}P5g%P&)&XwkGy
zN{}))5BlVe*JkoqPy8TWsscXd>o>g}Uk4mBg(e`0Ng`wTpo(MZP=kUjwTy$AC!s4e
zCS^&<5-e$Lf93HnL{yq6t-|=>DBbS(M@$lvtkeYbw5x<kA7kDcd<(0$TcfHIg$s`_
zp~~CT5Ua7F2^#S81sDnshL&2aGo^oW{lfW~nIjz{{f4wt=}IOk39XHBX{FN6<PHqm
z2XocwWR+P(@}nvgORNGmPb@i~KD>Bq10`|JP1OGWlmZ2x>F>FF!iH!*gmI6TSAxni
zcNOi(8#aB5!Ni@fH|g;x$kh4smE@Zz&llJM`~(9ZU<Yc~Yr$iA8b4Q2H<@`}bP4<1
zK@sZ2>RB^iFM2-)jE!#kUrj`)@xZ(cK41s@1Qcl6cAQgRA5^(yT$UPa2aT;otOq~T
z@lq%}bwzI&0`-NKlIsMw{e=5da_~rbn<J;|%Ay;W{Typo`tJ8~ivQc9C<9J70CaB+
zL|vYk_*w$fzl2P5m~HoB>OmVGkgCNC8YwWvww)DZ<<u2@Pjn3!s%0LQe^_3H&>Yzq
z6>5aQKLes1`=#mSV=Z?y!{{hTRWMRGS+jQh11boN`bS|&!*g|M#c~RsdB0@I1bTRq
z&j_=9hxp}^*&C`gtS;$Gn28&-KmE=FU<0NquGcPUz+9gs=ph8KuvHrNq(ps1%S%N(
z(K@;mZ}sK$L?jK^-7+0?Mq0S5(s@m##6JFM5r#I}7N+A;DWVLB(@KrR_YRs!3jEMG
z<RwL&)87lgDQnGd-3SY+3H|tSv*C}+7*TqtLMmejTMK8|tL)&Et$M%3_<@R=Q;)zg
zVmzNOa0czYUY7uwoCH3@Pj6GZKJO+wgtu>T)-<6^S^sBxvNe9s^qI9)b|d<A^&*0w
z#p0U&^`;__RccZR-L|j(e>+v}v6u^Bi0sK@&lnL}>b1OIt~rM1c{2`JD_OgK=f{CY
zBW`kPMmI%(GboMVCx9Yr^u_V_12RsxfT+5_+TADpup;y?-}}O%>GW3@g1!!5-He9!
zE+1k?Nz-XR%Fd$3Z<|w1!-L_uV_JdsRuwt(pSQk1ll~3}epKzk7r8pSVC{XQNhhUN
zNRvWBPzRG&^<1M0r@NLYTY@ryY0Sea%(e)YbDj8=G@Nu7rQGkRE1L4!+UW+^ng!R(
zSPKbXjF4>gHt))WzdJVfkFvM3dIgkdnnF(=h?SQr2XE?WOyugzgf6{op6S=cHgPPq
z&`LdN9S)8;Zgi~s{RT^u`kag+B;lu@j^RIW=a!e3GmUlN*TgVY6CIn=AAcq8>ej2v
z*~y&z=B{sgr?PRfEvTF9GKZ+jO<b+xLtaW~fnc`ZWw2}_MB4p02J!p04EQBJ0MA*u
z@TbOte=md(FT(fV-#!Ttw9?1@C<Ou016Qn<M4s$gI|~B>icpZ51^4wlXOH2z?i4)>
zk(;x>7{a@hzx|&9)fv|uwL4~EWms=Vp8KBoueLg1ocDgK@<aD3mey;Sn9y_mgz%_^
zUM-RZL|Gfv_qf&xy{f!wNe78al2aNKsJ9Ipyg8m<TVGt2=lyY`Kk5#!CbpNJ1+qR9
zWKUfl1>H5re%%Y1_QB!iIswrcX~WXZ*n;8$XG;~A&X%B7M{W1NEmPB;z`c`s?5w#k
zaK0w!1S+l*f@0IUzWuX8N8_a<x!47lM_nxsv#{~at^!a-{D2Eou0q6-*X$lk=lL0L
zVr3lKCMk^n)^Z??tt$Pu+*MZfCiyIrrd<N*y6&{Nb^RvmUb+{|Q)U#o=TAbIS(Q!E
z+7)s~9XTA8LrtYHvK?<03&F`zfaHGx{P)X$Mu|_DIuxt{{)%T6`UK)?y(fn~;_Y;x
zY(wL~-Lafl)(1MbVt`@zpuAD1H61<AwuAFC^{3Ox@AF#K1L;U<L`j^8!<km^tNktW
zy(9h>>yvuiV`qP3gAV?-$>9m0fBUScBmAESGWsum6rbPyWq{LI|Gp944||3VU>dW(
zNISizM_>!w{k$>G&tC`o@-z>nL1v#$P6Chpn)}n(<{T5`w^0?-fJ$x>Z{rX&6r32%
zwDi~_26X-8d*$r0x+kdv0IlsEkXaC`mCzkR;z&Vj>;OGUJ?9R+S?i2u2|aD2v1B2Y
zX$YY*qQqoU5cDJrA|)<&&f5q#?+MP@1mVP)gEXQ^>a%V=!e`vj?s!Nq0Gh$CM~Q4y
zd$x^}x|K;Y=<Bn92p(D?7C6QN={Y>qfuIoYBva8H(HBiiBk#Q;D-5n>2f%MSJd{f6
zXZ5RmUnaM1p+SjmVw~BoNTq~VW=r&(xON}&7}c?I>@L4AB1<3@C~~TGYpDYO^*}6l
z=uYA_J&sC)^P*SJ3k&8qOabDWbbC??NL2zQaDUYc#d)GnyV~wx1Z2<i#s#^_cThOv
z<{&+;D2MYuk_;m$XJ5R_b^`A-Ox3c`{7jr12U=W2)2TP&?dpwkW?6q3xW-yP0k#D5
zM}wj|*U!66D1Eiv1Dl_58(|R+P5n8dEO6>HsT=Fg2tRh54QAU9%q!v!yp0R;A<JO%
z5%o9rA+<KP*6N96dH&$;*SLOYOj50>4nHY|XL%rUleLp96#2?9J%9cU(LLec9U`#r
z=t7u}Tmf3ekH4Pu9(GX_USSfj8P3{iYk^Q5uuqJ;v>;MyMT%<Q056-H#%MNOtqr_s
z-aC>owz)cf1Ag7y1RJw;`}#oQWD<VK&X&a!y~bE{oTf!JR)3ILP5j5bN<Z^o)p3SV
z1iK)P7T<npS$xxWR~OdGry+sxFMl`F43_bKez6EEw2>W~2-Bp46OCrmYi_D2hFd4p
z{Tz}-GY9E+sePG{@T!=KzXttsCqP=Agfp5l+#GT<oeU9s=bn8*c-trzCyGH{e<+C3
zUp9XpeSf#Mb0*xFvncpIeCFJTRgrWVvCz<s+*KTx>FJO8h~Ji{-a!o=G04uyb3JU3
z+qU`Gr*f}mc(ZvY=tIoWU}R#7USWC=UFNNx*htBKW|qjd7iF^pwPcIi2ev4=I;YLS
zFVtFu7ubr$aTF3=;*&yyQkJY+WF|5<a}~W`$6KY^8yYi}D&rf#?7B5Q@k8S0%x((^
z3UTC5o3Fa_+$x8EF{wSyL0Ng#{X27p!`)Z{BL3KWATf~pPO#Ku5H&{7pFF0CHTRDs
z=L!52%rIDuHCPXBQD9?W+<(&Q^Vv(}47qbDwSF_2blRJcP&4w<(CCn{I`eJfAA={g
zYG~oAKP%!+@ghoG4F^7^27ml~TAqH$r7x0x#GFR#klpCO<k&$!BG-JPTLDvcM#$=7
zF<Fr6Alo+0A&bKuyA<9hFp<YQS`;AOqX40-I+h9M{_3`J9Dtd?SCh@~)5mf%Cxx<s
znVo~`xE-M`Ngm-8l7LRmy#UwtFk~|fX?AU!HJMm@j1LB<tU~+DoUGF*eB~{iG4fck
zbchFf^k#r}%DL}iouz!Q2LRScHsZ@#DvF6AkLO*iQgig5El!>W#3foVHPy6gEhjSg
z%AawHZ_$E7I?5Ii0u}-8jKp5F{69N3g0i*>@PASGlI09iNT-$3OYSp^mDNoC>gby|
zk?Y)*2RU&ec#dbJf1IPcq>Bm^f6j{cV^=DJF0^KY$3xsLFqcEwgF@zdGtqKRj`*0a
z;OFuU+!|tY+VvL_UU32uD=UFMyKzHr#nY9{4PnSQp#inM<W|*DOIZq(FC;EfVpG=o
zj!^L?e84KZxZe`(v2;<{jgLN$LCS0#*n!9Q_4QvEUrJ)rv-v3^ezVqkLuH%2^i2@_
zmUem-Kt)?)><~F{?!oSEEoCZ1as3+xmEMvV0bq*w<N{3kUP@Sq{y~To(ft{`w$lNG
zBBndP0)vYLzNN?wtoj@|O8<WU<^U}uM*<+F7?ce&hc=K>BB9uWqK|C^Bs^ox3mLQG
z%}klg@zjv4Cd>3uaPd@;5)82il(jWODT8>U$qQt*p)u1DJw6hkgaz;rLEW4ckQFj?
zY?_4(V%Hp4!jIxEfk3lIF^o%5R1A=KL5!liy`fl{Me^t^bNLJn%;y8bx7!5FO#5rp
zdC=)fxZLf=#7tjM?0%j<kxcoNoOJ1n7yCaw5P>7Fg_jar&+Ku;U3>%{%Q$w#i1Qx`
z{rnSb3OcjLWi&)I`~k{PaiXL7vx&Ca1|Ksbi9?7)iKE)Tt4&v1{5I>J<LWq+kr5vS
z)eFJM1LKG{tNzuE!8^4nDNF?4(AQk-(?U&g1+At!T2IkPLbswqU0*I)N{=&DoNQ5i
zLm)fCPJtR+`w+V(HKQnVFrEly-wqaj6fI~Hy^q!ycQ{0|59w{6{9ErPL2|PJGFcR6
zotxeYX@7&1LN!?uJY(m?op@Z))lC+h;-L<HHDp^>ksYi!kBi1QNQaPxzm`rWgnErW
z&p>OBYLT66_jIooKhYuoJ|>I1To)k<P!O_9?3Wbmr>rjc6EB<GxC4=qhkt;5?ce75
zFK*4_0v=?0hbmMzJ88LKbgE)-bQS_2ue9fivJ9{SvLxvbQ(7tb84x0^J991VH5T%*
zH3FqnNU2n!DP1T~<?zAL+JZ@DSYUh*y++{<{B*$01Tt>|N95A5KJv&7Q?UL}UGS&a
zUsmOBf>%hF%@k!bLHwZ(LHPCkzm_`2!J6)22LuTR2Jye?_89lOJ*0T&ET!vA9923f
zptL3hMs`R+X-+}MRq>2()knaaZgG=CuMBWJ&JX>^EA6TRYVLyDqnWNBP3~@O&L|el
zNgiE+#tqG<#{B<aMzv4oKp11HMI+@OH4oPIp=P6j3DJu&?-n1FC^^owRLAXBNrnXc
zLqkNpDrDN|yp#)1HP!6|!kS|Zy%yNg?GaR@NJ%)D!}8duOixKU4V;ffaJ1%ef{L_s
zs+9E-Fff*s)4}aQa}ajlpJ;JK%wEqjHXLp_s3)y*pEc0pt;a1j_z0(w*kv7}7{7Vo
z?Xbtoc35G{sS^yR*dq?VA-%~@euJYSwo3F{<Y!El2{wb1kEYI#SdD#vG&o5CWFq;_
zR~Zd&;X8%{z?ZK(k>g{ArcL%4k^TXmsQ2Y=+^eTbUOC=>PH$K~G%%rm*aJEzIVH&+
z+Nd5UySu#Zk$`McSh0-oHLd<HkPa*)F(1A$7{lNZ^kpQ>LNGv9v&P^&KllpO%pNVD
zxsDm78pn3yJtHl_p`sD(`ZA^mf~GLhOz;&h*MZ&VQ9~XtY$SVyUV2oik0eWSW7K=M
z@t1yaUo;ljxaTZ!(9L7|*>m(LQ`twi9$?<Bb={DMv`}MeL3ox5z6FQGhi)39$sVs~
zU!d+?85Er%Zq18-s5sRVH0wVFy6_wVty)^AK!8Zb8!>(nRLKU@utw%rZQE?4{XE9Z
zY}EhuS^yBS-orB~>eerXNOlPuMcYk{f<6~57E2cF*na{H$b5GuvWB5g`T<4fIRHQi
zMe>?ge1}JZX{UQq>+w-o-t9X_>Uy+#uH$gfuG9OjX{6oZk+b_?TZHNYSOIq(XQ(-d
zv%j;@PI`eGE@}nOR$IPwq{McNQX?}jiZisk#iJA*d$Jyed1;e2G)kZu-RvBS4cjb|
z`DG0V`}qn#q_063jXV|o^MJnZ7s3EzzL2r2G@f78N4frR)YK=!+D*y4A0`oA7-YbW
zatGvXTmXns{H}FSA_r(_Kc<;~9ga9@wHEjMl?!<r!q^qRSG)WEi%Qsqs=x|w^~3z-
zZ>@j71a=Rg9el|vFF!zCq6aa`4F?~~2^nO%o%sQ<5(4;Rp6K=LykuS$djslx!-o0g
zLN_YRe(ub8?Mv+%Y$>x^d&bAdLg@UgC$lYrvJx~kF$E+pZW%k(;JDaON>rAq!6cQX
zp^%pXSwpo-tuGxxvbG`a*hp*$Rx<g4vOOC6^y$H}-@YrC(B)7GeLpQ7$I=P8o)x5V
z=#*17LNxc%2s%!jatreOu26l>jcWCg>WVn3OOvrYx)i+OcCrz}F#&9G14TUtH}X=8
z;*4m!Dps)EP|o^Jz2XQ^r22|wR_xlz{^xGa!!iL5c*rZ*A^0ngNhZu{EDLoPPrNrX
zJDV(V^I>v3rCUkw7I!q2W0K+RHyc-l+XtJ@cmfM7Uka`Em}C^Wp(NxY_79bdKHLd(
zYy=L5?DAB*q`UM*@ivRLsl+tB8e!4q$e4<Ha;5lM*~r%v1FdK-kkkX;R{U@*3X(D$
z+S7<_n&hM^kexso>=ftDfDsim7cvUmd0sqs^*V-Nwe%Ww*zKjYos=s_n8IRm?%e3N
zeR<$9HA~fh=Y|6YF?@5D?gEk`aNCUKR3GOIoVEeah$eOCg!nR#C3MC&ifQVfeE|!j
zEf$?B(rOm0f6g{F_KN-4Gr)y0?iZLABSU#mK-D6EVufpYb(y8#EJFcEhzXOK0+U<z
zE-sUk9!n@>TS+VdMbTP{`P#wFX<^^76kxESTs(w5rpRcRH9&8M9L%Oa`a{zZ)QM~0
zMuk+cFt=#5t=v`U_uYZ%nD)0!4{c>Bw-z-w{31ORSj%cH(hW-F?eZl*dCh)g%=%pj
zfk(>vAglG^)Lrv4{63AO89b7@RK&2IkSo4s!0?Lo%0=83jv{>*t*J-PV!idwYo5w<
z{Rmh`;^{Kc%jyUSn}ckl3dmMD`Ts5JdOlCxY<lfTMC^{p{IlF8Z_U<$N%egB&5}Jw
z{jVnNNY-3#%BcY~%&wqpPE+Y;ph>l(bp~|dw%-@4aAjo*3yX{)NKH{RWWb4l^D>fA
z{N?02dP3UQq+2Lu)V!dCpw&mr!1#}+@u-sU<sSlvB-j4*Byi9ZSvS}v<1!T$8sR4t
zyPsP|=jB)O%ZCnjh0DU@+qMMuvx@NI%1VA<gj#XqrIX=EWIm#7%%rvxfLm+4redlg
zW5bd^_H$BXih@fnG}*jxIF0XxSdIdnyNqr?8<CvzzG3_W5atPK74YppHJ)`2G&%ZP
z9k9A6G$YEupqkNO1!&E)+BW`qw-}cK2V&m5TmV_IFR)r_zV+Y2W>6ZxNVU**0JhJ6
z9|4!`;bzBW?NY&8K+~!+^gv|&ZOVcrlqRV)E#P-WxMaSZYCgGCQm!itNUbtW9==^$
zyG9`o-XLp;JN+XfT%oLj772A|78BLzpWtu(lC$hzrR3gh%qbM=w*Jv`!Ya-9RZ$Zn
z!cu)@Ux{uf;-u>%w;_xgfMJ;PMY9ek`TC7`rY&o=3Sm>6e14}TDz62<al_lU7=*tH
zaEj}0hG^o(D1iLX*Vilg@c31R^$c{`c7UW0*-D=^=PB{iR?tTDWG!%4KbV$feNO&o
z!POeD0gW`V|3(ypzeAmvun1|2v>+Stp~jGJ1&{=?4Uo%AA5$KHQRFyq$7fP_@8-2O
z@?CfA$(yY+)tg93VhyyNHOeRTCa%Nu`fClbfprgQ0Y4H#?-0O1$t5)ASJ1bX=p(lt
zVy!<MF4y?cZm`risEYj3v<Yc?tPUin6FaQMHRV7gn8SOyX+C0|wmjybSmz&MC4Jm;
zT-ETFhCam5Ah*IlE7C<Pq6u1brBehNu^b;t+BTH2tW;}FhXB_gW{EgJpc?bIUtY~G
zi<je~O5l;3TP(N2ZNqjJLFx*626%Yc<t(WG9PRwLQ^0Tkkn8jQOqh(YH@CQhq~jPl
zcg0*(lvBqEAe(#yzLT=|=E|*GgFT?k_+gQvOFio37%I{82YZZ-K?n=OCxxIH;|eoh
zNC`ByQ>KkZJrh+y7L7lYq*C;awGfNnnfd20*;q<7UYdOOU=Q(Ohc91t@J#Kg4Efbt
zM1B>O#VW}f*-fO>xP8bk!|==NJ7?T4`}884Z^@l99uetRf0MzQ_=S;)i0Wi3Eo>$L
z)J!OC<u#ViFCSFIcdmB`2dpLuoBtvEYpkvIKD$jVpznSJyv#=tF^MhO(C!_NY?d&^
z%Wua>CHx<CUOKJDgWCQDX^i)TV*?q0IJ(t0MpcAjxZ<9~`W87+s&PQPyO``0aAh4f
z=-r<!zu5czJ=2$UxvGQV1^zhpJCxTpimiNsT``l#_Y7(%u%tDdrl6!u3i?*M2-Ot=
zGvkkZq4$iBvF%v$yfNP;VW{L1woqHXe#Vl8*Qm;uhC72HSJz;i@l*SlE=RRMq8Aw`
z({NxsR|fwM+zQVGojCoN`=^L&6<@6wD@08%S(=c3QYz`<!0e`huoh94HL7cn5X)U%
zHqs^;zVN~lHAje}^Ae0~P<?-H0hCpDjrCQPdRro+?%tRQ0Q-;9+@Mh39sn~jz^M>X
z)4};qV+>`WI#OWO(>w>DEI#qD{}O3?bAHSoHV)4bMbCcUnnuC3@$L?=MaXbktSjP<
z8ZdiRu}{QFJbTI%FXrd#5D}a}5NxNSIK7}0&SKM|5rf83O@4{?!Sj}ZnIaimG(bqV
z_@<z}5p6m(ve`=0DX5EvczfD-lyo(=t^HNTkvr)narhmN-=y!}<FxuC3^ys>wPG^)
zLcNoL`i_pZ@u0+VA*jM$@J%KeCy89F+NIGLQlk!|m$VQI-xk5sX8~8}H@INkYZ^h8
zA_3^Q?p~Q;dY>BsosI8$Ul{#l!Xy!n`oK=sg{R#<hd;n8QrH2Em4xCr0zX~l{&V3y
zN(83#0n=77CHujeydU0wK?=csj^xM}l5YWzqt`;7zM@m<!PN{n_Qhd$3$^Cs;tK*N
zPxm+W>}j+XXd5FaLbgH9>tPj@O^l!+q9J6G1{0~IuM|rzhispgLTH>jMKOP644}`(
z(arWDa(N*#>>&q<VXb<_epnZ!_BMnp5W5b=H=YTzkV$O0%VI(k(B*W7R>xI@oVG|?
z=x${*sy$J0#f{Dn^Pz4L@e5$=@owR;Z5tUG-2sj{@qq0@D_#2<a8NTp02*@nb^EAV
zmE8UVWIGBgq-p@HUIYO2nh?Lw1ONTWWNTq>j0xwBI3Gb~(WvfD^hhHFm;|J+j%?z<
zwBzyV=C9MRb_<Zy=nK$2?q1~yC%Oym5-&ejlY4Zv92eVjqlt4vIr5Q)6vPLqsD~&q
z)<T1&^n-1t^RTf=e?>}wAtd?o(wemDQU(oDfaE(ES1Oh`3XNC_$t;FH5hXu35)B#^
zUv_A(d2&;H)j8bn*zehWfyJv-qkOgfeb#}o2RdgsRy~3(CmxE4g=1~_()8pfofU&{
z{lIsky`pd-%f<vsIJy;*&bn-RKk-eRGUGxc^S7>*o@*hc7i*eL$q2J=81<s7{0b@2
z6Z+4shjBv^Si=NnD4GtY3j&p-KNdU9EC2qMPHB#I?I0wm%x37NKlX&g$QXEbg84NC
zq|-%qss9cRR}3ppz9)jhUl)j0=9}#d#WMgnwnLU|(|*x2MhQO$%TMgnkMew|n3{@J
z(p_^J&`{uDf+Q)ikl?zx92RQwK5h*qpelZm>(^|e`XzA~j~@b}zweTXNSp=esIvgE
z?L8)itOf9;RWZqV1AnQhtLydJ+$)P$w9Rt(<3NL?k+_KW77F2%V0&@l8-8FfV8}1H
z1;^59FOzgwAmUhuwX%6W=kSGU{768Cpbjbo+Y^CQl&Gf~_nTev3&VbYU=A!n>&I<J
zuk*F*k1W51>9EA=*u?M`e?ux{4)PWi`Z=SrhMSHja6hF}hl1lGM@M0M3S0>4BDwp&
zzsJ!R?5=9sDGE5bRj?L2?gOUx$J?W+IqWaiuRrmBf9a#V)Ezls_uG~djx1)#Ywvwo
z+Q@(z?w{>i8+qGySl3n7)g}I>g~W_ytT_q``!zvwwm>27TjQ^!4>)?2ET?d25$Iv7
zy>F1-4~53lIVV_iVs_P__Y;K0aNrIL>C(irN=CIYa>HFHs2tD*%k=$jS_?AW-U>5U
zP$@UGr3&gM;uc$k9TayaMspnZkDZg*VzE#`DJ(41p$vkTPmmD;2|72EJm<*RVoP)C
zMGVPIgde@@(u%Ju8vIID-US!|B?G~>>{>q}Fz0V_1rJ92p1*c&JSYQrV5Y@o^O@(u
z9cPC9-=9lf1F*tU%m-uda&D1ZmA{1LLrOBnu&}Ic)wk~e!Coq3JMD{y`_WPnz8(-j
zmEiA0tg^dJ>ffr(5oZR?{+WPvgw+$KL$6h34Rhu8bCOk92nCKGzoAkk)<DMlMz~eZ
zlcD#p5hWLBryw~(y(Q{|Rc^%MGE8VYiNXbmnj2WFd>jmXa%zb?0<7t`_GoLi*s?gm
zV*#DP3D)>}Lk5EN6=Nwfg5oq56ehO#yn67>4vXN7mV3ZUbEdLD;XvM?O=n7Mw7PAi
zi<wx*rY>fvK`I2{NUzC3Pv=eo>i;$`OwgJ~_?Y1@8{pX}cndgxYZ+-(Mqt+I%BmQc
zHp!J~W8wn=I}!Tb{(k#XmVo6!n`#+w?`HIjAPmp%uG5$`q05iOzVWYV6zVRK6*5CE
z|EhHO!2}125w}z;!*q*2bB%U+1a}{!pbef;+vyBX@RX@ndX@{xHVc&wHeMquafW~Y
zuXv^$fo+8k(%2O<JvEV#?YGT+jfOC$w0Ij5EJ@)VCrnmmeruBQy)>GYMugFOxtrKD
zP3ny@pk-lMi-J=EeFIGM-jj*A&*c2h_d-?3{K(}pt2=Aa^qtww$$q)1vJF6i&*nfx
zXMP*be|9sH|Ku$IpPsot?f&xk3Iw95noW%sr479}sb*+yXGa5uLV7?dtRg0vt(55r
z5JxgE#BeF(@=>u$Zpys$48uB`(?#}AjTsz52#pC+gi$H9zcHq?K8oo_%*`W?4khqV
zp*wecps^Ot?N3-xd`Ku`e7rO@H;Q`O3pt${sT}D*CeH;5<N_6g3o#`N{q1MMKdp9$
z=7A<YW}FE>pO!bRGK2EgnAOShYj}H#ltO<j+1ZrQp?a%2x~m>f7oqB1XhQtK-cJ(F
zYk~gpQs^z8oNTA^!@3Y<-&!)D93IaqIE1I)+(G~>pIpK6?_$Tnj11}nk&O81R9lp#
zSwjdLn&$ZE=Cwz0UEjSg70A70k5<|Rt|;rB{)+QCt%~y5%`j#eNiWOFlA!YizLN?K
zrkW6B?JM@KLmLJP6FF`B)bv=TrLt5BU*ag{H2r}!LU+ejK}H)1H0ls=Nps7V=GmDn
z*j#^*UPO@f6ZFpsE87^|6m`M#W-Pp_$u<JVCUHDtSQCRi6J!O<u`5?!`UN=NM{V6u
zY*Xi~m^C*t`HZ$@8X~FZbiX3Lv}j2i^eRXFauQ1*siU;(>Dr(`OtfFAE8xZd3P89e
z#+}}_@c0SZm%$f7uqdbs8MAwi_A70T89<Xp*On0PpT&R9U1)MNIBEd&EC6rHeG!_D
zM^sZ=lbp<-REZiTWPZIZ9Xc4P5*XPkBX%ZcFe9HMW`-bQmI0El(y0Q4^6R5zYc`hg
zp*jsM8x9MMHb&(h?swzCSU4k#Z9f|YsD_GDbhY}1KW;1?uQAY!$!3MzN}^~K$6kx$
z>CTvZOu8fwf$GDxvc%Lqitx8IvlxmnV;L4~(jd_bx}2NcDwA%(*Fv&^8%r=MLJyL}
zks}+i=4tfh-&UOxCPA!!?b{_W6j89pABnJ)=s8d2%a#4zPTe8Tj^E(_%f7qhwBqS0
zE2hH#1Bj~X><0d9Zh!sn#fDsCH(NFlQbl~phmPaolQ<e32Ga+Bk1Vz*XtO}XX%hIV
z$Iz0Ik+GwW>3RV)Ml)$#<_(r%2&pZtzwl)#gtC{~ktu2%0<q0Go2;h;oiH!?qk^nM
z+?w9>6=Vk&2w@+_JAZgEqSA|&wr3FC!naq8m>Ps%e&!yA_pGK`P-NOF9l=3d3&}f{
zwxuWbO##6fMm%=o!(kON!n)wPB>5_?l5|P>=%V69cVi;QMND2J3nZNAvqZMoX{U};
z({e|VlcSOFt8_kHOIM~S<+qIdT>lX<Yv9ybR0TAbNrmKZz7{|qo#Le5?f(VBjBX+T
z&Ag#Xv{`Em>OZe`0JYlC12CwrZU=bpyh5_?2FuIJQKMMRBZXXvn0Rm1Fp&NJ)?2^3
z0=Qr$ugx>Q1Ubr46s8UY4AQifrZN8KusRJpJ1v?(GU;&?mAK^*>5M1R5okh#iFjYe
z=7#;=Jd0>Tem21<csMMU8uF0HDJ-He#_xh~(cf35{rzuukS7KeL-{%uLEs*f>s*NP
zAYZsi9inM8e<;&RaFXqzp)dwlDCGv@M#-PGT1*)7;DxIjbZcD^Y{fzgYS+jlH9+Z?
zodM)_E2=AKlv7$7V!Oy;3hX}Z$=yUhMqr5#kR=$7$CWgeL|Oopo*T>6HjU#y|G_LU
zy*Y%-%}!3jmLo|o#Z-ANa{Q@<ik7(5=aeI(bWvIwm;0-oncl~(TXTIIrn>+xQbT>i
zJ|m=8h?P58FqyX=gFvleD>rADS->0`FX>21MBY2n2%Q6h{UL8{TOYzwLu#m%6cIa2
zk`WVfygokbQd$ACbb=Pro^`4O<_XoHBSo_l76ft09{(w&<ipn`l7D-Sg=Uby^Jf{E
znp06kU=MDTxX(UEwg$b4mn2R`v}nw&J|P_>z0vE6CJM(wU7(c+V$tV0;I?O|q)DQh
z?G6aw1NfwkZaWkG{aWInMmcRMZ$|0f!~0&4k&)GS6{FCbCO#o;_}|w}w!h_9uHphZ
z=-j3LxfmtY0s(B6<@!M8QDF}t?Xs$}xp(6%#5y&I0vdAaP(BW99p@t~@AXhsbpfqk
z8!-N8Fbf2+Qcsx0469S4c61O|Q^#O~(LIXamTI9v>+v~*1=rB}I4xQ7&{8V6ne1a*
zRXLe0pycNWseKT%h9x2z73Bv;7&)sslBk?ek!S6KcCaHga0O4lrQ#T5a!8UPI|NAX
z32`QLgUsmQl+T9Q-6Tz|2n@&Lk&$X!)*GAnGpRlUGnbMC8ig`|s+qI^H)@GbyAgd1
ze|Hyl${RH3?$Q>ZsjaPsFrNwpMhPk(2LH4AK|M&s1Oyz$zEc2G%Hubs)OC-v>rmdM
zltlx<_3o66YL2)OFxK;kiYVI1DKc5t`QWFu;=b%y1~6}hSkT0-zE8sS&?BvlJ-8-F
zoi>E`eiI9gbo7B$RvkbB!W);@$YXmcRn-U@m0<8Oz=)|o^4((yQHYz_a3D9~@6h29
z^I)52(X$<|OK;Mk@72Ypa85lSbODJ?N-&}<Owx)%f?s*2J5!a>35#g3ZI6CC`lVk9
zG#US%?+rn;kGTPKidp+q($D%Tm<)j5cOy<Y<%&oPoPeW~s%qsl=3DM=pc?Lh1-1g2
z3V}x}&A*2p1|wnC6DS#f++QF0q=n;9N7lU?WLcD9Kv%zPmkk7vafM2ju$JReLn*5}
zeqWwU#LR0l$=_xG^0bMuXj@FJK~Vgy;j4Tqg{$(2DjvyJPchv2adcI~p>v$5jRHgW
zSv_aXk;vE7Gd#jwb$fmPr@gmotFl}FK<V!8ZjeSoX^=*`Yf{pRNFzw6bVxHPVbWa!
zQc9zAiZs&Q$R4c!wcdB_Z?F$GCmg{w=kttl=P%}z@n6!1BRxs@U3zNZ9P|5tQA-dz
z=w9Mr4UT4I%^B~^<n{C#$}>?6eUBu`uS?#)@LO?`Ib@XfiG+u~;o<?qdmVS6Ck+F|
z_%6%WxAA&NwNxEv<0?BKEOF5dyc2omcj2&pfO~u~uJ6#04dUD~X#N-E4!-{LuIb2t
zM1N(D#QU3&(=kbNTsb*Qd~)5q{<l-Tj*gH56GwV{3&AthED_C$>t!JuZ3H~F=l-A_
z+yP`m4InKujc6(nsF%-x_=?Q4Og_dM6VGWYsMIE2lZQ6FHby2wz{Qq?OODn;qu}V0
z7JdKSs2jW&Is@wfQl=KBe{FwSs5Jw(1w9MCq7<_(uj?rOU8i;yA!^8b?yNpcRpyM#
z*QuoZw3U@I7`m2<vJUoo=2?=8=8;l6KcK-B{MHeA#^BIZSdXZle*N(4Fp@P#<NfW$
z)UN#^hrx+OPu<_%>DNA*7pnkmPgBJ8qGj!$zAR{R7R2x9o0}W^M?)2E?TwO#cv2(P
zmy40T<MhY6x;up)tfiE%zi0x7ARW|(&zjch6j+ZlWFgC5v?*YF!U!uDbLK0D7WciV
zM$I=4HxuD<t`4i|DS08~Bain<nefG5bt2e&;MivP*F~mqcU+uA^uAtH0_&&D_9?*y
z-h7k4(7*9DAuSX%r;K|#bvd{qt<B58u~WRO=t??8p|y9azJ_0!$z@lFhDIQoRODG0
zYMS;D*1O<C<Wk!<N8$$X&-G2+Q&`dz6EZq!Sm-NG0{(*U@)MWxQN=Jjmsqm*2QJeI
zf2H4+q$6?pPh1&ASNDs#S7kuUx88quy5h+O4(ERx8nnUKu&}VyN70t5$0es|MQH5G
zCq*7Dj2}t9KDal^&^^HS)H7~$(%k3;7i}s-$Z<01r9>$}o)?_f+WAKMl~q=13Z<vH
zE+q8MZ#6RdoR-0vr4oL+*09*5=%O)s%@C#`hxXOYMB|P|5$fd%yI-7^MoPqIUO){g
zP5bQ<6P$1rG(&<Go6W6jn-R=~f$oi32T9CKu%RFOU4QOP!MmcZ8EVeT#=)xS3>o=i
z*IwwZLU^oJhh1J_)Sv|lwJDOWN1@sj`5z(ezLzjC)sh7wH>#+$6TzrAMpK26{$yS4
zI3<C+jTqw+c<2{E2Xkbp#!A7lrQqLlVNMNFpQQh{81lMoklv(!TC6~&W5V(W2U#){
z#efs@<oZC;6wqwd-m*^T3KQJcj9vkAloF%dA4WnI&M;!bdR##Z@}3<=FM+r$YbB)3
zY8<N%&zl2hj!FwH#xVJfkh)k-Ep&yhb%fc1L!&9Tab7-+Tidd*?{~9?!7HS&CJ2{d
zv8Pxb5r~&x3J?i=u>W{wn(L2%#l_5&g+wpegQKa_;W*}lg-w5QJ;>dx*j8>CSzEMv
zp3?spurwStb^y(!w60{_2q`+iA8_m(K=(F@@M&m@p@Fm_0s4L1g4oXrz<gK-sCEAB
z-zO5t^VGA19H%iK4NgXl>=<iJco?czS)_fyU|7ji+^gCM@UR2hdC}8tZmz*KE7dL2
zD+Q918oMbhKUb&aYsvLqHHJo@GG2eBd#jwH`Ua;lVWz`wz=c1a!<HYND<587Pp~<t
z=ZRh&n{>o;zjUj<LeeNAao!Shj9Ai7E8Ex7M_Cuo>N2n!xmZQeia&S^zT>H!M}rs|
z$7sCE^cl<W);+636D2M0d>N~Zt4=^k(vUx*hpFI8XP6n;&pOWGqEjRkNkfEptiHPf
zDt7}%ll}}cAjH+NL6WVhn5$G}0C8;dP}Nh2)_rr3`owsCkXrlSC(u~{g|0M{nt4Ht
z4u7?~fe7H_U^%Q<gPZBf%ZsmkCXVe|nCb)6z@}Q=ceQX`SbD8Vgvd7+u-tAF$iLZT
z{?=L~GT8h&WGPd+|4}715T9rtvoA~y8Hra%*`)|qro!f1SEoVfX0<&-sAcrT0a|f)
ze`Zf8Zy)Ym2n|`fa>A}pAP*)dq>`*VQmEP~@%b)C8r21LRe#!$?wJHH)vFoN;s)kX
z6edT33gPe6o>@ENMbTh9-!=&-^)ZFIM)D3+gX)HXGbU~yM=@e%Oy*PlGV`*fMi=4+
zmD~5P^|}U<SjR}p^8PcJddvV<YL=G=OW&UZ?iFDqT2we6^}Gw_t^1elKjQd?e1VU6
zy|UxA?`3__X?EkKREVa>8Z$qB<T-~WbGjY(k(Pn+#zxpsb4E@hr)B-eE<JBtg(Jbc
zeHX41L{);JQXhmW=uewEtEYrPHt@kk?tF*O=|q9g_dd#)SSr(`#DmdMX%53PdbCVa
z0ZB@1hyycI{nE9-Zv^MsHz6}UUviJkh7P7B7p~tBHuJKnbJp#bD9j`Nkx$o4M)m@#
zyMOlBYftVeLhc_^F&NNK1>;JTpx-u|1V?Z(>=z(in=}X+jz^hI!aW1BBc%kR|8zNM
z{-pnD@g7ZB{lR~tWkHAv%ldRjpQ+j}W$wK`Akn^k$&OkKq}t}SPJxwo8uOP~L9#^m
zV-WH*LBFpL@LrSF6xi8<N17~HbAEOU<sZYCv3(Rp)=y94E&46_13aMfp%tq^qFd}3
zXw3>)n8^B>^pZTBQ8EM6M2+9BGycjDssFAgH$pgBnb#xJHM2;Jix{_!?J5=HKctM=
z&-@*d=eB@@Shr&^18h9#bIF32C?a082*pqH7|B`=3E8NL1Gk3^5zvQ>RlP6*Wr<Rn
z;n~iVN`w6bi$XsBA01uY5u>E|rkBLl?!)E5XKw&d1YRFU#KheE;qaNqo*j#))ISyO
zQJbu-2kg=EtJ4GsbS^i%UN*yhR`X<R(Zo)FAig~mMUo-bQkNt_`Tq8D20N^;>u`hO
z?<)Kes2cRaYG3<Nbl`$aOSQMfR4DyDY&_UPxAgp*vId>gCmg!2uPp9l9JJ~edgz*P
zb;$UYbZ);cwu1V)G=>V9x-bTqZMVf1w@9FRUsmG-SRiP&G~}PYGd(|}Lf5hKu8Pk`
zkn^yCtm;V{Al|(1R6)Y6K%P?IFI@emXVeDf^F%@xU*UuRt4r<c;c{mumt(Sh1takc
zpd(hgw4dv_gKggC3A#|E-cJJ|hsFNfkEu<a#OV!B^rpuDX20o1hXJBL_UYEx!_4q^
zp@e5S|K1NqJVOJ(6`ui@pz|etSIrU=O$bA#&j4S<(=n`I!3cc(7d%=vnzqAWBWOwz
z4IQ!dx;lcK0~<cO%rQ_sPcf&N<h#|`Nv<w(QRrkob%b$na4Po{<Hv_vYkGZ^KKq(+
z9*pErBpAhKJVBwHY{83Xu2^UK24BVE6(98o`x<Ri0sT?+g9MkM9bD$`;D(XJG#*<&
z^Q(x)FQ<f@M;44;&3*75`EkoSXy2F9P01q>Y{>3bK!-jFNIRYPtzs2UQFVFS^7MPM
z;W)bI=jRR}@b3U^CvM6)vpZi@94ZaqlmX2Uam@!~UGqw%_(^lu#=K(#5ww%2sKMd+
z)TLb5@U8py4{3mHbaw<MSzczFjFbb^>i-5#dTD2!N2M$*E&3nv3hUaZo8PzT%kY0=
z;f6CJwHVq;IWCGgPCz%yfE|E#g-Oe}-4J_PH+>@oh|zjB7fK(gpXr^0#)8n`_(++F
z(wWei6*~^iAq7#AiqgMNQ={2Oalr&#a}D>WExV6N*UxXNj9xM=YS3F3d0Z_*-#3lQ
zK9OQqbuBUx!zFBXR9RmtSK;n8Eb*Z*sgSvQIN!>w=)83rtK@lvx~Lx*YI=PEYkZn=
zNMnG&RBsa}GYeuMWqol-&@`O`z8_FRc8}Eq)zP`f^hSlOrUeb<zEvZB4fp3P@%{RV
zl0D0dFl<Wo;&6hu!i4{w7$F5<Sfk|4BV&@>Ej(#jti7!YaIOmPG)R~#ghkR5EjX{_
z2i9s9I7#Scv(!=ScGWu0R5}2SlpU~KWT#BGK`gE7Z>$5($mc+8u#8?d%x(w|nQ20b
zj8mY#eOpn*Dv*Jpuwg9EFOY|9L0+-zrw^+6?>04bs{y(o;{;;wN$I`^iP}wpz?Zz<
z15#=G*s3Z<c{Yhw4>7SEPzKplQY=Fwd`2G3aufdV4O?{8UUD4W-B&9TRrJ>mEF1cI
z1If(6mb<(gMn5kf2c^!XkJJz&peS$y5Hj`qS2GOdXvz1N!2Gy`T)?(Og{NJo%3Vl-
zD|#-gB1-0&fY&ZUf?kbS>P33_IGBX}{nMv!M%4~HRmED|(EmGB36c~@n6d-3itN`w
zr(ak}l-Sr6$kA_pgYz%TwihXaPvR2rp(`uZb0686%qv4F1%`y?6$Ujj_u!$}P_n4$
z^~{dSrb2;*o8}|x1onElW9K#XLva)PXde`kfF^9^-adkWs*a<5QtkCxq>Yn|@``nq
zko<`UzV`bbormV2BSuG>q)c86moqomr3Gttb76eJ3SY#!to>=xOh!cYS}(IrJa2CF
zH1*AG`7=xO;W7Vwyt7~JzGXlMP!B-b)yi^J8*LU^<8{uxkA6!xxGag?r-PNjgXBde
zl1LP6X*7Eeea@g;0HYIO5V22V47nFOfCk}2_6j~lK86mtTU#ecT8=~$Ph&_!F)x`J
zLWo6dD9;!4q0h2L5sp(D0bRu!-~TK1U~AQwuv_M6;j32PTD<dTx=sA)<hHG^mlsM8
z-;7>Im>>+SYu0=l>J90Qx>SMi9C9)6%d{!@j1pc#0R*7?qWKjVXz$lo;jDD(V4(ze
zS@4p9Ul1vKdwWY4mjg`jyK|~c|K;HuWEGmX26rB}+8ktr1cCEkzI#m~T~QIeQc_Yn
z0Sfc+fByV=3$~t9mBainmRKU%1aEKew_s*e3!)}C(=S@@(X2@ng^6|Itj=FO6PzCl
zsmP+sy%a;2B=tap!~ZQ3!pN_J1X&WmjBApuZ4Sb|Cb3<*+VgKjllp}wsm!>dSi~H}
za!mz;caGQRUTD;LMXhWqfn>-_ja)SkzjPyx5T#^ui|nlnwhVJEZm)oTu2+lKv1JPw
z>v|ur$}3oV*t9}}=zPIQVgrDBIDcXxUW!q%9+1PJp+gD#lWxE0=e=hlBcX0`dC&YM
zfa7MsFz8+u!Dxiy#GL7$htpLJ_xF1MXpkQSfUc~2(~=Kmf|xQsK5;3=Q%D>U?;R3-
zNFV}nA4UI@S!b7*O3)ux@Af!2Ig^Bti+&7_jj?80fj?${g))dij8@h9lw+5`Ce&~a
zC%C_zKzdWW1@NGvFhu1qoZPwF(#5-rTa}UMd_q2!v(&{Oeb|wLl-d!(Z%JRVGThm?
zqeJr5i7t{A8Ss=?5sWTP)GO0;b22{u_SF9{nmQelVmvmYeT(6XMZa-H-7D(UNf-TS
z1J>d&#WC1i2K$ER0VnewMEb&dhvklT7u=B0no18p4U-iKmXPZ0ckHU@?-yl>k3(;V
zL9}9+7$3iI`t{`+et%c?ng{Q{ho#E`34XnDePiSN@Mpnyd!p2DIALTiO-IYfqxnfx
zid;4Va?;^j7T6R*4#~hgoY|eSJeG<wAQ#@)%HF=zq|?7W3kcN$rwi6le%Yd;x1N*U
zvVqWYHUHoh`8O~MeBOxXZ}PrWV_7%7A|~XH#`)m?B-K_=5u(<New!+7ydL=mZ}LDv
zi76z>kL$FBpxdRnwVJ6Vg!vCs(4d=}Asa#{Vd7w~4C*+kazXQz7x{j}0f!3Rg{0W0
z;^N{#0BcLVc&rRz@(^OXhumkLu?Wl1lkS@4FW4OKd@U?3zoOuM%MuYNqdQ1%4k)P%
z+0L4;vHEUaTU%?!#=!v_3$TB@GXHmT3Zgz#>Kj4km{?g~*^UJ~7&k3J@sJaOWyYQ?
zO0!4g*?vGk%!NvjHp-Sj#oTw8wnj2ZH9|F0R)%dIu-1P83u?IzKp{E-h^$26rFVqH
z4KO<7^iTv+NzLT&#PMOZQ%Kb=G~lE=?E^kHrWTvU)1<!6nmMQ@(heSJIq_(apsVG?
zSvD)gXD|ObJ`2Z72{UG1s**-5`Xl1*-)gaHB0J+`Oi-I@WK7D_AR+Zsk*aR3jX`Pq
zNaz9KtUxuQ1h7ReY#tsRO$F`k=Wm#S7jNA64uKV`DG4d*5Ku<e$N}wKMTBZ_E5R+<
zCBx1*1r3SZ)2vtOd5zuT-FD$2?qUK0rv*VlL3;hP>z!QxJepw5c5A&^AQL>Vo-KBs
z1llUC1Q>=yEwVkb<5#IOxSolTA8MhrdvYMC_+Q0(TsATipzHM{CKBw38B9od)&U~G
z0O;2T<0Nh(h$tVO_<ElUI?ZYvzO$>Rg#~(dJ#X1Fz<wWz38DV*WDn*f7hjmDwwwKC
zynS@ghdty$m8T6U35`Kx(WU<j9!~I1aLq@I=*7Ad_?2$g*p%GElL9G3z5+$|vDR3w
zrcFL6oh}MbfKeU-RghW7L)YzO!y{-nNx#yhbXt5T?g&8>B}G?HFLiI?GY`H4M;dM%
zpUff+!Km4#O77O8OfKov2GJ!@4#^n6XMEvT2No#mKs73EwUh4OXX1*jp{GaE4oDyh
zV47(Bfjex__H(k~cBKt#Tt9942TKCER4w^DULuz!r-jBRQ8Fdu>j1bS3mKX+CA#H|
z;W25J^7sy>7yUr%TT8?blqdrf?mgIMw~+d$Jioe0wt_6lvuTuSh$$?Mi<qg_9nvLO
zLn;n@)y2-xjZ<YHDo<?Fl22advrolWW4#t0`Al#jhSQq0o`W8~#YKe|nSveG1ZC2?
zFl=y12^HbsFnWCghfEkW?R&n%%=$8iYo^>#)_Mx~{oNmA!m1JHH4R5{CCy`L#Em@u
zjLWm8DsGTdGgD5!mWo5HG{+>)*l}<e9zwJ~uX1@1%T7rVs?N)!OL)-wPuBU*6?*Xm
z0F6lrB>!HmeXh4WwgwfJyCcNODeJGnEQXXY&qd0h%A6}hdy8RzQrD&U-`O>-TmQiy
zE${w}3u$_@Nl~Npq3(qPx$p!qqk_iJ5?yP2meLG!``Jc2U8XSR9Z@0Xqw&t}gL(va
z8)WOLB0XeEXoNq+<m%9el?$Oaw9bmeL-yN8m=OJ4*+;IP;Xd7lq!Pamt!r@aAj@KZ
zBGBA0|FG=lW=<O!*s)cJPod+bip?(Tyr7<D$x-+!R$dR31n4M#gJCyw=fhuLhL|Ac
zz%tkn+hl^d-*G6FgkLkT(0gW`#G>|YiY!+0IhP4*dPuOU$l3>?PpxGRx55(KX8K0-
zoQJ@(sipqSN;fG6CT0?(ZL<^O-(#a09oVhLX-8QO8qePm_>Ag}c0YqKmXD6gp7x+s
ze2~N6uB{!tMo&j64Gy4%5zlDYt+*X$)FMB!5l?`r9Gy&AUS8fjv5^Oy7H04K-}~Ev
zpk|OO#lE>LwI)pM0K9L?z`#I`%z`n|t%r<G=bEdWSI9M0Yt}qks58Tm|KG&A(U@=L
zJP+O$3~-uO1Sd4r!BF?qPt^>9a@Swj0=zBqgS1qy*aqY@LMlziv3%tZ?><+t;(BA~
zTGR_`P<IAbD=RA}&ej<uf%+q<s^bRsC=j~=ATEmgXqF^;^BF;s<Cvy$&=Z-7&|z``
z#cQ;2>`MxU^=_Hc0=tlzaVHl?lE!Ja%^!BSF%d_5W1yND1W=3nT5y;2qoSiJ1?>C&
zub6o}RsnDM9Unbe0a?U%*iJx>zJ$ME(L<o_3uK14r%3!-fX%?FKa~{b`Si<iF{RDJ
z-+T5dWlq5ju%=a;Vwi&BXu^`Da<Sj;gEUoJUaso$>x-d-8#5{vnUn`tyzwUir0>Bd
zUl;qfvlo*?hmw{F<3=NXwO~ID9^T*)G!?-T!4(TAeS3JU@-_10T7%)kh^7eh7Keav
zcjvgWPWJ)oRKcKo)bXFY&(j(`VM^BbzCgx1^6t;lttJCZ3JprhDs~Eul(w1n&?Wq;
z;Zw>D1=TZ4Cif_{@3H{HADR!R^*a;>kjl^jzj1MnX(<MUcyWz|v@{TWQjUQb=ilI-
zS@M65&l-=SEwHmM{R^1cx9xz>fV|yb)QZ#EE<H%sAk~4yEg>&jmd=abqSqproLNNN
zpkdSeMUSC`MdJ#GLNJ2JsQNlk3dXJ*nUqia9jOm9nFXMNlYl#A9v_f05w-YAn2cQ9
z+Rkiu`Z-yUtr4m!>nRr#a)qQ-4Co3}@#6RxPY<m=Kb03~NJ5k1N6(ZCdV-+x$*=Pb
z41@5Zl}k*7W<?m!6e&d<xvk<@%)3&zBqla0wdU7zj<NF!l|e=mbG8Z{?i3@^>YwNP
z3;MAXLdyQYHn85`;(npsmlR({gJ1W&wIWJ9=&l^hU-|)HF`2*o2N!&{QcW12g3rv$
zss^%MGbFpW7R1%SM!^z?ud|xXYScB(VX?V}>Z#N0ANgn!abq2wcjBBC|0egf*C7Bb
z(gy<ZepjjX=gs26LXA{n45fGjYtNu5-tKg@(cDBC!-%66>_iHUU${9h6_2ddyPlpe
zx{Yau^AipC|CA|KuO>H`O0TkEYLfcW726CD5<4fU+1au?0JP{6kBoI171&K{O0d?>
zq)#0z{?kq~CNh%ymFc8;Tx`CSKhb5SG7J_HsXJ*?d{$dQKzO06{+Gy>m;xIOHSly4
zjUyfwWz8i#cC+|Bxh|R_TuWQp28lU-i(*+_GC@rUXetdFFSNRIR-l(-v*G-_t}5>T
zY%wiFl%PSEuVMk9(Q_mZZQgET<{)?75?{N{Ryjx#9`DehnST<D<TXMBz8=fLqxp}{
zHo`zJ+v}`1lJNXfz2(308)ecE3a0<|qPD}IX4*XVZ!mSVsu7{pI?#PO{ktT??)1TL
zj!g)q!QI56y#5N%m>I}|tj0OmyeKwk>F6*47w7kCXcZP*#sH5kkYFr%cZ7(|X83~{
zzr|RDXO>XBvF6ugHZ~HPQ`C#-bXT@SP7Z$M>Bx@>$LPnc@*|#7HTl1ILfVYl)~8aT
z{kX(IG<GgTqLg-(ubWp;7&OG*ZEGADiG%Di`R6Twzn=W=3f`!6rEANbqktU<QEs26
zv~uw9#I=&(kn_s{vck`T=M!PIU6!4}Cf~laA_{)M>+TpKa(Fo`SsAKT9@yI|aqTlW
zN-6ekwifhBk`Xv%ey?o*eH<_7_*IgVlTDgHB>y}yF@gKJu)f$*n>Zs1P3kxj$H8S8
z$E#a)g%QDMWbpt`oE0rp0K?AaS#LAY;$ok@0se)Fk8oX+I$P|}n&8P+5Z#3I8+F3s
zKiq5pOrW*4+~3sNPvqZYhRKZ}k~)B4uHD44GcBJBRivo3w2y<l*4BH`ChKlp{%7S(
z#GZ-CM^`tY)w18|cl#9%o)Bp79(y$6O{4qR>N7ywK+%DpCdnV<Xu@Ek?1zDAjcUjF
zv~ewHX-^s#To@e-w4SrCzAR<pi>p?-nKueeE9b}FBi)n}ir|^*B08;7bS+nlZv@dv
zLfrRa?`#RxQ+NVLH01E>KhY<+3k|~vo~jLuHf}e8Vt_H{UmgIe&f=1QvB_8SCre+U
z_l1=NRljKx4(Oj4;fmohj{4Dk7**1B865MdOb~f@4J4OrTwVFt^I(G<2F7sw2-f-#
z2t7WRtrY;5<y5{&Pk#%hCMSTFFykEKfs$-NCv4&U<$5!dy{eoAWzWk%e;diZ-fW({
zUz<|&ZJ{41^ELnrtAFs%Ykw)9d_o&FkK?k^#i#MkbnhUDa*d1NQA4^Iky98hbgYo~
zC`)LS>^GJii!nG?79z*R*p_Gccp08&bs+kZ+!D`FAZ0X~y8$5G_#ZIaLwCZq{-5)Z
zg4nkSa3)E5Rc6^@*8TA>X}o^J4~`<Z76oNNHzO(t%Zw3C{d*d+jr)$gIRr4}TR2jW
z4cbwWPY7Q=rx)PoUqAaZ0if0X>~Yl3Sa{677&yw*?w5GLWcu8|Qu^&v;j+L>8E+&4
zyp<a|KL^XNvEhq#gskd#=xghr_=2)?VL68xgAl|7@4G8khK)R!%mqn=$*iU>s%nv4
zFAaJe+GlY@f}w|;cXOk)Z?8S*uyND)W-n2qS#<O?+#9AYtiT1u83qj7>Ly3Jvhsh!
zW3c90h@Kq;vZ4lDOeiuE5{{pUQBt(+Lz6yXaED_Ai&5PSjpO4Wwm@tMT$WA>C1{tC
z7qU1eA=JScC7`L8RKkWFYm@+Kf7axRQ1v%}e>0J*{!yDUk~Ak5hFD%>kXckz#4jmn
zUJ1n3IxglNYr!%v89!VoJ1eXF5H((V);A|M5<>K%3XRK`np-~9!XM&*er9b2SuSm_
zd|P+qTkzuJ55A*yfY?!Z4feq)9vlgNpa1vmI5XBWJSu4>W@bKn1mm(o4rTm_ql}5h
ztwqn~qx19gm5T7$sOE_al~s^6tn#YEO_k?9A7u=h$Q)BwP@^Vu(xLwHJ5|GIeDV7R
zyynQ+oAViSM<&eZ;~9prz0F+6M``y)*R>Zd9{WbM0hUj2s6^tYx%v&ub<3?vu!$3p
z<cUvybj$SEW$&88w@dGFe;*+Uu@BSz)TqG7SnxcXx8d+R&9{y|N3=FnzQro@&IwUb
z(Ik(<U++;{Gf%SP|E~@GPd6GMCbRnkD*FT&Vw?gxhLs02n(}R|hEoArm;;8qkL8k_
zcmXS!jLNKrOR1DSn}UvpD8}2J4<*FgUN{&8=l*OaKZvoR%SM6RkD{>G-zclJzm0di
zzwNiZ1Y>N&MB<J@6hhMgf6Kvx^B&)LQxs5Pt4d1;4i66IH-xw(KW_b}4Sdlz@{K&{
zBC1JBPt7A(;Y^ViIT>b?^9U+2FgVhF=}0GITJk*nI`KvFW#E3A+JU=HK4}7h(BzXx
zRRQ)aqw%hyhlj^EV7a4JKe6r-_&;&vY6#y5ii%6)l$DuzyA7^|<O_V<p@drU{119j
zghWRx_&F9=Qu1v>N@j6}KMzRcidTG7T9K${E%UAVqwJU(-e74Y)5lOqZ)tpj3akRK
z{sz!;u>(5z@*o!{@0n{%gLy?Ld0r=Pjr+l(sG*+Ti#f<M&x1mobh3W)M^@1K<6st~
zyHeC?PG&lk=`16wLbA!}Y%SA3yS{nBU8L>W1Qna`;Xcn7UNaK0@Q79HzI3q_z78A|
z2<tqc2+Q;EZ?bcImUw9WzhA5k-^iuns_Frp9nb!Of%Np$)C=16TS4dPWHIX1C$IwY
zD2Lhm?V1a!WOlYAQ(ZerL7b-M`E0d0d{->&9bq~Z1|p6q6SzM`fYEy=9kL<<Ii=vU
z49Pm1XL^*I0|*aQhL#`fZ$Ni-0+w6W^tWJnH2^a()SX^_LRr>2s%v=5`=bGGhuylk
zYgHIvqIP^DchOe~mI!q%#AJq3mT(>AD~e{D4U7b^lPCs1iSga|Xk|amF2M=qiDbSj
zt**pjfF--9iG{z|`5rUlI{aX__(@C(Ok8p%rtLRDwf>hBo3dKrTK#{jbgUQhTAa1@
z_4NY)8tK~sSaz7>6B7YDKMPPx^(~08FmV}AFyux1;qa7{yF#~2JZb|%eyTHbgy|+J
z_ZiI*GsyIBA~V1hBBLl`#YGJz^$_niSS85w-@tBA4uL9^Z-4Ql8eF0-{??<&_#i+s
z|CC}O<%+J(fvzorBWA6ngpO}MC9Poy>`K>522bIoUO*|CTRAPcrIlB<f{-!SLA_w#
zk?;)UdY-vbZPr#6An}{FU5|dE)ainvVlE@|d~SELA<O}9#&GTsAwfI8+X_;_qB97S
zavY~-D3C7h>+`;Rfk2IV5o44lLYuV)w9|P&(Q{t_a_qUN-_;ud9Ftf7CJYp?!%#_1
zNs&KXYP$qnz0~t`ew)GZm7cJNX{apf;HXv<YY{(u3*0zbApwR*Egc0yrRme4ics8i
zIxM6h>RM^TdN%VRM|5o%mwX5N6p12AN+)=B5`kxfwX=mvgmdMF0(1HDm|BBhGr|Jz
z3jf~U4DIbXwfIbNw7lI=exK*I1m4y<7~EKc96PsY;dx3;%41gU&hZ3Ky&951&4X|u
zz32R^HeE;an_F17nlWpkpY~~RZiR7E>Jy{JJSTzSq73cwl(%k`6)9ph?q|C}@O=c8
z<Tj1c=q08q?rIQW-I)a&S@8|SXZd$Gr+>b(b18DL;mUp)!FZ!8A|amx`M7ee7|g)M
z%#6&mw1G~@vObzCDXC_R`vjzW%INk!PqP0G;2t9%EMZa%9B^u+-mR@INj?C=Mg|mu
zzb`YNI<vjr2AlASXN}OjxQlrlMg|5OtOzD&IWOl3|439w#c%!&7gog%D)vogahWf2
zX$#bE8+<K4eYXs=di^60-VmSfsM*ER^nNiWgd7da#!3(;#W_Tk2anno(V-wF25ZM(
z7_5*TCBDVczJ#oZ_}8r=yCS_s*|PB%^?K5)@G)F8>Se^tW_5?E!>7Wr(yexSBE48|
zRC;9H>{gb)kuL*Ubh;Vhl##a4?8cEbj0>zEqGQIZptXoTXo6#{T`eE7WVshWP#+rw
z5RTFL21nYZrq||f?@+93qy8uK$IQz*g=R~<Z-wgBH<^NE?E_Fba=~`eT55AoqH8MI
zr4yqIGi{(>6)mcdjB9g{mqSSvmr?c_K%sTCWbWChh`^RNDT$4BH5>X=%MT0Ok{<v4
z{Nuwnk>s}{d&}l!&}2DV#2MTW>d`0k9RP}zss$XG0<7d^TKoixLukjf3=-12Ovg0#
z$#i2$Mxie4t^8svM*9BjLiE4l)N?@GlNRog1cZuANx(=t18IE86V!qa-88?S!T&o~
z27Nofly{I*?&|95w?~fnBj>&&BR&0Eh|9LLwDja=-Fm4zJl>1Anwk{&d3Z~uN_ELI
z$rzB8`X<Y3%rdlwJZ#+~y~bpeW>78v*o8E)>rizPT<(feX5~z_9s8L`qoaqLe8Vr|
zE9@CQm8iUO8{TkTcucoZw+W@LHAgN+Z>GBCR0Ss_g&K5)w4grz)oeYG_!F!)9^_cZ
z*1pFn)WH5<557}`s76;y>#eD#=1)`5A(1_LHye_ZlZWR`2N7eYmanf{*B-E!(N8LK
zj15}ZM<@O?TUD5AOBVkbx$~Wvt$tyAbz8Rj6Vi`pxC;e+A@{fC<MemKX=s*a51s9|
zz9X<0M7UpNZk3`ls*D2&s4v`WFhWu^!)zd=7qWKVn!V*}@(g6ZxIUYD|54*fRJM{^
z%{nm)xuRtYb~?4`8Hp6+A>rUdHIt|Nyyd;@W;WAkGR@5-LF*-Q=qvK<P;^YR?fT^2
zKll1T+%tDh+x}(U-rUUeHwz0dS{m+7+#=7yixp)(gS$4etf->Oj~_o4(dgE^)c5th
zJqPP8&s^ZGc|KmGGP1U|R@PI3UxEM!2WP94Xst=spkHP7-oeZ3DkU&5urVhm=KvrC
z9_Huf42{@%D_5r%7fmostPNEs6sCJ%^dp7oW}~E+`npRa+&7ofg^PFa>DT;UY@d>i
zjo@<)s_mY;)6TtY3EwnZIj$;`8f~XAcj=%rbE!<ZBk9noJBu0TAKGwtA2_+$D0)Sn
zYd@R_14_kOo5Js{17WjC&H##_q@tqoxSV48BHOusdVL6D%Ca68iTTI$z?xiRzpcA1
zc<|vd8L(ZZz>?y=1~e?<o}j^M0`u#Jwzjrgpiem3WpFU{>sJn_8HyIu*!Qc5hw$pk
zE69i<1FKrKqzWZU<BForH?;bkde>I@rl$Dlw6eKMVag<99Hqv0xGH3%#pRU*Z*IcN
zL?zyhebsV_eQ|}EN&K`-(|<3VxKlqx|Ik>gy|6aQoa@ifri5`j4+_;<RLF+ENi@gE
z#9EDEXNA`=*fS@Bbu1I;wp%BD{yf%}$bBfTs;a8cU~{4%C-?TTw6wJGdX+j@`1m$x
z(CqD36M1*6JVsJD_02eNu>5q`h+4tO_C{7Bm)6PA@s=?)258Q82wJ8B$sxx?kn7T3
zm}qjNRIUE0jmaUiZZU2&09wzc=&)p8g(oTs&il3Ff16J%)r{t!y6I2^FV|iB9Z2~2
z+&7JXP2Z|grkv!t&)nrfO&%;GP(NHwd0%N}B<_gZBf?tbjkz_V2aTE20!szhZ~zzO
zh~C*yj;4yr&|x?Z_04sE0^{=K#fAUW^76ya*;xa(Jq00AQA64s&y*%w@NKTll>}N+
z)z#F5RMpibM8(AB1w}-zY-<ee*1;UvJXgeZ^$H~RC@}cDEhsDF{Ik8S*a#Tu9177N
z+t+66?X_#c$W!aL{igDJL-XSFB4@W0G47Z8ye0`YF)6jt6obo@2QHL))@An<pPmjb
z*A=gE(wd6yn_#DK)rT2w_3L4C9U32}>7osBqNi5A&e<J1aNWHB&K@gW3SzF_Cg<o9
zFmJTdK4Thor1I=u!~t(=Pc9(fVFo18J3)zHC=^;885zmibL!1BlBM+v6@05VJob9}
zx?H9)a}uC6_VaUaaM%a`EyI$wNCtZ3^7{4RtM~8UXM+L!aQJ>4*edYQJoh?k0xkFA
z<LZ-t#?IMUE$6iZEV<`?1|QMD@O4QjnIk1-5-3(!13d5f@TR7wgr+7Y1c(l9RmsA8
z+5?Cib3tQw(+=>??IfE!*Ss%3x{iWJLyV{;^v484`SC71XB&qz7``&fN)?{&{kFn)
zy9?^HGH&yZyWXp-tNH5pwoXoap#~RZja9L+u^luQ?f8wa!w(Nb_NS}gOYYtBIyHsw
ze}~kEjX6Wwd_gD};_V=7d0zW$X@(+BDehyyskBe5=eS!3c>v?z>Hhxyp%qVatlV6+
zs*T9mS6n8JvSjY|ze~m1!{u+39zW3k|MUNmCvYTnONjP;*jf0vMdI-zDaotLRmxZd
F{Xc1qX<h&T

literal 80754
zcmce-V|ZlW_AMOSNyoN2wrx8d+v?c1ZKq?~M#UX=Y}*~@t=~E4fA0I?ez^C`T_5Us
zYS*sXwdWdRuDQk>J5otO5)lp;4g>@QQCdn&1q1}59s~rm9R>_|WQ{sf1q76rTUtz5
z%>(q}4=5}MF$g%*o92_p019b)%gRYQ@GKM&;0p-^2uM4`Kd(YCp#M1*g7Tja{?88m
z>v#Syzw>|g%m16R{-0j#U)TSCb!Whf84~zHgTRo0kY{H1G;KNPz!u%S^$q_Ds4!%J
ziYjDr&VXZJJ@D&Fo}+yoF}r%9uQ3;1{;?+L!dI*wr&*`Z?|FAH5Dfh{H^%$#)pvS&
z-7dF}Ea%6yB?QKPDXp+ISyYFkXMw^<?L;-g%-q}_=VK&-lSi)-9GAPfVo64WUZ33H
z{CoTT%`g-Z7!qOX5EPM&es2unx#`*2?QYL|iG$b2^W&M^?3|n&n0)y-0$vUt9yj6!
z!JVTme(%mre!cmGi%4w*;#jT7vI>uD{W>U4=h%Vsp16?)hKn+2`+CEem>7J1FBej1
z!Q+RDg@|RmnT?H&*VjwQctU}wZjW1$UKx@Q6tocF_5JLW*tv#p;tL&bQfq*tx|*Jm
zk?dh6hufL<=iYE6nPhxSOdNhpL1~iOP{4F^mw4Bsk-?}R=K5MEfqug_Zo`0MV^6M{
z4q(B8^@*}|Wy?mhP&$rMPv#G@1WH0U5<ymGCik~pF}+?NPb()UNDWQYso8wN<CLPJ
z?OtCx$zos>U`2p`M-a^vwi0>#@6GOzzNwif<m^`JWIFK7c!z7?q5b{+@>2UYbW2Gd
zJ2?%QAWH`=IqA&Wp=aESx1ggDK7N;TIzp@-t@j3H3O58^qiPM2%aaxAvWMr}eT!lZ
za-URc?GRE6!ljRkRaOSc-%-GO4}mB|5s9dSAB@i!?Q*|HJ&ZW(^0*}hO$ZSqeNl2c
zx)wQZ0h`unTD5M|eRQqZSidB7*VP-@k(Jddz_a5-AAbtd57~{}uUP?UO{buCFRs^Y
zW$w<z8-e>u^BHQ_Qf`RG@K)X`slkhT5!T+6+Fk+0FfK5247;QvqnDJFjK}8|F+5vs
zvZ&MR^E+Rzd3<zj<`KCaGAalDIdYg#U}RFj(eqK#BNDXq^z^iJO<PlwsT39D<zr)G
zN!}AErZp1XB&dR18b(gn;4pOfZ6yAnho9}mNf?zaE}y<SfmN7IJv&W9#e6>N)0jYI
z<lZFp4)2Tf<<`fjrK-rlhhK`gF{~53K@>(HAj8`Xzehn7E6Cwf38h=GSR9*23YyK}
z9q?a?!HWL}F1M0nK6gTE3uTJRFeea4Q{9fcU~9-_L?U2%$_{L2psk2v5{|FJR19(A
z96T!qGaLphYhF_+m~gyASCN{&US-jOA4A)QWyg4PXY1n_8Iu&j=1t0+xR2(=fq4g>
z;v$NP5t_BS+CP4fo;=*{k0C&PBCR~@q5g*`Sxd?FilrV#ezJu3Ci4p3qsX9v2kSlF
z?)<gFTx`k#@)Pn<NgUe5iG0e;SWP~*PSqIQK@dKY%a&!MBjCSm=?-<m+BkU)%zs~+
zHa3dM+t~EWIcROP@{iY-LN+!j0X!8O?bmVPry&IKPLJ*Qy%nw;*Y(0K<h-+Z3?-+~
zfBEIY+ZDWWLl5WfK~SEgyx79PnnMxi$(rJ3+x0|f{KMrSB^Z+7Sy{~Y$iK*vzaJJC
zPXI8=VX<Dn{kjG%u%I%KQE~&2V#YP78-GMZI`k|y#kE;5Z&<E@+2)!Lv!fouzKS1<
zSmg5L>jmaYumQ3zFS{vd@aj_#6WR$>XL0QlM>qKn_rD|Xdb^$IB`BI;sd}%2MCL1K
z0M2{&aHjGnyFn{#WrbgpN`;kaEk;6`gEg1PwBt|tv`bk0F?Xbf9lG1w0aciD;eu8L
z75_uNjcP%^hZX&~nG(jac*UD{?6ybClpl7`88Xa;>R&9ly)8@5X-<)eOs8lXw5*qq
z<up7R(S`|y0T|`R>25jZtY19B=4%I=2z(gsEXH_^WwSYl>|xzgDA&tpXKS30u{|i;
zSrNrcUMc~nZiBkKI}3mtQ6&T2pl3Sp?7rNQrcxihh)$WdWGLGyDO2_jMm2+#)LFM}
zBk@}iZRArt0%4*(5%S+DI5r*xf?w=6@k9S)&wu9)Yb5NWgl_M@49tED3ky@Mk!L%U
zdFy|Fu*+1Rh^(7^viSTsS~MP*YQU?8<KPcZV+Ws_fE(xyS^5r+x~tELWX}UVpjn|d
zk!an5o7GMPKOW_l6+?U<VWy|Azjx?eeZn*Row>HV`}3vgc$So_;>PC_ZPsFb$zscj
zaPc5~*n(X%JuMCEC2&%<si|q$;%>;(KKVwElmk}gkR|g%G$OT7<!I4~hBf}=%CDrV
z<8Y#LmnMT?;K`T>Z)>;`(Z*svmo7r0Bw*5lL2N5<07Fcdk|B0a7Rdj9fr&E(=h;*#
zz!FwpH?9uh4|?1AMoBRDs-Y?`h;+T}ekN(f?=@U4^U~ax43?WC{Hh=819RZ10j}UD
zaCb*S5G}z}muE{=VzpaYxjkPypnHMZa#998UXf8A=kN1-@Apq$c)R2)5Q6bUWC29Q
zgjiTuTzWZdIX&gRrGdM0d$tJHM0?tGVsh`vRIm)odh|G$ity%Il$`W@$gSfojB%){
zQKNAY1lZ-rvoLJmYjyC;x^KZq-oKS}{b!1lh^f~inZ&n1nA!Pb6~nxp`6Pd-zzQdj
zet)qQjZ&b;Z1OUr{jS9TP9OfXQ!q623oSf;=e!B_M@A0R7hxVl2$68MO%-UTUC^=4
zWTl|6Xm9jQXT;;9qgy8K!`-h*Rn>(YH{I%71rKoYJn><p4*XhVIw*VXhqbr}tL_bK
zrY^<h(G;DLR-d07Ew*ySEFxS2hwti%{Ql)TDkLEZ#26wlx3GgCs4M52WPU%*&2jrs
z22$JoWrj*eWj5T3!8Ya9Cd+x)1x$My&z9)51zLYr`$#^oaB5bP3_4p{dKelyT3P}Q
zAg+tJydJRKU(y-$bfcJ151Rn-u2-<|iX(M^p=1~)zG(C@aIu4|Jc|_sgfLm{IODDG
zgk8}QNf^A=NG<arxcQ7*CvzL9Z8_mzw*Ev2&RjVw2!!|}nsvH8J$`uFUBE2-FGz^#
zqwk3b8!+oZ3lMDtxS_{`h(Vik-u7eSG2LrXm{sE}Z_zfkD|D@M;<?W_no_gq!Vy(E
zUK5LX4kEUZcc#ScUKNL9Zgt!)kZnom_j-xzGKe_Y+sDaz?!J2xvQb=Nq;etrnpbLn
z;F!3%SY<M)_?6i7jV?azySa|1fP82_2!|6uhD6~oG7@&ndwhy5LNu0|B;;8X61bqk
zkT3Ua@t1}OLy-303?d>SAt4|*p4*b5OhD2?78{SZs_lh;&%Ws0Kmx^XcfQ#|u>)Kr
zLio(1AI%<cd}w-h_47(@K9kox6U#X?v2Y5`hLm%mB}RySp}j|PJnS-Kiv~}sC;J}?
zsLfN$K3Lh0uzi0~MhVByvT{YK;&Y40cNPU^;Op=Ite>cbrcUjf?S8)2){P5R&P}l_
zZ`XZay3lD_q(j+wt>%UzX)0(pVR=o9JCiqWPWK<zf?x0Vf456PBqaui^EQIebym(F
zGXM~b)3Yv7-3RENe}kU~^K&@;c8Jht^90Pa(4b;Ou_L(z1j4Wq10NJa25<-fG1N>3
z2E&r(n6o)}Ay&GW(c!A!Iui<KpDi}pvUcNPkLX+a$T@&>`OfhV!9Ojo=?nG&ncwlv
zeJ1e~FoPzircg$qr3piTmD4D*?G*6+6t+jZ<IacNWX$#n&)O4!_38Fn8uM(exVBcK
zYRUSMyHoF1(#y5)>uOow$FxJ6!?r@Zl-6pCJ&GI{UiW7hQQ#C{9k%P+JNK^SNx!|L
zRx`>e&)D}mH<WQxRG1j1>gBOvLCj<4K>ofW0l{bqGB3Dj#rIksAw8JB@tX0JPLJEY
zKyYXz0v;DB5Srw|w6X$NcWG!u+y{rRCx>QMSHoY3IkwsmEZVtqU-ZUR)MphMY$WqE
zxtK)eq|3kO(7doVXWi8gEaPLIH0)CUod0?-lw^dwh9F|`Xr#Z1C_4`)@_T5C(XeL1
zMv#C(gbE%gpdihl3mp#?U&XmdOHb9*)dRJ24&y~O^?QHw{dI8HIcySB^MVCVPshke
zM>mudyc9Yf9?$>D1^=y{4U!y!vzz~dTl;M^FxMD~ROFNumG9$WVZGH(r`PADTDvKZ
z|7isj9135V;Pvmd|4tw@hxKB)E3gXt(PF*UY&8^yh<EAaI5!%LrwUp*_s<syc%RPy
z)UCl0c^)Kgz+X6xCsF9M*@qfaY_PwFTjuc9@ie>f>)2G$rC!5$xQe)w^eFOwVC0RW
zIAxINArt@pHgb+)4b{<%s76cj*_e`U;Oh!`8)HcX5DawNE#LkcHu~?q=ZH8B4&x=$
zcvf#rqhvbSS!r8|dv07SEHu?R{SL!G#7hS$gD6Q|FHb|O-3O^|EGa2zZ^vdA{>t~+
zgJpmQABId3c0MV|LRzLG5hnyWH~9v)OlTO<_w#U~1qpZ);TO5C%i2`AE-HVoHrJc2
z78rtB?bbOge}hnnETmY@m%z$Zi-sfpW>T=-uKmyleN-c`u4W40R8hB2$fDYK{CvCi
zAB3gK@j9z88H>|vGLK!0l9-&G^}nCyygdjJ{Bu%vMkL?q>qS!gTl1B>31u_s_3u3Q
z64eV6sGypG=JC@efo1-pFpD=V?Ni7(b!Bri#>_ZUvh6L+FPiq|y7{f}0YfHi5;klE
zC~$qdm_OP{c&f<4xH#zPfp<S4HqM{Ba1D5oT~Hkh-~dr^vEYp|bTwi)lo;hl@Ql6v
zd_wdIKR|sPV&k{{zkItnZ!d?tkgKrrk|)!?4|zLh3{j-(&R3|G1tamm1cme0+}cN=
zUUpsgq7<fm*CCY*EESK&oW@5<3M|Gxp^n0+g`{{3uQU`?3lhq7L=((kaHved{T{wn
ziCf@#e^iO*-cO`siX3+qSJ`9Mz9;Z@0X|fMzpccE`_d3PAEsp4LhDzFPAR9vX?W<x
zU2NRDu9MfVi*=-^=<#;>6-<OygemKqDJq>anaZQHy;RTli2_!T(mP=zvVA<JvGYBF
zB8Lba33f1KHNi8UW8KkV@P9(1!~R+4|3T*$e<NfLH6c>8>mbe|gr*AC31GqwoR7jk
zfS-`DX952y9=3C;wZ!iV+vu~`Cn<+Z+vK!A3JH%X^x~MrcUE5P1w_Fb=*$8&*p$Hy
zj;*Dmpo6+7EU)#+Z&Oa(`{NxPGAfme-KE06yFH-ky$|!U;mAbH_8aZ7cpSD{-JYuI
zO45wp1@|w5!LKhlYY?8zg*nr#rHVuXK3w;(xA3vc8cERMoi3+)kxuA-T@E@zjOMa=
zmZBA)B>8*cV2zgKlp4517K`YLd`?dnt5q5`gE6DvgQ)4J{yrr;Cc>S$3PU2Me8ctQ
zG1?-L#_#(h)U*txviD#SmveJfl6UTs&@XiE4$vdF`t{3uahK~()E_^QM<iH)=phRM
zrV>NGo9w!;hcdyQ$D?eI38St62$A&-!?q$_>gZs^ptrw~egR^5hYNu}=>w(;=%}g1
z3{B%%3C)FSA#r5GiHN0ILkKXb=$S&$0!^xQ+K`I3Y07fu+Z+s@VZ|Uhz=}mFLx+UG
z4v}g0sKOONleNL2X9M_<xOPA?=0macr2^7~Q?dEDKJjAK$(=8WJ(@*f#Yly$q-kKk
zmp-!gvnvC-)i^yCY+Ing2)_M(=gbpmiCwIR^O#v(UCmIWlFLEqG58!XOV@*{IN#`C
z{hs+-#+pCtPaAEJgZ1`v$;F*6S17a?VLPcp$8oOvmJBp)m&q6sB`Bqis@R0rm_@$t
z3>CuQnZVbEa|YWBv5J<*w;kBd-a5@-3@HeO2N|kY_le{AH<g3_Y)LIO%JWjXpYi{T
zeopL;a~r+BWBh-&bo7;xoY9f#YX~XKrU)>whe*A-GKIfaOa;Wm(;(uc%i8ktx?hFF
zUuLp*H4yLKM6Qzv%QO8nH#J3YI$3R^vX4@NN99)8AX|OBifd=_;($RhT_t0+4Vfb3
z_kQ9zuWlNP`@oXZVzrpb8h2Q(=5{`^-Dqa!Op_%8kT9LeRjrz12Twra(gjd0jjstt
z<}E8iDo@||VC<eAJhD7WBVH*tv$&uhDe3zW#`Zbxir_~0XGI)kv03fC9OuU)qBy8*
z=kY=QSbv*%efo=3#X>lU%q=@BKIiUH08Qk>#Gy`2y@;_+V1RF^)DPVxO{83czeQZy
zVcZ$gaobZIlzvia=i;XyX#D4dPgy15S$DEKp}j1po7X3Gmtrq)!|Cm^+U~h)`>WS)
zS(W*}=<_SQ5h5*S;*JXRHWCIEU8$rjFlH2goEs8|4{L}CfQP54068a}6C?7vA*tr9
zZ~Wb^eEpdplcar&c&)l20IS2|`}(jS$BX1Hxe|2Y7mH7frgdY8aRWymh=P!j7k>~5
zvO~U7(dl-%X2A&)&0;>4(cye-ys>@~U}Hv)nao~SM9X%>s1Vdoj!nu3(0&AA&|lAy
z0hgapjj9UOQaUl3+B8zRzl^MRS)KQPN%!ZzpJIJ`I$bYQbja!fN?s@ug2nUvC8JRR
zaDpkysAa0Uik@-!;Eqy|t;)};a3Q23^LhTCp56Sr;Z_vkuV})8A@~Bf!{|QHg>*Lp
zD8kSxRKeDbV*~nUwIGZK(|htmy&q>)b$1;@8HN7?w6M+_p(z)L)xPr?-iGTD$tuVf
zY_=#+C`6@$2E<VE=A;yvLu96vP=dqbLlYXWodM`=pM69r;;RBHia@bk&$r9A%tM&m
z3_<_T)3SVqXjMAs@}LV@rf@f;8Un*GMErr90YkuYv1I&yJg@yuD!6tCGTk0f9nvNu
zWo1o%+h2ZWuC8;`_f;;=!d6lSvuvWJMlzLtWsIu~%E3pB5BDxqF>XjlcOSe5V{gL*
zjKFfEHQwigHJds@T13VOU8OX06;Pb2RcY1%@uqU<6&Vbj?=wL&rDMvDK$KG&80<kj
ztEtM9`1r7dUJy;~gh07M<75Nl7NyFjYMP0jvFysYlm9IKbzG|ltYWYOJqw*XIy!uq
zZ?7}w50nJHkb=-4bnA>VE>Mn7SC8|^UQvm3t%=+INpB&)fh&S7>Px)9D~vbs5u`0D
z0yTV&w36uc+7R*;H$P(<bb_`x0X)Khl;G#{{=@e+`IC{qTi(~bZ&&;Cz>tg{qb#71
z@SE+avQ1ht&6Xnhl@iHZ_#GILge)lV+U@iUvzkx!`#NoPzv#5uMjnpHM2#qzjz(rb
z^L0gYCa%$jX#P265~t#>AtdI}c{^WLOD1I`|K1T{A`IJ~9;61&r~ETT8I+%3<+lUL
zS@j>m^}u@0<2-NsV+OqguZe}fP3WlaSb=Fs1o(?MC`<$kh!OUc5$rdj0G+IyOd8Ce
z05M5=Z}%-HXwLL}Ea*1$<8Y)o%<{wFUGV}4@|>cESd*K!m6HF)LWFe$i#}_tniec%
z*x0chyVeU<NSQ1O|L*?&=g*(mGlN-Io#(ZjTOPR;UQ>lKlH}NYdye-eksK0zQSY8B
zM&U*`MiKE=5vYQ;j(s0b3tsL;p<C7=Akv1ThJw&RV{#ccL<k@Ig<PBtM&#4wc%1y8
ztL!3$;3~SN$t!%+#gz}mOzjFv(1*eV%UoiYRaemuztxk{LaN_eB#kbSu)MgY?I*DP
zJ&dz6ad5OEVNuy!&lZ)*Bnf>V=J;+!k@+!>kdafmDh%ulWGT<O0`MbuV@->za(wQ_
z<si&Fef2Syd-{j<kY|1k&?JcZ$n55~TeB`CWlzk^?2atbrFGN5^<abj$Vkqfq>Jo(
z_<H~Qb)$FW4TK7lh^0IbEK}q#>fT4I7Psmq-7wKZq{=5Kf6;3A;o!MKonaA0NH{lL
z$aanD7nx7w!ns2Mu?{_tm`B8vpnE%GVk{%LMkvV0VwUIq^@Pq!LlO5>H2dD>ak=iF
zo*BN5Z{!dZ%jC>(o?KqusWuQK2GS6rbFu00J){6U{G=p7{}4MwYPn8vT7)KO$pn#S
z(la=AHAg=`B_{a^#>44f0!5@}Ak-=p$|>hnd5kleKtknlxUNN@4l(w<|D;SY{$_hn
zKrQS-P_%U8D~!>Q8Qe=>FdUtsRf=6ib3B4&Fx(DZSM}E_+)+V)9!rlJ_bTLS;?PGn
zfznFo^61SC{aGtH7yUTxMoy!~@RxV*Vg_Bszv2R{zWW%ME=<f9pMWI<qFD(b2?T-p
zFh_#`ZUYo;*e8$xkpoBjr<aBsCYVAYWA_ayA4-+pM;tv(g0#|#Y5769a<P_sTmd7?
z1(OPuDGW<F0@rFaw-*R^2(>YZDFNRyhha}IuwrZ|0vEOBo}-y6CXzlb6H7f3M*2%#
zSSm8OU=tfu5A%z}@>hxHAZ`)-Y>oGbQpv<A9g04*yv)Iie#RIFm>UgS5uK32=2YHT
z6y?N4T54{O@dzBx_`!HGGnR>X$-T?T@5EU+CefY!tjfLtgj4U6Im6J>?1qd{;GRay
zNThb|k?=H~0y=Zm8(1zVuiJ*V)AZh%Rd+1R4Wfb8`NWxoiM4pX9BO8;(o5R^8#7GU
ze!KNcWc4P7y<{ws=H?O_8ko-Sq!FNY&z`9etrJrx$#zi37N#sHW`VX-WGEa*luN~)
zA@eto6bNJu6uUo%!PNT|t2vqYVMt6F&mh<O0~>hh){Iz(U0Chk+ky2q>KS?$MX{lS
zg418pliK$0{_!#`iL?!&0VS0`7{%|2E8lMrKDjaq5>C_uC9H*T_3?-`=aMB{U_RZ*
z#Jy{X#Z!^`iA2bqiQyu#?!0@O>$8@&^sLEEZ@(c{rWYWc0rDZB1&tJmcs+Pe_(G6K
zM-gOk_l(zSbU2xXcED#RJR+QFD&&4!M)=Ak;GIxx>(&pVZk$}Z(#4t{>*C93zY%7W
zOeJ{D50Q8*cAWW+p}oqoiI=^Fs{iCU+>w!ipu~Lm+5$2w1_c)ZYKRfJI`C=jyl&fL
zAr=9jwRN<@(4IalCO04-x)S9RgiMxGW-DUq$4XuA6D>1`q5UIvTz*B2m^(Qs465+1
zE7uY8Go|_gGDK*|t&t&H-+6{foY52UsHky&wLxFrStMxEK^JKK6)RP^nqfBnfh;J}
zG9q`yjOG%U-KI@qvab4MlCe?R19($vpO?aS#fs_OtjQ>fgS%$cWfKU>bOzn#h!OGH
z?mHPu^gV;hc+{V=_RG!MHsKsK>(m|<X=~y5NjOzx=q{O<Fx=I3*ObpDeP5q%Vu7Sl
zXmR!Q_B7^F)2ds{lA-vY;|Q)(<KyPW<PMzqQ5lKRG%7P&f||hECm2-(h#iH(Eposa
z(#mQ*2-A*9_sPao07p_ns*L0h*x27Vls_4aI8e3b-cmL7jk>iA_)yRyy4F}{`GTpa
z?%V5|nP$>{K?+y(bGjzrC^<vk9`XX0FUc5uQ1B3b74EPW`$a-<r@g=6-WH%_()OXd
zj$%e=HPlm)TvKB}&18ygL7kTm9ff{@Irs#diVlW|H6Pm@a`zzn_08{tHr1ScVeGiC
zOK*1e>AtCI^UkKP5s`Cp4$7V(P-_myT-+Rtq^S+UqItL7&|Rapu%t;i3uFcxre+i6
zcTz?=#-7aDW$YC3VyP&)ow715x(b10<Exv$7U-c=pmbLY@kG$nT>rbAB8wNXk%CKr
zoY<7;;Atj~0^`BTIB@3~;f$)?cyxZ&N9&_2kQ2}G`wQ1}zd}<3iFsG6>aQ|NFfwUQ
zKar2)3@rX8W%e!)KYI<yhErRSB8+Er^uoo%!_>hr`FHWfrdhr>H~!K30^q<7fdmd)
zqpt_nS*EJDO$UEY0gkYa$4c>F?LR&q(H`FtWP%puP~E5J5>d-#8GBMh$!_4y&bT9D
zt#>j<C!n%d4d-s<h>t-HpT|Lwvnp7Vt?EEUb}GjR<GJFlnq~zoa-4V+t>xtvA2nT-
zTI#qnt~f)GQIhFUBvEg{6LGQvl+;|}M`)tW0uxeL0?oAQQN@$##PSjt=S5(3zHy71
zx{qimf8({#s8TdXid8AIRmE_W%(^z0?9;Y`8F@^^r^`Nz%#QuWN*mwn!p2M9B^5=T
zj*6IMTo^~E7HA$b-1veWU$(bCHN$4`d6&-oexY4i$82Dglk;LPdcQfkjzhFa7SD$U
z>;Jw_q}^}OtY}3?1uc7%v)l4VKiCZLY{pOY_`BI^r1`q}I?t+SL(thDM1J-rganVv
zZmav$|DOPk5YtmrQ+sp;G(GzX@^-mx{#b^U$fi2U*fK&9L4i{m7RQcag&!`%7?W*1
z?YoPj<L-)i>=$<s&&Xt^T>W`8isvxwi$s<X{?W_|eQ(kcj3#2Es>EL$3fca+taI76
z-HT5%kh88IYMqD+xrkX{!#2gNKc}*w%!e{(cve#oTg}nMlL)E0uEu!=+q{r`RZDkh
z5w^&Z*sVr0Vg4%Dm6sw%tY8uEuDMy0c4&{ID)h$_FIBp*1rPs>3g3N5O_wCWm)c#f
zM9*Va9JsLoDDYkZ{^ry*w|%EL;H|sA)fQO{e6Eh#zwchR@3LE|-<^{rI;_k2LWJ^8
zZgg5i<lKlD(Nt&egId+TXVZwpHGU5;RB!xyMc}@1J3&{MVkZR;2Nxx*rKEI|Cc!Nl
zq^Fh9b_+mn#Xnlei9cZ*CD08001*OV4k!&U**76Wyy@w_Y+YZWxy}FTN5aRThuSmi
zv|g(0`MZ^E$E`(WWFA9MzFMExWc;)Gl%>LUrF}`GkLTiMXolyUKE=qKc1*y$QbSkm
zo`fx5Nm)eP(*hIAF$t2x4C0V=_%{VM%^&StP8%mkiTpzh{V2(vQhH*DY|G7=FjVRO
z8YkD@^7(|LUUaHOn>Hq%R@I2qISLf+;(}k0Ydt5GKG}=Tg>71e#YszjSEm;abi{-7
zHo#`COVxcB&DHa0RuV7mG6uu+7?D5UdfFW_3|+`d`1Hi?+ha?*FEyuCwOHKXwslnv
z^~{W7hb>pR>=QUL6Ud9ap%AKd_uI@9Z_Uypq9%Dw0kOpOH0So<DC?8U_ov<Ln4q8_
zV-!pb3=9uZh0kt_WFbmVb#-R%YzTD3_SQ&P6CY#Ud+lX#8UPyx(M;bbB67oYFmI^+
zT65%*xOx6c;FL=y^yJpiOEOOVcOj7z3fZ(1OAo>c<FiPaYBjVX4w)ZDDfx>_bGBH*
zjtI`W)H2x|+g1wGSBq4WXih27*v4UE=}k}{xFW}Crh4?WctysrZHr5ta7EfmtJQKE
zEB&xR+(;hKKYTIv)^oGGI$CEax!5tB2QCJ?N&5MyMm90lzI9Z)s*DGWm?F|pw=~9u
z)i7>wGPdsoef(X&=G}f__?$(EdZ00DA}3@YHeM9ybo6_yGD!S-T6Z|c9~|hB_Qbsz
zr^@d>EzQ;%#n<j^u01Q&EPasO(K*y-zAIgJosKvX-Yd)Vo1n{dz=Z>je?d;^DaI)2
z?@loCT>#NNJ3UVx)}RM&{!qr&>rD`aK)}9K9jES}rB2s#a|;X4SL!y*cgDKV;6oUW
zDXzyw)zyd48iVf5B3qH~@jLJneAoh>Oklu`Q$}GSiTTuXIjS*8QGGLl{9A~zu_LU#
zkQr=KMDj!9a9FXsTYRBqW0URCET1-{nyf*^9Afm(am%1=^0*8d{%<xFdrEwd#%@k%
zXjvi!YPt>pWd;QVUx>E;q9XRhSa+8aSJoWOGo2yZqDNO{15#BO>1Lf>THL`R5e7$V
z9Y?jY@)o;K|3uCsHvfSfkNI)$tB&J%|GQ*G|5w)Q{Gqpp;|QeM1R{3B?;m*E&!YoC
zV!s@wH(3fkALXz4g{g`vM>=ux@XWuP%X!d0r@_ae7~_Z-V(ta^Cy~7+l3w~d{1d|e
z6~m_R7Mo>b=w<bh$~EdE;=H16k_R-zIiYd6vlXh+Gb7li`d%)vH=uGd25l<@p4ua)
z?PC~@JrmXch3L)r7lvY@Gn`Lc@U3I^11PQW19e0$@&v1f?gh3NeD*~Y)^8xUBTh4v
zHkj=Bnh}Un5>IFmQ<W0@us)!Ln((yqsrbxP;@QJ$%q@x`&bM)UnS`z_Z^X$ZI7Wb<
zbWI=Hb(Zk%?q+nPqHJS0^c2DL@R^~-NK}+8-|<k4bMw+K^vv9tw>DklZq8)w+oT+@
zF;m-Ah$tl8xdljBqt!W~h{?NB_f$KFkk<EAX}6VY@WH~61%5HT$U<V-u;6>_1Zss<
zKO(kIGmdC`bYFkI-6A{qA%x+??8n~eiT;`fb?r$B!m#L~$<ut_#tR0r^*?lVj9Vo`
z7W7&DmHvdw#`=dlhK(uFu(He|oOtDq5bx*9-60;Qy{WXLP@mEa$#BVmks!yc;ZfxR
zm=j#6LYb1!E?4a3+xFMM?O1;QBD%a*N`~sUp66~3Y~R@77|P6`X+ohw<pkv|9ok&a
zAU2c9*Jdvd;hM(h16OloSINh%Ap2sZM*pMnY@Y9g#lnaYb1)LT5(ZsP1Z3z+GF6f4
z>iKSKR=~7=2~=t+@=6|WNKCbSs{^aWB$AOhOw&v8lYYY!j68>by)gQ3Ii5l-c03nF
zd#R7yh^b?&t6;?j{c`1Z8K>ZDi}Cl+{{GKG2xTNJEIe?2LVTt!Y}>JQ!<1ZaKH8cB
zixZ+G%4-WVS8%4z7e7oMCoiyy31+YmdIo}Twyk`yGdjvpz+)S$bRL+~_tg8hS5p?h
z8oCkwtG4UHYhId)9hr0HCA-jtAY(x-R!I$x&apB{j2e;Uj(6!~5`{!XEhr<jD+Lax
zsD_|UDLo@v5>JFVH6o@Wl%mbB)J%t#DR-|ZUyP<~sr4r<wzP;8j2~MYBU!nE`u>(v
zETOGg0~AD|ys3*(8N6|4b!}p$$CIZ9Xyez2`WC)0q1ZBL#NJ`mb*=FwLrlakO4S&^
z_KMcpK&YVh)2912(Z`A8vmU3#c5tsK4X_j6o;vt7h}9dgz+N^k2<#(W5G8}V73!!s
zl}}x^ZO+i(UIel7@x`!MV_n;ZuJ1TN5exQ7@#O*%%SPz`e<9o>o>(=e)2zicUUMB+
zsvG+uq8Iqta&#Cm;1f$BmIiSvZ8AC3b=3(^)gYWFY|Nh!jHo^Qyoc2XFoslB%UR88
zA{96Q2hXf*6nW0Q_OaOhc;f$vSx^?5q-=2^gJHWB$Vc!ABI-C!O3DW?ly{-&&3neS
zPW>h(r<%oKRUEWE|5h^<#WMo2*_1&)3e9EUqIhJ>zG}9i-swX2aNdFZ@}Ns;A89rl
z?*$rZw>jlr=C*~a8rH-^%W`hTyxu^4=?70L;|X&V03mIWxY&0kwUi_<%zd2W4Ae}V
za`@8<k$U|Nf{{55u_w4vI8T9PeWY0gI~M>Q$h8`+hP}OLZN_d(OH1rv6hzVE)<z^I
zc$$$@JU*S1?<&BO;y=lWsXX`uD1tQmeRxq?+&x{u24Y5A;iz&(+%t0J%ad{Cd$~P<
zKE3NU+fW}-fBuU2Se^AN4JL(Ycx}ciGB3vt$1fWN59zvWJ<qhr<^C&$29Kc5zj3lq
zK2n9qS%$~JBv?sb&!u*+k&U08!D)R3QeNpf!qDBZ5iZQ!jdFQRqx4JWvQ}4Dwh|Qg
zK22nV?)Q7skW%I6>=urYb!v_8#uW532)l|D*rtRKJBhF+1}K#~TVw>AYbDRM_Y+W8
zYntuqFw{NzNo7XrB1sO24Ysb#sLD)<Ko<@|5l1=T*xc^Q&+L18>R!(A1+Dp7Up-%)
zeXD-tv#D{n;P>XYso|RiY7k>pY3fxPt2DU*lJUpNb0zH&e8IL$lMT#u`aNg-Mt~yY
z&vkD9PrkK#zP2xwdb*VYzB^aFbhB}}{mm}HvDLwdh=>yu2{AFT_qwJa`k9K#jz)S<
zb!2PenCmh8&lv13{aCrI(qb={(|L+kiVIYNO7tl%%IqfUR@>FVi;znPBd5YOa;Wfx
z*gMpWthFH~7d{Vyw<3RbZ_}d)F?!Iv44E2I`OTnuIjPE<Fx%qEgc27JWw!+y34>_<
zpc{&{$^g|KFLFGDxal)}VF{cilGI6<0rkBh8@_J<NuFOYF~bXO3ej$T;0o-&r04DQ
zga-9Zczdd!uztDxToQkKszQ<UBOlp=>y1;6{+<oV4j-QyYD+0SXi7X+0;EwRCrf{~
zFrgy+uK5x}tx1|0G9jPG{gJ%jY=R}2F&x)y7~uD+Y1$5iEqDgF9(*o?wUYX`Kv>%f
zul+H+I)gqxB2?fY_$N*jBzbgz9|KJmvuWbWY0mfe#UMw==TPFxrrM)buc4uk8W25i
zinAw55`iIMgj|mO@BLp6hExFm`D)~5c`<FF=XAzCKG!>PN)$E@w|5Cw6J%+-W((VM
zg%s?GayAgy^?dA>#Iyt%VgE&y-9@R&!32VX(DH0W5OyW`BhggY6fH%7uKPDACPm0a
zySQ;Z^BVnfaDLrCadyTN9&>D_n-%JPqZQ)iHX~1=qLpX$1%H$CQ&5i+w8eDmcOBdP
zzdjjzR~l_sSqM&oqAdkToWoFjMur7Qpm-XK462`}v)gX28tLhxM3B=9^vl<$!xb~I
zAaP(x5%cYF{~HCEt?hjP(5cx$9o-GE>$fX^mJ`~CJGu}V=qv{6aBIxV{QbInA8&tY
z9D$wkR(a}s1X~0X?;ja-0P194dbg`J&x_}V%E~F&YNj|r=$pq_ib`da8nD!bbetB1
zaz0l2r4e+rg=v8fkKW7J%JdNHc{2CIO&o1?+3Gkt{YPuG=B|x;{rK}qHQ`OWw~;!Y
zBwDPZv(0lm)!bUUIlCScT%u}EkYngzoH#b!ub1QQ0p_;fe4_A|VLNt6;W$5OrykG$
zI8D9EV<+7L8RX&anOA1@;}1KOT4A0<DZT80cKS0=C<FQ<UVljfi6IuwL`q5uCV90t
z5{*!pv}#(L6`X-yxgFWq!S<(8SUV*LY*yJXX348=#q;x>+hV~1=pY!0`qnzu6B_2X
z)}KaOqu1p&7Dr$}BoL#LO%#xE-jB_oNP}T|7=gDwxxK9BCca2*q=uyDHidC|fKXs9
z6vP!`VhfT=izn7{a828XGiawJe*$>=tKkIGhZl@L*<}h~=z~Kl-aMqpocOe(kyt95
ztW<iOX4BO2x~xI@V=@+hz18ClG$?dW&m~850uTh_n{xFUtQIH<^?jPQs<Mdqy~N(Z
zvSrP*CCU_E^(tJeptRF4#cx0U9>a(^a2NeE-E$-{K-BMO9cK$}nSv5F`FQ4~n`wjS
z_AqCe*0S|4?|j?M90<_E_X;<;ZOx;Qz-Td_#tn<%3cRqa`>nLjl0p%b!wi5$9~yAv
z!!cAqGH+*6HM2Vv?HEd6l1Y`tg`+|p&Va9?7FmXbW8RMMm7RCtdc!NASylbhqOD>a
z#WHe<NzldWC!V5i)n4;4ku(d(oG&IGs#8iN7iv&ypxl*V)afiow`eV*gPjDnNLNYo
zCrr{=k!jol%MEsbd6JHhX3nRZ<wu`r=|LkOugA?!ew)Mb2a-a8h_q*p=V<1AxFN$W
z&^i34R&N1r=+_m`{mrhZ23OP141oF%ge9}`NR)j$tm%nD_I;r+U@ZQVDtD4@J3p?s
z{dhAn$M3tD4nh+>x0HNXx`+($G?{iE`H;x>xu4K3{$_nmq|)Ws^>{s6W8$LXPAm?5
zu`_8VD3hrMb-7(;<>iecl#)ylvc^Q?kY!6>EK3zTS4qo?7)WD8)Eg5>5j+cZn#FE5
zXU}~GU>vDfv^_OsE5Odb3!~P+VIH>gHu7a>a<j9tn!GXpjKeo_)m`18l1`?dESaA=
zT^t~m4OIPR;$kmW#WJcS$rV5YS|u;ry2Pq<W;S5|5eMgPUX?3;_UC)p>d`~XfmviR
zuckpuA9I>T+R%)d3LZiB@VL59n@~#z^I9ZwRlvlZe-3T=Nro~eN1MmlK?QKQ`u}M2
zd0}ye7qshNCjy4_ap*j+$NMkZ)C-U*f`nqUI6+g~#X&a^`u;a>l4aF<v)7<XnD|md
zS6ui%o^KiG|G^iM5s+fTb=UsB-OtZcnXDe}O+!Xo#Ij8s^S4y;PTU~r<kE5Y+=Byt
zZT4Gx<dK9HQheS|7Z0Zk*_;mMToH7ZZ;C#~mZhj%zir>1E~l6Z{z!OGyUnq1aB7^v
zLo@{|XgF<1+(zGPcMO#wB;XXtafN6oKm0M|+L`hNyYYM8%@_Q5D=SmXXIYJInnr5S
zEyN;X{3(XVkKb%?boA-&mO2t=S}?s}k5>7U0d_nTk55S-reYTMSVQsCh@hjKN#zmO
zs@!eHxt?5n7fzZZq#H2i93$>@0Qdv!bnCX+6U=rIx?SSM)B)f`hcU6RR(0CP`~clc
zd;Y1XrzS(Y1pwziUi@C>T1h*iNWCvd4t?+M@b|ITWWcmjB#MoSdaE2b;-^{nNhgg?
znKrs5wFVhykX#~hpgo#G>@Bk6z0u)Jbphwa3)t>*udB6b4Kcz1KoD!@5`t#1Y4!Pi
z<ngO|aCrvHjm9Lpfk?^~Pwm|bCT`+-LQ1n(HIUP>3*~90IorWdTW}%q2<Y42K_$0=
zO}Ad9x`>n|<h~@JQz@`e+-(Z>?uU$~10PQC=5)gL-5rE{MdD{rDj|1TudxY$Y3YEw
zfm5uuBtxfRnh@WknCD#;p|QcJAX#sv@B;_rRjU>df@=N>iTU~6Sx$rQ$L{MqI@Y7`
zlH80coGRjO_PMj!1-V;6TS?t?YKu0j%^2fTRo#=_Mth<oi1(QjJS<U5OQ<f;`0aV}
zyAZg0dWaw!sUZ8z*@u2{h*F<^a-@*%VqS`oR|F?j@Z_1v<;5bC0tT>1^jVphl=O<&
zI{d96nTjM7A=^VTkIgVC0hy+L{gxklrqpTzE%&rova0fjmX=b$Nm3j-&?tNriB1KB
zX5t5;nE;|}4(0@TX?lK`?;A!3$ozvagFVEo@#c$|qitqB&eyL_%CZsx)#*^+lctp^
zBbSy{>4H~maa0p15hKyh2bHA;k^Xq%knza~l%Nl!;;MI{fy#5tq<8()6vEKvmDTLV
zWj{0PP(KUnzlXr6XZ}ZBpG6mb+|$U<leU_P2^ndciiyH%jGN7)Y{P6j+&&y1izxsj
z+xyYCpfI+KnRw^<LMj=oOm3xv9Q~>zGPSC=_`D(#@gnM>B3xU<!HDfVR|fmeQ%W~b
z>4^j57U_~wK3JpLWu4j(s}GuF^z+#m5xj5%1-WVp6DZR3n2J$rYSgqlMC#;z(?RL2
zNUDVe{QL71B>EaNw3;9-twI_3j2zsGDAOcqa!{(kAGm8=r5h8=rD|4*s?O34i&I7J
zY9-LlEPW8ACa%yOd2f!Urlz+eSYQ2b+xe@5FLXPI%A<+KICl<?zlEVc?ghW@gA5ad
zOS(yo`i5~>&F?&%_Wj2?uj$znCWio8Hj)WhYjkk`m0e4T+wW(1Gi%YSN{t{!Cal8b
zafKqU!Af7|!g;US_wzjVB8BgNxw}5^hSznTRnilq3WE3w@c3WR%>H1hs&1S(IiapQ
zXLc(RNny66H7DjnPYZK6A7+Iu_G`O6G%-Rqd1^DCwa)T+oa32+i&E4Z7#kSKkw&mu
zZdkEv+x%zu2ae2lQ$K{ndz4|Kz;`>GtSIoZsH(^f-1li)e?va=1h&mSUyhrWkseNg
zdidRV8NUDftt62v#+xTlSO6U!A#2!lTmLv@^e2%I8=1E$Rc6B0Ha7{;&3-W!7_~3y
zFy;|4(MbYY7PbS&TKsibU*oj$U#2WD^<0!SENYglV=*0Cm|ASjwDhJO;`nJdOF=1j
z*~fK3^CVOn4n!=yl(?xG`Bb$$mrm5<4oE~B%X(Y;=EyQ#V$Kf9w-8DKnPW|Lchr-u
zL~tgJJ*T&65f0hGMtGZ4<?KYVihj;(RKw{=8Ocb~dNxZXmQ!v=0~R&5l5E=tpbYfO
z8^|lnNxsllLf(~yc4QAmpk+~zJ0&5JM&TJd6SRYhRV9_nR@=ALWfNa_0L25rvv@gz
z@4Lv|7Sa;1|K7qq!vXbz2B=K)VE=gcU6(;E!7u@o-8NX<ZG7jQp`~j>znzIeV(#ai
zU~D<|^210nRBx-tCCxD+fR@rS(#W>}$P8g)CV|(vcp$3HGdQ;)8&rQ-C%6VN6~Kru
zrZFAZ_&_G9P=hgyO~lsKowg2H{Q=1`wBOAb5?OcqeE)b_M`lGHqol)W6!`pSDuENo
zqLgMmOcOqf?j182B)krWl8*6tFZh{kPseeus>nYQg=@R+yV>$b&ujJ9v4NvN*rC%H
zq2zSaH|S)(<EhNxvEU^RX30#tC5xogCbq<~FoTau&Auo0y6LH@c%O%2j7+z$<)&2A
zZ?Zxy42M(10ct9N4$^SR4^tjTMKNlUxEwug5Pdmd`*d_P+Ymh5671SYX~WID>~U(d
zdzp>W*)a8aJr@Kt&_8IF9(pyfilxeHolLVDWu)8=Onz6GDtMoerbv^M!Q*LX#-Z6D
z?3ZM-doQ=wwCQ{7hT?Dq$Y=Dyd@|I-?xHkCLOLjVKtZ#^=ldO5<r#16FO(|oA5rnD
z-=sBdnl#Mj3|LTp=`s9NRRRu#L7=Xs2?kUe^K#ubV4K4AQ74r-1`5T6ep>4Fn@41Z
zyf|I9{E53Y>j2Y|m&A7(UbCso%^ll%YHjOCC-zv#-fsRa0`JgqsG()x(g#oxgLd7k
zinB)G6pM>Qm#D=VaxtH_CSQLrW3$v4j{J&^ma~4nbntIFukEUb;&0ssGA`_NlA1l&
z!S{w!E7-UoqJdDG1PTw&x!FGpFqO@T+y^I+CSmc4SZ86%kjAxn9*X&+eD$?|Vsh5&
zh&ao5xxO3U43?2L+Y~k>RI0Jn9L6lUHW7@%4A%J;>Pl`MfyW4{((ZK^WQ6Y&K(S|D
zRt<+E3zDj0<*F(YC_(*4inN&)mHZk?O+`BuN?ND9=NFva3Aj1bck-eMmm|yhWm=`t
z9MbTLQKR`1X@j@5KieNy?)Q>~LpR^$9R(SC9_BMb<N59Y1&TOGqrlveD~P{w{f?MG
zg)Ab8SfX%e6Z8eGk8pc^Yyc#MurM=>K`l^HixW0qWGYSk)EI&Qn;s}?61ra@&bCOH
zRzS<ap}&^4IEkXGeXjd@tqc4)jIrT;-IM;qnuf>G!4iyjxaDXy(RS4=oj}mYM}J-t
zU1&x)TBYSga)o4^nY0iuA7VGd7QXv>?2D6)jnDOrIyvlUCfglA63&!&AIE!TiaH}e
zndbToX7XFE1rHhMQrw_l{VfRJHj3sy>%BEpt_M{x-(T^=j~fI>Lnm4Wn|kdz?BJMv
zoi4n&bo_8w%3RvAtF1A4i1D@rPf2+x5<6sWNbRNGEX+Y5jlUUA2leO|59*VI8UVk#
zDGq-`4*j7LE;~zk@fVr5cz{(#BfZEheOm*4l@}FLClj5SFNZp#H6($uZ8Z7!RnMy1
za1_o>0AO)RQ|H5k=p$nx2GpIsjSU=8E5_w&qvIdfQUNkNp$C+Ae9WT9pAn*5+{*fI
zSqpLxhsZVUaR2Q~HHP>Szl(QcS;!}68bVn@kUSgHAI1=(k@Qf6sW!F{>o*ERM;OP}
zYeMJ?R|_Mcxu=DD9P@5R3J<cNHDyPTiufAJ3bPI3i$E&L&s&nnqgSOh?(E{*1@;oC
zK4LR?Z@T^gI>?Lb79S6B)?QB){j(IDHEc?bKp+03zw)pX)d8B8#*HL`LI@tQL8Y%V
zEKWfhgRS5S#Tdjjr0^QZ!rU#Rl_pdNe^c6nbT?RpaHuO<;KJOe*}ax#%T}}~eDKl^
z!@!zSDkW=Bcawr=sQ=!RP-AJHBlpcpsaHt7SRCF1s6kVNvXSO$F7XvkNolnRkqpG*
z5^aXz*#nT+o}mcD;BwdBq7B~ngo33uol{9x1>aU@v&?rneM!AIBo#8GrZ5aJ8C`SS
zfVdo(9Qs$&v!B`Hj;5?W1#F0{iS`IVXyqL&@KS6HW(XD<m#%f&ecKoOu^|I29kj?v
zZcZ=Sgm#%&f8a1p2Prs&{=_TOil}@)#yn!HroW1i9;{KT8!<aA2mujMnYz>0`=Vh?
z97}IFfLSlMsMuxp{zR!*u+C8KRGKPROtfCX#H3}kt;en~6f29#NTjnvgD|B$N2_CE
zJShRA6k#1gD#*d1JRTvQ1T_Ff|CXMGpH+EyFspcw|L*S}&y%S+bjw3;Or_H;mM98>
zDy7s=%_KYO0i1*_a};W%B~DOT+G-u=HieKNe)xq~wGpueks*3rlUR0vyTtgN?^8tZ
zU$hSPVEc}lW@$KY#47p1qmcFU-~3UBhS<A<j-V^Eiot`YPz8Xi*6N1Yz$Dmz3zmL}
zqI|Wgr4xl+JlpDw!SH%mBs<CHh0M--pcC}!tg3b<B=d7QTJx5)@h%Entf`_P*?&dR
z_ApgbIJ{LJH_0M7h!~*&Ec8I!4pyKhIuS-b0?TFoKw2yKpB^?2sW-4rK&+2n-B~86
zg^HR*SuM*B7$pp@0Kry8e(Zqy4iG6luW7q_J+F&LRUm4sNfYBDsWD%d&_}vFu?{7-
ziD9@s`qeKRiO3^Gk(AO*>moLbDkaWlOpB#$k_B$r^}%=4iTXX~G_;&D3x3yqv+E2w
z6&=>&lBT>sTDCmoz4pSH9K-G<OhXINr!?SOQbPU<j<OLQ&0SQ>H@wCPWq7d1$;f)J
z*lOw4<ux1sJ@ou?BvLae5vaty@Axh~hnH>ZeiH{YkFRWW1Gwrs@Pjs``R@;9e+>Nf
zba)u~fgMnc;D6i;Al^GU&ND_URB0;@4sy^T@4bnl=RUaMlwslFWlQH{gx>T=3oCCb
zS^{F)&eQCf^U0t^E{l6;rX+Lj-TMS|HSK6LCb7TMNxMwx7AXL|K85@c%3TEd(S<sA
zIEBR;Rk7~}RD%4kC&kz8`$)RQ;5Z&(dWQBSdC+O+rZy}&;J}6(74O~tnW=a4_qL6n
z`>~v(P6J^$bk+5Pz;p~St^^vCXC(0Knny5oY+IHzfP1Hs&rHNeU^gf4lHzIG-#>=!
zDZc=D!iO9IaP0lO3N*CG4KB*{2*~8OR?Tp0-ES(%IW`@@Sw>G_X|xy(ifg37#LK4Q
ze*=ujxJCZ@G>4?+F4sLwBP%agu0Uf{Z&FI6UeL2=gpLZO>8cW&6Upp7sdQ*+X8J5W
zY);Z^YZd<WGE`-1pp1V&UcQ(sJ*fHTs;eP30>95XO)ISXN*id~6SxUPu9p;-5W8>N
zCstXO+tc3P#qAmx{aOJ&1TnZ)1bm>lR<Y`Mc7hV>jDP`-c<8M(rkwE~`@=ZSzuY7-
zTc$eQiIgW3_48heJ95SDtgbE?U7_Qyz!1SZja^}zHsGijUMjU_xI@lq1=Aw~WCB!6
z<swl<6c+Mq5?pyKL`79kMjHf)dX>zd5f;UZ>D5JX-HE*0O<L`M=E`bS#XT*ri=A+I
zuvw~5UsuL%$^c97L0C{dbrG*xt(j>0MwrPnL(cgcV3p|)nBaF|VC;Q1=0F&}i=lbb
z1<k%MFOJ70sEJ?1<rIxCg{eB0C+)f#kB&VBuL@LO%oc=7D~}g%7+`#2l*v_8k30=N
zW`il!oPkpKd1IX+5a5vubr>JYeA69aWN!o{z9#A6uJL$zpac)!`;DmWg?7~v5P;Hs
zdB;UjH|Gn_7XMg`f!&FR`8)J~+V}s)Zr9bHzSnQTf|950JJ{9%2}DN8mMjaKM%FmR
z1q!^EY+H%({Ly$0-A?b%x7Xg=Zzmo`l!yGj2qH&t41Mo+E~!jQQvPZg{_CEyyvT&#
z>Lwqfsw2@U4JY<|c;9lGh`ir#`&MCw!%TyPF|$c%@O`7dw_>ZNGC7@Es&vXl#wbe~
zpff^TDZ#}#Ve_K&3LzQYcnQ$otcD@jiVAGSIBq?Za*8N<|1S9_h|gn!pH2vapYWqd
zi~0esE-Ri%T|p8JIMqL?tr!Cry$8L-Y$FRSR1!JC02O<q<(g#6=n+hGI5O%dPk5yU
z7_8`LV!yu^D4gMUP<A#^MZhSv_tbWMi%m$#^%!r6npj|E=SHve?D-+{&DJ3o4pKSt
zn})h~2%SpmkrKLRVJuyry9?tHc<Bheu5awpsugRn)V*YiMOwH!a8)(K$_%V#|NnS8
z2lh&vU|r9|wr#H1w#|ucYhv3@Cbn(c_QbX`F(x=`zP<NZzhGVcc6U`*J<nZw6Mx|B
zx*wM<*DY2*?T=8ug}LdyeBIJx{I}fy>6{o+3=2-Oy$IwfFYCo`>LM|cYNqCriJ$y)
zc-#o0Mx(dFJ@+Fh(~1X4QZ?s^Z;plJ)5XKb=O3V!OI?o%eZ)J{ZJU_)P=a?T()j_J
zb*A7(0CeX;cn%AGcq=d?()tTl9wg=&R37$NaF_utz^d5;#Q|J!Ita=@fPxegX2cz^
z>y#Sv$>{$>)AaXmb#2?n-$NDN2DihVlFfknLzK(%j|c_tMC_Cs@0Ct0Ss9E&N#!D`
zuM{0gXW#>JL}0BKU?KmP8OCicW}d)%SEwsN<L;-HdC^I?l5K4b222#9zBbj}gnEEv
zps(;m$nIilH4cjUO%_cwKesY6oa_=KxE;QTDvbmLAZpQ3RWss==2Ydu3PX9>#~%9C
zhtM-WM-NH~{o+SIbdVJnO}e`AbNMk$CEX}J#p|BrQ0ZvjPl9pYQYKgr)z_f?Zgh5B
z<1x%=Y&Z^J7VAT)ki+b_Kt_<t&nEpnG;=pMczlqdr1IZA{XZhJRcN>bqZX`gR8Jbx
z0uXMdgORu}&bKmBN7k76jDdFp2z=DThIx;7t$K((1036iaf&nE`ovBTA$X{Qdw5Hl
z=CT;-aO6p?be9z@t+kpxEIA>w>ule*v)-3shP2%<%_v-AdY)*(mZ3h$gC%~`Djn`*
z&TAw+r*ZOh`Zl0sgi!!Vu0U(j>-G!u9ST&kPt0qITGh5F)ILd6G7??C4lDg}2&IZL
z$KB{_|63}@5H<3zOMBmYTpaQNV;j-X){na%y;+RDAZE(v&tjtX@K(*fO40Mac<<_!
ze1yg2kDVHOT}UbVUi48bh#!%kfoRMO?N~Q`bJwjskG4!u9+4i(?z00T@P0s627tE1
zV5)8ZZgPz;S0K{LS(EvvK^X`wivTd#{CgAsuU4u6=vp9r2deTW8A}ZnE0G<rYKRt%
z*>`O2xqy_ALo5@!?UGEp3B~ah4rCt2dsjwq4h_E`EZ#vOa&r&1xKkA2*s|}#&gz4d
zEo)|(AE#jg16Bhv?FL8&56mQJxK2R#o%srL6@Ru9Hu8k!lt3ivFObd-hR4U^KX{4M
zlZXWq7Nxq7igabE$@VFh<1fV`>0p-4x~_)s(dKVyfqOeX&s&^?g|4oTtCpqN5I?2g
z?*%@9#h9z9NKT8nV%^8%TMOsIx%=Y@a$^K|#BsSiRWDCwUMh%nRjUM%{P&h4O{I1g
zv!RV9=*1Tps)R+!@d_iGXTf+}!3r9UYS@VDs?dt7<<uxK<Skok&@^Fk`HkOCrOVbL
zTLnJSEKB+`HWfIN6{=3vy5@G4ISbV-n~_`{^e$7*(_Xo7B&PfHJPpww9v<iArB7?-
zgxjA6Hwo^{=f3P(3J-0!2R--MH+8V5|D+m$n5+M#vtti+w+AEeizhfBgDRmkSOoiQ
z>@ARdxXa+f;y8uWV<4FTkAVsJF6&W*aX|LV-1gt?=j!HTEjYemdltCR^#GVdXlE?J
z0H{Na5Sv5i#2P(}dy|9U#u;AgJaA(wQfGWkdn6tt2BG9pRH%8K%_BAHNr9eoHG9wd
z%$-NS%WSnYTnUuXUN62-#*D!!n-|$hTuXHxtroXIpguLL)fhr0EuG7Q+w9njd-<bk
zT~(ZozI=54sQfF{%N(b&qx7UQqvHB=iUKM@<`-aiCL;SgcHFhFwu&ZdD2UKDyqH|Z
zcD`9CsPhgmA}x7ez($zo;<n5QQii!FxXeQ{Y3;LWt5TZmEaBR>)n}B<5%JXy^_MSD
z&1ZaLpE@wPmcD5k(eXwgjuW3>k|OHPo?UrYKOpPi%y8yPzo9N>$!#ajve`ykdCeR@
zer;G{%}sx$A<F`c`MOsoeMdjhcZud{ajSYW`U5HJs;L(42AZi<Pptluc+k4zn|W19
z6BHDqs&K5Y)5V>pVj}@y;Rcqy_k$Fn{*}KS{D<aPnVGpG1YZf5S5P1SrqD9o)(2k#
zEo|cz*wb#M-oWd-E-@dbKqA6|TpF!nY}@OKk2e^GyEvu^c@;FF=7ljXAa>XZ*qOAu
zz9_yd>rOrjahU`%bW9*IH6KguYJwR<$Q_n1*RbG$C<fc#bZ{yK!b@EH`k->toWJE)
zWH--Z%yx4fIM^a4Psb^9q75n@I96UY%fkVc>qM6>E-rBJi2v>+F}V_d5==c8;%f&+
z+9HgQhZ)hF=a|8Xx*?sJh<!BHNr3T=@7SC@7V30o`-et4{?LB*^LNEHh=P(53R6D=
zS6+2QWnqt$=^Q>>NO#Rg%s~B*^IyOW*eAm&eu{GzijCHzebhWK&QAa9ZRP8B)^F)k
z;a^V*=3fH^Y$8abk5k*IOv^Mg{!x15#j9*bY6@((lP$BZkkoO+AW!S@KKCnY07}6q
zap5SC)2N<HIuS09llWWrhB|4Hqpz4C^($$gG6x%5v(;}Jc6X@f8_(1HFsf#tyC)(S
zOAtEPcgr{a0_eBHbD0y;)y=k;x9U$MXgt(_;cIxcH%`GvMLgwb>wLeP)I`E6Nbh|+
zuYBO*uC}uubQ)DICxZacW36d9I{0!(bQt=FkPQ<3K;hg}DcF-Qz-e0n%xH9CHGWWy
zp;NMER~>azjIah+(>Fo;8f#UO(dgfSF8UN4DZ-EN&LkUrz~Z&AIg5l&<(ZJAbcxSo
zTLo;iYIQD~K*}#}y*2)#Z|FXhh2F>j%dnBcnnb#p;-)XAO2XxN{|<@gKUwBGn^>Ly
zjp7;Td1QYF#ir~;fZwZ&XAW!5e2^OrLBP|42F5my-1?^Df2;dM8w_lP-WK(5*muGY
z+g$1rQGIt25C&h6N+heY_qZFUoL;*i_`HqtbMSqe;kf~L8C1kk?UGr*g_1m&Xk!=u
ze5GcRjt{b-`2j}5DeRC@(&kxEAIvlDM6{Y8MgTKiR%HZtC>%b@=&!|NJQDpXF(tuN
z5~aRG48PFgzF_7xL%FqJUs$S1nH&}R7EXwdEre_02b+8!f93GcQ0J`~!oYWcOzto&
z9cqwa1m|Pl^J-Sjnd5tWW<r!sAQDD6$8EVp(O;nt&BVT-fb;CBjoR!c*REvlKave2
zD{hd~fOf>?W;D`GV^cp5w<f<x#{JXkHk4q#6oHd0-NS;O7on?Wo_hCQV12G_j!jqE
zJmyO5C@dFp+7Kt@SxsM`kf6vjo=+v>2iOe<J4N?-Mdd&*cRkK)70c`)8}mnSUo6q$
z7TEq)AHs+LaGeU}fgP=R-;n>B>XRru>-j&3JPio&)S_d|0u&cER=h^i&BGOqc5Sr-
zqbOif(pDZaxnX|SbY2JMPz;y~VSx~@`j;UGQ@NV@Q+pHXdp$O%7ENezK9I9J^_@~m
zj2JI0@!1n)TB{2*%po|&$7<D%#==4`vKkPI;C2CPira+xsia~3OgNQraNe&n`p0F_
zf*ZR)OLh=@nfQzx`&ux4pq6d26*3<~$0-TxtCr9%vl~#0R{Gn@nc}oVwqm=fIF2>L
z(UEDHq`8kXO`CG2+QHa^a2|GdvB>QZHb>F8rA~iY!C}&bIl5hU$2S_i#&hUQ=*;I;
zV}yfL5BZ#9Mn(kgMk>*O2F_b*-_8e^>ODO@Em1aa{478{kHA!-1U5!3GKGN)h1}mh
zUYg|u;|cBr^#->Ol`mNH!lR{desk0N_qua6oLm%7NbGgFwI{?Z<eK=z?aU0Ws`c#b
zOsHqR1&tNaX47RXt`CKS)rR4lvRb*SeB~KXP#tv!ILu?jz-Tz4m`U<}#9UFNPd4L!
z2VyTi@nqoP73rO{b6jO@G4<SuQ3xPJ$R)?sR_UMYbff*966+X-ooD$lsoV<SjY_B8
zBYmM@ulfYRFGP9*oXX$#qZpPW57NzZ)_$(&YJRX5y-&^sIOu(3oo?t!?Xx9`&#Nuy
z_Z^ZE<@U!P*R_)`^_llk#(o_qw4k$@Ey#pZruDcJ<~?5;SS*C{3?4Rnn6PFExn?+M
zD9X#J%;}WnW@E7wZ5K6}SY#**=Xof?riXUkwBXvq{R|q-Om2nD)vD=!((<cr$j-N3
zsS(>T7BBp3+DSFZCl!<eBY#%)P$TwF(GgNd2Rzyr5Npa#UB2HyogjN3zu3y;^+`kW
zbOL~s2~LMbp4dD=?^jX$GBqp1K}Ppe;xN^VNwhFP5nDH2i>3eEadY0W3!|9xfsNp6
za?O+{q|L6}1OlyvG*yivRR8&kG})*@9#w;BR2rLXV~Hgoj8nS-=RV7M)^H7xX}wms
zNe3H3O#LZu*hQlZgOEiXzh2jHS1<`RM4eYG1Sm_}h;@`$ndK1wp!xzx15C(NX=#=3
zfNgc9j4-WytFTq(YNhp<RE-bg#i{OGGtx@_dTtIZ2$iY|Ke7>a)oQJh!BccTvc)FE
zEAr_hRSTRD_U@*wT3*YJR0bFx$U9V>jJtfa5X2J1+{`_z9?EwZFg&Wri{=cN*Uw>{
z1JeeJc@hj5h#DFb391?VqpjjviNywsaLWveqdTB%+UlP^MCqSC#Qm#9D3)6x(WHCM
zJbpQd6(1kltoJ7vnm0A*NAjw4@-#XlTmgJVa4-t9@n7sq;|NiepG-wD&YE!4OC@s=
z`;iSp!~xr}eiH+PUoWE!-g~gHnDnBaN%tj>WlTmdeZ9ck^6}v*yo6&5-}mpIVdB55
zV4sh*eo9<XZyg<-XWFKc3G!j@P-IPKdSGONh;aMixYt~vQ4BWcIR%fuGqvsAH=9%T
z9uKyK_gvndoOA!;4KSIh`qjN_FsujQqnc86nG*U=Q$GjT;($C_(rr5#t~aZmW4cm3
zp*C;$h!05JYb)4_ZX~p%S!6_g(Mg%VvCyvhz^D+b$o8~{v-uuRrFX^tNrQS%9*N+@
z&&K!moM1K8!rKphoy=t4g+~G|6#75)7}S^b1J$`od9XLrs(%wf5tt;gP0silO7Hs-
zg9z()*AlL$RbzpVGX+xUazu3E%yB%IT_LRNIl*%|)rKoInl){yWh_K=B1|NhqPwHX
zU%BoJ5w*R01l@TE1vW+PK%Z{G%Xm%xIew&k+lT80A=4LBPyazn2xE?!*Kj_CoQk*I
zYrR-7YyT~<KGE=(N*qz7y_{0cwxNVo6nQyh@%oznDYcLGH{&ThjP}`7t^lEN$Tf9j
zX_-Y(%Q&2F5&g|++kFj>wJ$7z?^9!L{gl&ZAb6Vklq8OxDVdy+RW6uzIMl}t$)ifc
zW6^iS9Af&P6*ca|ctv({Ef&Li9?xdN#hMW9P@xT0(nmM<rWV_C#Yf7y$&pXJdlRny
z%;LKa_<d>P$E?RLIV$R^EyGd2cJ*rbk!86{2zGxDQI|A-+fDLYlmn7F0M#Pp`_kX<
z|3n3G$Cfnz3)5x)G>kUE@L{^FuSL2vzmVwWjA=+Bet$uQOPC8%wLfK8E8PqCh#b(2
zPYB+2Oc8L*G7HO^TV_aK5kM%G2^tgBh6jWPg&Y0Q^EkTk`}%tvHc2XMNFOAxc^)KR
zhC4Eq!3MiwmIz0*dUV=oYbG@ew931UUbR{?IQm2WHey0rKQ+mHq3~IVPvAEZt?4<o
zni(t$*|Ycii(9;_inz4x9X0I;DJJYDi9Hny_2Dm5t=-w1%fADzK`nh7IopPR9eOfb
z6sCSqx?Wl5iCdP`C0#_kU6~3=ly)ivpXJ^w0^!rLsS~tqY<W_U9{1;v6`6D9-6p#Q
zy*E}!U>v-u1)V=zmg9J(rt_+VMP42KZeY!E6koFpk27ewN^|fcxuT3wrZ+wR!^h{a
z3SAg@3#$H?V$VTvY1j7lB1Vv4?@G*l6NOJEK?pW*#FrW1wPnPOQ$Vx6;#Y=bj<3+@
zyl$}OqW)nq{@oT6JfotxCCkP2=a%>4^fbrD(D%F3!nhGkRXoun3rj8ohYj0S-8Kv2
zX5vHBiyS+pxAB64AKn!bF2KiAPieKl``F-8*8u{LaP?8+aCd}su<5EOZr5HY?%XXe
z!Svi5E|pn)e;!onW%w8jx#&c^Z>gBNxMR<lxVNK0u38VQ%d<<T2x8*UlPMO}vM&`A
z0!;{Y!2Le_o8&vQtreta)QK$Xw-k28Utq2l`*X=JY%g-n*ys+x4wv_SQtlF|>re>6
z4K%+NxUZ2H@Wt)9T!;z2jxAo0)YJ0`wDELd{JY@(+f<@mPwUpJ=bU^Xngv-Bx|gRH
zSA*-J@yH}^#?=F*Xdlwkid0(rzuHW0QC#A{V&+83MdPRAEl!CoC4;q6JM!cHl}d8_
z$tS_rG7u9@{wn6H#14<ftF^*J;$$VClVN+pB>(|1eZ20#!WQ&*6n>xqWtG5uChfb2
zRH|7ueZ99;i}Kn+Ul~BJ;bmFdet19=b_7_LCBc0yV-GLKu$rWcr{c@b&i>Qvh%l~g
zQ$HL4Nl-RTo+=l!Fh*1XCrvk*++`*0d4btlMBy6{AI2#Km{zq2?Kng=Gl=9qB)`+A
z*G|x<Szt^~y@TezcfDJe*rGP6RFg;H$?!$AT$FAI8zL3~?Gu|^Mp^p7-!qlX^5Yj8
z%EaF=2A-Ex-0V5$BP?7(?G_j6+S2zZDI6Mn&GV}>-DWHF*Z&ku|I(OwVUK@CVh4kZ
ztFv-gaeu}jQkjAcfOgMi`$;Zr`4dnCz6Z-r3!!%LZFPsUAsul8iq@t{aUv+R+0yo1
z(#Tm#*u2Fc)apD;E5jY=XvusD-|rr$C@3>8tMbI*Y2C1EoDKwsEsODNTEN3IV*VKY
z;R&!bB3P<9Mq{4uM>-aTQ|l?JY##8IaY&ZS<McvzQZ$+56KDkE{nH1UY1@J=LOMXT
z4E-c6RzKyO_Y7m(T4?+_6p8L>Cy{R&{AGMoRX{sh&*t69u){M2H?2BlNM9pc5sJN?
zk=~w*lM|NyKfhOxo`Y;}>)OI4$4$65XQRnLxy0@!I?V!jMr|zJqLLA@tI?m>C*z!e
zRsqR$4GXfv;kZCsUf2&l7)?x8?zvP+j0QmYR6-=VN{^~N3YmqhqjQQP8#ekta%!_8
zB)E2@hxsAzc>+3lPyrqoIJ7CX{Yk?|@(2S|Xj3trGIfBn)JU~<E29A4jsEPNJP_k#
zE|InTm#XKx*~S#mSUMtTsu<|TXYVcY2)&`Gq=Y{Z85zl~l01FuZi$~giSpobsx~z>
z?S0IWs~ItQTdv>}DKAiH`(U31w2==1Sw5Hg8e_>av0Dky!oJ@b?Cfeztn0hC{U23l
z_?|ak)RBIv5#KH@*J_WRaFlI^^qLRyF=+%GuV2*s6p1zXNU8NMZnZh<{em2fgW?Lm
z3pi@0WBp1)u#Xp`&|p>DukPb91%3MiQHaRR%^iugTAf?T1a2^G6=w1d4EbBl^?M=<
zN5eDjmvd(ZyX+RPGeb+y;^NEK6h&QiAo$h#^S>`4xn(H6GjuMm56D@)flf|%4z3qP
zw3!EKV|zQ`j*gC|0nRU>N1)S%Cbs&sysuA}xnBRZJT;We?Ec~{8dmQ&oO^ioetq2B
zP$~g`|1A&<2YDQ}zYG4$anUm@0042?ak*OW>~4`({0G2hFdbyhccJO+7WVh#L8dPr
z?Q`}!UK~+oJQmKm08Vu<tm9=N`xlgV^!RvrDc_alzc-M`xU%)r*<GVJ1Ozh5E>5*x
zV@A#*DLOMk@GD|Y@oq@p`G86FYxm!@Z|ZjTV-ljW7@28UH)}dFGPJ&W^rIPps7a`o
z2FTi)RY<+B)Aq|Xx={^EY^OkQ0ETDHsx9$7fJq=1EIQm{n~3qN@#6fcZ4}7lczyO0
zK$A$G5bmB+bWbmAPEgEKmz3_f7gH|p{dFa{573k1QSP2f-tZ_%Rct|zk6=hvGqWi%
z(VGnY-e4m|eXqf6V9^6mCMlw`b5@$LmbZWXK6cEdaV<=$B(1cRNI6J;khpO-g1HGI
zi~7&&r85xOnRtS76TK=BI(?yiQ!DWP`8;)hk}wcN`y+eGp=I7`WhUF+dl2^x_J^vf
zYFJ%CK>-LMq939?W5>(KYHQplOcDWy?dHQUgLnP!R+HJ#MFoKmJNN?UgHd-E&(qAQ
zR)09hSbyb99*bpFe;Y|2cK**HO8$rh+Tsb6hB+$GAOOMOY97zcJbEYao6f!!bjdPY
zA*~D{9_|nt#2eVyTxM9;szLOZrpV5l2>Rcgp0;Tg6{(9#fD8bl6=VgyLwM3Gzq?3W
zU?GD~Z4@<9Z3VkVFhXH?0c8+{wm%SH27IP7*xH(zPy06AeQ#GN{`PP>UVodmb<hhl
zth2RgFSm#Q%=s^qBh%HAz3<}$o2-k`tW%PQ97W5kGqEGHttvA)v4FMFLYn_b=O+%I
z6ovdVp1?eLmm0#;bl;DxE-LJie>N$42?}0k^+<CqR~oln{vDB(0<CG==<)-!xq71|
zkub3R>KG;`GxI0iBJez)BdG%y^TB_`Wn!H2AZyNk75KuYaSw{79$vn$E>wtST}UzP
zQF*ZBeE*vtR-@OAqs){?cJ%7Q@h$P}dqKBA_<>GLY;3&)-(p$nBSi0W_s!m~{Rrax
zi|~Ey8qLPk?ESMP{H(ogNm8P(eyzT6WTmHPeODHyBC&52bK-IBNt!qcHg64+^nWKO
zmeJ7v^|JOCg_<B<`Z}L45&SyQrH{dlc5n51?UOWyA-@y&t{SSQvue|J<8~}w$X9tu
z*#~%#K5Z+acW2mRb~qxeb4~Anl~Ad|d30Fo=-qTjSl?0PS;UCFI&5HZ&B`#b?Bujs
z!Vxq;I9+Tic?)CsnQ1HOHJ}+?Jwi{xLGfc!`iY5&{e+^Wp*feG-#*U(MxyP@DLDKP
zK5Q?qu+!3+shJw>)@#&U3w^Ordf3XwKcSfszrp|ot>H(<)0u^&Aez38dPCP}?4q%P
z3918^ibv!hb8|>J5XSz+4ZF>?K6Kh&9}1xQgDlM{!^XnGRN&Nk;ZlL(pjXZgQXmgg
z8is6bzYvI9LjL0D0N2@TFYy79ohX9Xm6RrVmhXnQXXrw8>z_jIcB(v2gXbjYxr>qk
z1c_8*f;aD*X0Qz|g5&_8857v{K)Qi}ps5$2eI^pjFBt&r5TJ2hX5C91Ti8I;7};2E
zD}SqOpDIy3zWb$kj_!1|UH#3pX7j-*t4XaLeu0Lq*?YAjPsf3t1eSSwjhuzFs-S=d
zBdH;F+-UOGm@TnBE^+o}hO((j0|kK$Rb?|nl&G)4JTsb6=&j>^Nok3@^&tK^Wk_52
zRGs^C=gyX=_Q&UQ@5u*#oQ~cyz?#91gZWSUOKb0kZ7v)-I{I(ot{~uv4g_akbN{9v
z9y?~|S@!N+go(5I+nLu4*FL_RN-H}C(dSg;pL6;;7neS4vL6aXH$JpsNJ!^0!QO;X
zH-1tXoCI3R3zEWf0p18-wM(ZMrK-;ZsEpVy{@y6E_1F4$g&G<HER~FzR2~{}Fq<E=
zi4g+!-H=YLDZa3$O&Zj9Px^Ed+(odBwrgW4v(!A!qhu9ef-m5*h47iIBLBJrahrfL
z!?Gk@Xayw~PnT0mjewlm<L~=}u`2@0hQGg}d7UG_$(?$M;D8MY^2#ES&Nifu3uhu)
zW^A7K9UEjqsOP(Mx|MQ4dI}wRf?re-%Je`+;vv8SuPYX?17bPZ8XN~POl`%oQ^c<(
zO#=!pIl`)l7A32fw)o<2BF(lym!u(yOEyt*&$}xJ&rsp5jJ!KP(Zgv&cW|c)dK@cE
z=RKesVd~pckAlumTxqrC=<_dX|98rF3A%Q{8L$Yjuelfu%-?S|*TB9pRAFEL<27;s
zLxZ|it@|)7!Al?H-8_+9Xj1m7N!;{p9-(MHjL94i;DZy)OPENQ%g^Ln0;oH7glw}`
zuN@zYnBU)xozxi`RLy^Ha?->LE0mrapPR`@if&(xI+%gPSzah;cr;~9WwCDxmcJ`d
zSB-Ia5FMb9k6#XAMMBBdP@QWtoEZ%P@aeg?aAATx{#$Gg;A?s$Z@;3GnN7ZFa!pL&
z!2D$MUuMT2e}%X!X7Iv(=-e+#k{3q7_;FYaS|q&~#w+-US*UE5sVEA1gwgKlTqN`}
zNhRE1T#*-B{Ms=&tN74zJDJA<C%P{AumBl@R3#Bpm|e3NAQRdZ5Gs>ioMz1vkEU4>
z?=3;wd-?i!p*4|InKvi<v%z74ZU-XgZH$(YQ={4)<yf^4P;2B4p(&;oQJ84Seo*BG
z9yNNG(QK`27D~#{n0D$rFNQg6J{ZKIeiRX=Fjf@d4Y?uP{_N3pA4<jE-)o!?+~eHA
z!2NC~GU^J&1Ipt%bR8(?AmO5h#bsjSK)wUtb7{(Opu)-v|3*(w_4X%B!29nL{#*bN
z)El<W9p%>;swQWNv%V@?k^w_x&*I!1yZRqvw@zi1<$IH|Bu5#3G&uXZbc#2kp6kMu
z--YOso1{ZR`HhTv!H1fgiUE2nPxw5H_OJQ!u22au9<f}<SRK~nkBrg~3kZmaG11Zg
zG%ZRz^V|v1?b&e5qWF7o_ti=d@+`3Qq~aH5TvOICkDay_r_=VnEPxIWKh7tCtaRuw
zq&xNz)g4E=3tw!KFlBmZLg;cM6{5ySNi`Pk^FHMUroyp@l-e=!W|OHZGYo~;<-p_!
z$zbIw4#gUd7|n1c6BVjl2zchkDftFRRcX15i`jULxWWv20`m0fssX2#s;<Dq2pC*L
z!+T{cMb)%^n~!%S8Jcw}lVoTat=ptn@nZIbK>jcV&ONZ)N?!UlefP@YDTESUINt&1
zN$0r6PB?qpR38(eti2C&U<!x8wH*M=X#dOD&f$GOto6<5K*h~YF>LJn+M%C6&#3A^
z$STK@S;S<zZe#3Cmi3<?z77OFv*qD}13AAOZE7-mA;bYCkk68gWe!H=dE+jQFL`!W
zR*BX4s&j%>U16kXxojgXFQa%qE-DT`98#|lu*XTk;*ubdEQzg)C{VgKMt_+}lQF}s
zhQ}!lnYD+Ls&PY&>%cY)Vx=%MGs`|-PwIa*tTzv2t?0VpcT1Iwg@QXEC<)LA){G;S
zFE>n-SErdfS)BtVjT)2*BrMEBd811YE;ZIj02BIXRfi)c5-LE6lsJu8P}F9NEGgRf
zJG^Z|1Z@{d8XIy1$+0Z2>Si9w2!oMy`60TC+Hzj1EE`Qflr=r_AsXrE24gYN+oPI$
z$Y#Dg(FvfUgn>MhSAb|~X$nWW%sDnjv89Yjk4ij0k&ZY)sYp`cE*V}5d|-iDc^Hi&
z3~^L<cCyM(8w63CzyfIHmA^1!5%_wY^{}%6IyBs*;+31=j$?bSuIxLF<?yP@%E}N7
z#l#*V(p6tqNBL7fE<Cql2+~%#Hh9=1JmF-?_XpX#`j_<vWc2P(Mlu>W!W;X=L0l|P
zeZcw+`jn>bSm;JQ#O7cFiHRf-;AO?Z>BAjrz1d=}Sg}qHLpo^N7ZcX&97RY8ngZ<^
zqYp@;pSj7>u25OXX#ImGOz6}duz5{5*tmw@D#Hj}(?(A8w_z}Sd04|j!?sL%Rbp5a
z$0N~B2|$ay&!PK?=s5<LqdQO<P@G+DIGMS*nb|Qw8?*beIAkAywuD}{_Q~vWQVVd$
zcAAL0B6VZkG&<sfCi4;sL_^J=(Z&VXE9FdJ=C2ZU!3k#ZV#Ka>=#d!EAH%jK>GHWG
z*eFQK1WVB@qsrAL8t~bfQ4d0qb?%A;P%PFz=YAE&*%_Kl($M@`09-;Age!Wnsp-m?
z35SqRr=M5akO<GWlY?|`2!uZ0FBE>ut^0XRr2s6S1Z%hKVz0ZZ3V?JayaK5TJ`%Uk
zz|^KfL_<lbU$n5YrX%vlObji0nkB+?!u`Y4UKsx8#E%{)@@*pHAj=qxuKq6r8>9)L
zc)~Bd0}!xQP6@_%@bEN>`V~{njx3f4cb5AZ+^>7JT2Hmq<@5p*S95Q{G{kM;uJk~R
zAH-(tFp}P&BU2E8fysHZVZQ+M+-)Qp`*E7hl0R1s5lgi(SkYmIq(*?|EYldF=8Iq;
z5Gd2vq>6mdE$8ybcL}x>8D`%)g$6PW1d>b+Tav|p+o*=5J_DSPX}@yO7b|x85W+@C
zI<5FIElSjSlGUj)3hRIqMy6<)2%45BP(AW@&Y3t>1SR_8co(^XqSbe6J!Q=?e+*_4
zQsl{UWqK=C;;14tJaqFKeN~2LwN&m_ro}*;+_Cj}W2G%+CO<Nap*tTm^I@puE0POi
zav2I-aol6(g~{p>Kt&d)U;#$z6N*acvk_0ENNQjA;8F1}y>)K4WC?gw4DSbUp-lYb
zTXxK+o9D*E{|myKGhvYW&mAkaTMfgp;c0e)aRK%HC%h+I)k~}EoL)gLik}|>pT>_B
zYVPcdEQ|4(@D0#W(W(30k)ovgM1Ty2%$<kcRUWTZszgAnM5`7*z1Ex^*cjw72B#Nh
zbj+>G54C4qNq;a&@0{-bYRPycCRz|t2QmwV_$*|UK(L5!qDF#RcHksLf?gzKf+W9Q
zprD?8PdMm%Gt4Jg5USq>ldbjKdf!&O*s6VX^})!1_Eh6NjN`slY)_zs=P<kD0bZJw
zlZ$JdynsG+rGRE(H)@}Hbf1`-)hU%U6<Y|vMAM0XjNgAKD?1uLpDzF}<|gT(#loHb
zXYhV=R^ZFp)YtEJe;A0tjsRr>!A~rE`&#U(;Qdlr3D0s-!r*F-5cy=Uw-1z9K(8~h
z7spU4`k3p+6OJEs3~&wj#DPc6E_g@US`2z>w5Spkt<Vq?l}+R<1t&qah@wtR6rT=F
zE&Eks?gy<zVqPLpT;z}<`qPNW6z58Zh)dVNNrOpUt6*eFsXm~{*P_{ZeW({^q8Ws#
zwZ(8<8vSaF1hkkWzvezdu?lKvqWng*Ai|P7GQUR=TCBJm+e)R>YWxnt-23L`?QsiV
zv^ckJw!RRNke@6ky7&}BF!b;2(9p|~pI$0@9Z;boEeNC;)n(l7?D*bqhas)E)Dvl}
zcbh*K%lul6C8<3Dz7_aL#m+*Em8O?Zr}K_bGd__Q@DQ22Mn}xd%=mrYnoL+FsjxV3
z$?%N2$Pop^OUI8BN-;o!I$LbEogUAB`?{X_6Q~4XO<_l9qEL~Yru+o|u}nPm$3WVU
ziow-j?QQmjO4Jgn+YW}hzRm%nsTCe^(x8#o=F!~T+>)gZ*l~wPp%eWm$(xf<X*dBl
zY->9vlj=Y#)7xUAf0D`}6egTuXKX2yzv_z_gBkd?qJ<jV-_)X|3H7n8O^^RA)g>Gz
zx}=Kt5I=#T!#;S^HfUL9VY=)WY|Oio1UM)fZery9w#iP96rbxu+`WO!?9{3fGSFx2
z2J~HSwctmGe6BMGXFB`-lZJjb1PaD!Mt~IP*jWbA?H1c_a&x=$9xf)yko(U!I}Et+
zPY>{S8ofXYvC@SICPA<sRz%?Q(~#<6fJsJ6^+iVojizJ?r1@-4%2{BM!PeW)q`#Eq
z2CY!F{1817n_%`8yT<H%b1m@Tw_}e_SK5;k2yH3;|19TeH8SIrOS@A@n+KzDC)tVp
zz)>`sr8(P5mxA9$R7qr4YJWuE24n&92bMlRfd8*V7k(m=U<(Ko9#hm~-z~`~!I!i<
zb6t9nzzYQwjJ>t$``xn<eS}7vjDw<#&rbTkV`JkVY0b+U(IGeTmD^IsB#f|URXn%M
zYyXT-ynw?|D~T(Wac-#QhUHR&(MGYv{Y_7jQdJ&`%%)|vb;(lEg~bpx64|wk2k4@D
ziWo|*?IKS=ul!t?()j%4XTV>}Om<F7U3Rf<Av-bczjL#iQ{Q~Cyk1}UUUl~uE?dAa
zhb_h<Wm&EGQhrWTEyX$3W2MrR8Mxd+&`>}jnN9B0;~JmWNJhymbf7bRaGlq)osn1z
z-V|-S-xt5aDmM;Uqw`4(l4y0P^R^UG0wmZ&>qFY-b&~;*eC~F=S+4?lR#!k6ZK1fG
z$Kq&bV`IMvR{2x2ZER$0kyL1CHTCp*z1ccJ76Ow&uLu#<b8v7_=Ty0Ro?7j<Vg6Fr
zz|;U8aKs84ai$2fDROq%lMgYOzHqHyxEFSWC-CdQ1x)RS!5NTZmE8W*{QKm-wJUIz
z&bqxR8`)I3y*-=(2T(ETT`Lj5QaT(1g~zLZGp!9xvB7f_pdqTmD6X@}JcdvgcVZQx
z*G6#21gNsgy-fBBBv=1nOV+cHB(dm|qA&8_^E)bKaU_tNwuc~{cNAa~a=V1<ukC=B
z9yW%nl**sk?}ibYwFRHjssz_NDT`=PxH;K5@?FI0wL6gu94Dp303i{Qvf&U1luHn1
zsP8XvgvE{ZKv^T$Keclu9gg?iBm)o|udDWBrky*47rSnJ=>BB(J}7q8P}nv1mjx1%
zWgRQjN@4L#;dv^B6bzWWr6e=Pc346}0#GeiWIh8m$YH<DC_#VS(rR{v)8lzllmYuF
z2gB}=ZvV<MI!akl@%Cc)8k3_L5<+{bIqd)No&F3>uykPZ7sHQB7mWOTFU6+~B2zW!
z8*l0D<W4FlY?e8LwD`3a`1~!H@Od7Z<j+6Dn1wqr1=Z@3)%o4WZ}+iD6w|UZVb0D$
z8P{8#ZW6J0dq<KcDPi#qwi`Ldh{Y|b+*Y<+Sdcy~F6JRV=RZRW(M<9WXR!5gRDU*`
z;3wy(W==9ShhuVytPoxB!mCv4^0;laISwM!%?1%)Ln7eqj-GZ+x{nSArdlEOht+o*
z1Hbm~i&!V~V>XqZ+<5Q+Yz#Suqr@EOnXAp_i=D>CUQ9H!WPhMs)F5RKcvM*y7vX~M
z`Bn2$i=s*_Pm2xLwfS*O94P7uzlW~d$MZdeW;>TLmmL`^MP)U`t{v(O;i!)v9{O@S
zm^eQXWbwGkdxA^tjSH&Z==_#q{Vm>1{d?@9Vv(s?<qeB{x#_AzF4LrY(e%5=+5}-v
zaMgOS5q8!<2JPjGefEOiGtmJTQy`$S(c|9i#>bRs_PE2s8vX+Dl&LY{$ZC(BijN>K
z4xa~t_RmoU12mv`E?60(nY94C*Og3#ft_cKBjooJbk|>2gDR*kK-2vkShDJ5o^fV#
zi)rc?vu&;X5qs`O|Ia3l`>~5;)?(e0+T*t06he93UGlah>P@F?Sd7BDrisDoqZaI!
zN5YendX)2*vG%>)-X7$YbwIRwX1n(cSM};<S~QE?U&oqb{GD|+>;0TZuwWox-(aoo
zJ^Ot{|7-A1<m)qjjl4EXVnl?G%jaZ<25`fY|C2dt@a2h^h3^H*okEpxBmdOBH}QKo
zoquN}7N=`yt|y>|!SWnBx)a=1Qq(UQn?#MllT@HcI!0j=r_L=eZ?O$euF>zclj3*(
z;}2~qs(Ck&HEwYKpv)#55KW`Zv_NT{K1S*WFZna;p41PU%W)qpsNwB)3<v|*g-#P6
zYnhK<TF;+G-3Wojykq!#@BaS6G~WrJpV*y>c-@|Sjl>E|?@&vOocqQXogDN86zi!Y
z)$)5i!Kph0VL3mE8W!k_dSf7}-POad2BvFaIsAPRn4O+}R8Wxj`gmhwKz5%Nx*?G{
zzH`u#YHu-pPApTVT$izlnrL;MPghD>7jh|qq@k-8tWY)3JQXHI+>ku3Cras3qZihW
zE;qb}P%Q5#TQ*eqZ4@+t5>6&Nz6{^7jsm~_L2wsO3@3+ry6IeVZKyH~XfF!9)!4^x
zSBj2BL3Mqu`t=&T$!!9=_EqopRHt;Mfp?<~q6ISqlW5vtDAkZ2eML;${{${6nMu?l
zE{R4&bN2>9LnaD|jt-8l5FQyC2!cZ<8WeoTO@Kn^lk%+c>Gr9xoLz56ua@&Z8+{Tj
zFk8>Z!O#Cmwfp(;m-lHlTVSQ8=qpFSZ~qWFSLf}AAh4{d_OGm&b}=2t?QgXWXQd)d
z9GacIGl99rk{h!oN2vybh0gY(ZuU)@wWg;7h(4`C^cx?DxKW)66?p9*5r8ONg$SB%
zv;`kt9^xWb)|}@+n%->JFo*kH#}~0{fPT!G3YCWL$Tt2U&{kPV+k@8&R|R9STNaq6
zkv=cLlNt|?3ir3p&M_X&yqH@G@t&ypa4YB@_CA`FF0gIHvDP6T<S{j_a$wxTE%j2b
z+Y?>LGt1Kx$P&^=Xm4`C@!;_HU^!FpGOIQf$DN27X66|g>b0@IaTASVj+0Zv<*9GQ
z<94AM39q9WE{=>Z)hx8pyY3^AJy~^dkuq)=-yG)DN4KC#-$k%|)itI-n@w*MrOZGh
z5h!(1>MKWEnKpr>vZbf8?*(MExuQ5zF=I~e^OVc9GTMRon0&CC&jzyg*a4JcjoaRE
z<_KRrwt)bJF!nK{`RQpn-^3}k`A*<S7qc2LDQkrvO{U-PTu7Q0f2W`eq@T6&YA8Nw
zSn1WF4nSWNXx>RXwT93jjP=b73wHubL2ATRWo4Xmb=Qu-+(;$p`$5_*)^E@-jy`-A
zoWAv^%N6q@a`BCgjrGDn+PY0gdr@ICFNF4^K3pnU|Ku=lA~ZQEbdW4O>3|uWKw(YW
zN1)<^JxL*lS7^Eqt>l1pUW2Rw#wCYltbIb^(`alS{Js_~oi~Y7cGLMMSaYzD!c=m7
zW21<7Hnh+O3qj+%#VT=d^W)xV9HF1t<SFoN#(66yrbt)#m=Nk&Bd7K~R?l|tX}4s&
zEB+U9scRO_)^yP6xe**kZ~_mQgCpms)j%~V<PXObt@65<81XFPrkm-Q-Lu6~ERCU!
zZ6&GFpZ<q!zxnQJjO?@m)6hykGt|nvM5$53c*e@JbyZTaGgDb=1hUzaAV#NXt2Nb>
zQ8njDrt|s5((%2t(EJjTj~DprW2!7#Ib+4#!Yw*snmMuW>9_Z}TK1Z{uKGbyL76WW
z{^EBIMCfQ?=9Qkl4}c)DqG#NbkQCCD95J`@vT{yJPm+9N!I|64xdX<Mz>s%fjN>H}
zfx`7;5AEC;S$7Dp+v)Y&`B$2N0hT6)g&<oI>bB^Mhk8A>jl&@#zMkPO+WR7rMP5m~
z#Q!WqG^4Q$ySr9hqNJHX2aM*_QWfS$Y;*;55g$@vaq_&r;0BfY(bEGbn<U9u*lr-;
zj-=t3mt^%LdA+jQpdgOF(uj!UaQ)ifzLXPfDAi>VAV3JK%K4o$5-5DC*kWyEO<1)6
z1~)b~(%130KMY&&2;q4agUg|Vi${M>;-u-Uywv3S-7L;-@H7eCly52sI0w^sk4d`o
zGF4JKvqMU?OhC;9V|Rqf*u%zS?rmGVxwhGxm1Kg29m72{Gt>F=z4;t^*H%kMC{wJz
zmka#+?YVdM5|`W%OY%~F`f6<D68((bNaritW*qt~HdoAtGlE)!X_CTBXhE932bUv(
z*MLka39V{V!b+V1V)s!}#4ZZjb(|%9)PZtx;!*OHxFOb!8zkHWIt&&I!ouce|2r#~
zCP!dHlbv9K$0Do^3Wd38jYkY{_)&@<$h$0OeEQE)rjahUxb$md;oxqFPDq^pJ0+A+
z%py}LoDfVF5=;`(5xUARU!Ske#E>?Qs|~#2-{;aYB?&}qNWorFuw+k;j&HMzV1*4X
zVxOv^M}SF}k}uY@!gacaxdv(}@$JfhsuDmlq0m3j<^5(9I9z7+!#_6)lfkN+s;WRX
zgV^2dIm52{Me3f2Lg#^A3;q|01;gYL;&FWU&$QjQY%a%>8GIb5wcoNC6{nM`X%hs}
zTR>P;CvByAeywh&_zs4>Dh}mGkz;-p2%+IuVzBVQoaXx+aB`tEA3rRuV{%E<e26yZ
zX&i}pHVb0D_D2{6bBj?d&idxNzCa;1{v|N;x;AKYVdU;jufGtEqFWT+M+c7hlsyJP
z6p>AcBjBUqrA^a3;GXN>MOzRf1^Y<mbjx_nu*v=NUHJbl`>x1D>y~*9;n;bqqO>{e
zHqn`cjd89#yaN<Z*gxc`vbd$m12)kE;h6SRdPL`_JJbmwW7byTNs3hKM1@c6t#H<>
ziIDcIn@#OZ#r3Ga40FsOr{Cpi*mtsc9q;azO`i^3Y?6T!J<b*wHB3Pbqm_zTKyU#F
zZ7f=l#!sQCFGc}NN|idO!oPo_>C3g2GRXc)|4uRr)UW)>8^yW>F4yWcr#u8|7FHCs
z+zrYToBp{vs%U*iP{#W+!M``~jy?<rlCrKKDxu3?ER`9R+#VB0IF=l-MmK;NoSFD-
zt(=`pD#FhJ6r+6mWExW1E^^15HQxZd)baMi^yAkNO<C?O)lj01g!ez1S_PeVl9%)M
z&B{SJaRg-up==Dp;W{j|Wb)O$n)MR(XJ3^WXrO4Kj=WZBOPLdmv$19gAUqJi_YBA3
z>IUCWcVh1t9oK`xfTf%YVApi1l7iC+m1S2{#@hc8Fw(@SAsQhZLk*YQzLZHEB7qfs
zfO&jU$U;lPYAOV#bXP}<^#n7+i)e<B$%0jKtv#qUyf3ocynbDD=R8HzOBKCnYB^;^
z1V#?2RyxTz-%Mj0^Hzi|45x~qNoVY-&40f)7`D~(XF)>M#|HT@F0`ww3uU*FRLiKt
z*Tkhbr&i~+w^Po|`{OM|sPtMl`4!}^$V{3v;>S8jQL+WBe8$yG$_lQ2n?wJ}CSDFt
zv|O{IdH!kfM8-I;kk9TA*-6NO5%FKrKR*y=ElH<nxW=;UN)#ln0KRjbNLC9rmog~S
z8pB#>gG@ty*~d;jEcQD+SEcYy?^Dam7y=%?aqHZZEEPKUbsU}jf#d20{`(bna4+pj
zR7sq`0mamHqp6Yv)zrnV7e#2A#CO091=NxZ81(+TUcoW<nGpGO2=7|?!9;xS?0s!*
z!-+#spJ2xc1$?6;$!!(2RTNoRsmM|9(1=(1f_@Di=40OQs^?Til(f#HVSE|f0Q?U*
z6a7Bm{5nt@o3s)!hFZMMLXFMh*G9d$`B_*tfDE1g`PJQI%3oo!@$unruv~=y6#Xc=
zqMw>5$eEfsuK-2JqyIO;>}bXpDC{Fo#F%^^XaP;?ocPB5;C^w)o5rXk;l6$*Dq|F5
z(=>2zt^XGX(wGQ&A?N;NT7n)B{Ek5l#(>fDv~vSQIf){{!5;Qyuqn2{JPDg0?VEKt
zl;jVO#tdG{j=A~EUD@0Gio}Vw!MQm4Mr$0zw1(8Mr(4p+^~WR^F%M#;h7UL~M-w2O
zFNfJsP{88b6aZ<D0mdzE2U$w-yv%jl-J&pAL<K6gPUv_uhPom@CQ$dxqq0#q150WK
zCB>Z*WH6f2Pj3jB&A4<qPiC7e<W<uoK;p5f{N`Sr2W90+_brVm#|>`9ty_ji+xSno
zf%M3C#%NZ6Qzt|(__%J}4pZuj{h+9zR%Vk_9$YKXX>TnDnG`G051i4~#~hjQBMdLO
zmmK?PITw;4t_@P)g}A1FW^8N>#!y^*BnG1Q@0I<H%Lz~Ys|3yZ_28G!6PLkPD)CXn
zBtvb2y@o`S=_JOmTi*hyEO$78A{CVoO-%^t00}F7=YZHb0tzzO6k_z|kr1v>mas(1
z$-@EO6wer+q*ht2%?6U{VLr}?sL|xGwV-f6k}}wHnWJ~jh|{JxkF1VEKlo`)zS$zI
zq*J`;xl!%>qCB6RX^DAWb^fd%VF*x*{<PU;iP}(bg*~0q(tr*}SZ0IHDXQQ7yV?#N
z_k<PvWM$DOBSR^oFuRb+_End6OaX=5cm(#H)!3WrZ)5I96}5fVs`&3!mI#cfE9XKL
zKzlX7(3vZB5OWVWiJHt-X>g(5%;^LFfGu$&;tu(CLAu>hGE;1w`5+js<0)kAV1eH$
zk%~8)4V3z1xrb#Ai3|26Ug}~YK~<|Iz|S?WSi(O&nz<SQ`p^3zA5^E{V-@@-umgCg
zIdRXTF5S4#om0TBE)k^Nqi2nA>h3^sh5fcSfllk=5_Xmuq;S!TZhmMCTkURPzr)YW
zJds&dj*AIwCN&7BB_#9`c+bP?w;8=MFQeT$BRo<2AD9hq*fmk4{`n1X;C?+!LMAl|
zKo!g}5COjvw(z=*^HQ{V{njezP70+T7|!g6f?XqjNutmWST*W4I+B7@1=C7%bA{Gs
z#7;A#_#_dulQSwhvte4q#_Tc3ZEov2JK60QU&p~7<dsY+Xb+hSVIJ()?|mcZTVPma
zkB^P2h2(N2!QrmiZiU@yQD{<hSzw)m(4_WUH4KyZ%YhzM+w*qr@=I&g*wUuX&``-;
z=PLitdJ-~V){+y1$$ESHamJ0!G%g5cEeoTP2qJ6s+*tchY8@*7hRhiEGwY0!v3gkg
zf&T8EAI>fvGetW}E|<`PC<XxD(1zJq&XQjyV!!x!YHmw@b{#@4U4i7ljDJJr#~<U2
za8@#JC;P|44MFTBa}Z*_*E@=*?QN}vsZ1P#(CDOXg5j<j&r4&%$<7KagDKBsksPI`
znCTSZ5gr`6vt$#+bU@(#*-(MwuebZDy=<-N*5<m2lQr+<NfWm!vGLPiA|ivOIi6N}
z%ozy@=mWsf>bObl;nU{`Zf$(WLVB1tTL``<$k`V^xcCpSX9c~5!hhrl5(=`ecH%xQ
z1i<P$4%-&F8ScXMol~XK;R88QXQkHasfb>4-gCOfbQm{HK>;IB+Z*+>Pr8Om`1DFb
zWMauRrTmZO4NOVChKO!tEKRX<y2#r^!z3LkwCWDr`d{6%cC2___+j&)tbT`FoVgw!
zAs-R`WBzOP#-oV7e+EkqkSx>gfgph34usu`-x93Ws7r{L+n!Zg&2K<_k1bi9XAw;2
zSC|m`HX}N-5WxDlE&=|VZlZJte+?I=+(?`Jn#=OT@PJ-6aWj+ShMpO{@VPcGier*T
zy^j~Ze(JG4%*W~)@Z*zC>rL|sMDBb(wK~^`TrS{2_Hp(pYkdD(sEO!ea<n$^2L3Sn
zU@~AF$JcVq=o3qR7!lCZ!B=7~Yz3sWHi>&n0XO>pE-EBYJN)dZN>spGlGZIs%wUkR
z|G|o5JPkt0{^byW+Sk1zYoN&{CAq|iDi|zGdISjY`@GlBCRuULxyMrlkP)EeS8Efu
za(pGBbQY$fzb8r|FVlf_0uc-e3I{k>x6Y$H+f4GAf^K5E48b#*^~x6mQS_HzVuBAm
zp=}!J5pXb#YHW(AtLiS2D^G$*haH}eGzfZ8)layVIsm`!%ZABRfF{a02EehHFoBUL
zOb9K<$ruJS{OXbg;{Nos;~>_$ZZ-ye@6eOXR~&&4g{No6BzbhW<SKkaTLJQ394oT3
zg-W|ZVRZmrIjZ|2i8YQjCZ=3L!<F#Cd~9<YJ(}r-!*+WpaJ<(0h!!EOL@?=)xauRF
zTFQ_4zC{fIxf_3qt-|Lpk174QYr=6<Y1!tU%zUyq<Gk*Ex-aAV_D2GrX~fUQE{^^s
zft3Hhs^CaNgfIS(v2k(4i#9U;4Z(D#K)7G6&y{tj)cD~M;9wPI;m0KE0V;793E>n{
zLQgc=)Jr;&h~QpcZy4_(aoq~_vOW;Dft9z5staXVmXv}(kE3crTaDr5;ofR1HZ`CV
zk;O3xe=2t$%Fz{o`DA5{B(iA|gP~RM=8?-y%-vWj_a}g)3S#A(+a<5iN}c}xGM#pP
z!H^kluwt!pwUVdi7>pMtkb9<qp0{Ixi7j6v@$C^zrY5{JSu6?$mmTDYB&5O8oVEYp
z05vHI7f3-r#>+^=x3HkyEwC6-s8i!nhFc_ee!B=&l~_jeV#CQR$}+T=2CS~vVQqbo
zrfU}TwEt!ByO2E}_uk81uLSxox0{4GI*r7>%@)_ijPm3?B|iL_-IZrwlytsS6BvqY
zZ~58(FrbtJ$4drnqOfHL2i#}5gc>~lG*Un$BXK6X9XHU`y;aRhN=ix_jE#-$i~}{g
z%EwOnh`Bn@yB}x@5fQv~_%95&peF19IawZg9^uGPw;L_!WO@BN4{Uhfd5tP_B(dkE
zJne+&;rCF8H>b$i^gN6;J$FF~U!MJvS9pdgx$ARz)+gEBQ<$J3l|1Tnh@2BfoRTDi
z97#g!EB}tb;~Ig!rGuv2loiGb<B9?XA0}eU^WEyjZx?glmTVq*NNmy$ERbaT=fW=B
z`vutfF$nMA;i|TTH%sKOhW?;n<uZ%g7A{joI*gge5L&gxtJR~dA*(U+q1aAm1eD#?
zFxA2CIq+f~Az5F@jq1(qr9ftXZl3VBLQ-fJM)jQkiaFbjppDm-NZ1aCw=+S=l^^IH
zcWO&?s8j(P^7}{_Q_nb_l;Kt<M?;&!{!H$NN~{%}NKsj4#kVcku_mIXwkv5SR*4-T
z)zxMrHvtWIT^_t4M{@gUvB#lCR&n^LQ$KSLgsz+l;j+S>j4~498&s;-MBnZ#yFiaV
zbz|<XMr6vJ<g(&Hi|>k79zZAcY>5bU1Bbeu$K~x(`eTGAUJ~U%Pgx+e{6DJRfjiHr
z-P&$!+ji2}w%NwEZQHgQ+jbhOF&d|_8nn5SG{$>n@8{X$`+h(>MsuZWook+R9y4$9
zzjMykdr%U}rq<oC^5ZcRr~xW0AmCvA7YJ%DP;|!HuA}GIWfJkrHKeu04YdqpAtdMD
zPD(>eG6l4bP6EVRX}zIRH$>>(A}O+7fB+U*RedAllYtN+Ho>MOQ8+<F8Paz@@VSqi
zWe?ZQXL{DKvb;9f4-{*-^;K<zK9)8D8l7O!G;Zjk%j*YvSW9`S%`}>dlvQjUTY7{w
zUtd%25tHK&jRL2)U=+WrFHqYz`S;}8&S!48;%cn;8mfi__Ov!wTB&2cFkZWDAseI>
zhLHRoP8@Ziv`@sEkl+pjU@(YrkbavZZ0!Ks1JsLYwV~0Au~#F*gQ%S?wTW16In4nv
zSZmihnDm>BDs_(=Qi}u*+}1V+89rH-Qh-u>L&{;k1^-3XlW!55TX(Y7+Wri)Jwf7t
z`9(JNM-h?1)-5$v_|Ak=*3?GXr5()3C}xI3uyy@iq^6q2hz>3Dte57H4`czC;O<8%
z=A@P-abJ5<X0y|}gvsIWgg2YUEf4sH&z9G>GLN=q@^bb>e=pcZvpgtd&d5A;$$#F|
z62CJLh=?2SyHCDfKVsnFX_HM)Omw0VO3itahKh^7#F$R0v5BlnBa6_)B@WV;J%0GD
ztuXy;_6^udC`y>B%)WpcM8q(p(Gy~ADJw<M2<XUp=k-N$OfZ<cBO@cKG@oYj;mLNc
zUmd|bB&<v&yTdbmU=M0lF_HH1k$+2oE7)H^hHi5%qc+a0&pSnVv&5-R=$=|j6ML7g
zY~&ZQ&3z7WNMPgQO5g<_wfnJ11$amFKX3snc5#EMNQ4o=bY3nlA;v%#Rh~QcL1`7&
zgiEvQEN>*WSiei4PBo(W1fR~nNzKNaWUs&Kg5uUc6B}b!{MnZWfE~6mY_f3P&@XgR
zIk<Ov3QL$VX?G$zAv0v}9Ic0J9GQw)TZ&OF(eky>{E9}L3o9w>_FKG5c9;~@(aJ-+
zwvl(RnyD6ZF`|45)WxY<6c`n}$cmhhyu2(_T>2_<fLVI1rh|I;c(`_`{R_|}_V`0N
zU~w)tN3(YyOF%gLx+nOTCjmZy5@jJ+j2)n{w3gNheEnV7a&~z*O{BCEz)x~OVDVGm
zpycaH0&uKd8275~<1MdTKzWS?MApf%|7T)l<=)Gg3vRR3?cX8bz7`G&MV*!aVx~oO
z@*>8&<J+&opUN9ot|#7-(C4G4Y_TStS?0*s0Bk{;z6jrFrnKOhstm7_5HBm)@6Oes
zQa%Q+bZo;+W2q7_0wS!_cJ4JDV>UY|0xk!U>>@S)KO2^4I;6w2k-r!Zfs#w%ZwI3S
zN!`@^UaLLZqinop;{c_jPSLv%hlQ)T67dM$e*QA5lFd%#OKw{3=iJp#(zcx=&|mPI
zjUjCJgh0{Cw}nW}im;b+u_&GKmj-CL<_$h+X;U54NTgjzFBrdK>R?@zepi<pLbR+<
z)=z27T}Nz0w^!x!XujRX_&EA|c`LbA?F9!<vL_Y&D`WPrD){kmK=Pi|HSh`H`6fgX
zVSbBIFLJ)22bvBGM%LfsjFW@sG*nQ?_T^Msn0}b*P5A2Vo}G@GdW=paBn^s)7){gA
zefg`Dl#~W6@bf)pTcZix@x2X3g5tVHQE=FO<-i`w84lOBn$$I;^g<z~^q&AvTBqez
z;R#9za_~nJ`EA5!sDj{FT0MGbrg~ToYGQT65>h(HG@KQF_gg#G?Tn6=J(V`5+PKC~
z78`Sml%`iT&5$nwa_NGE(h*g`%(qsXD#C@s9;i;ffJIU_{H+7c=V6#cDYJ<HbrQG7
zA>!@j*WZ8+G$IY(Vi7K;ykBRJz3j7jiN7u@RtcC1b^D1g%Q!>`@qC~h_)9Ux8_8hH
z5wJfGRIlew1f1*c;8TlxM;N;W#UFv0f>I@TD@AxExp{VfY#G?!@D4y^U^rC3f%f9Y
zsu;eRrLvkZsGWU7)G50Hk0|}7>6T7M!w|z#*xhEcms-@^%-Oh+{(WGEx}EO8fk<rW
z_!TNw_#ZE;_SiH>+~}sl5BHLi`Sxe|^csiKYmVK;PadVO6FfJe+g{ke{?&WdX)g>c
zh3Z$CT+2m!bF(xa6W@2jz?C0U|Mw*Z0-Sy5C8#laWC{xK0jn^p$mDIF&l@rBo__2R
zQMLA#qmx(!<+5R+{rlu`Vx?^HgW(-%gbif&zh^MIbYNqAw69}|p8=Ov^|g~Qrr5NJ
z7Obo_85F0Hs2XRZ4C2Om(t7j{Y*9Ds?aUV3W*GY<=nsb4sYb>X+|gbUS>Ne-prtCP
z&e0!1hz?v3rYSMK_?e_pIC5ggDdKd%v+sr|2Wl`gIdo=lFx1#=y}67@fBX3J=ev-)
z&$sICdNI)~I6KE&9go20T7@|I>vzJxFt)c|=de2h!g)6}nh348L6+53;!!2uO*my+
zpsiPE*K?OAb??+=nXn~D+*Z6KjQfO9m6bCZCu#E7-e*7|)^A;ER7PnH|9b<oPWVf3
zsiFeYq5M}*f**ET%+@NO^6Y;vn$P*Hw3I(VY$`UL^7UaOKeHco+!L<C=U-y!ahc7~
z#u4&ej96V4lEPXXwX>&z<|4yC5V+;tyK(HZL9PMPxYO8E4e*Z2^UT6`O^J##iU4KU
zES!ac0^$Za0)ILbV+oh}4OUcytbG%|r~(Mr!j9*_I5!eEq`MP>i&}2kQjOUzqN-%p
zkhgI|@ZuQn4M}Di24sIj(D+0iJY&d0;y}}b^OZ<rZvRk%vF+$ITxz2b>G?XdpHL9V
zobD&ebSN%?cI-0%fAF)pyGpANfFi1G+q!?hjA(XC&3)O?-G0IL?j-vv+N!9OE+RF;
zh-Vql8HkvEbR%On5v{}0jBn(kNz9?((Z2hF7+(-SAWH@`HaS_%IuB5X`3`p4EswI}
z<osN}Egc@M>y)V{PAw&uUM-Ge&(ZZCS6Feu|4pr^p($U5X5Ff{Y%I`x26Ys2_Ebbo
zX^)&C#=@Y?|Bquu^PbCgs}^=DcM2>k1q+Mt-bMr?jiAw%946KOIHRI*eEL_Ht7XT(
z!;dH0!KlgaqRE5v@|)w)w;ES8V08W8OZG5D-s@kippyXD-w0NeX2{A-E;22hD8)JA
z!z0$~P*_=vMs-=dh|~Hzm~cKV6Dl|f3^)BdY1ugvPZFXBX)--w3sJ$4E$o<fc0RU{
zS*K-nP2<yZQBRX5+G>Od#WHc5LF9moJKmm6*rq%M!hm?nNe5KV?xj43LQefwh+Nbm
zVJR7U$z@vA76?QmbyAz+VrH7&41$d$ABEV?smuni<r;(K-0mq0-rfsXTPCK6{g_4u
zoS`CvQ9`sAP+)C_>5@-P6cg6I<a`z!x2gjPZVkPEF?BlGjEeFioU#+qzi1zDQ!F}P
zlT<(<*J$V)WpV&T?z|Vxty0Z-jj;>ZhkFOB&UUE`A8PskDpN@x%4ZyGGEw8%vrmo;
z8S^L!V4|y?g&=kcB-W?}ws+T%2gzOl&9WQH_Ww?3)V0$Wpp$H$AS>e&%L@4FKU34S
zPL(UI4NYre#2#`nMETFJKByE5DyS3Smv5kdmka8o>RY$xEBwTsgjh{*l|Rah$${62
z=8>UZz~hk>b(DaU`3$Q|M1vkB4qAA}YI59!pe=Cr%zZ!RY{))?3w)e1Ob~wa>J(Fq
z(Y$s;!WQ$uHaGwK^CDRJq0zV*F-0wde2~eI*k7>62xke<1wykh#o!L{`DweQFd-0z
z$HwX;7~1&;eIkPzJr|XV%I%WYzGB7Qk~~gGC;h}b`;#3OWrwG@pj+?q_K(wkS$E-l
z3c^=VQ>P&%im85BcBA$#C7bG}uv#ytO)qG2%tVqB<EAha`RSOupLdz0QRhZ1Y!yl2
zj;AFO%y3C^<O#FZ798W}Pm3*EeN&cb4)h_Kr3}xgUjaDVFUQ>M+WWOX(}*1bj7$V4
zcsVfp{jWHwH`vkl$izroXZY&=64G!0eub2XSVHA=C2|B1NeX&^SsWH7Ul2&>?qj2U
zB6|~!Ccr@rsK?5hMX#cWU!O2jLFlI7(R)F|3dXj6;bSa-y<OFFji3I&qT*N~5H<zH
zVU<qnKn=^<{$4SSBU*_KeRe?0)w=t%l3C2ZkY%H2Wm8FFmGx(XO}7&W3)4~Ee%sqC
zdb~Ma_Jdj8OyI022;htS`6Zm^FKfH$0{ukLUd@C)xaDF#Ip4Q;Ypo9C=vYlx<3{}^
z6DsM%TMreOE(iA-UE{4NXC+A$Lxu+@z4`-qM5_kXo+;J8v`VnhRfVXl@LEY26e*J-
zTj@Gn?wMZJmYo9Ulj~te^5PA&7!5{)*1F|7v%DJQmf~py8~IU`&e1jQE%6~NO0RqE
z6z~>adRNnCa}~`+wH0)8kKC2Ih;=3gFZUByGCJ|@Zx~*7O=m*!9MIBPe=6Gmdxfdf
zrixiabGMMflO7<rRE&Oo<9NBH5jJP|R<tL|F_}iyPGC+Po-Xu%FJ1(@gh>3BdZd!x
zc#B~W1Ts(ICNkj;FbuCL&N89iZJ8>kWr+DCMSNz>39BQa3Xhiho&!&kU_+XwiB|s^
zR~u5pJ9Ccw$L#(3huTpEb*<<w+O{oHIoLR|@e{ylzI~ge0hN0JNmV#@naCofVhK^g
zaQIv@NJ~xKo=bbjO*XlUK7LIJZVqv-xV&G=Filt&0CDPP2z_TgF8f6BXslKk7ZV_I
z<$Xq|7#73T+v6@Go+cC@7Pm_QEjReJsa9m+w&6vXGLhtkL{mKBKLyiH_LLoPg$b+T
z-wll%J5(T^8CjQLVMxFG<jVh4XtoH@c0ftW_K}Fy0ZnMnY18=%u4KBZCuaFXD2Cdj
zE<F+K+?Kz^>-RdF_Vs9^+2Y|Er7u?-*|o}!$IJbUda~d^ZLNR5@2{+7Qt{lTQvXvO
zlj#}GPx9UMXcB8QvL_=9TTpatT<EUp%YV-0EZYeh)Mn<blu>yV0V#wyOwBO#u!l|H
zB!B7l{G$KX6D0jLJ|U?s4i&UdoS>6Mmr~9R7Kwza&AL-`+Xti|YB6_tC>tN1oQoyD
z=}46G#X;^v5TrpK@+O!{b+|QzZ_k!mSksmQ>Ots!oj^CWt*52`i88W<1Wb9Y7Q~M~
z_-@=3MGF&Ekz8v4BHjI7?9wc$ki7&xA`PzESNrzoWk`N$=-ORIz;8t-OHR_0p+S!|
zDI=jLgFavJl8X$Up78i-9ro2F770zBRrMP))LDFwm494nEB`diF$Vbk2h;k0C^}w;
z(FizKJF@Vvaq~Rtcp3Pk!1Gio?q}g;*ERiM1{cNvSq=5hrM?T@cPal~9n`)9L<nx|
zz6@#}=Hn0Ks*qaN|Gn_PJq2BT1dWL34SXpi5h1W+O}h8&|9t7rieqVWuKen=0jZl3
z_lY)1kdVCcTC)=ot|D`S5Kd7@PmZujmh0dEn~s9$y)>Gm#pS449GN%Fm5rWY@1kW+
z%2XnRjEbv_HbPkb2Hi7EOrv<wVJ!jGIsdM;f^73&NwzDrpgr(r%yGN_<q_$1G4|Md
zBG_P1@Y^0|>77Z$IgLMJsMq8Xs9BwX7UMKW+s@T_D8~67W$#jnwu2VmY7|*cVWK51
z0l~kOA3saXY0TzAp2u;jDCA@=jQap7sDOmn(yDA1E+<_$nE=VS>>|3^>3OxA<UZc(
zJ!6L;vjqQ}NrrM=VP2@=f#J(%cJtQhAhl8Q<dJwgX3>O8XtMhZHPR3Y$_YF=CK|ST
zH7E*Az1pboubfu<Ee`GJ9Gml8K+-B46unaDGi^$IP*V^vpjz34%*%KJVGE7BLAQG6
z)*7QZF41-VQsXtfK}BkRrPlHAz~QfgM}(_YlUI;Q@nYup{=C!RC(#&+iKoRLA|$6V
zm@Ab3sW(37|Gv-`m<^)Mr*2ecC#=JW2<XT4<NN$jJbG7WWUL`p@@57C7?{ZEEwxHW
zFoQ6%ZX0n)8uL7ZrF~G46M1Z*L!RfKuJjy4!)rYN6xs^W!(WI&{t2sHkrf_ZvJ@*~
zFM-p5^7v9{6M`P=U%Mq-%s7Cxj}1ol)yIV&*q4l@vs#{98F#GQX>q_ihP_xLZZA7Q
zL|PQW9A^mnNEwxb=mpxYfiSwDp)zMRn<ep|wI+yH?^2Ol`E&Gl4Ae3Vl=pw?ND*W$
zS&+<m69}>VJHKb^y&Ym!`|jFe;V(2kaeiu#9b&A{0n!3m=~50y!sK<14|vh(EZXJ*
z+Ei9q+;0z-i#AWc1dr<`6$W5&o{Mxz@bC|-Pqh|0VP$!RI#)XuWOR*u70GASrfD%O
zY?0{g9>)Kyu`=X>KENzTbd#Mio+8c{a$QZP5pipadofo}1{f)FTk1u3G94F{9ybnr
zbK+-%QwDd<4*aG>-XmzVVLvNJR;!n5gl^X76wLoKM4SHEEg^ZuZ64hS4n~C%(M$f?
z?zr=IZunlV7P)82eh&+GN!5%Pt)n$DZx>u#15a0E&Zg52WVHi8UvUZ#8(H}#uR_3U
z%OuXlO~e^QQuic<#yAi|VTk<Zp>PbY0LW~oWml5LS2AH>Q>8lnf{y`EXB;b48tFD(
ztu4^{0nAS#?{U`Ja*|SMp;i6bY}(C}V6k{%+ZzC<J$AYSI>1vg9<>fVeyU1y{$fcw
z-bWzMN!ut2WHX}ux_hUyllxDkA87{Z`D_*VySC$MwB)qa&c_mYa7|n1>=Kstsv-SV
z8*E|+2?E~2HMlA}B6@6y8PKOZcjDx1IyGHD@Ij*C(FEe$k!pOEPwVo>4xT*(4W|33
znuL|gh#OB1ml$-9ZY<~3%z2EhK?ob(ltTMxiKlmpU?^$^EXig5w<ye7oj^X*>+Qd<
z^kd{}m@sCqL4;%(EmochYq%F@rj=2UY2YMXh1+H#<QHY!OcM&oS{oVnpsj(P`I=P9
zAl;W?ELAj2P%`6;F+AKZ2X+>kL~HPSK|A|EAt~h0mFV^mL}BhS6rV_`DWnLbiU{ec
z%HI}YW6&vRY-8rn*o8t?pyiWv=&E~i)cN;7Rs=9ZI;yZwK20lP&%eJb)2ViMt$^cP
z+OU3qXUDH?6LSy6TLuvh=BrE=etwkgR9^SLPb3DJBJO@xQHf^W=fHy@Vf)kwhLh(?
zI{b}Yp=kccqTLLxcvxgLBW`)9k+rEz{lnMD6@1Bdi3}CXE1G=|ESTaY@y;%0mr8+W
zJwspWxj$i7zO!AzkFB;QaiHN1JR><o2~n1JT+sQ<Z`aJ3Cax$o=mF$tfl@=9Um_E!
z82v~5bFNg9OHs|1exY7XxL|jmId%p}jSB1`IzzUyGOQS&`^u0=N6C2H8I_O_PYWL=
zN(;`^D}CY2Jj0R0Es|6ao0oowI&(si28l9`e`;BIvdnMZDtM+*?5&?7K_MRB`O@8n
z-OB^3O-YA4b5H6T^<4lNa%UH0{<pT|f+ykiop7*TOGi7Sn589K6vPaQ9yYRo#T}l$
z8bD<WGetaL<@d<?eYj?9VG%G*G9#_4dvdq^IJ3R(yZyFcSa*DP%c0@9qszIh@1D!?
zFe>6?u%Tb#P<H$aRq2c6<?hbw>khL%U$B6+lKf$2c!%A`i$kVS<s;7s1%!R!_2vfC
zI+4^o!V3Ielm|gIvJ9he9x~)$De_>@-WE4?T&W<9H=Hz$Ao@ctg)BAPyQ<$&S>J<R
zC>PVCXp%(-+?#k)&)v0PFGz(z<U5+XHwdM2VG3Rp6P0>(R^L5lbk-X-ISE>SN>207
z3O(E1#ge0P!N78l7ou8Wf_DtlkX>po54_q@YKRoK(a+EZ<NlnO)OQ{F5YPlYcJk1T
zP>J#d^sY-?!FjWgl+Y&4?(#jiy(ti;NuJlnFKXHK#Cg0o)@PMuYKD%3U($LCMc^<F
z8Jl=IXOYU8GxOc1oFQE)rXUMxOD8t?Vv;B3T)Z=_58CbIWt-XBX;TBc@GjGvO}{Na
z-F5W;l3fgZq>y7B)Y98XF%C&LjHDt}U01G0lTns`z&aOisaP!bYZ${U%-c&^atvKu
zseCxB5R&BWwK>E$zd33)9=_{U9ucIorUycEB0y-ai8Kfr(IAk)un(z2N^HOc{;7b#
zp>xpiX^})w8Lh?)0o6KW=@N3$!>e<>Co0PqDyr%TgM57$(y<~F>hSyNMrV3clk_cT
zgEvxyxN*gGktq22ilVHn1e*jtrrUwlG?1c}))&1hC($>Q6{2cJBJdE={IR045q(H~
zLJx}}F7Ox1%m33{#n`fg$4NBkZ)B5Lt9LFI)X4FSencmso`|W@mh~Fo(>SePMH>KB
z0AmLwp`A<FnrgX=Z@x<aeF^0C@B+QHb%~34!{YZijfrDg+DUvIE>CJqT(&Cw#M;e*
zK%oSMXR!uEWuL`VKZ;?<;lBvaty2y2Uf!rBZKxu?57(vZL3cNt*Bh&S9xH8g0WJx8
z&GIDRQjr4eKRh5j>fYzXKK#a5AAaMtrwLh<fK_j2UwOzu=odT34LA9Kt`BNT$7$ve
zJHaOG50|MKGiD<_+t!Ys2152fl0=uKw58Hy{ASTQ1okC6s)r~N1yb}2v-Js52`hEt
z;-flQgWP0HW;`S~Lj&2n?9eF+l9Jn-n&30eqbL$^m*m~TxW5|2<#acIRr8@P!avRb
zgd32ph>pG@5Pd1v-BvTm_7)5JlDUTU%~qa8Dbx@{r`UiGNqwF6Gal;-d!jueH3KoQ
zaih3RP$;;W6W*c7i|LDl>b0w{`BuP1w{wCp=K|vrTIPzJ<<v;)ikt8ighu6+XE0t)
zVC9Xemc%1{c(O1AUNz7u4<_t#T}}Z7XWybKL{A?LHW%BewE-3P&zjoP#v^&v&04Q1
zCS-G(M)>hZuRsjeuO$$vyqsZ4P>?*GjzHKpmH7)Z82XIqP-%AR4>Gl4+MUiKNVHz)
zYfkLHa$0mW-<*bO&GydE2Ov-+UP?ThDwAoVjcdF)IduN_Fo+3v2}(L3$&%TFdDDpA
zIllLO{pquP@%G2FKbMn2PBLBotj%Msv1pHiD?6{_*I)}lriv8ojpHQRHeUNy)Vdk(
z7}#GOhK;XVgL#GYr8qJaxN>{`T#kQE^kKhJJpep%@Zuu)5<WBfHrFD1-8LUiq+-Do
zWKbwWyV+Q2hr~~_pH^_wv^1IJ()R75V6E_WTW0WvxVVlv@wr^ia<EmuPfZi>1~2)=
z*v_oV_2S~*sU!z_JhWh|SCf%`1d+V#!nDE==Q*oB+bf$=w<{l5eWv3t@vnApq1;!k
zcsdw1KO&LzMo=SV-b7!pPVFdn#>%uVv6xW%`FsD5QcVIzu|l!RdVXsmT!e}jN(ifQ
zKjJe)k6e^&ufr~ZNOpCpU#2rBDJaf*W|2<zo_C5n%kb?M{Jmya;E%uy8p_FNrlHlN
zZurfx%xII$M{xGz3;+evp$_rg^kwLK<f3~;_gGwRJiqoozdp_d=BF2Z&@6wH34~t5
zdZ*}3T0mVx2qPU`MbTal*`+B@=4KzyU(LijVEl$<{Y3St-Rz^n{$D2IJ0KLk0LzdO
z>SthA*Zci$1EC8%kG|N5uov>lMtT$bvRo8i(<_2-sk0<)6M(e|LP<0v-@>z{8#}6n
zIn(9nZZpQ+t-OaIe9rooHPW;@M#Lqx4Ah<1`^hkG^~TiunvvY%2aKd85SVm)zgRP-
zDEY!gDxJ>6M8Q-lDE*iv&kJ6gm#isMfvJ%}&t3fu4$V3$@pF3GVapmgMd^<ginB8T
zH7KvqfnF2o+YemCV~W8V%q*jOOC@z4rp%>DN73eKi3T|xH8uuwgtaM}z6z_uROi~S
zLbT&thi+?)r*A%IRT%OAzMi+BZpV@-_dWmmTMrJ{tN-Vezz!3EEeRC?XYLywgXXt;
z9qAtIuA&Q=YNFP$cv(mcfQ%gJ6U75J_>?M{)J2p$(7l1-wA$6VAD!v2>(1E>xuUo0
zvisF*?=>k>05Wocd)w>aqpzF;0(R^h0|VTH<NKYXU98yMfdC@Bl!E66qGGsYmjV!{
zUhj8E3Sj1?bHDvTo3Xswg{@d=h!m7NTnpCitm)Z4s$WaNTZ*D6*`Uk`&Qq~T`-%)>
zKanOmOWubtxX1q+P3nuZ6)vXGZV<#NPd5a?ypU{MBF%Quh505EzsvKQf7vTb=foxa
zrERJ5_&Q%{o_X_~FWs)ybQS$gd1<>qL<i}m$gD#cik;1+dl(<HsWA7b;2`c+aimlm
zS+`)Tv|1^aACnV&0@KkARri&D2+twpQU+p(8ub~n{g;yGRXbK+uJlLKcA0sl(dQ(|
zK>{k^#*7jl)mF|m^j=nfQM(#S)~8e*v(NR%^Fw1I4gLTp!2<{ib<&^x8HniR5(4*$
zNYiYZTmzMM!^hoqehM%Xq3&Xoc5_XGl+<h&hS@D&ZcaJ%W0~?)pw+h8z{vNP^6xmp
zzJIV?-!Y<MmHp4YBm&BzAIRA+0dgKyD4Nmir#OzJYQnhPP!z3P1r~!QIlNklo4oxm
z5qGl@;kPVkA~+JHEJZQevVQx}lmeL(^rdyxRyHbw$4SiuE|d?LZu2>)_=~NJo9i9=
zWXZ028@~=g!0Wl;ffwpzC2^SCQmspUeW5t(4&qT3k|g&7EuHdCw0LkR;l74kwxffo
zJdLP`8)~)vOUzTS$pEaAeK2iek4x~lK3;(-rWEuO^EA;v$-5U8L;l&c6!a~id}KPy
z`yXH$^6Wdrral39^~VnOuMfsk9d`9dbmLCqAso|lW$H~j-!l#*c{EcIV&0FPpb(Kc
zdT>vpz{&R1EVy3!&KopIDYbt#iF^!VG4vm7rC=2y2xKr~sHQNPFp|`Ca5Aw%aI(Kq
zkKZ%34+3wp_fjDpZ`fTpNkwR>D8|-kxfZ>}qx$ve!2Y_r>|z|mP$!Q_yxI2$Z<9@s
zWi4>JNlduMD9gZ(C@VoU1$&tZ)bkxt2#Tme*GTxSz@$LOs1k;?)mu408a=W$xO~(l
z{<-&8W@sZ!TI!~oDdA`5xUw+~%8a_*_F4i`A+_v_50*kV*(K3tJZyt23E(yyP+CXR
z{tj6rn~sTbkn-@q=9l<PpC1g3JBir3F_z**P$@hGFqq5D(Xy<&K_JVHEObUbB$go#
zaY*vpyCQo6>mfo@gQBgnmQqo#auGJ&3%6WGzM1#E!bNRXeY-R0C}$Eq8*AC)u&!PS
zVdF5oj*4a}e@G})tXs@#LBhgoym`Y55l|`K%~uXuK3j!8uoX+2_hNGc3Ro+|9!diM
zXFgXl?=p&|dDTp(;Knu*rNNGwPR_-RM3Wk9=4QD6DN2MPnj0)C0e5<8+_rQIf)Z|j
z<pLtnZ@=OS?R%#r1?nQA#^lF+s|_Wl_sjvlcPVR8^H73-AVd1$NdDgwsUOh0uD;Z%
zx`T1YT>63s-g^eF(xaX=`qm(gP3V4Fu}@fIQPV(ga8zzAGL3HjL8;mLMIDx+J`>7B
zLt*%}4B`zJ*n52K@>!<GrRMRPvaiBVN4@xq#J$ZTBm@Tm;+VdXuN1RR^#8+QMlcCU
zP|6q-JdV1MZ7Gy*>P4X-86<@tO(2LXZoU5E=!gxMUhMq)n64o?7>;C86(15&k5$WA
zcO)TYnzx6z{<*!Qhlm_C#+rWg`Xb}m!TYv^WM<(@TwdR~{@<bK_mdB)3-~W;XVmww
zA3Mi)Ui%>n@?W-MgjP0y!#8n66xYIT`*(&8uMggdg{zSfA&%7<ugcTVW5U@n>+jlQ
z79)>Xde?=)PG$DgVuRYv865Wbag?&fNPOa*WPEa2@pZ-~5Y$x;5Dc!s<5=zuqnns>
zN><%eMmI(lqZM?2=!Y;vb~w&EUqAg5&%$lb&-tZs!z{*hs!TKLJT~=Lu<!km*Qmzt
zwiOfB+U70WDB=HiO1+$E_E$%s)`iZ?d07TKq5WNuwUb)If4f1!9i<o!v5Yui7i4db
z$~2A<JFqAm!Aw=#ByW+NQT<9eSEe`)?@&=bzc_C$c-@8I_Jbp1XkAeO9VJ&P#9Doi
zZ^A^Mp2J1cLWk|O!UB;P;a)F)lMv<&0A+MhHLH3#aC5eO?x0!Pg53`#Ek|5)G7=fa
z)l=p@!h{+^yUL#PgVynmadA?x7q=k^{BmBgbrd_BTB7ZrHT9uKj1zeh`nBi!;;sDq
z!s-i-E_wKaqR0Y2<3vj;3IABj9x=~+zKK;{+G#nyb9Vn}xgqf1M?)V|-O(X^jzO9x
zp@;c3h<Fg&oR?QB9<J)Gj-s`+8Ez<M>xTgBw%5+r)8!3UE@5)wdFR4A6ta0HXhL}@
zL<^cbz>{W!$nSp@N)m=iI4SvW1S>Y}ulHYH7NL<ri&9ZOD5Q1WTpagur-=AlV}oCh
zcu{dy)Y`i!e!CC{Yfgcu)t1e{y5qb}0>2^z+%38x6i-QiL88L+hhKb+1izRJ0G7#7
z3S~4}nIdOOXUXq%WatmVHu2+VXx?#(H|vlgs$WPc2kwapY<pnC4lT_Wy!u!^Y->!g
z|DT&DELB6CC;SsTRSO@K^aM(vbg+}{*t&5vDSD|BnkX;bd`d8+)JdA8B($PEAnRqb
zZiBQjapyWDp_itlrC|GwV2L(N>Q-+ePeaDI_do3V_$+l`WGfpNBDYI(Avuzef!Ilq
z8zqTCPlj*q5}sFDe+FNyQ7Jc4#y5OFZw;}YE27D|n9VNgIeHBfaJ*BrAg9AuPfwF1
ziwiMsY7bRded!vKqS$nT{+A;E`4JeGV@ZG2i!vQF3EW;-3U7Wdk;&@vR+2W0VA5^h
z^1GSA?R^b^@dM~}!)BNYz5M9%<T8&xvx}nCv8?gvjzpekFaPxX4FJR^WBY4h|IfDR
zuR89|3;7K6EWFe?dQSyBUyge%*dipV8_aGBWVX-6)9;p&2kFAvWRI6g!+`cfU6je-
zS-p&q*C%>&vNms#QCKUZcz^LV5@5(r%p*AlP#)A!n4^#%E{gVXCciJ1+!9TU=8{qH
zQ=qbqpRV$6gA%ZVRgfCHUj2<P8ryZChM<D~dqtsI?mGp%7)>>CYB4OWh?1H)9+K;E
zaeG%tguTcl2V5601is95^@5XtE#-_S$tsv7y$f9}!4ALOQ#Yed+JmaRE&fQRp<6S4
zR+F?#Lq!`~=ldHUqam4YvCy!(RPc72|L60@vK)%<+AuDsXKkI%cboEqXbo~7p<inc
zESHRU#s<bnAh!2$;rKsjZ@|93Fx+XFRcQso6g3s5tY*Av^1BTMkJtz?W4t46N#!>_
zL3XHOB8Xw4)UOJW@WtfcZ3v*%4?p)@Tmu?7?5khg!^AXekF33L&OlbpfF|Oqf$ycB
zbx0efRIsZpd)ZL}jHCqP3FdFNIa^b4R~N+fPgr=+Udg5(RK4?M3yzOYD<k;|wJ!#L
zL_t>g6XI4kCE=v_Gr7c&ViH!R``&s!rv<;+S`bD{m>04T9udGH(|;8PC*aGE_7dCR
zq@ZCc3xFhI%GMvx7m~O=_>kfgDMMwt)bzH{ugSmnS|E`zt88$FA^YDZ<B->~nN856
zekKJlj356&@Y6+qkPdI?t?n~cmx#c+wq)2TjwNNW#nBl-*ThCCsnBuMV&|d<f0Os1
z?vy0wYhCVaYj2s}XD{#w4nN}878%0b7iYuU5i!LfwuU5|WJ;zQ4YfhGiYC+*I<Z3A
zwD|y5--CAI7eh<ja2aO+@FqldW09u5zk1+)VW}8HRMN4ZRP!VRUzmzy=}Y}@({8Vw
zPsXOE6!0cV8FfY4ho^HG6uhJu)qzC;qm*O#ikkOCy<7*tFLLjjuvmE`hJD_BpH`_<
zPfKP4!VnN0;Wrsz2A0c@IcsYN`ps@|jxd!?_G3!UOLzLF=m|Tld}V{vZwWBT>kqSE
z-{XXsru4I|{IG7KkX}Cin6t&w!p!Rd@jVYbO+y}n+Jm-+nLZVjOY<EW^hKN|saboY
znGn!P*J=&x=&GBUe)Xy;DBigXs9_&77(Hq|*7*u(3h89BukeG3n9LZe`P`ic3$23|
zVk?!9q)JETm_m~NJMI!W_1U;GssmlS;@VpGmj{<iM%5Gy<c2Q%D=SS1H*EWGyknu^
z!w}AA`+-Wb3<cS+m5B7gLS48Au}(D(GApL1i&|4Dqr8Bb4NfK|+gq~p?Z;Wqe>Ag^
zLbqh64NQ1+7_ROUZn%73{2WQI!$dJ9$U}JS@Ff@~{>(VXF*jJVV1(+-`EYZ+-JWzq
z;Q3?1JZ3a#A@?NGqwEPVFB>oE<zNz>U`=CQ79C7?i=*(~0tJmIWR`uDU>S&!!c_?v
z*-71m8F!;h6Xmco2aCGh9TXjRz#0Ni%)-k)9P@~g%wpz@a~?h?6*t{c8a+GcvIO`z
zFiT#?HFZRnvN6Y_x3j~ujr6GWQEW>(wQ(k-8Mmyl)gqm!{}C4HQJZD0k+gcG&grhC
zUhGWA1~?#gWzZ4pyQ#gv7aQ;>R<6h2KWhnQF^@`<wPwi6@w?nGmBwAJ)MOtU0qd6m
zyNFP>1l8lHobqiv=17GM!7nwwjtco0phy?vqiXf%i|@)LuX7)rS{(Ylwn5Kf9N2;?
zOkBcQ1#6oZ%Aa#4-$bfIsp*x-ru1k;5$p?FPI^!wv=p^MezPYqu||As;8{mDD73rH
z==kZ^6F2fCo{kc~l+(6o9fW-`JQ$uBFe2xxR~C@*0npxh?#t=)^y9(6=~QviU#4bJ
z*j7>AI(vx;w{QxoF}yiT`FYWH>_%05ZFPMHGy&+vV>v#z+fDG#%T0uH$TY(U?1J?%
zp9<NO`vLZ|nEhl<CDl<oyDsL4q%ERdF4b;~gx`;<S?)^L*g+#NeMv&i?A-0}VSlT^
z_d-Pf_t9G|a$1GO1IO$1`IMv4&+9N*de-LhDiLVu{QlS9(dEZ}t=h=`WI@>>iYWXN
zE**~9noMX0sv;{N)dBjyH18P)K_gNRQfkf9NV?s%Vt%j|jP#g<&m-Tv$WfO^6o=f@
zK2f2`Q~t{eG8en6uKGFJ7OH=hVvQ+EESZQXwR2!&W>gJYZ#>EO1%7b-rzKZ|72x|A
z9NORMZQ=&#OA)>9S9^~+DgU4d*prKPX=6T-zNbk5LCCp-d>t%%_NKX&c`xY<lfRz*
z&&FIB(Z&6=6O^KF#<r|#a@i^Nm9%7SpStFRo|9aZuwIvhUooT{$i%*t#qG_SktQW$
zhu2tQiNO?;hDLph*hEyCkDosWoW7fx20nCBoNzCJ(c)~B$|Hz2i5k5426lM`9yEb%
zq>GIlNm~|zgRvbbeUvBFlpL&gMujxRIcK6abSty?ITvpysY-ls`a4#skgRI_BCJ|R
z9V@r@4){vRDdYC@Q;cXthUvHR!Se^PWg@f&0EcVA-yqh>ikBYvEMoupEc9ZYkee|n
z)yBsf2>MrK|9=1G7q7nsyg0{}2KVPI0%eUDjVgF;=rxm3u!qVBpfMhVwq13!%@ugj
zjEMuFHi=f4yc+^q*Me5lCJtwF_DdH11%rsqg+hX3;X<hOsHjxnXiU2KxqaQ<oiUsK
z?0%lo3*ZE4$fp@u`zrf|)traLvM@b@V~+RaTfPG2y1PK7rtEQ}?_+UAf(EsmggM(G
z>)kAZBGNkyp#O;#h^IFJ4H&r&Lykh56n}wVRh8>(%lzo*1vV;>8~n6vs7<qNeOJU-
z>MD-lZLxp-i8T|i3fhw6pLL9fI7<PDXt&l`lUuAsI%((aX2I_nO+QB>I<aaP>yLg?
z0~RONEZO=4;CXNOc4R1*v%3jli9)fN;th<K3d}<p(+ct;;+#>nwx}LwCe-6T(iHfv
zp&bPCGeh!xSN-OD2+|xUZf36J;<xfR$ukM_y6liGT*R*|uF=eqdQ1Uc*h~gtxo^Pz
z2m7D<4_rJDU<mtzO2_~5UBJ~2PpUKQrF&(^W3pZdtO1vd-vfcSwBMEe3}@ad3)q6d
z74vZETkw9@WBJrReiJ!7@dRf6Cv%H9P<HrHcQN$e{Q_2@mg>&jXoz-V3HSrGVV7Zw
zBGKQ7sJ+XGad67slV9AD|JF}re;!{8;-L42^#4WzRVsfgn~#Ew3*|z>dkNrsDw6H0
z+I-FnLA2z!8c)S8wKOcFAV6pe122l3ewyAr#-qhr?1X~=gEJR1Q^<k0O_2Y@WPke=
zG2oDb#CwE-c<)ZWdLD^7-K1Z7onNi`ismSk__nZ%{#&w+^Pjou3hd=j25ljvYbSY1
z$D7G(2;L+H8!5uzxD~@~kvxwLYd;*;{fT!NLZ={qJD427gk78Vk>IE%2ADXR+<x#?
zocJ~czp}K{m8uC!ymiboKtU8ZR$oieZui4${_60_UjqN|?l4s;W+~l#l`jREz{rnG
zoFm3Ph)p9#ApGVQ+Q5WI5iR)l9!jwqPM%J$7o5LYMa{n3Itw+#FH7FkISX1#V1D#`
z0ZgZ2IUjT5|7sh8d#1!UxLOMBFN0)oU94JV#>Cse6vl=N&chOL(R96fnEZ>Shnq@f
z)DZ4QGKEc7PMtCpY_T40hI--f5Hf-_=fHdO=7g*ICriWSWt7<^9v{`7@w!!zxspIp
zf%}T~0fAvFM^=?lqsh|7WHO6Lr%PDd=#bu77dJXLI!jLDtSVZ(^y4rVCvx9E3V-D$
z3@NTuNwf-c!c9y0Y4Kl<gf0_BugZwzrGh8CbD{$+S7k_6T=Y1l2th@Ki!X5dNc>nQ
zIu!VlVFNt47jnO0(U;7j;J6GD?9^eaF4jyF)8k}*-eUeUlBQbpKFJ$zEyDBeds2<l
zYV~FsKso$4shhE9Z^>Ip;}gqApJqM#LYq|hir=)2g+iHWGZZKkiCzGMO*`Y>M_5?b
zI2(e<62SG`v6VwIl$oFIN0-u$v8J?@v1fGa@l4BZqs(rw`0;L^8{Dg%#xJTD?RZXM
zBO|6-h!*}wvcppLTg2Fda>i={uibiz+%Yq_8)h;_FXX@~<djhy8~j7MSc}S_nWK*@
z2gZx^ne^zYikoU$HBCl^(Xf3hqjL$%o&bI>6qzq7R9CBa3-~v&wthMo`l3Y@8}n40
z=J)p?N*3kyo05rY)wg5qTXwb3b$*x<$rfHE2-b1d+Cl0Fh}O|qoH|rw$=2;$*j&ob
zy!3+tLe#sc0?*oWZ-3vP{t6*QpjmQ}qiA(o2=DP5Z!MSP)S@(^g{Y75K&I0)exG(l
ze;DBz=Spn$wkp!#)#7<T6oFWG-4z1bY)Vc`>?}B$O7n)WxOrLO+V<Mlul4)DRrHsL
zqMW=0gD=p-))$*eFI^COAs~|iQCmt7C?0-DOu?x8&q(Y7vbm+_3@;lClXjg5uDlvg
z{*bd?pBM<sIQM(!f)PZw#~~;DEV}gefH$x~XNe@@sg&Eal0cm`rWypi%$|mX5|a6)
zqje-Mn1&|$aiFYB?Grr7GZ(Acd0U-7aHIEH3ICWECBniV)5Wrct^*ng-Tp0q*iIjy
zk71~;i%BS-fw+}O$Hf1fW&bnG6H|<2;?%-L1`4Q+hVM9z(BMjZMQyP#3&mjMj6>cM
zDQQ4e^nl+D1lyksGQLieoti^$UCImNfJj9o3>hkp&aD+VpOClm3v{J~E4Z*h>zGV}
zYt7_3ArR8VH{8mO4di7YbBt}R!cN#%;ha5v&xKCB3_87Z@Z^t=Ev_IXRc@~%GiP=s
ziE(ba<UOo&=Bo}kAlO-JIjYp~*m9Q6t;WV*Ney*%Cart-7Pwd;)ldz;US=y_Ky}MT
z+EP&Zd^5dC<PZq6C4B2hxqYY|gia<QIx*#;%Ak%&aeY?P@Q0a_9Zvh=OkQ1hW7LD5
zNAL=4V$#IFY5uA85Uar}d|c&MBYghD2#v?w?ALyvP7`sVcrdgi4V(Mx=rb5Pr-u5J
z`VFu|3Q-pa>NyF)qFkq8`fRfFMK+G1N=2eX^(}ns^_PS$VvlX(t=C_zSiR8<^H}_t
z7FRQh4(I}pif4Dm(5!9!vr2H7b?jEXAc{}M(EUIu=+bFj9&;S|K-HoHl@=->>-|U9
zYv{d}^WfM^;gQ#=!GDF@Xg8h(<^QX-OqQ?b<H<LFq?ocV_R=WT(U3qt*lE`lrp{Cx
zQs0dvuz>1;I)&LlQEXbiVsi9GSPXCIh+WZgsm8(O)h}7gA*=Vh5<cRbCAi59&z+gk
zZ}eXeT<tvotX{|m#TOh32d3k8h(Et6EE*Nd-3p}!kR~_9`-Rl$Z0!J$`-%yk6bVz>
z^gQcx{JwP)cDMe!x%ZbjS0)lT8~afEcC!q|qVui}Z*(a{7BhvUajWk&g11E|mkk&0
zg58QgZ{kDRGAz-IziaQ_`k95~B5anz3X^%O9Z&mt*3%#=So_4k;o0Nz6G+=eXkWd-
zAOYW`kQ#jXn}qE)WE20VI(&&(=;J|-T?qfGn{bsgXgtx$A|wjk=A(IvNwqO~0wq0d
z9W^$55q?MC&CTmN^)qN^<)KV^3!Oq}OBH^#bZ)nA+WK2YE^JIU#;JUX6j2;++_E`#
z)=0PmUl6oLF43e3Srtg$0An5){FS6)@Ct5&7t56{(<I}6AH5;*f){!^+n+>h_Q;aZ
zs9Cqh`{<C@5HTo>$z}1jY)BZHhnTXmz74br)_orr{1Yq}<9S9@cjqdkNLA#nfFN~=
zr7T6uQ}(T78n0MP;93YLvUhk;N<qVl+??<M(DW<v$!e`O;^KZp!>w^LVQdWEfqu-n
zT2Deh|7lS!s7oR1{&@OZ##tdEiEBIp0uRAK7FIMYqFrUK?VeprnzkkZ_CapxTL^0N
z@+eR0(t)d8l`r5Xt&-hNMngVwE7)}qC-|{;RIQ&cqcU=@@+0DY2&X2w<+B`d_b0VW
z=f+h3{7RoEmV4aFuSqRa#+@!o85uHhCfP2{BDx_uR$QeAUIwx;j(!IOSxsbM&#Aog
zJotj^>P5e>A`|gpHbgF4=Ytv4ZOr0Qll%<ZFu3xYLFsz*@ia@2$Ik+>u45?Dpk5gV
z$~==SKQbWk`F=mFH(_KF<C^oP0I7nCeqbCH9`fH?d*Epz<c696TI?z{k!R3@bcR0d
z0jQpiXkhQ47&6F>-3n+m*4Awu%s@AKSaIynKR1pfikN2C^guem`+{_8RPAn}y^uxz
zRYGN8>)9H|=xLqrD4^f@lf%VfsxmSYhB&0DRc^6y7SdL$v*`uaVcEc<RAWII$Xu^`
z*_a57vGCTBw>tp{YGG!eS)(dWeFO~E;>9U9g-&dYB6`17hF$cHIt}aIt1_T@q|<6h
z0yXjVsL9aDBHqivU&I(T!{JDHTs&y*RA-7%#nsDFoneQjOUd7KSO=Y1H0A~WI?n+i
zmOR0pI7euXnpu*b+OnnRi%yDz&F>VaNvbLgGAOzUS(cKx5*s6L6$k0^1E)uTIH%N4
zD|&PY`*jo^=O~gxM)h;07X2SbY4@?*LcKl*VU~-FxW&xZkHBxjzkS!CAJe2B?|f(Z
z)WWb|TA!u|{N;JcZRB`|W<Y-wz&0j~-OIOtEh*C?BPKA|{?BC)BJRmT`=>0eW_L)K
zoQKv0XdOmA7@m*0GDQh&`L#2BwXzBR8#@g0$dEF&n>sGqc5;FW{opH60Jv%}QVm5`
zXvK^b``Up-FpE9LfR9}mmQG$l6;3ju1gVeBY!qtpni6CoyW1wPmHR!E)eaVTomwEF
zkNW&6Q=~IHUxBUpDLJxW(|%Q-RXP|8>8|?s+(1Hkuso)WKO#Qej*0%w$8i0ASMqmM
ziCT}-+`<$KZFd0Okz5EkYG%@@FJ{Z8RkBT3cgXgIS2?biieSfQ+z9iKZKZ&;^+GQq
z;WI?rIBvJ7U)xbSd9P+`5OY7!(Dh`8CwLIY{`GGSaop$QL9SWY!Y}+kovj?6m45=p
z3PU0t8I=h!R4{~sU!3)Qr$w)40g>OsgH5akSi*Aut#Lt2eeRr>z`yk($g$j)Ms)x@
zez+SX?PexF<oQmaRfIF{zFzewW?@DoT)^VD-w{DJk!$%IlX3N>#!v~oj@r-)#-trH
zxPq1V9iBs2g~KW~L}nwD<ET(*4#A{;qZp(&!a@D7wI^7nFtQu2$qoF99ycQsLVq|b
z1*o<k&Y!gPp!`fG4<;vunQb*_R^3eW&=K@5<p_uI1K|zr!Dwk%d^mHS^BmE-k%0P9
zyw_%Yu`?slNP*y)0T%t>%cDu5n)a_R3L2NQ;@qW0O1#$-6boUrX+F&f(&o|==KWI%
zStgPYcN<-v9W;$e(GICx1-^f}%Di>kaTZ<l>f==|_997;70cDjH`m`>sM|vyYayY!
zP<4bJ22t+*HqSz@7tMHC_b#Z~W}A1TtOJ|NzGwZkLyC}pQ$1Mscp37Yl*sl=WRNC7
z6@0$?@`g|79HkUZp{t_C@h#@Jk-{&=_mZ!z6@p0X;=I*%{=L6<RX8e;C^C&S1$JC~
zBnr13{m*r&agFbTp(PL2EDh+obq8))3BFLoioA`K#rX1@-X<&I<#l|&v`_A={W*4!
ztR~z1qqCE+8+oT8)wykysp?xXK7M?<7S}~OQ0la4D2r_ydC={KeiG(zXCU(5+Zl@a
z*;vR(+sGtCNn9UWYB*G!ekbatUei$b!d@4CLQ(1_Gl(XOf)Q<ip(J7NlFbE^ekQ-~
zA=$vJKcn5WxU&GaNjw=X0H4OU@h8u3{3WYCU<u=SPILf{`-MI-D9+I|+EP%*(98M9
z>FGJV9+90&pS{Sw0|@=nxZ5{Lc5%mCfSN%tTjS5TctFsrIr|<gM=<!G@g)dp-~LJ5
z$XprNaMZSYA>S75ddtk2sV6ah%%SS*Pi<|C@W?F9Tp!&7f(mh;E<jFUoZI+~0af44
z*Zhq~u-1RLjtT|?ieUuXufZt-5{AVE*zp&>{K5lFjt01i{kwlI>#Sy&Q^}?r!MqL9
z_GpVTyXZUsIA4n3%k(!jA*KQ}hv0LE85<5Sj-c=JWlehDP0p~$@8B53tpmy>@e&+R
zZRdWni4U7Rl%DA|mc9~9!<FRXwG+zMyI`?*P7xf^g(>Bkc)iQygopq464;GG)J=F9
zV+PaZg@qE=8c1iM@;))B(s9GVV+`TVd@3lEgj+{P;9P0!(3?&theB&6%_%(zcT=`j
zF*;Bpnu_~mSMdEGdCr`d9I4M~#heA7z!e%@IfCJWmY2vYXI$xP-i2|LBn_%=_LO8t
zp#d!Hze>CgqpS_hm6+S8ar^+Sp93BUVqDt+LBYvKUZ`eUfNe&-_ZEin8Q}b<^j3V<
z8+IOw!I!?mN~njkAhK4;af$~~C5<^-K;s_>M3v4jxQ1%EjW|B^#*q#&`DPXMZxn3_
z)Nm2DOkz97Bqr})>`(YydwxIH$HW?^%ciIzPdXiFp^9CGU2vAnc_SLfg<DE75r_6@
zmi4(SD}J|YVAynyj&De#TQ-6B9mA52^_FkJ%WgeI^yijfqy90my+{Izk~aHCifJ38
zU*t5^-E%dBz)QkkGbg@*&7V!=-@UtEtUeKzC19@KXt$0R>=4iG92GKAZ|26$h^K$S
z>S28>#e+n*OR?hqgniQ`FT4orXk8)M*w*v)b~IRFIkZa<5;ZRR-smbs{6FToGgh&S
zNvlF;9x<&NtoZK&dM~3WfmK^UiYMx<dLfoxY+|U*t=SK-*wOM{wNXPKQLF3yu6`vc
zY2(J-Mrtl|Ovs+}=hm!FE+=XXe|&@4d73zJ(o&I`l_^5kc30=6&(K!CHr&7EtBIql
zzXN_r|DPqqP(%tOp=)T!NXu24**K&SLBSv~9GJgTFJ|;Z7<192IoF!=NaKH4qtLAW
zR^}~(xXHtW?w?SwbDMah5MEn2w7ABPp|LqzVDoSZte7mr6h~o*+*GViD3!F$<JkD)
zwVA*9NEWOFZbz^Zl$-x?Cx(})lZ)4cSb>GE#7SW~3Q8JrIqy0;f@M$=)cp*(p2#eS
z((dg90`LvEb^LbUrG7RcO{<k^%R$_N56jqD9z_}D&w-hJefi5^H%>RH;C-LtQihP|
zyLI5CI?<%u2Nw-WhW{Y|SnvDS<g|!hO@vx;IZQPBH?Q+_`o0FuuQ46Cr{9^*bO!y`
zLL2kpZ^}tAgzV1_5`k?<)t*b)q|TNC$AQW4`X@eO59f*~6z|)4<$wPRM}I}2+e~CY
z<w;+_p){b*>f77!V!Sx!A-pt#E3Yg1Z|vC9!ggh+mpYUAk+X86PC={;Z@I=wySF4*
zcjn0sQ}7iHOybUcdy{&OE`T@Tb}s!FGhpM1oias_FmQ3*C=g3~7ciCyja1l+zTe3n
zuF-}?23SB2G%QhgJ!QyIrLw^p7_{51vl${JwUkQ}xu?;WG=qscrCVefbv+*EMq>Q~
zzH44I7-#$MfQ}x?xAr2`V;aX=p!=9FlJOjxjyEpHMG!QC0WzOlLSuYt9@fr0pAhJy
zDmwGO+de5f$v@||<TY-63G1|a7H1*Gb%dht3tQl-9;<Nre?+|lW1P{}HXPe_CbrE^
zY}+=Pq)8el6I+dK+i8-<Mq}Gn(*_N`>3Pn1zxe}mW8Hi0eXR@7XeLu6C#~KG#iTLE
z?^4oIjN)sbYif+4r0DT{{I(L|H9PU|I--M-(f+ZG!0d`hCDBVId8j?g0u}Zr+&@C7
zlQZw+aY<uLj+2un{l2;t3D}eoD%qc)rr}}Tpdxq=@n7FSa_&>qK22jp@EK|skE}$F
zHRC<4Ndi+Rl)rrQu@>;r>?w_W|2S@g3I;$$mp|izh}&I!c!7dmCe+?i$XLkWa8U~s
zU?_?Nr!O^RV-5e0aqojTz9OUrjF}w2um~iatl4#DU;Z`oTa>g{*C9@q3PYV*V~<@B
z{JvA^hcLHLFzW++3*#wUjiBhg=`Dr>6^3N{F;&oXovodh3<j|+!-{_U8%@DhAuHbG
z*!q}W!c?t2MmBXNeZ}WKZTgSf5fICAj*nF}wV>9vLxaXHGI)vv9*Vk`RAMlLML0p?
z&)WdVWu*zH?_fPI`&nvbMX&(g=$<rzQuq1Z4ps<v_Gb?!#gHQQ6P}^Z0dLuV=2rIL
zkv*j=CU*o-Ndk5YonIKIun4a@bdbl$<EtLw_T|ca0O5lId*v+i&6KDe5AzBUm@vp%
z8mJ^|V~RFsuz9@r6+Zu?f#G(yoe;!+7tN@I;BXmi5E}HO?kh4YfngOhI6Ougo0>t|
z-zY@%U@ioMX%u0cCG`vnj%4&dXJb1pW-=2~y&KU#g__%t%$ydYN6Uz)!WT!Pgz(4R
z4RUe>2obE+SSJ2;yfF$G0MSUo8dCyHW6x+{M`6vHS}nVF0{+JBKIcl5U!#J9TmDu|
zbXv2Q?hV>OBhm1^ueId?8-~)NcnK!k=8`$7=XjuhRY;Hx2a`^V9W{=URd0X(zOAWM
zHIpthrpaG%n6u&M@d~E(ApX&;%w@!}c9WqAbPge=+FBa_W8Efl5S+{gV_XCLp2%2C
zKS@~}5`R5&l=fTaluk>xk^-hC_r1)2E#w8P|BQEKcx+8OPMS4Xuh*?@@lGo(ciad%
zG4#5!_5tFlT1OU;7aTM>N9^3r)*dy`l%wBbTvQI_teD_!Gk0X0g1}JS|IzE@p1!a2
zDCf@eYFlJM12g+BjL}y!nz+>`>Vy+!xe2ptf~v`B@P?aZ1+m#-$|L0C{_KjeR$Zh2
zw#X?I*9_9IbFh|7k7G0K>P#D_jzr69{QW7uQNnj*RRG5PDytRcAADz%m6P{PmO9cX
zg|nEDMvR0`^!4YqaC@l8?@ATYg+DsoEydz<BD4z-aTA6o5OtV|I={lF+)npr=DrY(
za9!B|aP0KKMz|(ky960GRN_R62tMV@J|Ws|YBr4<F5Fe%!Fg-e!j!sg-8X}qt<O>1
z89gnJ<ZBwr0yH=3Xu;_gSdd|Sd~#S2F!x>P@O&?Q4V`w_{cOJD3j??Rz_5AWOFeSj
zha?v0B<syx7}9c%E$<}an-?g!h`}f`H#Te6C-b@?o_Q28VP@J*U}V{MLdjAG?_i)q
zHOW`YAkA7CV-|v3@8iroNaKS4w^8gG*o|x9?IdOX;7;V$uG1a&ZpJH1Y#%5YDm3}x
z&eHFOMZc!P_9{i<rv_vC?ZI!jvR0jNKA&o|Q^3$-k!bpG0llN;nCNS0*4U}kD<XL*
zKNYI4G9sEsz~B8ymkwmAMs~A87K+%1=M=h6otC}-WDZ|_C-xwH8E^26nwdH$)g^4r
zj@sHgYqh11Nmr|Zmtt;-&Lp~7)%vMMVL3?1Y<sh%Ibl~pY3m35GLbg;rJf&mKHvkH
z;xlw|6~e@*Ir}NFf$VgSEAK9L&he^<BqTX6E5=8Go&lWi8Qw08koarW)zQKk9GKLp
z<KAs6$J|0|`z=kmc#}&&qV(7|B)9DHW}4B;1iBG1_yNJ94#!F%UgbnIp7_RVROl4y
zhTj~LmMBPS5N?<o6Y`Zl8Lv}bRu^MfdfzQdQRfgOZHQWkK*~GxkNu+g{dgXsx}x_u
z%R#o;1w8EiKN$(yNe&o3yEnK;>gT-u5-%aH$vXH1L1qT%50Tq|b({5KO)8R2KQLR>
zL{4e@4Te60E`5UA<MmTNP>9vjxTr0c;(oL8@#{Wq(pkytYQI3u`b__=D1<hHCtZi5
zA?FKp>)LScI)eUeEU+aR40#YbmtbbWhXGG~f%hXl@9+Hcl|lwcjHo2({@S)&#)Zcf
z9OEYsulFG=4@XJDA<8F<rVaU$XymzO^#f-y%>^9xT_~<5fhz%#<3h**8)h!7zd*3u
zsqH^blOFnwAW;qrkQEIOGI-ZlMoTz;PTZ<e%*HsmB>$KwjKaw9mY_(yes<_nA`>&`
zb`M2jy}9v7f5OhYh2iTDKk)LWn`K{!B?d1$#i9tIf-H&>H(LEuk#0c~pYc`IXT2?g
z6RW;dj({>P#eCRk9y;gunN0BOW!LVI&2yc(kDQ7rUxKCoCx`&&eV@BTr4>Tl=758L
z0@s9)0Yb@CsGkv~@h+ay(9+^d*qc2j9ondHjIFshn*SM>##-xIvm0PoTO$b{FZgo=
zN>(ne<*pe0LX)0A@qIX+_Fa<N$_{+X3>3UBtDqYe``wsw-|Ke!MDcAjJ*dnJ6j~Ke
z;s(%aO3RaH?6TVC_*^D>z$jWh#vQ5-+AJnTmR6EtRkQyF!3&{z$iO2Sc${g2XRDfa
z>GBZ%3k|;r^YC7bmdb?al*l#2P^z_4j+p8!srS!knBHGBY~FHZ$ypMz)}>Rr&#XV#
z;(~UhBjFJ7Lru*N<{Iza{-pBULYs7-S5=?CNDO1L=EiV%>dpKpRxVHiRr3x*T<B7-
z36(e;GI$5FmsQxsi)-Rb=Hm0orWF(g{#rUiJSD2ldV#(2YW`VLSPP|h&Kl89`q0+g
z&Xo1=*;i!aaovHfpj9Hk?WcNA+Z@_nkK@zborKQEM|(p<14O8qnb{Cj(qlsPVyHO7
z9&Hhv*j_(tLWD3$%NZ`SW>8%0%|q~~W8RHfGmv13etg03nA+$#U4D(Yap%{guwU7E
zgf4rpn0zUApk|_HAQ&YQ-JF=8PCXsl_PyD9q85*QnqW4U4vAN}PEenZG<TM9;M?*0
z6;A9-&!)#JRL_K?ln5O9Yt!wCpugpeFBm0c9y=DW`XFG=1OI!7EUSW9Yy+o!(Uk<m
z0EruwVjn7vD0Ajn$AdnCBjdm6I{NlEFqU%#IWnF-bzn{e!hA>e`b~>~<$|!3+ej(J
z-5sInXdZCRS(X(B{8Hh}EKK*8x&8CuV^xlv%3+#d8Rhe1y<+yHvg3O*ax0HTLsn#$
zpxC-*wkoqvG3wo`U=b2BGBS_=504iXWdzZN$fSGEWGWNGqfY~j*q`Pa0;=mv|11PT
ziXS>k8<#-lN>pGym;FH35<H(->qaL{iW&V)ZRL8HnV3jSe}4dz{(y!6P8e@@Ect^e
z3hx93ETZ#_ogwxNY6-GXk|ncT8T(RwdwkZ*Iz$VTgJFq4#lg*;#IG{God)fS&&Z=o
z%T!ap@38}RZ>aX>YDtI4oXX?cdrh0FH_s?!(n4(5KgUT`OM)iXRHMUQ{YNbTR_gth
z?Ww5q8>1Q)e}GJrzx?(+a$144r-Y(navU~rBB@BA1}9agDp|9HTtgQsZr>))JA6eE
znWA8KkQ^-VNio>nlOvE)Sx)+K_2Vy@qg%s|Pc#hAfhW-8-a)@17vB*x;xju4bN37b
z-+oV3X%}ABN4|gqVf6|-!IcGxFgP$!7PL%H0tg^BM|R_Upn|XMmk~gS8+-~u7uEIn
zrl2j&*07ECU4CSGDAVix`9#{l1<HdYj4Df^Euzx<&C(JU(>`J%?6$%6DKDd?qeAP~
zhJAId+maX|*Uwn+A9=s%(sH+L`&@`GsBgLNdY`P*Cq(A|OWKslSdG&02gjR-z^!>5
zg_+`3wDCQNKW_W7?Z5`KI12<)ab~_ywh9uhgzXeuLM|Bh+^KRW6~w4apVu*YJJ?46
zb3{L0e=X6-(W6ia;0ZmvCdeORV@Li`JSd~B)}X9j0yULf&UX}M|E0wH;DupFw$2ZD
zAw+dfEYT|fXj?m;pQS_%6`ojS-tX&Lg1N3GWQa`?o3Y&0#oYI&^d76_t>7mtll}R}
zbI#fq!N`Tfod!E6{cPOJ=qjZn<ws}|^<Pd)<=$(P#v>rv6)cUCJSsZtK2aX;caD?I
zRE@G%Q(awMh=GO%_U<p6GFlJ@2ihe(*Y|Z@*XR6!vZ?!PlhD83g!54_B>4B*MK~BS
zN=?-mEcFxkKlX#*E}WksVkj`MJi$hGuUy<Kr?IEZ+8~~Jpd}K5WT%+0Ixl^U`og@v
z+YYW2qlLmO+L<nuVz_0m7`Ylbln;gPl{<lIL^W!yU<w(vA>Pl7HJ8pb<&Mce1)t)q
z5e-TsAjEmqJ#bMOZXOHA6imlzLw8S>Rt$^F&L;%sBj-80Se0v~L?J9;yLn~-C&)PC
zLGaZ-Zdki-#o=a-?<B~3QqMZ{IP5Rwm>-@F5<bsn{G+`z)Jle|5Bhn%4j!O5o%&&k
zPYuT90$%hR7aVzw8+=oVqPdyw_22G(MbYIUgh)F$t+Mb4sP*XiDe@sxCBx8v>Pl!z
zewL6wE?!P?_P?lYUnkAj0V&(yTK~*6`lIM?5#F}pER@vv|0)+n?&)DcMdOk1%=1G2
z*2Et%jeiDm;^4`Q*M++j4)LgT@6HTTd^IWwDCUK}Z?soH?XcG+mL_pl%xtld(`yQ;
z0a84&#r!KrmpcS(xGz$~zdi%cdepuT8xpxiskDU{#5ishHkQ#_VkHPN=Hlku|Kp)-
zmXI(oYE%ja=}GC*{^g=;B2tKlh&W8i018^0L2Q%>BID4k{yTtIZLUI%o!XCv<0$i+
ze!Ni-TpW{xqQsYy&V`Jqk355&`pdqDTdh7VSYG#&zn#iR-p)r77hb{tvd<ILvcv#}
z&n>n6gzSkl3!aYlr%|{>mF<kKN@nh7GI^e8O^Kc-VrmUUIJ~ZJe>g2p;QY{)Uq^HX
zwu_A+&C$7pWGEh{KWQOfWfbFCeK4LXya9QWziB>at#nJ<WyY0t#BjXFGzc;?Geel^
z>aH$wl8DK*SfJvIF~c)(?=qEN3gu)J5&re2u3XYc7k>j|TRId?38{l1YKo5Piji&H
z+O&1CB*-w>sN$V076emMO;CEZAR{!bm=C)^T%8&d)^+e=nffjn17=!m7(K|}LD!b?
zeOZu%H5#-d?e);NA5Gj6oi)phdzT5cf-^WB{ez2uwFf;pbnSGynfN4wJ|_tddk@gy
zTiy8Fo15z>w|@BjP5cQkKHk9ew9gG?-;_?TXL7E4o+6`A4AhtfWW$$&b^FVN11!-3
zm-WMzU-PZ1zc2zCvl4{wWe<vG_0;L?N#3UNdxJifuFQUDZGTNWUQFh&z^Gc6@<%yE
z$l5PFPxPgXxeB*tH;gX`8YK%<RFK}Jy{TZB+B`URS}CC!$$bK!dlv}@K=9Y~z)k5%
z#!q8$#c$Yncz8kV%*>9_YdXCzTC(B?1GHw0-J#YnNpl?$E~<sKvDtoh{{9o3ya-&{
zzto0$3m+Or$$WzZPur^IGb6{~MEA=-8%LWFjt<}MEikIa-RvBswl&q;MkY^6GBgMq
zS;{r4U-cJ_KZ~p(a0%3OT{guCZzX~G9U|c?+mWZ(lKqXenW*qzF}fvB(%^9UZKA|%
zkY_T5@NZqf5}H&fUc)!AuFmuX*vtNkt;}EOoY5!1@X|o@D%>!CXM^AeJHBI2L5Ko_
zTsiFAn4ZRPg4#)hg)>==QRxe28uT@A+=2~HT79C<gxw9(9v_alrfpEpIkSp3O)N9l
zsnvDO4d%?2Vbp!VmcoTvWR{!5Rfh7}Y4ShoPiC@_6_3{VBfSn6t@nz;{N{8FSc;{z
z))IUpZUc%QzBnwl6-IDtDOM{W2~ylMG`d`Vz>|6Pt%1PZv8JWK@voyP@9L6{NzZ>v
zbrq)-fVcy8soR6V-Dj#y!K7oBhqN}5mV!zBqs&V=V<Xo@)X!|#(Fj(>?La|)5=Os4
z?a@g7;*yX8ArS$K#k^y~(3>~>-EUmftc|Iz!#vb)ouz$qz^{!qq|*A}$KUG(j3>3<
z>|ATd<SQv9EyH*Q+|m9z*$qf!ZRclv$EtTlkKi!0S>ArQr-GqVLH-qIDR2;R&*dKz
zu(IdqbQdnui6})Di~7q}m70KR!={G3T8k+K6Jz}1au0zenCM@sL8LkU*;Lt{h1Z3r
zKLW)tD6uGa$$yv3(x*`wVn5NGK~GcDE#$N;Idd(;X;pl?{Ff(sGYm|6z#g&*fgnlV
zrw9@^*-R*X+NaWeEb2K|4;-1lCc*B8K%+{C9K$;9{E5b&KZP$8k37%yP5!R0m^OPa
zKNmFF_)CcNSFDO1D6=Cxg9gS?v2-H+?@Zos%iSpGz$N^j3a+xo633FS<se-8)u?B|
zZ#lMbFzwzNg#Y`We+9GuvG&}4zBLAeGF)QvV8G(l_ZBT#6EQs8-sf-muhi*OKhQ7`
z+%e}QKadqKvio&egMM3yRpgI#&k+tiO1IMAk`*Z$tmW;z<?cM!O2x?EsWg?`Dz*B(
z?K(E~#>AM`-jyI@*)@gZPnvU(glJ(AhjXy%b%&k<B(kM!>2CPis}R%NBuPBM4(n>-
zL3r|RxI6mJf~W({Vh>uIl9JlkZgR*q`d<^WHaW4;0NodLU9X6bY)bcJe8Gp(_p@B6
zqf=ahND;?G*DrWph>>F~RH-=jT)VR?9zpyP`vRH9z6js+%}nl1EvVE}_~jZ*ECR+n
zLb)srkMdR$wZcQ6mZBMs3P89edLNw}7gEg`90*Hd>ASn(zGC*$B7^9sh(n|g9)vM7
z?~<SN26%hyW4;F#a6#<;a}KELI9(((FBWe|uPzgqtBqS#Ea?Bg4Zg+(6do3Bgh5~6
zI*TVzk>uwA*odU!*N$(u88!JG0%<Pvr(n!p_?r{(zTUA1iHr+q^-YPF;yZ3HwN33V
zo14^9>m!?{-~?~uxGgL9d-6IJiw0#oyeI6wmF5hF8!eJ|D^+sgq<G6=bgBbVf!HNG
zUB=yrg1Ba{*LW`D1lU66q>e0?;$y6?53wz;)s{(;*(D_+4f$iT_jPg^a8joa>qj7y
z-`$^VjhW&Dw(y<ORG7#o^#E%@mKgl7oawA9%ZKX3AwjG*Ij$qr8Y*8f{U$l*XlS3~
zKKoHw;ZA}=;N)m6hY4E~pTXZ3GO{K-0t1b>5TFt6Vr9%?srL<pBw|w-rRivR-49P5
zsxe*InMMY)BoUyE00o)tUBXV0TPlm)23b8tF>rsxv{?H7#p7u&g3tMCQO(I1daqKJ
zgm$A?Y((B^iGgO}(DZ6F+Qo{tvrxzJ7nIi}fKq=ZwxGkyj&cgOpX`52H4^d1xD17A
z<=3_XDCNQV($9d|8CN8=l9C|Y1{m^|Efv@P!caoY0L_rNk;=%5KHgU>ln-2)q4e}2
z_56Y9aWzZXv`cy=nBk|Vr-};w{e5be&+@CKoR&B?II1bVzF>qFiI~r(pW`4zohu~&
zAMr$5S1Z3p+3+O!JF`+U0brzXx`}WVQSk?Ct9CoWi9rW)34Cg9xqed)&hBx&Zv3!E
z)4;1O5GoJ1W%CzM(vN5-%hC*epmQ&xR$t{9u6@m#`1;yy_x7qj@a^JDWaW&;7<J7B
z#MC^Ps<)o}#Q8PDrt%6eMG#G;q$aTVUBSq+d7780vwwcba~q8N<9;PCSN?N5V810h
z5!rW8h&=ko7p(qK_?hV)=&P8|tCUof62#_9U#1MYJGSPl-(r8ud7Wa|_@}mHwVcdG
z`R05fJKQ$-Hv{c{U|;|WBRnijNu>E5V<!4{#9=<BkbDjqN$>*H_jLYrB%_NPth9{8
zTXu7{F6!US(Pccnr$C!JbvMC`*BxBTm@&qZg+n@%^Jm3ejakE6+ESQX*3vyWz)(9=
zVI*mn30*SNO!g;qOthT8YEE=eIEAhRYE0ftwc@Y(bYEu}Jn58wve~l6((U79mAWEo
zqiPF7Luk>$*wyQ|%HtCexuZ(sK3p~bA`}`q&J=zv)3#K5QAy(@I;?B-z^vdyaGAjQ
z_9G@T>5~gxnC>w36=V9vRzC5f5pYC5bF3;~^{#}w*?wKqbId)2x(_K<iC?he`(m;j
z=}(9<v<hh#J1M2PEzb?5pxH{Y`V?Vt3jR|&l#hQRsheV(L7Uf0Q=!mBY1Lo*O_Qv@
zR&sX@uBq^bMRj${1in~*Bd9D+``<}lW4n()QgNCZVj)EpyAY%Tyo1=`8u>M%koYx&
z<f};QGIYiyJ`IPtL7KbL=yOl)rq#JHKKZ4B9?rCG=u~L;xmLZnmN_*ziCnkPb>!4G
zh|#qoX<iOk05pQ%Ig8RcTotCLI=biB_$CwbFNs<!Ud6o;w!CUk87&)o{X|o6eEn_O
zU31V;BB<rMVnJC*2|I5MD<JGloUhlsyL92w0PmH0D62U^ZiXu<VAkr-_t4L7h`aC$
z8xXkpZ<jWi&sbgO;WRw$tTHKnywai1H5J36m6)+CDV$<C!Ejg3p~zBWEfPXtBbrah
zviTtv@Jh%3knjeBk3C9WkMdm4s#&(T`Sc${Q(S5&&DE?C(U4dS_IxY}M9~nCG9Kk$
z4VtdjPlAxVlGP`X1c@DwCQ>)WYM-YBVF7-m%stnZ=-?`Z1)v}!Yq)-iGT;pwY(YdP
z>y&*v+2KGS*;MM(&KqRiih=sNH$R=rhfbDU?7qQlhy)pDC2*XQJ*R*S@>4K=?k~!;
zB=w1sTaO(@$|w7o%*+|dyw3enQMoAH&+UgqmWB_D!I_l1S$SMu%qcQMGb!H)GZ?!>
zT*cCL^P`KCqKlp?meX|%3KiBAKw=KyLUxkTJh$g$tpaTb^qv;QWQ<czCHL^5CjJ{(
z_5@!*tf+yMU`J73oUY|CzcLd-u72AQcJVjFXR04RG))<k*lBe|bT*cKs*$0zD5_{z
zD;$q%bm}vebmf~gr0u<x^i?mNoe|o3Ru&S7g`FmY_izvsNUS1&og(G~@CAQhjPoPi
z8n)}!%IF`J<-QfIxevCfL_RfHP2#9rrzg%aeH79$rjm-Umn=AO4tCPN%}EiTMNM?}
zfcY=l5&wOl2I){T9OwQ9J*t_Ze5M`<%!?;ove3biINz)jYBVTRY}B9_J!1kc+OInf
z&^CTRjnKkS^j9zVAf1(N%g&|;vdtB6bCou6$x-DbFgLl?$v3Zxr;CEUuqK}&jVdfi
zp&5bgd$So%_6wMI{EW^RPEla=U~Re#8)DEJqXbDvu)^P7{7~>)Efx(Hj+O0Gm({hQ
z-fmJaul%3s41th86_L7_Y)Ho?qQsF!+0}ABEasVN#bq0SYg1A0FNr_Uz{dln^+i2k
za>h9flW!jg9%_>K4aQ20V-7SjUr`ql*;)wKm?jn<DAD<qfSbp|0S^=1d#3Y*9XBp-
z5Knx<6<52~L1+$j1|LUWB;^ZjgLbrhTg)HGj)Qoi;FNG<*Z_12?LOSD8BVX@EN<mp
zSG`w>PXgS95$k_?+&H%2LGD(2rv7eu3KHhOp3`EiSu%6K;+23a^*{Jkn=+yCLH70o
zZP=mSF-inVJwmN;B+jVR2%%J+1pg=kx{sa71nOXq^w{?I<76X>Jb98byT0YT_PzXZ
zO=?GZH~nDfNi-3v0WOJF^Lqp&Ww`I*m1RmhW;4<}Nc;P$lgt|w5s7QNZ+JSJu_nC^
zRSXj{@MEtexO@n$f5E)t2t9Mvcds%PQ-TzMa42O-6PL;j%t*>l_^i8hXxt^yr1(da
zxD;yui{YC%azSGdD0T2GU3iWLJj&61pSpB%0hGcz_r7^<lcaQ)pDw5?YB9<%hr;55
zodtX^=Wl6oO&ICT;{)2ZJPkl!RFqmna#`*8pg17g8GFqJ&C^+p7(FN>^bZTgV3VSi
zkV#k2cu?EHNra&*O9&Jdx}%V7R?`rH>pmB?n2Pq?GXrW&>Mo77Hnc^3Eb1yBdd{qp
zalU~#U>{S|1#y_q_V{DDy>}zoHM(XV+F*q1|9X>BGj9G#3O!Bj(bQn5OQH&@v;U83
zO#3WIX06LE<cd{3+`e$qFH;;X3+tlkw3130vn^b)C93WQ4qm0WF7PtUx($i3L?mF|
zCD##6;%FjV*}_{9pFo5Q%B&WY8!gOA9D*VjZvZ#(WMO$MEbeH{*{5XLIWSdSR!((0
z5(#4DB*Hjs|1(PvSLHN^RyAEoo1~;waP^RdqgSmmuwqBGknJU{y*rHc&co)H8ZGcQ
zqk=O#{Bh$(KiB=-U;I`osl*G;J@F7^e3nC4BCcI-WJbVMX@P~1z}FeW<LTv>UrLYs
z4^5@glU%sX@Xe)$hM;j7x~TK?KO9h><xml$;@9)i&2nVO{oRMltPrS`7vO1U1A`EL
zEfCT+Q(^>(Cn3qTPTPNWQSTeQ6p<RZUB~_CL9r=c?j=x8<We{;5bNpm8;+g^N9Unw
zQ1WJ$7n@#zft;5Aham_$dW}5MKMQY|^8yIZaelx@-6)6y$XUGy7NPOn?EKh>`KwH{
zw$So0PT+oSV{SO4#NDd=bQ*3H&*7GffEEpPFP5u{5)T-NjXFu;+xdi!0F^q!Y~0;}
z5?3rMvPHE&6NNpf-j7g;!^22=zA77OCC;tzbBV7FMnREvXBJs35D|kHE?PsxV#K}Z
zzQV(-mxeo1!f~$P)zH4?4$1p18b-V&OcVR3vVYna%K^l`;u0^50kxgNaN<F|Cd+X^
zT;@%{W7m*3673v6aggnKQ?U0qDio<xi7kWWeua`?b|$-QG@*XZf_^Jat6CW|Jn7%r
z2vJKLIIs+Hl%M-<$wyb|9qDKot)_$Adlpgs1@kyV{-ZIbio6_UNPh8@LfTHuU^Jme
zOq~gz<%VI}>fEo$qpFj0qXx%2W9-BJNg0yj9xA2GVcZ{gV-tM1e?a&jzTGxM1cUtk
z_F%W*O2ypLm(WiKf&GsOf9sE20=WI!oKuW?+hR$|rur1rT3~n&4p4Ra>jU3`fX^NN
zmD8pTnk~0m{F7Iza|#w`Xo{H48A30S*j`PsHhKU?1)R8-cidHTiY{hopnMNTiukVM
z9rI+KLCVxuJ$_2YJ0(|cB}&^KG5!XF91=RA0oZt3r*?`y=r%JPy(95N;5IK7CtjVy
zx|sZ>uA=R%GKN6tEA@=`X-<$tfgucn!3_>gc~nb_KqCo9gNq}a@NcoBGcXcs*9O^L
zWUuTZZF=-Y@{@XaVJuFo^kard6J$i4P-NJ}0LDvA_ghG!K+pOuI$!r*_=VG}KyLZ&
zHdrZUA8MaXM{@h81#E;K*sY8ip{qwm#e3L_X~|0aWqh9oVkKHU$rddYmc^Y5D@Z;Y
zU@RVXHIE%97aA5n(p~AUvdT$h16s2n5quKM6BGsDYCz1NJ5_e05*y=+{cks0>tKxx
zRB-9Wt)@Q<!{E;m?<FlkzI7bJKHpHj)X?wZ<at2_Gk+7hD%!xjheVtX@71gULk2zJ
zRKKGP<!H?1NM|nf7A-Jie}W`RM+pUsP}T$zLNxApbUFAf2vT;n+I0!JKf(fzo^bw1
zXeLtxegJ<Zb3KS}%N={nUeh+QMwvt@B1qoJKe)z}Om>urC>1FfYSFGlj}0^bJ%s$V
zfS)o34lJ@GIlAE~7X1AoP7O_H&^KO?8U|<c#LfD3N4pBfO?AIW4V(Ng*bxG?=zwc~
zFG-oSg+w-?0zlS2jwW;o^bT4+qg2-%<xuvlnqVoovXf)n8JqVTW-^8ZERy}k6Rm}X
z9Y+76`OsSLU+bEU@aG@56A98(I~S^WXp+-cwH~(>7}dG;x%bUoao15db0~+k=P(&5
zleGz+#(a@pe-If@na_=C58ECmK7J25wNp!~md9eaQ;=^1>^W_|Kj?udV{(!hg1-FY
zsz~k(OV{7yzqonBZy4+VFiE|iCA-)3hZKQZ@-5FCO+?r!w$Ma`ld(BtDMl<pSB?>&
z6uTuHV{CO*Q8em9lYUwky_GAKfl!999A3xQ@tA;_{?2hoRqJOV1hFPTMe-h#&h%*D
z`(K>yAg+E3)_QSiN@o#zCNl?on**ge<|%ZmQN|%^(#Jcnae^8|xm3t`<nW1rBX0iF
zarS32cc~}B<Y@w&5LiZb?i`&{{OGo|S#!)Sm;;Wh46dsp(NlC|emSd<0!~2mc^LM2
zlEXS3EPlpN4)m`?v?haKP&GI5uW(lnuWm67P!OXjdM*Kk0P$3OZm0OQ7I16J46&Hb
zeH9+1)-;=n!bG(kL5~ExG=aiX-jeMs-P3w^f!e-wqqF(IyxO`aGMLb#oz6F0%_2a#
znKn|ua?;<bgMba4-kvUPEG<_>gZ@<25pHNZD45`cN7(a;0G|gVJ1|@?9_NaRXlM>`
zBWSzLnP6#M0K8|@ef%veOZ#6u*i`)e7aPqWt72rkSc6{L<fDZQ3vElD@>vFhKf<u=
z=1^VQo-srny+mYa4i~1lG|Vnw1rcAVj`0#UBv;gFU7FZg(w$NYjk`r~@JOl}dJdBY
zN=|NAE3konsc4<shSCm6SUZ^!LTBBCACxpCkqlGC6I>!50XLzOWJkr(L7GAM964ni
z7_LF9qzT0UZ<JCDZ|{h(X&+1e)CaFxc)5Q~Z&uGT+Oo0MDxbivyc=4WN(Z2O7POU-
zp&l@$eo7J;Y5V+ul=<E~Bd9=FlEwF9VBl^K3Fw^3VFbHvEW`d#f^Jv+C7LRp-`tiw
z&*z+h-v%O<(K1aMP!*f1PJv<17?h}XnhN1K*pUR;ZtBLN#^61-{eq&c1E1io#H+61
z$lJOTz>JOj07lf|VnrUFy}_fbUq;6=G)&yMyJn0(^vx61t1nS=P1rwgpK=sGS<P|D
z=!;NEah&=Tp*QKKi{xoUjX@3l@4#a434$UI+cjIDbV%?y+M9}5{^TvdC6`>tK5%kR
zE0LY8`!;xRV9$KpZIY!=oJKM#=9^!>Az`;5hr<1orbsaP>mVJ6@hzmEt?~l8;B7&@
z-!l`DS}r8jxQ#>!%!<i8W-e!WM!lCsS#I9J_q`atreUBAweh}Zh%`c(6ecFK&)e^n
zL8NuUY?KM9O7cX#_{q^=JY0L0SHV!xm!iaVk;l!!72=S2hg-(KX;J24O8M(H`u2n!
z-O=S&pXYBa2a-J29Gj=dFpmhr1lq|y8S>HmJyT~GDzZPgm8zDpbP=P6TkGx@b{FzF
z3ZG-TSBo%?U)6C|Q4Kv$=RD!u3ejgi4t<)U%lE^YX}jn{c*#N!$$in>u(&Z(E#TI@
z(+yeEE~qhi)&MA!OTmoZ!w_e2DKfXyyH^s<A@oB*eEMrP!$Tj!Fm%eaoJM1m8~yR1
zmsKQsSN$k<2E%?~-MGN+^x`fJGRJOTdWnSl-@Z@{H|xur;n;?)i!;Clb^{veehZew
z{P0XOe>UcjJ7U2PHZbhK^V4w5s=%uF#KT_1UI4{L&>sIW*JoqXR|a@NbHVrW)fF(6
zDdML+lh30f-o)@)#brb_V?R0*@?Jt4UA|m<XXtNcxz12TN!djFpu@R5G}DxZ2>pHs
z9U|R&amq^AyDC3nKy(0_8wZ23%K#!>qSy*7OUiOZ^p$&4jB;byn4IUN%%_(*r22Fa
z04roQd`R30xd!<m-O}1|31)06i5WvTx3M}+B7fj^tphcKRo4~bWA*}zPXXaH4BvQ6
zB8Xl)2(|tB{qK#+B?OO}E~g0)SAfJBNY}J--30dT=TgKpk%;Sp-c)uhQTpr1#P{tf
z!%a0}fC6F<Y=P{fonwQ41eERhmi!GB+iDWB-BC_GaE@eON9+dTx2S(O?g<W}v#-9q
zQ4^R5<?;V_&~jmlczjlz_!^Iu!wC8S^gEPKo|>9uh9EC-rYTz{(G-0gf&i{u*Y%&{
z*6h*kTb@jM9F{gLMlUOY_jG~sj>Hp4K?Z)>Kq@;g9Fy=J;0k03Qet*26>C}uR@g4L
zu9$SX1ypt#Nu$=v64#xZGLP)S;P`q%zysAX{+<j2t3BOQ&qI%%nVb0`9OUOf+u4#K
zWAS`Or}=zyChMWu)e(9ddC{+$a6`fP`)E)j1}`z0CDj1<Eup3CM1*;V`X22ez_Lb-
zEH(g}EZpv<m$Gd@^bu2}-)pZ~osr86jDSKK>DF6={w{hi(937$YLq`rMui`D$JDj=
zBzF80h?LKuL*<jeVBBqcBoE&$FqG#E#5;+Y$-OUM6?B)jNS1_{_#6KLyI;Dv54UCV
z`s-ixqke^1yo=-8CfGF9U423OH=~EbcI%#IaI0&#e#2_9d15loA{Sz;e|x(L?Cnl-
z76<5+M4A+Zl8~6p>ZrViFu`TRM1kI}cHT+rUA1Ho@@?}0BBz*h$+5`r>G+};52Xh^
zDP@!+=syX>#3Sl*gbzw|O~fxN%-J%@59G4H`$~=FTA+YXff=QiI<z}Bn<iK%I4|_J
zb4(dakuD9MeO$7&g*{E=Y2TR<b2|R2svC8Y<`Yj-oUJVqS|JM96z0xYM3NyXs4o|`
z0C-p!N8+Dv(w#Va7@7M$&8;2tHAdM=;1}fLJ;Jee4fP@Ggn^D>T01!JNSb8hBB>@A
zTJa4mfE>E;K)-$08-`Toc1~-%w2eZQ5_-PfqMa8OTh%U!CO3lnF=-0{@YJmb<{wK2
zgt%9n;`Qy&*+7xsOu%!IL(~QAv9?QY6O?3V&HSOojzz^6{@!=F7GS=FBlGby(Jp)v
zmRo8^DxkJo+UImsiFYLJg(HlCCkpvh7J?!@01S)2f)+b}yD$u8WB!J>pj9Iw2AyRR
z=Ve-$^s^rdVma#Zg(}8lD#zv&<GZK(B&Sz#useWx1VxvJ)KOwpsem)cG3I9%hbkIf
znE{t>H}F84)06gF*Lboco}s`(p@Ca9OFQL*`yqPbrdcBHYpV01GiS3EV2Ywj?bdGA
z8TU)rF`ZnSVUj2Fp_?bdBaz9P&xO;fUFu`XxVPxjZb;N%%4&_y>Zeqdpg$+(Xii$0
zzMT4{ub0G|1(Z@<o@KO1tyL9b<o|=bQKN;xIgPHEKzJjRSaX@VjPZ=wl~#%O66)Mn
z=9VVQoT}<Qr$M;@Fv8z5@%KZ53&_s+iWo22x|P(OPF4^e#I#%pSf79>6P@{f(@>>P
zg=sQXLhDBj_ZKNCcu;=QQ2h5SbC=d}(u-!wRUo7GHxUUAL@c%oAB7>d%+HMOGgwa<
zMYu)TW;9E<hqGdrR$-Wpij1T^6aCeqdeOg>qNLFHUv7-!sdpou@v>)aoV%8(OYtbP
zaQAfKD}X$Ky_{xJ6ut!j(zMlt5+(T3@g&?SQ}6D@TvC_sh1jJt7a49mG%?vA+g7`!
z>z+qr0_Anb;xDj&U*XLrKUWD#Gzb#5`L7D!JK{13=E~0ThRVJ3uoF}ndMEskP%yBZ
zbA9uDqpl-wY|Q;xRWjZjOt-Nnhm<pg@WB$KRmp_C&~ZbCN0^rnYx}cilOMzOBV%@Y
z?t24P6^J1?jLH!!N<mnlj-G+YYK4C);bfBLLt-4ch$qv_EA8Om04uSA7pY6bIz&<o
zMp#P<kdAoQpP~@<0&<aih>;9&dFV%Z6Po(oFn#L~7MVk|^&IH4@@^5wd$x*a;OGh_
z-(){o{!EOKv`S%@J)Yem(>`$jDe`#vg~eHd#OF`9Ey>9BXF>As28k;9VeC=D)K#-{
zH)n(zN{pmT!?~=&BZn@{zI0^WyvQZr029i~VmO-KYu1MAE5EPKzbX4=d?9mK0u2dY
z+k({SGt5Ke3>f!mO{2!mSlO;*qUE(mMMr*X_8Y(7r?;oGp#B%P!pp$0!uPWhK8D*!
zM7?rHS;EV2o8VcH4NR8(o|<_V7YvFP)F>TN;$4FQ`P#E!NJbdbW18FY0*2R`tB8L?
z-|{d#qrU!K1Y1^rd|kJr<AlBw8y70_4^yhLhb66h+-FW)cKCQi)5rUS>!%!8V8Cz)
zO!9#-t@!%517$QaX=;{<@S{`}GFoWjc%I#fIX}U0I`Sdh+v-Q?SrNfrrRJc-PYl|$
z#L2o;sAno<$*266Gkocvq!_%+J1*b=JqYhB)v%PXJ^{}^SdXv|m}}amvf&GL1NMTN
z?@Gq}IVcY`sYjuIK%Zci*j@HnQfnDEx6?+?#5~KlyMEN6pUv#U0?{CiGjw^U3clf3
z$5zqdWbchEUQuOi9bAJs$4}hO63$aggK=Ld;{|Zk);ulDW;o3p<S!wHBldxwoXDfX
z6&2y15Pz&$P^4A@`#hiTk3^X6PaIu{3#$Cb%FMrO?s0)P<u#=L<}0wYB?HDYbdE>e
zI6^-6<8<J0^*Y==X=PzV!hnuTs=n~?p?Pvj1sA<61G@1Ks!dFSs0p`@v$44S#esVx
z0kd=?Pr_JAG1u;d`atjiO#=`Qq4^^i(;JpMSt3D&8CMdQYshagNngm}by_nxd9l5w
zi;KL<2C$z(u{*?N&(0zNcLNSoyCb?I4xh@;z_UlZm!pmLSi~>gi4<twilbtlIfZGg
z<rJ`J9?>k#eU4x+afeipPCEuexrowG9ryc1F|1Ix2XoPZ7IVJpF7E(!J}<1dfv`vn
z+AYj7WLN!j7~yv?p-A{1AqVA)LJk=)K2f|DihQ}lzxhj9x9W(LJ$+wB|2%*72p$cy
zcFeHN>UNdGiHTHpwTSMb)cx~{p?+filt4L)q)}1E#42K0DFF2ZZL^y*QZnAuE1wDx
z&-rY=G`i9n%EKfZV(yRM=<)%yv#9>=YB1P{5st`6y{4=0%Zh)7<BD6L`n+SsJ4~0W
z$0sVCMD$`|<~0K1rOP^FzIvlj1FpdmjzI9h>|%kuNDG%?eXMBF1(%_!D2CapVl4E(
zp!s0;gay4|T4V8e$;=+?zBh*Tc*GkVjahJ)%HlWSF;sgcV;&c@6}?Q;Ooe_gwXAKN
zVd^aetE0Uhkeo}`U$R33pJBoGC3U)SrA@9#@msAs56`h@r821`P%IA2{!?Y8#!(r1
zf?9mvbPlr@K{y~wT%p)jM7reblU&4Bw9^r+h!a^pEmK_7JhR=O7K2kPHty<&XlJ1w
z&TeWWyG+$}%g1@gPCv%-ag`IS@tw5RqzTR~oLIH~`C#nbL959$%wxt4t8}BpqSB8n
z8sjI9C8@p8AABGTQq(d~*|5Fl<}I6ZQi~u!5n;ddzC=Pcd39<WnTEB+AOq>g1$L2L
zBsccfYye<{nEpD15B7T7eL*Ql4?Oz*Fu!38I^=IE)tIlt>$SADHn0X|hEf>G(hY(#
z!9RDiGH5O?uD??R*4D`!egLkacd%R_>i5*e#JSPr(|r8hwv&pE$Bm+l)sb(e7O$?a
zaxiL-U_B)U0t^K;6bKlEiS|)V>SV{FuaLPk3buO4)AJuPrmAD`R<5Hml80^YFXykH
z<j<2j!LHqr+4#CE?5!*BrY4^!e&?+=U?%#(r@i2iZWy?veXpMw95g_~)G{1)I1y$~
zM`AZqX5ShEHfSVcfeIG9Cy#I_*6y!X9<RvS(uz=%IPVGD%+MycmeqLscGjf(*)kHH
zV@L+4m8^s}ABn}W<yb4Azq(#JR!Q@)2P?gP<0(hZBYA!z?lU8FeM6fd#g4<MRyWJz
z02#y731G+Knx<O!a|d`7^SS%(`$b)G(O+;LRGwyLFe7@K4KiI~M<bNW51BvR`xu(9
zoJ`hsc=o=QL4zN~>Mf%PFu@pbP@oD@C+lg7O{-p>?ZjiNby>Ha+;{rT=i@H>^!Hg$
zF8zK+<cHU*@26NUImaFq9fNZ|f@Wi#<(9O)I<xr|Dly#L-qYXdapnwDvg63qemdR<
z9Fl}#xIEP*0S=WQgQ7sFJN=r55Cg@qP2LzwA4MnmSTxH>4jMPb78{DoNwxyf8vbDV
zAaA(iBem8!D{sVWxY-5(a8(oDI!5b+rE_hnD_ZXBTC!3SQWI&d;c6QK0s;`s02uT}
zLKEtZ@<=Ax)&8sZkr(B5<(X;HZ1*{7*L{k-7yAe2GOgY;%u1WZ_e{qm&^Wm*5CRYh
zpmr2i4bf;f{S>cix&cbpE{L8Y_zw`>{eT{1F%vfM>UECP{&ai-0;`O|;~<UN7l=A{
zkEBWQUfzHKdA>$+IQ91B`K9&~Do&tki%9I_b<qbZJzP4E?KS8&vROqUxBhGWcF)+f
zZiIjm>?^1wMp#vVn1+m0)=#P$lvXoXZlsO&#TVSJ?P48kYkA1MP2Du3!LI=j3cf8r
z8K+9MlX+lo;&PjI7Ao1-P1j>GhICR*oK9rr-g)~7Vooh6FK5itIv50hn8Q%Xy^^2S
z+-EKM5a}G^*yt)$>W*Cf2&w~An5q#JYCX{;$>Bs;rCwb>@RSz6aA6qv#FLE$1z%SC
zvYhh`gYyeV1t~K}^?#v9#GOQECk9&je}h<bQ+w#{hCp=AswikX)FPU)PK(0QG4faf
zQ^a(YKG@EQEe#H53nhH@8HoN{LA#*_POYh}1bXwXB2NaBki~`c3#9WovjM{k^PHes
zw&gsSg2cj<a#~R#pz;y{4k4y`#6JHkCgL%o+<js%C2OZUZvR8jq;FxR?tXHiUK20+
zQi{P~Hhux2qIbU<w6l~gZ74+|#H(+Veq92!Q@9X$WZ}YqhsauZ+HbCQPvJG9*6x-e
zJP5;=i`)TWyC+-HPXWSA=UfLjXJHD}#@A(c{RZ4zX)k=*j8cOd-2WDVS2GL*$t(IV
zP*XDfzi}mxmPl|SP>HRH=aaFq9vln8dcp>ttutH#;Vi{$6Yy@btO`<m=_l-{5@Exm
z<}|b5=Rb#kr(bp0KL+mbd~jF3Xcg#UhyUS(oJbbOnGnVZ)#ubTT8k?BlmVd%wl6@}
z$My&n=O?K$W)FXNw=-IUp4iTm<b}QeVRHM45yE}03o+zs@sYrJyd_~uR!jR^lV!-~
z6K$fPqMvP6?M><r;O!(TZv`g!!ckzLKvPb3Wi8$UIy{|Fl1vVn1jpJ(0h}{2YM+Ih
z2^mXd@zhCF*>Xwu=+=IPZ0<`a!TOOZF~!ZOswxHQmxIPoz6!3CxK$GJaIT6{3(0Na
z^WzlwP@pAgNK$<y>{I2NK_cFxzcJjng#q&(;38_HK&qovhUW*dlyB0LYF#+xp*n;R
zwpdxMCn49kG|(OaRjCc%0xoKr(F`Dk?tz}8SG*UzFi7R*uoVWMdw%=g^sIm{97+rU
z8q|j#qrlo3+7n#j6y^72{iZQ3s_iT`yd8r@Ts|yz(AvDI6jRljc{PS@?hpKuW%(Hy
zj1z-I&@P+sGm?qjUALYeXJ!UwRmoVFw`f0Pw+A;CHMG_Kit2rQ@r9kAJiJcVFDfz$
zaR3j+oTZYJA>c6_&~=6D!IHBrBZflx7h&?7b-Hws%tI!`#Mo6SMD5?=j+G>!VCZ0t
zq>zM+b*{%U*9?D1;m19qT|K^`OFwu+GV!ES792#i+$pSgCaS=qTiFP96b!f<#xF$u
z?^kQu6y$9P4TsWD&?X)ZF<Y8jjg6P}{_`T|gI+O*Kk0(t$J{)aM_bB}*78z7;@~6h
zJ0UU3ivwNya?lb>9ethn#}kJq2QAS*DGT8=|9336Mo^vV;#j%%!2T#^KaEl?l_W5k
zP%O3R9BDi`$i%x+)IW2PQ1-Pk$^AxZ&Mv8eSelIC>qtFQK|{$X&$8~I<0l%M>NbOB
z){uGfQmL=>8l>I<&a0$>uXp`$&>$ej01&|LZGdFrwFm22?o!=VTifF@4a2SDwKagu
z=C_oplZ0-~s+s{Q;(4h%IjjulN!3#lMoTh7sZvvO)y@fLI7k;@hfdU?IB?>7+Nc}s
zHlaJNwi{qR)J1_17+hbp9S4sV_lFfzc|aNpDB1{GI0&DAj=?x2GV&ALbBCaHSFgk!
zu=A4Y=aJx!7uQ&udY2d@g)K<=g|4cLj2t-P;?zF2mZoQ&35I85aGx^4L1MzUeHCiO
z%rHCWoV#-d$%=T|Q``%RcpupRDJ(i6D9~=`;@dko469AMuT^=@CmOjR0Qa)zar+W?
zio|@rM6Nu~hmjbwb7Jqg=aS9c$h*)`AS-cqw<Z=cl>^?2kC78*cL9AkCN#l5trKps
z=sWYQgh8I<KzNy{dR|D5#WSlMZd3dvg=&Rwr2(beHP)I}Kq<@lI7Uljg@o?w;9l?G
zo}-aKp~7)tXOm^5)dKo2E4wCsH-T%XIehn%+^+$TTVJ{I8%+Y=c*sMhJ~`Gw&@-E}
z@44RYQlN`InU11I0|6MJ?BKOY(s>93Pu4eP%_<}N8jW{e5_4&{hxVAkVL|3|TKKA#
z2OhEf<L7WMIM_Mu^+Iq{B=(yFS#v?f0RROJplhhet^;ynj4E{`Inohgf%ZKn^fOWB
zp!&J-L`CEgsYOeN0YaY$(t0zE$(e>#_v|aw*xnrmD+AHHq~_1sA4dZpxKf9>z^zr_
z4{}U-<MMkqx1ekMrTewj#myno##C+nvl*eA%Q3jGn;EJ<>1=x6-(+cHc%ghA&y|>1
z&8K-*{0`z)gaZ7)E7gCx8n7Dr+D~KXfXtIJKSmUZI&MMb)0+wSs0g;|-68dU`m^!b
zj(5=X$R3s<R^1y_Q>(2MS+cb@`kEAKX#86!tp2Z%ydO=AZ2ez@xQ!ToZoiU$Q)hyq
z1G#JAM)}R+jwqWI?zkdhLZiETBexKh{vK5SERMb}wAI}25rv6DvPQMqTiW&5?dI?b
zsN|AW4~Pm6pV>!P=4Wo`gZg&~nT$z#Tp!bXJM4J@+ukR&Pho!)Q2OZ@D*^e@*tCj?
ze~iGb`9JSQQMy6dZp|wFXg*ZXn36uTRKuOz%3=>of%y)6F8OL1GG|bp<2I4=WoAtu
z5+AtzT`^<JVNcxKBdsL80{co;*!(#WuCOxl>k{su_D8noB&Z-*R&kD4V1==1*+?s)
z_$d^C$4UpGs#p$LX#Wyq@`ijjhr1~Hbr5PsfMNstcP>+H-H}kZ_^iCFHY&wZn)zJ7
zvT&H#wOM0v0;?WajAAXr3%-S1FhH2`Q(ctNJMa6V*6L4)nw$VIB+(1DbQtFfG)K<-
zU#)Ft@+Y~DPqR$JM41$^R`-~vj2iv=mk;m#=tgSM+e*Yp>!23Lt$&JJIpAu^fE4kw
zY9j>OEnVNa=p_OEbVRCkRR;;<J2=|p9q;{li?Hvv!{H~X;C$uj=5Ntu^)US{CLOTD
z7?f4MSf`$nZ@#CHlhL8Ua1=U*i&k~OV25W#eB+Y>gP9n`9sQJCQT29$m-h)%DI!pt
zW}mvsOXPOo$6KaoQ8?K3=j&J^g<@(!HvO(iR@?wQfV`PXCf=_v3ohh;3-Rs=*p=rs
z84qC-$Hs{+bMGq?Fyio`w#MrT+Chvw;Av02SoqJXg@JP?4Kea`C@B#2XK*j2WSlo#
zl{mJ$NdB%Wr6&~c_nTsh=hO`R&{bVu?|_b8Tij694Pj+C*(@p=CdfIwaB)$%^n=I=
zb$6>bRxzpMhO{31Sv6|WgfvU+fT!?%m9ca7Q0noqt`|Wk(r0D@4D7I;vKxHA&s5a8
zMjccmqwC;GQ&h-!-Kqogy{$H`+K#+0Q4rg<R#($gD^f5XSN*>(Z^Pq)8~uM;=1;Vi
zI6aRgtxlIhUE8B#))+wU!S@KJ?Dx0w&96KDJK+BMO3^X@{r9o~SY~6#sbcWS{}T<l
z-5$!s<{;mY<b=&OAxc1gei}5a7_jZQ(8<2)69cj)Vv3Ddv<V<ELwF?U<xr^PBXZVq
z`qu-<lJc4y!|Kb;eUBYPenT_?oRP5+BL<wa8l(IPVKlmo2L!N#?D?99zWjK-c#2FC
z{AM1(eyq=TqvR*mo>Tdz!Xnw#&)ihg%{FC17>xH+fx5PZVc-R$n;skW-z^2kBft#!
zq%`nmDDiEjNNHR-T^Ul-;I%9}4q9j6>KG<@Kei-}bMw>K76HZFW(&kf2L2rT{=QDN
z%@b#AXKwaVfv-!oP?VJx0VdL`oMQt;QyC{YY4Dk-3+Z(jqp+|gM$}Y$BbH5jE<hRP
z<2#YFN<eq-WAt68@WnogL=1PV_ff+@BY)a6wD^+S7?f~Sgg<dNCVmdX``?Z(6b-hV
z+P7$xb9AeMeu48xjljw{y))C4rri;(H;eTsv%zqYe-VweFUbG<hU$9XeOQxapF1KU
zu?!x-Z>Pxq`&pTRRjQU_?KgC5;(s=MO!eJOYl&DDPUaG2hsWj6j6Ox?2zznpHvTAw
z3y^)rFuv-WeGH)z-zza*29icOl7WOH43-8s0*4TJo)?zexKO3d2O`FXgSS^Sd&K`=
zb8i`y<=RD!f^?^pbhmVOcXvricZZ}jf|R6E0@B@$gh+QwcXtctV!wNTzt1@1`*Ftb
zm&J2G_Z4%^IoDjpE!){Y4oQBfW;!669{a6kmzrk>Z(Tgo7vjItO`w7ha+29>Oq1jv
z1B1oRj~Z5vX`zZE-q=+_^5@2=sad$aO^4{TK@yTFA}98{9M`}OVAXiJc>ckbxJF(<
zO6*C9Oewro9A-J#O@sldX0g1V1+VAOgdZyp_oHf^K+o~!L=+NZdDcD0C5EA>cVKm(
z=p8Jbi6`AHY@7)RR8~DzzYH2?OT4}8tCUw?a`4bM+qIMv{`fiBQrDyk`z(;dy9=zk
zP?w?F(&D@gJT8h2d{zyL;K5dRGYA^=gx=9rjc-b8qj{%GDn~C<QxeN|3$g}Bgr6T@
zYw18jkoagFA45(PAfj@c_C$aU(6Esb@$c&hnH&Pa!rfogcj$}Dz6=(H9QK&asmbi~
z*v+Z5N4EvvxferQZ-SmK4yRQS2J*TvLhWeuHp8)l@g4%=e4HutSb|u=PmEp?`!}b!
zQ)7O9k?4G#yx|=ZH)xZAw0oCmnjEk845Z=JXU=QF5#s~V#q-UWZKy1hl+>kB-%1IY
zB%;#`saaE^4_KXZea9}Vz=^1ib_C{CprB5Op583Ejsm0FFX^xD$jvu3h`zCkU{p!V
zadXMB{0p>yxiD90LU(V#CBO4xh&vaQ$51Fsfn*LYy@+c+0y~~tS<R*tOn!*4S(9TZ
z>q)HDgvi$D$~jM8D|tK1V*)!u8dn!1Sm_}ey9aOH+7R&Gr;q;VT@T)Z)05yuB&*yq
zB}OA;5_65j{_^`H;muJjQ?0`M6`9(u{n2Q4+O@*byWE`BRXrHVfr}cU$yezQ(Nh==
zB9~<i%lovExbHqV4>Hwf3$l>};t;S(vff`Fi}%TF^MYRfhvSwC3b2m;p%vaiwu5*U
zB<4orE*M<9{lzH*>quGcI4y$*y+;29hnAy$8h*kEMqi&Brn)IL%8=J9=@#YX(4$ys
zYfVRTg_t;vkZ^?;JQ4{I*@VJwJ`*4K$Qh*lNG0`DMlk~~6Aa)Mwy^k;xY{x78Y$y^
zVIhL?<+_zO3r3*ym?gKjHtAf(#3OFLOL2ev!?yPt**6~d5K6?ar}d0mtqbHW{CbP7
znH_o#290q8U*MVD--oN6ZYEh6Uv6&J$VzL_AifMND^Gw+@c=L7AIN-an}C=F{%PHe
zo^5eaflWCC%$^l2wZnYaJ$W?aPi)_}>0<gLk3e;^Y(X8>QbfQiQQ0iQU8o5QB&WC|
zz$8`v#P-dBHm>Kg2nmnzt3{hw7mBHfNDXV+80}w+>buA=i-Z14PndmM0WuhatQfNV
z!zeZr_>mK+tz%R<PwSt&BRggOzunKmU)90(Gdf#l(gzsXRrTuB-u1n4bW7?1ucphM
zPLKA2Y^DPYdJdl85>b@MPfvnDeSX{#rqKC^`~qvNLrG7j=oEmi9fIftqLRwSQ@IM#
zvhzgYv6{=m@3Ga4+iIyC))U|;t~%>`Q}ZUgJ3iLM4;GuwqR@U8s&$>`*4EZa3;r9d
z^5!pu`!4v(=K&!e9_kcRSmJN5W#%lR-prYGTE0{Hs-|B^U4rY^7mkTNS#cUt=&1Oi
zlqdpKPdeo?aD5kBl0x#U@TIhDmAv_nesqZ2h-@?*5)7s?rrNg_^~1m{&G2wzgPM)I
zo1bFDXWoxa@6YraLS~6`APjkLEt`FarTaxMRrnSQc0Rlq9z3-FA2qUB9hz@m>x?x+
zKRMC0<x%|jtjSinDaWJ2!gY(+KshJZfiD;EUiuMGepZtWpnq$KYtc^NO~Z538%Os%
zL|WY_csdkO7lGL{^<5ow#F$%mk4x_JUm}02Nn|qd1V2wqLNwDm!-^Ev2iNjnRntAI
zQI=>!cKL6vyh8mptbWteEAH%I&wUV)TA8(``1*d43i1kx>*~zfIFt2Lr^yAeXS|O0
z@|s9$#InbtJw+H=!yjfXs<^{D_KJmMF3;fUyeYDIo7*>RpAr6d|BH<MlqU8zUz&3^
z;7ZFPj%s{$2<NnuDXD2t6+<j|-+D3PN?<n?@woPq-q4LgCCA)5^eO34g`N|EOQjkK
ztz2xa6?b2vd;tc(^LS}Ng6vJgS8Q3TB$026sBWzt>(qg7$EkHglqpw9Y@lJ%<qt05
zvInCf(Lp}Yr71Hxw!~Knh)j68K#5fZg8@V`@$P3Z)dka(s>oR1*YXEz+8fX48C}b7
z091X!e5Y%A4Xzt7oGu1Aom=a7`0LTb=mPgGv_Zxi<QiH&u#^5_?ru>gevS%1JWj|n
z6LH#L>*C)`J#cYC7OH=-`PejP(M<x2Lf{7W;M0!qGo3t=Vs75V?MrmcN0(i?`L)TV
z38enPkEdvm<7JwB#T9DQlRw}H4M*?|`OX;@g6`$flLdvc5zw+1N#ixW5VO`rT@a_7
z->l(N44GYJsjakrIO9POvCUKykfc_YlC8p)Y@v%gBS(kE$g`i?>K`cFh)+;VW$Ah>
z831RucAQ3Bi$>XNokN>@eTnk93Uaau%Yz;)<tZw(|H^{L=B|-WFpMYN_WQCQpS}aZ
z8-huM)1^Uf=g&GeMO34Lvv0}2Fz{aQFM*@q?rk1hr|Y?$0g(%<^x4>VP7!x{)4#~0
z7LsxFU-*oO@MGJ^<FMQd^_v3s-GV4N)zVN9mP^@A<E3p^b=9<JP7sw7@}rC~No#&h
zTB;yiVF|H*>^6g`aBV@8pT>9)Kz?cuR_a#~`Mrq^<%U!NS=UVMP1><N1PR@l*%nVB
zZ3H4k6j-kcvmrtya3WlUqcd5*>FXUGwfWwNP9V=9lJkV8S)^No!R*ll<NsltcHHT@
zBag+agW1pH*h^NHc(d5Dm#=ow%_Q^8`aZ==<{`W&GY^L~XqvC0iz?NaC&ao6F-w2Z
z*<dA*MIG_Sk)epzcZd>5A(GzUl0QMXrx%QN?{5fv&4L;C5JQj)6GfDXqNU4IHgtu2
zj=hUdJx$}S4co1;pU)^PGmAGXgVuOJKIoGYO5-Ro@$Wzg8+5E4mjd*t^z8oF@#}~L
z#B<S}A8~KA)kCKXFTAJ6#w-u#s=#Gi;kx|a@sL{;C(ohR;WXdVtYY>)QmZ<hd?E-6
zj?Ho%bc1?odD$4qzXfhghK2<jhOj_gGJNhQZ#{SunLGL1<iFV}Ct}6q80cXM-uRAB
z*(0qIK@>hplvtCa*QP<r=jJYcF=jMLQ2Dku-%Vwgti4>yotBDFnau|>!}tsExI-2T
zQ=u*`rR2M|Dqtac1B6IQdA?R`{Q7KJbO$m7=G)+~J-?N=-|yQ56*>!?-NDXL4VN(!
z|7LS1h>Ifb{qGUTdox3I#KTeRHaiD0eZ+mJtaPs_<37B{p98!9VSu56r}VAk<qL$f
zG%gqX3#-U<s2^0wz_=HaP>&}{r?urOW3N$kz(K}i>>!mHVX92)7kg*NoP7bO!ktN7
zD)ZN!?5m9Y4!xK{u0|qt5+>p^;@_^XpUb-Uk0jf%@MH4(?>jZ*#fN+5xIS%X1w4UH
zu^ZqT`hj7kOKfGVyVr~RPQbV`kiNm3!T5{<;@Y5^_w)<uZ-9RE9P%W<G5rt5Bzx_D
zIW7%C9)!V&QC;TkeuUqb#Wp6Y=ALgabDOd-WXcy&`F68^Wcf7ve#fdUY1%8u;97DL
zr`~XNwhp=Qog~fPeKqBnO_y*&SxifG_)eA+A*t#XLcqJ4F)N;}WR{S&U|SXQnRs_?
zO`^JcOEF}7;#I%Jw0|&3_9$|frQbk-gL1n-S+SV>V3?3Qv@uHG2P%^cfO56o`MJvl
zW6>xbl0Gg#Lbj*Oyj{v&_go>ADACu5l(T0LqM0M|1ECA8V4?-lf7>6rd5zl@l-Fn^
zLQD4nr4bzV5?zMgE@H&WLB=z>7JtkW6#<wdb{L|W60?@|0qEJTvI`dUOuI|6*jdui
zh00&PiqE;r)*%yL$8+n>fEqc?Pg(DOD~a7BL%Gn^K~>DenB_{YeukZblBe?~>Vsxr
z&tGv?xVKLf<OlTe8;ik74>p2ZaIJ|n6_C7kxP?C&g5kPjui3U9+}EG&9>V;5%$+qJ
zS_($c?^ga+bUdZ=%K^~L{RY)uIjRCBCPvH_?lx(a3rDkyDp@DkL${*+-sUr+1mFt)
zIj-S9Jf8h}p+kYWaOZXWeTmY!)IQYG;Ew*SjqE!>@oGtXc3D0A0Jd!qk!)lV`g+d1
zpEvFs7pF7Va9!f~mOb%9ViZ!`Zs`RjR=nnM>uee_p<3K!Opp`m)vA2ElXQp$0dWc|
zSdWF?UBWDqw{>v^7py81vv6@@PNoXj^^!ig2uzWP@mL76_>lg;?i3G~3asrn4r(Wr
zTENi18jefQI;x(ZV@k3QL@+aIvOlJcbv?7~F)<E3AGF6zrw}E0sa*PjpL4yep%;qg
zKaeVdP!;RIs)SM0Q7k=sX<5EQKtLe72#ZEMRLeT!5P2=8DL1f1Z78d4;M|K}kd;%H
z{{{Jr`np&pUls>aV7JrKhTs?2tL?n?Kbbr*&k)+>RodPTq%9AMB29y&ybx*@l&6Wy
zkSPh2PaOC3p&SechViRYPmb6@A%&9Eq;irq^1QEA3?`%Y!-;y2Wmj*~4L@8HuEwIN
z%jzOI0mr3&pu`QO=sHMSSzVrNblxb1i4UgeSSUieL6krfSQWWuDdGJOpQ7)IV(e9#
zbeBfd#^T(Ql5uRPm}Yu!>)Jowf{cW=k}mQ2PzqM-i97%&HbF_3<4Vf=gZF!NdQvcq
zh<RBbLT5#)hBN$F0wqM36j3>R$|t^K(lMBV;}7ve$53{$r;R8QsoB3?`H8`gTEQ@5
zg|k4@qcIhcMJpCy@{<~v22Ke;{DulzKcDYuQoX>qdFnsj!fflbCps6YdET0hSrlJN
zU-L|3`b8w+*)dY^>{x%deJJQq(MgZdsvPw905^iz{c?QCG5ruG_y6oHJdCcG$E}oi
z%U@SA7_39oKC&poCvZP?a#B&XgOs){po?hA%R-ukaZs0OB`%aQ1`&w-{6tcx78fy{
zY(Xrh?#ed1CjAb+o@UtmLw%qG9^?`)eP>hB2Sdez*+`_2U(#2R5PK_;OD%B$q)BTG
zn79b}%mk}W7a>syy+XrplUC?zqSicZ(ya@00oL|d@$;0LnmX;Qw&}p{s}%Q&;hZrJ
zuN1`LK`#-H=4Ncq(4;bLw+$*RltKHqm?LH3jgon3<%<uSmy3^P{~n5&Ol2QpKf=2M
zN<l$TWuTrn#~R#nS`X2hank9hY8iQN0q(n3t11Km9>E&n@z-ow9ICT4s;_7Q*3TX0
zC%RhH6d|Ih*vm~^2r63iYKvFBALDvUAXH)ZZzp)VpaZQ2rnWkLKJ1o+m|d-_ScZ#J
zaF;{1AE#T{=fTeH9q6ASQO%L`E3LlpFMs?P52rGC=nc04fg^la*?oJ-@`heb^mxOZ
zi@Bb|^IRktr^gNbC5b1X`qc{__y=mg$}@S<1VOWfRPe95^s2X)6U?{<&Rp7^8}nhc
zn+fvOkB6ZBXUqdz&cm2>KT%oechX}F*FwZl;(;DB-~8tu8*bG7xkNsP@2Dyhc34Iq
zg8M}-dBsp_#+7(kgu*{5M7!|rj9hhcKMt`=ipH8SU^WqRno>NTxz*;hx^#rhoIr+B
zzkiyxwJEx^bQi;3Q9*AzWEeW3=wQ>r8HsHN%twMgQz_CeFPgb0Nm))9GCtd+0z3W=
zWyQf_gY2<A#BO)+wEy46=$`OCV8GUGQPMo!Q6mMK=0CKXNYA`5FwvEi)h__sa^LF=
zO*@w^nqI1zNasD-;=YZtY`4w+_*%+3BhtG2sT!ZX{FL&>b;JU#%JNV2;dN|k!-tDa
z$VY=YZLb@s*~H$eCrQ`i>~o3oI9|)pxokr{9q?5qZ^jWve{|EtNMYRNj^l$aM#Pbc
zO)e4LCW6L@SThht8-ZF{q@ZJg@W+_*wym4l#$i8cy@&;<e@b0>3wC%XD_}X1FSuBL
zsBYG%Wh+^KglFT^jMvg{-iOQM=|#Rc^`kmJpPTwu&?Bz*dp|7m@4sjp-MM~B{Xc6n
zO2!(s%R?wRaDp(m=#_q7)4{rr%Fmi9>)>Frha`ult>jiUHC4rX0P5Q>M)*rT7EPm>
zv~=IUt|xHOnz8BMa<tXA%?cADmPYT|EOb2;p-&|&o=~Td^k1ETcT2<jI>HXqneT)i
zj%&yupoPTq>w9@3mJF65e}+RIqlboM*F*6XmeZ$j1GWt;PVZU{0rziKlR30b<rzt(
z7u_q%4rJ$wug54Y%IaqLKw`8`2v~;iiiz+QVLHIE51Q33vp=E|u$qS8hpYM5GOsTn
zojtMn-E*As4@9zh1moX;kcVSHT*%Sm!Q={i{<kGhL90e4n7@OK-#A0rVpc~z8{D?)
zEA^AT%F5Q!vJx-lGY1-oCnF;9*(K8|y)r1O44!z2)|y-d>Ep1dgjUCQ&`q@A8@mQ&
z`x;#MVxR5mq?R#WUBQvQhoaa`J(=#(9_L82t8;~xLis_Vq_JQ#jg*kA4fm1OJ+$~_
z>c+sP)@d7IytnX)gSbLMGUh}a){4aayCtO_uyL>s@>pYvqnTV?jaOFS8H#`A+qbGG
z8e!>1CT#oL;;1`<18?k6aHM4m)C(j+0D(t^p9LD+b4C8qwO=@-cbJXLtuL4fWVL|<
za+vM=-NIahGon?;kkPkYdr@=7!%fWOwApaLi39HyU8)IJW4k%kB2deG!A%ct|9!^9
z?=>(GlL|bV<?muhwz<4>8n003At8;LC^aC0DDbInF;)jngJH;fc_lD&0-DHcRaI#<
zr;(=Ej9z*3F$Yopc6n;#<5itq`bi=-<6nR#BAH@KUaFJM6#QsX-n5<j>m(<f*aw8y
zw%zZSl$PR9vY;J4`2pKmnpQIi(>q799mjYKVoZ8x5^m<}*Q=$~X<gIl`*?eX`_6^+
zn+(5yAK0k>lb1;8xtf;D=jUeh9Tm$)5vQ$;`g_R(6+%BD&C50WiL1M+`|3Y5R&Aj2
zZpMN1m{p)Y9o=0P*V!{Bwt#+XQ2*EDh=-2|&Mpy-=oK@rRqltKFmJZmNDN1tM-~*2
zii{p8<u@krO0RvUFvZSERS$kI`b)q{Xj{L`rW{Fn$t^WEJ$zIC?pd1i+vs6{z2`@2
z=EHV<*I`a&zCFqT&(a>H01CN$cs7BsABF%e^{@AD(Mv-9EjSdWf&kdsnb=`}(I}0n
z<2|?!xEZwPU9H}ozKf&>jK=?tqCl4=0IY{JDcFBC+HgD|)+02Lofj5aaJ1abDD4HF
ztQR}K5Y9G5`5w#Omg)0Jv&f-iXZs8lM*eqOK)^B<TPUp=vAJ?L58KQq{F7X!rMu7P
zDAq?Ra}M)O67ri{p=?HN9=3rD6d#{*>$u~>Bq}%hGm~sK=Nk<W-g09kr8qMid|h1u
ztLaekf%=WP#VQbE0fE%<LjD*1$h;p7c%tx-lJmJs&>;p*vLGanuq=-ShKH|%dK;B$
zP!|E>5vQ)M-lf<rWsM<vNS1L=V*k^_!OLy(Kh_zn;b07NIAW*Oz)-ljcaT=p>2?^A
z&?JTJ*X4mo@5)JkW9lZ>@0v!BHwGvCL^Cq97$7TS)G6b$7{aS(SA}BbCir<NE<aK^
zFaez{gEZiR?e&PRbl=9EJ;e+uI{7u#m5hN8rf50t{<<><zcA}{HsO1l<<$hX{@MrV
zI0526!;oFiHJ&(~&V>57O3`bPpVoRzEG)tX*joe1hQe5Y*^E8a6p@{#;6BErH1%g#
zR$BX!tzwx#nd%_J@1Tn|?Tj;<y7axhvi+K!%QoISOV?30kcl75?|H0njvwl=7K%H8
z9M)F74P8(6;qDxKc@&Gg*Vauc?eu$7P3+~QS#l{&`5e!KL_+7(M0XrzK>MD8d;(+n
zc1<XVZhwftlZn!Xs0gZww66WU+M5igvQtaIW?7!lq|IP3h@_U#)RPx~lBGQcJb3}V
zAg3e}2mVBdSfKs&;XLRuL`12xt`zM;9uj|Y$VGFO;mL9%;A&6tZVvU*sR^0ZHLr;<
z*PyT~PFfn;ZOp>J8rI@3!YrI`2Y&#M%Z!eNnJ{lN73yxtFxkm0z(H3HhHZOxDu2f%
zxv!Y$E;V~nPe^eH0?j#W?9U|??NOeuHg=waVUP;>KF;@(tQ#a4(58=B_%_<u?sMt5
zB9-vSRjq*2<^iB~GZKmbr8@CYbj*+dsSxypP(rgV)r*VHj=#eRX^gJ%nvC4hgqix-
zI#>~G{=LgV=5$)bf00SNH{-Kqf0Ec^m4uY3gNnEfTz{wBK9{>)_j5Qcb?pJLpG#-u
zqafom44XKzrOsgzq8TL9x%Suf7n;UMem{m5MkA1LQFu)jI5n4vmo_Uw%gRfcvdvuM
zp$=I<D^X;kHZ1hhI_%S3&*9AYeD>o@wJ;ZbxIT(zcyXXA178PAz2aW|w;i`k(l%b7
zODof5aCTSKMH_2fh?<$EB!6MXC9>(o-25JIu8ZKS&T|R)A-$zd6?igAFla$+ATFP*
z1+t>$*oUvb=6aZkk15gmXk&x+yz-Kg|CeLc<z|`3oHHE9o1h8Z8Vgn3+Hd#glh$VU
zmwR>zJ(BYl8TO5c=~nt(YTqZ!w0ou{uc@6JihTBiqGue_))Z3qh@{Mwj#!U94ct<0
z7`5wOQ-6(Kc23)ekEb^y2(=x_mSjs?zF^PGrAON&$r%6+>`hQh`JU#$6>Z*K&Axk{
z4fv~_5de#_No7GALwkQi5_nt7)ItamvuV=Qm@Zb{KmR(%nu(wpkm1e<luA3JS<eAt
z|9duaJj{o^A6a3b95(KRC{EBLm=qA-N0&Nwl(!Q%&%q~Plr3tl0+A@+eD;ePR{Z%h
z@aQ7PiD?|iMq`Hd4=OtRXAM17lMA#fj6&|UjOKUbtKR;_Ov5q@RqUGn8m)t=)mk)i
zK7OV273rB$i5|3>?2-q(?M6`eW_6Jgzb|j4+~ARD;W60nRWiDqt++bC<Op1G<dY#H
zWpkLZgjdG9VPdWkfFyy0X>?i>v(US~WEeyK04Rx3pi;ghgHaN?#Io-%<TJqS-Nmt%
zl!`f4|HdJ@oy`n*zev^wt#4wCNEQN}gDxh6UriJBnw|)rNkUIu-4?E}<(Bb#T1>KL
z$*Dfdd~1*I^}(X!Qls->Q*M%^{<i?BZt?ScWnsZfK$=)q;M)4xkt_}7t&zRwy`}lt
z$&Ajak4bBuZdgs#ZqgjRXK4J3sWFy0do?#iSEr!KxI)6$s$4cCdSL)>1%u^S(iyh&
zLU+ydr1VR2l9Ov0I_;VKdE$~)bl^Gi7h`y0tUOAXdoWw&Wx+<&9)6Zxn|7<Jvz7$8
zU2y=`CTxdTXt)Ty&wpRAWpEkcl=H}Z(NtbP@+jglhf2V)3-Y8ShD~$i;r@MA#{2<O
zXN6TPS4U8oTJ9+bBC(U8tCfm=#DtkBBO24DQqhZY?dLzuqgsC{lL+3Bqs~v6kC?Os
z3rPe|zy?Op{e`%l6!g8OM1S$CPB6x*n+mo`kg4-;2ev<X{5Gj>c?^ATa=_1KZY7TE
zFq`G?-l%Ns^_+!-knp(SM9E%id7)|7Y%TG@FV)Gksp@uT-8V)3Vf#MqTpD_UIn;XS
zXc>%hVs5`RU1(I!6hIhEuRvB&w11kH)gG42RK?r7=0EOikxDra8i<^pz#Q0d2_qCA
z40B$lqG=jCKVNFCV-BW}`eapOP(l_0jw3PnoO5>9oe?4~JDmh-&KUED%Sz+wt!P(y
z2WB&}LGn~jQB&RciD}<be-JrVg%F2&wc>X}grm4`j(8>f(J>eid{OV{TJAxZu5*wy
zp)<6us0Mk8Y#D)uMBNXza7n}i2qyXA-^RZlZ$|>H9m^n=Cb<5{a9_FZ)rX$7J?eR?
zG8<@e2wg-v8}6*}&^`TTbvs#(Io%O@ICOQ26^{#uV6~Z6t4++6h)>KreM@>P*IT?n
z3~XL`DZF>*y&9(&t9IRA#4>D2tY<SHcBeV~Emf76lkjZ~PpmapEc`79$U@>svBls;
z)3L=*9xq0J802W;NTM%DG1`XVC@H3&Bn^-*B-0SnZ3mf{cJY2fO&$Tkgp2_ZwKTzH
zOekL?LfHaPXW=toYPMKM0W$aR!3eLxs$MQEVPE-8FvjV%f3RQn0F%<Gatgo4b<bL#
z8!c}F`woZrsq$BfDEkct`IA=jH)%TtKU(_gadw{4;?m+Xu~sr^8so2LQ1*lG+QO%(
zR<y=$Hvw2&_s4kp%IA(~iu{h*l)83n%CwuTjnK&NN)vN7i6?iLSv^?3W}qQ;lgrhP
z<>R(J0mFv@Dt1(f3Va+PpV~YU0WT+d+y%06m46@lE?lPIY~vR&WL;%AG}G}zm5u98
zFbeS-;$I3T=sg>@xWAvo9VKnmQAoVx-%3)aZR;n`un#}%u(_armWrmwu$G%~+a5~O
z$N=;hO{L%NmJGDBI+}byamI{ynbnht|78-*kgj5<bDkbr$)gto)6q<Cbe-0fgHsT#
z(^Imjb_9FG6E~CLmr5_EVy5pIpLGLLt#6I}3%MaZ{u;Xcrm{oK|IXL&F(bG{L8iJb
zROR%qbB%Lq5vm*<ZbIQfSqt-y-Ly|yx1G*=RNRk#oan^6r&y12n22@RoF`Hke}I*7
z16WP+Tu#_VLjT>ww2Fuv8`O@GmR^9wG(L_GHAAosHP_kvj%-#EoW~Zl%aHt&@jGw5
z2L>f?(X%tKI+;Mf)c!zucjb@l?#Ck|x=@Y05WE%B;C^pQZYgtoX^iGhfx(iethl(D
zI2od%dY6*E-+bT9(I|3FAg$lOf>vNu8X<q0d#L|$HLw&A?C_bOS(qKa)Bo?iD$6wx
z_j1eLvrU-`>9@Wg^Cus(>#Q>Sr51S!B$mA2Ef-D*7LMmkuoRtB!-ubbt3nW}_5I?5
zTbN~FC~L%Qv4=w;cmyj~U4r}P=Alyvx>zu{VWA&VWGV!&rV=fIqZ4oxeNi*XHPlc#
zf9|=?ws~M`Le}IcB;XkY8S8YN^sBL7SYMkEySA$tP-CJVLDIhdD6~nqppX3KOc4ft
zo{iB?rIyz0CsD%+tJ5lI#uOM6`*B65z|ZPH7?)@l(K(P`4~G&z#q9-E`O~19YIUde
z_4yu9Qk%gscMjJROLrE$Dx1+sMEYFa@G4hQHL#-XdI69xwMQVa7RVSO8pCz$d$!wL
z+A+j#ikw;U<SoOV-O_w|vPOO3MGoBGPC)%1!7XHFF;Tj86NmI#3?4y@EJOu^;8lJA
z_j|+~A+2Xn=rXHv>z}AWK`DQdHb_bm#?(}(p6hPGpx|)sXNBATk;75myiY$h3t)<<
zFE?T9A(l~nHiycm%ZQA4(}h}VY>FJ$4L}eyfkNML0rNJl5Zkl_G`U`<+au~K9+QUZ
zFcD^;WC)K6Tnqup!uxV}9NKnrHq_zAm@Qd`7{4(CT~yLrT$!Ni=r1Z97>b0#iH%xN
zk!fLm!xZnFb#Q9a?lO+A@My8*98w$3hYfA;oS<o3@n-#&TfIZX@*w~y3O@CWLKpjs
zY;XV9@zxB~7KFc>K>~j0pD-EGl9Hf0wTl!2q|mUIL&?sQbD?^phSywh*AzH2FNJIq
zu;qeSJ%A`%-25s25V$Yc3p1LK2YhpQNKPIK#9b}R38L%1aLy3ZN-WEWz~WGg{sC#A
zP1ZeemH{!`pC8NY^BOAdPvnO(k(pV!ek~std!~WGR12%0V{S1Ocl&Vx(?cH|pVRRp
zx*Gq~FJ7OlkYr3jUyv|i)Bo?XAbSu0e5w2#(rlbUL>@z)FRQ3D(+irA?tjAhth5w1
zr&69U)?1!*ze%XA-QqWqEM>n(SGkSH<m3?st~It6bUF$AmFLQhEz^we2jm(<ia(yA
z-F4>@JVB%CSaMujkph~JD)Wx$6)Ug2i?OYC2B{mf`VJ?%dYK))W6w}6f}=hPZ-Jk{
zd$D;Gev_Xel1R8=!lM6Tvh~k;c}eSW&`7d)3GC+Lq$TFbe*`8h7WD>9GE=|m^F^H#
z;8pg}Y*=~=XO>=6^8J{hF+wk1ed#EXg4Z+wR*pB6>m7d=J6<;?sxV#*f4%izlKV6a
z(AxtjO(_EgV}!O-%}T?`umW|1^6jcoZaxox&8N!08y3s%O_156xhtD6NO?3kkXz28
z8&=qsmD@i30^PQ;_nOuF+?>(&3&OvP`nCp_u1@b;KMP_v5FB7MzL>Y9yBl`znjI~V
z6?I)ZypQPaM@80ZgQ|e-9_xX4Hdm&2?y0JpUBy-%k1zYoxb&I-xbdX~X>+>dB8`z%
z=T{Qa&yr!Tf4xUG>_yeW`ul@RhS2>kMRBFmM&VU6cmNQM?%*}<VToa}v}<rSx=vn@
ztU0hIJL$j1oAmr{HqWnJUXiIl-ChypByxd~ZtZQ-*+^q-o6nUgE;*H}%*9jp%Javs
zoh;z11|=H0T39D6{mk%psTfmkTw5Pg_hf4Kk+hQT;P#;#UgYwP#E&ut@#5Zkqfn?U
z*w&GjWuu9qLdR73LWQ%ziL$Db(ag=eyrT~%9m)^<=iy!|)joU{KN)o@0}BEUlY2~j
zySib=UxsD_YBKj-Z#wZsP|%`HLp5}i{1D#e0fYlz&*AOHwdIGJ&X(kd-|7czvV)=L
z(!fBc$Voaeo=B~jD-C1GOawmZ3&bJQYx@(eLnI%d=dZr=F~-QYyp9@1UN@cwr3HLb
zA_Lgced9MR#!*Y_&GA&32Hzi<4I?wwA5)`5xM#d|?)9@oCc=QVdjE^I!Ar!&BnMiV
zOpuCC!FT8g#%k9D2pe1N=Z;^7p`lrop#niCFqIE;JF-(30G1Z)Q=3I&|5&Dja<IQ=
zy!ee$4b)rxNup-=iYIyZ$RBf)xm8~s{4hDvy~Q)!YgKA}SUNAh_Suw_%OT7xxB0r>
z6rtJ_ZPXL${)^VgF5=AhO6O||JDq{odUC%~IZJ3x)PeWf_RFgS_aunwVZvS~@kh5o
zaV&4emcDt_bW?4G1$2CsldA2gdc}CN=$u^TquxiWhoc4>Kd|&$Fh#cPfP=2zOz=>f
zGEA;9zB)PU!};%0-I};q7{rd}BU;2FmJkK8wG9Z@wOv8tq7vB>!M>0(KaTG!z^H{^
z4vL(Z;M$0mUW$3Vlf2*Lyb5oeKAB1_o~MaU@2EBKebE1gB!sqPx9P8FUzVkDHFMZ=
z%(K&1go@9$*_Yw)0W^iT-=E7P&SC0*LHX~E@fGSW<w{1=%CmpCJp~7}NB=4raEsBj
zpg12XpirZnl~oIm8b5~GNH$ws$Ih$f;u%WGJ6H1L;)fL|4a?Y_I%z$!cPzy8s#rTH
zr3fz^Y`nGKGU;A42`BFJuh{_!KJ!wvVY12sKf~P^DVgrX)#J#Ciulmo^UPCt-~?DH
zk9|)%!gEr-aw+XaU{IVY9W{F`0g`-X#n{io+GWk-ZYkSbr&08h%-RYXH`c_Qg*6yo
z=Z%r=L#E07{IDFaA9ITy(=uCPHzi5H>=boFf+an{ADL#xT*J3*mukl&w`UtgQ4&gC
z^V)AP|J_t<Xx^BH5^oTE5aL(_010j-)?ZK!yntN;GTXuaP3CkOq>M6uoqP6$Ntq1x
zX$>XWis4|JVZ_I2!!T)?AeF+(@Bau8y4mcS(^#KI!zVNsO!>^M=)}L0kKrPo8f`88
zD~hU09(qw^g{X!y-Ge{F8A{W1_$XgeQgN_QC*N@V2l@Gxk=npBUQXW`qTJ0;OLg8j
zl5SmS<JBkLs}MUGCZv5BOH?J~>4D^NU@B0{h5Zs8Kd3aG4cBib@b4ik=B85OtaZAH
z32bEe=E!^PMuNV%n7a4hM`Xx?@gq?(n-_XT)vwX(Nv{<A8k4*jAt>dXDQ1e6UKJt;
zeDqkii&js?wW)CQ9O4H3pyZ~!zwevxp_P8;nVqvS*KD<YV9vi)8?E)Q8&CgQ-|NHg
zeypKs_<s4j?yuIcpY?7eIb3v$*e}cpoq7Sfy`tXd$5_d1^#6g0I3DN;zr)E4L0cSm
zIhnMHgjiY%O%W|UXUS+cQ-WkK8(W*<1+leN!W{fK)LwYW&w~lk%%=*?!lLc>Rob;-
zx!7P_dgTHn3;FiymYG}yi^1G0x2odNhssY<N_);5cyT?owJ`xQ>XRWFkW|JB>bD>)
z-(q(xXQMC1On>9??!uY@le-Q8I2rV(Ck!$8qF(`jX9M!HkxW;CnY|O2+$%CvMkTJ1
z^k@U#RWEzWC;B0`Kt*>eKV=IU@@_o$?Dh0eXZ~<C_2<>#MdB3vBCL<44AHldwz{|T
zPeU$f4WTWnYc-uq1W(pslob+J7<k9y-{E|p=i0s2BWacalUZAoos7m$oEVex-}`#x
zUHlgQ#!zK2sgblgh@Nh$vlU2NRw>FsD#daRATU=3gMACrPT9Ea=39at&FI)wc0X3h
zyjm{H7N<qWRN5y6O=ah?iFb-eovw<guaxsvCVOjxKGi>T{xD&+*`w*|WNU4zKcAjX
zzE)tl`{h3laAAq#O1ov2A6LVtYcv3B$TSrcAL2=3OY|uJ1-Bu=1$3vFk=P^Wk(0pA
zV@i{Y`I~T^A4oL*^(Lq?Y3cD1Uq$)Ol?NHgt$Da^t#xCUaJZ(-ofB{0S4pZNQEO_m
z*VNP3TIn{wsx|WWBeFf0Axl#ehUg4LKdJ4i^2z*!za@n)Yh<$pY$P$P!ntX1_VoW6
zvdAB4&27?@2mB}6Sn3_@*WmxHrO0aH+b>?O(v)`}Sp61iS<U(cfO=M#1mfhoe3&4%
zr-4(owl)0x%S=G-l-b{5Z)kpI{nCKqK)8puqnnuVTk@uysz0~ve}<U~=nljaFySmH
zbWc+<ktcktKCg}vpcgENR3!7*o9OKe&ny3OQ=8L$)&d;wCmqlJ^?rJ@F)x;du3#9A
z2Rqd%*(-#9Ki9Z(<fL1g`hbQhliFcY0nDUeQUxKG9iFCgk%c$t;o5K}@>&ftC%U;D
z>&>hWkttsnup2b6W<Q-Y*l}ZlW4cipr8rG}CVA)}(l_}s@{MotEw%FO&floDm8#!Z
zJYG#5`UHJSbv$U$ls=!OE<9ok>_#&MS+(&Y-#}Axm^wCFf&$TXd+07D0Q|bRbxz)(
z`S&&Ukcd)+Ez&&Q1H#KIE*3~x<8xJJ(j06qoBcqJFaq)c%{RA+PV8TVu0zys91q{?
zm+Wm?>(FbRjDHV!eu7dby+HQ@wrso~g1PaQQZWR={*Rx9pKhbWqYWFKOq%n3@vc5R
zKVKir!3V;_Ll{3FHQ`H_BS1bQ#`Sx)=s<*^LtGE*9S~OEEEB)CkVvBCwDslgOLaZY
zIDvp5gNA?*fro^EKo^66c=@aU-+t@=(tq>+{^$Q+_{{%5{b7M5g}O;sL&x*-;9Wq-
MN-9Z|ix~(1KZItKMF0Q*


From 60de5bbc32b6ff283d386d00ab7d07fe1564931d Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <hugovk@users.noreply.github.com>
Date: Thu, 31 Dec 2020 19:07:31 +0200
Subject: [PATCH 0058/1034] Bump typed-ast to fix for s390x (#1892)

* Bump typed-ast to fix for s390x

* pipenv install typed-ast==1.4.2
---
 Pipfile      |   2 +-
 Pipfile.lock | 253 +++++++++++++++++++++++++++------------------------
 setup.py     |   2 +-
 3 files changed, 136 insertions(+), 121 deletions(-)

diff --git a/Pipfile b/Pipfile
index ba596b3d738..9a4d5bd7c1b 100644
--- a/Pipfile
+++ b/Pipfile
@@ -28,7 +28,7 @@ mypy_extensions = ">=0.4.3"
 pathspec = ">=0.6"
 regex = ">=2020.1.8"
 toml = ">=0.10.1"
-typed-ast = "==1.4.1"
+typed-ast = "==1.4.2"
 typing_extensions = ">=3.7.4"
 black = {editable = true,extras = ["d"],path = "."}
 dataclasses = {"python_version <" = "3.7","version >" = "0.6"}
diff --git a/Pipfile.lock b/Pipfile.lock
index a5c38aa0777..dd78a3c3178 100644
--- a/Pipfile.lock
+++ b/Pipfile.lock
@@ -1,7 +1,7 @@
 {
     "_meta": {
         "hash": {
-            "sha256": "21836c0a63b6e3e1eacd0adec7dea61d2d5989e38225edd976ff144e499f0426"
+            "sha256": "3c4e23d0b6e49bac5ff2347dcb07bb4dd084d39b78c93a32359842dda401e7bf"
         },
         "pipfile-spec": 6,
         "requires": {},
@@ -259,39 +259,39 @@
         },
         "typed-ast": {
             "hashes": [
-                "sha256:0666aa36131496aed8f7be0410ff974562ab7eeac11ef351def9ea6fa28f6355",
-                "sha256:0c2c07682d61a629b68433afb159376e24e5b2fd4641d35424e462169c0a7919",
-                "sha256:0d8110d78a5736e16e26213114a38ca35cb15b6515d535413b090bd50951556d",
-                "sha256:249862707802d40f7f29f6e1aad8d84b5aa9e44552d2cc17384b209f091276aa",
-                "sha256:24995c843eb0ad11a4527b026b4dde3da70e1f2d8806c99b7b4a7cf491612652",
-                "sha256:269151951236b0f9a6f04015a9004084a5ab0d5f19b57de779f908621e7d8b75",
-                "sha256:3742b32cf1c6ef124d57f95be609c473d7ec4c14d0090e5a5e05a15269fb4d0c",
-                "sha256:4083861b0aa07990b619bd7ddc365eb7fa4b817e99cf5f8d9cf21a42780f6e01",
-                "sha256:498b0f36cc7054c1fead3d7fc59d2150f4d5c6c56ba7fb150c013fbc683a8d2d",
-                "sha256:4e3e5da80ccbebfff202a67bf900d081906c358ccc3d5e3c8aea42fdfdfd51c1",
-                "sha256:6daac9731f172c2a22ade6ed0c00197ee7cc1221aa84cfdf9c31defeb059a907",
-                "sha256:715ff2f2df46121071622063fc7543d9b1fd19ebfc4f5c8895af64a77a8c852c",
-                "sha256:73d785a950fc82dd2a25897d525d003f6378d1cb23ab305578394694202a58c3",
-                "sha256:7e4c9d7658aaa1fc80018593abdf8598bf91325af6af5cce4ce7c73bc45ea53d",
-                "sha256:8c8aaad94455178e3187ab22c8b01a3837f8ee50e09cf31f1ba129eb293ec30b",
-                "sha256:8ce678dbaf790dbdb3eba24056d5364fb45944f33553dd5869b7580cdbb83614",
-                "sha256:92c325624e304ebf0e025d1224b77dd4e6393f18aab8d829b5b7e04afe9b7a2c",
-                "sha256:aaee9905aee35ba5905cfb3c62f3e83b3bec7b39413f0a7f19be4e547ea01ebb",
-                "sha256:b52ccf7cfe4ce2a1064b18594381bccf4179c2ecf7f513134ec2f993dd4ab395",
-                "sha256:bcd3b13b56ea479b3650b82cabd6b5343a625b0ced5429e4ccad28a8973f301b",
-                "sha256:c9e348e02e4d2b4a8b2eedb48210430658df6951fa484e59de33ff773fbd4b41",
-                "sha256:d205b1b46085271b4e15f670058ce182bd1199e56b317bf2ec004b6a44f911f6",
-                "sha256:d43943ef777f9a1c42bf4e552ba23ac77a6351de620aa9acf64ad54933ad4d34",
-                "sha256:d5d33e9e7af3b34a40dc05f498939f0ebf187f07c385fd58d591c533ad8562fe",
-                "sha256:d648b8e3bf2fe648745c8ffcee3db3ff903d0817a01a12dd6a6ea7a8f4889072",
-                "sha256:f208eb7aff048f6bea9586e61af041ddf7f9ade7caed625742af423f6bae3298",
-                "sha256:fac11badff8313e23717f3dada86a15389d0708275bddf766cca67a84ead3e91",
-                "sha256:fc0fea399acb12edbf8a628ba8d2312f583bdbdb3335635db062fa98cf71fca4",
-                "sha256:fcf135e17cc74dbfbc05894ebca928ffeb23d9790b3167a674921db19082401f",
-                "sha256:fe460b922ec15dd205595c9b5b99e2f056fd98ae8f9f56b888e7a17dc2b757e7"
+                "sha256:07d49388d5bf7e863f7fa2f124b1b1d89d8aa0e2f7812faff0a5658c01c59aa1",
+                "sha256:14bf1522cdee369e8f5581238edac09150c765ec1cb33615855889cf33dcb92d",
+                "sha256:240296b27397e4e37874abb1df2a608a92df85cf3e2a04d0d4d61055c8305ba6",
+                "sha256:36d829b31ab67d6fcb30e185ec996e1f72b892255a745d3a82138c97d21ed1cd",
+                "sha256:37f48d46d733d57cc70fd5f30572d11ab8ed92da6e6b28e024e4a3edfb456e37",
+                "sha256:4c790331247081ea7c632a76d5b2a265e6d325ecd3179d06e9cf8d46d90dd151",
+                "sha256:5dcfc2e264bd8a1db8b11a892bd1647154ce03eeba94b461effe68790d8b8e07",
+                "sha256:7147e2a76c75f0f64c4319886e7639e490fee87c9d25cb1d4faef1d8cf83a440",
+                "sha256:7703620125e4fb79b64aa52427ec192822e9f45d37d4b6625ab37ef403e1df70",
+                "sha256:8368f83e93c7156ccd40e49a783a6a6850ca25b556c0fa0240ed0f659d2fe496",
+                "sha256:84aa6223d71012c68d577c83f4e7db50d11d6b1399a9c779046d75e24bed74ea",
+                "sha256:85f95aa97a35bdb2f2f7d10ec5bbdac0aeb9dafdaf88e17492da0504de2e6400",
+                "sha256:8db0e856712f79c45956da0c9a40ca4246abc3485ae0d7ecc86a20f5e4c09abc",
+                "sha256:9044ef2df88d7f33692ae3f18d3be63dec69c4fb1b5a4a9ac950f9b4ba571606",
+                "sha256:963c80b583b0661918718b095e02303d8078950b26cc00b5e5ea9ababe0de1fc",
+                "sha256:987f15737aba2ab5f3928c617ccf1ce412e2e321c77ab16ca5a293e7bbffd581",
+                "sha256:9ec45db0c766f196ae629e509f059ff05fc3148f9ffd28f3cfe75d4afb485412",
+                "sha256:9fc0b3cb5d1720e7141d103cf4819aea239f7d136acf9ee4a69b047b7986175a",
+                "sha256:a2c927c49f2029291fbabd673d51a2180038f8cd5a5b2f290f78c4516be48be2",
+                "sha256:a38878a223bdd37c9709d07cd357bb79f4c760b29210e14ad0fb395294583787",
+                "sha256:b4fcdcfa302538f70929eb7b392f536a237cbe2ed9cba88e3bf5027b39f5f77f",
+                "sha256:c0c74e5579af4b977c8b932f40a5464764b2f86681327410aa028a22d2f54937",
+                "sha256:c1c876fd795b36126f773db9cbb393f19808edd2637e00fd6caba0e25f2c7b64",
+                "sha256:c9aadc4924d4b5799112837b226160428524a9a45f830e0d0f184b19e4090487",
+                "sha256:cc7b98bf58167b7f2db91a4327da24fb93368838eb84a44c472283778fc2446b",
+                "sha256:cf54cfa843f297991b7388c281cb3855d911137223c6b6d2dd82a47ae5125a41",
+                "sha256:d003156bb6a59cda9050e983441b7fa2487f7800d76bdc065566b7d728b4581a",
+                "sha256:d175297e9533d8d37437abc14e8a83cbc68af93cc9c1c59c2c292ec59a0697a3",
+                "sha256:d746a437cdbca200622385305aedd9aef68e8a645e385cc483bdc5e488f07166",
+                "sha256:e683e409e5c45d5c9082dc1daf13f6374300806240719f95dc783d1fc942af10"
             ],
             "index": "pypi",
-            "version": "==1.4.1"
+            "version": "==1.4.2"
         },
         "typing-extensions": {
             "hashes": [
@@ -499,43 +499,58 @@
         },
         "coverage": {
             "hashes": [
-                "sha256:0203acd33d2298e19b57451ebb0bed0ab0c602e5cf5a818591b4918b1f97d516",
-                "sha256:0f313707cdecd5cd3e217fc68c78a960b616604b559e9ea60cc16795c4304259",
-                "sha256:1c6703094c81fa55b816f5ae542c6ffc625fec769f22b053adb42ad712d086c9",
-                "sha256:1d44bb3a652fed01f1f2c10d5477956116e9b391320c94d36c6bf13b088a1097",
-                "sha256:280baa8ec489c4f542f8940f9c4c2181f0306a8ee1a54eceba071a449fb870a0",
-                "sha256:29a6272fec10623fcbe158fdf9abc7a5fa032048ac1d8631f14b50fbfc10d17f",
-                "sha256:2b31f46bf7b31e6aa690d4c7a3d51bb262438c6dcb0d528adde446531d0d3bb7",
-                "sha256:2d43af2be93ffbad25dd959899b5b809618a496926146ce98ee0b23683f8c51c",
-                "sha256:381ead10b9b9af5f64646cd27107fb27b614ee7040bb1226f9c07ba96625cbb5",
-                "sha256:47a11bdbd8ada9b7ee628596f9d97fbd3851bd9999d398e9436bd67376dbece7",
-                "sha256:4d6a42744139a7fa5b46a264874a781e8694bb32f1d76d8137b68138686f1729",
-                "sha256:50691e744714856f03a86df3e2bff847c2acede4c191f9a1da38f088df342978",
-                "sha256:530cc8aaf11cc2ac7430f3614b04645662ef20c348dce4167c22d99bec3480e9",
-                "sha256:582ddfbe712025448206a5bc45855d16c2e491c2dd102ee9a2841418ac1c629f",
-                "sha256:63808c30b41f3bbf65e29f7280bf793c79f54fb807057de7e5238ffc7cc4d7b9",
-                "sha256:71b69bd716698fa62cd97137d6f2fdf49f534decb23a2c6fc80813e8b7be6822",
-                "sha256:7858847f2d84bf6e64c7f66498e851c54de8ea06a6f96a32a1d192d846734418",
-                "sha256:78e93cc3571fd928a39c0b26767c986188a4118edc67bc0695bc7a284da22e82",
-                "sha256:7f43286f13d91a34fadf61ae252a51a130223c52bfefb50310d5b2deb062cf0f",
-                "sha256:86e9f8cd4b0cdd57b4ae71a9c186717daa4c5a99f3238a8723f416256e0b064d",
-                "sha256:8f264ba2701b8c9f815b272ad568d555ef98dfe1576802ab3149c3629a9f2221",
-                "sha256:9342dd70a1e151684727c9c91ea003b2fb33523bf19385d4554f7897ca0141d4",
-                "sha256:9361de40701666b034c59ad9e317bae95c973b9ff92513dd0eced11c6adf2e21",
-                "sha256:9669179786254a2e7e57f0ecf224e978471491d660aaca833f845b72a2df3709",
-                "sha256:aac1ba0a253e17889550ddb1b60a2063f7474155465577caa2a3b131224cfd54",
-                "sha256:aef72eae10b5e3116bac6957de1df4d75909fc76d1499a53fb6387434b6bcd8d",
-                "sha256:bd3166bb3b111e76a4f8e2980fa1addf2920a4ca9b2b8ca36a3bc3dedc618270",
-                "sha256:c1b78fb9700fc961f53386ad2fd86d87091e06ede5d118b8a50dea285a071c24",
-                "sha256:c3888a051226e676e383de03bf49eb633cd39fc829516e5334e69b8d81aae751",
-                "sha256:c5f17ad25d2c1286436761b462e22b5020d83316f8e8fcb5deb2b3151f8f1d3a",
-                "sha256:c851b35fc078389bc16b915a0a7c1d5923e12e2c5aeec58c52f4aa8085ac8237",
-                "sha256:cb7df71de0af56000115eafd000b867d1261f786b5eebd88a0ca6360cccfaca7",
-                "sha256:cedb2f9e1f990918ea061f28a0f0077a07702e3819602d3507e2ff98c8d20636",
-                "sha256:e8caf961e1b1a945db76f1b5fa9c91498d15f545ac0ababbe575cfab185d3bd8"
+                "sha256:08b3ba72bd981531fd557f67beee376d6700fba183b167857038997ba30dd297",
+                "sha256:2757fa64e11ec12220968f65d086b7a29b6583d16e9a544c889b22ba98555ef1",
+                "sha256:3102bb2c206700a7d28181dbe04d66b30780cde1d1c02c5f3c165cf3d2489497",
+                "sha256:3498b27d8236057def41de3585f317abae235dd3a11d33e01736ffedb2ef8606",
+                "sha256:378ac77af41350a8c6b8801a66021b52da8a05fd77e578b7380e876c0ce4f528",
+                "sha256:38f16b1317b8dd82df67ed5daa5f5e7c959e46579840d77a67a4ceb9cef0a50b",
+                "sha256:3911c2ef96e5ddc748a3c8b4702c61986628bb719b8378bf1e4a6184bbd48fe4",
+                "sha256:3a3c3f8863255f3c31db3889f8055989527173ef6192a283eb6f4db3c579d830",
+                "sha256:3b14b1da110ea50c8bcbadc3b82c3933974dbeea1832e814aab93ca1163cd4c1",
+                "sha256:535dc1e6e68fad5355f9984d5637c33badbdc987b0c0d303ee95a6c979c9516f",
+                "sha256:6f61319e33222591f885c598e3e24f6a4be3533c1d70c19e0dc59e83a71ce27d",
+                "sha256:723d22d324e7997a651478e9c5a3120a0ecbc9a7e94071f7e1954562a8806cf3",
+                "sha256:76b2775dda7e78680d688daabcb485dc87cf5e3184a0b3e012e1d40e38527cc8",
+                "sha256:782a5c7df9f91979a7a21792e09b34a658058896628217ae6362088b123c8500",
+                "sha256:7e4d159021c2029b958b2363abec4a11db0ce8cd43abb0d9ce44284cb97217e7",
+                "sha256:8dacc4073c359f40fcf73aede8428c35f84639baad7e1b46fce5ab7a8a7be4bb",
+                "sha256:8f33d1156241c43755137288dea619105477961cfa7e47f48dbf96bc2c30720b",
+                "sha256:8ffd4b204d7de77b5dd558cdff986a8274796a1e57813ed005b33fd97e29f059",
+                "sha256:93a280c9eb736a0dcca19296f3c30c720cb41a71b1f9e617f341f0a8e791a69b",
+                "sha256:9a4f66259bdd6964d8cf26142733c81fb562252db74ea367d9beb4f815478e72",
+                "sha256:9a9d4ff06804920388aab69c5ea8a77525cf165356db70131616acd269e19b36",
+                "sha256:a2070c5affdb3a5e751f24208c5c4f3d5f008fa04d28731416e023c93b275277",
+                "sha256:a4857f7e2bc6921dbd487c5c88b84f5633de3e7d416c4dc0bb70256775551a6c",
+                "sha256:a607ae05b6c96057ba86c811d9c43423f35e03874ffb03fbdcd45e0637e8b631",
+                "sha256:a66ca3bdf21c653e47f726ca57f46ba7fc1f260ad99ba783acc3e58e3ebdb9ff",
+                "sha256:ab110c48bc3d97b4d19af41865e14531f300b482da21783fdaacd159251890e8",
+                "sha256:b239711e774c8eb910e9b1ac719f02f5ae4bf35fa0420f438cdc3a7e4e7dd6ec",
+                "sha256:be0416074d7f253865bb67630cf7210cbc14eb05f4099cc0f82430135aaa7a3b",
+                "sha256:c46643970dff9f5c976c6512fd35768c4a3819f01f61169d8cdac3f9290903b7",
+                "sha256:c5ec71fd4a43b6d84ddb88c1df94572479d9a26ef3f150cef3dacefecf888105",
+                "sha256:c6e5174f8ca585755988bc278c8bb5d02d9dc2e971591ef4a1baabdf2d99589b",
+                "sha256:c89b558f8a9a5a6f2cfc923c304d49f0ce629c3bd85cb442ca258ec20366394c",
+                "sha256:cc44e3545d908ecf3e5773266c487ad1877be718d9dc65fc7eb6e7d14960985b",
+                "sha256:cc6f8246e74dd210d7e2b56c76ceaba1cc52b025cd75dbe96eb48791e0250e98",
+                "sha256:cd556c79ad665faeae28020a0ab3bda6cd47d94bec48e36970719b0b86e4dcf4",
+                "sha256:ce6f3a147b4b1a8b09aae48517ae91139b1b010c5f36423fa2b866a8b23df879",
+                "sha256:ceb499d2b3d1d7b7ba23abe8bf26df5f06ba8c71127f188333dddcf356b4b63f",
+                "sha256:cef06fb382557f66d81d804230c11ab292d94b840b3cb7bf4450778377b592f4",
+                "sha256:e448f56cfeae7b1b3b5bcd99bb377cde7c4eb1970a525c770720a352bc4c8044",
+                "sha256:e52d3d95df81c8f6b2a1685aabffadf2d2d9ad97203a40f8d61e51b70f191e4e",
+                "sha256:ee2f1d1c223c3d2c24e3afbb2dd38be3f03b1a8d6a83ee3d9eb8c36a52bee899",
+                "sha256:f2c6888eada180814b8583c3e793f3f343a692fc802546eed45f40a001b1169f",
+                "sha256:f51dbba78d68a44e99d484ca8c8f604f17e957c1ca09c3ebc2c7e3bbd9ba0448",
+                "sha256:f54de00baf200b4539a5a092a759f000b5f45fd226d6d25a76b0dff71177a714",
+                "sha256:fa10fee7e32213f5c7b0d6428ea92e3a3fdd6d725590238a3f92c0de1c78b9d2",
+                "sha256:fabeeb121735d47d8eab8671b6b031ce08514c86b7ad8f7d5490a7b6dcd6267d",
+                "sha256:fac3c432851038b3e6afe086f777732bcf7f6ebbfd90951fa04ee53db6d0bcdd",
+                "sha256:fda29412a66099af6d6de0baa6bd7c52674de177ec2ad2630ca264142d69c6c7",
+                "sha256:ff1330e8bc996570221b450e2d539134baa9465f5cb98aff0e0f73f34172e0ae"
             ],
             "index": "pypi",
-            "version": "==5.3"
+            "version": "==5.3.1"
         },
         "distlib": {
             "hashes": [
@@ -610,11 +625,11 @@
         },
         "keyring": {
             "hashes": [
-                "sha256:12de23258a95f3b13e5b167f7a641a878e91eab8ef16fafc077720a95e6115bb",
-                "sha256:207bd66f2a9881c835dad653da04e196c678bf104f8252141d2d3c4f31051579"
+                "sha256:1746d3ac913d449a090caf11e9e4af00e26c3f7f7e81027872192b2398b98675",
+                "sha256:4be9cbaaaf83e61d6399f733d113ede7d1c73bc75cb6aeb64eee0f6ac39b30ea"
             ],
             "markers": "python_version >= '3.6'",
-            "version": "==21.5.0"
+            "version": "==21.8.0"
         },
         "markupsafe": {
             "hashes": [
@@ -805,10 +820,10 @@
         },
         "pytz": {
             "hashes": [
-                "sha256:3e6b7dd2d1e0a59084bcee14a17af60c5c562cdc16d828e8eba2e683d3a7e268",
-                "sha256:5c55e189b682d420be27c6995ba6edce0c0a77dd67bfbe2ae6607134d5851ffd"
+                "sha256:16962c5fb8db4a8f63a26646d8886e9d769b6c511543557bc84e9569fb9a9cb4",
+                "sha256:180befebb1927b16f6b57101720075a984c019ac16b1b7575673bea42c6c3da5"
             ],
-            "version": "==2020.4"
+            "version": "==2020.5"
         },
         "pyyaml": {
             "hashes": [
@@ -838,11 +853,11 @@
         },
         "recommonmark": {
             "hashes": [
-                "sha256:29cd4faeb6c5268c633634f2d69aef9431e0f4d347f90659fd0aab20e541efeb",
-                "sha256:2ec4207a574289355d5b6ae4ae4abb29043346ca12cdd5f07d374dc5987d2852"
+                "sha256:1b1db69af0231efce3fa21b94ff627ea33dee7079a01dd0a7f8482c3da148b3f",
+                "sha256:bdb4db649f2222dcd8d2d844f0006b958d627f732415d399791ee436a3686d67"
             ],
             "index": "pypi",
-            "version": "==0.6.0"
+            "version": "==0.7.1"
         },
         "regex": {
             "hashes": [
@@ -893,11 +908,11 @@
         },
         "requests": {
             "hashes": [
-                "sha256:7f1a0b932f4a60a1a65caa4263921bb7d9ee911957e0ae4a23a6dd08185ad5f8",
-                "sha256:e786fa28d8c9154e6a4de5d46a1d921b8749f8b74e28bde23768e5e16eece998"
+                "sha256:27973dd4a904a4f13b263a19c866c13b92a39ed1c964655f025f3f8d3d75b804",
+                "sha256:c210084e36a42ae6b9219e00e48287def368a26d03a048ddad7bfee44f75871e"
             ],
             "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
-            "version": "==2.25.0"
+            "version": "==2.25.1"
         },
         "requests-toolbelt": {
             "hashes": [
@@ -944,11 +959,11 @@
         },
         "sphinx": {
             "hashes": [
-                "sha256:1e8d592225447104d1172be415bc2972bd1357e3e12fdc76edf2261105db4300",
-                "sha256:d4e59ad4ea55efbb3c05cde3bfc83bfc14f0c95aa95c3d75346fcce186a47960"
+                "sha256:aeef652b14629431c82d3fe994ce39ead65b3fe87cf41b9a3714168ff8b83376",
+                "sha256:e450cb205ff8924611085183bf1353da26802ae73d9251a8fcdf220a8f8712ef"
             ],
             "index": "pypi",
-            "version": "==3.3.1"
+            "version": "==3.4.1"
         },
         "sphinxcontrib-applehelp": {
             "hashes": [
@@ -1008,55 +1023,55 @@
         },
         "tqdm": {
             "hashes": [
-                "sha256:38b658a3e4ecf9b4f6f8ff75ca16221ae3378b2e175d846b6b33ea3a20852cf5",
-                "sha256:d4f413aecb61c9779888c64ddf0c62910ad56dcbe857d8922bb505d4dbff0df1"
+                "sha256:0cd81710de29754bf17b6fee07bdb86f956b4fa20d3078f02040f83e64309416",
+                "sha256:f4f80b96e2ceafea69add7bf971b8403b9cba8fb4451c1220f91c79be4ebd208"
             ],
             "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==4.54.1"
+            "version": "==4.55.0"
         },
         "twine": {
             "hashes": [
-                "sha256:34352fd52ec3b9d29837e6072d5a2a7c6fe4290e97bba46bb8d478b5c598f7ab",
-                "sha256:ba9ff477b8d6de0c89dd450e70b2185da190514e91c42cc62f96850025c10472"
+                "sha256:2f6942ec2a17417e19d2dd372fc4faa424c87ee9ce49b4e20c427eb00a0f3f41",
+                "sha256:fcffa8fc37e8083a5be0728371f299598870ee1eccc94e9a25cef7b1dcfa8297"
             ],
             "index": "pypi",
-            "version": "==3.2.0"
+            "version": "==3.3.0"
         },
         "typed-ast": {
             "hashes": [
-                "sha256:0666aa36131496aed8f7be0410ff974562ab7eeac11ef351def9ea6fa28f6355",
-                "sha256:0c2c07682d61a629b68433afb159376e24e5b2fd4641d35424e462169c0a7919",
-                "sha256:0d8110d78a5736e16e26213114a38ca35cb15b6515d535413b090bd50951556d",
-                "sha256:249862707802d40f7f29f6e1aad8d84b5aa9e44552d2cc17384b209f091276aa",
-                "sha256:24995c843eb0ad11a4527b026b4dde3da70e1f2d8806c99b7b4a7cf491612652",
-                "sha256:269151951236b0f9a6f04015a9004084a5ab0d5f19b57de779f908621e7d8b75",
-                "sha256:3742b32cf1c6ef124d57f95be609c473d7ec4c14d0090e5a5e05a15269fb4d0c",
-                "sha256:4083861b0aa07990b619bd7ddc365eb7fa4b817e99cf5f8d9cf21a42780f6e01",
-                "sha256:498b0f36cc7054c1fead3d7fc59d2150f4d5c6c56ba7fb150c013fbc683a8d2d",
-                "sha256:4e3e5da80ccbebfff202a67bf900d081906c358ccc3d5e3c8aea42fdfdfd51c1",
-                "sha256:6daac9731f172c2a22ade6ed0c00197ee7cc1221aa84cfdf9c31defeb059a907",
-                "sha256:715ff2f2df46121071622063fc7543d9b1fd19ebfc4f5c8895af64a77a8c852c",
-                "sha256:73d785a950fc82dd2a25897d525d003f6378d1cb23ab305578394694202a58c3",
-                "sha256:7e4c9d7658aaa1fc80018593abdf8598bf91325af6af5cce4ce7c73bc45ea53d",
-                "sha256:8c8aaad94455178e3187ab22c8b01a3837f8ee50e09cf31f1ba129eb293ec30b",
-                "sha256:8ce678dbaf790dbdb3eba24056d5364fb45944f33553dd5869b7580cdbb83614",
-                "sha256:92c325624e304ebf0e025d1224b77dd4e6393f18aab8d829b5b7e04afe9b7a2c",
-                "sha256:aaee9905aee35ba5905cfb3c62f3e83b3bec7b39413f0a7f19be4e547ea01ebb",
-                "sha256:b52ccf7cfe4ce2a1064b18594381bccf4179c2ecf7f513134ec2f993dd4ab395",
-                "sha256:bcd3b13b56ea479b3650b82cabd6b5343a625b0ced5429e4ccad28a8973f301b",
-                "sha256:c9e348e02e4d2b4a8b2eedb48210430658df6951fa484e59de33ff773fbd4b41",
-                "sha256:d205b1b46085271b4e15f670058ce182bd1199e56b317bf2ec004b6a44f911f6",
-                "sha256:d43943ef777f9a1c42bf4e552ba23ac77a6351de620aa9acf64ad54933ad4d34",
-                "sha256:d5d33e9e7af3b34a40dc05f498939f0ebf187f07c385fd58d591c533ad8562fe",
-                "sha256:d648b8e3bf2fe648745c8ffcee3db3ff903d0817a01a12dd6a6ea7a8f4889072",
-                "sha256:f208eb7aff048f6bea9586e61af041ddf7f9ade7caed625742af423f6bae3298",
-                "sha256:fac11badff8313e23717f3dada86a15389d0708275bddf766cca67a84ead3e91",
-                "sha256:fc0fea399acb12edbf8a628ba8d2312f583bdbdb3335635db062fa98cf71fca4",
-                "sha256:fcf135e17cc74dbfbc05894ebca928ffeb23d9790b3167a674921db19082401f",
-                "sha256:fe460b922ec15dd205595c9b5b99e2f056fd98ae8f9f56b888e7a17dc2b757e7"
+                "sha256:07d49388d5bf7e863f7fa2f124b1b1d89d8aa0e2f7812faff0a5658c01c59aa1",
+                "sha256:14bf1522cdee369e8f5581238edac09150c765ec1cb33615855889cf33dcb92d",
+                "sha256:240296b27397e4e37874abb1df2a608a92df85cf3e2a04d0d4d61055c8305ba6",
+                "sha256:36d829b31ab67d6fcb30e185ec996e1f72b892255a745d3a82138c97d21ed1cd",
+                "sha256:37f48d46d733d57cc70fd5f30572d11ab8ed92da6e6b28e024e4a3edfb456e37",
+                "sha256:4c790331247081ea7c632a76d5b2a265e6d325ecd3179d06e9cf8d46d90dd151",
+                "sha256:5dcfc2e264bd8a1db8b11a892bd1647154ce03eeba94b461effe68790d8b8e07",
+                "sha256:7147e2a76c75f0f64c4319886e7639e490fee87c9d25cb1d4faef1d8cf83a440",
+                "sha256:7703620125e4fb79b64aa52427ec192822e9f45d37d4b6625ab37ef403e1df70",
+                "sha256:8368f83e93c7156ccd40e49a783a6a6850ca25b556c0fa0240ed0f659d2fe496",
+                "sha256:84aa6223d71012c68d577c83f4e7db50d11d6b1399a9c779046d75e24bed74ea",
+                "sha256:85f95aa97a35bdb2f2f7d10ec5bbdac0aeb9dafdaf88e17492da0504de2e6400",
+                "sha256:8db0e856712f79c45956da0c9a40ca4246abc3485ae0d7ecc86a20f5e4c09abc",
+                "sha256:9044ef2df88d7f33692ae3f18d3be63dec69c4fb1b5a4a9ac950f9b4ba571606",
+                "sha256:963c80b583b0661918718b095e02303d8078950b26cc00b5e5ea9ababe0de1fc",
+                "sha256:987f15737aba2ab5f3928c617ccf1ce412e2e321c77ab16ca5a293e7bbffd581",
+                "sha256:9ec45db0c766f196ae629e509f059ff05fc3148f9ffd28f3cfe75d4afb485412",
+                "sha256:9fc0b3cb5d1720e7141d103cf4819aea239f7d136acf9ee4a69b047b7986175a",
+                "sha256:a2c927c49f2029291fbabd673d51a2180038f8cd5a5b2f290f78c4516be48be2",
+                "sha256:a38878a223bdd37c9709d07cd357bb79f4c760b29210e14ad0fb395294583787",
+                "sha256:b4fcdcfa302538f70929eb7b392f536a237cbe2ed9cba88e3bf5027b39f5f77f",
+                "sha256:c0c74e5579af4b977c8b932f40a5464764b2f86681327410aa028a22d2f54937",
+                "sha256:c1c876fd795b36126f773db9cbb393f19808edd2637e00fd6caba0e25f2c7b64",
+                "sha256:c9aadc4924d4b5799112837b226160428524a9a45f830e0d0f184b19e4090487",
+                "sha256:cc7b98bf58167b7f2db91a4327da24fb93368838eb84a44c472283778fc2446b",
+                "sha256:cf54cfa843f297991b7388c281cb3855d911137223c6b6d2dd82a47ae5125a41",
+                "sha256:d003156bb6a59cda9050e983441b7fa2487f7800d76bdc065566b7d728b4581a",
+                "sha256:d175297e9533d8d37437abc14e8a83cbc68af93cc9c1c59c2c292ec59a0697a3",
+                "sha256:d746a437cdbca200622385305aedd9aef68e8a645e385cc483bdc5e488f07166",
+                "sha256:e683e409e5c45d5c9082dc1daf13f6374300806240719f95dc783d1fc942af10"
             ],
             "index": "pypi",
-            "version": "==1.4.1"
+            "version": "==1.4.2"
         },
         "typing-extensions": {
             "hashes": [
diff --git a/setup.py b/setup.py
index 14bc1ef586a..c97dd35fe28 100644
--- a/setup.py
+++ b/setup.py
@@ -71,7 +71,7 @@ def get_long_description() -> str:
         "click>=7.1.2",
         "appdirs",
         "toml>=0.10.1",
-        "typed-ast>=1.4.0",
+        "typed-ast>=1.4.2",
         "regex>=2020.1.8",
         "pathspec>=0.6, <1",
         "dataclasses>=0.6; python_version < '3.7'",

From af6f78f2ae408afebb375043930bbdd4c26599f5 Mon Sep 17 00:00:00 2001
From: Jon Dufresne <jon.dufresne@gmail.com>
Date: Thu, 31 Dec 2020 09:09:07 -0800
Subject: [PATCH 0059/1034] Add pyi file support to .pre-commit-hooks.yaml
 (#1875)

Since pre-commit 2.9.0 (2020-11-21), the types_or key can be used to
match multiple disparate file types. For more upstream details, see:
https://github.com/pre-commit/pre-commit/issues/607

Add the minimum_pre_commit_version to require pre-commit 2.9.0+.

Fixes #402
---
 .pre-commit-config.yaml | 3 ++-
 .pre-commit-hooks.yaml  | 3 ++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 4e12e46f8d8..c2580d2d601 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -8,8 +8,9 @@ repos:
         name: black
         language: system
         entry: black
+        minimum_pre_commit_version: 2.9.0
         require_serial: true
-        types: [python]
+        types_or: [python, pyi]
 
   - repo: https://gitlab.com/pycqa/flake8
     rev: 3.8.1
diff --git a/.pre-commit-hooks.yaml b/.pre-commit-hooks.yaml
index c59213e2632..c575842e2bf 100644
--- a/.pre-commit-hooks.yaml
+++ b/.pre-commit-hooks.yaml
@@ -4,5 +4,6 @@
   entry: black
   language: python
   language_version: python3
+  minimum_pre_commit_version: 2.9.0
   require_serial: true
-  types: [python]
+  types_or: [python, pyi]

From 33d861371533d64a54af419798f1ddfa692f388c Mon Sep 17 00:00:00 2001
From: Jon Dufresne <jon.dufresne@gmail.com>
Date: Thu, 31 Dec 2020 11:10:18 -0800
Subject: [PATCH 0060/1034] Bump minimum_pre_commit_version per recommendation
 (#1895)

Recommended by @asottile, the pre-commit author and maintainer, to avoid
some breakages in version 2.9.0.
---
 .pre-commit-config.yaml | 2 +-
 .pre-commit-hooks.yaml  | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index c2580d2d601..dc95e902053 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -8,7 +8,7 @@ repos:
         name: black
         language: system
         entry: black
-        minimum_pre_commit_version: 2.9.0
+        minimum_pre_commit_version: 2.9.2
         require_serial: true
         types_or: [python, pyi]
 
diff --git a/.pre-commit-hooks.yaml b/.pre-commit-hooks.yaml
index c575842e2bf..de2eb674e0d 100644
--- a/.pre-commit-hooks.yaml
+++ b/.pre-commit-hooks.yaml
@@ -4,6 +4,6 @@
   entry: black
   language: python
   language_version: python3
-  minimum_pre_commit_version: 2.9.0
+  minimum_pre_commit_version: 2.9.2
   require_serial: true
   types_or: [python, pyi]

From f07832eac44eb38f8b048aae3e1de3512a06057c Mon Sep 17 00:00:00 2001
From: "Paul \"TBBle\" Hampson" <Paul.Hampson@Pobox.com>
Date: Sat, 2 Jan 2021 05:54:35 +1100
Subject: [PATCH 0061/1034] Use Prettier pre-commit mirror (#1896)

This fixes Prettier install failures similar to those seen in
https://github.com/prettier/prettier/issues/9459, and is the solution
recommended there.

Signed-off-by: Paul "TBBle" Hampson <Paul.Hampson@Pobox.com>
---
 .pre-commit-config.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index dc95e902053..9955a24baf8 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -24,8 +24,8 @@ repos:
       - id: mypy
         exclude: ^docs/conf.py
 
-  - repo: https://github.com/prettier/prettier
-    rev: 1.19.1
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: v1.19.1
     hooks:
       - id: prettier
         args: [--prose-wrap=always, --print-width=88]

From 966baaacbc24a4affa88ea5bb0b5a44b0f52fe2f Mon Sep 17 00:00:00 2001
From: Taneli Hukkinen <hukkinj1@users.noreply.github.com>
Date: Sun, 3 Jan 2021 17:14:59 +0100
Subject: [PATCH 0062/1034] Only require typing-extensions if Python < 3.8
 (#1873)

---
 Pipfile                     |  2 +-
 Pipfile.lock                | 95 +++++++++++++++++++++++++++++++++++--
 setup.py                    |  2 +-
 src/black/__init__.py       |  6 ++-
 src/blib2to3/pgen2/token.py |  7 ++-
 5 files changed, 105 insertions(+), 7 deletions(-)

diff --git a/Pipfile b/Pipfile
index 9a4d5bd7c1b..32fb867415f 100644
--- a/Pipfile
+++ b/Pipfile
@@ -29,6 +29,6 @@ pathspec = ">=0.6"
 regex = ">=2020.1.8"
 toml = ">=0.10.1"
 typed-ast = "==1.4.2"
-typing_extensions = ">=3.7.4"
+typing_extensions = {"python_version <" = "3.8","version >=" = "3.7.4"}
 black = {editable = true,extras = ["d"],path = "."}
 dataclasses = {"python_version <" = "3.7","version >" = "0.6"}
diff --git a/Pipfile.lock b/Pipfile.lock
index dd78a3c3178..91fd3a49556 100644
--- a/Pipfile.lock
+++ b/Pipfile.lock
@@ -1,7 +1,7 @@
 {
     "_meta": {
         "hash": {
-            "sha256": "3c4e23d0b6e49bac5ff2347dcb07bb4dd084d39b78c93a32359842dda401e7bf"
+            "sha256": "1b075e0e344dad54944ed4474351c3f311accb67cbea2e0c381da3700b71f415"
         },
         "pipfile-spec": 6,
         "requires": {},
@@ -300,7 +300,9 @@
                 "sha256:dafc7639cde7f1b6e1acc0f457842a83e722ccca8eef5270af2d74792619a89f"
             ],
             "index": "pypi",
-            "version": "==3.7.4.3"
+            "python_version <": "3.8",
+            "version": "==3.7.4.3",
+            "version >=": "3.7.4"
         },
         "yarl": {
             "hashes": [
@@ -459,6 +461,47 @@
             ],
             "version": "==2020.12.5"
         },
+        "cffi": {
+            "hashes": [
+                "sha256:00a1ba5e2e95684448de9b89888ccd02c98d512064b4cb987d48f4b40aa0421e",
+                "sha256:00e28066507bfc3fe865a31f325c8391a1ac2916219340f87dfad602c3e48e5d",
+                "sha256:045d792900a75e8b1e1b0ab6787dd733a8190ffcf80e8c8ceb2fb10a29ff238a",
+                "sha256:0638c3ae1a0edfb77c6765d487fee624d2b1ee1bdfeffc1f0b58c64d149e7eec",
+                "sha256:105abaf8a6075dc96c1fe5ae7aae073f4696f2905fde6aeada4c9d2926752362",
+                "sha256:155136b51fd733fa94e1c2ea5211dcd4c8879869008fc811648f16541bf99668",
+                "sha256:1a465cbe98a7fd391d47dce4b8f7e5b921e6cd805ef421d04f5f66ba8f06086c",
+                "sha256:1d2c4994f515e5b485fd6d3a73d05526aa0fcf248eb135996b088d25dfa1865b",
+                "sha256:2c24d61263f511551f740d1a065eb0212db1dbbbbd241db758f5244281590c06",
+                "sha256:51a8b381b16ddd370178a65360ebe15fbc1c71cf6f584613a7ea08bfad946698",
+                "sha256:594234691ac0e9b770aee9fcdb8fa02c22e43e5c619456efd0d6c2bf276f3eb2",
+                "sha256:5cf4be6c304ad0b6602f5c4e90e2f59b47653ac1ed9c662ed379fe48a8f26b0c",
+                "sha256:64081b3f8f6f3c3de6191ec89d7dc6c86a8a43911f7ecb422c60e90c70be41c7",
+                "sha256:6bc25fc545a6b3d57b5f8618e59fc13d3a3a68431e8ca5fd4c13241cd70d0009",
+                "sha256:798caa2a2384b1cbe8a2a139d80734c9db54f9cc155c99d7cc92441a23871c03",
+                "sha256:7c6b1dece89874d9541fc974917b631406233ea0440d0bdfbb8e03bf39a49b3b",
+                "sha256:840793c68105fe031f34d6a086eaea153a0cd5c491cde82a74b420edd0a2b909",
+                "sha256:8d6603078baf4e11edc4168a514c5ce5b3ba6e3e9c374298cb88437957960a53",
+                "sha256:9cc46bc107224ff5b6d04369e7c595acb700c3613ad7bcf2e2012f62ece80c35",
+                "sha256:9f7a31251289b2ab6d4012f6e83e58bc3b96bd151f5b5262467f4bb6b34a7c26",
+                "sha256:9ffb888f19d54a4d4dfd4b3f29bc2c16aa4972f1c2ab9c4ab09b8ab8685b9c2b",
+                "sha256:a5ed8c05548b54b998b9498753fb9cadbfd92ee88e884641377d8a8b291bcc01",
+                "sha256:a7711edca4dcef1a75257b50a2fbfe92a65187c47dab5a0f1b9b332c5919a3fb",
+                "sha256:af5c59122a011049aad5dd87424b8e65a80e4a6477419c0c1015f73fb5ea0293",
+                "sha256:b18e0a9ef57d2b41f5c68beefa32317d286c3d6ac0484efd10d6e07491bb95dd",
+                "sha256:b4e248d1087abf9f4c10f3c398896c87ce82a9856494a7155823eb45a892395d",
+                "sha256:ba4e9e0ae13fc41c6b23299545e5ef73055213e466bd107953e4a013a5ddd7e3",
+                "sha256:c6332685306b6417a91b1ff9fae889b3ba65c2292d64bd9245c093b1b284809d",
+                "sha256:d5ff0621c88ce83a28a10d2ce719b2ee85635e85c515f12bac99a95306da4b2e",
+                "sha256:d9efd8b7a3ef378dd61a1e77367f1924375befc2eba06168b6ebfa903a5e59ca",
+                "sha256:df5169c4396adc04f9b0a05f13c074df878b6052430e03f50e68adf3a57aa28d",
+                "sha256:ebb253464a5d0482b191274f1c8bf00e33f7e0b9c66405fbffc61ed2c839c775",
+                "sha256:ec80dc47f54e6e9a78181ce05feb71a0353854cc26999db963695f950b5fb375",
+                "sha256:f032b34669220030f905152045dfa27741ce1a6db3324a5bc0b96b6c7420c87b",
+                "sha256:f60567825f791c6f8a592f3c6e3bd93dd2934e3f9dac189308426bd76b00ef3b",
+                "sha256:f803eaa94c2fcda012c047e62bc7a51b0bdabda1cad7a92a522694ea2d76e49f"
+            ],
+            "version": "==1.14.4"
+        },
         "cfgv": {
             "hashes": [
                 "sha256:32e43d604bbe7896fe7c248a9c2276447dbef840feb28fe20494f62af110211d",
@@ -552,6 +595,26 @@
             "index": "pypi",
             "version": "==5.3.1"
         },
+        "cryptography": {
+            "hashes": [
+                "sha256:0003a52a123602e1acee177dc90dd201f9bb1e73f24a070db7d36c588e8f5c7d",
+                "sha256:0e85aaae861d0485eb5a79d33226dd6248d2a9f133b81532c8f5aae37de10ff7",
+                "sha256:594a1db4511bc4d960571536abe21b4e5c3003e8750ab8365fafce71c5d86901",
+                "sha256:69e836c9e5ff4373ce6d3ab311c1a2eed274793083858d3cd4c7d12ce20d5f9c",
+                "sha256:788a3c9942df5e4371c199d10383f44a105d67d401fb4304178020142f020244",
+                "sha256:7e177e4bea2de937a584b13645cab32f25e3d96fc0bc4a4cf99c27dc77682be6",
+                "sha256:83d9d2dfec70364a74f4e7c70ad04d3ca2e6a08b703606993407bf46b97868c5",
+                "sha256:84ef7a0c10c24a7773163f917f1cb6b4444597efd505a8aed0a22e8c4780f27e",
+                "sha256:9e21301f7a1e7c03dbea73e8602905a4ebba641547a462b26dd03451e5769e7c",
+                "sha256:9f6b0492d111b43de5f70052e24c1f0951cb9e6022188ebcb1cc3a3d301469b0",
+                "sha256:a69bd3c68b98298f490e84519b954335154917eaab52cf582fa2c5c7efc6e812",
+                "sha256:b4890d5fb9b7a23e3bf8abf5a8a7da8e228f1e97dc96b30b95685df840b6914a",
+                "sha256:c366df0401d1ec4e548bebe8f91d55ebcc0ec3137900d214dd7aac8427ef3030",
+                "sha256:dc42f645f8f3a489c3dd416730a514e7a91a59510ddaadc09d04224c098d3302"
+            ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4, 3.5'",
+            "version": "==3.3.1"
+        },
         "distlib": {
             "hashes": [
                 "sha256:8c09de2c67b3e7deef7184574fc060ab8a793e7adbb183d942c389c8b13c52fb",
@@ -615,6 +678,14 @@
             "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==1.2.0"
         },
+        "jeepney": {
+            "hashes": [
+                "sha256:7d59b6622675ca9e993a6bd38de845051d315f8b0c72cca3aef733a20b648657",
+                "sha256:aec56c0eb1691a841795111e184e13cad504f7703b9a64f63020816afa79a8ae"
+            ],
+            "markers": "sys_platform == 'linux'",
+            "version": "==0.6.0"
+        },
         "jinja2": {
             "hashes": [
                 "sha256:89aab215427ef59c34ad58735269eb58b1a5808103067f7bb9d5836c651b3bb0",
@@ -794,6 +865,14 @@
             "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==2.6.0"
         },
+        "pycparser": {
+            "hashes": [
+                "sha256:2d475327684562c3a96cc71adf7dc8c4f0565175cf86b6d7a404ff4c771f15f0",
+                "sha256:7582ad22678f0fcd81102833f60ef8d0e57288b6b5fb00323d101be910e35705"
+            ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
+            "version": "==2.20"
+        },
         "pyflakes": {
             "hashes": [
                 "sha256:0d94e0e05a19e57a99444b6ddcf9a6eb2e5c68d3ca1e98e90707af8152c90a92",
@@ -928,6 +1007,14 @@
             ],
             "version": "==1.4.0"
         },
+        "secretstorage": {
+            "hashes": [
+                "sha256:30cfdef28829dad64d6ea1ed08f8eff6aa115a77068926bcc9f5225d5a3246aa",
+                "sha256:5c36f6537a523ec5f969ef9fad61c98eb9e017bc601d811e53aa25bece64892f"
+            ],
+            "markers": "sys_platform == 'linux'",
+            "version": "==3.3.0"
+        },
         "setuptools-scm": {
             "hashes": [
                 "sha256:1fc4e25df445351d172bb4788f4d07f9e9ce0e8b7dee6b19584e46110172ca13",
@@ -1080,7 +1167,9 @@
                 "sha256:dafc7639cde7f1b6e1acc0f457842a83e722ccca8eef5270af2d74792619a89f"
             ],
             "index": "pypi",
-            "version": "==3.7.4.3"
+            "python_version <": "3.8",
+            "version": "==3.7.4.3",
+            "version >=": "3.7.4"
         },
         "urllib3": {
             "hashes": [
diff --git a/setup.py b/setup.py
index c97dd35fe28..48160568265 100644
--- a/setup.py
+++ b/setup.py
@@ -75,7 +75,7 @@ def get_long_description() -> str:
         "regex>=2020.1.8",
         "pathspec>=0.6, <1",
         "dataclasses>=0.6; python_version < '3.7'",
-        "typing_extensions>=3.7.4",
+        "typing_extensions>=3.7.4; python_version < '3.8'",
         "mypy_extensions>=0.4.3",
     ],
     extras_require={
diff --git a/src/black/__init__.py b/src/black/__init__.py
index c7c5d724a9f..9b9903c6645 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -42,7 +42,6 @@
     cast,
     TYPE_CHECKING,
 )
-from typing_extensions import Final
 from mypy_extensions import mypyc_attr
 
 from appdirs import user_cache_dir
@@ -61,6 +60,11 @@
 
 from _black_version import version as __version__
 
+if sys.version_info < (3, 8):
+    from typing_extensions import Final
+else:
+    from typing import Final
+
 if TYPE_CHECKING:
     import colorama  # noqa: F401
 
diff --git a/src/blib2to3/pgen2/token.py b/src/blib2to3/pgen2/token.py
index 5870d47a61a..1e0dec9c714 100644
--- a/src/blib2to3/pgen2/token.py
+++ b/src/blib2to3/pgen2/token.py
@@ -1,7 +1,12 @@
 """Token constants (from "token.h")."""
 
+import sys
 from typing import Dict
-from typing_extensions import Final
+
+if sys.version_info < (3, 8):
+    from typing_extensions import Final
+else:
+    from typing import Final
 
 #  Taken from Python (r53757) and modified to include some tokens
 #   originally monkeypatched in by pgen2.tokenize

From ba3648d98471a6d0ad951d7f75ac512108173bc7 Mon Sep 17 00:00:00 2001
From: Rick Staa <rick.staa@outlook.com>
Date: Fri, 8 Jan 2021 20:47:03 +0100
Subject: [PATCH 0063/1034] Release gh action (#1909)

* Gets gh-action ready for marketplace release

* Updates documentation and removes redundant gh-action input argument

* Fixes gh-action bug

This commit fixes a bug which caused not all input arguments were forwarder to the black formatter.

* Update README.md

Co-authored-by: Cooper Lees <me@cooperlees.com>

Co-authored-by: Cooper Lees <me@cooperlees.com>
---
 README.md            |  8 ++++++++
 action.yml           |  5 +++++
 action/entrypoint.sh | 17 ++++++++++++-----
 3 files changed, 25 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index a557a6fc6c8..269bf5aaa43 100644
--- a/README.md
+++ b/README.md
@@ -411,8 +411,16 @@ jobs:
       - uses: actions/checkout@v2
       - uses: actions/setup-python@v2
       - uses: psf/black@stable
+        with:
+          black_args: ". --check"
 ```
 
+### Inputs
+
+#### `black_args`
+
+**optional**: Black input arguments. Defaults to `. --check --diff`.
+
 ## Ignoring unmodified files
 
 _Black_ remembers files it has already formatted, unless the `--diff` flag is used or
diff --git a/action.yml b/action.yml
index 60bf369a3d8..59b16a9fb6c 100644
--- a/action.yml
+++ b/action.yml
@@ -1,6 +1,11 @@
 name: "Black"
 description: "The uncompromising Python code formatter."
 author: "Łukasz Langa and contributors to Black"
+inputs:
+  black_args:
+    description: "Black input arguments."
+    required: false
+    default: ""
 branding:
   color: "black"
   icon: "check-circle"
diff --git a/action/entrypoint.sh b/action/entrypoint.sh
index dc86fa1996e..92501f79db8 100755
--- a/action/entrypoint.sh
+++ b/action/entrypoint.sh
@@ -1,10 +1,17 @@
 #!/bin/sh
 set -e
 
-if [ $# -eq 0 ]; then
-    # Default (if no args provided).
-    sh -c "black . --check --diff"
+# If no arguments are given use current working directory
+black_args=(".")
+if [ "$#" -eq 0 ] && [ "${INPUT_BLACK_ARGS}" != "" ]; then
+  black_args+=(${INPUT_BLACK_ARGS})
+elif [ "$#" -ne 0 ] && [ "${INPUT_BLACK_ARGS}" != "" ]; then
+  black_args+=($* ${INPUT_BLACK_ARGS})
+elif [ "$#" -ne 0 ] && [ "${INPUT_BLACK_ARGS}" == "" ]; then
+  black_args+=($*)
 else
-    # Custom args.
-    sh -c "black $*"
+  # Default (if no args provided).
+  black_args+=("--check" "--diff")
 fi
+
+sh -c "black . ${black_args[*]}"

From a81702ce027ef6792955d5db02aad60a34c7ec44 Mon Sep 17 00:00:00 2001
From: Troy Murray <troysmurray@gmail.com>
Date: Sat, 9 Jan 2021 07:26:42 +1100
Subject: [PATCH 0064/1034] Changed max workers on windows to 60 (#1912)

---
 src/black/__init__.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index 9b9903c6645..91f70d96165 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -741,7 +741,7 @@ def reformat_many(
     worker_count = os.cpu_count()
     if sys.platform == "win32":
         # Work around https://bugs.python.org/issue26903
-        worker_count = min(worker_count, 61)
+        worker_count = min(worker_count, 60)
     try:
         executor = ProcessPoolExecutor(max_workers=worker_count)
     except (ImportError, OSError):

From ce269d2da52596f549e54c94726b77fa1adad177 Mon Sep 17 00:00:00 2001
From: Shota Ray Imaki <shota.imaki@icloud.com>
Date: Tue, 12 Jan 2021 01:21:14 +0900
Subject: [PATCH 0065/1034] fix #1917 (#1918)

---
 docs/compatible_configs/isort/pyproject.toml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/compatible_configs/isort/pyproject.toml b/docs/compatible_configs/isort/pyproject.toml
index cea9915bebf..2dc02c8c50c 100644
--- a/docs/compatible_configs/isort/pyproject.toml
+++ b/docs/compatible_configs/isort/pyproject.toml
@@ -1,2 +1,2 @@
 [tool.isort]
-profile = black
+profile = 'black'

From 3d0689470752daedf7ef2bc9e602478ea31c0430 Mon Sep 17 00:00:00 2001
From: Thomas Hagebols <ThomasHagebols@users.noreply.github.com>
Date: Mon, 11 Jan 2021 17:23:11 +0100
Subject: [PATCH 0066/1034] Set gh action entrypoint interpreter to bash
 (#1919)

---
 action/entrypoint.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/action/entrypoint.sh b/action/entrypoint.sh
index 92501f79db8..50f9472cc5f 100755
--- a/action/entrypoint.sh
+++ b/action/entrypoint.sh
@@ -1,4 +1,4 @@
-#!/bin/sh
+#!/bin/bash
 set -e
 
 # If no arguments are given use current working directory

From 4310f39bd94c7fa29fc31079247d2aab4bd50f1a Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Wed, 13 Jan 2021 15:17:30 -0800
Subject: [PATCH 0067/1034] Update Contributing Docs (#1915)

* Update Contributing Docs
- Update docs with all new tox hotness
- Test running docs build:
  - `sphinx-build -a -b html -W docs/ docs/_build/`

Fixes #1907

* Fix docs/contributing_to_black.md lint

* Remove autogenerated copy pasta

* Fix review typos + regen automated docs via Running Sphinx v1.8.5
---
 CONTRIBUTING.md                     | 32 ++++++++++++++++++++++++++---
 docs/change_log.md                  | 11 ++++++++--
 docs/contributing_to_black.md       | 32 ++++++++++++++++++++++++++---
 docs/github_actions.md              | 12 ++++++++---
 docs/installation_and_usage.md      |  7 ++++++-
 docs/version_control_integration.md |  5 -----
 test_requirements.txt               |  4 +++-
 7 files changed, 85 insertions(+), 18 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index a4250f78718..571d870452b 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -34,14 +34,40 @@ If you haven't used `pipenv` before but are comfortable with virtualenvs, just r
 `pip install pipenv` in the virtualenv you're already using and invoke the command above
 from the cloned _Black_ repo. It will do the correct thing.
 
-Before submitting pull requests, run lints and tests with:
+Non pipenv install works too:
 
 ```console
+$ pip install -r test_requirements
+$ pip install -e .[d]
+```
+
+Before submitting pull requests, run lints and tests with the following commands from
+the root of the black repo:
+
+```console
+# Linting
 $ pre-commit run -a
-$ python -m unittest
+
+# Unit tests
+$ tox -e py
+
+# Optional Fuzz testing
+$ tox -e fuzz
+
+# Optional CI run to test your changes on many popular python projects
 $ black-primer [-k -w /tmp/black_test_repos]
 ```
 
+### Docs Testing
+
+If you make changes to docs, you can test they still build locally too.
+
+```console
+$ pip install -r docs/requirements.txt
+$ pip install [-e] .[d]
+$ sphinx-build -a -b html -W docs/ docs/_build/
+```
+
 ## black-primer
 
 `black-primer` is used by CI to pull down well-known _Black_ formatted projects and see
@@ -52,7 +78,7 @@ your PR. You may need to change
 configuration for it to pass.
 
 For more `black-primer` information visit the
-[documentation](https://github.com/psf/black/blob/master/docs/black_primer.md#black-primer).
+[documentation](https://github.com/psf/black/blob/master/docs/black_primer.md).
 
 ## Hygiene
 
diff --git a/docs/change_log.md b/docs/change_log.md
index e6afefbf686..066be76c06c 100644
--- a/docs/change_log.md
+++ b/docs/change_log.md
@@ -23,8 +23,15 @@
 
 - Added support for PEP 614 relaxed decorator syntax on python 3.9 (#1711)
 
-- Added `--stdin-filename` argument to allow stdin to respect `--force-exclude` rules.
-  Works very alike to flake8's `--stdin-display-name` (#1780)
+- Added parsing support for unparenthesized tuples and yield expressions in annotated
+  assignments (#1835)
+
+- use lowercase hex strings (#1692)
+
+#### _Packaging_
+
+- Self-contained native _Black_ binaries are now provided for releases via GitHub
+  Releases (#1743)
 
 ### 20.8b1
 
diff --git a/docs/contributing_to_black.md b/docs/contributing_to_black.md
index f0be872a578..562b43a76ac 100644
--- a/docs/contributing_to_black.md
+++ b/docs/contributing_to_black.md
@@ -36,14 +36,40 @@ If you haven't used `pipenv` before but are comfortable with virtualenvs, just r
 `pip install pipenv` in the virtualenv you're already using and invoke the command above
 from the cloned _Black_ repo. It will do the correct thing.
 
-Before submitting pull requests, run lints and tests with:
+Non pipenv install works too:
 
 ```console
+$ pip install -r test_requirements
+$ pip install -e .[d]
+```
+
+Before submitting pull requests, run lints and tests with the following commands from
+the root of the black repo:
+
+```console
+# Linting
 $ pre-commit run -a
-$ python -m unittest
+
+# Unit tests
+$ tox -e py
+
+# Optional Fuzz testing
+$ tox -e fuzz
+
+# Optional CI run to test your changes on many popular python projects
 $ black-primer [-k -w /tmp/black_test_repos]
 ```
 
+### Docs Testing
+
+If you make changes to docs, you can test they still build locally too.
+
+```console
+$ pip install -r docs/requirements.txt
+$ pip install [-e] .[d]
+$ sphinx-build -a -b html -W docs/ docs/_build/
+```
+
 ## black-primer
 
 `black-primer` is used by CI to pull down well-known _Black_ formatted projects and see
@@ -54,7 +80,7 @@ your PR. You may need to change
 configuration for it to pass.
 
 For more `black-primer` information visit the
-[documentation](https://github.com/psf/black/blob/master/docs/black_primer.md#).
+[documentation](https://github.com/psf/black/blob/master/docs/black_primer.md).
 
 ## Hygiene
 
diff --git a/docs/github_actions.md b/docs/github_actions.md
index ac80c2fab6f..bd4680998d9 100644
--- a/docs/github_actions.md
+++ b/docs/github_actions.md
@@ -15,7 +15,13 @@ jobs:
     steps:
       - uses: actions/checkout@v2
       - uses: actions/setup-python@v2
-      - uses: psf/black@stable # the default is equivalent to `black . --diff --check`.
-        with: # (optional - override the default parameters).
-          args: ". --diff --check"
+      - uses: psf/black@stable
+        with:
+          black_args: ". --check"
 ```
+
+## Inputs
+
+### `black_args`
+
+**optional**: Black input arguments. Defaults to `. --check --diff`.
diff --git a/docs/installation_and_usage.md b/docs/installation_and_usage.md
index c91a1c400ef..d0dd0c99dc5 100644
--- a/docs/installation_and_usage.md
+++ b/docs/installation_and_usage.md
@@ -90,6 +90,11 @@ Options:
                                   matching this regex will be excluded even
                                   when they are passed explicitly as arguments.
 
+  --stdin-filename TEXT           The name of the file when passing it through
+                                  stdin. Useful to make sure Black will respect
+                                  --force-exclude option on some editors that
+                                  rely on using stdin.
+
   -q, --quiet                     Don't emit non-error messages to stderr.
                                   Errors are still emitted; silence those with
                                   2>/dev/null.
@@ -119,7 +124,7 @@ about _Black_'s changes or will overwrite _Black_'s changes. A good example of t
 should be configured to neither warn about nor overwrite _Black_'s changes.
 
 Actual details on _Black_ compatible configurations for various tools can be found in
-[compatible_configs](https://github.com/psf/black/blob/master/docs/compatible_configs.md#).
+[compatible_configs](https://github.com/psf/black/blob/master/docs/compatible_configs.md#black-compatible-configurations).
 
 ## Migrating your code style without ruining git blame
 
diff --git a/docs/version_control_integration.md b/docs/version_control_integration.md
index 0e09854a2e5..2d8bc172eba 100644
--- a/docs/version_control_integration.md
+++ b/docs/version_control_integration.md
@@ -23,11 +23,6 @@ for your project. See _Black_'s own
 [pyproject.toml](https://github.com/psf/black/blob/master/pyproject.toml) for an
 example.
 
-When using the `--diff` flag with `pre-commit`, you must also use the `--check` flag.
-When you want to run _Black_ only on specific files in pre-commit, either use
-pre-commit's own `files` and `exclude` or, when using _Black_'s `--include`, set
-`--force-exclude` to the negated regex of `--include`.
-
 If you're already using Python 3.7, switch the `language_version` accordingly. Finally,
 `stable` is a branch that tracks the latest release on PyPI. If you'd rather run on
 master, this is also an option.
diff --git a/test_requirements.txt b/test_requirements.txt
index 9f69b8edf83..a1464e90686 100644
--- a/test_requirements.txt
+++ b/test_requirements.txt
@@ -1,5 +1,7 @@
+coverage >= 5.3
+pre-commit
 pytest >= 6.1.1
 pytest-mock >= 3.3.1
 pytest-cases >= 2.3.0
-coverage >= 5.3
 parameterized >= 0.7.4
+tox

From b55fb821e795bc45903e6f7b89e8857ddb5a94f8 Mon Sep 17 00:00:00 2001
From: Peter Stensmyr <peter.stensmyr@iress.com>
Date: Fri, 15 Jan 2021 10:57:45 +1100
Subject: [PATCH 0068/1034] Update link pointing to how-black-wraps-lines
 (#1925)

The section about the Black code style has been moved to its own file.
Update link on the compatible configs page to point to the right place.
---
 docs/compatible_configs.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/compatible_configs.md b/docs/compatible_configs.md
index c6724e77e57..a4f83ee472f 100644
--- a/docs/compatible_configs.md
+++ b/docs/compatible_configs.md
@@ -221,7 +221,7 @@ max-line-length = 88
 ### Why those options above?
 
 When _Black_ is folding very long expressions, the closing brackets will
-[be dedented](https://github.com/psf/black#how-black-wraps-lines).
+[be dedented](https://github.com/psf/black/blob/master/docs/the_black_code_style.md#how-black-wraps-lines).
 
 ```py3
 ImportantClass.important_method(

From e8aadedd970140a840e8120bd36e8df52cc26ed2 Mon Sep 17 00:00:00 2001
From: Emilv2 <emil.vanherp@hotmail.com>
Date: Fri, 15 Jan 2021 23:43:23 +0100
Subject: [PATCH 0069/1034] Fix typo (#1931)

---
 src/black_primer/lib.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/black_primer/lib.py b/src/black_primer/lib.py
index 5c5576e1ff3..c3069812b22 100644
--- a/src/black_primer/lib.py
+++ b/src/black_primer/lib.py
@@ -21,7 +21,7 @@
 
 WINDOWS = system() == "Windows"
 BLACK_BINARY = "black.exe" if WINDOWS else "black"
-GIT_BIANRY = "git.exe" if WINDOWS else "git"
+GIT_BINARY = "git.exe" if WINDOWS else "git"
 LOG = logging.getLogger(__name__)
 
 
@@ -160,7 +160,7 @@ async def git_checkout_or_rebase(
     depth: int = 1,
 ) -> Optional[Path]:
     """git Clone project or rebase"""
-    git_bin = str(which(GIT_BIANRY))
+    git_bin = str(which(GIT_BINARY))
     if not git_bin:
         LOG.error("No git binary found")
         return None

From de510478d9b12490eddf93a785494f726897363b Mon Sep 17 00:00:00 2001
From: Zac Hatfield-Dodds <zac.hatfield.dodds@gmail.com>
Date: Sat, 16 Jan 2021 11:05:15 +1100
Subject: [PATCH 0070/1034] OSS-Fuzz integration (#1930)

---
 fuzz.py | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/fuzz.py b/fuzz.py
index 604e6ced291..6330c58cc81 100644
--- a/fuzz.py
+++ b/fuzz.py
@@ -56,4 +56,17 @@ def test_idempotent_any_syntatically_valid_python(
 
 
 if __name__ == "__main__":
+    # Run tests, including shrinking and reporting any known failures.
     test_idempotent_any_syntatically_valid_python()
+
+    # If Atheris is available, run coverage-guided fuzzing.
+    # (if you want only bounded fuzzing, just use `pytest fuzz.py`)
+    try:
+        import sys
+        import atheris
+    except ImportError:
+        pass
+    else:
+        test = test_idempotent_any_syntatically_valid_python
+        atheris.Setup(sys.argv, test.hypothesis.fuzz_one_input)
+        atheris.Fuzz()

From 692c0f50d91e3163bb87401e4a0e070b2eb5b163 Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Sun, 17 Jan 2021 16:59:06 -0800
Subject: [PATCH 0071/1034] Add --skip-magic-trailing-comma (#1824)

---
 README.md                                     |  19 +-
 docs/blackd.md                                |   3 +
 docs/installation_and_usage.md                |  18 +-
 docs/the_black_code_style.md                  |   3 +
 src/black/__init__.py                         |  89 ++--
 src/blackd/__init__.py                        |   6 +
 .../expression_skip_magic_trailing_comma.diff | 404 ++++++++++++++++++
 tests/test_black.py                           |  25 ++
 8 files changed, 531 insertions(+), 36 deletions(-)
 create mode 100644 tests/data/expression_skip_magic_trailing_comma.diff

diff --git a/README.md b/README.md
index 269bf5aaa43..f1ec76938f0 100644
--- a/README.md
+++ b/README.md
@@ -97,6 +97,10 @@ Options:
 
   -S, --skip-string-normalization
                                   Don't normalize string quotes or prefixes.
+  -C, --skip-magic-trailing-comma
+                                  Don't use trailing commas as a reason to
+                                  split lines.
+
   --check                         Don't write the files back, just return the
                                   status.  Return code 0 means nothing would
                                   change.  Return code 1 means some files
@@ -127,18 +131,19 @@ Options:
                                   paths are excluded. Use forward slashes for
                                   directories on all platforms (Windows, too).
                                   Exclusions are calculated first, inclusions
-                                  later.  [default: /(\.eggs|\.git|\.hg|\.mypy
-                                  _cache|\.nox|\.tox|\.venv|\.svn|_build|buck-
-                                  out|build|dist)/]
+                                  later.  [default: /(\.direnv|\.eggs|\.git|\.
+                                  hg|\.mypy_cache|\.nox|\.tox|\.venv|\.svn|_bu
+                                  ild|buck-out|build|dist)/]
 
   --force-exclude TEXT            Like --exclude, but files and directories
                                   matching this regex will be excluded even
-                                  when they are passed explicitly as arguments.
+                                  when they are passed explicitly as
+                                  arguments.
 
   --stdin-filename TEXT           The name of the file when passing it through
-                                  stdin. Useful to make sure Black will respect
-                                  --force-exclude option on some editors that
-                                  rely on using stdin.
+                                  stdin. Useful to make sure Black will
+                                  respect --force-exclude option on some
+                                  editors that rely on using stdin.
 
   -q, --quiet                     Don't emit non-error messages to stderr.
                                   Errors are still emitted; silence those with
diff --git a/docs/blackd.md b/docs/blackd.md
index c341308e1e4..c8058ee7c63 100644
--- a/docs/blackd.md
+++ b/docs/blackd.md
@@ -54,6 +54,9 @@ The headers controlling how source code is formatted are:
 - `X-Skip-String-Normalization`: corresponds to the `--skip-string-normalization`
   command line flag. If present and its value is not the empty string, no string
   normalization will be performed.
+- `X-Skip-Magic-Trailing-Comma`: corresponds to the `--skip-magic-trailing-comma`
+  command line flag. If present and its value is not the empty string, trailing commas
+  will not be used as a reason to split lines.
 - `X-Fast-Or-Safe`: if set to `fast`, `blackd` will act as _Black_ does when passed the
   `--fast` command line flag.
 - `X-Python-Variant`: if set to `pyi`, `blackd` will act as _Black_ does when passed the
diff --git a/docs/installation_and_usage.md b/docs/installation_and_usage.md
index d0dd0c99dc5..e3b53fd076e 100644
--- a/docs/installation_and_usage.md
+++ b/docs/installation_and_usage.md
@@ -52,6 +52,10 @@ Options:
 
   -S, --skip-string-normalization
                                   Don't normalize string quotes or prefixes.
+  -C, --skip-magic-trailing-comma
+                                  Don't use trailing commas as a reason to
+                                  split lines.
+
   --check                         Don't write the files back, just return the
                                   status.  Return code 0 means nothing would
                                   change.  Return code 1 means some files
@@ -82,13 +86,19 @@ Options:
                                   paths are excluded. Use forward slashes for
                                   directories on all platforms (Windows, too).
                                   Exclusions are calculated first, inclusions
-                                  later.  [default: /(\.eggs|\.git|\.hg|\.mypy
-                                  _cache|\.nox|\.tox|\.venv|\.svn|_build|buck-
-                                  out|build|dist)/]
+                                  later.  [default: /(\.direnv|\.eggs|\.git|\.
+                                  hg|\.mypy_cache|\.nox|\.tox|\.venv|\.svn|_bu
+                                  ild|buck-out|build|dist)/]
 
   --force-exclude TEXT            Like --exclude, but files and directories
                                   matching this regex will be excluded even
-                                  when they are passed explicitly as arguments.
+                                  when they are passed explicitly as
+                                  arguments.
+
+  --stdin-filename TEXT           The name of the file when passing it through
+                                  stdin. Useful to make sure Black will
+                                  respect --force-exclude option on some
+                                  editors that rely on using stdin.
 
   --stdin-filename TEXT           The name of the file when passing it through
                                   stdin. Useful to make sure Black will respect
diff --git a/docs/the_black_code_style.md b/docs/the_black_code_style.md
index 19464ba482a..a4e55c1744c 100644
--- a/docs/the_black_code_style.md
+++ b/docs/the_black_code_style.md
@@ -438,6 +438,9 @@ into one item per line.
 How do you make it stop? Just delete that trailing comma and _Black_ will collapse your
 collection into one line if it fits.
 
+If you must, you can recover the behaviour of early versions of Black with the option
+`--skip-magic-trailing-comma` / `-C`.
+
 ### r"strings" and R"strings"
 
 _Black_ normalizes string quotes as well as string prefixes, making them lowercase. One
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 91f70d96165..9034bf6cf77 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -260,6 +260,7 @@ class Mode:
     target_versions: Set[TargetVersion] = field(default_factory=set)
     line_length: int = DEFAULT_LINE_LENGTH
     string_normalization: bool = True
+    magic_trailing_comma: bool = True
     experimental_string_processing: bool = False
     is_pyi: bool = False
 
@@ -397,6 +398,12 @@ def target_version_option_callback(
     is_flag=True,
     help="Don't normalize string quotes or prefixes.",
 )
+@click.option(
+    "-C",
+    "--skip-magic-trailing-comma",
+    is_flag=True,
+    help="Don't use trailing commas as a reason to split lines.",
+)
 @click.option(
     "--experimental-string-processing",
     is_flag=True,
@@ -524,6 +531,7 @@ def main(
     fast: bool,
     pyi: bool,
     skip_string_normalization: bool,
+    skip_magic_trailing_comma: bool,
     experimental_string_processing: bool,
     quiet: bool,
     verbose: bool,
@@ -546,6 +554,7 @@ def main(
         line_length=line_length,
         is_pyi=pyi,
         string_normalization=not skip_string_normalization,
+        magic_trailing_comma=not skip_magic_trailing_comma,
         experimental_string_processing=experimental_string_processing,
     )
     if config and verbose:
@@ -1022,13 +1031,12 @@ def f(
         versions = detect_target_versions(src_node)
     normalize_fmt_off(src_node)
     lines = LineGenerator(
+        mode=mode,
         remove_u_prefix="unicode_literals" in future_imports
         or supports_feature(versions, Feature.UNICODE_LITERALS),
-        is_pyi=mode.is_pyi,
-        normalize_strings=mode.string_normalization,
     )
     elt = EmptyLineTracker(is_pyi=mode.is_pyi)
-    empty_line = Line()
+    empty_line = Line(mode=mode)
     after = 0
     split_line_features = {
         feature
@@ -1464,6 +1472,7 @@ def get_open_lsqb(self) -> Optional[Leaf]:
 class Line:
     """Holds leaves and comments. Can be printed with `str(line)`."""
 
+    mode: Mode
     depth: int = 0
     leaves: List[Leaf] = field(default_factory=list)
     # keys ordered like `leaves`
@@ -1496,8 +1505,11 @@ def append(self, leaf: Leaf, preformatted: bool = False) -> None:
             )
         if self.inside_brackets or not preformatted:
             self.bracket_tracker.mark(leaf)
-            if self.maybe_should_explode(leaf):
-                self.should_explode = True
+            if self.mode.magic_trailing_comma:
+                if self.has_magic_trailing_comma(leaf):
+                    self.should_explode = True
+            elif self.has_magic_trailing_comma(leaf, ensure_removable=True):
+                self.remove_trailing_comma()
         if not self.append_comment(leaf):
             self.leaves.append(leaf)
 
@@ -1673,10 +1685,14 @@ def contains_unsplittable_type_ignore(self) -> bool:
     def contains_multiline_strings(self) -> bool:
         return any(is_multiline_string(leaf) for leaf in self.leaves)
 
-    def maybe_should_explode(self, closing: Leaf) -> bool:
-        """Return True if this line should explode (always be split), that is when:
-        - there's a trailing comma here; and
-        - it's not a one-tuple.
+    def has_magic_trailing_comma(
+        self, closing: Leaf, ensure_removable: bool = False
+    ) -> bool:
+        """Return True if we have a magic trailing comma, that is when:
+        - there's a trailing comma here
+        - it's not a one-tuple
+        Additionally, if ensure_removable:
+        - it's not from square bracket indexing
         """
         if not (
             closing.type in CLOSING_BRACKETS
@@ -1685,9 +1701,15 @@ def maybe_should_explode(self, closing: Leaf) -> bool:
         ):
             return False
 
-        if closing.type in {token.RBRACE, token.RSQB}:
+        if closing.type == token.RBRACE:
             return True
 
+        if closing.type == token.RSQB:
+            if not ensure_removable:
+                return True
+            comma = self.leaves[-1]
+            return bool(comma.parent and comma.parent.type == syms.listmaker)
+
         if self.is_import:
             return True
 
@@ -1765,6 +1787,7 @@ def is_complex_subscript(self, leaf: Leaf) -> bool:
 
     def clone(self) -> "Line":
         return Line(
+            mode=self.mode,
             depth=self.depth,
             inside_brackets=self.inside_brackets,
             should_explode=self.should_explode,
@@ -1923,10 +1946,9 @@ class LineGenerator(Visitor[Line]):
     in ways that will no longer stringify to valid Python code on the tree.
     """
 
-    is_pyi: bool = False
-    normalize_strings: bool = True
-    current_line: Line = field(default_factory=Line)
+    mode: Mode
     remove_u_prefix: bool = False
+    current_line: Line = field(init=False)
 
     def line(self, indent: int = 0) -> Iterator[Line]:
         """Generate a line.
@@ -1941,7 +1963,7 @@ def line(self, indent: int = 0) -> Iterator[Line]:
             return  # Line is empty, don't emit. Creating a new one unnecessary.
 
         complete_line = self.current_line
-        self.current_line = Line(depth=complete_line.depth + indent)
+        self.current_line = Line(mode=self.mode, depth=complete_line.depth + indent)
         yield complete_line
 
     def visit_default(self, node: LN) -> Iterator[Line]:
@@ -1965,7 +1987,7 @@ def visit_default(self, node: LN) -> Iterator[Line]:
                     yield from self.line()
 
             normalize_prefix(node, inside_brackets=any_open_brackets)
-            if self.normalize_strings and node.type == token.STRING:
+            if self.mode.string_normalization and node.type == token.STRING:
                 normalize_string_prefix(node, remove_u_prefix=self.remove_u_prefix)
                 normalize_string_quotes(node)
             if node.type == token.NUMBER:
@@ -2017,7 +2039,7 @@ def visit_stmt(
 
     def visit_suite(self, node: Node) -> Iterator[Line]:
         """Visit a suite."""
-        if self.is_pyi and is_stub_suite(node):
+        if self.mode.is_pyi and is_stub_suite(node):
             yield from self.visit(node.children[2])
         else:
             yield from self.visit_default(node)
@@ -2026,7 +2048,7 @@ def visit_simple_stmt(self, node: Node) -> Iterator[Line]:
         """Visit a statement without nested statements."""
         is_suite_like = node.parent and node.parent.type in STATEMENT
         if is_suite_like:
-            if self.is_pyi and is_stub_body(node):
+            if self.mode.is_pyi and is_stub_body(node):
                 yield from self.visit_default(node)
             else:
                 yield from self.line(+1)
@@ -2034,7 +2056,11 @@ def visit_simple_stmt(self, node: Node) -> Iterator[Line]:
                 yield from self.line(-1)
 
         else:
-            if not self.is_pyi or not node.parent or not is_stub_suite(node.parent):
+            if (
+                not self.mode.is_pyi
+                or not node.parent
+                or not is_stub_suite(node.parent)
+            ):
                 yield from self.line()
             yield from self.visit_default(node)
 
@@ -2110,6 +2136,8 @@ def visit_STRING(self, leaf: Leaf) -> Iterator[Line]:
 
     def __post_init__(self) -> None:
         """You are in a twisty little maze of passages."""
+        self.current_line = Line(mode=self.mode)
+
         v = self.visit_stmt
         Ø: Set[str] = set()
         self.visit_assert_stmt = partial(v, keywords={"assert"}, parens={"assert", ","})
@@ -4350,6 +4378,7 @@ def do_transform(self, line: Line, string_idx: int) -> Iterator[TResult[Line]]:
         # `StringSplitter` will break it down further if necessary.
         string_value = LL[string_idx].value
         string_line = Line(
+            mode=line.mode,
             depth=line.depth + 1,
             inside_brackets=True,
             should_explode=line.should_explode,
@@ -4943,7 +4972,7 @@ def bracket_split_build_line(
     If `is_body` is True, the result line is one-indented inside brackets and as such
     has its first leaf's prefix normalized and a trailing comma added when expected.
     """
-    result = Line(depth=original.depth)
+    result = Line(mode=original.mode, depth=original.depth)
     if is_body:
         result.inside_brackets = True
         result.depth += 1
@@ -5015,7 +5044,9 @@ def delimiter_split(line: Line, features: Collection[Feature] = ()) -> Iterator[
         if bt.delimiter_count_with_priority(delimiter_priority) == 1:
             raise CannotSplit("Splitting a single attribute from its owner looks wrong")
 
-    current_line = Line(depth=line.depth, inside_brackets=line.inside_brackets)
+    current_line = Line(
+        mode=line.mode, depth=line.depth, inside_brackets=line.inside_brackets
+    )
     lowest_depth = sys.maxsize
     trailing_comma_safe = True
 
@@ -5027,7 +5058,9 @@ def append_to_line(leaf: Leaf) -> Iterator[Line]:
         except ValueError:
             yield current_line
 
-            current_line = Line(depth=line.depth, inside_brackets=line.inside_brackets)
+            current_line = Line(
+                mode=line.mode, depth=line.depth, inside_brackets=line.inside_brackets
+            )
             current_line.append(leaf)
 
     for leaf in line.leaves:
@@ -5051,7 +5084,9 @@ def append_to_line(leaf: Leaf) -> Iterator[Line]:
         if leaf_priority == delimiter_priority:
             yield current_line
 
-            current_line = Line(depth=line.depth, inside_brackets=line.inside_brackets)
+            current_line = Line(
+                mode=line.mode, depth=line.depth, inside_brackets=line.inside_brackets
+            )
     if current_line:
         if (
             trailing_comma_safe
@@ -5072,7 +5107,9 @@ def standalone_comment_split(
     if not line.contains_standalone_comments(0):
         raise CannotSplit("Line does not have any standalone comments")
 
-    current_line = Line(depth=line.depth, inside_brackets=line.inside_brackets)
+    current_line = Line(
+        mode=line.mode, depth=line.depth, inside_brackets=line.inside_brackets
+    )
 
     def append_to_line(leaf: Leaf) -> Iterator[Line]:
         """Append `leaf` to current line or to new line if appending impossible."""
@@ -5082,7 +5119,9 @@ def append_to_line(leaf: Leaf) -> Iterator[Line]:
         except ValueError:
             yield current_line
 
-            current_line = Line(depth=line.depth, inside_brackets=line.inside_brackets)
+            current_line = Line(
+                line.mode, depth=line.depth, inside_brackets=line.inside_brackets
+            )
             current_line.append(leaf)
 
     for leaf in line.leaves:
@@ -5767,7 +5806,7 @@ def should_split_body_explode(line: Line, opening_bracket: Leaf) -> bool:
         return False
 
     return max_priority == COMMA_PRIORITY and (
-        trailing_comma
+        (line.mode.magic_trailing_comma and trailing_comma)
         # always explode imports
         or opening_bracket.parent.type in {syms.atom, syms.import_from}
     )
diff --git a/src/blackd/__init__.py b/src/blackd/__init__.py
index f77a5e8e7be..fc684730e4b 100644
--- a/src/blackd/__init__.py
+++ b/src/blackd/__init__.py
@@ -32,6 +32,7 @@
 LINE_LENGTH_HEADER = "X-Line-Length"
 PYTHON_VARIANT_HEADER = "X-Python-Variant"
 SKIP_STRING_NORMALIZATION_HEADER = "X-Skip-String-Normalization"
+SKIP_MAGIC_TRAILING_COMMA = "X-Skip-Magic-Trailing-Comma"
 FAST_OR_SAFE_HEADER = "X-Fast-Or-Safe"
 DIFF_HEADER = "X-Diff"
 
@@ -40,6 +41,7 @@
     LINE_LENGTH_HEADER,
     PYTHON_VARIANT_HEADER,
     SKIP_STRING_NORMALIZATION_HEADER,
+    SKIP_MAGIC_TRAILING_COMMA,
     FAST_OR_SAFE_HEADER,
     DIFF_HEADER,
 ]
@@ -114,6 +116,9 @@ async def handle(request: web.Request, executor: Executor) -> web.Response:
         skip_string_normalization = bool(
             request.headers.get(SKIP_STRING_NORMALIZATION_HEADER, False)
         )
+        skip_magic_trailing_comma = bool(
+            request.headers.get(SKIP_MAGIC_TRAILING_COMMA, False)
+        )
         fast = False
         if request.headers.get(FAST_OR_SAFE_HEADER, "safe") == "fast":
             fast = True
@@ -122,6 +127,7 @@ async def handle(request: web.Request, executor: Executor) -> web.Response:
             is_pyi=pyi,
             line_length=line_length,
             string_normalization=not skip_string_normalization,
+            magic_trailing_comma=not skip_magic_trailing_comma,
         )
         req_bytes = await request.content.read()
         charset = request.charset if request.charset is not None else "utf8"
diff --git a/tests/data/expression_skip_magic_trailing_comma.diff b/tests/data/expression_skip_magic_trailing_comma.diff
new file mode 100644
index 00000000000..8a0225bceb5
--- /dev/null
+++ b/tests/data/expression_skip_magic_trailing_comma.diff
@@ -0,0 +1,404 @@
+--- [Deterministic header]
++++ [Deterministic header]
+@@ -1,8 +1,8 @@
+ ...
+-'some_string'
+-b'\\xa3'
++"some_string"
++b"\\xa3"
+ Name
+ None
+ True
+ False
+ 1
+@@ -29,63 +29,84 @@
+ ~great
+ +value
+ -1
+ ~int and not v1 ^ 123 + v2 | True
+ (~int) and (not ((v1 ^ (123 + v2)) | True))
+-+really ** -confusing ** ~operator ** -precedence
+-flags & ~ select.EPOLLIN and waiters.write_task is not None
+++(really ** -(confusing ** ~(operator ** -precedence)))
++flags & ~select.EPOLLIN and waiters.write_task is not None
+ lambda arg: None
+ lambda a=True: a
+ lambda a, b, c=True: a
+-lambda a, b, c=True, *, d=(1 << v2), e='str': a
+-lambda a, b, c=True, *vararg, d=(v1 << 2), e='str', **kwargs: a + b
++lambda a, b, c=True, *, d=(1 << v2), e="str": a
++lambda a, b, c=True, *vararg, d=(v1 << 2), e="str", **kwargs: a + b
+ manylambdas = lambda x=lambda y=lambda z=1: z: y(): x()
+-foo = (lambda port_id, ignore_missing: {"port1": port1_resource, "port2": port2_resource}[port_id])
++foo = lambda port_id, ignore_missing: {
++    "port1": port1_resource,
++    "port2": port2_resource,
++}[port_id]
+ 1 if True else 2
+ str or None if True else str or bytes or None
+ (str or None) if True else (str or bytes or None)
+ str or None if (1 if True else 2) else str or bytes or None
+ (str or None) if (1 if True else 2) else (str or bytes or None)
+-((super_long_variable_name or None) if (1 if super_long_test_name else 2) else (str or bytes or None))
+-{'2.7': dead, '3.7': (long_live or die_hard)}
+-{'2.7': dead, '3.7': (long_live or die_hard), **{'3.6': verygood}}
++(
++    (super_long_variable_name or None)
++    if (1 if super_long_test_name else 2)
++    else (str or bytes or None)
++)
++{"2.7": dead, "3.7": (long_live or die_hard)}
++{"2.7": dead, "3.7": (long_live or die_hard), **{"3.6": verygood}}
+ {**a, **b, **c}
+-{'2.7', '3.6', '3.7', '3.8', '3.9', ('4.0' if gilectomy else '3.10')}
+-({'a': 'b'}, (True or False), (+value), 'string', b'bytes') or None
++{"2.7", "3.6", "3.7", "3.8", "3.9", ("4.0" if gilectomy else "3.10")}
++({"a": "b"}, (True or False), (+value), "string", b"bytes") or None
+ ()
+ (1,)
+ (1, 2)
+ (1, 2, 3)
+ []
+ [1, 2, 3, 4, 5, 6, 7, 8, 9, (10 or A), (11 or B), (12 or C)]
+-[1, 2, 3,]
++[1, 2, 3]
+ [*a]
+ [*range(10)]
+-[*a, 4, 5,]
+-[4, *a, 5,]
+-[this_is_a_very_long_variable_which_will_force_a_delimiter_split, element, another, *more]
++[*a, 4, 5]
++[4, *a, 5]
++[
++    this_is_a_very_long_variable_which_will_force_a_delimiter_split,
++    element,
++    another,
++    *more,
++]
+ {i for i in (1, 2, 3)}
+ {(i ** 2) for i in (1, 2, 3)}
+-{(i ** 2) for i, _ in ((1, 'a'), (2, 'b'), (3, 'c'))}
++{(i ** 2) for i, _ in ((1, "a"), (2, "b"), (3, "c"))}
+ {((i ** 2) + j) for i in (1, 2, 3) for j in (1, 2, 3)}
+ [i for i in (1, 2, 3)]
+ [(i ** 2) for i in (1, 2, 3)]
+-[(i ** 2) for i, _ in ((1, 'a'), (2, 'b'), (3, 'c'))]
++[(i ** 2) for i, _ in ((1, "a"), (2, "b"), (3, "c"))]
+ [((i ** 2) + j) for i in (1, 2, 3) for j in (1, 2, 3)]
+ {i: 0 for i in (1, 2, 3)}
+-{i: j for i, j in ((1, 'a'), (2, 'b'), (3, 'c'))}
++{i: j for i, j in ((1, "a"), (2, "b"), (3, "c"))}
+ {a: b * 2 for a, b in dictionary.items()}
+ {a: b * -2 for a, b in dictionary.items()}
+-{k: v for k, v in this_is_a_very_long_variable_which_will_cause_a_trailing_comma_which_breaks_the_comprehension}
++{
++    k: v
++    for k, v in this_is_a_very_long_variable_which_will_cause_a_trailing_comma_which_breaks_the_comprehension
++}
+ Python3 > Python2 > COBOL
+ Life is Life
+ call()
+ call(arg)
+-call(kwarg='hey')
+-call(arg, kwarg='hey')
+-call(arg, another, kwarg='hey', **kwargs)
+-call(this_is_a_very_long_variable_which_will_force_a_delimiter_split, arg, another, kwarg='hey', **kwargs)  # note: no trailing comma pre-3.6
++call(kwarg="hey")
++call(arg, kwarg="hey")
++call(arg, another, kwarg="hey", **kwargs)
++call(
++    this_is_a_very_long_variable_which_will_force_a_delimiter_split,
++    arg,
++    another,
++    kwarg="hey",
++    **kwargs
++)  # note: no trailing comma pre-3.6
+ call(*gidgets[:2])
+ call(a, *gidgets[:2])
+ call(**self.screen_kwargs)
+ call(b, **self.screen_kwargs)
+ lukasz.langa.pl
+@@ -94,26 +115,24 @@
+ 1.0 .real
+ ....__class__
+ list[str]
+ dict[str, int]
+ tuple[str, ...]
+-tuple[
+-    str, int, float, dict[str, int]
+-]
++tuple[str, int, float, dict[str, int]]
+ tuple[str, int, float, dict[str, int],]
+ very_long_variable_name_filters: t.List[
+     t.Tuple[str, t.Union[str, t.List[t.Optional[str]]]],
+ ]
+ xxxx_xxxxx_xxxx_xxx: Callable[..., List[SomeClass]] = classmethod(  # type: ignore
+     sync(async_xxxx_xxx_xxxx_xxxxx_xxxx_xxx.__func__)
+ )
+ xxxx_xxx_xxxx_xxxxx_xxxx_xxx: Callable[..., List[SomeClass]] = classmethod(  # type: ignore
+     sync(async_xxxx_xxx_xxxx_xxxxx_xxxx_xxx.__func__)
+ )
+-xxxx_xxx_xxxx_xxxxx_xxxx_xxx: Callable[
+-    ..., List[SomeClass]
+-] = classmethod(sync(async_xxxx_xxx_xxxx_xxxxx_xxxx_xxx.__func__))  # type: ignore
++xxxx_xxx_xxxx_xxxxx_xxxx_xxx: Callable[..., List[SomeClass]] = classmethod(
++    sync(async_xxxx_xxx_xxxx_xxxxx_xxxx_xxx.__func__)
++)  # type: ignore
+ slice[0]
+ slice[0:1]
+ slice[0:1:2]
+ slice[:]
+ slice[:-1]
+@@ -137,113 +156,178 @@
+ numpy[-(c + 1) :, d]
+ numpy[:, l[-2]]
+ numpy[:, ::-1]
+ numpy[np.newaxis, :]
+ (str or None) if (sys.version_info[0] > (3,)) else (str or bytes or None)
+-{'2.7': dead, '3.7': long_live or die_hard}
+-{'2.7', '3.6', '3.7', '3.8', '3.9', '4.0' if gilectomy else '3.10'}
++{"2.7": dead, "3.7": long_live or die_hard}
++{"2.7", "3.6", "3.7", "3.8", "3.9", "4.0" if gilectomy else "3.10"}
+ [1, 2, 3, 4, 5, 6, 7, 8, 9, 10 or A, 11 or B, 12 or C]
+ (SomeName)
+ SomeName
+ (Good, Bad, Ugly)
+ (i for i in (1, 2, 3))
+ ((i ** 2) for i in (1, 2, 3))
+-((i ** 2) for i, _ in ((1, 'a'), (2, 'b'), (3, 'c')))
++((i ** 2) for i, _ in ((1, "a"), (2, "b"), (3, "c")))
+ (((i ** 2) + j) for i in (1, 2, 3) for j in (1, 2, 3))
+ (*starred,)
+-{"id": "1","type": "type","started_at": now(),"ended_at": now() + timedelta(days=10),"priority": 1,"import_session_id": 1,**kwargs}
++{
++    "id": "1",
++    "type": "type",
++    "started_at": now(),
++    "ended_at": now() + timedelta(days=10),
++    "priority": 1,
++    "import_session_id": 1,
++    **kwargs,
++}
+ a = (1,)
+-b = 1,
++b = (1,)
+ c = 1
+ d = (1,) + a + (2,)
+ e = (1,).count(1)
+ f = 1, *range(10)
+ g = 1, *"ten"
+-what_is_up_with_those_new_coord_names = (coord_names + set(vars_to_create)) + set(vars_to_remove)
+-what_is_up_with_those_new_coord_names = (coord_names | set(vars_to_create)) - set(vars_to_remove)
+-result = session.query(models.Customer.id).filter(models.Customer.account_id == account_id, models.Customer.email == email_address).order_by(models.Customer.id.asc()).all()
+-result = session.query(models.Customer.id).filter(models.Customer.account_id == account_id, models.Customer.email == email_address).order_by(models.Customer.id.asc(),).all()
++what_is_up_with_those_new_coord_names = (coord_names + set(vars_to_create)) + set(
++    vars_to_remove
++)
++what_is_up_with_those_new_coord_names = (coord_names | set(vars_to_create)) - set(
++    vars_to_remove
++)
++result = (
++    session.query(models.Customer.id)
++    .filter(
++        models.Customer.account_id == account_id, models.Customer.email == email_address
++    )
++    .order_by(models.Customer.id.asc())
++    .all()
++)
++result = (
++    session.query(models.Customer.id)
++    .filter(
++        models.Customer.account_id == account_id, models.Customer.email == email_address
++    )
++    .order_by(models.Customer.id.asc())
++    .all()
++)
+ Ø = set()
+ authors.łukasz.say_thanks()
+ mapping = {
+     A: 0.25 * (10.0 / 12),
+     B: 0.1 * (10.0 / 12),
+     C: 0.1 * (10.0 / 12),
+     D: 0.1 * (10.0 / 12),
+ }
+ 
++
+ def gen():
+     yield from outside_of_generator
+-    a = (yield)
+-    b = ((yield))
+-    c = (((yield)))
++    a = yield
++    b = yield
++    c = yield
++
+ 
+ async def f():
+     await some.complicated[0].call(with_args=(True or (1 is not 1)))
+-print(* [] or [1])
++
++
++print(*[] or [1])
+ print(**{1: 3} if False else {x: x for x in range(3)})
+-print(* lambda x: x)
+-assert(not Test),("Short message")
+-assert this is ComplexTest and not requirements.fit_in_a_single_line(force=False), "Short message"
+-assert(((parens is TooMany)))
+-for x, in (1,), (2,), (3,): ...
+-for y in (): ...
+-for z in (i for i in (1, 2, 3)): ...
+-for i in (call()): ...
+-for j in (1 + (2 + 3)): ...
+-while(this and that): ...
+-for addr_family, addr_type, addr_proto, addr_canonname, addr_sockaddr in socket.getaddrinfo('google.com', 'http'):
++print(*lambda x: x)
++assert not Test, "Short message"
++assert this is ComplexTest and not requirements.fit_in_a_single_line(
++    force=False
++), "Short message"
++assert parens is TooMany
++for (x,) in (1,), (2,), (3,):
++    ...
++for y in ():
++    ...
++for z in (i for i in (1, 2, 3)):
++    ...
++for i in call():
++    ...
++for j in 1 + (2 + 3):
++    ...
++while this and that:
++    ...
++for (
++    addr_family,
++    addr_type,
++    addr_proto,
++    addr_canonname,
++    addr_sockaddr,
++) in socket.getaddrinfo("google.com", "http"):
+     pass
+-a = aaaa.bbbb.cccc.dddd.eeee.ffff.gggg.hhhh.iiii.jjjj.kkkk.llll.mmmm.nnnn.oooo.pppp in qqqq.rrrr.ssss.tttt.uuuu.vvvv.xxxx.yyyy.zzzz
+-a = aaaa.bbbb.cccc.dddd.eeee.ffff.gggg.hhhh.iiii.jjjj.kkkk.llll.mmmm.nnnn.oooo.pppp not in qqqq.rrrr.ssss.tttt.uuuu.vvvv.xxxx.yyyy.zzzz
+-a = aaaa.bbbb.cccc.dddd.eeee.ffff.gggg.hhhh.iiii.jjjj.kkkk.llll.mmmm.nnnn.oooo.pppp is qqqq.rrrr.ssss.tttt.uuuu.vvvv.xxxx.yyyy.zzzz
+-a = aaaa.bbbb.cccc.dddd.eeee.ffff.gggg.hhhh.iiii.jjjj.kkkk.llll.mmmm.nnnn.oooo.pppp is not qqqq.rrrr.ssss.tttt.uuuu.vvvv.xxxx.yyyy.zzzz
+-if (
+-    threading.current_thread() != threading.main_thread() and
+-    threading.current_thread() != threading.main_thread() or
+-    signal.getsignal(signal.SIGINT) != signal.default_int_handler
+-):
+-    return True
+-if (
+-    aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa |
+-    aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+-):
+-    return True
+-if (
+-    aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa &
+-    aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+-):
+-    return True
+-if (
+-    aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa +
+-    aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+-):
+-    return True
+-if (
+-    aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa -
+-    aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+-):
+-    return True
+-if (
+-    aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa *
+-    aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+-):
+-    return True
+-if (
+-    aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa /
+-    aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+-):
+-    return True
+-if (
+-    ~ aaaa.a + aaaa.b - aaaa.c * aaaa.d / aaaa.e | aaaa.f & aaaa.g % aaaa.h ^ aaaa.i << aaaa.k >> aaaa.l ** aaaa.m // aaaa.n
+-):
+-    return True
+-if (
+-    ~ aaaaaaaa.a + aaaaaaaa.b - aaaaaaaa.c @ aaaaaaaa.d / aaaaaaaa.e | aaaaaaaa.f & aaaaaaaa.g % aaaaaaaa.h ^ aaaaaaaa.i << aaaaaaaa.k >> aaaaaaaa.l ** aaaaaaaa.m // aaaaaaaa.n
+-):
+-    return True
+-if (
+-    ~ aaaaaaaaaaaaaaaa.a + aaaaaaaaaaaaaaaa.b - aaaaaaaaaaaaaaaa.c * aaaaaaaaaaaaaaaa.d @ aaaaaaaaaaaaaaaa.e | aaaaaaaaaaaaaaaa.f & aaaaaaaaaaaaaaaa.g % aaaaaaaaaaaaaaaa.h ^ aaaaaaaaaaaaaaaa.i << aaaaaaaaaaaaaaaa.k >> aaaaaaaaaaaaaaaa.l ** aaaaaaaaaaaaaaaa.m // aaaaaaaaaaaaaaaa.n
++a = (
++    aaaa.bbbb.cccc.dddd.eeee.ffff.gggg.hhhh.iiii.jjjj.kkkk.llll.mmmm.nnnn.oooo.pppp
++    in qqqq.rrrr.ssss.tttt.uuuu.vvvv.xxxx.yyyy.zzzz
++)
++a = (
++    aaaa.bbbb.cccc.dddd.eeee.ffff.gggg.hhhh.iiii.jjjj.kkkk.llll.mmmm.nnnn.oooo.pppp
++    not in qqqq.rrrr.ssss.tttt.uuuu.vvvv.xxxx.yyyy.zzzz
++)
++a = (
++    aaaa.bbbb.cccc.dddd.eeee.ffff.gggg.hhhh.iiii.jjjj.kkkk.llll.mmmm.nnnn.oooo.pppp
++    is qqqq.rrrr.ssss.tttt.uuuu.vvvv.xxxx.yyyy.zzzz
++)
++a = (
++    aaaa.bbbb.cccc.dddd.eeee.ffff.gggg.hhhh.iiii.jjjj.kkkk.llll.mmmm.nnnn.oooo.pppp
++    is not qqqq.rrrr.ssss.tttt.uuuu.vvvv.xxxx.yyyy.zzzz
++)
++if (
++    threading.current_thread() != threading.main_thread()
++    and threading.current_thread() != threading.main_thread()
++    or signal.getsignal(signal.SIGINT) != signal.default_int_handler
++):
++    return True
++if (
++    aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
++    | aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
++):
++    return True
++if (
++    aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
++    & aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
++):
++    return True
++if (
++    aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
++    + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
++):
++    return True
++if (
++    aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
++    - aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
++):
++    return True
++if (
++    aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
++    * aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
++):
++    return True
++if (
++    aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
++    / aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
++):
++    return True
++if (
++    ~aaaa.a + aaaa.b - aaaa.c * aaaa.d / aaaa.e
++    | aaaa.f & aaaa.g % aaaa.h ^ aaaa.i << aaaa.k >> aaaa.l ** aaaa.m // aaaa.n
++):
++    return True
++if (
++    ~aaaaaaaa.a + aaaaaaaa.b - aaaaaaaa.c @ aaaaaaaa.d / aaaaaaaa.e
++    | aaaaaaaa.f & aaaaaaaa.g % aaaaaaaa.h
++    ^ aaaaaaaa.i << aaaaaaaa.k >> aaaaaaaa.l ** aaaaaaaa.m // aaaaaaaa.n
++):
++    return True
++if (
++    ~aaaaaaaaaaaaaaaa.a
++    + aaaaaaaaaaaaaaaa.b
++    - aaaaaaaaaaaaaaaa.c * aaaaaaaaaaaaaaaa.d @ aaaaaaaaaaaaaaaa.e
++    | aaaaaaaaaaaaaaaa.f & aaaaaaaaaaaaaaaa.g % aaaaaaaaaaaaaaaa.h
++    ^ aaaaaaaaaaaaaaaa.i
++    << aaaaaaaaaaaaaaaa.k
++    >> aaaaaaaaaaaaaaaa.l ** aaaaaaaaaaaaaaaa.m // aaaaaaaaaaaaaaaa.n
+ ):
+     return True
+ last_call()
+ # standalone comment at ENDMARKER
diff --git a/tests/test_black.py b/tests/test_black.py
index a688c8780ef..28b75787bd6 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -395,6 +395,31 @@ def test_numeric_literals_ignoring_underscores(self) -> None:
         black.assert_equivalent(source, actual)
         black.assert_stable(source, actual, mode)
 
+    def test_skip_magic_trailing_comma(self) -> None:
+        source, _ = read_data("expression.py")
+        expected, _ = read_data("expression_skip_magic_trailing_comma.diff")
+        tmp_file = Path(black.dump_to_file(source))
+        diff_header = re.compile(
+            rf"{re.escape(str(tmp_file))}\t\d\d\d\d-\d\d-\d\d "
+            r"\d\d:\d\d:\d\d\.\d\d\d\d\d\d \+\d\d\d\d"
+        )
+        try:
+            result = BlackRunner().invoke(black.main, ["-C", "--diff", str(tmp_file)])
+            self.assertEqual(result.exit_code, 0)
+        finally:
+            os.unlink(tmp_file)
+        actual = result.output
+        actual = diff_header.sub(DETERMINISTIC_HEADER, actual)
+        actual = actual.rstrip() + "\n"  # the diff output has a trailing space
+        if expected != actual:
+            dump = black.dump_to_file(actual)
+            msg = (
+                "Expected diff isn't equal to the actual. If you made changes to"
+                " expression.py and this is an anticipated difference, overwrite"
+                f" tests/data/expression_skip_magic_trailing_comma.diff with {dump}"
+            )
+            self.assertEqual(expected, actual, msg)
+
     @patch("black.dump_to_file", dump_to_stderr)
     def test_python2_print_function(self) -> None:
         source, expected = read_data("python2_print_function")

From 71117e730c4f62458b30af820f51890487b458e4 Mon Sep 17 00:00:00 2001
From: Oliver Newman <15459200+orn688@users.noreply.github.com>
Date: Wed, 27 Jan 2021 12:36:21 -0500
Subject: [PATCH 0072/1034] Update example exclude to match only files in root
 (#1861)

* Update example exclude to match only files in root

The `exclude` section of the example `pyproject.toml` file didn't work
as expected. It claimed to exclude matched files only in the project
root, but it actually excluded matched files at any directory level
within the project. We can address this by prepending `^/` to the regex
to ensure that it only matches files in the project root.

See https://github.com/psf/black/issues/1473#issuecomment-740008873 for
explanation.

* Mention excluding directories as well
---
 README.md | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index f1ec76938f0..83ecb89d6c9 100644
--- a/README.md
+++ b/README.md
@@ -313,9 +313,10 @@ line-length = 88
 target-version = ['py37']
 include = '\.pyi?$'
 exclude = '''
-
-(
-  /(
+# A regex preceded with ^/ will apply only to files and directories
+# in the root of the project.
+^/(
+  (
       \.eggs         # exclude a few common directories in the
     | \.git          # root of the project
     | \.hg

From 988c686d312986760a42cc7edd9a79a8f31c4769 Mon Sep 17 00:00:00 2001
From: James Addison <jay@jp-hosting.net>
Date: Mon, 1 Feb 2021 17:54:19 +0000
Subject: [PATCH 0073/1034] Remove placeholder exit code in unreachable
 'black-primer' subprocess handler (#1952)

---
 src/black_primer/lib.py | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/src/black_primer/lib.py b/src/black_primer/lib.py
index c3069812b22..39ae93ba516 100644
--- a/src/black_primer/lib.py
+++ b/src/black_primer/lib.py
@@ -58,13 +58,16 @@ async def _gen_check_output(
         await process.wait()
         raise
 
-    if process.returncode != 0:
-        returncode = process.returncode
-        if returncode is None:
-            returncode = 69
+    # A non-optional timeout was supplied to asyncio.wait_for, guaranteeing
+    # a timeout or completed process.  A terminated Python process will have a
+    # non-empty returncode value.
+    assert process.returncode is not None
 
+    if process.returncode != 0:
         cmd_str = " ".join(cmd)
-        raise CalledProcessError(returncode, cmd_str, output=stdout, stderr=stderr)
+        raise CalledProcessError(
+            process.returncode, cmd_str, output=stdout, stderr=stderr
+        )
 
     return (stdout, stderr)
 

From df4dd38a9a2b44c14485948fe8209fa19db2383a Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Tue, 2 Feb 2021 15:54:14 -0800
Subject: [PATCH 0074/1034] Bump bleach from 3.2.1 to 3.3.0 (#1957)

Bumps [bleach](https://github.com/mozilla/bleach) from 3.2.1 to 3.3.0.
- [Release notes](https://github.com/mozilla/bleach/releases)
- [Changelog](https://github.com/mozilla/bleach/blob/master/CHANGES)
- [Commits](https://github.com/mozilla/bleach/compare/v3.2.1...v3.3.0)

Signed-off-by: dependabot[bot] <support@github.com>

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 Pipfile.lock | 219 ++++++++++++++++++++++-----------------------------
 1 file changed, 92 insertions(+), 127 deletions(-)

diff --git a/Pipfile.lock b/Pipfile.lock
index 91fd3a49556..44e987de0e4 100644
--- a/Pipfile.lock
+++ b/Pipfile.lock
@@ -78,7 +78,6 @@
                 "sha256:0c3c816a028d47f659d6ff5c745cb2acf1f966da1fe5c19c77a70282b25f4c5f",
                 "sha256:4291ca197d287d274d0b6cb5d6f8f8f82d434ed288f962539ff18cc9012f9ea3"
             ],
-            "markers": "python_full_version >= '3.5.3'",
             "version": "==3.0.1"
         },
         "attrs": {
@@ -86,7 +85,6 @@
                 "sha256:31b2eced602aa8423c2aea9c76a724617ed67cf9513173fd3a4f03e3a929c7e6",
                 "sha256:832aa3cde19744e49938b91fea06d69ecb9e649c93ba974535d08ad92164f700"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==20.3.0"
         },
         "black": {
@@ -117,17 +115,14 @@
                 "sha256:6988bd2b895eef432d562370bb707d540f32f7360ab13da45340101bc2307d84"
             ],
             "index": "pypi",
-            "python_version <": "3.7",
-            "version": "==0.6",
-            "version >": "0.6"
+            "version": "==0.6"
         },
         "idna": {
             "hashes": [
-                "sha256:b307872f855b18632ce0c21c5e45be78c0ea7ae4c15c828c20788b26921eb3f6",
-                "sha256:b97d804b1e9b523befed77c48dacec60e6dcb0b5391d57af6a65a312a90648c0"
+                "sha256:5205d03e7bcbb919cc9c19885f9920d622ca52448306f2377daede5cf3faac16",
+                "sha256:c5b02147e01ea9920e6b0a3f1f7bb833612d507592c837a6c49552768f4054e1"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==2.10"
+            "version": "==3.1"
         },
         "multidict": {
             "hashes": [
@@ -169,7 +164,6 @@
                 "sha256:f21756997ad8ef815d8ef3d34edd98804ab5ea337feedcd62fb52d22bf531281",
                 "sha256:fc13a9524bc18b6fb6e0dbec3533ba0496bbed167c56d0aabefd965584557d80"
             ],
-            "markers": "python_version >= '3.6'",
             "version": "==5.1.0"
         },
         "mypy-extensions": {
@@ -235,20 +229,6 @@
             "index": "pypi",
             "version": "==2020.11.13"
         },
-        "setuptools-scm": {
-            "hashes": [
-                "sha256:1fc4e25df445351d172bb4788f4d07f9e9ce0e8b7dee6b19584e46110172ca13",
-                "sha256:48b31488d089270500f120efea723968c01abd85fd4876043a3b7c7ef7d0b761",
-                "sha256:62fa535edb31ece9fa65dc9dcb3056145b8020c8c26c0ef1018aef33db95c40d",
-                "sha256:b928021c4381f96d577847d540d6e03065f8f8851c768a0c9bc552d463bae0d4",
-                "sha256:c85b6b46d0edd40d2301038cdea96bb6adc14d62ef943e75afb08b3e7bcf142a",
-                "sha256:db4ab2e0c2644ba71b1e5212b14ff65dbf0af465796d314a75e0cf6128f605f7",
-                "sha256:e878036c2527dfd05818727846338be86b2be6955741b85fab2625f63d001021",
-                "sha256:eb19b46816fc106a4c2d4180022687eab40f9773cf61390b845afb093d1f4ecd"
-            ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
-            "version": "==5.0.1"
-        },
         "toml": {
             "hashes": [
                 "sha256:806143ae5bfb6a3c6e736a764057db0e6a0e05e338b5630894a5f779cabb4f9b",
@@ -300,9 +280,7 @@
                 "sha256:dafc7639cde7f1b6e1acc0f457842a83e722ccca8eef5270af2d74792619a89f"
             ],
             "index": "pypi",
-            "python_version <": "3.8",
-            "version": "==3.7.4.3",
-            "version >=": "3.7.4"
+            "version": "==3.7.4.3"
         },
         "yarl": {
             "hashes": [
@@ -344,7 +322,6 @@
                 "sha256:f0b059678fd549c66b89bed03efcabb009075bd131c248ecdf087bdb6faba24a",
                 "sha256:fcbb48a93e8699eae920f8d92f7160c03567b421bc17362a9ffbbd706a816f71"
             ],
-            "markers": "python_version >= '3.6'",
             "version": "==1.6.3"
         }
     },
@@ -420,7 +397,6 @@
                 "sha256:0c3c816a028d47f659d6ff5c745cb2acf1f966da1fe5c19c77a70282b25f4c5f",
                 "sha256:4291ca197d287d274d0b6cb5d6f8f8f82d434ed288f962539ff18cc9012f9ea3"
             ],
-            "markers": "python_full_version >= '3.5.3'",
             "version": "==3.0.1"
         },
         "attrs": {
@@ -428,7 +404,6 @@
                 "sha256:31b2eced602aa8423c2aea9c76a724617ed67cf9513173fd3a4f03e3a929c7e6",
                 "sha256:832aa3cde19744e49938b91fea06d69ecb9e649c93ba974535d08ad92164f700"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==20.3.0"
         },
         "babel": {
@@ -436,7 +411,6 @@
                 "sha256:9d35c22fcc79893c3ecc85ac4a56cde1ecf3f19c540bba0922308a6c06ca6fa5",
                 "sha256:da031ab54472314f210b0adcff1588ee5d1d1d0ba4dbd07b94dba82bde791e05"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==2.9.0"
         },
         "black": {
@@ -448,11 +422,11 @@
         },
         "bleach": {
             "hashes": [
-                "sha256:52b5919b81842b1854196eaae5ca29679a2f2e378905c346d3ca8227c2c66080",
-                "sha256:9f8ccbeb6183c6e6cddea37592dfb0167485c1e3b13b3363bc325aa8bda3adbd"
+                "sha256:6123ddc1052673e52bab52cdc955bcb57a015264a1c57d37bea2f6b817af0125",
+                "sha256:98b3170739e5e83dd9dc19633f074727ad848cbedb6026708c8ac2d3b697a433"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
-            "version": "==3.2.1"
+            "index": "pypi",
+            "version": "==3.3.0"
         },
         "certifi": {
             "hashes": [
@@ -479,6 +453,7 @@
                 "sha256:6bc25fc545a6b3d57b5f8618e59fc13d3a3a68431e8ca5fd4c13241cd70d0009",
                 "sha256:798caa2a2384b1cbe8a2a139d80734c9db54f9cc155c99d7cc92441a23871c03",
                 "sha256:7c6b1dece89874d9541fc974917b631406233ea0440d0bdfbb8e03bf39a49b3b",
+                "sha256:7ef7d4ced6b325e92eb4d3502946c78c5367bc416398d387b39591532536734e",
                 "sha256:840793c68105fe031f34d6a086eaea153a0cd5c491cde82a74b420edd0a2b909",
                 "sha256:8d6603078baf4e11edc4168a514c5ce5b3ba6e3e9c374298cb88437957960a53",
                 "sha256:9cc46bc107224ff5b6d04369e7c595acb700c3613ad7bcf2e2012f62ece80c35",
@@ -507,7 +482,6 @@
                 "sha256:32e43d604bbe7896fe7c248a9c2276447dbef840feb28fe20494f62af110211d",
                 "sha256:cf22deb93d4bcf92f345a5c3cd39d3d41d6340adc60c78bbbd6588c384fda6a1"
             ],
-            "markers": "python_full_version >= '3.6.1'",
             "version": "==3.2.0"
         },
         "chardet": {
@@ -530,7 +504,6 @@
                 "sha256:5941b2b48a20143d2267e95b1c2a7603ce057ee39fd88e7329b0c292aa16869b",
                 "sha256:9f47eda37229f68eee03b24b9748937c7dc3868f906e8ba69fbcbdd3bc5dc3e2"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
             "version": "==0.4.4"
         },
         "commonmark": {
@@ -612,7 +585,6 @@
                 "sha256:c366df0401d1ec4e548bebe8f91d55ebcc0ec3137900d214dd7aac8427ef3030",
                 "sha256:dc42f645f8f3a489c3dd416730a514e7a91a59510ddaadc09d04224c098d3302"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4, 3.5'",
             "version": "==3.3.1"
         },
         "distlib": {
@@ -625,7 +597,6 @@
         "docutils": {
             "hashes": [
                 "sha256:54a349c622ff31c91cbec43b0b512f113b5b24daf00e2ea530bb1bd9aac14849",
-                "sha256:ba4584f9107571ced0d2c7f56a5499c696215ba90797849c92d395979da68521",
                 "sha256:d2ddba74835cb090a1b627d3de4e7835c628d07ee461f7b4480f51af2fe4d448"
             ],
             "index": "pypi",
@@ -656,26 +627,23 @@
         },
         "identify": {
             "hashes": [
-                "sha256:943cd299ac7f5715fcb3f684e2fc1594c1e0f22a90d15398e5888143bd4144b5",
-                "sha256:cc86e6a9a390879dcc2976cef169dd9cc48843ed70b7380f321d1b118163c60e"
+                "sha256:70b638cf4743f33042bebb3b51e25261a0a10e80f978739f17e7fd4837664a66",
+                "sha256:9dfb63a2e871b807e3ba62f029813552a24b5289504f5b071dea9b041aee9fe4"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==1.5.10"
+            "version": "==1.5.13"
         },
         "idna": {
             "hashes": [
-                "sha256:b307872f855b18632ce0c21c5e45be78c0ea7ae4c15c828c20788b26921eb3f6",
-                "sha256:b97d804b1e9b523befed77c48dacec60e6dcb0b5391d57af6a65a312a90648c0"
+                "sha256:5205d03e7bcbb919cc9c19885f9920d622ca52448306f2377daede5cf3faac16",
+                "sha256:c5b02147e01ea9920e6b0a3f1f7bb833612d507592c837a6c49552768f4054e1"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==2.10"
+            "version": "==3.1"
         },
         "imagesize": {
             "hashes": [
                 "sha256:6965f19a6a2039c7d48bca7dba2473069ff854c36ae6f19d2cde309d998228a1",
                 "sha256:b1f6b5a4eab1f73479a50fb79fcf729514a900c341d8503d62a62dbc4127a2b1"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==1.2.0"
         },
         "jeepney": {
@@ -688,19 +656,17 @@
         },
         "jinja2": {
             "hashes": [
-                "sha256:89aab215427ef59c34ad58735269eb58b1a5808103067f7bb9d5836c651b3bb0",
-                "sha256:f0a4641d3cf955324a89c04f3d94663aa4d638abe8f733ecd3582848e1c37035"
+                "sha256:03e47ad063331dd6a3f04a43eddca8a966a26ba0c5b7207a9a9e4e08f1b29419",
+                "sha256:a6d58433de0ae800347cab1fa3043cebbabe8baa9d29e668f1c768cb87a333c6"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
-            "version": "==2.11.2"
+            "version": "==2.11.3"
         },
         "keyring": {
             "hashes": [
-                "sha256:1746d3ac913d449a090caf11e9e4af00e26c3f7f7e81027872192b2398b98675",
-                "sha256:4be9cbaaaf83e61d6399f733d113ede7d1c73bc75cb6aeb64eee0f6ac39b30ea"
+                "sha256:9acb3e1452edbb7544822b12fd25459078769e560fa51f418b6d00afaa6178df",
+                "sha256:9f44660a5d4931bdc14c08a1d01ef30b18a7a8147380710d8c9f9531e1f6c3c0"
             ],
-            "markers": "python_version >= '3.6'",
-            "version": "==21.8.0"
+            "version": "==22.0.1"
         },
         "markupsafe": {
             "hashes": [
@@ -709,8 +675,12 @@
                 "sha256:09c4b7f37d6c648cb13f9230d847adf22f8171b1ccc4d5682398e77f40309235",
                 "sha256:1027c282dad077d0bae18be6794e6b6b8c91d58ed8a8d89a89d59693b9131db5",
                 "sha256:13d3144e1e340870b25e7b10b98d779608c02016d5184cfb9927a9f10c689f42",
+                "sha256:195d7d2c4fbb0ee8139a6cf67194f3973a6b3042d742ebe0a9ed36d8b6f0c07f",
+                "sha256:22c178a091fc6630d0d045bdb5992d2dfe14e3259760e713c490da5323866c39",
                 "sha256:24982cc2533820871eba85ba648cd53d8623687ff11cbb805be4ff7b4c971aff",
                 "sha256:29872e92839765e546828bb7754a68c418d927cd064fd4708fab9fe9c8bb116b",
+                "sha256:2beec1e0de6924ea551859edb9e7679da6e4870d32cb766240ce17e0a0ba2014",
+                "sha256:3b8a6499709d29c2e2399569d96719a1b21dcd94410a586a18526b143ec8470f",
                 "sha256:43a55c2930bbc139570ac2452adf3d70cdbb3cfe5912c71cdce1c2c6bbd9c5d1",
                 "sha256:46c99d2de99945ec5cb54f23c8cd5689f6d7177305ebff350a58ce5f8de1669e",
                 "sha256:500d4957e52ddc3351cabf489e79c91c17f6e0899158447047588650b5e69183",
@@ -719,26 +689,40 @@
                 "sha256:62fe6c95e3ec8a7fad637b7f3d372c15ec1caa01ab47926cfdf7a75b40e0eac1",
                 "sha256:6788b695d50a51edb699cb55e35487e430fa21f1ed838122d722e0ff0ac5ba15",
                 "sha256:6dd73240d2af64df90aa7c4e7481e23825ea70af4b4922f8ede5b9e35f78a3b1",
+                "sha256:6f1e273a344928347c1290119b493a1f0303c52f5a5eae5f16d74f48c15d4a85",
+                "sha256:6fffc775d90dcc9aed1b89219549b329a9250d918fd0b8fa8d93d154918422e1",
                 "sha256:717ba8fe3ae9cc0006d7c451f0bb265ee07739daf76355d06366154ee68d221e",
                 "sha256:79855e1c5b8da654cf486b830bd42c06e8780cea587384cf6545b7d9ac013a0b",
                 "sha256:7c1699dfe0cf8ff607dbdcc1e9b9af1755371f92a68f706051cc8c37d447c905",
+                "sha256:7fed13866cf14bba33e7176717346713881f56d9d2bcebab207f7a036f41b850",
+                "sha256:84dee80c15f1b560d55bcfe6d47b27d070b4681c699c572af2e3c7cc90a3b8e0",
                 "sha256:88e5fcfb52ee7b911e8bb6d6aa2fd21fbecc674eadd44118a9cc3863f938e735",
                 "sha256:8defac2f2ccd6805ebf65f5eeb132adcf2ab57aa11fdf4c0dd5169a004710e7d",
+                "sha256:98bae9582248d6cf62321dcb52aaf5d9adf0bad3b40582925ef7c7f0ed85fceb",
                 "sha256:98c7086708b163d425c67c7a91bad6e466bb99d797aa64f965e9d25c12111a5e",
                 "sha256:9add70b36c5666a2ed02b43b335fe19002ee5235efd4b8a89bfcf9005bebac0d",
                 "sha256:9bf40443012702a1d2070043cb6291650a0841ece432556f784f004937f0f32c",
+                "sha256:a6a744282b7718a2a62d2ed9d993cad6f5f585605ad352c11de459f4108df0a1",
+                "sha256:acf08ac40292838b3cbbb06cfe9b2cb9ec78fce8baca31ddb87aaac2e2dc3bc2",
                 "sha256:ade5e387d2ad0d7ebf59146cc00c8044acbd863725f887353a10df825fc8ae21",
                 "sha256:b00c1de48212e4cc9603895652c5c410df699856a2853135b3967591e4beebc2",
                 "sha256:b1282f8c00509d99fef04d8ba936b156d419be841854fe901d8ae224c59f0be5",
+                "sha256:b1dba4527182c95a0db8b6060cc98ac49b9e2f5e64320e2b56e47cb2831978c7",
                 "sha256:b2051432115498d3562c084a49bba65d97cf251f5a331c64a12ee7e04dacc51b",
+                "sha256:b7d644ddb4dbd407d31ffb699f1d140bc35478da613b441c582aeb7c43838dd8",
                 "sha256:ba59edeaa2fc6114428f1637ffff42da1e311e29382d81b339c1817d37ec93c6",
+                "sha256:bf5aa3cbcfdf57fa2ee9cd1822c862ef23037f5c832ad09cfea57fa846dec193",
                 "sha256:c8716a48d94b06bb3b2524c2b77e055fb313aeb4ea620c8dd03a105574ba704f",
+                "sha256:caabedc8323f1e93231b52fc32bdcde6db817623d33e100708d9a68e1f53b26b",
                 "sha256:cd5df75523866410809ca100dc9681e301e3c27567cf498077e8551b6d20e42f",
                 "sha256:cdb132fc825c38e1aeec2c8aa9338310d29d337bebbd7baa06889d09a60a1fa2",
+                "sha256:d53bc011414228441014aa71dbec320c66468c1030aae3a6e29778a3382d96e5",
+                "sha256:d73a845f227b0bfe8a7455ee623525ee656a9e2e749e4742706d80a6065d5e2c",
+                "sha256:d9be0ba6c527163cbed5e0857c451fcd092ce83947944d6c14bc95441203f032",
                 "sha256:e249096428b3ae81b08327a63a485ad0878de3fb939049038579ac0ef61e17e7",
-                "sha256:e8313f01ba26fbbe36c7be1966a7b7424942f670f38e666995b88d012765b9be"
+                "sha256:e8313f01ba26fbbe36c7be1966a7b7424942f670f38e666995b88d012765b9be",
+                "sha256:feb7b34d6325451ef96bc0e36e1a6c0c1c64bc1fbec4b854f4529e51887b1621"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==1.1.1"
         },
         "mccabe": {
@@ -788,7 +772,6 @@
                 "sha256:f21756997ad8ef815d8ef3d34edd98804ab5ea337feedcd62fb52d22bf531281",
                 "sha256:fc13a9524bc18b6fb6e0dbec3533ba0496bbed167c56d0aabefd965584557d80"
             ],
-            "markers": "python_version >= '3.6'",
             "version": "==5.1.0"
         },
         "mypy": {
@@ -828,11 +811,10 @@
         },
         "packaging": {
             "hashes": [
-                "sha256:24e0da08660a87484d1602c30bb4902d74816b6985b93de36926f5bc95741858",
-                "sha256:78598185a7008a470d64526a8059de9aaa449238f280fc9eb6b13ba6c4109093"
+                "sha256:5b327ac1320dc863dca72f4514ecc086f31186744b84a230374cc1fd776feae5",
+                "sha256:67714da7f7bc052e064859c05c595155bd1ee9f69f76557e21f051443c20947a"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==20.8"
+            "version": "==20.9"
         },
         "pathspec": {
             "hashes": [
@@ -844,10 +826,10 @@
         },
         "pkginfo": {
             "hashes": [
-                "sha256:a6a4ac943b496745cec21f14f021bbd869d5e9b4f6ec06918cffea5a2f4b9193",
-                "sha256:ce14d7296c673dc4c61c759a0b6c14bae34e34eb819c0017bb6ca5b7292c56e9"
+                "sha256:029a70cb45c6171c329dfc890cde0879f8c52d6f3922794796e06f577bb03db4",
+                "sha256:9fdbea6495622e022cc72c2e5e1b735218e4ffb2a2a69cde2694a6c1f16afb75"
             ],
-            "version": "==1.6.1"
+            "version": "==1.7.0"
         },
         "pre-commit": {
             "hashes": [
@@ -862,7 +844,6 @@
                 "sha256:2295e7b2f6b5bd100585ebcb1f616591b652db8a741695b3d8f5d28bdc934367",
                 "sha256:c58a7d2815e0e8d7972bf1803331fb0152f867bd89adf8a01dfd55085434192e"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==2.6.0"
         },
         "pycparser": {
@@ -870,7 +851,6 @@
                 "sha256:2d475327684562c3a96cc71adf7dc8c4f0565175cf86b6d7a404ff4c771f15f0",
                 "sha256:7582ad22678f0fcd81102833f60ef8d0e57288b6b5fb00323d101be910e35705"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==2.20"
         },
         "pyflakes": {
@@ -878,49 +858,54 @@
                 "sha256:0d94e0e05a19e57a99444b6ddcf9a6eb2e5c68d3ca1e98e90707af8152c90a92",
                 "sha256:35b2d75ee967ea93b55750aa9edbbf72813e06a66ba54438df2cfac9e3c27fc8"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==2.2.0"
         },
         "pygments": {
             "hashes": [
-                "sha256:ccf3acacf3782cbed4a989426012f1c535c9a90d3a7fc3f16d231b9372d2b716",
-                "sha256:f275b6c0909e5dafd2d6269a656aa90fa58ebf4a74f8fcf9053195d226b24a08"
+                "sha256:bc9591213a8f0e0ca1a5e68a479b4887fdc3e75d0774e5c71c31920c427de435",
+                "sha256:df49d09b498e83c1a73128295860250b0b7edd4c723a32e9bc0d295c7c2ec337"
             ],
-            "markers": "python_version >= '3.5'",
-            "version": "==2.7.3"
+            "version": "==2.7.4"
         },
         "pyparsing": {
             "hashes": [
                 "sha256:c203ec8783bf771a155b207279b9bccb8dea02d8f0c9e5f8ead507bc3246ecc1",
                 "sha256:ef9d7589ef3c200abe66653d3f1ab1033c3c419ae9b9bdb1240a85b024efc88b"
             ],
-            "markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==2.4.7"
         },
         "pytz": {
             "hashes": [
-                "sha256:16962c5fb8db4a8f63a26646d8886e9d769b6c511543557bc84e9569fb9a9cb4",
-                "sha256:180befebb1927b16f6b57101720075a984c019ac16b1b7575673bea42c6c3da5"
+                "sha256:83a4a90894bf38e243cf052c8b58f381bfe9a7a483f6a9cab140bc7f702ac4da",
+                "sha256:eb10ce3e7736052ed3623d49975ce333bcd712c7bb19a58b9e2089d4057d0798"
             ],
-            "version": "==2020.5"
+            "version": "==2021.1"
         },
         "pyyaml": {
             "hashes": [
-                "sha256:06a0d7ba600ce0b2d2fe2e78453a470b5a6e000a985dd4a4e54e436cc36b0e97",
-                "sha256:240097ff019d7c70a4922b6869d8a86407758333f02203e0fc6ff79c5dcede76",
-                "sha256:4f4b913ca1a7319b33cfb1369e91e50354d6f07a135f3b901aca02aa95940bd2",
-                "sha256:6034f55dab5fea9e53f436aa68fa3ace2634918e8b5994d82f3621c04ff5ed2e",
-                "sha256:69f00dca373f240f842b2931fb2c7e14ddbacd1397d57157a9b005a6a9942648",
-                "sha256:73f099454b799e05e5ab51423c7bcf361c58d3206fa7b0d555426b1f4d9a3eaf",
-                "sha256:74809a57b329d6cc0fdccee6318f44b9b8649961fa73144a98735b0aaf029f1f",
-                "sha256:7739fc0fa8205b3ee8808aea45e968bc90082c10aef6ea95e855e10abf4a37b2",
-                "sha256:95f71d2af0ff4227885f7a6605c37fd53d3a106fcab511b8860ecca9fcf400ee",
-                "sha256:ad9c67312c84def58f3c04504727ca879cb0013b2517c85a9a253f0cb6380c0a",
-                "sha256:b8eac752c5e14d3eca0e6dd9199cd627518cb5ec06add0de9d32baeee6fe645d",
-                "sha256:cc8955cfbfc7a115fa81d85284ee61147059a753344bc51098f3ccd69b0d7e0c",
-                "sha256:d13155f591e6fcc1ec3b30685d50bf0711574e2c0dfffd7644babf8b5102ca1a"
-            ],
-            "version": "==5.3.1"
+                "sha256:08682f6b72c722394747bddaf0aa62277e02557c0fd1c42cb853016a38f8dedf",
+                "sha256:0f5f5786c0e09baddcd8b4b45f20a7b5d61a7e7e99846e3c799b05c7c53fa696",
+                "sha256:129def1b7c1bf22faffd67b8f3724645203b79d8f4cc81f674654d9902cb4393",
+                "sha256:294db365efa064d00b8d1ef65d8ea2c3426ac366c0c4368d930bf1c5fb497f77",
+                "sha256:3b2b1824fe7112845700f815ff6a489360226a5609b96ec2190a45e62a9fc922",
+                "sha256:3bd0e463264cf257d1ffd2e40223b197271046d09dadf73a0fe82b9c1fc385a5",
+                "sha256:4465124ef1b18d9ace298060f4eccc64b0850899ac4ac53294547536533800c8",
+                "sha256:49d4cdd9065b9b6e206d0595fee27a96b5dd22618e7520c33204a4a3239d5b10",
+                "sha256:4e0583d24c881e14342eaf4ec5fbc97f934b999a6828693a99157fde912540cc",
+                "sha256:5accb17103e43963b80e6f837831f38d314a0495500067cb25afab2e8d7a4018",
+                "sha256:607774cbba28732bfa802b54baa7484215f530991055bb562efbed5b2f20a45e",
+                "sha256:6c78645d400265a062508ae399b60b8c167bf003db364ecb26dcab2bda048253",
+                "sha256:74c1485f7707cf707a7aef42ef6322b8f97921bd89be2ab6317fd782c2d53183",
+                "sha256:8c1be557ee92a20f184922c7b6424e8ab6691788e6d86137c5d93c1a6ec1b8fb",
+                "sha256:bb4191dfc9306777bc594117aee052446b3fa88737cd13b7188d0e7aa8162185",
+                "sha256:c20cfa2d49991c8b4147af39859b167664f2ad4561704ee74c1de03318e898db",
+                "sha256:d2d9808ea7b4af864f35ea216be506ecec180628aced0704e34aca0b040ffe46",
+                "sha256:dd5de0646207f053eb0d6c74ae45ba98c3395a571a2891858e87df7c9b9bd51b",
+                "sha256:e1d4970ea66be07ae37a3c2e48b5ec63f7ba6804bdddfdbd3cfd954d25a82e63",
+                "sha256:e4fac90784481d221a8e4b1162afa7c47ed953be40d31ab4629ae917510051df",
+                "sha256:fa5ae20527d8e831e8230cbffd9f8fe952815b2b7dae6ffec25318803a7528fc"
+            ],
+            "version": "==5.4.1"
         },
         "readme-renderer": {
             "hashes": [
@@ -990,7 +975,6 @@
                 "sha256:27973dd4a904a4f13b263a19c866c13b92a39ed1c964655f025f3f8d3d75b804",
                 "sha256:c210084e36a42ae6b9219e00e48287def368a26d03a048ddad7bfee44f75871e"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
             "version": "==2.25.1"
         },
         "requests-toolbelt": {
@@ -1017,16 +1001,10 @@
         },
         "setuptools-scm": {
             "hashes": [
-                "sha256:1fc4e25df445351d172bb4788f4d07f9e9ce0e8b7dee6b19584e46110172ca13",
-                "sha256:48b31488d089270500f120efea723968c01abd85fd4876043a3b7c7ef7d0b761",
                 "sha256:62fa535edb31ece9fa65dc9dcb3056145b8020c8c26c0ef1018aef33db95c40d",
-                "sha256:b928021c4381f96d577847d540d6e03065f8f8851c768a0c9bc552d463bae0d4",
-                "sha256:c85b6b46d0edd40d2301038cdea96bb6adc14d62ef943e75afb08b3e7bcf142a",
-                "sha256:db4ab2e0c2644ba71b1e5212b14ff65dbf0af465796d314a75e0cf6128f605f7",
-                "sha256:e878036c2527dfd05818727846338be86b2be6955741b85fab2625f63d001021",
-                "sha256:eb19b46816fc106a4c2d4180022687eab40f9773cf61390b845afb093d1f4ecd"
+                "sha256:c85b6b46d0edd40d2301038cdea96bb6adc14d62ef943e75afb08b3e7bcf142a"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
+            "index": "pypi",
             "version": "==5.0.1"
         },
         "six": {
@@ -1034,15 +1012,14 @@
                 "sha256:30639c035cdb23534cd4aa2dd52c3bf48f06e5f4a941509c8bafd8ce11080259",
                 "sha256:8b74bedcbbbaca38ff6d7491d76f2b06b3592611af620f8426e82dddb04a5ced"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==1.15.0"
         },
         "snowballstemmer": {
             "hashes": [
-                "sha256:209f257d7533fdb3cb73bdbd24f436239ca3b2fa67d56f6ff88e86be08cc5ef0",
-                "sha256:df3bac3df4c2c01363f3dd2cfa78cce2840a79b9f1c2d2de9ce8d31683992f52"
+                "sha256:b51b447bea85f9968c13b650126a888aabd4cb4463fca868ec596826325dedc2",
+                "sha256:e997baa4f2e9139951b6f4c631bad912dfd3c792467e2f03d7239464af90e914"
             ],
-            "version": "==2.0.0"
+            "version": "==2.1.0"
         },
         "sphinx": {
             "hashes": [
@@ -1057,7 +1034,6 @@
                 "sha256:806111e5e962be97c29ec4c1e7fe277bfd19e9652fb1a4392105b43e01af885a",
                 "sha256:a072735ec80e7675e3f432fcae8610ecf509c5f1869d17e2eecff44389cdbc58"
             ],
-            "markers": "python_version >= '3.5'",
             "version": "==1.0.2"
         },
         "sphinxcontrib-devhelp": {
@@ -1065,7 +1041,6 @@
                 "sha256:8165223f9a335cc1af7ffe1ed31d2871f325254c0423bc0c4c7cd1c1e4734a2e",
                 "sha256:ff7f1afa7b9642e7060379360a67e9c41e8f3121f2ce9164266f61b9f4b338e4"
             ],
-            "markers": "python_version >= '3.5'",
             "version": "==1.0.2"
         },
         "sphinxcontrib-htmlhelp": {
@@ -1073,7 +1048,6 @@
                 "sha256:3c0bc24a2c41e340ac37c85ced6dafc879ab485c095b1d65d2461ac2f7cca86f",
                 "sha256:e8f5bb7e31b2dbb25b9cc435c8ab7a79787ebf7f906155729338f3156d93659b"
             ],
-            "markers": "python_version >= '3.5'",
             "version": "==1.0.3"
         },
         "sphinxcontrib-jsmath": {
@@ -1081,7 +1055,6 @@
                 "sha256:2ec2eaebfb78f3f2078e73666b1415417a116cc848b72e5172e596c871103178",
                 "sha256:a9925e4a4587247ed2191a22df5f6970656cb8ca2bd6284309578f2153e0c4b8"
             ],
-            "markers": "python_version >= '3.5'",
             "version": "==1.0.1"
         },
         "sphinxcontrib-qthelp": {
@@ -1089,7 +1062,6 @@
                 "sha256:4c33767ee058b70dba89a6fc5c1892c0d57a54be67ddd3e7875a18d14cba5a72",
                 "sha256:bd9fc24bcb748a8d51fd4ecaade681350aa63009a347a8c14e637895444dfab6"
             ],
-            "markers": "python_version >= '3.5'",
             "version": "==1.0.3"
         },
         "sphinxcontrib-serializinghtml": {
@@ -1097,7 +1069,6 @@
                 "sha256:eaa0eccc86e982a9b939b2b82d12cc5d013385ba5eadcc7e4fed23f4405f77bc",
                 "sha256:f242a81d423f59617a8e5cf16f5d4d74e28ee9a66f9e5b637a18082991db5a9a"
             ],
-            "markers": "python_version >= '3.5'",
             "version": "==1.1.4"
         },
         "toml": {
@@ -1110,11 +1081,10 @@
         },
         "tqdm": {
             "hashes": [
-                "sha256:0cd81710de29754bf17b6fee07bdb86f956b4fa20d3078f02040f83e64309416",
-                "sha256:f4f80b96e2ceafea69add7bf971b8403b9cba8fb4451c1220f91c79be4ebd208"
+                "sha256:4621f6823bab46a9cc33d48105753ccbea671b68bab2c50a9f0be23d4065cb5a",
+                "sha256:fe3d08dd00a526850568d542ff9de9bbc2a09a791da3c334f3213d8d0bbbca65"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==4.55.0"
+            "version": "==4.56.0"
         },
         "twine": {
             "hashes": [
@@ -1167,25 +1137,21 @@
                 "sha256:dafc7639cde7f1b6e1acc0f457842a83e722ccca8eef5270af2d74792619a89f"
             ],
             "index": "pypi",
-            "python_version <": "3.8",
-            "version": "==3.7.4.3",
-            "version >=": "3.7.4"
+            "version": "==3.7.4.3"
         },
         "urllib3": {
             "hashes": [
-                "sha256:19188f96923873c92ccb987120ec4acaa12f0461fa9ce5d3d0772bc965a39e08",
-                "sha256:d8ff90d979214d7b4f8ce956e80f4028fc6860e4431f731ea4a8c08f23f99473"
+                "sha256:1b465e494e3e0d8939b50680403e3aedaa2bc434b7d5af64dfd3c958d7f5ae80",
+                "sha256:de3eedaad74a2683334e282005cd8d7f22f4d55fa690a2a1020a416cb0a47e73"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4' and python_version < '4'",
-            "version": "==1.26.2"
+            "version": "==1.26.3"
         },
         "virtualenv": {
             "hashes": [
-                "sha256:54b05fc737ea9c9ee9f8340f579e5da5b09fb64fd010ab5757eb90268616907c",
-                "sha256:b7a8ec323ee02fb2312f098b6b4c9de99559b462775bc8fe3627a73706603c1b"
+                "sha256:147b43894e51dd6bba882cf9c282447f780e2251cd35172403745fc381a0a80d",
+                "sha256:2be72df684b74df0ea47679a7df93fd0e04e72520022c57b479d8f881485dbe3"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==20.2.2"
+            "version": "==20.4.2"
         },
         "webencodings": {
             "hashes": [
@@ -1242,7 +1208,6 @@
                 "sha256:f0b059678fd549c66b89bed03efcabb009075bd131c248ecdf087bdb6faba24a",
                 "sha256:fcbb48a93e8699eae920f8d92f7160c03567b421bc17362a9ffbbd706a816f71"
             ],
-            "markers": "python_version >= '3.6'",
             "version": "==1.6.3"
         }
     }

From 3fca540d05a0f0b4480cfcce84d7e0392270b841 Mon Sep 17 00:00:00 2001
From: Anthony Sottile <asottile@umich.edu>
Date: Thu, 4 Feb 2021 13:03:42 -0800
Subject: [PATCH 0075/1034] speed up cache by approximately 42x by avoiding
 pathlib (#1953)

---
 CHANGES.md            |  2 ++
 src/black/__init__.py | 14 +++++++++-----
 tests/test_black.py   | 39 +++++++++++++++++++++------------------
 3 files changed, 32 insertions(+), 23 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index ca8a0472a3b..5f7ca4f4da7 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -26,6 +26,8 @@
 
 - use lowercase hex strings (#1692)
 
+- speed up caching by avoiding pathlib (#1950)
+
 #### _Packaging_
 
 - Self-contained native _Black_ binaries are now provided for releases via GitHub
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 9034bf6cf77..7c1a013aae3 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -93,7 +93,7 @@
 Timestamp = float
 FileSize = int
 CacheInfo = Tuple[Timestamp, FileSize]
-Cache = Dict[Path, CacheInfo]
+Cache = Dict[str, CacheInfo]
 out = partial(click.secho, bold=True, err=True)
 err = partial(click.secho, fg="red", err=True)
 
@@ -724,7 +724,8 @@ def reformat_one(
             if write_back not in (WriteBack.DIFF, WriteBack.COLOR_DIFF):
                 cache = read_cache(mode)
                 res_src = src.resolve()
-                if res_src in cache and cache[res_src] == get_cache_info(res_src):
+                res_src_s = str(res_src)
+                if res_src_s in cache and cache[res_src_s] == get_cache_info(res_src):
                     changed = Changed.CACHED
             if changed is not Changed.CACHED and format_file_in_place(
                 src, fast=fast, write_back=write_back, mode=mode
@@ -6781,8 +6782,8 @@ def filter_cached(cache: Cache, sources: Iterable[Path]) -> Tuple[Set[Path], Set
     """
     todo, done = set(), set()
     for src in sources:
-        src = src.resolve()
-        if cache.get(src) != get_cache_info(src):
+        res_src = src.resolve()
+        if cache.get(str(res_src)) != get_cache_info(res_src):
             todo.add(src)
         else:
             done.add(src)
@@ -6794,7 +6795,10 @@ def write_cache(cache: Cache, sources: Iterable[Path], mode: Mode) -> None:
     cache_file = get_cache_file(mode)
     try:
         CACHE_DIR.mkdir(parents=True, exist_ok=True)
-        new_cache = {**cache, **{src.resolve(): get_cache_info(src) for src in sources}}
+        new_cache = {
+            **cache,
+            **{str(src.resolve()): get_cache_info(src) for src in sources},
+        }
         with tempfile.NamedTemporaryFile(dir=str(cache_file.parent), delete=False) as f:
             pickle.dump(new_cache, f, protocol=4)
         os.replace(f.name, cache_file)
diff --git a/tests/test_black.py b/tests/test_black.py
index 28b75787bd6..cfd3cbd91b3 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -1003,7 +1003,7 @@ def test_cache_broken_file(self) -> None:
                 fobj.write("print('hello')")
             self.invokeBlack([str(src)])
             cache = black.read_cache(mode)
-            self.assertIn(src, cache)
+            self.assertIn(str(src), cache)
 
     def test_cache_single_file_already_cached(self) -> None:
         mode = DEFAULT_MODE
@@ -1035,8 +1035,8 @@ def test_cache_multiple_files(self) -> None:
             with two.open("r") as fobj:
                 self.assertEqual(fobj.read(), 'print("hello")\n')
             cache = black.read_cache(mode)
-            self.assertIn(one, cache)
-            self.assertIn(two, cache)
+            self.assertIn(str(one), cache)
+            self.assertIn(str(two), cache)
 
     def test_no_cache_when_writeback_diff(self) -> None:
         mode = DEFAULT_MODE
@@ -1116,8 +1116,8 @@ def test_write_cache_read_cache(self) -> None:
             src.touch()
             black.write_cache({}, [src], mode)
             cache = black.read_cache(mode)
-            self.assertIn(src, cache)
-            self.assertEqual(cache[src], black.get_cache_info(src))
+            self.assertIn(str(src), cache)
+            self.assertEqual(cache[str(src)], black.get_cache_info(src))
 
     def test_filter_cached(self) -> None:
         with TemporaryDirectory() as workspace:
@@ -1128,7 +1128,10 @@ def test_filter_cached(self) -> None:
             uncached.touch()
             cached.touch()
             cached_but_changed.touch()
-            cache = {cached: black.get_cache_info(cached), cached_but_changed: (0.0, 0)}
+            cache = {
+                str(cached): black.get_cache_info(cached),
+                str(cached_but_changed): (0.0, 0),
+            }
             todo, done = black.filter_cached(
                 cache, {uncached, cached, cached_but_changed}
             )
@@ -1156,8 +1159,8 @@ def test_failed_formatting_does_not_get_cached(self) -> None:
                 fobj.write('print("hello")\n')
             self.invokeBlack([str(workspace)], exit_code=123)
             cache = black.read_cache(mode)
-            self.assertNotIn(failing, cache)
-            self.assertIn(clean, cache)
+            self.assertNotIn(str(failing), cache)
+            self.assertIn(str(clean), cache)
 
     def test_write_cache_write_fail(self) -> None:
         mode = DEFAULT_MODE
@@ -1210,9 +1213,9 @@ def test_read_cache_line_lengths(self) -> None:
             path.touch()
             black.write_cache({}, [path], mode)
             one = black.read_cache(mode)
-            self.assertIn(path, one)
+            self.assertIn(str(path), one)
             two = black.read_cache(short_mode)
-            self.assertNotIn(path, two)
+            self.assertNotIn(str(path), two)
 
     def test_single_file_force_pyi(self) -> None:
         pyi_mode = replace(DEFAULT_MODE, is_pyi=True)
@@ -1226,9 +1229,9 @@ def test_single_file_force_pyi(self) -> None:
                 actual = fh.read()
             # verify cache with --pyi is separate
             pyi_cache = black.read_cache(pyi_mode)
-            self.assertIn(path, pyi_cache)
+            self.assertIn(str(path), pyi_cache)
             normal_cache = black.read_cache(DEFAULT_MODE)
-            self.assertNotIn(path, normal_cache)
+            self.assertNotIn(str(path), normal_cache)
         self.assertFormatEqual(expected, actual)
         black.assert_equivalent(contents, actual)
         black.assert_stable(contents, actual, pyi_mode)
@@ -1255,8 +1258,8 @@ def test_multi_file_force_pyi(self) -> None:
             pyi_cache = black.read_cache(pyi_mode)
             normal_cache = black.read_cache(reg_mode)
             for path in paths:
-                self.assertIn(path, pyi_cache)
-                self.assertNotIn(path, normal_cache)
+                self.assertIn(str(path), pyi_cache)
+                self.assertNotIn(str(path), normal_cache)
 
     def test_pipe_force_pyi(self) -> None:
         source, expected = read_data("force_pyi")
@@ -1280,9 +1283,9 @@ def test_single_file_force_py36(self) -> None:
                 actual = fh.read()
             # verify cache with --target-version is separate
             py36_cache = black.read_cache(py36_mode)
-            self.assertIn(path, py36_cache)
+            self.assertIn(str(path), py36_cache)
             normal_cache = black.read_cache(reg_mode)
-            self.assertNotIn(path, normal_cache)
+            self.assertNotIn(str(path), normal_cache)
         self.assertEqual(actual, expected)
 
     @event_loop()
@@ -1307,8 +1310,8 @@ def test_multi_file_force_py36(self) -> None:
             pyi_cache = black.read_cache(py36_mode)
             normal_cache = black.read_cache(reg_mode)
             for path in paths:
-                self.assertIn(path, pyi_cache)
-                self.assertNotIn(path, normal_cache)
+                self.assertIn(str(path), pyi_cache)
+                self.assertNotIn(str(path), normal_cache)
 
     def test_pipe_force_py36(self) -> None:
         source, expected = read_data("force_py36")

From aebd3c37b28bbc0183a58d13b80e7595db3c09bb Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Thu, 4 Feb 2021 23:10:45 -0500
Subject: [PATCH 0076/1034] Update prettier in pre-commit config (#1966)

With older versions of prettier, when the hook failed a bunch of
"[error] No parser could be inferred for file: {PATH}" error lines
showed up because of lack of support of a flag that pre-commit
passes for us by default. It made figuring out why the prettier hook
failed annoying.
---
 .pre-commit-config.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 9955a24baf8..292ed5727d9 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -25,7 +25,7 @@ repos:
         exclude: ^docs/conf.py
 
   - repo: https://github.com/pre-commit/mirrors-prettier
-    rev: v1.19.1
+    rev: v2.2.1
     hooks:
       - id: prettier
         args: [--prose-wrap=always, --print-width=88]

From 1c364f42ee298251d009e39fcab5ecc8cd0384d6 Mon Sep 17 00:00:00 2001
From: James Addison <jay@jp-hosting.net>
Date: Wed, 10 Feb 2021 01:10:02 +0000
Subject: [PATCH 0077/1034] Regenerate documentation (#1980)

Resolves #1979 and ensures that the content from #1861 is included in the repository-published documentation.
---
 docs/installation_and_usage.md | 5 -----
 docs/pyproject_toml.md         | 7 ++++---
 2 files changed, 4 insertions(+), 8 deletions(-)

diff --git a/docs/installation_and_usage.md b/docs/installation_and_usage.md
index e3b53fd076e..ee45c934da8 100644
--- a/docs/installation_and_usage.md
+++ b/docs/installation_and_usage.md
@@ -100,11 +100,6 @@ Options:
                                   respect --force-exclude option on some
                                   editors that rely on using stdin.
 
-  --stdin-filename TEXT           The name of the file when passing it through
-                                  stdin. Useful to make sure Black will respect
-                                  --force-exclude option on some editors that
-                                  rely on using stdin.
-
   -q, --quiet                     Don't emit non-error messages to stderr.
                                   Errors are still emitted; silence those with
                                   2>/dev/null.
diff --git a/docs/pyproject_toml.md b/docs/pyproject_toml.md
index cd313452b1e..453f533bf96 100644
--- a/docs/pyproject_toml.md
+++ b/docs/pyproject_toml.md
@@ -55,9 +55,10 @@ line-length = 88
 target-version = ['py37']
 include = '\.pyi?$'
 exclude = '''
-
-(
-  /(
+# A regex preceded with ^/ will apply only to files and directories
+# in the root of the project.
+^/(
+  (
       \.eggs         # exclude a few common directories in the
     | \.git          # root of the project
     | \.hg

From 2d0c14989dca41676fc83fb36f2d652cf93fad58 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Tue, 9 Feb 2021 18:17:23 -0800
Subject: [PATCH 0078/1034] Bump cryptography from 3.3.1 to 3.3.2 (#1981)

Bumps [cryptography](https://github.com/pyca/cryptography) from 3.3.1 to 3.3.2.
- [Release notes](https://github.com/pyca/cryptography/releases)
- [Changelog](https://github.com/pyca/cryptography/blob/master/CHANGELOG.rst)
- [Commits](https://github.com/pyca/cryptography/compare/3.3.1...3.3.2)

Signed-off-by: dependabot[bot] <support@github.com>

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 Pipfile.lock | 44 ++++++++++++++++++++++----------------------
 1 file changed, 22 insertions(+), 22 deletions(-)

diff --git a/Pipfile.lock b/Pipfile.lock
index 44e987de0e4..9aa2d0e7ce8 100644
--- a/Pipfile.lock
+++ b/Pipfile.lock
@@ -425,7 +425,6 @@
                 "sha256:6123ddc1052673e52bab52cdc955bcb57a015264a1c57d37bea2f6b817af0125",
                 "sha256:98b3170739e5e83dd9dc19633f074727ad848cbedb6026708c8ac2d3b697a433"
             ],
-            "index": "pypi",
             "version": "==3.3.0"
         },
         "certifi": {
@@ -570,22 +569,23 @@
         },
         "cryptography": {
             "hashes": [
-                "sha256:0003a52a123602e1acee177dc90dd201f9bb1e73f24a070db7d36c588e8f5c7d",
-                "sha256:0e85aaae861d0485eb5a79d33226dd6248d2a9f133b81532c8f5aae37de10ff7",
-                "sha256:594a1db4511bc4d960571536abe21b4e5c3003e8750ab8365fafce71c5d86901",
-                "sha256:69e836c9e5ff4373ce6d3ab311c1a2eed274793083858d3cd4c7d12ce20d5f9c",
-                "sha256:788a3c9942df5e4371c199d10383f44a105d67d401fb4304178020142f020244",
-                "sha256:7e177e4bea2de937a584b13645cab32f25e3d96fc0bc4a4cf99c27dc77682be6",
-                "sha256:83d9d2dfec70364a74f4e7c70ad04d3ca2e6a08b703606993407bf46b97868c5",
-                "sha256:84ef7a0c10c24a7773163f917f1cb6b4444597efd505a8aed0a22e8c4780f27e",
-                "sha256:9e21301f7a1e7c03dbea73e8602905a4ebba641547a462b26dd03451e5769e7c",
-                "sha256:9f6b0492d111b43de5f70052e24c1f0951cb9e6022188ebcb1cc3a3d301469b0",
-                "sha256:a69bd3c68b98298f490e84519b954335154917eaab52cf582fa2c5c7efc6e812",
-                "sha256:b4890d5fb9b7a23e3bf8abf5a8a7da8e228f1e97dc96b30b95685df840b6914a",
-                "sha256:c366df0401d1ec4e548bebe8f91d55ebcc0ec3137900d214dd7aac8427ef3030",
-                "sha256:dc42f645f8f3a489c3dd416730a514e7a91a59510ddaadc09d04224c098d3302"
+                "sha256:0d7b69674b738068fa6ffade5c962ecd14969690585aaca0a1b1fc9058938a72",
+                "sha256:1bd0ccb0a1ed775cd7e2144fe46df9dc03eefd722bbcf587b3e0616ea4a81eff",
+                "sha256:3c284fc1e504e88e51c428db9c9274f2da9f73fdf5d7e13a36b8ecb039af6e6c",
+                "sha256:49570438e60f19243e7e0d504527dd5fe9b4b967b5a1ff21cc12b57602dd85d3",
+                "sha256:541dd758ad49b45920dda3b5b48c968f8b2533d8981bcdb43002798d8f7a89ed",
+                "sha256:5a60d3780149e13b7a6ff7ad6526b38846354d11a15e21068e57073e29e19bed",
+                "sha256:7951a966613c4211b6612b0352f5bf29989955ee592c4a885d8c7d0f830d0433",
+                "sha256:922f9602d67c15ade470c11d616f2b2364950602e370c76f0c94c94ae672742e",
+                "sha256:a0f0b96c572fc9f25c3f4ddbf4688b9b38c69836713fb255f4a2715d93cbaf44",
+                "sha256:a777c096a49d80f9d2979695b835b0f9c9edab73b59e4ceb51f19724dda887ed",
+                "sha256:a9a4ac9648d39ce71c2f63fe7dc6db144b9fa567ddfc48b9fde1b54483d26042",
+                "sha256:aa4969f24d536ae2268c902b2c3d62ab464b5a66bcb247630d208a79a8098e9b",
+                "sha256:c7390f9b2119b2b43160abb34f63277a638504ef8df99f11cb52c1fda66a2e6f",
+                "sha256:e18e6ab84dfb0ab997faf8cca25a86ff15dfea4027b986322026cc99e0a892da"
             ],
-            "version": "==3.3.1"
+            "index": "pypi",
+            "version": "==3.3.2"
         },
         "distlib": {
             "hashes": [
@@ -993,11 +993,11 @@
         },
         "secretstorage": {
             "hashes": [
-                "sha256:30cfdef28829dad64d6ea1ed08f8eff6aa115a77068926bcc9f5225d5a3246aa",
-                "sha256:5c36f6537a523ec5f969ef9fad61c98eb9e017bc601d811e53aa25bece64892f"
+                "sha256:422d82c36172d88d6a0ed5afdec956514b189ddbfb72fefab0c8a1cee4eaf71f",
+                "sha256:fd666c51a6bf200643495a04abb261f83229dcb6fd8472ec393df7ffc8b6f195"
             ],
             "markers": "sys_platform == 'linux'",
-            "version": "==3.3.0"
+            "version": "==3.3.1"
         },
         "setuptools-scm": {
             "hashes": [
@@ -1081,10 +1081,10 @@
         },
         "tqdm": {
             "hashes": [
-                "sha256:4621f6823bab46a9cc33d48105753ccbea671b68bab2c50a9f0be23d4065cb5a",
-                "sha256:fe3d08dd00a526850568d542ff9de9bbc2a09a791da3c334f3213d8d0bbbca65"
+                "sha256:2874fa525c051177583ec59c0fb4583e91f28ccd3f217ffad2acdb32d2c789ac",
+                "sha256:ab9b659241d82b8b51b2269ee243ec95286046bf06015c4e15a947cc15914211"
             ],
-            "version": "==4.56.0"
+            "version": "==4.56.1"
         },
         "twine": {
             "hashes": [

From b8c1020b526b488a1a216d9a4d58fc8616b61a99 Mon Sep 17 00:00:00 2001
From: James Addison <jay@jp-hosting.net>
Date: Thu, 11 Feb 2021 20:11:42 +0000
Subject: [PATCH 0079/1034] Stability fixup: interaction between newlines and
 comments (#1975)

* Add test case to illustrate the issue

* Accept carriage returns as valid separators while enumerating comments

Without this acceptance, escaped multi-line statments that use carriage returns will not be counted into the 'ignored_lines' variable since the emitted line values will end with a CR and not an escape character.  That leads to comments associated with the line being incorrectly labeled with the STANDALONE_COMMENT type, affecting comment placement and line space management.

* Remove comment linking to ephemeral build log
---
 src/black/__init__.py | 2 +-
 tests/test_black.py   | 5 +++++
 2 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index 7c1a013aae3..6dbb765cf7a 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -2635,7 +2635,7 @@ def list_comments(prefix: str, *, is_endmarker: bool) -> List[ProtoComment]:
     consumed = 0
     nlines = 0
     ignored_lines = 0
-    for index, line in enumerate(prefix.split("\n")):
+    for index, line in enumerate(re.split("\r?\n", prefix)):
         consumed += len(line) + 1  # adding the length of the split '\n'
         line = line.lstrip()
         if not line:
diff --git a/tests/test_black.py b/tests/test_black.py
index cfd3cbd91b3..a2efef82422 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -1793,6 +1793,11 @@ def test_bpo_33660_workaround(self) -> None:
         finally:
             os.chdir(str(old_cwd))
 
+    def test_newline_comment_interaction(self) -> None:
+        source = "class A:\\\r\n# type: ignore\n pass\n"
+        output = black.format_str(source, mode=DEFAULT_MODE)
+        black.assert_stable(source, output, mode=DEFAULT_MODE)
+
 
 with open(black.__file__, "r", encoding="utf-8") as _bf:
     black_source_lines = _bf.readlines()

From 76268ab0c9b4e4d030b2d16272bfbdcad5172aad Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Sun, 14 Feb 2021 10:23:47 -0500
Subject: [PATCH 0080/1034] Fix duplication of checks on internal PRs (#1986)

Internal PRs (that come from branches of psf/black) match both the push
and pull_request events. This leads to a duplication of test, lint, etc.
checks on such PRs. Not only is it a waste of resources, it makes the
Status Checks UI more frustrating to go through.

Patch taken from:
https://github.community/t/duplicate-checks-on-push-and-pull-request-simultaneous-event/18012
---
 .github/workflows/doc.yml    | 8 +++++++-
 .github/workflows/fuzz.yml   | 7 +++++++
 .github/workflows/lint.yml   | 7 +++++++
 .github/workflows/primer.yml | 7 +++++++
 .github/workflows/test.yml   | 7 +++++++
 5 files changed, 35 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml
index d266e55aa02..930b6d440ff 100644
--- a/.github/workflows/doc.yml
+++ b/.github/workflows/doc.yml
@@ -16,8 +16,14 @@ on:
 
 jobs:
   build:
-    runs-on: ubuntu-latest
+    # We want to run on external PRs, but not on our own internal PRs as they'll be run
+    # by the push to the branch. Without this if check, checks are duplicated since
+    # internal PRs match both the push and pull_request events.
+    if:
+      github.event_name == 'push' || github.event.pull_request.head.repo.full_name !=
+      github.repository
 
+    runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
 
diff --git a/.github/workflows/fuzz.yml b/.github/workflows/fuzz.yml
index 0153767509a..f3b688f3ef6 100644
--- a/.github/workflows/fuzz.yml
+++ b/.github/workflows/fuzz.yml
@@ -4,6 +4,13 @@ on: [push, pull_request]
 
 jobs:
   build:
+    # We want to run on external PRs, but not on our own internal PRs as they'll be run
+    # by the push to the branch. Without this if check, checks are duplicated since
+    # internal PRs match both the push and pull_request events.
+    if:
+      github.event_name == 'push' || github.event.pull_request.head.repo.full_name !=
+      github.repository
+
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index fa7286eec1f..e01e9ade5e2 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -4,6 +4,13 @@ on: [push, pull_request]
 
 jobs:
   build:
+    # We want to run on external PRs, but not on our own internal PRs as they'll be run
+    # by the push to the branch. Without this if check, checks are duplicated since
+    # internal PRs match both the push and pull_request events.
+    if:
+      github.event_name == 'push' || github.event.pull_request.head.repo.full_name !=
+      github.repository
+
     runs-on: ubuntu-latest
     strategy:
       matrix:
diff --git a/.github/workflows/primer.yml b/.github/workflows/primer.yml
index b623b938345..4c5751ae996 100644
--- a/.github/workflows/primer.yml
+++ b/.github/workflows/primer.yml
@@ -4,6 +4,13 @@ on: [push, pull_request]
 
 jobs:
   build:
+    # We want to run on external PRs, but not on our own internal PRs as they'll be run
+    # by the push to the branch. Without this if check, checks are duplicated since
+    # internal PRs match both the push and pull_request events.
+    if:
+      github.event_name == 'push' || github.event.pull_request.head.repo.full_name !=
+      github.repository
+
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 8dd4e4f59fd..bec769064c2 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -4,6 +4,13 @@ on: [push, pull_request]
 
 jobs:
   build:
+    # We want to run on external PRs, but not on our own internal PRs as they'll be run
+    # by the push to the branch. Without this if check, checks are duplicated since
+    # internal PRs match both the push and pull_request events.
+    if:
+      github.event_name == 'push' || github.event.pull_request.head.repo.full_name !=
+      github.repository
+
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false

From 3a309a36fcfc30a96a7fdd68b6b2c3aa2aa5341c Mon Sep 17 00:00:00 2001
From: rht <rhtbot@protonmail.com>
Date: Sun, 14 Feb 2021 10:32:29 -0500
Subject: [PATCH 0081/1034] readme: Include Zulip in used-by section (#1987)

Zulip has recently formatted their code in Black and also set Black as a linter: https://github.com/zulip/zulip/pull/15662.
See also https://chat.zulip.org/#narrow/stream/2-general/topic/black.
---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 83ecb89d6c9..97df938eab2 100644
--- a/README.md
+++ b/README.md
@@ -454,7 +454,7 @@ then write the above files to `.cache/black/<version>/`.
 The following notable open-source projects trust _Black_ with enforcing a consistent
 code style: pytest, tox, Pyramid, Django Channels, Hypothesis, attrs, SQLAlchemy,
 Poetry, PyPA applications (Warehouse, Bandersnatch, Pipenv, virtualenv), pandas, Pillow,
-every Datadog Agent Integration, Home Assistant.
+every Datadog Agent Integration, Home Assistant, Zulip.
 
 The following organizations use _Black_: Facebook, Dropbox, Mozilla, Quora.
 

From 6a105e019fcaa10cc0b6fb59edea4a4018eac97e Mon Sep 17 00:00:00 2001
From: Sagi Shadur <saroad2@gmail.com>
Date: Mon, 15 Feb 2021 18:02:48 +0200
Subject: [PATCH 0082/1034] Add "# fmt: skip" directive to black (#1800)

Fixes #1162
---
 README.md              |   5 +-
 src/black/__init__.py  | 104 +++++++++++++++++++++++++----------------
 tests/data/fmtskip.py  |   3 ++
 tests/data/fmtskip2.py |  17 +++++++
 tests/data/fmtskip3.py |  20 ++++++++
 tests/data/fmtskip4.py |  13 ++++++
 tests/data/fmtskip5.py |  22 +++++++++
 tests/test_format.py   |   5 ++
 8 files changed, 147 insertions(+), 42 deletions(-)
 create mode 100644 tests/data/fmtskip.py
 create mode 100644 tests/data/fmtskip2.py
 create mode 100644 tests/data/fmtskip3.py
 create mode 100644 tests/data/fmtskip4.py
 create mode 100644 tests/data/fmtskip5.py

diff --git a/README.md b/README.md
index 97df938eab2..89ef4271d41 100644
--- a/README.md
+++ b/README.md
@@ -239,8 +239,9 @@ feeling confident, use `--fast`.
 _Black_ is a PEP 8 compliant opinionated formatter. _Black_ reformats entire files in
 place. It is not configurable. It doesn't take previous formatting into account. Your
 main option of configuring _Black_ is that it doesn't reformat blocks that start with
-`# fmt: off` and end with `# fmt: on`. `# fmt: on/off` have to be on the same level of
-indentation. To learn more about _Black_'s opinions, to go
+`# fmt: off` and end with `# fmt: on`, or lines that ends with `# fmt: skip`. Pay
+attention that `# fmt: on/off` have to be on the same level of indentation. To learn
+more about _Black_'s opinions, to go
 [the_black_code_style](https://github.com/psf/black/blob/master/docs/the_black_code_style.md).
 
 Please refer to this document before submitting an issue. What seems like a bug might be
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 6dbb765cf7a..08930d11cea 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -2581,6 +2581,8 @@ def is_split_before_delimiter(leaf: Leaf, previous: Optional[Leaf] = None) -> Pr
 
 
 FMT_OFF = {"# fmt: off", "# fmt:off", "# yapf: disable"}
+FMT_SKIP = {"# fmt: skip", "# fmt:skip"}
+FMT_PASS = {*FMT_OFF, *FMT_SKIP}
 FMT_ON = {"# fmt: on", "# fmt:on", "# yapf: enable"}
 
 
@@ -5404,58 +5406,80 @@ def convert_one_fmt_off_pair(node: Node) -> bool:
     for leaf in node.leaves():
         previous_consumed = 0
         for comment in list_comments(leaf.prefix, is_endmarker=False):
-            if comment.value in FMT_OFF:
-                # We only want standalone comments. If there's no previous leaf or
-                # the previous leaf is indentation, it's a standalone comment in
-                # disguise.
-                if comment.type != STANDALONE_COMMENT:
-                    prev = preceding_leaf(leaf)
-                    if prev and prev.type not in WHITESPACE:
+            if comment.value not in FMT_PASS:
+                previous_consumed = comment.consumed
+                continue
+            # We only want standalone comments. If there's no previous leaf or
+            # the previous leaf is indentation, it's a standalone comment in
+            # disguise.
+            if comment.value in FMT_PASS and comment.type != STANDALONE_COMMENT:
+                prev = preceding_leaf(leaf)
+                if prev:
+                    if comment.value in FMT_OFF and prev.type not in WHITESPACE:
+                        continue
+                    if comment.value in FMT_SKIP and prev.type in WHITESPACE:
                         continue
 
-                ignored_nodes = list(generate_ignored_nodes(leaf))
-                if not ignored_nodes:
-                    continue
-
-                first = ignored_nodes[0]  # Can be a container node with the `leaf`.
-                parent = first.parent
-                prefix = first.prefix
-                first.prefix = prefix[comment.consumed :]
-                hidden_value = (
-                    comment.value + "\n" + "".join(str(n) for n in ignored_nodes)
-                )
-                if hidden_value.endswith("\n"):
-                    # That happens when one of the `ignored_nodes` ended with a NEWLINE
-                    # leaf (possibly followed by a DEDENT).
-                    hidden_value = hidden_value[:-1]
-                first_idx: Optional[int] = None
-                for ignored in ignored_nodes:
-                    index = ignored.remove()
-                    if first_idx is None:
-                        first_idx = index
-                assert parent is not None, "INTERNAL ERROR: fmt: on/off handling (1)"
-                assert first_idx is not None, "INTERNAL ERROR: fmt: on/off handling (2)"
-                parent.insert_child(
-                    first_idx,
-                    Leaf(
-                        STANDALONE_COMMENT,
-                        hidden_value,
-                        prefix=prefix[:previous_consumed] + "\n" * comment.newlines,
-                    ),
-                )
-                return True
+            ignored_nodes = list(generate_ignored_nodes(leaf, comment))
+            if not ignored_nodes:
+                continue
 
-            previous_consumed = comment.consumed
+            first = ignored_nodes[0]  # Can be a container node with the `leaf`.
+            parent = first.parent
+            prefix = first.prefix
+            first.prefix = prefix[comment.consumed :]
+            hidden_value = "".join(str(n) for n in ignored_nodes)
+            if comment.value in FMT_OFF:
+                hidden_value = comment.value + "\n" + hidden_value
+            if comment.value in FMT_SKIP:
+                hidden_value += "  " + comment.value
+            if hidden_value.endswith("\n"):
+                # That happens when one of the `ignored_nodes` ended with a NEWLINE
+                # leaf (possibly followed by a DEDENT).
+                hidden_value = hidden_value[:-1]
+            first_idx: Optional[int] = None
+            for ignored in ignored_nodes:
+                index = ignored.remove()
+                if first_idx is None:
+                    first_idx = index
+            assert parent is not None, "INTERNAL ERROR: fmt: on/off handling (1)"
+            assert first_idx is not None, "INTERNAL ERROR: fmt: on/off handling (2)"
+            parent.insert_child(
+                first_idx,
+                Leaf(
+                    STANDALONE_COMMENT,
+                    hidden_value,
+                    prefix=prefix[:previous_consumed] + "\n" * comment.newlines,
+                ),
+            )
+            return True
 
     return False
 
 
-def generate_ignored_nodes(leaf: Leaf) -> Iterator[LN]:
+def generate_ignored_nodes(leaf: Leaf, comment: ProtoComment) -> Iterator[LN]:
     """Starting from the container of `leaf`, generate all leaves until `# fmt: on`.
 
+    If comment is skip, returns leaf only.
     Stops at the end of the block.
     """
     container: Optional[LN] = container_of(leaf)
+    if comment.value in FMT_SKIP:
+        prev_sibling = leaf.prev_sibling
+        if comment.value in leaf.prefix and prev_sibling is not None:
+            leaf.prefix = leaf.prefix.replace(comment.value, "")
+            siblings = [prev_sibling]
+            while (
+                "\n" not in prev_sibling.prefix
+                and prev_sibling.prev_sibling is not None
+            ):
+                prev_sibling = prev_sibling.prev_sibling
+                siblings.insert(0, prev_sibling)
+            for sibling in siblings:
+                yield sibling
+        elif leaf.parent is not None:
+            yield leaf.parent
+        return
     while container is not None and container.type != token.ENDMARKER:
         if is_fmt_on(container):
             return
diff --git a/tests/data/fmtskip.py b/tests/data/fmtskip.py
new file mode 100644
index 00000000000..1d5836fc031
--- /dev/null
+++ b/tests/data/fmtskip.py
@@ -0,0 +1,3 @@
+a, b = 1, 2
+c =    6  # fmt: skip
+d = 5
diff --git a/tests/data/fmtskip2.py b/tests/data/fmtskip2.py
new file mode 100644
index 00000000000..e6248117aa9
--- /dev/null
+++ b/tests/data/fmtskip2.py
@@ -0,0 +1,17 @@
+l1 = ["This list should be broken up", "into multiple lines", "because it is way too long"]
+l2 = ["But this list shouldn't", "even though it also has", "way too many characters in it"]  # fmt: skip
+l3 = ["I have", "trailing comma", "so I should be braked",]
+
+# output
+
+l1 = [
+    "This list should be broken up",
+    "into multiple lines",
+    "because it is way too long",
+]
+l2 = ["But this list shouldn't", "even though it also has", "way too many characters in it"]  # fmt: skip
+l3 = [
+    "I have",
+    "trailing comma",
+    "so I should be braked",
+]
\ No newline at end of file
diff --git a/tests/data/fmtskip3.py b/tests/data/fmtskip3.py
new file mode 100644
index 00000000000..6e166888e21
--- /dev/null
+++ b/tests/data/fmtskip3.py
@@ -0,0 +1,20 @@
+a  =    3
+# fmt: off
+b,    c = 1, 2
+d =    6  # fmt: skip
+e = 5
+# fmt: on
+f = ["This is a very long line that should be formatted into a clearer line ", "by rearranging."]
+
+# output
+
+a = 3
+# fmt: off
+b,    c = 1, 2
+d =    6  # fmt: skip
+e = 5
+# fmt: on
+f = [
+    "This is a very long line that should be formatted into a clearer line ",
+    "by rearranging.",
+]
diff --git a/tests/data/fmtskip4.py b/tests/data/fmtskip4.py
new file mode 100644
index 00000000000..aadd77d0e53
--- /dev/null
+++ b/tests/data/fmtskip4.py
@@ -0,0 +1,13 @@
+a =   2
+# fmt: skip
+l = [1, 2, 3,]
+
+# output
+
+a = 2
+# fmt: skip
+l = [
+    1,
+    2,
+    3,
+]
\ No newline at end of file
diff --git a/tests/data/fmtskip5.py b/tests/data/fmtskip5.py
new file mode 100644
index 00000000000..d7b15e0ff41
--- /dev/null
+++ b/tests/data/fmtskip5.py
@@ -0,0 +1,22 @@
+a, b, c = 3, 4,       5
+if (
+    a ==    3
+    and b    != 9  # fmt: skip
+    and c is not None
+):
+    print("I'm good!")
+else:
+    print("I'm bad")
+
+
+# output
+
+a, b, c = 3, 4, 5
+if (
+    a == 3
+    and b    != 9  # fmt: skip
+    and c is not None
+):
+    print("I'm good!")
+else:
+    print("I'm bad")
diff --git a/tests/test_format.py b/tests/test_format.py
index e4677707e3c..e0cb0b74195 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -37,6 +37,11 @@
     "fmtonoff2",
     "fmtonoff3",
     "fmtonoff4",
+    "fmtskip",
+    "fmtskip2",
+    "fmtskip3",
+    "fmtskip4",
+    "fmtskip5",
     "fstring",
     "function",
     "function2",

From 71bbb678b9f3ad1b18eab9c967b39f22a0d19535 Mon Sep 17 00:00:00 2001
From: Archit Gopal <73956153+Architrixs@users.noreply.github.com>
Date: Mon, 15 Feb 2021 21:35:23 +0530
Subject: [PATCH 0083/1034] add gedit integration (#1988)

---
 docs/editor_integration.md | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/docs/editor_integration.md b/docs/editor_integration.md
index 037b265b9a0..aa3a1eeedec 100644
--- a/docs/editor_integration.md
+++ b/docs/editor_integration.md
@@ -233,6 +233,36 @@ If you later want to update _Black_, you should do it like this:
 $ pip install -U black --no-binary regex,typed-ast
 ```
 
+## Gedit
+
+gedit is the default text editor of the GNOME, Unix like Operating Systems. Open gedit
+as
+
+```console
+$ gedit <file_name>
+```
+
+1. `Go to edit > preferences > plugins`
+2. Search for `external tools` and activate it.
+3. In `Tools menu -> Manage external tools`
+4. Add a new tool using `+` button.
+5. Copy the below content to the code window.
+
+```console
+#!/bin/bash
+Name=$GEDIT_CURRENT_DOCUMENT_NAME
+black $Name
+```
+
+- Set a keyboard shortcut if you like, Ex. `ctrl-B`
+- Save: `Nothing`
+- Input: `Nothing`
+- Output: `Display in bottom pane` if you like.
+- Change the name of the tool if you like.
+
+Use your keyboard shortcut or `Tools -> External Tools` to use your new tool. When you
+close and reopen your File, _Black_ will be done with its job.
+
 ## Visual Studio Code
 
 Use the

From 97b8496d67741a10f30eefbb3d6c97a0e541fba4 Mon Sep 17 00:00:00 2001
From: Romain Rigaux <romain.rigaux@gmail.com>
Date: Tue, 16 Feb 2021 13:10:23 -0800
Subject: [PATCH 0084/1034] Use 'args' to Avoid GH workflow warning (#1990)

Unexpected input(s) 'black_args', valid inputs are ['entryPoint', 'args']
---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 89ef4271d41..178f763c32d 100644
--- a/README.md
+++ b/README.md
@@ -419,7 +419,7 @@ jobs:
       - uses: actions/setup-python@v2
       - uses: psf/black@stable
         with:
-          black_args: ". --check"
+          args: ". --check"
 ```
 
 ### Inputs

From 306a513137ec93a5053d415319e24bd4057d4045 Mon Sep 17 00:00:00 2001
From: James Addison <jay@jp-hosting.net>
Date: Sat, 20 Feb 2021 16:44:48 +0000
Subject: [PATCH 0085/1034] fuzzer: add special-case for multi-line EOF
 TokenError (#1991)

* Add special-case for multi-line EOF TokenError under Python3.7

* Update conditional check to correspond to original issue description (and include issue hyperlink)

* Add warning and hint regarding replaying the fuzzer code generation

* Include code review suggestion (with modifications for this to follow)

Co-authored-by: Zac Hatfield-Dodds <zac.hatfield.dodds@gmail.com>

* Remove Python version check, since this issue does exist across more recent Python versions than 3.7

* Update explanatory comment

* Add clarification for potentially-ambiguous blib2to3 import

* Update explanatory comment

* Bring comment into consistent format with previous comment

* Revert "Add clarification for potentially-ambiguous blib2to3 import"

This reverts commit 357b7cc03bdb19dd924f1accd428352f4bb44e5c.

Co-authored-by: Zac Hatfield-Dodds <zac.hatfield.dodds@gmail.com>
---
 fuzz.py | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/fuzz.py b/fuzz.py
index 6330c58cc81..6e2068690b5 100644
--- a/fuzz.py
+++ b/fuzz.py
@@ -5,10 +5,13 @@
 a coverage-guided fuzzer I'm working on.
 """
 
+import re
+
 import hypothesmith
 from hypothesis import HealthCheck, given, settings, strategies as st
 
 import black
+from blib2to3.pgen2.tokenize import TokenError
 
 
 # This test uses the Hypothesis and Hypothesmith libraries to generate random
@@ -46,6 +49,16 @@ def test_idempotent_any_syntatically_valid_python(
         # able to cope with it.  See issues #970, #1012, #1358, and #1557.
         # TODO: remove this try-except block when issues are resolved.
         return
+    except TokenError as e:
+        if (
+            e.args[0] == "EOF in multi-line statement"
+            and re.search(r"\r?\n\\\r?\n", src_contents) is not None
+        ):
+            # This is a bug - if it's valid Python code, as above, Black should be
+            # able to cope with it.  See issue #1012.
+            # TODO: remove this block when the issue is resolved.
+            return
+        raise
 
     # And check that we got equivalent and stable output.
     black.assert_equivalent(src_contents, dst_contents)

From afc8c326bf97ce7a22e8fc0b8cc5ced1586ef022 Mon Sep 17 00:00:00 2001
From: James Addison <jay@jp-hosting.net>
Date: Thu, 4 Feb 2021 17:26:29 +0000
Subject: [PATCH 0086/1034] Brevity: rename method

---
 src/black/__init__.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index 08930d11cea..e398ed04f43 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -5005,7 +5005,7 @@ def bracket_split_build_line(
         result.append(leaf, preformatted=True)
         for comment_after in original.comments_after(leaf):
             result.append(comment_after, preformatted=True)
-    if is_body and should_split_body_explode(result, opening_bracket):
+    if is_body and should_split(result, opening_bracket):
         result.should_explode = True
     return result
 
@@ -5810,7 +5810,7 @@ def ensure_visible(leaf: Leaf) -> None:
         leaf.value = ")"
 
 
-def should_split_body_explode(line: Line, opening_bracket: Leaf) -> bool:
+def should_split(line: Line, opening_bracket: Leaf) -> bool:
     """Should `line` be immediately split with `delimiter_split()` after RHS?"""
 
     if not (opening_bracket.parent and opening_bracket.value in "[{("):

From caa3fcc2de3cfb6162bee0bb6f68b10bc38e612f Mon Sep 17 00:00:00 2001
From: James Addison <jay@jp-hosting.net>
Date: Thu, 4 Feb 2021 17:30:05 +0000
Subject: [PATCH 0087/1034] Clarity: isolate and extract each responsibility
 from an overloaded variable

---
 src/black/__init__.py | 19 ++++++++++++-------
 1 file changed, 12 insertions(+), 7 deletions(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index e398ed04f43..44017b59602 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -1481,6 +1481,7 @@ class Line:
     bracket_tracker: BracketTracker = field(default_factory=BracketTracker)
     inside_brackets: bool = False
     should_explode: bool = False
+    magic_trailing_comma: Optional[Leaf] = None
 
     def append(self, leaf: Leaf, preformatted: bool = False) -> None:
         """Add a new `leaf` to the end of the line.
@@ -1508,7 +1509,7 @@ def append(self, leaf: Leaf, preformatted: bool = False) -> None:
             self.bracket_tracker.mark(leaf)
             if self.mode.magic_trailing_comma:
                 if self.has_magic_trailing_comma(leaf):
-                    self.should_explode = True
+                    self.magic_trailing_comma = leaf
             elif self.has_magic_trailing_comma(leaf, ensure_removable=True):
                 self.remove_trailing_comma()
         if not self.append_comment(leaf):
@@ -1792,6 +1793,7 @@ def clone(self) -> "Line":
             depth=self.depth,
             inside_brackets=self.inside_brackets,
             should_explode=self.should_explode,
+            magic_trailing_comma=self.magic_trailing_comma,
         )
 
     def __str__(self) -> str:
@@ -2710,7 +2712,7 @@ def init_st(ST: Type[StringTransformer]) -> StringTransformer:
     transformers: List[Transformer]
     if (
         not line.contains_uncollapsable_type_comments()
-        and not line.should_explode
+        and not (line.should_explode or line.magic_trailing_comma)
         and (
             is_line_short_enough(line, line_length=mode.line_length, line_str=line_str)
             or line.contains_unsplittable_type_ignore()
@@ -4385,6 +4387,7 @@ def do_transform(self, line: Line, string_idx: int) -> Iterator[TResult[Line]]:
             depth=line.depth + 1,
             inside_brackets=True,
             should_explode=line.should_explode,
+            magic_trailing_comma=line.magic_trailing_comma,
         )
         string_leaf = Leaf(token.STRING, string_value)
         insert_str_child(string_leaf)
@@ -5946,7 +5949,7 @@ def generate_trailers_to_omit(line: Line, line_length: int) -> Iterator[Set[Leaf
     """
 
     omit: Set[LeafID] = set()
-    if not line.should_explode:
+    if not line.should_explode and not line.magic_trailing_comma:
         yield omit
 
     length = 4 * line.depth
@@ -5968,7 +5971,7 @@ def generate_trailers_to_omit(line: Line, line_length: int) -> Iterator[Set[Leaf
             elif leaf.type in CLOSING_BRACKETS:
                 prev = line.leaves[index - 1] if index > 0 else None
                 if (
-                    line.should_explode
+                    (line.should_explode or line.magic_trailing_comma)
                     and prev
                     and prev.type == token.COMMA
                     and not is_one_tuple_between(
@@ -5996,7 +5999,7 @@ def generate_trailers_to_omit(line: Line, line_length: int) -> Iterator[Set[Leaf
                 yield omit
 
             if (
-                line.should_explode
+                (line.should_explode or line.magic_trailing_comma)
                 and prev
                 and prev.type == token.COMMA
                 and not is_one_tuple_between(leaf.opening_bracket, leaf, line.leaves)
@@ -6629,7 +6632,7 @@ def can_omit_invisible_parens(
 
     penultimate = line.leaves[-2]
     last = line.leaves[-1]
-    if line.should_explode:
+    if line.should_explode or line.magic_trailing_comma:
         try:
             penultimate, last = last_two_except(line.leaves, omit=omit_on_explode)
         except LookupError:
@@ -6656,7 +6659,9 @@ def can_omit_invisible_parens(
             # unnecessary.
             return True
 
-        if line.should_explode and penultimate.type == token.COMMA:
+        if (
+            line.should_explode or line.magic_trailing_comma
+        ) and penultimate.type == token.COMMA:
             # The rightmost non-omitted bracket pair is the one we want to explode on.
             return True
 

From a23f521fee1b283b10000d94267ef93069b7f7ec Mon Sep 17 00:00:00 2001
From: James Addison <jay@jp-hosting.net>
Date: Thu, 4 Feb 2021 17:37:25 +0000
Subject: [PATCH 0088/1034] Brevity: only use the variables required to convey
 the intended expressions

---
 src/black/__init__.py | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index 44017b59602..67eef95390d 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -5971,7 +5971,7 @@ def generate_trailers_to_omit(line: Line, line_length: int) -> Iterator[Set[Leaf
             elif leaf.type in CLOSING_BRACKETS:
                 prev = line.leaves[index - 1] if index > 0 else None
                 if (
-                    (line.should_explode or line.magic_trailing_comma)
+                    line.magic_trailing_comma
                     and prev
                     and prev.type == token.COMMA
                     and not is_one_tuple_between(
@@ -5999,7 +5999,7 @@ def generate_trailers_to_omit(line: Line, line_length: int) -> Iterator[Set[Leaf
                 yield omit
 
             if (
-                (line.should_explode or line.magic_trailing_comma)
+                line.magic_trailing_comma
                 and prev
                 and prev.type == token.COMMA
                 and not is_one_tuple_between(leaf.opening_bracket, leaf, line.leaves)
@@ -6659,9 +6659,7 @@ def can_omit_invisible_parens(
             # unnecessary.
             return True
 
-        if (
-            line.should_explode or line.magic_trailing_comma
-        ) and penultimate.type == token.COMMA:
+        if line.magic_trailing_comma and penultimate.type == token.COMMA:
             # The rightmost non-omitted bracket pair is the one we want to explode on.
             return True
 

From 51141f1af4aab0e0c7f71932ffe06482a884f1d5 Mon Sep 17 00:00:00 2001
From: James Addison <jay@jp-hosting.net>
Date: Thu, 4 Feb 2021 17:38:55 +0000
Subject: [PATCH 0089/1034] Consistency: use variable names that correspond to
 the methods they invoke

---
 src/black/__init__.py | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index 67eef95390d..c836b2b46eb 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -1480,7 +1480,7 @@ class Line:
     comments: Dict[LeafID, List[Leaf]] = field(default_factory=dict)
     bracket_tracker: BracketTracker = field(default_factory=BracketTracker)
     inside_brackets: bool = False
-    should_explode: bool = False
+    should_split: bool = False
     magic_trailing_comma: Optional[Leaf] = None
 
     def append(self, leaf: Leaf, preformatted: bool = False) -> None:
@@ -1792,7 +1792,7 @@ def clone(self) -> "Line":
             mode=self.mode,
             depth=self.depth,
             inside_brackets=self.inside_brackets,
-            should_explode=self.should_explode,
+            should_split=self.should_split,
             magic_trailing_comma=self.magic_trailing_comma,
         )
 
@@ -2712,7 +2712,7 @@ def init_st(ST: Type[StringTransformer]) -> StringTransformer:
     transformers: List[Transformer]
     if (
         not line.contains_uncollapsable_type_comments()
-        and not (line.should_explode or line.magic_trailing_comma)
+        and not (line.should_split or line.magic_trailing_comma)
         and (
             is_line_short_enough(line, line_length=mode.line_length, line_str=line_str)
             or line.contains_unsplittable_type_ignore()
@@ -4386,7 +4386,7 @@ def do_transform(self, line: Line, string_idx: int) -> Iterator[TResult[Line]]:
             mode=line.mode,
             depth=line.depth + 1,
             inside_brackets=True,
-            should_explode=line.should_explode,
+            should_split=line.should_split,
             magic_trailing_comma=line.magic_trailing_comma,
         )
         string_leaf = Leaf(token.STRING, string_value)
@@ -5009,7 +5009,7 @@ def bracket_split_build_line(
         for comment_after in original.comments_after(leaf):
             result.append(comment_after, preformatted=True)
     if is_body and should_split(result, opening_bracket):
-        result.should_explode = True
+        result.should_split = True
     return result
 
 
@@ -5949,7 +5949,7 @@ def generate_trailers_to_omit(line: Line, line_length: int) -> Iterator[Set[Leaf
     """
 
     omit: Set[LeafID] = set()
-    if not line.should_explode and not line.magic_trailing_comma:
+    if not line.should_split and not line.magic_trailing_comma:
         yield omit
 
     length = 4 * line.depth
@@ -6632,7 +6632,7 @@ def can_omit_invisible_parens(
 
     penultimate = line.leaves[-2]
     last = line.leaves[-1]
-    if line.should_explode or line.magic_trailing_comma:
+    if line.should_split or line.magic_trailing_comma:
         try:
             penultimate, last = last_two_except(line.leaves, omit=omit_on_explode)
         except LookupError:

From 89c42a0011721e164738c17a192452ee77d9cc99 Mon Sep 17 00:00:00 2001
From: James Addison <jay@jp-hosting.net>
Date: Thu, 4 Feb 2021 17:40:42 +0000
Subject: [PATCH 0090/1034] Clarity: special case: avoid using variables that
 have the same names as methods

---
 src/black/__init__.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index c836b2b46eb..7f727b18bf0 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -5008,7 +5008,7 @@ def bracket_split_build_line(
         result.append(leaf, preformatted=True)
         for comment_after in original.comments_after(leaf):
             result.append(comment_after, preformatted=True)
-    if is_body and should_split(result, opening_bracket):
+    if is_body and should_split_line(result, opening_bracket):
         result.should_split = True
     return result
 
@@ -5813,7 +5813,7 @@ def ensure_visible(leaf: Leaf) -> None:
         leaf.value = ")"
 
 
-def should_split(line: Line, opening_bracket: Leaf) -> bool:
+def should_split_line(line: Line, opening_bracket: Leaf) -> bool:
     """Should `line` be immediately split with `delimiter_split()` after RHS?"""
 
     if not (opening_bracket.parent and opening_bracket.value in "[{("):

From 829331a8777aa758c6fc2a5032d38d8fbb5b5ac6 Mon Sep 17 00:00:00 2001
From: James Addison <jay@jp-hosting.net>
Date: Thu, 4 Feb 2021 17:45:45 +0000
Subject: [PATCH 0091/1034] Simplification: only use special-case token
 retrieval logic when magic trailing comma is present

---
 src/black/__init__.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index 7f727b18bf0..56f180ac8a6 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -6632,7 +6632,7 @@ def can_omit_invisible_parens(
 
     penultimate = line.leaves[-2]
     last = line.leaves[-1]
-    if line.should_split or line.magic_trailing_comma:
+    if line.magic_trailing_comma:
         try:
             penultimate, last = last_two_except(line.leaves, omit=omit_on_explode)
         except LookupError:

From e0d766727dc87f5c5f39ef751d0bf23fc5ff31a0 Mon Sep 17 00:00:00 2001
From: James Addison <jay@jp-hosting.net>
Date: Thu, 4 Feb 2021 17:48:38 +0000
Subject: [PATCH 0092/1034] Simplification: only yield empty omit list when
 magic trailing comma is present

---
 src/black/__init__.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index 56f180ac8a6..3eea33ced14 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -5949,7 +5949,7 @@ def generate_trailers_to_omit(line: Line, line_length: int) -> Iterator[Set[Leaf
     """
 
     omit: Set[LeafID] = set()
-    if not line.should_split and not line.magic_trailing_comma:
+    if not line.magic_trailing_comma:
         yield omit
 
     length = 4 * line.depth

From 24700806f681f2809a2b85999871e291c36dd948 Mon Sep 17 00:00:00 2001
From: James Addison <jay@jp-hosting.net>
Date: Thu, 4 Feb 2021 18:07:43 +0000
Subject: [PATCH 0093/1034] Cleanup: remove unused / redundant variables from
 conditionals

---
 src/black/__init__.py | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index 3eea33ced14..c2a4bda6061 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -5971,8 +5971,7 @@ def generate_trailers_to_omit(line: Line, line_length: int) -> Iterator[Set[Leaf
             elif leaf.type in CLOSING_BRACKETS:
                 prev = line.leaves[index - 1] if index > 0 else None
                 if (
-                    line.magic_trailing_comma
-                    and prev
+                    prev
                     and prev.type == token.COMMA
                     and not is_one_tuple_between(
                         leaf.opening_bracket, leaf, line.leaves
@@ -5999,8 +5998,7 @@ def generate_trailers_to_omit(line: Line, line_length: int) -> Iterator[Set[Leaf
                 yield omit
 
             if (
-                line.magic_trailing_comma
-                and prev
+                prev
                 and prev.type == token.COMMA
                 and not is_one_tuple_between(leaf.opening_bracket, leaf, line.leaves)
             ):
@@ -6659,7 +6657,7 @@ def can_omit_invisible_parens(
             # unnecessary.
             return True
 
-        if line.magic_trailing_comma and penultimate.type == token.COMMA:
+        if penultimate.type == token.COMMA:
             # The rightmost non-omitted bracket pair is the one we want to explode on.
             return True
 

From 22127c633eba10d41519fb562c1252f859e2d7fa Mon Sep 17 00:00:00 2001
From: James Addison <jay@jp-hosting.net>
Date: Tue, 9 Feb 2021 21:13:57 +0000
Subject: [PATCH 0094/1034] Readability: reduce boolean nesting

---
 src/black/__init__.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index c2a4bda6061..c2b0ad43fa8 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -2712,7 +2712,8 @@ def init_st(ST: Type[StringTransformer]) -> StringTransformer:
     transformers: List[Transformer]
     if (
         not line.contains_uncollapsable_type_comments()
-        and not (line.should_split or line.magic_trailing_comma)
+        and not line.should_split
+        and not line.magic_trailing_comma
         and (
             is_line_short_enough(line, line_length=mode.line_length, line_str=line_str)
             or line.contains_unsplittable_type_ignore()

From 0cbe19c813559d6642e71832242264ab8d5a5d59 Mon Sep 17 00:00:00 2001
From: James Addison <jay@jp-hosting.net>
Date: Wed, 10 Feb 2021 12:33:50 +0000
Subject: [PATCH 0095/1034] Minimize changes: more closely resemble original
 conditional logic

---
 src/black/__init__.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index c2b0ad43fa8..0b734adca56 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -6658,7 +6658,7 @@ def can_omit_invisible_parens(
             # unnecessary.
             return True
 
-        if penultimate.type == token.COMMA:
+        if line.magic_trailing_comma and penultimate.type == token.COMMA:
             # The rightmost non-omitted bracket pair is the one we want to explode on.
             return True
 

From cd4295dd9888f491cfd9aae060d7832b7f831b24 Mon Sep 17 00:00:00 2001
From: "Paul \"TBBle\" Hampson" <Paul.Hampson@Pobox.com>
Date: Mon, 22 Feb 2021 17:43:23 +1100
Subject: [PATCH 0096/1034] Indicate that a final newline was added in --diff
 (#1897) (#1897)

Fixes: #1662

Work-around for https://bugs.python.org/issue2142

The test has to slightly mess with its input data, because the utility
functions default to ensuring the test data has a final newline, which
defeats the point of the test.

Signed-off-by: Paul "TBBle" Hampson <Paul.Hampson@Pobox.com>
---
 CHANGES.md                            |  2 ++
 docs/authors.md                       |  1 +
 src/black/__init__.py                 | 23 ++++++++++++++++-------
 tests/data/missing_final_newline.diff |  8 ++++++++
 tests/data/missing_final_newline.py   |  3 +++
 tests/test_black.py                   | 23 ++++++++++++++++++++++-
 6 files changed, 52 insertions(+), 8 deletions(-)
 create mode 100644 tests/data/missing_final_newline.diff
 create mode 100644 tests/data/missing_final_newline.py

diff --git a/CHANGES.md b/CHANGES.md
index 5f7ca4f4da7..3fd7ad40496 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -28,6 +28,8 @@
 
 - speed up caching by avoiding pathlib (#1950)
 
+- `--diff` correctly indicates when a file doesn't end in a newline (#1662)
+
 #### _Packaging_
 
 - Self-contained native _Black_ binaries are now provided for releases via GitHub
diff --git a/docs/authors.md b/docs/authors.md
index cdf5046c446..9f2ea0571b9 100644
--- a/docs/authors.md
+++ b/docs/authors.md
@@ -132,6 +132,7 @@ Multiple contributions by:
 - [Pablo Galindo](mailto:Pablogsal@gmail.com)
 - [Paul Ganssle](mailto:p.ganssle@gmail.com)
 - [Paul Meinhardt](mailto:mnhrdt@gmail.com)
+- [Paul "TBBle" Hampson](mailto:Paul.Hampson@Pobox.com)
 - [Peter Bengtsson](mailto:mail@peterbe.com)
 - [Peter Grayson](mailto:pete@jpgrayson.net)
 - [Peter Stensmyr](mailto:peter.stensmyr@gmail.com)
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 0b734adca56..c1907d9b1f1 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -6425,14 +6425,14 @@ def assert_stable(src: str, dst: str, mode: Mode) -> None:
 
 
 @mypyc_attr(patchable=True)
-def dump_to_file(*output: str) -> str:
+def dump_to_file(*output: str, ensure_final_newline: bool = True) -> str:
     """Dump `output` to a temporary file. Return path to the file."""
     with tempfile.NamedTemporaryFile(
         mode="w", prefix="blk_", suffix=".log", delete=False, encoding="utf8"
     ) as f:
         for lines in output:
             f.write(lines)
-            if lines and lines[-1] != "\n":
+            if ensure_final_newline and lines and lines[-1] != "\n":
                 f.write("\n")
     return f.name
 
@@ -6450,11 +6450,20 @@ def diff(a: str, b: str, a_name: str, b_name: str) -> str:
     """Return a unified diff string between strings `a` and `b`."""
     import difflib
 
-    a_lines = [line + "\n" for line in a.splitlines()]
-    b_lines = [line + "\n" for line in b.splitlines()]
-    return "".join(
-        difflib.unified_diff(a_lines, b_lines, fromfile=a_name, tofile=b_name, n=5)
-    )
+    a_lines = [line for line in a.splitlines(keepends=True)]
+    b_lines = [line for line in b.splitlines(keepends=True)]
+    diff_lines = []
+    for line in difflib.unified_diff(
+        a_lines, b_lines, fromfile=a_name, tofile=b_name, n=5
+    ):
+        # Work around https://bugs.python.org/issue2142
+        # See https://www.gnu.org/software/diffutils/manual/html_node/Incomplete-Lines.html
+        if line[-1] == "\n":
+            diff_lines.append(line)
+        else:
+            diff_lines.append(line + "\n")
+            diff_lines.append("\\ No newline at end of file\n")
+    return "".join(diff_lines)
 
 
 def cancel(tasks: Iterable["asyncio.Task[Any]"]) -> None:
diff --git a/tests/data/missing_final_newline.diff b/tests/data/missing_final_newline.diff
new file mode 100644
index 00000000000..6d991c74f8f
--- /dev/null
+++ b/tests/data/missing_final_newline.diff
@@ -0,0 +1,8 @@
+--- [Deterministic header]
++++ [Deterministic header]
+@@ -1,3 +1,3 @@
+ # A comment-only file, with no final EOL character
+ # This triggers https://bugs.python.org/issue2142
+-# This is the line without the EOL character
+\ No newline at end of file
++# This is the line without the EOL character
diff --git a/tests/data/missing_final_newline.py b/tests/data/missing_final_newline.py
new file mode 100644
index 00000000000..687e1367552
--- /dev/null
+++ b/tests/data/missing_final_newline.py
@@ -0,0 +1,3 @@
+# A comment-only file, with no final EOL character
+# This triggers https://bugs.python.org/issue2142
+# This is the line without the EOL character
\ No newline at end of file
diff --git a/tests/test_black.py b/tests/test_black.py
index a2efef82422..5d14ceda8f4 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -300,7 +300,6 @@ def test_expression_diff(self) -> None:
             os.unlink(tmp_file)
         actual = result.output
         actual = diff_header.sub(DETERMINISTIC_HEADER, actual)
-        actual = actual.rstrip() + "\n"  # the diff output has a trailing space
         if expected != actual:
             dump = black.dump_to_file(actual)
             msg = (
@@ -1798,6 +1797,28 @@ def test_newline_comment_interaction(self) -> None:
         output = black.format_str(source, mode=DEFAULT_MODE)
         black.assert_stable(source, output, mode=DEFAULT_MODE)
 
+    def test_bpo_2142_workaround(self) -> None:
+
+        # https://bugs.python.org/issue2142
+
+        source, _ = read_data("missing_final_newline.py")
+        # read_data adds a trailing newline
+        source = source.rstrip()
+        expected, _ = read_data("missing_final_newline.diff")
+        tmp_file = Path(black.dump_to_file(source, ensure_final_newline=False))
+        diff_header = re.compile(
+            rf"{re.escape(str(tmp_file))}\t\d\d\d\d-\d\d-\d\d "
+            r"\d\d:\d\d:\d\d\.\d\d\d\d\d\d \+\d\d\d\d"
+        )
+        try:
+            result = BlackRunner().invoke(black.main, ["--diff", str(tmp_file)])
+            self.assertEqual(result.exit_code, 0)
+        finally:
+            os.unlink(tmp_file)
+        actual = result.output
+        actual = diff_header.sub(DETERMINISTIC_HEADER, actual)
+        self.assertEqual(actual, expected)
+
 
 with open(black.__file__, "r", encoding="utf-8") as _bf:
     black_source_lines = _bf.readlines()

From 24e8dad575f2ae373e64b583f6ad103cf9193781 Mon Sep 17 00:00:00 2001
From: James <50501825+Gobot1234@users.noreply.github.com>
Date: Mon, 22 Feb 2021 15:42:05 +0000
Subject: [PATCH 0097/1034] Fix for enum changes in 3.10 (#1999)

---
 src/black/__init__.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index c1907d9b1f1..e09f08df7df 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -883,7 +883,7 @@ def format_file_in_place(
         dst_name = f"{src}\t{now} +0000"
         diff_contents = diff(src_contents, dst_contents, src_name, dst_name)
 
-        if write_back == write_back.COLOR_DIFF:
+        if write_back == WriteBack.COLOR_DIFF:
             diff_contents = color_diff(diff_contents)
 
         with lock or nullcontext():

From fe4a9d6bee21c471139e07fa27b464187477556c Mon Sep 17 00:00:00 2001
From: James Addison <jay@jp-hosting.net>
Date: Mon, 22 Feb 2021 15:46:38 +0000
Subject: [PATCH 0098/1034] Fixup: update function name in docs to match source
 (#1997)

---
 docs/reference/reference_functions.rst |  2 +-
 src/black/__init__.py                  | 10 +++++-----
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/reference/reference_functions.rst b/docs/reference/reference_functions.rst
index a7184115c94..bffce7e9e32 100644
--- a/docs/reference/reference_functions.rst
+++ b/docs/reference/reference_functions.rst
@@ -171,7 +171,7 @@ Utilities
 
 .. autofunction:: black.re_compile_maybe_verbose
 
-.. autofunction:: black.should_split_body_explode
+.. autofunction:: black.should_split_line
 
 .. autofunction:: black.shutdown
 
diff --git a/src/black/__init__.py b/src/black/__init__.py
index e09f08df7df..07251d55fb5 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -1480,7 +1480,7 @@ class Line:
     comments: Dict[LeafID, List[Leaf]] = field(default_factory=dict)
     bracket_tracker: BracketTracker = field(default_factory=BracketTracker)
     inside_brackets: bool = False
-    should_split: bool = False
+    should_split_rhs: bool = False
     magic_trailing_comma: Optional[Leaf] = None
 
     def append(self, leaf: Leaf, preformatted: bool = False) -> None:
@@ -1792,7 +1792,7 @@ def clone(self) -> "Line":
             mode=self.mode,
             depth=self.depth,
             inside_brackets=self.inside_brackets,
-            should_split=self.should_split,
+            should_split_rhs=self.should_split_rhs,
             magic_trailing_comma=self.magic_trailing_comma,
         )
 
@@ -2712,7 +2712,7 @@ def init_st(ST: Type[StringTransformer]) -> StringTransformer:
     transformers: List[Transformer]
     if (
         not line.contains_uncollapsable_type_comments()
-        and not line.should_split
+        and not line.should_split_rhs
         and not line.magic_trailing_comma
         and (
             is_line_short_enough(line, line_length=mode.line_length, line_str=line_str)
@@ -4387,7 +4387,7 @@ def do_transform(self, line: Line, string_idx: int) -> Iterator[TResult[Line]]:
             mode=line.mode,
             depth=line.depth + 1,
             inside_brackets=True,
-            should_split=line.should_split,
+            should_split_rhs=line.should_split_rhs,
             magic_trailing_comma=line.magic_trailing_comma,
         )
         string_leaf = Leaf(token.STRING, string_value)
@@ -5010,7 +5010,7 @@ def bracket_split_build_line(
         for comment_after in original.comments_after(leaf):
             result.append(comment_after, preformatted=True)
     if is_body and should_split_line(result, opening_bracket):
-        result.should_split = True
+        result.should_split_rhs = True
     return result
 
 

From e1c86f987eca7e532f7d69f7ff4b9c70432fabbf Mon Sep 17 00:00:00 2001
From: James Addison <jay@jp-hosting.net>
Date: Mon, 22 Feb 2021 15:49:38 +0000
Subject: [PATCH 0099/1034] Fuzzer testing: less strict special-case regex
 match passthrough for multi-line EOF exceptions (#1998)

---
 fuzz.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/fuzz.py b/fuzz.py
index 6e2068690b5..a9ca8eff8b0 100644
--- a/fuzz.py
+++ b/fuzz.py
@@ -50,9 +50,9 @@ def test_idempotent_any_syntatically_valid_python(
         # TODO: remove this try-except block when issues are resolved.
         return
     except TokenError as e:
-        if (
+        if (  # Special-case logic for backslashes followed by newlines or end-of-input
             e.args[0] == "EOF in multi-line statement"
-            and re.search(r"\r?\n\\\r?\n", src_contents) is not None
+            and re.search(r"\\($|\r?\n)", src_contents) is not None
         ):
             # This is a bug - if it's valid Python code, as above, Black should be
             # able to cope with it.  See issue #1012.

From b06cd15666e5d766347cda0434dc6c828a96c74a Mon Sep 17 00:00:00 2001
From: tpilewicz <31728184+tpilewicz@users.noreply.github.com>
Date: Wed, 24 Feb 2021 12:56:56 +0100
Subject: [PATCH 0100/1034] Wrap arithmetic and binary arithmetic expressions
 in invisible parentheses (#2001)

---
 src/black/__init__.py                         | 13 ++++++++
 tests/data/expression.diff                    | 30 +++++++++++++++++--
 tests/data/expression.py                      | 24 +++++++++++++++
 .../expression_skip_magic_trailing_comma.diff | 30 +++++++++++++++++--
 4 files changed, 91 insertions(+), 6 deletions(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index 07251d55fb5..6919468609c 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -2049,6 +2049,8 @@ def visit_suite(self, node: Node) -> Iterator[Line]:
 
     def visit_simple_stmt(self, node: Node) -> Iterator[Line]:
         """Visit a statement without nested statements."""
+        if first_child_is_arith(node):
+            wrap_in_parentheses(node, node.children[0], visible=False)
         is_suite_like = node.parent and node.parent.type in STATEMENT
         if is_suite_like:
             if self.mode.is_pyi and is_stub_body(node):
@@ -5613,6 +5615,17 @@ def unwrap_singleton_parenthesis(node: LN) -> Optional[LN]:
     return wrapped
 
 
+def first_child_is_arith(node: Node) -> bool:
+    """Whether first child is an arithmetic or a binary arithmetic expression"""
+    expr_types = {
+        syms.arith_expr,
+        syms.shift_expr,
+        syms.xor_expr,
+        syms.and_expr,
+    }
+    return bool(node.children and node.children[0].type in expr_types)
+
+
 def wrap_in_parentheses(parent: Node, child: LN, *, visible: bool = True) -> None:
     """Wrap `child` in parentheses.
 
diff --git a/tests/data/expression.diff b/tests/data/expression.diff
index 684f92cd3b7..721a07d2141 100644
--- a/tests/data/expression.diff
+++ b/tests/data/expression.diff
@@ -166,7 +166,7 @@
  slice[0:1:2]
  slice[:]
  slice[:-1]
-@@ -137,113 +173,180 @@
+@@ -137,118 +173,199 @@
  numpy[-(c + 1) :, d]
  numpy[:, l[-2]]
  numpy[:, ::-1]
@@ -346,6 +346,9 @@
 -    return True
 -if (
 -    ~ aaaaaaaaaaaaaaaa.a + aaaaaaaaaaaaaaaa.b - aaaaaaaaaaaaaaaa.c * aaaaaaaaaaaaaaaa.d @ aaaaaaaaaaaaaaaa.e | aaaaaaaaaaaaaaaa.f & aaaaaaaaaaaaaaaa.g % aaaaaaaaaaaaaaaa.h ^ aaaaaaaaaaaaaaaa.i << aaaaaaaaaaaaaaaa.k >> aaaaaaaaaaaaaaaa.l ** aaaaaaaaaaaaaaaa.m // aaaaaaaaaaaaaaaa.n
+-):
+-    return True
+-aaaaaaaaaaaaaaaa + aaaaaaaaaaaaaaaa - aaaaaaaaaaaaaaaa * (aaaaaaaaaaaaaaaa + aaaaaaaaaaaaaaaa) / (aaaaaaaaaaaaaaaa + aaaaaaaaaaaaaaaa + aaaaaaaaaaaaaaaa)
 +a = (
 +    aaaa.bbbb.cccc.dddd.eeee.ffff.gggg.hhhh.iiii.jjjj.kkkk.llll.mmmm.nnnn.oooo.pppp
 +    in qqqq.rrrr.ssss.tttt.uuuu.vvvv.xxxx.yyyy.zzzz
@@ -417,7 +420,28 @@
 +    ^ aaaaaaaaaaaaaaaa.i
 +    << aaaaaaaaaaaaaaaa.k
 +    >> aaaaaaaaaaaaaaaa.l ** aaaaaaaaaaaaaaaa.m // aaaaaaaaaaaaaaaa.n
- ):
-     return True
++):
++    return True
++(
++    aaaaaaaaaaaaaaaa
++    + aaaaaaaaaaaaaaaa
++    - aaaaaaaaaaaaaaaa
++    * (aaaaaaaaaaaaaaaa + aaaaaaaaaaaaaaaa)
++    / (aaaaaaaaaaaaaaaa + aaaaaaaaaaaaaaaa + aaaaaaaaaaaaaaaa)
++)
+ aaaaaaaaaaaaaaaa + aaaaaaaaaaaaaaaa
+-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa >> aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa << aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
++(
++    aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
++    >> aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
++    << aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
++)
+ bbbb >> bbbb * bbbb
+-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa ^bbbb.a & aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa^aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
++(
++    aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
++    ^ bbbb.a & aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
++    ^ aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
++)
  last_call()
  # standalone comment at ENDMARKER
diff --git a/tests/data/expression.py b/tests/data/expression.py
index 8e63bdcdf9b..d13450cda68 100644
--- a/tests/data/expression.py
+++ b/tests/data/expression.py
@@ -245,6 +245,11 @@ async def f():
     ~ aaaaaaaaaaaaaaaa.a + aaaaaaaaaaaaaaaa.b - aaaaaaaaaaaaaaaa.c * aaaaaaaaaaaaaaaa.d @ aaaaaaaaaaaaaaaa.e | aaaaaaaaaaaaaaaa.f & aaaaaaaaaaaaaaaa.g % aaaaaaaaaaaaaaaa.h ^ aaaaaaaaaaaaaaaa.i << aaaaaaaaaaaaaaaa.k >> aaaaaaaaaaaaaaaa.l ** aaaaaaaaaaaaaaaa.m // aaaaaaaaaaaaaaaa.n
 ):
     return True
+aaaaaaaaaaaaaaaa + aaaaaaaaaaaaaaaa - aaaaaaaaaaaaaaaa * (aaaaaaaaaaaaaaaa + aaaaaaaaaaaaaaaa) / (aaaaaaaaaaaaaaaa + aaaaaaaaaaaaaaaa + aaaaaaaaaaaaaaaa)
+aaaaaaaaaaaaaaaa + aaaaaaaaaaaaaaaa
+aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa >> aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa << aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+bbbb >> bbbb * bbbb
+aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa ^bbbb.a & aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa^aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
 last_call()
 # standalone comment at ENDMARKER
 
@@ -602,5 +607,24 @@ async def f():
     >> aaaaaaaaaaaaaaaa.l ** aaaaaaaaaaaaaaaa.m // aaaaaaaaaaaaaaaa.n
 ):
     return True
+(
+    aaaaaaaaaaaaaaaa
+    + aaaaaaaaaaaaaaaa
+    - aaaaaaaaaaaaaaaa
+    * (aaaaaaaaaaaaaaaa + aaaaaaaaaaaaaaaa)
+    / (aaaaaaaaaaaaaaaa + aaaaaaaaaaaaaaaa + aaaaaaaaaaaaaaaa)
+)
+aaaaaaaaaaaaaaaa + aaaaaaaaaaaaaaaa
+(
+    aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+    >> aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+    << aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+)
+bbbb >> bbbb * bbbb
+(
+    aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+    ^ bbbb.a & aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+    ^ aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+)
 last_call()
 # standalone comment at ENDMARKER
diff --git a/tests/data/expression_skip_magic_trailing_comma.diff b/tests/data/expression_skip_magic_trailing_comma.diff
index 8a0225bceb5..4a8a95c7237 100644
--- a/tests/data/expression_skip_magic_trailing_comma.diff
+++ b/tests/data/expression_skip_magic_trailing_comma.diff
@@ -149,7 +149,7 @@
  slice[0:1:2]
  slice[:]
  slice[:-1]
-@@ -137,113 +156,178 @@
+@@ -137,118 +156,197 @@
  numpy[-(c + 1) :, d]
  numpy[:, l[-2]]
  numpy[:, ::-1]
@@ -327,6 +327,9 @@
 -    return True
 -if (
 -    ~ aaaaaaaaaaaaaaaa.a + aaaaaaaaaaaaaaaa.b - aaaaaaaaaaaaaaaa.c * aaaaaaaaaaaaaaaa.d @ aaaaaaaaaaaaaaaa.e | aaaaaaaaaaaaaaaa.f & aaaaaaaaaaaaaaaa.g % aaaaaaaaaaaaaaaa.h ^ aaaaaaaaaaaaaaaa.i << aaaaaaaaaaaaaaaa.k >> aaaaaaaaaaaaaaaa.l ** aaaaaaaaaaaaaaaa.m // aaaaaaaaaaaaaaaa.n
+-):
+-    return True
+-aaaaaaaaaaaaaaaa + aaaaaaaaaaaaaaaa - aaaaaaaaaaaaaaaa * (aaaaaaaaaaaaaaaa + aaaaaaaaaaaaaaaa) / (aaaaaaaaaaaaaaaa + aaaaaaaaaaaaaaaa + aaaaaaaaaaaaaaaa)
 +a = (
 +    aaaa.bbbb.cccc.dddd.eeee.ffff.gggg.hhhh.iiii.jjjj.kkkk.llll.mmmm.nnnn.oooo.pppp
 +    in qqqq.rrrr.ssss.tttt.uuuu.vvvv.xxxx.yyyy.zzzz
@@ -398,7 +401,28 @@
 +    ^ aaaaaaaaaaaaaaaa.i
 +    << aaaaaaaaaaaaaaaa.k
 +    >> aaaaaaaaaaaaaaaa.l ** aaaaaaaaaaaaaaaa.m // aaaaaaaaaaaaaaaa.n
- ):
-     return True
++):
++    return True
++(
++    aaaaaaaaaaaaaaaa
++    + aaaaaaaaaaaaaaaa
++    - aaaaaaaaaaaaaaaa
++    * (aaaaaaaaaaaaaaaa + aaaaaaaaaaaaaaaa)
++    / (aaaaaaaaaaaaaaaa + aaaaaaaaaaaaaaaa + aaaaaaaaaaaaaaaa)
++)
+ aaaaaaaaaaaaaaaa + aaaaaaaaaaaaaaaa
+-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa >> aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa << aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
++(
++    aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
++    >> aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
++    << aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
++)
+ bbbb >> bbbb * bbbb
+-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa ^bbbb.a & aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa^aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
++(
++    aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
++    ^ bbbb.a & aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
++    ^ aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
++)
  last_call()
  # standalone comment at ENDMARKER

From 858225d34dc49ca353f9e573dd82dd5845766115 Mon Sep 17 00:00:00 2001
From: Rishav Kundu <rk@rishav.io>
Date: Sun, 28 Feb 2021 06:50:23 +0530
Subject: [PATCH 0101/1034] Strip redundant parentheses from assignment exprs
 (#1906)

Fixes #1656
---
 src/black/__init__.py               | 10 +++++---
 tests/data/pep_572.py               |  4 +--
 tests/data/pep_572_remove_parens.py | 38 +++++++++++++++++++++++++++++
 tests/data/remove_parens.py         |  2 --
 tests/test_black.py                 |  9 +++++++
 5 files changed, 55 insertions(+), 8 deletions(-)
 create mode 100644 tests/data/pep_572_remove_parens.py

diff --git a/src/black/__init__.py b/src/black/__init__.py
index 6919468609c..a1d16d9bdeb 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -5370,10 +5370,7 @@ def normalize_invisible_parens(node: Node, parens_after: Set[str]) -> None:
             check_lpar = True
 
         if check_lpar:
-            if is_walrus_assignment(child):
-                pass
-
-            elif child.type == syms.atom:
+            if child.type == syms.atom:
                 if maybe_make_parens_invisible_in_atom(child, parent=node):
                     wrap_in_parentheses(node, child, visible=False)
             elif is_one_tuple(child):
@@ -5545,6 +5542,7 @@ def maybe_make_parens_invisible_in_atom(node: LN, parent: LN) -> bool:
     Returns whether the node should itself be wrapped in invisible parentheses.
 
     """
+
     if (
         node.type != syms.atom
         or is_empty_tuple(node)
@@ -5554,6 +5552,10 @@ def maybe_make_parens_invisible_in_atom(node: LN, parent: LN) -> bool:
     ):
         return False
 
+    if is_walrus_assignment(node):
+        if parent.type in [syms.annassign, syms.expr_stmt]:
+            return False
+
     first = node.children[0]
     last = node.children[-1]
     if first.type == token.LPAR and last.type == token.RPAR:
diff --git a/tests/data/pep_572.py b/tests/data/pep_572.py
index 637b3bb38c6..c6867f26258 100644
--- a/tests/data/pep_572.py
+++ b/tests/data/pep_572.py
@@ -2,7 +2,7 @@
 (a := a)
 if (match := pattern.search(data)) is None:
     pass
-if (match := pattern.search(data)):
+if match := pattern.search(data):
     pass
 [y := f(x), y ** 2, y ** 3]
 filtered_data = [y for x in data if (y := f(x)) is None]
@@ -43,5 +43,5 @@ def foo(answer: (p := 42) = 5):
 
 while x := f(x):
     pass
-while (x := f(x)):
+while x := f(x):
     pass
diff --git a/tests/data/pep_572_remove_parens.py b/tests/data/pep_572_remove_parens.py
new file mode 100644
index 00000000000..04cc75bc36c
--- /dev/null
+++ b/tests/data/pep_572_remove_parens.py
@@ -0,0 +1,38 @@
+if (foo := 0):
+    pass
+
+if (foo := 1):
+    pass
+
+if (y := 5 + 5):
+    pass
+
+y = (x := 0)
+
+y += (x := 0)
+
+(y := 5 + 5)
+
+test: int = (test2 := 2)
+
+a, b = (test := (1, 2))
+
+# output
+if foo := 0:
+    pass
+
+if foo := 1:
+    pass
+
+if y := 5 + 5:
+    pass
+
+y = (x := 0)
+
+y += (x := 0)
+
+(y := 5 + 5)
+
+test: int = (test2 := 2)
+
+a, b = (test := (1, 2))
diff --git a/tests/data/remove_parens.py b/tests/data/remove_parens.py
index afc34010c30..abd5f71fcd0 100644
--- a/tests/data/remove_parens.py
+++ b/tests/data/remove_parens.py
@@ -54,7 +54,6 @@ def example7():
 def example8():
     return (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((None)))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))
 
-
 # output
 x = 1
 x = 1.2
@@ -141,4 +140,3 @@ def example7():
 
 def example8():
     return None
-
diff --git a/tests/test_black.py b/tests/test_black.py
index 5d14ceda8f4..9c3cc64387b 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -263,6 +263,15 @@ def test_pep_572(self) -> None:
         if sys.version_info >= (3, 8):
             black.assert_equivalent(source, actual)
 
+    @patch("black.dump_to_file", dump_to_stderr)
+    def test_pep_572_remove_parens(self) -> None:
+        source, expected = read_data("pep_572_remove_parens")
+        actual = fs(source)
+        self.assertFormatEqual(expected, actual)
+        black.assert_stable(source, actual, DEFAULT_MODE)
+        if sys.version_info >= (3, 8):
+            black.assert_equivalent(source, actual)
+
     def test_pep_572_version_detection(self) -> None:
         source, _ = read_data("pep_572")
         root = black.lib2to3_parse(source)

From beecd6fd0a9103aa91b1019dcf8fc774b667ea6c Mon Sep 17 00:00:00 2001
From: Joshua Cannon <joshua.cannon@ni.com>
Date: Mon, 1 Mar 2021 16:07:36 -0600
Subject: [PATCH 0102/1034] Add --extend-exclude parameter (#2005)

Look ma! I contribute to open source!

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 README.md                      | 30 +++++-------
 docs/change_log.md             |  2 +
 docs/installation_and_usage.md |  7 ++-
 docs/pyproject_toml.md         | 22 ++-------
 pyproject.toml                 | 13 +----
 src/black/__init__.py          | 78 ++++++++++++++++++++----------
 tests/test_black.py            | 86 ++++++++++++++++++++++++++++------
 7 files changed, 148 insertions(+), 90 deletions(-)

diff --git a/README.md b/README.md
index 178f763c32d..5f8b52cb823 100644
--- a/README.md
+++ b/README.md
@@ -135,11 +135,17 @@ Options:
                                   hg|\.mypy_cache|\.nox|\.tox|\.venv|\.svn|_bu
                                   ild|buck-out|build|dist)/]
 
+  --extend-exclude TEXT           Like --exclude, but adds additional files
+                                  and directories on top of the excluded
+                                  ones (useful if you simply want to add to
+                                  the default).
+
   --force-exclude TEXT            Like --exclude, but files and directories
                                   matching this regex will be excluded even
                                   when they are passed explicitly as
                                   arguments.
 
+
   --stdin-filename TEXT           The name of the file when passing it through
                                   stdin. Useful to make sure Black will
                                   respect --force-exclude option on some
@@ -151,7 +157,7 @@ Options:
 
   -v, --verbose                   Also emit messages to stderr about files
                                   that were not changed or were ignored due to
-                                  --exclude=.
+                                  exclusion patterns.
 
   --version                       Show the version and exit.
   --config FILE                   Read configuration from FILE path.
@@ -263,7 +269,7 @@ above. What seems like a bug might be intended behaviour.
 
 _Black_ is able to read project-specific default values for its command line options
 from a `pyproject.toml` file. This is especially useful for specifying custom
-`--include` and `--exclude` patterns for your project.
+`--include` and `--exclude`/`--extend-exclude` patterns for your project.
 
 **Pro-tip**: If you're asking yourself "Do I need to configure anything?" the answer is
 "No". _Black_ is all about sensible defaults.
@@ -313,25 +319,10 @@ expressions by Black. Use `[ ]` to denote a significant space character.
 line-length = 88
 target-version = ['py37']
 include = '\.pyi?$'
-exclude = '''
+extend-exclude = '''
 # A regex preceded with ^/ will apply only to files and directories
 # in the root of the project.
-^/(
-  (
-      \.eggs         # exclude a few common directories in the
-    | \.git          # root of the project
-    | \.hg
-    | \.mypy_cache
-    | \.tox
-    | \.venv
-    | _build
-    | buck-out
-    | build
-    | dist
-  )/
-  | foo.py           # also separately exclude a file named foo.py in
-                     # the root of the project
-)
+^/foo.py  # exclude a file named foo.py in the root of the project (in addition to the defaults)
 '''
 ```
 
@@ -616,6 +607,7 @@ Multiple contributions by:
 - [Joseph Larson](mailto:larson.joseph@gmail.com)
 - [Josh Bode](mailto:joshbode@fastmail.com)
 - [Josh Holland](mailto:anowlcalledjosh@gmail.com)
+- [Joshua Cannon](mailto:joshdcannon@gmail.com)
 - [José Padilla](mailto:jpadilla@webapplicate.com)
 - [Juan Luis Cano Rodríguez](mailto:hello@juanlu.space)
 - [kaiix](mailto:kvn.hou@gmail.com)
diff --git a/docs/change_log.md b/docs/change_log.md
index 066be76c06c..01c27553fca 100644
--- a/docs/change_log.md
+++ b/docs/change_log.md
@@ -28,6 +28,8 @@
 
 - use lowercase hex strings (#1692)
 
+- added `--extend-exclude` argument (#1571)
+
 #### _Packaging_
 
 - Self-contained native _Black_ binaries are now provided for releases via GitHub
diff --git a/docs/installation_and_usage.md b/docs/installation_and_usage.md
index ee45c934da8..bb554eb6744 100644
--- a/docs/installation_and_usage.md
+++ b/docs/installation_and_usage.md
@@ -95,6 +95,11 @@ Options:
                                   when they are passed explicitly as
                                   arguments.
 
+  --extend-exclude TEXT           Like --exclude, but adds additional files
+                                  and directories on top of the excluded
+                                  ones. (useful if you simply want to add to
+                                  the default)
+
   --stdin-filename TEXT           The name of the file when passing it through
                                   stdin. Useful to make sure Black will
                                   respect --force-exclude option on some
@@ -106,7 +111,7 @@ Options:
 
   -v, --verbose                   Also emit messages to stderr about files
                                   that were not changed or were ignored due to
-                                  --exclude=.
+                                  exclusion patterns.
 
   --version                       Show the version and exit.
   --config FILE                   Read configuration from FILE path.
diff --git a/docs/pyproject_toml.md b/docs/pyproject_toml.md
index 453f533bf96..9acc4c03d7c 100644
--- a/docs/pyproject_toml.md
+++ b/docs/pyproject_toml.md
@@ -4,7 +4,8 @@
 
 _Black_ is able to read project-specific default values for its command line options
 from a `pyproject.toml` file. This is especially useful for specifying custom
-`--include` and `--exclude` patterns for your project.
+`--include` and `--exclude`/`--force-exclude`/`--extend-exclude` patterns for your
+project.
 
 **Pro-tip**: If you're asking yourself "Do I need to configure anything?" the answer is
 "No". _Black_ is all about sensible defaults.
@@ -54,25 +55,10 @@ expressions by Black. Use `[ ]` to denote a significant space character.
 line-length = 88
 target-version = ['py37']
 include = '\.pyi?$'
-exclude = '''
+extend-exclude = '''
 # A regex preceded with ^/ will apply only to files and directories
 # in the root of the project.
-^/(
-  (
-      \.eggs         # exclude a few common directories in the
-    | \.git          # root of the project
-    | \.hg
-    | \.mypy_cache
-    | \.tox
-    | \.venv
-    | _build
-    | buck-out
-    | build
-    | dist
-  )/
-  | foo.py           # also separately exclude a file named foo.py in
-                     # the root of the project
-)
+^/foo.py  # exclude a file named foo.py in the root of the project (in addition to the defaults)
 '''
 ```
 
diff --git a/pyproject.toml b/pyproject.toml
index 9d4da0bf692..7f632f2839d 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -9,19 +9,8 @@
 line-length = 88
 target-version = ['py36', 'py37', 'py38']
 include = '\.pyi?$'
-exclude = '''
+extend-exclude = '''
 /(
-    \.eggs
-  | \.git
-  | \.hg
-  | \.mypy_cache
-  | \.tox
-  | \.venv
-  | _build
-  | buck-out
-  | build
-  | dist
-
   # The following are specific to Black, you probably don't want those.
   | blib2to3
   | tests/data
diff --git a/src/black/__init__.py b/src/black/__init__.py
index a1d16d9bdeb..e21e2af5bd1 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -461,6 +461,14 @@ def target_version_option_callback(
     ),
     show_default=True,
 )
+@click.option(
+    "--extend-exclude",
+    type=str,
+    help=(
+        "Like --exclude, but adds additional files and directories on top of the"
+        " excluded ones. (Useful if you simply want to add to the default)"
+    ),
+)
 @click.option(
     "--force-exclude",
     type=str,
@@ -493,7 +501,7 @@ def target_version_option_callback(
     is_flag=True,
     help=(
         "Also emit messages to stderr about files that were not changed or were ignored"
-        " due to --exclude=."
+        " due to exclusion patterns."
     ),
 )
 @click.version_option(version=__version__)
@@ -537,6 +545,7 @@ def main(
     verbose: bool,
     include: str,
     exclude: str,
+    extend_exclude: Optional[str],
     force_exclude: Optional[str],
     stdin_filename: Optional[str],
     src: Tuple[str, ...],
@@ -570,6 +579,7 @@ def main(
         verbose=verbose,
         include=include,
         exclude=exclude,
+        extend_exclude=extend_exclude,
         force_exclude=force_exclude,
         report=report,
         stdin_filename=stdin_filename,
@@ -602,6 +612,18 @@ def main(
     ctx.exit(report.return_code)
 
 
+def test_regex(
+    ctx: click.Context,
+    regex_name: str,
+    regex: Optional[str],
+) -> Optional[Pattern]:
+    try:
+        return re_compile_maybe_verbose(regex) if regex is not None else None
+    except re.error:
+        err(f"Invalid regular expression for {regex_name} given: {regex!r}")
+        ctx.exit(2)
+
+
 def get_sources(
     *,
     ctx: click.Context,
@@ -610,28 +632,18 @@ def get_sources(
     verbose: bool,
     include: str,
     exclude: str,
+    extend_exclude: Optional[str],
     force_exclude: Optional[str],
     report: "Report",
     stdin_filename: Optional[str],
 ) -> Set[Path]:
     """Compute the set of files to be formatted."""
-    try:
-        include_regex = re_compile_maybe_verbose(include)
-    except re.error:
-        err(f"Invalid regular expression for include given: {include!r}")
-        ctx.exit(2)
-    try:
-        exclude_regex = re_compile_maybe_verbose(exclude)
-    except re.error:
-        err(f"Invalid regular expression for exclude given: {exclude!r}")
-        ctx.exit(2)
-    try:
-        force_exclude_regex = (
-            re_compile_maybe_verbose(force_exclude) if force_exclude else None
-        )
-    except re.error:
-        err(f"Invalid regular expression for force_exclude given: {force_exclude!r}")
-        ctx.exit(2)
+
+    include_regex = test_regex(ctx, "include", include)
+    exclude_regex = test_regex(ctx, "exclude", exclude)
+    assert exclude_regex is not None
+    extend_exclude_regex = test_regex(ctx, "extend_exclude", extend_exclude)
+    force_exclude_regex = test_regex(ctx, "force_exclude", force_exclude)
 
     root = find_project_root(src)
     sources: Set[Path] = set()
@@ -672,6 +684,7 @@ def get_sources(
                     root,
                     include_regex,
                     exclude_regex,
+                    extend_exclude_regex,
                     force_exclude_regex,
                     report,
                     gitignore,
@@ -6112,17 +6125,27 @@ def normalize_path_maybe_ignore(
     return normalized_path
 
 
+def path_is_excluded(
+    normalized_path: str,
+    pattern: Optional[Pattern[str]],
+) -> bool:
+    match = pattern.search(normalized_path) if pattern else None
+    return bool(match and match.group(0))
+
+
 def gen_python_files(
     paths: Iterable[Path],
     root: Path,
     include: Optional[Pattern[str]],
     exclude: Pattern[str],
+    extend_exclude: Optional[Pattern[str]],
     force_exclude: Optional[Pattern[str]],
     report: "Report",
     gitignore: PathSpec,
 ) -> Iterator[Path]:
     """Generate all files under `path` whose paths are not excluded by the
-    `exclude_regex` or `force_exclude` regexes, but are included by the `include` regex.
+    `exclude_regex`, `extend_exclude`, or `force_exclude` regexes,
+    but are included by the `include` regex.
 
     Symbolic links pointing outside of the `root` directory are ignored.
 
@@ -6139,20 +6162,22 @@ def gen_python_files(
             report.path_ignored(child, "matches the .gitignore file content")
             continue
 
-        # Then ignore with `--exclude` and `--force-exclude` options.
+        # Then ignore with `--exclude` `--extend-exclude` and `--force-exclude` options.
         normalized_path = "/" + normalized_path
         if child.is_dir():
             normalized_path += "/"
 
-        exclude_match = exclude.search(normalized_path) if exclude else None
-        if exclude_match and exclude_match.group(0):
+        if path_is_excluded(normalized_path, exclude):
             report.path_ignored(child, "matches the --exclude regular expression")
             continue
 
-        force_exclude_match = (
-            force_exclude.search(normalized_path) if force_exclude else None
-        )
-        if force_exclude_match and force_exclude_match.group(0):
+        if path_is_excluded(normalized_path, extend_exclude):
+            report.path_ignored(
+                child, "matches the --extend-exclude regular expression"
+            )
+            continue
+
+        if path_is_excluded(normalized_path, force_exclude):
             report.path_ignored(child, "matches the --force-exclude regular expression")
             continue
 
@@ -6162,6 +6187,7 @@ def gen_python_files(
                 root,
                 include,
                 exclude,
+                extend_exclude,
                 force_exclude,
                 report,
                 gitignore,
diff --git a/tests/test_black.py b/tests/test_black.py
index 9c3cc64387b..ba1869aa4c5 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -1346,7 +1346,14 @@ def test_include_exclude(self) -> None:
         this_abs = THIS_DIR.resolve()
         sources.extend(
             black.gen_python_files(
-                path.iterdir(), this_abs, include, exclude, None, report, gitignore
+                path.iterdir(),
+                this_abs,
+                include,
+                exclude,
+                None,
+                None,
+                report,
+                gitignore,
             )
         )
         self.assertEqual(sorted(expected), sorted(sources))
@@ -1370,6 +1377,7 @@ def test_exclude_for_issue_1572(self) -> None:
                 verbose=False,
                 include=include,
                 exclude=exclude,
+                extend_exclude=None,
                 force_exclude=None,
                 report=report,
                 stdin_filename=None,
@@ -1392,6 +1400,7 @@ def test_get_sources_with_stdin(self) -> None:
                 verbose=False,
                 include=include,
                 exclude=exclude,
+                extend_exclude=None,
                 force_exclude=None,
                 report=report,
                 stdin_filename=None,
@@ -1415,6 +1424,7 @@ def test_get_sources_with_stdin_filename(self) -> None:
                 verbose=False,
                 include=include,
                 exclude=exclude,
+                extend_exclude=None,
                 force_exclude=None,
                 report=report,
                 stdin_filename=stdin_filename,
@@ -1442,6 +1452,35 @@ def test_get_sources_with_stdin_filename_and_exclude(self) -> None:
                 verbose=False,
                 include=include,
                 exclude=exclude,
+                extend_exclude=None,
+                force_exclude=None,
+                report=report,
+                stdin_filename=stdin_filename,
+            )
+        )
+        self.assertEqual(sorted(expected), sorted(sources))
+
+    @patch("black.find_project_root", lambda *args: THIS_DIR.resolve())
+    def test_get_sources_with_stdin_filename_and_extend_exclude(self) -> None:
+        # Extend exclude shouldn't exclude stdin_filename since it is mimicking the
+        # file being passed directly. This is the same as
+        # test_exclude_for_issue_1572
+        path = THIS_DIR / "data" / "include_exclude_tests"
+        include = ""
+        extend_exclude = r"/exclude/|a\.py"
+        src = "-"
+        report = black.Report()
+        stdin_filename = str(path / "b/exclude/a.py")
+        expected = [Path(f"__BLACK_STDIN_FILENAME__{stdin_filename}")]
+        sources = list(
+            black.get_sources(
+                ctx=FakeContext(),
+                src=(src,),
+                quiet=True,
+                verbose=False,
+                include=include,
+                exclude="",
+                extend_exclude=extend_exclude,
                 force_exclude=None,
                 report=report,
                 stdin_filename=stdin_filename,
@@ -1467,6 +1506,7 @@ def test_get_sources_with_stdin_filename_and_force_exclude(self) -> None:
                 verbose=False,
                 include=include,
                 exclude="",
+                extend_exclude=None,
                 force_exclude=force_exclude,
                 report=report,
                 stdin_filename=stdin_filename,
@@ -1551,7 +1591,14 @@ def test_gitignore_exclude(self) -> None:
         this_abs = THIS_DIR.resolve()
         sources.extend(
             black.gen_python_files(
-                path.iterdir(), this_abs, include, exclude, None, report, gitignore
+                path.iterdir(),
+                this_abs,
+                include,
+                exclude,
+                None,
+                None,
+                report,
+                gitignore,
             )
         )
         self.assertEqual(sorted(expected), sorted(sources))
@@ -1581,25 +1628,21 @@ def test_empty_include(self) -> None:
                 empty,
                 re.compile(black.DEFAULT_EXCLUDES),
                 None,
+                None,
                 report,
                 gitignore,
             )
         )
         self.assertEqual(sorted(expected), sorted(sources))
 
-    def test_empty_exclude(self) -> None:
+    def test_extend_exclude(self) -> None:
         path = THIS_DIR / "data" / "include_exclude_tests"
         report = black.Report()
         gitignore = PathSpec.from_lines("gitwildmatch", [])
-        empty = re.compile(r"")
         sources: List[Path] = []
         expected = [
-            Path(path / "b/dont_exclude/a.py"),
-            Path(path / "b/dont_exclude/a.pyi"),
             Path(path / "b/exclude/a.py"),
-            Path(path / "b/exclude/a.pyi"),
-            Path(path / "b/.definitely_exclude/a.py"),
-            Path(path / "b/.definitely_exclude/a.pyi"),
+            Path(path / "b/dont_exclude/a.py"),
         ]
         this_abs = THIS_DIR.resolve()
         sources.extend(
@@ -1607,7 +1650,8 @@ def test_empty_exclude(self) -> None:
                 path.iterdir(),
                 this_abs,
                 re.compile(black.DEFAULT_INCLUDES),
-                empty,
+                re.compile(r"\.pyi$"),
+                re.compile(r"\.definitely_exclude"),
                 None,
                 report,
                 gitignore,
@@ -1615,8 +1659,8 @@ def test_empty_exclude(self) -> None:
         )
         self.assertEqual(sorted(expected), sorted(sources))
 
-    def test_invalid_include_exclude(self) -> None:
-        for option in ["--include", "--exclude"]:
+    def test_invalid_cli_regex(self) -> None:
+        for option in ["--include", "--exclude", "--extend-exclude", "--force-exclude"]:
             self.invokeBlack(["-", option, "**()(!!*)"], exit_code=2)
 
     def test_preserves_line_endings(self) -> None:
@@ -1665,7 +1709,14 @@ def test_symlink_out_of_root_directory(self) -> None:
         try:
             list(
                 black.gen_python_files(
-                    path.iterdir(), root, include, exclude, None, report, gitignore
+                    path.iterdir(),
+                    root,
+                    include,
+                    exclude,
+                    None,
+                    None,
+                    report,
+                    gitignore,
                 )
             )
         except ValueError as ve:
@@ -1679,7 +1730,14 @@ def test_symlink_out_of_root_directory(self) -> None:
         with self.assertRaises(ValueError):
             list(
                 black.gen_python_files(
-                    path.iterdir(), root, include, exclude, None, report, gitignore
+                    path.iterdir(),
+                    root,
+                    include,
+                    exclude,
+                    None,
+                    None,
+                    report,
+                    gitignore,
                 )
             )
         path.iterdir.assert_called()

From cac18293d5a6bd6b34a953f9cb5413f9826e505f Mon Sep 17 00:00:00 2001
From: Austin Pray <71290498+austinpray-mixpanel@users.noreply.github.com>
Date: Mon, 1 Mar 2021 18:35:57 -0600
Subject: [PATCH 0103/1034] Adds --stdin-filename back to changelog (#2017)

* Adds --stdin-filename back to changelog

Looks like this went missing https://github.com/psf/black/commit/dea81b7ad5cfa04c3572771c34af823449d0a8f3#diff-729efdd61772b108539268bdbfd7472521bdc05a7cae6113f62ed2649a3ad9c7

* Update CHANGES.md

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>

* Update CHANGES.md

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 CHANGES.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/CHANGES.md b/CHANGES.md
index 3fd7ad40496..90e5143fafe 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -30,6 +30,9 @@
 
 - `--diff` correctly indicates when a file doesn't end in a newline (#1662)
 
+- Added `--stdin-filename` argument to allow stdin to respect `--force-exclude` rules
+  (#1780)
+
 #### _Packaging_
 
 - Self-contained native _Black_ binaries are now provided for releases via GitHub

From e3c71c3a477a44e6d817d37825a59bc6ba6a9897 Mon Sep 17 00:00:00 2001
From: Joshua Cannon <joshdcannon@gmail.com>
Date: Tue, 2 Mar 2021 19:21:50 -0600
Subject: [PATCH 0104/1034] Turn test_regex into a click callback (#2016)

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 src/black/__init__.py | 61 ++++++++++++++++++++-----------------------
 tests/test_black.py   | 28 ++++++++++----------
 2 files changed, 43 insertions(+), 46 deletions(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index e21e2af5bd1..a8f4f89a6bb 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -363,6 +363,17 @@ def target_version_option_callback(
     return [TargetVersion[val.upper()] for val in v]
 
 
+def validate_regex(
+    ctx: click.Context,
+    param: click.Parameter,
+    value: Optional[str],
+) -> Optional[Pattern]:
+    try:
+        return re_compile_maybe_verbose(value) if value is not None else None
+    except re.error:
+        raise click.BadParameter("Not a valid regular expression")
+
+
 @click.command(context_settings=dict(help_option_names=["-h", "--help"]))
 @click.option("-c", "--code", type=str, help="Format the code passed in as a string.")
 @click.option(
@@ -441,6 +452,7 @@ def target_version_option_callback(
     "--include",
     type=str,
     default=DEFAULT_INCLUDES,
+    callback=validate_regex,
     help=(
         "A regular expression that matches files and directories that should be"
         " included on recursive searches.  An empty value means all files are included"
@@ -453,6 +465,7 @@ def target_version_option_callback(
     "--exclude",
     type=str,
     default=DEFAULT_EXCLUDES,
+    callback=validate_regex,
     help=(
         "A regular expression that matches files and directories that should be"
         " excluded on recursive searches.  An empty value means no paths are excluded."
@@ -464,6 +477,7 @@ def target_version_option_callback(
 @click.option(
     "--extend-exclude",
     type=str,
+    callback=validate_regex,
     help=(
         "Like --exclude, but adds additional files and directories on top of the"
         " excluded ones. (Useful if you simply want to add to the default)"
@@ -472,6 +486,7 @@ def target_version_option_callback(
 @click.option(
     "--force-exclude",
     type=str,
+    callback=validate_regex,
     help=(
         "Like --exclude, but files and directories matching this regex will be "
         "excluded even when they are passed explicitly as arguments."
@@ -543,10 +558,10 @@ def main(
     experimental_string_processing: bool,
     quiet: bool,
     verbose: bool,
-    include: str,
-    exclude: str,
-    extend_exclude: Optional[str],
-    force_exclude: Optional[str],
+    include: Pattern,
+    exclude: Pattern,
+    extend_exclude: Optional[Pattern],
+    force_exclude: Optional[Pattern],
     stdin_filename: Optional[str],
     src: Tuple[str, ...],
     config: Optional[str],
@@ -612,39 +627,21 @@ def main(
     ctx.exit(report.return_code)
 
 
-def test_regex(
-    ctx: click.Context,
-    regex_name: str,
-    regex: Optional[str],
-) -> Optional[Pattern]:
-    try:
-        return re_compile_maybe_verbose(regex) if regex is not None else None
-    except re.error:
-        err(f"Invalid regular expression for {regex_name} given: {regex!r}")
-        ctx.exit(2)
-
-
 def get_sources(
     *,
     ctx: click.Context,
     src: Tuple[str, ...],
     quiet: bool,
     verbose: bool,
-    include: str,
-    exclude: str,
-    extend_exclude: Optional[str],
-    force_exclude: Optional[str],
+    include: Pattern[str],
+    exclude: Pattern[str],
+    extend_exclude: Optional[Pattern[str]],
+    force_exclude: Optional[Pattern[str]],
     report: "Report",
     stdin_filename: Optional[str],
 ) -> Set[Path]:
     """Compute the set of files to be formatted."""
 
-    include_regex = test_regex(ctx, "include", include)
-    exclude_regex = test_regex(ctx, "exclude", exclude)
-    assert exclude_regex is not None
-    extend_exclude_regex = test_regex(ctx, "extend_exclude", extend_exclude)
-    force_exclude_regex = test_regex(ctx, "force_exclude", force_exclude)
-
     root = find_project_root(src)
     sources: Set[Path] = set()
     path_empty(src, "No Path provided. Nothing to do 😴", quiet, verbose, ctx)
@@ -665,8 +662,8 @@ def get_sources(
 
             normalized_path = "/" + normalized_path
             # Hard-exclude any files that matches the `--force-exclude` regex.
-            if force_exclude_regex:
-                force_exclude_match = force_exclude_regex.search(normalized_path)
+            if force_exclude:
+                force_exclude_match = force_exclude.search(normalized_path)
             else:
                 force_exclude_match = None
             if force_exclude_match and force_exclude_match.group(0):
@@ -682,10 +679,10 @@ def get_sources(
                 gen_python_files(
                     p.iterdir(),
                     root,
-                    include_regex,
-                    exclude_regex,
-                    extend_exclude_regex,
-                    force_exclude_regex,
+                    include,
+                    exclude,
+                    extend_exclude,
+                    force_exclude,
                     report,
                     gitignore,
                 )
diff --git a/tests/test_black.py b/tests/test_black.py
index ba1869aa4c5..72e16a324a5 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -1375,8 +1375,8 @@ def test_exclude_for_issue_1572(self) -> None:
                 src=(src,),
                 quiet=True,
                 verbose=False,
-                include=include,
-                exclude=exclude,
+                include=re.compile(include),
+                exclude=re.compile(exclude),
                 extend_exclude=None,
                 force_exclude=None,
                 report=report,
@@ -1398,8 +1398,8 @@ def test_get_sources_with_stdin(self) -> None:
                 src=(src,),
                 quiet=True,
                 verbose=False,
-                include=include,
-                exclude=exclude,
+                include=re.compile(include),
+                exclude=re.compile(exclude),
                 extend_exclude=None,
                 force_exclude=None,
                 report=report,
@@ -1422,8 +1422,8 @@ def test_get_sources_with_stdin_filename(self) -> None:
                 src=(src,),
                 quiet=True,
                 verbose=False,
-                include=include,
-                exclude=exclude,
+                include=re.compile(include),
+                exclude=re.compile(exclude),
                 extend_exclude=None,
                 force_exclude=None,
                 report=report,
@@ -1450,8 +1450,8 @@ def test_get_sources_with_stdin_filename_and_exclude(self) -> None:
                 src=(src,),
                 quiet=True,
                 verbose=False,
-                include=include,
-                exclude=exclude,
+                include=re.compile(include),
+                exclude=re.compile(exclude),
                 extend_exclude=None,
                 force_exclude=None,
                 report=report,
@@ -1478,9 +1478,9 @@ def test_get_sources_with_stdin_filename_and_extend_exclude(self) -> None:
                 src=(src,),
                 quiet=True,
                 verbose=False,
-                include=include,
-                exclude="",
-                extend_exclude=extend_exclude,
+                include=re.compile(include),
+                exclude=re.compile(""),
+                extend_exclude=re.compile(extend_exclude),
                 force_exclude=None,
                 report=report,
                 stdin_filename=stdin_filename,
@@ -1504,10 +1504,10 @@ def test_get_sources_with_stdin_filename_and_force_exclude(self) -> None:
                 src=(src,),
                 quiet=True,
                 verbose=False,
-                include=include,
-                exclude="",
+                include=re.compile(include),
+                exclude=re.compile(""),
                 extend_exclude=None,
-                force_exclude=force_exclude,
+                force_exclude=re.compile(force_exclude),
                 report=report,
                 stdin_filename=stdin_filename,
             )

From e293473ea9c6a4408d4eb489d9d61fc87dbec639 Mon Sep 17 00:00:00 2001
From: Utkarsh Gupta <utkarshgupta137@gmail.com>
Date: Thu, 4 Mar 2021 06:16:27 +0530
Subject: [PATCH 0105/1034] Add formatters-python for atom to
 editor_integration (#1834)

---
 docs/editor_integration.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/editor_integration.md b/docs/editor_integration.md
index aa3a1eeedec..bc7c2e7b7be 100644
--- a/docs/editor_integration.md
+++ b/docs/editor_integration.md
@@ -286,7 +286,8 @@ Sublime Text, Visual Studio Code and many more), you can use the
 
 ## Atom/Nuclide
 
-Use [python-black](https://atom.io/packages/python-black).
+Use [python-black](https://atom.io/packages/python-black) or
+[formatters-python](https://atom.io/packages/formatters-python).
 
 ## Gradle (the build tool)
 

From 24418a54501381e1cdbe0ab1de4e4ced7537c124 Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <hugovk@users.noreply.github.com>
Date: Thu, 4 Mar 2021 15:59:31 +0200
Subject: [PATCH 0106/1034] Black requires Python 3.6.2+ (#1668)

---
 README.md        | 2 +-
 plugin/black.vim | 6 +++---
 setup.py         | 4 ++--
 3 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 5f8b52cb823..411a8c8609d 100644
--- a/README.md
+++ b/README.md
@@ -49,7 +49,7 @@ _Contents:_ **[Installation and usage](#installation-and-usage)** |
 
 ### Installation
 
-_Black_ can be installed by running `pip install black`. It requires Python 3.6.0+ to
+_Black_ can be installed by running `pip install black`. It requires Python 3.6.2+ to
 run but you can reformat Python 2 code with it, too.
 
 #### Install from GitHub
diff --git a/plugin/black.vim b/plugin/black.vim
index c5f0313f4ac..39a31f14b52 100644
--- a/plugin/black.vim
+++ b/plugin/black.vim
@@ -103,9 +103,9 @@ def _get_virtualenv_site_packages(venv_path, pyver):
   return venv_path / 'lib' / f'python{pyver[0]}.{pyver[1]}' / 'site-packages'
 
 def _initialize_black_env(upgrade=False):
-  pyver = sys.version_info[:2]
-  if pyver < (3, 6):
-    print("Sorry, Black requires Python 3.6+ to run.")
+  pyver = sys.version_info[:3]
+  if pyver < (3, 6, 2):
+    print("Sorry, Black requires Python 3.6.2+ to run.")
     return False
 
   from pathlib import Path
diff --git a/setup.py b/setup.py
index 48160568265..efdf6933025 100644
--- a/setup.py
+++ b/setup.py
@@ -3,7 +3,7 @@
 import sys
 import os
 
-assert sys.version_info >= (3, 6, 0), "black requires Python 3.6+"
+assert sys.version_info >= (3, 6, 2), "black requires Python 3.6.2+"
 from pathlib import Path  # noqa E402
 
 CURRENT_DIR = Path(__file__).parent
@@ -65,7 +65,7 @@ def get_long_description() -> str:
     packages=["blackd", "black", "blib2to3", "blib2to3.pgen2", "black_primer"],
     package_dir={"": "src"},
     package_data={"blib2to3": ["*.txt"], "black": ["py.typed"]},
-    python_requires=">=3.6",
+    python_requires=">=3.6.2",
     zip_safe=False,
     install_requires=[
         "click>=7.1.2",

From 12f98219bc83fa186cc97db7b614dccfb2a1db71 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Fri, 5 Mar 2021 10:43:54 -0800
Subject: [PATCH 0107/1034] Bump aiohttp from 3.7.3 to 3.7.4 (#2009)

Bumps [aiohttp](https://github.com/aio-libs/aiohttp) from 3.7.3 to 3.7.4.
- [Release notes](https://github.com/aio-libs/aiohttp/releases)
- [Changelog](https://github.com/aio-libs/aiohttp/blob/master/CHANGES.rst)
- [Commits](https://github.com/aio-libs/aiohttp/compare/v3.7.3...v3.7.4)

Signed-off-by: dependabot[bot] <support@github.com>

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 Pipfile.lock | 279 +++++++++++++++++++++++++--------------------------
 1 file changed, 138 insertions(+), 141 deletions(-)

diff --git a/Pipfile.lock b/Pipfile.lock
index 9aa2d0e7ce8..9cdcba2a0ea 100644
--- a/Pipfile.lock
+++ b/Pipfile.lock
@@ -16,46 +16,46 @@
     "default": {
         "aiohttp": {
             "hashes": [
-                "sha256:0b795072bb1bf87b8620120a6373a3c61bfcb8da7e5c2377f4bb23ff4f0b62c9",
-                "sha256:0d438c8ca703b1b714e82ed5b7a4412c82577040dadff479c08405e2a715564f",
-                "sha256:16a3cb5df5c56f696234ea9e65e227d1ebe9c18aa774d36ff42f532139066a5f",
-                "sha256:1edfd82a98c5161497bbb111b2b70c0813102ad7e0aa81cbeb34e64c93863005",
-                "sha256:2406dc1dda01c7f6060ab586e4601f18affb7a6b965c50a8c90ff07569cf782a",
-                "sha256:2858b2504c8697beb9357be01dc47ef86438cc1cb36ecb6991796d19475faa3e",
-                "sha256:2a7b7640167ab536c3cb90cfc3977c7094f1c5890d7eeede8b273c175c3910fd",
-                "sha256:3228b7a51e3ed533f5472f54f70fd0b0a64c48dc1649a0f0e809bec312934d7a",
-                "sha256:328b552513d4f95b0a2eea4c8573e112866107227661834652a8984766aa7656",
-                "sha256:39f4b0a6ae22a1c567cb0630c30dd082481f95c13ca528dc501a7766b9c718c0",
-                "sha256:3b0036c978cbcc4a4512278e98e3e6d9e6b834dc973206162eddf98b586ef1c6",
-                "sha256:3ea8c252d8df5e9166bcf3d9edced2af132f4ead8ac422eac723c5781063709a",
-                "sha256:41608c0acbe0899c852281978492f9ce2c6fbfaf60aff0cefc54a7c4516b822c",
-                "sha256:59d11674964b74a81b149d4ceaff2b674b3b0e4d0f10f0be1533e49c4a28408b",
-                "sha256:5e479df4b2d0f8f02133b7e4430098699450e1b2a826438af6bec9a400530957",
-                "sha256:684850fb1e3e55c9220aad007f8386d8e3e477c4ec9211ae54d968ecdca8c6f9",
-                "sha256:6ccc43d68b81c424e46192a778f97da94ee0630337c9bbe5b2ecc9b0c1c59001",
-                "sha256:6d42debaf55450643146fabe4b6817bb2a55b23698b0434107e892a43117285e",
-                "sha256:710376bf67d8ff4500a31d0c207b8941ff4fba5de6890a701d71680474fe2a60",
-                "sha256:756ae7efddd68d4ea7d89c636b703e14a0c686688d42f588b90778a3c2fc0564",
-                "sha256:77149002d9386fae303a4a162e6bce75cc2161347ad2ba06c2f0182561875d45",
-                "sha256:78e2f18a82b88cbc37d22365cf8d2b879a492faedb3f2975adb4ed8dfe994d3a",
-                "sha256:7d9b42127a6c0bdcc25c3dcf252bb3ddc70454fac593b1b6933ae091396deb13",
-                "sha256:8389d6044ee4e2037dca83e3f6994738550f6ee8cfb746762283fad9b932868f",
-                "sha256:9c1a81af067e72261c9cbe33ea792893e83bc6aa987bfbd6fdc1e5e7b22777c4",
-                "sha256:c1e0920909d916d3375c7a1fdb0b1c78e46170e8bb42792312b6eb6676b2f87f",
-                "sha256:c68fdf21c6f3573ae19c7ee65f9ff185649a060c9a06535e9c3a0ee0bbac9235",
-                "sha256:c733ef3bdcfe52a1a75564389bad4064352274036e7e234730526d155f04d914",
-                "sha256:c9c58b0b84055d8bc27b7df5a9d141df4ee6ff59821f922dd73155861282f6a3",
-                "sha256:d03abec50df423b026a5aa09656bd9d37f1e6a49271f123f31f9b8aed5dc3ea3",
-                "sha256:d2cfac21e31e841d60dc28c0ec7d4ec47a35c608cb8906435d47ef83ffb22150",
-                "sha256:dcc119db14757b0c7bce64042158307b9b1c76471e655751a61b57f5a0e4d78e",
-                "sha256:df3a7b258cc230a65245167a202dd07320a5af05f3d41da1488ba0fa05bc9347",
-                "sha256:df48a623c58180874d7407b4d9ec06a19b84ed47f60a3884345b1a5099c1818b",
-                "sha256:e1b95972a0ae3f248a899cdbac92ba2e01d731225f566569311043ce2226f5e7",
-                "sha256:f326b3c1bbfda5b9308252ee0dcb30b612ee92b0e105d4abec70335fab5b1245",
-                "sha256:f411cb22115cb15452d099fec0ee636b06cf81bfb40ed9c02d30c8dc2bc2e3d1"
+                "sha256:119feb2bd551e58d83d1b38bfa4cb921af8ddedec9fad7183132db334c3133e0",
+                "sha256:16d0683ef8a6d803207f02b899c928223eb219111bd52420ef3d7a8aa76227b6",
+                "sha256:2eb3efe243e0f4ecbb654b08444ae6ffab37ac0ef8f69d3a2ffb958905379daf",
+                "sha256:2ffea7904e70350da429568113ae422c88d2234ae776519549513c8f217f58a9",
+                "sha256:40bd1b101b71a18a528ffce812cc14ff77d4a2a1272dfb8b11b200967489ef3e",
+                "sha256:418597633b5cd9639e514b1d748f358832c08cd5d9ef0870026535bd5eaefdd0",
+                "sha256:481d4b96969fbfdcc3ff35eea5305d8565a8300410d3d269ccac69e7256b1329",
+                "sha256:4c1bdbfdd231a20eee3e56bd0ac1cd88c4ff41b64ab679ed65b75c9c74b6c5c2",
+                "sha256:5563ad7fde451b1986d42b9bb9140e2599ecf4f8e42241f6da0d3d624b776f40",
+                "sha256:58c62152c4c8731a3152e7e650b29ace18304d086cb5552d317a54ff2749d32a",
+                "sha256:5b50e0b9460100fe05d7472264d1975f21ac007b35dcd6fd50279b72925a27f4",
+                "sha256:5d84ecc73141d0a0d61ece0742bb7ff5751b0657dab8405f899d3ceb104cc7de",
+                "sha256:5dde6d24bacac480be03f4f864e9a67faac5032e28841b00533cd168ab39cad9",
+                "sha256:5e91e927003d1ed9283dee9abcb989334fc8e72cf89ebe94dc3e07e3ff0b11e9",
+                "sha256:62bc216eafac3204877241569209d9ba6226185aa6d561c19159f2e1cbb6abfb",
+                "sha256:6c8200abc9dc5f27203986100579fc19ccad7a832c07d2bc151ce4ff17190076",
+                "sha256:6ca56bdfaf825f4439e9e3673775e1032d8b6ea63b8953d3812c71bd6a8b81de",
+                "sha256:71680321a8a7176a58dfbc230789790639db78dad61a6e120b39f314f43f1907",
+                "sha256:7c7820099e8b3171e54e7eedc33e9450afe7cd08172632d32128bd527f8cb77d",
+                "sha256:7dbd087ff2f4046b9b37ba28ed73f15fd0bc9f4fdc8ef6781913da7f808d9536",
+                "sha256:822bd4fd21abaa7b28d65fc9871ecabaddc42767884a626317ef5b75c20e8a2d",
+                "sha256:8ec1a38074f68d66ccb467ed9a673a726bb397142c273f90d4ba954666e87d54",
+                "sha256:950b7ef08b2afdab2488ee2edaff92a03ca500a48f1e1aaa5900e73d6cf992bc",
+                "sha256:99c5a5bf7135607959441b7d720d96c8e5c46a1f96e9d6d4c9498be8d5f24212",
+                "sha256:b84ad94868e1e6a5e30d30ec419956042815dfaea1b1df1cef623e4564c374d9",
+                "sha256:bc3d14bf71a3fb94e5acf5bbf67331ab335467129af6416a437bd6024e4f743d",
+                "sha256:c2a80fd9a8d7e41b4e38ea9fe149deed0d6aaede255c497e66b8213274d6d61b",
+                "sha256:c44d3c82a933c6cbc21039326767e778eface44fca55c65719921c4b9661a3f7",
+                "sha256:cc31e906be1cc121ee201adbdf844522ea3349600dd0a40366611ca18cd40e81",
+                "sha256:d5d102e945ecca93bcd9801a7bb2fa703e37ad188a2f81b1e65e4abe4b51b00c",
+                "sha256:dd7936f2a6daa861143e376b3a1fb56e9b802f4980923594edd9ca5670974895",
+                "sha256:dee68ec462ff10c1d836c0ea2642116aba6151c6880b688e56b4c0246770f297",
+                "sha256:e76e78863a4eaec3aee5722d85d04dcbd9844bc6cd3bfa6aa880ff46ad16bfcb",
+                "sha256:eab51036cac2da8a50d7ff0ea30be47750547c9aa1aa2cf1a1b710a1827e7dbe",
+                "sha256:f4496d8d04da2e98cc9133e238ccebf6a13ef39a93da2e87146c8c8ac9768242",
+                "sha256:fbd3b5e18d34683decc00d9a360179ac1e7a320a5fee10ab8053ffd6deab76e0",
+                "sha256:feb24ff1226beeb056e247cf2e24bba5232519efb5645121c4aea5b6ad74c1f2"
             ],
             "index": "pypi",
-            "version": "==3.7.3"
+            "version": "==3.7.4"
         },
         "aiohttp-cors": {
             "hashes": [
@@ -328,46 +328,46 @@
     "develop": {
         "aiohttp": {
             "hashes": [
-                "sha256:0b795072bb1bf87b8620120a6373a3c61bfcb8da7e5c2377f4bb23ff4f0b62c9",
-                "sha256:0d438c8ca703b1b714e82ed5b7a4412c82577040dadff479c08405e2a715564f",
-                "sha256:16a3cb5df5c56f696234ea9e65e227d1ebe9c18aa774d36ff42f532139066a5f",
-                "sha256:1edfd82a98c5161497bbb111b2b70c0813102ad7e0aa81cbeb34e64c93863005",
-                "sha256:2406dc1dda01c7f6060ab586e4601f18affb7a6b965c50a8c90ff07569cf782a",
-                "sha256:2858b2504c8697beb9357be01dc47ef86438cc1cb36ecb6991796d19475faa3e",
-                "sha256:2a7b7640167ab536c3cb90cfc3977c7094f1c5890d7eeede8b273c175c3910fd",
-                "sha256:3228b7a51e3ed533f5472f54f70fd0b0a64c48dc1649a0f0e809bec312934d7a",
-                "sha256:328b552513d4f95b0a2eea4c8573e112866107227661834652a8984766aa7656",
-                "sha256:39f4b0a6ae22a1c567cb0630c30dd082481f95c13ca528dc501a7766b9c718c0",
-                "sha256:3b0036c978cbcc4a4512278e98e3e6d9e6b834dc973206162eddf98b586ef1c6",
-                "sha256:3ea8c252d8df5e9166bcf3d9edced2af132f4ead8ac422eac723c5781063709a",
-                "sha256:41608c0acbe0899c852281978492f9ce2c6fbfaf60aff0cefc54a7c4516b822c",
-                "sha256:59d11674964b74a81b149d4ceaff2b674b3b0e4d0f10f0be1533e49c4a28408b",
-                "sha256:5e479df4b2d0f8f02133b7e4430098699450e1b2a826438af6bec9a400530957",
-                "sha256:684850fb1e3e55c9220aad007f8386d8e3e477c4ec9211ae54d968ecdca8c6f9",
-                "sha256:6ccc43d68b81c424e46192a778f97da94ee0630337c9bbe5b2ecc9b0c1c59001",
-                "sha256:6d42debaf55450643146fabe4b6817bb2a55b23698b0434107e892a43117285e",
-                "sha256:710376bf67d8ff4500a31d0c207b8941ff4fba5de6890a701d71680474fe2a60",
-                "sha256:756ae7efddd68d4ea7d89c636b703e14a0c686688d42f588b90778a3c2fc0564",
-                "sha256:77149002d9386fae303a4a162e6bce75cc2161347ad2ba06c2f0182561875d45",
-                "sha256:78e2f18a82b88cbc37d22365cf8d2b879a492faedb3f2975adb4ed8dfe994d3a",
-                "sha256:7d9b42127a6c0bdcc25c3dcf252bb3ddc70454fac593b1b6933ae091396deb13",
-                "sha256:8389d6044ee4e2037dca83e3f6994738550f6ee8cfb746762283fad9b932868f",
-                "sha256:9c1a81af067e72261c9cbe33ea792893e83bc6aa987bfbd6fdc1e5e7b22777c4",
-                "sha256:c1e0920909d916d3375c7a1fdb0b1c78e46170e8bb42792312b6eb6676b2f87f",
-                "sha256:c68fdf21c6f3573ae19c7ee65f9ff185649a060c9a06535e9c3a0ee0bbac9235",
-                "sha256:c733ef3bdcfe52a1a75564389bad4064352274036e7e234730526d155f04d914",
-                "sha256:c9c58b0b84055d8bc27b7df5a9d141df4ee6ff59821f922dd73155861282f6a3",
-                "sha256:d03abec50df423b026a5aa09656bd9d37f1e6a49271f123f31f9b8aed5dc3ea3",
-                "sha256:d2cfac21e31e841d60dc28c0ec7d4ec47a35c608cb8906435d47ef83ffb22150",
-                "sha256:dcc119db14757b0c7bce64042158307b9b1c76471e655751a61b57f5a0e4d78e",
-                "sha256:df3a7b258cc230a65245167a202dd07320a5af05f3d41da1488ba0fa05bc9347",
-                "sha256:df48a623c58180874d7407b4d9ec06a19b84ed47f60a3884345b1a5099c1818b",
-                "sha256:e1b95972a0ae3f248a899cdbac92ba2e01d731225f566569311043ce2226f5e7",
-                "sha256:f326b3c1bbfda5b9308252ee0dcb30b612ee92b0e105d4abec70335fab5b1245",
-                "sha256:f411cb22115cb15452d099fec0ee636b06cf81bfb40ed9c02d30c8dc2bc2e3d1"
+                "sha256:119feb2bd551e58d83d1b38bfa4cb921af8ddedec9fad7183132db334c3133e0",
+                "sha256:16d0683ef8a6d803207f02b899c928223eb219111bd52420ef3d7a8aa76227b6",
+                "sha256:2eb3efe243e0f4ecbb654b08444ae6ffab37ac0ef8f69d3a2ffb958905379daf",
+                "sha256:2ffea7904e70350da429568113ae422c88d2234ae776519549513c8f217f58a9",
+                "sha256:40bd1b101b71a18a528ffce812cc14ff77d4a2a1272dfb8b11b200967489ef3e",
+                "sha256:418597633b5cd9639e514b1d748f358832c08cd5d9ef0870026535bd5eaefdd0",
+                "sha256:481d4b96969fbfdcc3ff35eea5305d8565a8300410d3d269ccac69e7256b1329",
+                "sha256:4c1bdbfdd231a20eee3e56bd0ac1cd88c4ff41b64ab679ed65b75c9c74b6c5c2",
+                "sha256:5563ad7fde451b1986d42b9bb9140e2599ecf4f8e42241f6da0d3d624b776f40",
+                "sha256:58c62152c4c8731a3152e7e650b29ace18304d086cb5552d317a54ff2749d32a",
+                "sha256:5b50e0b9460100fe05d7472264d1975f21ac007b35dcd6fd50279b72925a27f4",
+                "sha256:5d84ecc73141d0a0d61ece0742bb7ff5751b0657dab8405f899d3ceb104cc7de",
+                "sha256:5dde6d24bacac480be03f4f864e9a67faac5032e28841b00533cd168ab39cad9",
+                "sha256:5e91e927003d1ed9283dee9abcb989334fc8e72cf89ebe94dc3e07e3ff0b11e9",
+                "sha256:62bc216eafac3204877241569209d9ba6226185aa6d561c19159f2e1cbb6abfb",
+                "sha256:6c8200abc9dc5f27203986100579fc19ccad7a832c07d2bc151ce4ff17190076",
+                "sha256:6ca56bdfaf825f4439e9e3673775e1032d8b6ea63b8953d3812c71bd6a8b81de",
+                "sha256:71680321a8a7176a58dfbc230789790639db78dad61a6e120b39f314f43f1907",
+                "sha256:7c7820099e8b3171e54e7eedc33e9450afe7cd08172632d32128bd527f8cb77d",
+                "sha256:7dbd087ff2f4046b9b37ba28ed73f15fd0bc9f4fdc8ef6781913da7f808d9536",
+                "sha256:822bd4fd21abaa7b28d65fc9871ecabaddc42767884a626317ef5b75c20e8a2d",
+                "sha256:8ec1a38074f68d66ccb467ed9a673a726bb397142c273f90d4ba954666e87d54",
+                "sha256:950b7ef08b2afdab2488ee2edaff92a03ca500a48f1e1aaa5900e73d6cf992bc",
+                "sha256:99c5a5bf7135607959441b7d720d96c8e5c46a1f96e9d6d4c9498be8d5f24212",
+                "sha256:b84ad94868e1e6a5e30d30ec419956042815dfaea1b1df1cef623e4564c374d9",
+                "sha256:bc3d14bf71a3fb94e5acf5bbf67331ab335467129af6416a437bd6024e4f743d",
+                "sha256:c2a80fd9a8d7e41b4e38ea9fe149deed0d6aaede255c497e66b8213274d6d61b",
+                "sha256:c44d3c82a933c6cbc21039326767e778eface44fca55c65719921c4b9661a3f7",
+                "sha256:cc31e906be1cc121ee201adbdf844522ea3349600dd0a40366611ca18cd40e81",
+                "sha256:d5d102e945ecca93bcd9801a7bb2fa703e37ad188a2f81b1e65e4abe4b51b00c",
+                "sha256:dd7936f2a6daa861143e376b3a1fb56e9b802f4980923594edd9ca5670974895",
+                "sha256:dee68ec462ff10c1d836c0ea2642116aba6151c6880b688e56b4c0246770f297",
+                "sha256:e76e78863a4eaec3aee5722d85d04dcbd9844bc6cd3bfa6aa880ff46ad16bfcb",
+                "sha256:eab51036cac2da8a50d7ff0ea30be47750547c9aa1aa2cf1a1b710a1827e7dbe",
+                "sha256:f4496d8d04da2e98cc9133e238ccebf6a13ef39a93da2e87146c8c8ac9768242",
+                "sha256:fbd3b5e18d34683decc00d9a360179ac1e7a320a5fee10ab8053ffd6deab76e0",
+                "sha256:feb24ff1226beeb056e247cf2e24bba5232519efb5645121c4aea5b6ad74c1f2"
             ],
             "index": "pypi",
-            "version": "==3.7.3"
+            "version": "==3.7.4"
         },
         "aiohttp-cors": {
             "hashes": [
@@ -436,45 +436,45 @@
         },
         "cffi": {
             "hashes": [
-                "sha256:00a1ba5e2e95684448de9b89888ccd02c98d512064b4cb987d48f4b40aa0421e",
-                "sha256:00e28066507bfc3fe865a31f325c8391a1ac2916219340f87dfad602c3e48e5d",
-                "sha256:045d792900a75e8b1e1b0ab6787dd733a8190ffcf80e8c8ceb2fb10a29ff238a",
-                "sha256:0638c3ae1a0edfb77c6765d487fee624d2b1ee1bdfeffc1f0b58c64d149e7eec",
-                "sha256:105abaf8a6075dc96c1fe5ae7aae073f4696f2905fde6aeada4c9d2926752362",
-                "sha256:155136b51fd733fa94e1c2ea5211dcd4c8879869008fc811648f16541bf99668",
-                "sha256:1a465cbe98a7fd391d47dce4b8f7e5b921e6cd805ef421d04f5f66ba8f06086c",
-                "sha256:1d2c4994f515e5b485fd6d3a73d05526aa0fcf248eb135996b088d25dfa1865b",
-                "sha256:2c24d61263f511551f740d1a065eb0212db1dbbbbd241db758f5244281590c06",
-                "sha256:51a8b381b16ddd370178a65360ebe15fbc1c71cf6f584613a7ea08bfad946698",
-                "sha256:594234691ac0e9b770aee9fcdb8fa02c22e43e5c619456efd0d6c2bf276f3eb2",
-                "sha256:5cf4be6c304ad0b6602f5c4e90e2f59b47653ac1ed9c662ed379fe48a8f26b0c",
-                "sha256:64081b3f8f6f3c3de6191ec89d7dc6c86a8a43911f7ecb422c60e90c70be41c7",
-                "sha256:6bc25fc545a6b3d57b5f8618e59fc13d3a3a68431e8ca5fd4c13241cd70d0009",
-                "sha256:798caa2a2384b1cbe8a2a139d80734c9db54f9cc155c99d7cc92441a23871c03",
-                "sha256:7c6b1dece89874d9541fc974917b631406233ea0440d0bdfbb8e03bf39a49b3b",
-                "sha256:7ef7d4ced6b325e92eb4d3502946c78c5367bc416398d387b39591532536734e",
-                "sha256:840793c68105fe031f34d6a086eaea153a0cd5c491cde82a74b420edd0a2b909",
-                "sha256:8d6603078baf4e11edc4168a514c5ce5b3ba6e3e9c374298cb88437957960a53",
-                "sha256:9cc46bc107224ff5b6d04369e7c595acb700c3613ad7bcf2e2012f62ece80c35",
-                "sha256:9f7a31251289b2ab6d4012f6e83e58bc3b96bd151f5b5262467f4bb6b34a7c26",
-                "sha256:9ffb888f19d54a4d4dfd4b3f29bc2c16aa4972f1c2ab9c4ab09b8ab8685b9c2b",
-                "sha256:a5ed8c05548b54b998b9498753fb9cadbfd92ee88e884641377d8a8b291bcc01",
-                "sha256:a7711edca4dcef1a75257b50a2fbfe92a65187c47dab5a0f1b9b332c5919a3fb",
-                "sha256:af5c59122a011049aad5dd87424b8e65a80e4a6477419c0c1015f73fb5ea0293",
-                "sha256:b18e0a9ef57d2b41f5c68beefa32317d286c3d6ac0484efd10d6e07491bb95dd",
-                "sha256:b4e248d1087abf9f4c10f3c398896c87ce82a9856494a7155823eb45a892395d",
-                "sha256:ba4e9e0ae13fc41c6b23299545e5ef73055213e466bd107953e4a013a5ddd7e3",
-                "sha256:c6332685306b6417a91b1ff9fae889b3ba65c2292d64bd9245c093b1b284809d",
-                "sha256:d5ff0621c88ce83a28a10d2ce719b2ee85635e85c515f12bac99a95306da4b2e",
-                "sha256:d9efd8b7a3ef378dd61a1e77367f1924375befc2eba06168b6ebfa903a5e59ca",
-                "sha256:df5169c4396adc04f9b0a05f13c074df878b6052430e03f50e68adf3a57aa28d",
-                "sha256:ebb253464a5d0482b191274f1c8bf00e33f7e0b9c66405fbffc61ed2c839c775",
-                "sha256:ec80dc47f54e6e9a78181ce05feb71a0353854cc26999db963695f950b5fb375",
-                "sha256:f032b34669220030f905152045dfa27741ce1a6db3324a5bc0b96b6c7420c87b",
-                "sha256:f60567825f791c6f8a592f3c6e3bd93dd2934e3f9dac189308426bd76b00ef3b",
-                "sha256:f803eaa94c2fcda012c047e62bc7a51b0bdabda1cad7a92a522694ea2d76e49f"
-            ],
-            "version": "==1.14.4"
+                "sha256:005a36f41773e148deac64b08f233873a4d0c18b053d37da83f6af4d9087b813",
+                "sha256:0857f0ae312d855239a55c81ef453ee8fd24136eaba8e87a2eceba644c0d4c06",
+                "sha256:1071534bbbf8cbb31b498d5d9db0f274f2f7a865adca4ae429e147ba40f73dea",
+                "sha256:158d0d15119b4b7ff6b926536763dc0714313aa59e320ddf787502c70c4d4bee",
+                "sha256:1f436816fc868b098b0d63b8920de7d208c90a67212546d02f84fe78a9c26396",
+                "sha256:2894f2df484ff56d717bead0a5c2abb6b9d2bf26d6960c4604d5c48bbc30ee73",
+                "sha256:29314480e958fd8aab22e4a58b355b629c59bf5f2ac2492b61e3dc06d8c7a315",
+                "sha256:34eff4b97f3d982fb93e2831e6750127d1355a923ebaeeb565407b3d2f8d41a1",
+                "sha256:35f27e6eb43380fa080dccf676dece30bef72e4a67617ffda586641cd4508d49",
+                "sha256:3d3dd4c9e559eb172ecf00a2a7517e97d1e96de2a5e610bd9b68cea3925b4892",
+                "sha256:43e0b9d9e2c9e5d152946b9c5fe062c151614b262fda2e7b201204de0b99e482",
+                "sha256:48e1c69bbacfc3d932221851b39d49e81567a4d4aac3b21258d9c24578280058",
+                "sha256:51182f8927c5af975fece87b1b369f722c570fe169f9880764b1ee3bca8347b5",
+                "sha256:58e3f59d583d413809d60779492342801d6e82fefb89c86a38e040c16883be53",
+                "sha256:5de7970188bb46b7bf9858eb6890aad302577a5f6f75091fd7cdd3ef13ef3045",
+                "sha256:65fa59693c62cf06e45ddbb822165394a288edce9e276647f0046e1ec26920f3",
+                "sha256:69e395c24fc60aad6bb4fa7e583698ea6cc684648e1ffb7fe85e3c1ca131a7d5",
+                "sha256:6c97d7350133666fbb5cf4abdc1178c812cb205dc6f41d174a7b0f18fb93337e",
+                "sha256:6e4714cc64f474e4d6e37cfff31a814b509a35cb17de4fb1999907575684479c",
+                "sha256:72d8d3ef52c208ee1c7b2e341f7d71c6fd3157138abf1a95166e6165dd5d4369",
+                "sha256:8ae6299f6c68de06f136f1f9e69458eae58f1dacf10af5c17353eae03aa0d827",
+                "sha256:8b198cec6c72df5289c05b05b8b0969819783f9418e0409865dac47288d2a053",
+                "sha256:99cd03ae7988a93dd00bcd9d0b75e1f6c426063d6f03d2f90b89e29b25b82dfa",
+                "sha256:9cf8022fb8d07a97c178b02327b284521c7708d7c71a9c9c355c178ac4bbd3d4",
+                "sha256:9de2e279153a443c656f2defd67769e6d1e4163952b3c622dcea5b08a6405322",
+                "sha256:9e93e79c2551ff263400e1e4be085a1210e12073a31c2011dbbda14bda0c6132",
+                "sha256:9ff227395193126d82e60319a673a037d5de84633f11279e336f9c0f189ecc62",
+                "sha256:a465da611f6fa124963b91bf432d960a555563efe4ed1cc403ba5077b15370aa",
+                "sha256:ad17025d226ee5beec591b52800c11680fca3df50b8b29fe51d882576e039ee0",
+                "sha256:afb29c1ba2e5a3736f1c301d9d0abe3ec8b86957d04ddfa9d7a6a42b9367e396",
+                "sha256:b85eb46a81787c50650f2392b9b4ef23e1f126313b9e0e9013b35c15e4288e2e",
+                "sha256:bb89f306e5da99f4d922728ddcd6f7fcebb3241fc40edebcb7284d7514741991",
+                "sha256:cbde590d4faaa07c72bf979734738f328d239913ba3e043b1e98fe9a39f8b2b6",
+                "sha256:cd2868886d547469123fadc46eac7ea5253ea7fcb139f12e1dfc2bbd406427d1",
+                "sha256:d42b11d692e11b6634f7613ad8df5d6d5f8875f5d48939520d351007b3c13406",
+                "sha256:f2d45f97ab6bb54753eab54fffe75aaf3de4ff2341c9daee1987ee1837636f1d",
+                "sha256:fd78e5fee591709f32ef6edb9a015b4aa1a5022598e36227500c8f4e02328d9c"
+            ],
+            "version": "==1.14.5"
         },
         "cfgv": {
             "hashes": [
@@ -569,23 +569,20 @@
         },
         "cryptography": {
             "hashes": [
-                "sha256:0d7b69674b738068fa6ffade5c962ecd14969690585aaca0a1b1fc9058938a72",
-                "sha256:1bd0ccb0a1ed775cd7e2144fe46df9dc03eefd722bbcf587b3e0616ea4a81eff",
-                "sha256:3c284fc1e504e88e51c428db9c9274f2da9f73fdf5d7e13a36b8ecb039af6e6c",
-                "sha256:49570438e60f19243e7e0d504527dd5fe9b4b967b5a1ff21cc12b57602dd85d3",
-                "sha256:541dd758ad49b45920dda3b5b48c968f8b2533d8981bcdb43002798d8f7a89ed",
-                "sha256:5a60d3780149e13b7a6ff7ad6526b38846354d11a15e21068e57073e29e19bed",
-                "sha256:7951a966613c4211b6612b0352f5bf29989955ee592c4a885d8c7d0f830d0433",
-                "sha256:922f9602d67c15ade470c11d616f2b2364950602e370c76f0c94c94ae672742e",
-                "sha256:a0f0b96c572fc9f25c3f4ddbf4688b9b38c69836713fb255f4a2715d93cbaf44",
-                "sha256:a777c096a49d80f9d2979695b835b0f9c9edab73b59e4ceb51f19724dda887ed",
-                "sha256:a9a4ac9648d39ce71c2f63fe7dc6db144b9fa567ddfc48b9fde1b54483d26042",
-                "sha256:aa4969f24d536ae2268c902b2c3d62ab464b5a66bcb247630d208a79a8098e9b",
-                "sha256:c7390f9b2119b2b43160abb34f63277a638504ef8df99f11cb52c1fda66a2e6f",
-                "sha256:e18e6ab84dfb0ab997faf8cca25a86ff15dfea4027b986322026cc99e0a892da"
-            ],
-            "index": "pypi",
-            "version": "==3.3.2"
+                "sha256:066bc53f052dfeda2f2d7c195cf16fb3e5ff13e1b6b7415b468514b40b381a5b",
+                "sha256:0923ba600d00718d63a3976f23cab19aef10c1765038945628cd9be047ad0336",
+                "sha256:2d32223e5b0ee02943f32b19245b61a62db83a882f0e76cc564e1cec60d48f87",
+                "sha256:4169a27b818de4a1860720108b55a2801f32b6ae79e7f99c00d79f2a2822eeb7",
+                "sha256:57ad77d32917bc55299b16d3b996ffa42a1c73c6cfa829b14043c561288d2799",
+                "sha256:5ecf2bcb34d17415e89b546dbb44e73080f747e504273e4d4987630493cded1b",
+                "sha256:600cf9bfe75e96d965509a4c0b2b183f74a4fa6f5331dcb40fb7b77b7c2484df",
+                "sha256:66b57a9ca4b3221d51b237094b0303843b914b7d5afd4349970bb26518e350b0",
+                "sha256:93cfe5b7ff006de13e1e89830810ecbd014791b042cbe5eec253be11ac2b28f3",
+                "sha256:9e98b452132963678e3ac6c73f7010fe53adf72209a32854d55690acac3f6724",
+                "sha256:df186fcbf86dc1ce56305becb8434e4b6b7504bc724b71ad7a3239e0c9d14ef2",
+                "sha256:fec7fb46b10da10d9e1d078d1ff8ed9e05ae14f431fdbd11145edd0550b9a964"
+            ],
+            "version": "==3.4.6"
         },
         "distlib": {
             "hashes": [
@@ -627,10 +624,10 @@
         },
         "identify": {
             "hashes": [
-                "sha256:70b638cf4743f33042bebb3b51e25261a0a10e80f978739f17e7fd4837664a66",
-                "sha256:9dfb63a2e871b807e3ba62f029813552a24b5289504f5b071dea9b041aee9fe4"
+                "sha256:de7129142a5c86d75a52b96f394d94d96d497881d2aaf8eafe320cdbe8ac4bcc",
+                "sha256:e0dae57c0397629ce13c289f6ddde0204edf518f557bfdb1e56474aa143e77c3"
             ],
-            "version": "==1.5.13"
+            "version": "==1.5.14"
         },
         "idna": {
             "hashes": [
@@ -862,10 +859,10 @@
         },
         "pygments": {
             "hashes": [
-                "sha256:bc9591213a8f0e0ca1a5e68a479b4887fdc3e75d0774e5c71c31920c427de435",
-                "sha256:df49d09b498e83c1a73128295860250b0b7edd4c723a32e9bc0d295c7c2ec337"
+                "sha256:37a13ba168a02ac54cc5891a42b1caec333e59b66addb7fa633ea8a6d73445c0",
+                "sha256:b21b072d0ccdf29297a82a2363359d99623597b8a265b8081760e4d0f7153c88"
             ],
-            "version": "==2.7.4"
+            "version": "==2.8.0"
         },
         "pyparsing": {
             "hashes": [
@@ -1081,10 +1078,10 @@
         },
         "tqdm": {
             "hashes": [
-                "sha256:2874fa525c051177583ec59c0fb4583e91f28ccd3f217ffad2acdb32d2c789ac",
-                "sha256:ab9b659241d82b8b51b2269ee243ec95286046bf06015c4e15a947cc15914211"
+                "sha256:2c44efa73b8914dba7807aefd09653ac63c22b5b4ea34f7a80973f418f1a3089",
+                "sha256:c23ac707e8e8aabb825e4d91f8e17247f9cc14b0d64dd9e97be0781e9e525bba"
             ],
-            "version": "==4.56.1"
+            "version": "==4.58.0"
         },
         "twine": {
             "hashes": [

From b3ceb293d9e69295a190fed93517cbe1b7372154 Mon Sep 17 00:00:00 2001
From: Hadi Alqattan <alqattanhadizaki@gmail.com>
Date: Fri, 5 Mar 2021 22:58:00 +0300
Subject: [PATCH 0108/1034] Remove unused import statements using Pycln.
 (#2021)

* remove unused imports using Pycln.

* reverse comma style.
---
 src/blib2to3/pgen2/driver.py | 3 ---
 src/blib2to3/pgen2/parse.py  | 2 --
 src/blib2to3/pgen2/pgen.py   | 1 -
 src/blib2to3/pytree.py       | 1 -
 4 files changed, 7 deletions(-)

diff --git a/src/blib2to3/pgen2/driver.py b/src/blib2to3/pgen2/driver.py
index 81940f78f0f..af1dc6b8aeb 100644
--- a/src/blib2to3/pgen2/driver.py
+++ b/src/blib2to3/pgen2/driver.py
@@ -16,7 +16,6 @@
 __all__ = ["Driver", "load_grammar"]
 
 # Python imports
-import codecs
 import io
 import os
 import logging
@@ -24,7 +23,6 @@
 import sys
 from typing import (
     Any,
-    Callable,
     IO,
     Iterable,
     List,
@@ -32,7 +30,6 @@
     Text,
     Tuple,
     Union,
-    Sequence,
 )
 
 # Pgen imports
diff --git a/src/blib2to3/pgen2/parse.py b/src/blib2to3/pgen2/parse.py
index 8c374d35b42..47c8f02b4f5 100644
--- a/src/blib2to3/pgen2/parse.py
+++ b/src/blib2to3/pgen2/parse.py
@@ -15,8 +15,6 @@
 from typing import (
     Optional,
     Text,
-    Sequence,
-    Any,
     Union,
     Tuple,
     Dict,
diff --git a/src/blib2to3/pgen2/pgen.py b/src/blib2to3/pgen2/pgen.py
index a685145933c..564ebbd1184 100644
--- a/src/blib2to3/pgen2/pgen.py
+++ b/src/blib2to3/pgen2/pgen.py
@@ -8,7 +8,6 @@
     Any,
     Dict,
     IO,
-    Iterable,
     Iterator,
     List,
     Optional,
diff --git a/src/blib2to3/pytree.py b/src/blib2to3/pytree.py
index 6dba3c7bb15..0c074f6a4ac 100644
--- a/src/blib2to3/pytree.py
+++ b/src/blib2to3/pytree.py
@@ -25,7 +25,6 @@
     Union,
     Set,
     Iterable,
-    Sequence,
 )
 from blib2to3.pgen2.grammar import Grammar
 

From 1f7e73506c8b8c37d72becad5c9d8f1ab61644e1 Mon Sep 17 00:00:00 2001
From: John Meow <j0hn.meow@ya.ru>
Date: Sat, 6 Mar 2021 07:22:19 +0300
Subject: [PATCH 0109/1034] Add ALE (#1753)

---
 docs/editor_integration.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/docs/editor_integration.md b/docs/editor_integration.md
index bc7c2e7b7be..ae24c768882 100644
--- a/docs/editor_integration.md
+++ b/docs/editor_integration.md
@@ -111,6 +111,8 @@ $ black --help
 
 ## Vim
 
+### Official plugin
+
 Commands and shortcuts:
 
 - `:Black` to format the entire file (ranges not supported);
@@ -233,6 +235,17 @@ If you later want to update _Black_, you should do it like this:
 $ pip install -U black --no-binary regex,typed-ast
 ```
 
+### With ALE
+
+1. Install [`ale`](https://github.com/dense-analysis/ale)
+2. Install `black`
+3. Add this to your vimrc:
+
+   ```vim
+   let g:ale_fixers = {}
+   let g:ale_fixers.python = ['black']
+   ```
+
 ## Gedit
 
 gedit is the default text editor of the GNOME, Unix like Operating Systems. Open gedit

From b332cfa655dedfeb74974abdac1fb7b55d7e62ea Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Sat, 6 Mar 2021 15:02:25 -0500
Subject: [PATCH 0110/1034] Add missing changelog entry for fmt: skip (#2025)

---
 CHANGES.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/CHANGES.md b/CHANGES.md
index 90e5143fafe..e6dcc1b967d 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -33,6 +33,8 @@
 - Added `--stdin-filename` argument to allow stdin to respect `--force-exclude` rules
   (#1780)
 
+- Lines ending with `fmt: skip` will now be not formatted (#1800)
+
 #### _Packaging_
 
 - Self-contained native _Black_ binaries are now provided for releases via GitHub

From 5446a92f0161e398de765bf9532d8c76c5652333 Mon Sep 17 00:00:00 2001
From: Konstantin Alekseev <mail@kalekseev.com>
Date: Mon, 8 Mar 2021 03:13:25 +0300
Subject: [PATCH 0111/1034] Use vim autoload script (#1157)

---
 autoload/black.vim | 172 +++++++++++++++++++++++++++++++++++++++++++++
 plugin/black.vim   | 172 ++-------------------------------------------
 2 files changed, 179 insertions(+), 165 deletions(-)
 create mode 100644 autoload/black.vim

diff --git a/autoload/black.vim b/autoload/black.vim
new file mode 100644
index 00000000000..f0357b07123
--- /dev/null
+++ b/autoload/black.vim
@@ -0,0 +1,172 @@
+python3 << EndPython3
+import collections
+import os
+import sys
+import vim
+from distutils.util import strtobool
+
+
+class Flag(collections.namedtuple("FlagBase", "name, cast")):
+  @property
+  def var_name(self):
+    return self.name.replace("-", "_")
+
+  @property
+  def vim_rc_name(self):
+    name = self.var_name
+    if name == "line_length":
+      name = name.replace("_", "")
+    return "g:black_" + name
+
+
+FLAGS = [
+  Flag(name="line_length", cast=int),
+  Flag(name="fast", cast=strtobool),
+  Flag(name="string_normalization", cast=strtobool),
+  Flag(name="quiet", cast=strtobool),
+]
+
+
+def _get_python_binary(exec_prefix):
+  try:
+    default = vim.eval("g:pymode_python").strip()
+  except vim.error:
+    default = ""
+  if default and os.path.exists(default):
+    return default
+  if sys.platform[:3] == "win":
+    return exec_prefix / 'python.exe'
+  return exec_prefix / 'bin' / 'python3'
+
+def _get_pip(venv_path):
+  if sys.platform[:3] == "win":
+    return venv_path / 'Scripts' / 'pip.exe'
+  return venv_path / 'bin' / 'pip'
+
+def _get_virtualenv_site_packages(venv_path, pyver):
+  if sys.platform[:3] == "win":
+    return venv_path / 'Lib' / 'site-packages'
+  return venv_path / 'lib' / f'python{pyver[0]}.{pyver[1]}' / 'site-packages'
+
+def _initialize_black_env(upgrade=False):
+  pyver = sys.version_info[:3]
+  if pyver < (3, 6, 2):
+    print("Sorry, Black requires Python 3.6.2+ to run.")
+    return False
+
+  from pathlib import Path
+  import subprocess
+  import venv
+  virtualenv_path = Path(vim.eval("g:black_virtualenv")).expanduser()
+  virtualenv_site_packages = str(_get_virtualenv_site_packages(virtualenv_path, pyver))
+  first_install = False
+  if not virtualenv_path.is_dir():
+    print('Please wait, one time setup for Black.')
+    _executable = sys.executable
+    _base_executable = getattr(sys, "_base_executable", _executable)
+    try:
+      executable = str(_get_python_binary(Path(sys.exec_prefix)))
+      sys.executable = executable
+      sys._base_executable = executable
+      print(f'Creating a virtualenv in {virtualenv_path}...')
+      print('(this path can be customized in .vimrc by setting g:black_virtualenv)')
+      venv.create(virtualenv_path, with_pip=True)
+    except Exception:
+      print('Encountered exception while creating virtualenv (see traceback below).')
+      print(f'Removing {virtualenv_path}...')
+      import shutil
+      shutil.rmtree(virtualenv_path)
+      raise
+    finally:
+      sys.executable = _executable
+      sys._base_executable = _base_executable
+    first_install = True
+  if first_install:
+    print('Installing Black with pip...')
+  if upgrade:
+    print('Upgrading Black with pip...')
+  if first_install or upgrade:
+    subprocess.run([str(_get_pip(virtualenv_path)), 'install', '-U', 'black'], stdout=subprocess.PIPE)
+    print('DONE! You are all set, thanks for waiting ✨ 🍰 ✨')
+  if first_install:
+    print('Pro-tip: to upgrade Black in the future, use the :BlackUpgrade command and restart Vim.\n')
+  if virtualenv_site_packages not in sys.path:
+    sys.path.insert(0, virtualenv_site_packages)
+  return True
+
+if _initialize_black_env():
+  import black
+  import time
+
+def Black():
+  start = time.time()
+  configs = get_configs()
+  mode = black.FileMode(
+    line_length=configs["line_length"],
+    string_normalization=configs["string_normalization"],
+    is_pyi=vim.current.buffer.name.endswith('.pyi'),
+  )
+  quiet = configs["quiet"]
+
+  buffer_str = '\n'.join(vim.current.buffer) + '\n'
+  try:
+    new_buffer_str = black.format_file_contents(
+      buffer_str,
+      fast=configs["fast"],
+      mode=mode,
+    )
+  except black.NothingChanged:
+    if not quiet:
+      print(f'Already well formatted, good job. (took {time.time() - start:.4f}s)')
+  except Exception as exc:
+    print(exc)
+  else:
+    current_buffer = vim.current.window.buffer
+    cursors = []
+    for i, tabpage in enumerate(vim.tabpages):
+      if tabpage.valid:
+        for j, window in enumerate(tabpage.windows):
+          if window.valid and window.buffer == current_buffer:
+            cursors.append((i, j, window.cursor))
+    vim.current.buffer[:] = new_buffer_str.split('\n')[:-1]
+    for i, j, cursor in cursors:
+      window = vim.tabpages[i].windows[j]
+      try:
+        window.cursor = cursor
+      except vim.error:
+        window.cursor = (len(window.buffer), 0)
+    if not quiet:
+      print(f'Reformatted in {time.time() - start:.4f}s.')
+
+def get_configs():
+  path_pyproject_toml = black.find_pyproject_toml(vim.eval("fnamemodify(getcwd(), ':t')"))
+  if path_pyproject_toml:
+    toml_config = black.parse_pyproject_toml(path_pyproject_toml)
+  else:
+    toml_config = {}
+
+  return {
+    flag.var_name: flag.cast(toml_config.get(flag.name, vim.eval(flag.vim_rc_name)))
+    for flag in FLAGS
+  }
+
+
+def BlackUpgrade():
+  _initialize_black_env(upgrade=True)
+
+def BlackVersion():
+  print(f'Black, version {black.__version__} on Python {sys.version}.')
+
+EndPython3
+
+function black#Black()
+  :py3 Black()
+endfunction
+
+function black#BlackUpgrade()
+  :py3 BlackUpgrade()
+endfunction
+
+function black#BlackVersion()
+  :py3 BlackVersion()
+endfunction
diff --git a/plugin/black.vim b/plugin/black.vim
index 39a31f14b52..b5edb2a6ade 100644
--- a/plugin/black.vim
+++ b/plugin/black.vim
@@ -2,7 +2,7 @@
 " Author: Łukasz Langa
 " Created: Mon Mar 26 23:27:53 2018 -0700
 " Requires: Vim Ver7.0+
-" Version:  1.1
+" Version:  1.2
 "
 " Documentation:
 "   This plugin formats Python files.
@@ -12,6 +12,8 @@
 "    - initial version
 "  1.1:
 "    - restore cursor/window position after formatting
+"  1.2:
+"    - use autoload script
 
 if v:version < 700 || !has('python3')
     func! __BLACK_MISSING()
@@ -24,7 +26,7 @@ if v:version < 700 || !has('python3')
 endif
 
 if exists("g:load_black")
-   finish
+  finish
 endif
 
 let g:load_black = "py1.0"
@@ -52,167 +54,7 @@ if !exists("g:black_quiet")
   let g:black_quiet = 0
 endif
 
-python3 << EndPython3
-import collections
-import os
-import sys
-import vim
-from distutils.util import strtobool
 
-
-class Flag(collections.namedtuple("FlagBase", "name, cast")):
-  @property
-  def var_name(self):
-    return self.name.replace("-", "_")
-
-  @property
-  def vim_rc_name(self):
-    name = self.var_name
-    if name == "line_length":
-      name = name.replace("_", "")
-    return "g:black_" + name
-
-
-FLAGS = [
-  Flag(name="line_length", cast=int),
-  Flag(name="fast", cast=strtobool),
-  Flag(name="string_normalization", cast=strtobool),
-  Flag(name="quiet", cast=strtobool),
-]
-
-
-def _get_python_binary(exec_prefix):
-  try:
-    default = vim.eval("g:pymode_python").strip()
-  except vim.error:
-    default = ""
-  if default and os.path.exists(default):
-    return default
-  if sys.platform[:3] == "win":
-    return exec_prefix / 'python.exe'
-  return exec_prefix / 'bin' / 'python3'
-
-def _get_pip(venv_path):
-  if sys.platform[:3] == "win":
-    return venv_path / 'Scripts' / 'pip.exe'
-  return venv_path / 'bin' / 'pip'
-
-def _get_virtualenv_site_packages(venv_path, pyver):
-  if sys.platform[:3] == "win":
-    return venv_path / 'Lib' / 'site-packages'
-  return venv_path / 'lib' / f'python{pyver[0]}.{pyver[1]}' / 'site-packages'
-
-def _initialize_black_env(upgrade=False):
-  pyver = sys.version_info[:3]
-  if pyver < (3, 6, 2):
-    print("Sorry, Black requires Python 3.6.2+ to run.")
-    return False
-
-  from pathlib import Path
-  import subprocess
-  import venv
-  virtualenv_path = Path(vim.eval("g:black_virtualenv")).expanduser()
-  virtualenv_site_packages = str(_get_virtualenv_site_packages(virtualenv_path, pyver))
-  first_install = False
-  if not virtualenv_path.is_dir():
-    print('Please wait, one time setup for Black.')
-    _executable = sys.executable
-    _base_executable = getattr(sys, "_base_executable", _executable)
-    try:
-      executable = str(_get_python_binary(Path(sys.exec_prefix)))
-      sys.executable = executable
-      sys._base_executable = executable
-      print(f'Creating a virtualenv in {virtualenv_path}...')
-      print('(this path can be customized in .vimrc by setting g:black_virtualenv)')
-      venv.create(virtualenv_path, with_pip=True)
-    except Exception:
-      print('Encountered exception while creating virtualenv (see traceback below).')
-      print(f'Removing {virtualenv_path}...')
-      import shutil
-      shutil.rmtree(virtualenv_path)
-      raise
-    finally:
-      sys.executable = _executable
-      sys._base_executable = _base_executable
-    first_install = True
-  if first_install:
-    print('Installing Black with pip...')
-  if upgrade:
-    print('Upgrading Black with pip...')
-  if first_install or upgrade:
-    subprocess.run([str(_get_pip(virtualenv_path)), 'install', '-U', 'black'], stdout=subprocess.PIPE)
-    print('DONE! You are all set, thanks for waiting ✨ 🍰 ✨')
-  if first_install:
-    print('Pro-tip: to upgrade Black in the future, use the :BlackUpgrade command and restart Vim.\n')
-  if virtualenv_site_packages not in sys.path:
-    sys.path.insert(0, virtualenv_site_packages)
-  return True
-
-if _initialize_black_env():
-  import black
-  import time
-
-def Black():
-  start = time.time()
-  configs = get_configs()
-  mode = black.FileMode(
-    line_length=configs["line_length"],
-    string_normalization=configs["string_normalization"],
-    is_pyi=vim.current.buffer.name.endswith('.pyi'),
-  )
-  quiet = configs["quiet"]
-
-  buffer_str = '\n'.join(vim.current.buffer) + '\n'
-  try:
-    new_buffer_str = black.format_file_contents(
-      buffer_str,
-      fast=configs["fast"],
-      mode=mode,
-    )
-  except black.NothingChanged:
-    if not quiet:
-      print(f'Already well formatted, good job. (took {time.time() - start:.4f}s)')
-  except Exception as exc:
-    print(exc)
-  else:
-    current_buffer = vim.current.window.buffer
-    cursors = []
-    for i, tabpage in enumerate(vim.tabpages):
-      if tabpage.valid:
-        for j, window in enumerate(tabpage.windows):
-          if window.valid and window.buffer == current_buffer:
-            cursors.append((i, j, window.cursor))
-    vim.current.buffer[:] = new_buffer_str.split('\n')[:-1]
-    for i, j, cursor in cursors:
-      window = vim.tabpages[i].windows[j]
-      try:
-        window.cursor = cursor
-      except vim.error:
-        window.cursor = (len(window.buffer), 0)
-    if not quiet:
-      print(f'Reformatted in {time.time() - start:.4f}s.')
-
-def get_configs():
-  path_pyproject_toml = black.find_pyproject_toml(vim.eval("fnamemodify(getcwd(), ':t')"))
-  if path_pyproject_toml:
-    toml_config = black.parse_pyproject_toml(path_pyproject_toml)
-  else:
-    toml_config = {}
-
-  return {
-    flag.var_name: flag.cast(toml_config.get(flag.name, vim.eval(flag.vim_rc_name)))
-    for flag in FLAGS
-  }
-
-
-def BlackUpgrade():
-  _initialize_black_env(upgrade=True)
-
-def BlackVersion():
-  print(f'Black, version {black.__version__} on Python {sys.version}.')
-
-EndPython3
-
-command! Black :py3 Black()
-command! BlackUpgrade :py3 BlackUpgrade()
-command! BlackVersion :py3 BlackVersion()
+command! Black :call black#Black()
+command! BlackUpgrade :call black#BlackUpgrade()
+command! BlackVersion :call black#BlackVersion()

From d62d677ca2135714d6159f6b4839983fb0a557c8 Mon Sep 17 00:00:00 2001
From: Jairo Llopis <Yajo@users.noreply.github.com>
Date: Thu, 18 Mar 2021 15:14:15 +0000
Subject: [PATCH 0112/1034] Recommend B950 + 88 char limit instead of 80
 (#2050)

[The section about line length][1] was contradictory.

On one side, it said:

> Black will try to respect that [line length limit]. However, sometimes it won't be able to without breaking other rules. In those rare cases, auto-formatted code will exceed your allotted limit.

So black doesn't guarantee that your code is formatted at 88 chars, even when configured with `--line-length=88` (default). Black uses this limit as a "hint" more than a "rule".

OTOH, it also said:

> If you're using Flake8, you can bump max-line-length to 88 and forget about it. Alternatively, use Bugbear's B950 warning instead of E501 and keep the max line length at 80 which you are probably already using.

But that's not true. You can't "forget about it" because Black sometimes won't respect the limit. Both E501 at 88 and B950 at 80 behave the same: linter error at 89+ length. So, if Black happens to decide that a line of code is better at 90 characters that some other fancy style, you land on a unlucky situation where both tools will fight.

So, AFAICS, the best way to align flake8 and black is to:

1. Use flake8-bugbear
2. Enable B950
3. Disable E501
4. Set `max-line-length = 88`

This way, we also tell flake8 that 88 limit is a "hint" and not a "rule". The real rule will be 88 + 10%. If black decides that a line fits better in 97 characters than in 88 + some formatting, _that_ probably means your code has a real problem.

To avoid further confusion, I change the official recommendation here.

[1]: https://github.com/PyCQA/flake8-bugbear/tree/e82bb8d8b855adbf1f6f9757fb1527e93039e0d9#opinionated-warnings
---
 docs/the_black_code_style.md | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/docs/the_black_code_style.md b/docs/the_black_code_style.md
index a4e55c1744c..1cc591b8031 100644
--- a/docs/the_black_code_style.md
+++ b/docs/the_black_code_style.md
@@ -189,22 +189,22 @@ harder to work with line lengths exceeding 100 characters. It also adversely aff
 side-by-side diff review on typical screen resolutions. Long lines also make it harder
 to present code neatly in documentation or talk slides.
 
-If you're using Flake8, you can bump `max-line-length` to 88 and forget about it.
-Alternatively, use [Bugbear](https://github.com/PyCQA/flake8-bugbear)'s B950 warning
-instead of E501 and keep the max line length at 80 which you are probably already using.
-You'd do it like this:
+If you're using Flake8, you can bump `max-line-length` to 88 and mostly forget about it.
+However, it's better if you use [Bugbear](https://github.com/PyCQA/flake8-bugbear)'s
+B950 warning instead of E501, and bump the max line length to 88 (or the `--line-length`
+you used for black), which will align more with black's _"try to respect
+`--line-length`, but don't become crazy if you can't"_. You'd do it like this:
 
 ```ini
 [flake8]
-max-line-length = 80
+max-line-length = 88
 ...
 select = C,E,F,W,B,B950
 extend-ignore = E203, E501
 ```
 
-You'll find _Black_'s own .flake8 config file is configured like this. Explanation of
-why E203 is disabled can be found further in this documentation. And if you're curious
-about the reasoning behind B950,
+Explanation of why E203 is disabled can be found further in this documentation. And if
+you're curious about the reasoning behind B950,
 [Bugbear's documentation](https://github.com/PyCQA/flake8-bugbear#opinionated-warnings)
 explains it. The tl;dr is "it's like highway speed limits, we won't bother you if you
 overdo it by a few km/h".

From 0be7f96d9ce764db1b2b6e176f6e74a3cdece665 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Sat, 20 Mar 2021 15:15:55 -0400
Subject: [PATCH 0113/1034] Fix indentation in docs/editor_integration.md
 (#2056)

Numbered list entries' bodies need to be indented or else the list won't
render correctly.
---
 docs/editor_integration.md | 68 +++++++++++++++++++-------------------
 1 file changed, 34 insertions(+), 34 deletions(-)

diff --git a/docs/editor_integration.md b/docs/editor_integration.md
index ae24c768882..f2d21f21113 100644
--- a/docs/editor_integration.md
+++ b/docs/editor_integration.md
@@ -12,38 +12,38 @@ Options include the following:
 
 1. Install `black`.
 
-```console
-$ pip install black
-```
+   ```console
+   $ pip install black
+   ```
 
 2. Locate your `black` installation folder.
 
-On macOS / Linux / BSD:
+   On macOS / Linux / BSD:
 
-```console
-$ which black
-/usr/local/bin/black  # possible location
-```
+   ```console
+   $ which black
+   /usr/local/bin/black  # possible location
+   ```
 
-On Windows:
+   On Windows:
 
-```console
-$ where black
-%LocalAppData%\Programs\Python\Python36-32\Scripts\black.exe  # possible location
-```
+   ```console
+   $ where black
+   %LocalAppData%\Programs\Python\Python36-32\Scripts\black.exe  # possible location
+   ```
 
-Note that if you are using a virtual environment detected by PyCharm, this is an
-unneeded step. In this case the path to `black` is `$PyInterpreterDirectory$/black`.
+   Note that if you are using a virtual environment detected by PyCharm, this is an
+   unneeded step. In this case the path to `black` is `$PyInterpreterDirectory$/black`.
 
 3. Open External tools in PyCharm/IntelliJ IDEA
 
-On macOS:
+   On macOS:
 
-`PyCharm -> Preferences -> Tools -> External Tools`
+   `PyCharm -> Preferences -> Tools -> External Tools`
 
-On Windows / Linux / BSD:
+   On Windows / Linux / BSD:
 
-`File -> Settings -> Tools -> External Tools`
+   `File -> Settings -> Tools -> External Tools`
 
 4. Click the + icon to add a new external tool with the following values:
 
@@ -83,28 +83,28 @@ Wing supports black via the OS Commands tool, as explained in the Wing documenta
 
 1. Install `black`.
 
-```console
-$ pip install black
-```
+   ```console
+   $ pip install black
+   ```
 
 2. Make sure it runs from the command line, e.g.
 
-```console
-$ black --help
-```
+   ```console
+   $ black --help
+   ```
 
 3. In Wing IDE, activate the **OS Commands** panel and define the command **black** to
    execute black on the currently selected file:
 
-- Use the Tools -> OS Commands menu selection
-- click on **+** in **OS Commands** -> New: Command line..
-  - Title: black
-  - Command Line: black %s
-  - I/O Encoding: Use Default
-  - Key Binding: F1
-  - [x] Raise OS Commands when executed
-  - [x] Auto-save files before execution
-  - [x] Line mode
+   - Use the Tools -> OS Commands menu selection
+   - click on **+** in **OS Commands** -> New: Command line..
+     - Title: black
+     - Command Line: black %s
+     - I/O Encoding: Use Default
+     - Key Binding: F1
+     - [x] Raise OS Commands when executed
+     - [x] Auto-save files before execution
+     - [x] Line mode
 
 4. Select a file in the editor and press **F1** , or whatever key binding you selected
    in step 3, to reformat the file.

From 5d33f20a2a2c85cfb521ae9c5f9254bfe9fc2fd9 Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Sun, 21 Mar 2021 13:05:24 -0700
Subject: [PATCH 0114/1034] Add a GitHub CHANGELOG/News Check (#2057)

- Run grep to see commit has a line mentioning it to CHANGES.md
- Also add a label to disable this being required for PRs that don't need a change entry
---
 .github/workflows/changelog.yml | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)
 create mode 100644 .github/workflows/changelog.yml

diff --git a/.github/workflows/changelog.yml b/.github/workflows/changelog.yml
new file mode 100644
index 00000000000..434950d24f9
--- /dev/null
+++ b/.github/workflows/changelog.yml
@@ -0,0 +1,21 @@
+name: changelog
+
+on:
+  pull_request:
+    types: [opened, synchronize, labeled, unlabeled, reopened]
+
+jobs:
+  build:
+    name: Changelog Entry Check
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Grep CHANGES.md for PR number
+        if: contains(github.event.pull_request.labels.*.name, 'skip news') != true
+        run: |
+          grep -P "PR #${{ github.event.pull_request.number }}[^0-9]" CHANGES.md || \
+          (echo "Please add 'PR #${{ github.event.pull_request.number }}' change line to CHANGES.md" && \
+          exit 1)

From 580b4fe8bc8d859c228f2eea1c8335bb3e911b12 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Wed, 24 Mar 2021 19:38:07 -0400
Subject: [PATCH 0115/1034] Add entry for `--extend-exclude` in the right place
 (#2061)

The PR author added the changelog entry for their `extend-exclude` addition
in `docs/change_log.md` which is understandable but incorrect as it will be
overwritten since it's autogenerated from the readme.
---
 CHANGES.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/CHANGES.md b/CHANGES.md
index e6dcc1b967d..61fc35f43a4 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -26,6 +26,8 @@
 
 - use lowercase hex strings (#1692)
 
+- added `--extend-exclude` argument (PR #2005)
+
 - speed up caching by avoiding pathlib (#1950)
 
 - `--diff` correctly indicates when a file doesn't end in a newline (#1662)

From 4218ae18c06df82904b9c9eac166510ac0ebee7c Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Fri, 26 Mar 2021 07:21:18 -0700
Subject: [PATCH 0116/1034] Add `--skip-magic-trailing-comma` to CHANGES.md
 (#2064)

---
 CHANGES.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/CHANGES.md b/CHANGES.md
index 61fc35f43a4..7da7be7b842 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -13,6 +13,9 @@
 - `Black` no longer adds an incorrect space after a parenthesized assignment expression
   in if/while statements (#1655)
 
+- Added `--skip-magic-trailing-comma` / `-C` to avoid using trailing commas as a reason
+  to split lines (#1824)
+
 - fixed a crash when PWD=/ on POSIX (#1631)
 
 - fixed "I/O operation on closed file" when using --diff (#1664)

From dc8b0a43837a6280e0d7d7d4e71a5282083c6b01 Mon Sep 17 00:00:00 2001
From: Mark Bell <MarkCBell@users.noreply.github.com>
Date: Mon, 29 Mar 2021 00:01:37 +0100
Subject: [PATCH 0117/1034] GREP for PR reference accepts references that are
 split over a line (#2072)

Fixes #2070
---
 .github/workflows/changelog.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/changelog.yml b/.github/workflows/changelog.yml
index 434950d24f9..58a8c092edb 100644
--- a/.github/workflows/changelog.yml
+++ b/.github/workflows/changelog.yml
@@ -16,6 +16,6 @@ jobs:
       - name: Grep CHANGES.md for PR number
         if: contains(github.event.pull_request.labels.*.name, 'skip news') != true
         run: |
-          grep -P "PR #${{ github.event.pull_request.number }}[^0-9]" CHANGES.md || \
+          grep -Pz "PR( |\n\s*)#${{ github.event.pull_request.number }}[^0-9]" CHANGES.md || \
           (echo "Please add 'PR #${{ github.event.pull_request.number }}' change line to CHANGES.md" && \
           exit 1)

From c702588daa9f75855119d0656661ac17934efe35 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 29 Mar 2021 18:59:57 -0700
Subject: [PATCH 0118/1034] Bump pygments from 2.6.1 to 2.7.4 in /docs (#2076)

Bumps [pygments](https://github.com/pygments/pygments) from 2.6.1 to 2.7.4.
- [Release notes](https://github.com/pygments/pygments/releases)
- [Changelog](https://github.com/pygments/pygments/blob/master/CHANGES)
- [Commits](https://github.com/pygments/pygments/compare/2.6.1...2.7.4)

Signed-off-by: dependabot[bot] <support@github.com>

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 docs/requirements.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index 4cad9bc205b..fcb6809cadc 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,3 +1,3 @@
 recommonmark==0.6.0
 Sphinx==3.2.1
-Pygments==2.6.1
\ No newline at end of file
+Pygments==2.7.4
\ No newline at end of file

From ed9d58b7410f24446cedebd0f767b71b154f5f5b Mon Sep 17 00:00:00 2001
From: KotlinIsland <kotlinisland@users.noreply.github.com>
Date: Tue, 16 Mar 2021 19:31:18 +1000
Subject: [PATCH 0119/1034] don't require typed-ast

---
 CHANGES.md            |  5 +++++
 README.md             |  3 ++-
 setup.py              |  3 ++-
 src/black/__init__.py | 22 ++++++++++++++++++++--
 tox.ini               |  2 +-
 5 files changed, 30 insertions(+), 5 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 7da7be7b842..97a3be33c93 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -40,6 +40,11 @@
 
 - Lines ending with `fmt: skip` will now be not formatted (#1800)
 
+- PR #2053: Black no longer relies on typed-ast for Python 3.8 and higher
+
+- PR #2053: Python 2 support is now optional, install with
+  `python3 -m pip install black[python2]` to maintain support.
+
 #### _Packaging_
 
 - Self-contained native _Black_ binaries are now provided for releases via GitHub
diff --git a/README.md b/README.md
index 411a8c8609d..0be356e3b84 100644
--- a/README.md
+++ b/README.md
@@ -50,7 +50,8 @@ _Contents:_ **[Installation and usage](#installation-and-usage)** |
 ### Installation
 
 _Black_ can be installed by running `pip install black`. It requires Python 3.6.2+ to
-run but you can reformat Python 2 code with it, too.
+run. If you want to format Python 2 code as well, install with
+`pip install black[python2]`.
 
 #### Install from GitHub
 
diff --git a/setup.py b/setup.py
index efdf6933025..856c7fadb0c 100644
--- a/setup.py
+++ b/setup.py
@@ -71,7 +71,7 @@ def get_long_description() -> str:
         "click>=7.1.2",
         "appdirs",
         "toml>=0.10.1",
-        "typed-ast>=1.4.2",
+        "typed-ast>=1.4.2; python_version < '3.8'",
         "regex>=2020.1.8",
         "pathspec>=0.6, <1",
         "dataclasses>=0.6; python_version < '3.7'",
@@ -81,6 +81,7 @@ def get_long_description() -> str:
     extras_require={
         "d": ["aiohttp>=3.3.2", "aiohttp-cors"],
         "colorama": ["colorama>=0.4.3"],
+        "python2": ["typed-ast>=1.4.2"],
     },
     test_suite="tests.test_black",
     classifiers=[
diff --git a/src/black/__init__.py b/src/black/__init__.py
index a8f4f89a6bb..52a57695aef 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -48,7 +48,20 @@
 from dataclasses import dataclass, field, replace
 import click
 import toml
-from typed_ast import ast3, ast27
+
+try:
+    from typed_ast import ast3, ast27
+except ImportError:
+    if sys.version_info < (3, 8):
+        print(
+            "The typed_ast package is not installed.\n"
+            "You can install it with `python3 -m pip install typed-ast`.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    else:
+        ast3 = ast27 = ast
+
 from pathspec import PathSpec
 
 # lib2to3 fork
@@ -6336,7 +6349,12 @@ def parse_ast(src: str) -> Union[ast.AST, ast3.AST, ast27.AST]:
                 return ast3.parse(src, filename, feature_version=feature_version)
             except SyntaxError:
                 continue
-
+    if ast27.__name__ == "ast":
+        raise SyntaxError(
+            "The requested source code has invalid Python 3 syntax.\n"
+            "If you are trying to format Python 2 files please reinstall Black"
+            " with the 'python2' extra: `python3 -m pip install black[python2]`."
+        )
     return ast27.parse(src)
 
 
diff --git a/tox.ini b/tox.ini
index 500a2cad579..9bb809abe41 100644
--- a/tox.ini
+++ b/tox.ini
@@ -7,7 +7,7 @@ skip_install = True
 deps =
     -r{toxinidir}/test_requirements.txt
 commands =
-    pip install -e .[d]
+    pip install -e .[d,python2]
     coverage erase
     coverage run -m pytest tests
     coverage report

From 9451c57d1c60d70ddd55e21b44382ca96637398e Mon Sep 17 00:00:00 2001
From: Harish Rajagopal <harish.rajagopals@gmail.com>
Date: Thu, 1 Apr 2021 18:39:18 +0200
Subject: [PATCH 0120/1034] Support for top-level user configuration (#1899)

* Added support for top-level user configuration

At the user level, a TOML config can be specified in the following locations:
* Windows: ~\.black
* Unix-like: $XDG_CONFIG_HOME/black (~/.config/black fallback)

Instead of changing env vars for the entire black-primer process, they
are now changed only for the black subprocess, using a tmpdir.
---
 README.md               | 14 ++++++++++++
 docs/pyproject_toml.md  | 14 ++++++++++++
 src/black/__init__.py   | 22 ++++++++++++++++++-
 src/black_primer/lib.py | 47 ++++++++++++++++++++++++-----------------
 tests/test_black.py     | 36 +++++++++++++++++++++++++++++--
 5 files changed, 111 insertions(+), 22 deletions(-)

diff --git a/README.md b/README.md
index 0be356e3b84..b19e6e5e098 100644
--- a/README.md
+++ b/README.md
@@ -293,6 +293,20 @@ parent directories. It stops looking when it finds the file, or a `.git` directo
 If you're formatting standard input, _Black_ will look for configuration starting from
 the current working directory.
 
+You can use a "global" configuration, stored in a specific location in your home
+directory. This will be used as a fallback configuration, that is, it will be used if
+and only if _Black_ doesn't find any configuration as mentioned above. Depending on your
+operating system, this configuration file should be stored as:
+
+- Windows: `~\.black`
+- Unix-like (Linux, MacOS, etc.): `$XDG_CONFIG_HOME/black` (`~/.config/black` if the
+  `XDG_CONFIG_HOME` environment variable is not set)
+
+Note that these are paths to the TOML file itself (meaning that they shouldn't be named
+as `pyproject.toml`), not directories where you store the configuration. Here, `~`
+refers to the path to your home directory. On Windows, this will be something like
+`C:\\Users\UserName`.
+
 You can also explicitly specify the path to a particular file that you want with
 `--config`. In this situation _Black_ will not look for any other file.
 
diff --git a/docs/pyproject_toml.md b/docs/pyproject_toml.md
index 9acc4c03d7c..77c12b76be9 100644
--- a/docs/pyproject_toml.md
+++ b/docs/pyproject_toml.md
@@ -28,6 +28,20 @@ parent directories. It stops looking when it finds the file, or a `.git` directo
 If you're formatting standard input, _Black_ will look for configuration starting from
 the current working directory.
 
+You can use a "global" configuration, stored in a specific location in your home
+directory. This will be used as a fallback configuration, that is, it will be used if
+and only if _Black_ doesn't find any configuration as mentioned above. Depending on your
+operating system, this configuration file should be stored as:
+
+- Windows: `~\.black`
+- Unix-like (Linux, MacOS, etc.): `$XDG_CONFIG_HOME/black` (`~/.config/black` if the
+  `XDG_CONFIG_HOME` environment variable is not set)
+
+Note that these are paths to the TOML file itself (meaning that they shouldn't be named
+as `pyproject.toml`), not directories where you store the configuration. Here, `~`
+refers to the path to your home directory. On Windows, this will be something like
+`C:\\Users\UserName`.
+
 You can also explicitly specify the path to a particular file that you want with
 `--config`. In this situation _Black_ will not look for any other file.
 
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 52a57695aef..e85ffb37f88 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -306,7 +306,11 @@ def find_pyproject_toml(path_search_start: Iterable[str]) -> Optional[str]:
     """Find the absolute filepath to a pyproject.toml if it exists"""
     path_project_root = find_project_root(path_search_start)
     path_pyproject_toml = path_project_root / "pyproject.toml"
-    return str(path_pyproject_toml) if path_pyproject_toml.is_file() else None
+    if path_pyproject_toml.is_file():
+        return str(path_pyproject_toml)
+
+    path_user_pyproject_toml = find_user_pyproject_toml()
+    return str(path_user_pyproject_toml) if path_user_pyproject_toml.is_file() else None
 
 
 def parse_pyproject_toml(path_config: str) -> Dict[str, Any]:
@@ -6248,6 +6252,22 @@ def find_project_root(srcs: Iterable[str]) -> Path:
     return directory
 
 
+@lru_cache()
+def find_user_pyproject_toml() -> Path:
+    r"""Return the path to the top-level user configuration for black.
+
+    This looks for ~\.black on Windows and ~/.config/black on Linux and other
+    Unix systems.
+    """
+    if sys.platform == "win32":
+        # Windows
+        user_config_path = Path.home() / ".black"
+    else:
+        config_root = os.environ.get("XDG_CONFIG_HOME", "~/.config")
+        user_config_path = Path(config_root).expanduser() / "black"
+    return user_config_path.resolve()
+
+
 @dataclass
 class Report:
     """Provides a reformatting counter. Can be rendered with `str(report)`."""
diff --git a/src/black_primer/lib.py b/src/black_primer/lib.py
index 39ae93ba516..7999f6a3e36 100644
--- a/src/black_primer/lib.py
+++ b/src/black_primer/lib.py
@@ -13,6 +13,7 @@
 from shutil import rmtree, which
 from subprocess import CalledProcessError
 from sys import version_info
+from tempfile import TemporaryDirectory
 from typing import Any, Callable, Dict, NamedTuple, Optional, Sequence, Tuple
 from urllib.parse import urlparse
 
@@ -121,28 +122,36 @@ async def black_run(
         cmd.extend(*project_config["cli_arguments"])
     cmd.extend(["--check", "--diff", "."])
 
-    try:
-        _stdout, _stderr = await _gen_check_output(cmd, cwd=repo_path)
-    except asyncio.TimeoutError:
-        results.stats["failed"] += 1
-        LOG.error(f"Running black for {repo_path} timed out ({cmd})")
-    except CalledProcessError as cpe:
-        # TODO: Tune for smarter for higher signal
-        # If any other return value than 1 we raise - can disable project in config
-        if cpe.returncode == 1:
-            if not project_config["expect_formatting_changes"]:
+    with TemporaryDirectory() as tmp_path:
+        # Prevent reading top-level user configs by manipulating envionment variables
+        env = {
+            **os.environ,
+            "XDG_CONFIG_HOME": tmp_path,  # Unix-like
+            "USERPROFILE": tmp_path,  # Windows (changes `Path.home()` output)
+        }
+
+        try:
+            _stdout, _stderr = await _gen_check_output(cmd, cwd=repo_path, env=env)
+        except asyncio.TimeoutError:
+            results.stats["failed"] += 1
+            LOG.error(f"Running black for {repo_path} timed out ({cmd})")
+        except CalledProcessError as cpe:
+            # TODO: Tune for smarter for higher signal
+            # If any other return value than 1 we raise - can disable project in config
+            if cpe.returncode == 1:
+                if not project_config["expect_formatting_changes"]:
+                    results.stats["failed"] += 1
+                    results.failed_projects[repo_path.name] = cpe
+                else:
+                    results.stats["success"] += 1
+                return
+            elif cpe.returncode > 1:
                 results.stats["failed"] += 1
                 results.failed_projects[repo_path.name] = cpe
-            else:
-                results.stats["success"] += 1
-            return
-        elif cpe.returncode > 1:
-            results.stats["failed"] += 1
-            results.failed_projects[repo_path.name] = cpe
-            return
+                return
 
-        LOG.error(f"Unknown error with {repo_path}")
-        raise
+            LOG.error(f"Unknown error with {repo_path}")
+            raise
 
     # If we get here and expect formatting changes something is up
     if project_config["expect_formatting_changes"]:
diff --git a/tests/test_black.py b/tests/test_black.py
index 72e16a324a5..c603233efc4 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -296,6 +296,7 @@ def test_expression_ff(self) -> None:
 
     def test_expression_diff(self) -> None:
         source, _ = read_data("expression.py")
+        config = THIS_DIR / "data" / "empty_pyproject.toml"
         expected, _ = read_data("expression.diff")
         tmp_file = Path(black.dump_to_file(source))
         diff_header = re.compile(
@@ -303,7 +304,9 @@ def test_expression_diff(self) -> None:
             r"\d\d:\d\d:\d\d\.\d\d\d\d\d\d \+\d\d\d\d"
         )
         try:
-            result = BlackRunner().invoke(black.main, ["--diff", str(tmp_file)])
+            result = BlackRunner().invoke(
+                black.main, ["--diff", str(tmp_file), f"--config={config}"]
+            )
             self.assertEqual(result.exit_code, 0)
         finally:
             os.unlink(tmp_file)
@@ -320,11 +323,12 @@ def test_expression_diff(self) -> None:
 
     def test_expression_diff_with_color(self) -> None:
         source, _ = read_data("expression.py")
+        config = THIS_DIR / "data" / "empty_pyproject.toml"
         expected, _ = read_data("expression.diff")
         tmp_file = Path(black.dump_to_file(source))
         try:
             result = BlackRunner().invoke(
-                black.main, ["--diff", "--color", str(tmp_file)]
+                black.main, ["--diff", "--color", str(tmp_file), f"--config={config}"]
             )
         finally:
             os.unlink(tmp_file)
@@ -1842,6 +1846,34 @@ def test_find_project_root(self) -> None:
             self.assertEqual(black.find_project_root((src_dir,)), src_dir.resolve())
             self.assertEqual(black.find_project_root((src_python,)), src_dir.resolve())
 
+    @patch("black.find_user_pyproject_toml", black.find_user_pyproject_toml.__wrapped__)
+    def test_find_user_pyproject_toml_linux(self) -> None:
+        if system() == "Windows":
+            return
+
+        # Test if XDG_CONFIG_HOME is checked
+        with TemporaryDirectory() as workspace:
+            tmp_user_config = Path(workspace) / "black"
+            with patch.dict("os.environ", {"XDG_CONFIG_HOME": workspace}):
+                self.assertEqual(
+                    black.find_user_pyproject_toml(), tmp_user_config.resolve()
+                )
+
+        # Test fallback for XDG_CONFIG_HOME
+        with patch.dict("os.environ"):
+            os.environ.pop("XDG_CONFIG_HOME", None)
+            fallback_user_config = Path("~/.config").expanduser() / "black"
+            self.assertEqual(
+                black.find_user_pyproject_toml(), fallback_user_config.resolve()
+            )
+
+    def test_find_user_pyproject_toml_windows(self) -> None:
+        if system() != "Windows":
+            return
+
+        user_config_path = Path.home() / ".black"
+        self.assertEqual(black.find_user_pyproject_toml(), user_config_path.resolve())
+
     def test_bpo_33660_workaround(self) -> None:
         if system() == "Windows":
             return

From 125ed5b2601f0e74ded03b666132e3c37ae8af07 Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Thu, 1 Apr 2021 09:41:55 -0700
Subject: [PATCH 0121/1034] Add a GitHub Action to build + Upload black to PyPI
 (#1848)

* Add a GitHub Action to build + Upload black to PyPI
- Build a wheel + sdist
- Upload via twine using token stored in GitHub secrets
---
 .github/workflows/lint.yml        |  7 ++-----
 .github/workflows/pypi_upload.yml | 31 +++++++++++++++++++++++++++++++
 .pre-commit-config.yaml           |  2 +-
 3 files changed, 34 insertions(+), 6 deletions(-)
 create mode 100644 .github/workflows/pypi_upload.yml

diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index e01e9ade5e2..c46042d71b9 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -12,17 +12,14 @@ jobs:
       github.repository
 
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        python-version: [3.7]
 
     steps:
       - uses: actions/checkout@v2
 
-      - name: Set up Python ${{ matrix.python-version }}
+      - name: Set up Python
         uses: actions/setup-python@v2
         with:
-          python-version: ${{ matrix.python-version }}
+          python-version: 3.7
 
       - name: Install dependencies
         run: |
diff --git a/.github/workflows/pypi_upload.yml b/.github/workflows/pypi_upload.yml
new file mode 100644
index 00000000000..5df91d92165
--- /dev/null
+++ b/.github/workflows/pypi_upload.yml
@@ -0,0 +1,31 @@
+name: pypi_upload
+
+on:
+  release:
+    types: created
+
+jobs:
+  build:
+    name: PyPI Upload
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Set up Python
+        uses: actions/setup-python@v2
+
+      - name: Install latest pip, setuptools, twine + wheel
+        run: |
+          python -m pip install --upgrade pip setuptools twine wheel
+
+      - name: Build wheels
+        run: |
+          python setup.py bdist_wheel
+          python setup.py sdist
+
+      - name: Upload to PyPI via Twine
+        env:
+          TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
+        run: |
+          twine upload --verbose -u '__token__' dist/*
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 292ed5727d9..48a7429c1f2 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -13,7 +13,7 @@ repos:
         types_or: [python, pyi]
 
   - repo: https://gitlab.com/pycqa/flake8
-    rev: 3.8.1
+    rev: 3.8.4
     hooks:
       - id: flake8
         additional_dependencies: [flake8-bugbear]

From 53a6216cd57955837e84f6ea82ca650c86320b03 Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Thu, 1 Apr 2021 09:54:45 -0700
Subject: [PATCH 0122/1034] Add CONTRBUTING info about CHANGES.md requirement
 (#2073)

Instruct contributors to add the change line to help save maintainer / releaser time
---
 .github/workflows/changelog.yml |  4 ++--
 CONTRIBUTING.md                 | 17 +++++++++++++++++
 2 files changed, 19 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/changelog.yml b/.github/workflows/changelog.yml
index 58a8c092edb..d7ee50558d3 100644
--- a/.github/workflows/changelog.yml
+++ b/.github/workflows/changelog.yml
@@ -16,6 +16,6 @@ jobs:
       - name: Grep CHANGES.md for PR number
         if: contains(github.event.pull_request.labels.*.name, 'skip news') != true
         run: |
-          grep -Pz "PR( |\n\s*)#${{ github.event.pull_request.number }}[^0-9]" CHANGES.md || \
-          (echo "Please add 'PR #${{ github.event.pull_request.number }}' change line to CHANGES.md" && \
+          grep -Pz "\((\n\s*)?#${{ github.event.pull_request.number }}(\n\s*)?\)" CHANGES.md || \
+          (echo "Please add '(#${{ github.event.pull_request.number }})' change line to CHANGES.md" && \
           exit 1)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 571d870452b..8a3d8bf2830 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -58,6 +58,23 @@ $ tox -e fuzz
 $ black-primer [-k -w /tmp/black_test_repos]
 ```
 
+### News / Changelog Requirement
+
+`Black` has CI that will check for an entry corresponding to your PR in `CHANGES.md`. If
+you feel this PR 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:
+
+```md
+- `Black` is now more awesome (#X)
+```
+
+To workout X, checkout the latest issue and PR number and add 1. 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.
+
+_Suggestions welcome on how this could be a better less invasive flow._
+
 ### Docs Testing
 
 If you make changes to docs, you can test they still build locally too.

From 48dfda084a8c854a73c11b6c91c67deae5f86ca3 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Thu, 1 Apr 2021 17:24:18 -0400
Subject: [PATCH 0123/1034] Push contributors to use Next PR Number (#2080)

This is a tool of my own making. Right now our requirement to have the
PR number in the changelog entry is pretty painful / annoying since
the contributor either has to guess or add the # retroactively after
the PR creation. This tool should make it way less painful by making
it simple to get your PR number beforehand.
---
 CONTRIBUTING.md               |  9 ++++-----
 docs/contributing_to_black.md | 16 ++++++++++++++++
 2 files changed, 20 insertions(+), 5 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 8a3d8bf2830..bd6ebfca114 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -69,11 +69,10 @@ have a line in the following format:
 - `Black` is now more awesome (#X)
 ```
 
-To workout X, checkout the latest issue and PR number and add 1. 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.
-
-_Suggestions welcome on how this could be a better less invasive flow._
+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.
 
 ### Docs Testing
 
diff --git a/docs/contributing_to_black.md b/docs/contributing_to_black.md
index 562b43a76ac..b911b465afd 100644
--- a/docs/contributing_to_black.md
+++ b/docs/contributing_to_black.md
@@ -60,6 +60,22 @@ $ tox -e fuzz
 $ black-primer [-k -w /tmp/black_test_repos]
 ```
 
+### News / Changelog Requirement
+
+`Black` has CI that will check for an entry corresponding to your PR in `CHANGES.md`. If
+you feel this PR 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:
+
+```md
+- `Black` is now more awesome (#X)
+```
+
+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.
+
 ### Docs Testing
 
 If you make changes to docs, you can test they still build locally too.

From 201b331e55948d187fc150101bebf5262e160290 Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Thu, 1 Apr 2021 16:15:50 -0700
Subject: [PATCH 0124/1034] Run lint in latest python + update precommit
 (#2081)

- Lets move to latest and greatest of lints
---
 .github/workflows/lint.yml | 2 --
 .pre-commit-config.yaml    | 4 ++--
 2 files changed, 2 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index c46042d71b9..2480a5ec131 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -18,8 +18,6 @@ jobs:
 
       - name: Set up Python
         uses: actions/setup-python@v2
-        with:
-          python-version: 3.7
 
       - name: Install dependencies
         run: |
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 48a7429c1f2..e461aa39c9d 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -13,13 +13,13 @@ repos:
         types_or: [python, pyi]
 
   - repo: https://gitlab.com/pycqa/flake8
-    rev: 3.8.4
+    rev: 3.9.0
     hooks:
       - id: flake8
         additional_dependencies: [flake8-bugbear]
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v0.780
+    rev: v0.812
     hooks:
       - id: mypy
         exclude: ^docs/conf.py

From e114ef5514e95cb9908b38c2397978f2070c1b0e Mon Sep 17 00:00:00 2001
From: Jakub Warczarek <jakub.warczarek@gmail.com>
Date: Sun, 4 Apr 2021 16:21:33 +0200
Subject: [PATCH 0125/1034] Get rid of redundant spaces in docs (#2085)

Thanks!
---
 README.md             | 14 +++++++-------
 src/black/__init__.py | 14 +++++++-------
 2 files changed, 14 insertions(+), 14 deletions(-)

diff --git a/README.md b/README.md
index b19e6e5e098..0bc0228b7d0 100644
--- a/README.md
+++ b/README.md
@@ -103,8 +103,8 @@ Options:
                                   split lines.
 
   --check                         Don't write the files back, just return the
-                                  status.  Return code 0 means nothing would
-                                  change.  Return code 1 means some files
+                                  status. Return code 0 means nothing would
+                                  change. Return code 1 means some files
                                   would be reformatted. Return code 123 means
                                   there was an internal error.
 
@@ -119,20 +119,20 @@ Options:
 
   --include TEXT                  A regular expression that matches files and
                                   directories that should be included on
-                                  recursive searches.  An empty value means
+                                  recursive searches. An empty value means
                                   all files are included regardless of the
-                                  name.  Use forward slashes for directories
-                                  on all platforms (Windows, too).  Exclusions
+                                  name. Use forward slashes for directories
+                                  on all platforms (Windows, too). Exclusions
                                   are calculated first, inclusions later.
                                   [default: \.pyi?$]
 
   --exclude TEXT                  A regular expression that matches files and
                                   directories that should be excluded on
-                                  recursive searches.  An empty value means no
+                                  recursive searches. An empty value means no
                                   paths are excluded. Use forward slashes for
                                   directories on all platforms (Windows, too).
                                   Exclusions are calculated first, inclusions
-                                  later.  [default: /(\.direnv|\.eggs|\.git|\.
+                                  later. [default: /(\.direnv|\.eggs|\.git|\.
                                   hg|\.mypy_cache|\.nox|\.tox|\.venv|\.svn|_bu
                                   ild|buck-out|build|dist)/]
 
diff --git a/src/black/__init__.py b/src/black/__init__.py
index e85ffb37f88..431ee027270 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -445,8 +445,8 @@ def validate_regex(
     "--check",
     is_flag=True,
     help=(
-        "Don't write the files back, just return the status.  Return code 0 means"
-        " nothing would change.  Return code 1 means some files would be reformatted."
+        "Don't write the files back, just return the status. Return code 0 means"
+        " nothing would change. Return code 1 means some files would be reformatted."
         " Return code 123 means there was an internal error."
     ),
 )
@@ -472,9 +472,9 @@ def validate_regex(
     callback=validate_regex,
     help=(
         "A regular expression that matches files and directories that should be"
-        " included on recursive searches.  An empty value means all files are included"
-        " regardless of the name.  Use forward slashes for directories on all platforms"
-        " (Windows, too).  Exclusions are calculated first, inclusions later."
+        " included on recursive searches. An empty value means all files are included"
+        " regardless of the name. Use forward slashes for directories on all platforms"
+        " (Windows, too). Exclusions are calculated first, inclusions later."
     ),
     show_default=True,
 )
@@ -485,8 +485,8 @@ def validate_regex(
     callback=validate_regex,
     help=(
         "A regular expression that matches files and directories that should be"
-        " excluded on recursive searches.  An empty value means no paths are excluded."
-        " Use forward slashes for directories on all platforms (Windows, too). "
+        " excluded on recursive searches. An empty value means no paths are excluded."
+        " Use forward slashes for directories on all platforms (Windows, too)."
         " Exclusions are calculated first, inclusions later."
     ),
     show_default=True,

From 9cbf1f162261b64ebb150639b608be0c38f23e2b Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Tue, 6 Apr 2021 11:07:57 -0700
Subject: [PATCH 0126/1034] Bump urllib3 from 1.26.3 to 1.26.4 (#2090)

Bumps [urllib3](https://github.com/urllib3/urllib3) from 1.26.3 to 1.26.4.
- [Release notes](https://github.com/urllib3/urllib3/releases)
- [Changelog](https://github.com/urllib3/urllib3/blob/main/CHANGES.rst)
- [Commits](https://github.com/urllib3/urllib3/compare/1.26.3...1.26.4)

Signed-off-by: dependabot[bot] <support@github.com>

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 Pipfile.lock | 89 +++++++++++++++++++++++++++++++++-------------------
 1 file changed, 56 insertions(+), 33 deletions(-)

diff --git a/Pipfile.lock b/Pipfile.lock
index 9cdcba2a0ea..3d908dc90f3 100644
--- a/Pipfile.lock
+++ b/Pipfile.lock
@@ -569,20 +569,20 @@
         },
         "cryptography": {
             "hashes": [
-                "sha256:066bc53f052dfeda2f2d7c195cf16fb3e5ff13e1b6b7415b468514b40b381a5b",
-                "sha256:0923ba600d00718d63a3976f23cab19aef10c1765038945628cd9be047ad0336",
-                "sha256:2d32223e5b0ee02943f32b19245b61a62db83a882f0e76cc564e1cec60d48f87",
-                "sha256:4169a27b818de4a1860720108b55a2801f32b6ae79e7f99c00d79f2a2822eeb7",
-                "sha256:57ad77d32917bc55299b16d3b996ffa42a1c73c6cfa829b14043c561288d2799",
-                "sha256:5ecf2bcb34d17415e89b546dbb44e73080f747e504273e4d4987630493cded1b",
-                "sha256:600cf9bfe75e96d965509a4c0b2b183f74a4fa6f5331dcb40fb7b77b7c2484df",
-                "sha256:66b57a9ca4b3221d51b237094b0303843b914b7d5afd4349970bb26518e350b0",
-                "sha256:93cfe5b7ff006de13e1e89830810ecbd014791b042cbe5eec253be11ac2b28f3",
-                "sha256:9e98b452132963678e3ac6c73f7010fe53adf72209a32854d55690acac3f6724",
-                "sha256:df186fcbf86dc1ce56305becb8434e4b6b7504bc724b71ad7a3239e0c9d14ef2",
-                "sha256:fec7fb46b10da10d9e1d078d1ff8ed9e05ae14f431fdbd11145edd0550b9a964"
-            ],
-            "version": "==3.4.6"
+                "sha256:0f1212a66329c80d68aeeb39b8a16d54ef57071bf22ff4e521657b27372e327d",
+                "sha256:1e056c28420c072c5e3cb36e2b23ee55e260cb04eee08f702e0edfec3fb51959",
+                "sha256:240f5c21aef0b73f40bb9f78d2caff73186700bf1bc6b94285699aff98cc16c6",
+                "sha256:26965837447f9c82f1855e0bc8bc4fb910240b6e0d16a664bb722df3b5b06873",
+                "sha256:37340614f8a5d2fb9aeea67fd159bfe4f5f4ed535b1090ce8ec428b2f15a11f2",
+                "sha256:3d10de8116d25649631977cb37da6cbdd2d6fa0e0281d014a5b7d337255ca713",
+                "sha256:3d8427734c781ea5f1b41d6589c293089704d4759e34597dce91014ac125aad1",
+                "sha256:7ec5d3b029f5fa2b179325908b9cd93db28ab7b85bb6c1db56b10e0b54235177",
+                "sha256:8e56e16617872b0957d1c9742a3f94b43533447fd78321514abbe7db216aa250",
+                "sha256:de4e5f7f68220d92b7637fc99847475b59154b7a1b3868fb7385337af54ac9ca",
+                "sha256:eb8cc2afe8b05acbd84a43905832ec78e7b3873fb124ca190f574dca7389a87d",
+                "sha256:ee77aa129f481be46f8d92a1a7db57269a2f23052d5f2433b4621bb457081cc9"
+            ],
+            "version": "==3.4.7"
         },
         "distlib": {
             "hashes": [
@@ -624,10 +624,10 @@
         },
         "identify": {
             "hashes": [
-                "sha256:de7129142a5c86d75a52b96f394d94d96d497881d2aaf8eafe320cdbe8ac4bcc",
-                "sha256:e0dae57c0397629ce13c289f6ddde0204edf518f557bfdb1e56474aa143e77c3"
+                "sha256:43cb1965e84cdd247e875dec6d13332ef5be355ddc16776396d98089b9053d87",
+                "sha256:c7c0f590526008911ccc5ceee6ed7b085cbc92f7b6591d0ee5913a130ad64034"
             ],
-            "version": "==1.5.14"
+            "version": "==2.2.2"
         },
         "idna": {
             "hashes": [
@@ -643,6 +643,13 @@
             ],
             "version": "==1.2.0"
         },
+        "importlib-metadata": {
+            "hashes": [
+                "sha256:c9db46394197244adf2f0b08ec5bc3cf16757e9590b02af1fca085c16c0d600a",
+                "sha256:d2d46ef77ffc85cbf7dac7e81dd663fde71c45326131bea8033b9bad42268ebe"
+            ],
+            "version": "==3.10.0"
+        },
         "jeepney": {
             "hashes": [
                 "sha256:7d59b6622675ca9e993a6bd38de845051d315f8b0c72cca3aef733a20b648657",
@@ -660,10 +667,10 @@
         },
         "keyring": {
             "hashes": [
-                "sha256:9acb3e1452edbb7544822b12fd25459078769e560fa51f418b6d00afaa6178df",
-                "sha256:9f44660a5d4931bdc14c08a1d01ef30b18a7a8147380710d8c9f9531e1f6c3c0"
+                "sha256:045703609dd3fccfcdb27da201684278823b72af515aedec1a8515719a038cb8",
+                "sha256:8f607d7d1cc502c43a932a275a56fe47db50271904513a379d39df1af277ac48"
             ],
-            "version": "==22.0.1"
+            "version": "==23.0.1"
         },
         "markupsafe": {
             "hashes": [
@@ -859,10 +866,10 @@
         },
         "pygments": {
             "hashes": [
-                "sha256:37a13ba168a02ac54cc5891a42b1caec333e59b66addb7fa633ea8a6d73445c0",
-                "sha256:b21b072d0ccdf29297a82a2363359d99623597b8a265b8081760e4d0f7153c88"
+                "sha256:2656e1a6edcdabf4275f9a3640db59fd5de107d88e8663c5d4e9a0fa62f77f94",
+                "sha256:534ef71d539ae97d4c3a4cf7d6f110f214b0e687e92f9cb9d2a3b0d3101289c8"
             ],
-            "version": "==2.8.0"
+            "version": "==2.8.1"
         },
         "pyparsing": {
             "hashes": [
@@ -892,15 +899,23 @@
                 "sha256:5accb17103e43963b80e6f837831f38d314a0495500067cb25afab2e8d7a4018",
                 "sha256:607774cbba28732bfa802b54baa7484215f530991055bb562efbed5b2f20a45e",
                 "sha256:6c78645d400265a062508ae399b60b8c167bf003db364ecb26dcab2bda048253",
+                "sha256:72a01f726a9c7851ca9bfad6fd09ca4e090a023c00945ea05ba1638c09dc3347",
                 "sha256:74c1485f7707cf707a7aef42ef6322b8f97921bd89be2ab6317fd782c2d53183",
+                "sha256:895f61ef02e8fed38159bb70f7e100e00f471eae2bc838cd0f4ebb21e28f8541",
                 "sha256:8c1be557ee92a20f184922c7b6424e8ab6691788e6d86137c5d93c1a6ec1b8fb",
                 "sha256:bb4191dfc9306777bc594117aee052446b3fa88737cd13b7188d0e7aa8162185",
+                "sha256:bfb51918d4ff3d77c1c856a9699f8492c612cde32fd3bcd344af9be34999bfdc",
                 "sha256:c20cfa2d49991c8b4147af39859b167664f2ad4561704ee74c1de03318e898db",
+                "sha256:cb333c16912324fd5f769fff6bc5de372e9e7a202247b48870bc251ed40239aa",
                 "sha256:d2d9808ea7b4af864f35ea216be506ecec180628aced0704e34aca0b040ffe46",
+                "sha256:d483ad4e639292c90170eb6f7783ad19490e7a8defb3e46f97dfe4bacae89122",
                 "sha256:dd5de0646207f053eb0d6c74ae45ba98c3395a571a2891858e87df7c9b9bd51b",
                 "sha256:e1d4970ea66be07ae37a3c2e48b5ec63f7ba6804bdddfdbd3cfd954d25a82e63",
                 "sha256:e4fac90784481d221a8e4b1162afa7c47ed953be40d31ab4629ae917510051df",
-                "sha256:fa5ae20527d8e831e8230cbffd9f8fe952815b2b7dae6ffec25318803a7528fc"
+                "sha256:fa5ae20527d8e831e8230cbffd9f8fe952815b2b7dae6ffec25318803a7528fc",
+                "sha256:fd7f6999a8070df521b6384004ef42833b9bd62cfee11a09bda1079b4b704247",
+                "sha256:fdc842473cd33f45ff6bce46aea678a54e3d21f1b61a7750ce3c498eedfe25d6",
+                "sha256:fe69978f3f768926cfa37b867e3843918e012cf83f680806599ddce33c2c68b0"
             ],
             "version": "==5.4.1"
         },
@@ -1078,10 +1093,10 @@
         },
         "tqdm": {
             "hashes": [
-                "sha256:2c44efa73b8914dba7807aefd09653ac63c22b5b4ea34f7a80973f418f1a3089",
-                "sha256:c23ac707e8e8aabb825e4d91f8e17247f9cc14b0d64dd9e97be0781e9e525bba"
+                "sha256:daec693491c52e9498632dfbe9ccfc4882a557f5fa08982db1b4d3adbe0887c3",
+                "sha256:ebdebdb95e3477ceea267decfc0784859aa3df3e27e22d23b83e9b272bf157ae"
             ],
-            "version": "==4.58.0"
+            "version": "==4.60.0"
         },
         "twine": {
             "hashes": [
@@ -1138,17 +1153,18 @@
         },
         "urllib3": {
             "hashes": [
-                "sha256:1b465e494e3e0d8939b50680403e3aedaa2bc434b7d5af64dfd3c958d7f5ae80",
-                "sha256:de3eedaad74a2683334e282005cd8d7f22f4d55fa690a2a1020a416cb0a47e73"
+                "sha256:2f4da4594db7e1e110a944bb1b551fdf4e6c136ad42e4234131391e21eb5b0df",
+                "sha256:e7b021f7241115872f92f43c6508082facffbd1c048e3c6e2bb9c2a157e28937"
             ],
-            "version": "==1.26.3"
+            "index": "pypi",
+            "version": "==1.26.4"
         },
         "virtualenv": {
             "hashes": [
-                "sha256:147b43894e51dd6bba882cf9c282447f780e2251cd35172403745fc381a0a80d",
-                "sha256:2be72df684b74df0ea47679a7df93fd0e04e72520022c57b479d8f881485dbe3"
+                "sha256:49ec4eb4c224c6f7dd81bb6d0a28a09ecae5894f4e593c89b0db0885f565a107",
+                "sha256:83f95875d382c7abafe06bd2a4cdd1b363e1bb77e02f155ebe8ac082a916b37c"
             ],
-            "version": "==20.4.2"
+            "version": "==20.4.3"
         },
         "webencodings": {
             "hashes": [
@@ -1206,6 +1222,13 @@
                 "sha256:fcbb48a93e8699eae920f8d92f7160c03567b421bc17362a9ffbbd706a816f71"
             ],
             "version": "==1.6.3"
+        },
+        "zipp": {
+            "hashes": [
+                "sha256:3607921face881ba3e026887d8150cca609d517579abe052ac81fc5aeffdbd76",
+                "sha256:51cb66cc54621609dd593d1787f286ee42a5c0adbb4b29abea5a63edc3e03098"
+            ],
+            "version": "==3.4.1"
         }
     }
 }

From 8e0803e7e5acabdd28b80258f15d8aebf11fbb4c Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Wed, 7 Apr 2021 21:13:11 -0700
Subject: [PATCH 0127/1034] Add `black` Dockerfile (#1916)

* Add `black` Dockerfile
- Build a `black` container based on python3-slim
- Test: `docker build --network-host --tag black .`
```console
cooper-mbp1:black cooper$ docker image ls
REPOSITORY                                         TAG            IMAGE ID       CREATED              SIZE
black                                              latest         0c7636402ac2   4 seconds ago        332MB
```

Addresses part of #1914

* Build with colorama + d extra installs - Adds ~9mb

* Combine all build commands in 1 run
- Combine the commands all into 1 RUN to down the size
- Get to 65.98 MB image size now: https://hub.docker.com/repository/docker/cooperlees/black/tags?page=1&ordering=last_updated

* Add rm -r of /var/lib/apt/lists/* + save 10mb down to 55mb
---
 Dockerfile | 14 ++++++++++++++
 1 file changed, 14 insertions(+)
 create mode 100644 Dockerfile

diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 00000000000..9542479eca5
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,14 @@
+FROM python:3-slim
+
+RUN mkdir /src
+COPY . /src/
+RUN pip install --no-cache-dir --upgrade pip setuptools wheel \
+    && apt update && apt install -y git \
+    && cd /src \
+    && pip install --no-cache-dir .[colorama,d] \
+    && rm -rf /src \
+    && apt remove -y git \
+    && apt autoremove -y \
+    && rm -rf /var/lib/apt/lists/*
+
+CMD ["black"]

From 4d36304a2c70a5b6e39cdabf404fe72186fc8202 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Thu, 8 Apr 2021 10:25:37 -0700
Subject: [PATCH 0128/1034] Fix error from upcoming typeshed change (#2096)

See python/typeshed#5190
---
 src/black/__init__.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index 431ee027270..54d6edf760a 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -847,7 +847,7 @@ async def schedule_formatting(
         ): src
         for src in sorted(sources)
     }
-    pending: Iterable["asyncio.Future[bool]"] = tasks.keys()
+    pending = tasks.keys()
     try:
         loop.add_signal_handler(signal.SIGINT, cancel, pending)
         loop.add_signal_handler(signal.SIGTERM, cancel, pending)

From e4003c2c439fc08a407d3024a195c010f03c4173 Mon Sep 17 00:00:00 2001
From: johnthagen <johnthagen@users.noreply.github.com>
Date: Sat, 10 Apr 2021 08:07:34 -0400
Subject: [PATCH 0129/1034] Exclude venv directory by default (#1683)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Łukasz Langa <lukasz@langa.pl>
---
 CHANGES.md                     | 2 ++
 README.md                      | 4 ++--
 docs/installation_and_usage.md | 4 ++--
 src/black/__init__.py          | 2 +-
 4 files changed, 7 insertions(+), 5 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 97a3be33c93..6340f60ae59 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -45,6 +45,8 @@
 - PR #2053: Python 2 support is now optional, install with
   `python3 -m pip install black[python2]` to maintain support.
 
+- Exclude `venv` directory by default (#1683)
+
 #### _Packaging_
 
 - Self-contained native _Black_ binaries are now provided for releases via GitHub
diff --git a/README.md b/README.md
index 0bc0228b7d0..ed9f105f5aa 100644
--- a/README.md
+++ b/README.md
@@ -133,8 +133,8 @@ Options:
                                   directories on all platforms (Windows, too).
                                   Exclusions are calculated first, inclusions
                                   later. [default: /(\.direnv|\.eggs|\.git|\.
-                                  hg|\.mypy_cache|\.nox|\.tox|\.venv|\.svn|_bu
-                                  ild|buck-out|build|dist)/]
+                                  hg|\.mypy_cache|\.nox|\.tox|\.venv|venv|\.sv
+                                  n|_build|buck-out|build|dist)/]
 
   --extend-exclude TEXT           Like --exclude, but adds additional files
                                   and directories on top of the excluded
diff --git a/docs/installation_and_usage.md b/docs/installation_and_usage.md
index bb554eb6744..fcde49f4e3a 100644
--- a/docs/installation_and_usage.md
+++ b/docs/installation_and_usage.md
@@ -87,8 +87,8 @@ Options:
                                   directories on all platforms (Windows, too).
                                   Exclusions are calculated first, inclusions
                                   later.  [default: /(\.direnv|\.eggs|\.git|\.
-                                  hg|\.mypy_cache|\.nox|\.tox|\.venv|\.svn|_bu
-                                  ild|buck-out|build|dist)/]
+                                  hg|\.mypy_cache|\.nox|\.tox|\.venv|venv|\.sv
+                                  n|_build|buck-out|build|dist)/]
 
   --force-exclude TEXT            Like --exclude, but files and directories
                                   matching this regex will be excluded even
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 54d6edf760a..0065beafe0e 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -82,7 +82,7 @@
     import colorama  # noqa: F401
 
 DEFAULT_LINE_LENGTH = 88
-DEFAULT_EXCLUDES = r"/(\.direnv|\.eggs|\.git|\.hg|\.mypy_cache|\.nox|\.tox|\.venv|\.svn|_build|buck-out|build|dist)/"  # noqa: B950
+DEFAULT_EXCLUDES = r"/(\.direnv|\.eggs|\.git|\.hg|\.mypy_cache|\.nox|\.tox|\.venv|venv|\.svn|_build|buck-out|build|dist)/"  # noqa: B950
 DEFAULT_INCLUDES = r"\.pyi?$"
 CACHE_DIR = Path(user_cache_dir("black", version=__version__))
 STDIN_PLACEHOLDER = "__BLACK_STDIN_FILENAME__"

From 2116eca51f1108ebc924185c87bc363d8e0329b3 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Sun, 11 Apr 2021 07:49:42 -0700
Subject: [PATCH 0130/1034] fix typing issue around lru_cache arguments (#2098)

This was found by python/mypy#10308
---
 src/black/__init__.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index 0065beafe0e..2bb42a470ea 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -302,7 +302,7 @@ def supports_feature(target_versions: Set[TargetVersion], feature: Feature) -> b
     return all(feature in VERSION_TO_FEATURES[version] for version in target_versions)
 
 
-def find_pyproject_toml(path_search_start: Iterable[str]) -> Optional[str]:
+def find_pyproject_toml(path_search_start: Tuple[str, ...]) -> Optional[str]:
     """Find the absolute filepath to a pyproject.toml if it exists"""
     path_project_root = find_project_root(path_search_start)
     path_pyproject_toml = path_project_root / "pyproject.toml"
@@ -6214,7 +6214,7 @@ def gen_python_files(
 
 
 @lru_cache()
-def find_project_root(srcs: Iterable[str]) -> Path:
+def find_project_root(srcs: Tuple[str, ...]) -> Path:
     """Return a directory containing .git, .hg, or pyproject.toml.
 
     That directory will be a common parent of all files and directories

From ea4e714b9a3b636afd8e81c5c5c916fcf8e6ed42 Mon Sep 17 00:00:00 2001
From: Simon <32608483+J-Exodus@users.noreply.github.com>
Date: Mon, 12 Apr 2021 07:00:03 +1000
Subject: [PATCH 0131/1034] Added not formatting files in gitignore (psf#1682)
 (#1734)

---
 docs/pyproject_toml.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/pyproject_toml.md b/docs/pyproject_toml.md
index 77c12b76be9..ed88f37aa4a 100644
--- a/docs/pyproject_toml.md
+++ b/docs/pyproject_toml.md
@@ -48,6 +48,8 @@ You can also explicitly specify the path to a particular file that you want with
 If you're running with `--verbose`, you will see a blue message if a file was found and
 used.
 
+Files listed within a projects `.gitignore` file will not be formatted by _Black_.
+
 Please note `blackd` will not use `pyproject.toml` configuration.
 
 ## Configuration format

From d960d5d238bc8c73010a3ca5a9f316678ad91e6f Mon Sep 17 00:00:00 2001
From: Pierre Sassoulas <pierre.sassoulas@gmail.com>
Date: Sun, 11 Apr 2021 23:41:22 +0200
Subject: [PATCH 0132/1034] Remove NBSP at the beginning of comments (#2092)

Closes #2091
---
 CHANGES.md                                |  2 ++
 src/black/__init__.py                     |  7 ++++
 tests/data/comments7.py                   |  7 +++-
 tests/data/comments_non_breaking_space.py | 44 +++++++++++++++++++++++
 tests/test_format.py                      |  1 +
 5 files changed, 60 insertions(+), 1 deletion(-)
 create mode 100644 tests/data/comments_non_breaking_space.py

diff --git a/CHANGES.md b/CHANGES.md
index 6340f60ae59..12e8d453277 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -4,6 +4,8 @@
 
 #### _Black_
 
+- `Black` now cleans up leading non-breaking spaces in comments (#2092)
+
 - `Black` now respects `--skip-string-normalization` when normalizing multiline
   docstring quotes (#1637)
 
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 2bb42a470ea..36716474e8c 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -2709,6 +2709,13 @@ def make_comment(content: str) -> str:
 
     if content[0] == "#":
         content = content[1:]
+    NON_BREAKING_SPACE = " "
+    if (
+        content
+        and content[0] == NON_BREAKING_SPACE
+        and not content.lstrip().startswith("type:")
+    ):
+        content = " " + content[1:]  # Replace NBSP by a simple space
     if content and content[0] not in " !:#'%":
         content = " " + content
     return "#" + content
diff --git a/tests/data/comments7.py b/tests/data/comments7.py
index 0e2bd35bf55..ca9d7c62b21 100644
--- a/tests/data/comments7.py
+++ b/tests/data/comments7.py
@@ -129,6 +129,8 @@ def test_fails_invalid_post_data(
     ):
         ...
 
+square = Square(4) # type: Optional[Square]
+
 # output
 
 from .config import (
@@ -263,4 +265,7 @@ class C:
     def test_fails_invalid_post_data(
         self, pyramid_config, db_request, post_data, message
     ):
-        ...
\ No newline at end of file
+        ...
+
+
+square = Square(4)  # type: Optional[Square]
diff --git a/tests/data/comments_non_breaking_space.py b/tests/data/comments_non_breaking_space.py
new file mode 100644
index 00000000000..e17c3f4ca39
--- /dev/null
+++ b/tests/data/comments_non_breaking_space.py
@@ -0,0 +1,44 @@
+from .config import (  ConfigTypeAttributes,    Int,    Path,    # String,
+    # DEFAULT_TYPE_ATTRIBUTES,
+)
+
+result = 1  # A simple comment
+result = (    1, ) # Another one
+
+result = 1    # type: ignore
+result = 1# This comment is talking about type: ignore
+square = Square(4) # type: Optional[Square]
+
+def function(a:int=42):
+    """ This docstring is already formatted
+       a
+       b
+    """
+    #    There's a NBSP + 3 spaces before
+    #    And 4 spaces on the next line
+    pass
+
+# output
+from .config import (
+    ConfigTypeAttributes,
+    Int,
+    Path,  # String,
+    # DEFAULT_TYPE_ATTRIBUTES,
+)
+
+result = 1  # A simple comment
+result = (1,)  # Another one
+
+result = 1  #  type: ignore
+result = 1  # This comment is talking about type: ignore
+square = Square(4)  #  type: Optional[Square]
+
+
+def function(a: int = 42):
+    """This docstring is already formatted
+    a
+    b
+    """
+    #    There's a NBSP + 3 spaces before
+    #    And 4 spaces on the next line
+    pass
diff --git a/tests/test_format.py b/tests/test_format.py
index e0cb0b74195..eabec8c7219 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -27,6 +27,7 @@
     "comments5",
     "comments6",
     "comments7",
+    "comments_non_breaking_space",
     "comment_after_escaped_newline",
     "composition",
     "composition_no_trailing_comma",

From 6d0bdc2f38d57ddf07e7d127215d51f8553997f9 Mon Sep 17 00:00:00 2001
From: Pierre Verkest <pierreverkest84@gmail.com>
Date: Mon, 12 Apr 2021 15:18:11 +0200
Subject: [PATCH 0133/1034] Add missing instructions to make test passed
 (#2100)

---
 .github/ISSUE_TEMPLATE/bug_report.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
index e652f17c94b..f4a438622aa 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -28,7 +28,8 @@ assignees: ""
 2. Or run _Black_ on your machine:
    - create a new virtualenv (make sure it's the same Python version);
    - clone this repository;
-   - run `pip install -e .`;
+   - run `pip install -e .[d,python2]`;
+   - run `pip install -r test_requirements.txt`
    - make sure it's sane by running `python -m unittest`; and
    - run `black` like you did last time.
 

From 9eb29a6d4733c0e467ba5c1c54361f097cc1c305 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Laurent=20Tr=C3=A9guier?= <laurent@treguier.org>
Date: Fri, 16 Apr 2021 19:41:19 +0200
Subject: [PATCH 0134/1034] Fix small comment typo (#2112)

We probably don't need to fall back on "polling" when setting up an asyncio loop
---
 src/black/__init__.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index 36716474e8c..bb8f8c7422a 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -784,7 +784,7 @@ def reformat_many(
     except (ImportError, OSError):
         # we arrive here if the underlying system does not support multi-processing
         # like in AWS Lambda or Termux, in which case we gracefully fallback to
-        # a ThreadPollExecutor with just a single worker (more workers would not do us
+        # a ThreadPoolExecutor with just a single worker (more workers would not do us
         # any good due to the Global Interpreter Lock)
         executor = ThreadPoolExecutor(max_workers=1)
 

From 7b4ca4bd90c148d72548048f5109537a555aaf77 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Felix=20Hild=C3=A9n?= <felix.hilden@gmail.com>
Date: Mon, 19 Apr 2021 00:18:39 +0300
Subject: [PATCH 0135/1034] Instructions on documenting code style
 modifications (#2109)

---
 CONTRIBUTING.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index bd6ebfca114..f2a4ee20c99 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -74,6 +74,12 @@ To workout X, please use
 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.
+
 ### Docs Testing
 
 If you make changes to docs, you can test they still build locally too.

From 1fc3215e8c8856094b20d497e4e0e3e547ed38eb Mon Sep 17 00:00:00 2001
From: Mark Bell <MarkCBell@users.noreply.github.com>
Date: Thu, 22 Apr 2021 16:23:41 +0100
Subject: [PATCH 0136/1034] Make black remove leading and trailing spaces from
 one-line docstrings (#1740)

Fixes #1738. Fixes #1812.

Previously, Black removed leading and trailing spaces in multiline docstrings but failed to remove them from one-line docstrings.
---
 CHANGES.md                   |  3 +++
 src/black/__init__.py        | 40 ++++++++++++++++++++++++------------
 src/black_primer/primer.json | 10 ++++-----
 tests/data/docstring.py      | 36 +++++++++++++++++++++++++++++++-
 tox.ini                      |  2 +-
 5 files changed, 71 insertions(+), 20 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 12e8d453277..f911fdf77ae 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -4,6 +4,9 @@
 
 #### _Black_
 
+- `Black` now processes one-line docstrings by stripping leading and trailing spaces,
+  and adding a padding space when needed to break up """". (#1740)
+
 - `Black` now cleans up leading non-breaking spaces in comments (#2092)
 
 - `Black` now respects `--skip-string-normalization` when normalizing multiline
diff --git a/src/black/__init__.py b/src/black/__init__.py
index bb8f8c7422a..efa82f41160 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -2153,16 +2153,35 @@ def visit_STRING(self, leaf: Leaf) -> Iterator[Line]:
             # We're ignoring docstrings with backslash newline escapes because changing
             # indentation of those changes the AST representation of the code.
             prefix = get_string_prefix(leaf.value)
-            lead_len = len(prefix) + 3
-            tail_len = -3
-            indent = " " * 4 * self.current_line.depth
-            docstring = fix_docstring(leaf.value[lead_len:tail_len], indent)
+            docstring = leaf.value[len(prefix) :]  # Remove the prefix
+            quote_char = docstring[0]
+            # A natural way to remove the outer quotes is to do:
+            #   docstring = docstring.strip(quote_char)
+            # but that breaks on """""x""" (which is '""x').
+            # So we actually need to remove the first character and the next two
+            # characters but only if they are the same as the first.
+            quote_len = 1 if docstring[1] != quote_char else 3
+            docstring = docstring[quote_len:-quote_len]
+
+            if is_multiline_string(leaf):
+                indent = " " * 4 * self.current_line.depth
+                docstring = fix_docstring(docstring, indent)
+            else:
+                docstring = docstring.strip()
+
             if docstring:
-                if leaf.value[lead_len - 1] == docstring[0]:
+                # Add some padding if the docstring starts / ends with a quote mark.
+                if docstring[0] == quote_char:
                     docstring = " " + docstring
-                if leaf.value[tail_len + 1] == docstring[-1]:
+                if docstring[-1] == quote_char:
                     docstring = docstring + " "
-            leaf.value = leaf.value[0:lead_len] + docstring + leaf.value[tail_len:]
+            else:
+                # Add some padding if the docstring is empty.
+                docstring = " "
+
+            # We could enforce triple quotes at this point.
+            quote = quote_char * quote_len
+            leaf.value = prefix + quote + docstring + quote
 
         yield from self.visit_default(leaf)
 
@@ -6113,7 +6132,7 @@ def get_imports_from_children(children: List[LN]) -> Generator[str, None, None]:
 
 @lru_cache()
 def get_gitignore(root: Path) -> PathSpec:
-    """ Return a PathSpec matching gitignore content if present."""
+    """Return a PathSpec matching gitignore content if present."""
     gitignore = root / ".gitignore"
     lines: List[str] = []
     if gitignore.is_file():
@@ -6953,11 +6972,6 @@ def patched_main() -> None:
 
 
 def is_docstring(leaf: Leaf) -> bool:
-    if not is_multiline_string(leaf):
-        # For the purposes of docstring re-indentation, we don't need to do anything
-        # with single-line docstrings.
-        return False
-
     if prev_siblings_are(
         leaf.parent, [None, token.NEWLINE, token.INDENT, syms.simple_stmt]
     ):
diff --git a/src/black_primer/primer.json b/src/black_primer/primer.json
index 32df01571a7..3a1fae090a0 100644
--- a/src/black_primer/primer.json
+++ b/src/black_primer/primer.json
@@ -3,7 +3,7 @@
   "projects": {
     "aioexabgp": {
       "cli_arguments": [],
-      "expect_formatting_changes": false,
+      "expect_formatting_changes": true,
       "git_clone_url": "https://github.com/cooperlees/aioexabgp.git",
       "long_checkout": false,
       "py_versions": ["all"]
@@ -17,7 +17,7 @@
     },
     "bandersnatch": {
       "cli_arguments": [],
-      "expect_formatting_changes": false,
+      "expect_formatting_changes": true,
       "git_clone_url": "https://github.com/pypa/bandersnatch.git",
       "long_checkout": false,
       "py_versions": ["all"]
@@ -84,7 +84,7 @@
     },
     "ptr": {
       "cli_arguments": [],
-      "expect_formatting_changes": false,
+      "expect_formatting_changes": true,
       "git_clone_url": "https://github.com/facebookincubator/ptr.git",
       "long_checkout": false,
       "py_versions": ["all"]
@@ -98,14 +98,14 @@
     },
     "sqlalchemy": {
       "cli_arguments": [],
-      "expect_formatting_changes": false,
+      "expect_formatting_changes": true,
       "git_clone_url": "https://github.com/sqlalchemy/sqlalchemy.git",
       "long_checkout": false,
       "py_versions": ["all"]
     },
     "tox": {
       "cli_arguments": [],
-      "expect_formatting_changes": false,
+      "expect_formatting_changes": true,
       "git_clone_url": "https://github.com/tox-dev/tox.git",
       "long_checkout": false,
       "py_versions": ["all"]
diff --git a/tests/data/docstring.py b/tests/data/docstring.py
index 5c6985d0e08..74532b2b91d 100644
--- a/tests/data/docstring.py
+++ b/tests/data/docstring.py
@@ -102,6 +102,23 @@ def and_this():
   "hey yah"'''
 
 
+def empty():
+    '''
+    
+    
+    
+    
+    '''
+
+
+def oneline_empty():
+    '''      '''
+
+
+def single_quotes():
+    'testing'
+
+
 def believe_it_or_not_this_is_in_the_py_stdlib(): ''' 
 "hey yah"'''
 
@@ -110,6 +127,8 @@ def ignored_docstring():
     """a => \
 b"""  
 
+def single_line_docstring_with_whitespace():
+    """   This should be stripped """
 
 def docstring_with_inline_tabs_and_space_indentation():
     """hey
@@ -134,7 +153,6 @@ def docstring_with_inline_tabs_and_tab_indentation():
 	line ends with some tabs		
 	"""
 	pass
-        
 
 # output
 
@@ -241,6 +259,18 @@ def and_this():
     "hey yah"'''
 
 
+def empty():
+    """ """
+
+
+def oneline_empty():
+    """ """
+
+
+def single_quotes():
+    "testing"
+
+
 def believe_it_or_not_this_is_in_the_py_stdlib():
     '''
     "hey yah"'''
@@ -251,6 +281,10 @@ def ignored_docstring():
 b"""
 
 
+def single_line_docstring_with_whitespace():
+    """This should be stripped"""
+
+
 def docstring_with_inline_tabs_and_space_indentation():
     """hey
 
diff --git a/tox.ini b/tox.ini
index 9bb809abe41..71b02e920c7 100644
--- a/tox.ini
+++ b/tox.ini
@@ -23,4 +23,4 @@ commands =
     pip install -e .[d]
     coverage erase
     coverage run fuzz.py
-    coverage report
\ No newline at end of file
+    coverage report

From 5316bbff0e9db989db98b14761ce2c299a05895b Mon Sep 17 00:00:00 2001
From: CiderMan <github.hills@spamgourmet.com>
Date: Thu, 22 Apr 2021 16:40:51 +0100
Subject: [PATCH 0137/1034] Handle Docstrings as bytes + strip all whitespace
 (#2037)

(fixes #1844, fixes #1923, fixes #1851, fixes #2002, fixes #2103)
---
 CHANGES.md            |  3 +++
 src/black/__init__.py | 14 ++++++++++++--
 tests/test_black.py   | 20 ++++++++++++++++++++
 3 files changed, 35 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index f911fdf77ae..2999abfff4e 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -52,6 +52,9 @@
 
 - Exclude `venv` directory by default (#1683)
 
+- Fixed "Black produced code that is not equivalent to the source" when formatting
+  Python 2 docstrings (#2037)
+
 #### _Packaging_
 
 - Self-contained native _Black_ binaries are now provided for releases via GitHub
diff --git a/src/black/__init__.py b/src/black/__init__.py
index efa82f41160..5c9ab751650 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -6466,12 +6466,22 @@ def _stringify_ast(
             # Constant strings may be indented across newlines, if they are
             # docstrings; fold spaces after newlines when comparing. Similarly,
             # trailing and leading space may be removed.
+            # Note that when formatting Python 2 code, at least with Windows
+            # line-endings, docstrings can end up here as bytes instead of
+            # str so make sure that we handle both cases.
             if (
                 isinstance(node, ast.Constant)
                 and field == "value"
-                and isinstance(value, str)
+                and isinstance(value, (str, bytes))
             ):
-                normalized = re.sub(r" *\n[ \t]*", "\n", value).strip()
+                lineend = "\n" if isinstance(value, str) else b"\n"
+                # To normalize, we strip any leading and trailing space from
+                # each line...
+                stripped = [line.strip() for line in value.splitlines()]
+                normalized = lineend.join(stripped)  # type: ignore[attr-defined]
+                # ...and remove any blank lines at the beginning and end of
+                # the whole string
+                normalized = normalized.strip()
             else:
                 normalized = value
             yield f"{'  ' * (depth+2)}{normalized!r},  # {value.__class__.__name__}"
diff --git a/tests/test_black.py b/tests/test_black.py
index c603233efc4..201edfa2de5 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -1918,6 +1918,26 @@ def test_bpo_2142_workaround(self) -> None:
         actual = diff_header.sub(DETERMINISTIC_HEADER, actual)
         self.assertEqual(actual, expected)
 
+    def test_docstring_reformat_for_py27(self) -> None:
+        """
+        Check that stripping trailing whitespace from Python 2 docstrings
+        doesn't trigger a "not equivalent to source" error
+        """
+        source = (
+            b'def foo():\r\n    """Testing\r\n    Testing """\r\n    print "Foo"\r\n'
+        )
+        expected = 'def foo():\n    """Testing\n    Testing"""\n    print "Foo"\n'
+
+        result = CliRunner().invoke(
+            black.main,
+            ["-", "-q", "--target-version=py27"],
+            input=BytesIO(source),
+        )
+
+        self.assertEqual(result.exit_code, 0)
+        actual = result.output
+        self.assertFormatEqual(actual, expected)
+
 
 with open(black.__file__, "r", encoding="utf-8") as _bf:
     black_source_lines = _bf.readlines()

From 368f043f138112f63ff521c3481993c589eb7508 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Felix=20Hild=C3=A9n?= <felix.hilden@gmail.com>
Date: Thu, 22 Apr 2021 20:37:27 +0300
Subject: [PATCH 0138/1034] Document experimental string processing and
 docstring indentation (#2106)

---
 docs/the_black_code_style.md | 15 +++++++++++++++
 tests/data/docstring.py      |  8 ++++++++
 2 files changed, 23 insertions(+)

diff --git a/docs/the_black_code_style.md b/docs/the_black_code_style.md
index 1cc591b8031..67ccb8aab11 100644
--- a/docs/the_black_code_style.md
+++ b/docs/the_black_code_style.md
@@ -289,6 +289,21 @@ If you are adopting _Black_ in a large project with pre-existing string conventi
 you can pass `--skip-string-normalization` on the command line. This is meant as an
 adoption helper, avoid using this for new projects.
 
+As an experimental option, _Black_ splits long strings (using parentheses where
+appropriate) and merges short ones. When split, parts of f-strings that don't need
+formatting are converted to plain strings. User-made splits are respected when they do
+not exceed the line length limit. Line continuation backslashes are converted into
+parenthesized strings. Unnecessary parentheses are stripped. To enable experimental
+string processing, pass `--experimental-string-processing` on the command line. Because
+the functionality is experimental, feedback and issue reports are highly encouraged!
+
+_Black_ also processes docstrings. Firstly the indentation of docstrings is corrected
+for both quotations and the text within, although relative indentation in the text is
+preserved. Superfluous trailing whitespace on each line and unnecessary new lines at the
+end of the docstring are removed. All leading tabs are converted to spaces, but tabs
+inside text are preserved. Whitespace leading and trailing one-line docstrings is
+removed. The quotations of an empty docstring are separated with one space.
+
 ### Numeric literals
 
 _Black_ standardizes most numeric literals to use lowercase letters for the syntactic
diff --git a/tests/data/docstring.py b/tests/data/docstring.py
index 74532b2b91d..9e1c2441e0e 100644
--- a/tests/data/docstring.py
+++ b/tests/data/docstring.py
@@ -115,6 +115,10 @@ def oneline_empty():
     '''      '''
 
 
+def oneline_nothing():
+    """"""
+
+
 def single_quotes():
     'testing'
 
@@ -267,6 +271,10 @@ def oneline_empty():
     """ """
 
 
+def oneline_nothing():
+    """ """
+
+
 def single_quotes():
     "testing"
 

From 773e4a22d58be1f1aa82df7ad9a0f4c4e1328c10 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C5=81ukasz=20Langa?= <lukasz@langa.pl>
Date: Sun, 25 Apr 2021 19:04:15 +0200
Subject: [PATCH 0139/1034] Revert "Use lowercase hex numbers fixes #1692
 (#1775)"

This reverts commit 7d032fa848c8910007a0a41c1ba61d70d2846f48.
---
 .gitignore                                      |  3 +--
 src/black/__init__.py                           |  9 ++-------
 src/black_primer/primer.json                    | 10 +++++-----
 src/blib2to3/pytree.py                          |  2 +-
 tests/data/numeric_literals.py                  |  4 ++--
 tests/data/numeric_literals_py2.py              |  4 ++--
 tests/data/numeric_literals_skip_underscores.py |  6 +++---
 7 files changed, 16 insertions(+), 22 deletions(-)

diff --git a/.gitignore b/.gitignore
index 30225ec7764..3207e72ae28 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,4 +1,3 @@
-.venv
 .coverage
 _build
 .DS_Store
@@ -16,4 +15,4 @@ src/_black_version.py
 .dmypy.json
 *.swp
 .hypothesis/
-venv/
+venv/
\ No newline at end of file
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 5c9ab751650..0a893aa80fe 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -5351,15 +5351,10 @@ def normalize_numeric_literal(leaf: Leaf) -> None:
 
 def format_hex(text: str) -> str:
     """
-    Formats a hexadecimal string like "0x12b3"
-
-    Uses lowercase because of similarity between "B" and "8", which
-    can cause security issues.
-    see: https://github.com/psf/black/issues/1692
+    Formats a hexadecimal string like "0x12B3"
     """
-
     before, after = text[:2], text[2:]
-    return f"{before}{after.lower()}"
+    return f"{before}{after.upper()}"
 
 
 def format_scientific_notation(text: str) -> str:
diff --git a/src/black_primer/primer.json b/src/black_primer/primer.json
index 3a1fae090a0..7f7c3b0f37b 100644
--- a/src/black_primer/primer.json
+++ b/src/black_primer/primer.json
@@ -10,7 +10,7 @@
     },
     "attrs": {
       "cli_arguments": [],
-      "expect_formatting_changes": true,
+      "expect_formatting_changes": false,
       "git_clone_url": "https://github.com/python-attrs/attrs.git",
       "long_checkout": false,
       "py_versions": ["all"]
@@ -47,7 +47,7 @@
     },
     "hypothesis": {
       "cli_arguments": [],
-      "expect_formatting_changes": true,
+      "expect_formatting_changes": false,
       "git_clone_url": "https://github.com/HypothesisWorks/hypothesis.git",
       "long_checkout": false,
       "py_versions": ["all"]
@@ -63,7 +63,7 @@
     },
     "pillow": {
       "cli_arguments": [],
-      "expect_formatting_changes": true,
+      "expect_formatting_changes": false,
       "git_clone_url": "https://github.com/python-pillow/Pillow.git",
       "long_checkout": false,
       "py_versions": ["all"]
@@ -77,7 +77,7 @@
     },
     "pyramid": {
       "cli_arguments": [],
-      "expect_formatting_changes": true,
+      "expect_formatting_changes": false,
       "git_clone_url": "https://github.com/Pylons/pyramid.git",
       "long_checkout": false,
       "py_versions": ["all"]
@@ -112,7 +112,7 @@
     },
     "virtualenv": {
       "cli_arguments": [],
-      "expect_formatting_changes": true,
+      "expect_formatting_changes": false,
       "git_clone_url": "https://github.com/pypa/virtualenv.git",
       "long_checkout": false,
       "py_versions": ["all"]
diff --git a/src/blib2to3/pytree.py b/src/blib2to3/pytree.py
index 0c074f6a4ac..7843467e012 100644
--- a/src/blib2to3/pytree.py
+++ b/src/blib2to3/pytree.py
@@ -33,7 +33,7 @@
 import sys
 from io import StringIO
 
-HUGE: int = 0x7fffffff  # maximum repeat count, default max
+HUGE: int = 0x7FFFFFFF  # maximum repeat count, default max
 
 _type_reprs: Dict[int, Union[Text, int]] = {}
 
diff --git a/tests/data/numeric_literals.py b/tests/data/numeric_literals.py
index 06b7f7758ee..254da68d330 100644
--- a/tests/data/numeric_literals.py
+++ b/tests/data/numeric_literals.py
@@ -12,7 +12,7 @@
 x = 123456789E123456789
 x = 123456789J
 x = 123456789.123456789J
-x = 0Xb1aCc
+x = 0XB1ACC
 x = 0B1011
 x = 0O777
 x = 0.000000006
@@ -36,7 +36,7 @@
 x = 123456789e123456789
 x = 123456789j
 x = 123456789.123456789j
-x = 0xb1acc
+x = 0xB1ACC
 x = 0b1011
 x = 0o777
 x = 0.000000006
diff --git a/tests/data/numeric_literals_py2.py b/tests/data/numeric_literals_py2.py
index 8b2c7faa306..8f85c43f265 100644
--- a/tests/data/numeric_literals_py2.py
+++ b/tests/data/numeric_literals_py2.py
@@ -3,7 +3,7 @@
 x = 123456789L
 x = 123456789l
 x = 123456789
-x = 0xB1aCc
+x = 0xb1acc
 
 # output
 
@@ -13,4 +13,4 @@
 x = 123456789L
 x = 123456789L
 x = 123456789
-x = 0xb1acc
+x = 0xB1ACC
diff --git a/tests/data/numeric_literals_skip_underscores.py b/tests/data/numeric_literals_skip_underscores.py
index f83e23312f2..e345bb90276 100644
--- a/tests/data/numeric_literals_skip_underscores.py
+++ b/tests/data/numeric_literals_skip_underscores.py
@@ -3,7 +3,7 @@
 x = 123456789
 x = 1_2_3_4_5_6_7
 x = 1E+1
-x = 0xb1AcC
+x = 0xb1acc
 x = 0.00_00_006
 x = 12_34_567J
 x = .1_2
@@ -16,8 +16,8 @@
 x = 123456789
 x = 1_2_3_4_5_6_7
 x = 1e1
-x = 0xb1acc
+x = 0xB1ACC
 x = 0.00_00_006
 x = 12_34_567j
 x = 0.1_2
-x = 1_2.0
+x = 1_2.0
\ No newline at end of file

From ea9fefb359b86208ad20c944c3c420e6c3fb2c5e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C5=81ukasz=20Langa?= <lukasz@langa.pl>
Date: Sun, 25 Apr 2021 19:42:02 +0200
Subject: [PATCH 0140/1034] Re-add .venv to .gitignore

---
 .gitignore | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.gitignore b/.gitignore
index 3207e72ae28..f487d96cb3d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,4 @@
+.venv
 .coverage
 _build
 .DS_Store

From 5e09fa07f5db113c9b0858da15eff6bb31fe2417 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C5=81ukasz=20Langa?= <lukasz@langa.pl>
Date: Sun, 25 Apr 2021 19:44:06 +0200
Subject: [PATCH 0141/1034] Fix primer config

---
 src/black_primer/primer.json | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/src/black_primer/primer.json b/src/black_primer/primer.json
index 7f7c3b0f37b..1dd380b3cb4 100644
--- a/src/black_primer/primer.json
+++ b/src/black_primer/primer.json
@@ -10,7 +10,7 @@
     },
     "attrs": {
       "cli_arguments": [],
-      "expect_formatting_changes": false,
+      "expect_formatting_changes": true,
       "git_clone_url": "https://github.com/python-attrs/attrs.git",
       "long_checkout": false,
       "py_versions": ["all"]
@@ -63,7 +63,7 @@
     },
     "pillow": {
       "cli_arguments": [],
-      "expect_formatting_changes": false,
+      "expect_formatting_changes": true,
       "git_clone_url": "https://github.com/python-pillow/Pillow.git",
       "long_checkout": false,
       "py_versions": ["all"]
@@ -77,7 +77,7 @@
     },
     "pyramid": {
       "cli_arguments": [],
-      "expect_formatting_changes": false,
+      "expect_formatting_changes": true,
       "git_clone_url": "https://github.com/Pylons/pyramid.git",
       "long_checkout": false,
       "py_versions": ["all"]
@@ -91,7 +91,7 @@
     },
     "pytest": {
       "cli_arguments": [],
-      "expect_formatting_changes": true,
+      "expect_formatting_changes": false,
       "git_clone_url": "https://github.com/pytest-dev/pytest.git",
       "long_checkout": false,
       "py_versions": ["all"]
@@ -112,7 +112,7 @@
     },
     "virtualenv": {
       "cli_arguments": [],
-      "expect_formatting_changes": false,
+      "expect_formatting_changes": true,
       "git_clone_url": "https://github.com/pypa/virtualenv.git",
       "long_checkout": false,
       "py_versions": ["all"]

From 8672af35f052a636545e38110f0419ea92aeca0f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C5=81ukasz=20Langa?= <lukasz@langa.pl>
Date: Sun, 25 Apr 2021 20:15:54 +0200
Subject: [PATCH 0142/1034] Work around stability errors due to optional
 trailing commas (#2126)

Optional trailing commas put by Black become magic trailing commas on another
pass of the tool.  Since they are influencing formatting around optional
parentheses, on rare occasions the tool changes its mind in terms of putting
parentheses or not.

Ideally this would never be the case but sadly the decision to put optional
parentheses or not (which looks at pre-existing "magic" trailing commas) is
happening around the same time as the decision to put an optional trailing
comma.  Untangling the two proved to be impractically difficult.

This shameful workaround uses the fact that the formatting instability
introduced by magic trailing commas is deterministic: if the optional trailing
comma becoming a pre-existing "magic" trailing comma changes formatting, the
second pass becomes stable since there is no variable factor anymore on pass 3,
4, and so on.

For most files, this will introduce no performance penalty since `--safe` is
already re-formatting everything twice to ensure formatting stability.  We're
using this result and if all's good, the behavior is equivalent.  If there is
a difference, we treat the second result as the binding one, and check its
sanity again.
---
 CHANGES.md            |  4 ++++
 src/black/__init__.py | 24 +++++++++++++++++-------
 tests/test_black.py   | 18 ++++++++++++++++++
 3 files changed, 39 insertions(+), 7 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 2999abfff4e..0ca0b84f6d1 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -4,6 +4,10 @@
 
 #### _Black_
 
+- Fixed a rare but annoying formatting instability created by the combination of
+  optional trailing commas inserted by `Black` and optional parentheses looking at
+  pre-existing "magic" trailing commas (#2126)
+
 - `Black` now processes one-line docstrings by stripping leading and trailing spaces,
   and adding a padding space when needed to break up """". (#1740)
 
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 0a893aa80fe..08267d50f89 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -1016,7 +1016,17 @@ def format_file_contents(src_contents: str, *, fast: bool, mode: Mode) -> FileCo
 
     if not fast:
         assert_equivalent(src_contents, dst_contents)
-        assert_stable(src_contents, dst_contents, mode=mode)
+
+        # Forced second pass to work around optional trailing commas (becoming
+        # forced trailing commas on pass 2) interacting differently with optional
+        # parentheses.  Admittedly ugly.
+        dst_contents_pass2 = format_str(dst_contents, mode=mode)
+        if dst_contents != dst_contents_pass2:
+            dst_contents = dst_contents_pass2
+            assert_equivalent(src_contents, dst_contents, pass_num=2)
+            assert_stable(src_contents, dst_contents, mode=mode)
+        # Note: no need to explicitly call `assert_stable` if `dst_contents` was
+        # the same as `dst_contents_pass2`.
     return dst_contents
 
 
@@ -6484,7 +6494,7 @@ def _stringify_ast(
     yield f"{'  ' * depth})  # /{node.__class__.__name__}"
 
 
-def assert_equivalent(src: str, dst: str) -> None:
+def assert_equivalent(src: str, dst: str, *, pass_num: int = 1) -> None:
     """Raise AssertionError if `src` and `dst` aren't equivalent."""
     try:
         src_ast = parse_ast(src)
@@ -6499,9 +6509,9 @@ def assert_equivalent(src: str, dst: str) -> None:
     except Exception as exc:
         log = dump_to_file("".join(traceback.format_tb(exc.__traceback__)), dst)
         raise AssertionError(
-            f"INTERNAL ERROR: Black produced invalid code: {exc}. Please report a bug"
-            " on https://github.com/psf/black/issues.  This invalid output might be"
-            f" helpful: {log}"
+            f"INTERNAL ERROR: Black produced invalid code on pass {pass_num}: {exc}. "
+            "Please report a bug on https://github.com/psf/black/issues.  "
+            f"This invalid output might be helpful: {log}"
         ) from None
 
     src_ast_str = "\n".join(_stringify_ast(src_ast))
@@ -6510,8 +6520,8 @@ def assert_equivalent(src: str, dst: str) -> None:
         log = dump_to_file(diff(src_ast_str, dst_ast_str, "src", "dst"))
         raise AssertionError(
             "INTERNAL ERROR: Black produced code that is not equivalent to the"
-            " source.  Please report a bug on https://github.com/psf/black/issues. "
-            f" This diff might be helpful: {log}"
+            f" source on pass {pass_num}.  Please report a bug on "
+            f"https://github.com/psf/black/issues.  This diff might be helpful: {log}"
         ) from None
 
 
diff --git a/tests/test_black.py b/tests/test_black.py
index 201edfa2de5..8733b7a63ad 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -254,6 +254,24 @@ def test_trailing_comma_optional_parens_stability3(self) -> None:
         actual = fs(source)
         black.assert_stable(source, actual, DEFAULT_MODE)
 
+    @patch("black.dump_to_file", dump_to_stderr)
+    def test_trailing_comma_optional_parens_stability1_pass2(self) -> None:
+        source, _expected = read_data("trailing_comma_optional_parens1")
+        actual = fs(fs(source))  # this is what `format_file_contents` does with --safe
+        black.assert_stable(source, actual, DEFAULT_MODE)
+
+    @patch("black.dump_to_file", dump_to_stderr)
+    def test_trailing_comma_optional_parens_stability2_pass2(self) -> None:
+        source, _expected = read_data("trailing_comma_optional_parens2")
+        actual = fs(fs(source))  # this is what `format_file_contents` does with --safe
+        black.assert_stable(source, actual, DEFAULT_MODE)
+
+    @patch("black.dump_to_file", dump_to_stderr)
+    def test_trailing_comma_optional_parens_stability3_pass2(self) -> None:
+        source, _expected = read_data("trailing_comma_optional_parens3")
+        actual = fs(fs(source))  # this is what `format_file_contents` does with --safe
+        black.assert_stable(source, actual, DEFAULT_MODE)
+
     @patch("black.dump_to_file", dump_to_stderr)
     def test_pep_572(self) -> None:
         source, expected = read_data("pep_572")

From e5490e96232e301e9eed971984bb75f2f87475b0 Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Sun, 25 Apr 2021 11:27:35 -0700
Subject: [PATCH 0143/1034] Add Docker Github Action (#2086)

* Add Docker Github Action
- Build and upload arm64 + amd64 black images on push to master

This will need a `DOCKERHUB_USERNAME` and `DOCKERHUB_TOKEN` secrets set by someone with access.

* Change tag to push to pyfound/black repository. Thanks @ewdurbin
---
 .github/workflows/docker.yml | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)
 create mode 100644 .github/workflows/docker.yml

diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
new file mode 100644
index 00000000000..40b3d07736b
--- /dev/null
+++ b/.github/workflows/docker.yml
@@ -0,0 +1,33 @@
+name: docker
+
+on:
+  push:
+    branches:
+      - "master"
+
+jobs:
+  docker:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v1
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v1
+
+      - name: Login to DockerHub
+        uses: docker/login-action@v1
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Build and push
+        uses: docker/build-push-action@v2
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: pyfound/black:latest
+
+      - name: Image digest
+        run: echo ${{ steps.docker_build.outputs.digest }}

From eee949e286363384b25426b9ce461d31a5842ebf Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Sun, 25 Apr 2021 14:51:13 -0700
Subject: [PATCH 0144/1034] Docker CI: Add missed Checkout step (#2128)

- Reading my error others hit it by forgetting this Checkoutstep too so trying the fix
  - e.g. https://github.com/docker/build-push-action/issues/179
- Makes sense it's needed
---
 .github/workflows/docker.yml | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
index 40b3d07736b..09390130b3d 100644
--- a/.github/workflows/docker.yml
+++ b/.github/workflows/docker.yml
@@ -9,6 +9,9 @@ jobs:
   docker:
     runs-on: ubuntu-latest
     steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
       - name: Set up QEMU
         uses: docker/setup-qemu-action@v1
 

From de7187a823bd701ecb75c62bca0d7bd00076108a Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Sun, 25 Apr 2021 17:52:23 -0400
Subject: [PATCH 0145/1034] Issue 1629 has been closed, let's celebrate!
 (#2127)

---
 CHANGES.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index 0ca0b84f6d1..65d037394ad 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -6,7 +6,8 @@
 
 - Fixed a rare but annoying formatting instability created by the combination of
   optional trailing commas inserted by `Black` and optional parentheses looking at
-  pre-existing "magic" trailing commas (#2126)
+  pre-existing "magic" trailing commas. This fixes issue #1629 and all of its many many
+  duplicates. (#2126)
 
 - `Black` now processes one-line docstrings by stripping leading and trailing spaces,
   and adding a padding space when needed to break up """". (#1740)

From 67d5532c3392280de0ce717a1ab728eca2beb698 Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Sun, 25 Apr 2021 15:12:27 -0700
Subject: [PATCH 0146/1034] Update CHANGES.md for release (#2129)

---
 CHANGES.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index 65d037394ad..76653853d90 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,6 +1,6 @@
 ## Change Log
 
-### Unreleased
+### 21.4b0
 
 #### _Black_
 

From 65f0ea61599dc6d2be95ee961c42a55247130c49 Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Sun, 25 Apr 2021 20:48:04 -0700
Subject: [PATCH 0147/1034] Remove Lowercase Hex (PR #1692) from CHANGES.md
 (#2133)

- It was reverted to not cause so much diff churn on millions of lines of code
- Fix primer config for projects that should now pass
---
 CHANGES.md                   | 2 --
 src/black_primer/primer.json | 4 ++--
 2 files changed, 2 insertions(+), 4 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 76653853d90..e313a44474d 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -37,8 +37,6 @@
 - Added parsing support for unparenthesized tuples and yield expressions in annotated
   assignments (#1835)
 
-- use lowercase hex strings (#1692)
-
 - added `--extend-exclude` argument (PR #2005)
 
 - speed up caching by avoiding pathlib (#1950)
diff --git a/src/black_primer/primer.json b/src/black_primer/primer.json
index 1dd380b3cb4..7a6f5abf408 100644
--- a/src/black_primer/primer.json
+++ b/src/black_primer/primer.json
@@ -3,7 +3,7 @@
   "projects": {
     "aioexabgp": {
       "cli_arguments": [],
-      "expect_formatting_changes": true,
+      "expect_formatting_changes": false,
       "git_clone_url": "https://github.com/cooperlees/aioexabgp.git",
       "long_checkout": false,
       "py_versions": ["all"]
@@ -17,7 +17,7 @@
     },
     "bandersnatch": {
       "cli_arguments": [],
-      "expect_formatting_changes": true,
+      "expect_formatting_changes": false,
       "git_clone_url": "https://github.com/pypa/bandersnatch.git",
       "long_checkout": false,
       "py_versions": ["all"]

From 0a833b4b14953f98e81d632281a75318faa66170 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Sun, 25 Apr 2021 22:46:48 -0700
Subject: [PATCH 0148/1034] fix magic comma and experimental string cache flags
 (#2131)

* fix magic comma and experimental string cache flags

* more changelog

* Update CHANGES.md

Co-authored-by: Cooper Lees <me@cooperlees.com>

* fix tests

Co-authored-by: Cooper Lees <me@cooperlees.com>
---
 CHANGES.md            |  8 ++++++++
 src/black/__init__.py |  4 +++-
 tests/test_black.py   |  7 ++++---
 tests/test_format.py  | 37 ++++++++++++++++++++++---------------
 tests/util.py         |  2 +-
 5 files changed, 38 insertions(+), 20 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index e313a44474d..aa08396e491 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,5 +1,13 @@
 ## Change Log
 
+### Unreleased
+
+#### _Black_
+
+- Reflect the `--skip-magic-trailing-comma` and `--experimental-string-processing` flags
+  in the name of the cache file. Without this fix, changes in these flags would not take
+  effect if the cache had already been populated. (#2131)
+
 ### 21.4b0
 
 #### _Black_
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 08267d50f89..00d3729c835 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -273,9 +273,9 @@ class Mode:
     target_versions: Set[TargetVersion] = field(default_factory=set)
     line_length: int = DEFAULT_LINE_LENGTH
     string_normalization: bool = True
+    is_pyi: bool = False
     magic_trailing_comma: bool = True
     experimental_string_processing: bool = False
-    is_pyi: bool = False
 
     def get_cache_key(self) -> str:
         if self.target_versions:
@@ -290,6 +290,8 @@ def get_cache_key(self) -> str:
             str(self.line_length),
             str(int(self.string_normalization)),
             str(int(self.is_pyi)),
+            str(int(self.magic_trailing_comma)),
+            str(int(self.experimental_string_processing)),
         ]
         return ".".join(parts)
 
diff --git a/tests/test_black.py b/tests/test_black.py
index 8733b7a63ad..88ea31777fb 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -379,11 +379,12 @@ def test_detect_pos_only_arguments(self) -> None:
     @patch("black.dump_to_file", dump_to_stderr)
     def test_string_quotes(self) -> None:
         source, expected = read_data("string_quotes")
-        actual = fs(source)
+        mode = black.Mode(experimental_string_processing=True)
+        actual = fs(source, mode=mode)
         self.assertFormatEqual(expected, actual)
         black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-        mode = replace(DEFAULT_MODE, string_normalization=False)
+        black.assert_stable(source, actual, mode)
+        mode = replace(mode, string_normalization=False)
         not_normalized = fs(source, mode=mode)
         self.assertFormatEqual(source.replace("\\\n", ""), not_normalized)
         black.assert_equivalent(source, not_normalized)
diff --git a/tests/test_format.py b/tests/test_format.py
index eabec8c7219..e1335aedf43 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -16,7 +16,6 @@
 SIMPLE_CASES = [
     "beginning_backslash",
     "bracketmatch",
-    "cantfit",
     "class_blank_parentheses",
     "class_methods_new_line",
     "collections",
@@ -26,7 +25,6 @@
     "comments4",
     "comments5",
     "comments6",
-    "comments7",
     "comments_non_breaking_space",
     "comment_after_escaped_newline",
     "composition",
@@ -48,11 +46,7 @@
     "function2",
     "function_trailing_comma",
     "import_spacing",
-    "long_strings",
-    "long_strings__edge_case",
-    "long_strings__regression",
     "numeric_literals_py2",
-    "percent_precedence",
     "python2",
     "python2_unicode_literals",
     "remove_parens",
@@ -62,6 +56,15 @@
     "tupleassign",
 ]
 
+EXPERIMENTAL_STRING_PROCESSING_CASES = [
+    "cantfit",
+    "comments7",
+    "long_strings",
+    "long_strings__edge_case",
+    "long_strings__regression",
+    "percent_precedence",
+]
+
 
 SOURCES = [
     "tests/test_black.py",
@@ -86,19 +89,23 @@ class TestSimpleFormat(BlackBaseTestCase):
     @parameterized.expand(SIMPLE_CASES)
     @patch("black.dump_to_file", dump_to_stderr)
     def test_simple_format(self, filename: str) -> None:
-        source, expected = read_data(filename)
-        actual = fs(source)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
+        self.check_file(filename, DEFAULT_MODE)
+
+    @parameterized.expand(EXPERIMENTAL_STRING_PROCESSING_CASES)
+    @patch("black.dump_to_file", dump_to_stderr)
+    def test_experimental_format(self, filename: str) -> None:
+        self.check_file(filename, black.Mode(experimental_string_processing=True))
 
     @parameterized.expand(SOURCES)
     @patch("black.dump_to_file", dump_to_stderr)
     def test_source_is_formatted(self, filename: str) -> None:
         path = THIS_DIR.parent / filename
-        source, expected = read_data(str(path), data=False)
-        actual = fs(source, mode=DEFAULT_MODE)
+        self.check_file(str(path), DEFAULT_MODE, data=False)
+        self.assertFalse(ff(path))
+
+    def check_file(self, filename: str, mode: black.Mode, *, data: bool = True) -> None:
+        source, expected = read_data(filename, data=data)
+        actual = fs(source, mode=mode)
         self.assertFormatEqual(expected, actual)
         black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-        self.assertFalse(ff(path))
+        black.assert_stable(source, actual, mode)
diff --git a/tests/util.py b/tests/util.py
index da65ed0cc93..ad9866975ac 100644
--- a/tests/util.py
+++ b/tests/util.py
@@ -12,7 +12,7 @@
 DETERMINISTIC_HEADER = "[Deterministic header]"
 
 
-DEFAULT_MODE = black.FileMode(experimental_string_processing=True)
+DEFAULT_MODE = black.Mode()
 ff = partial(black.format_file_in_place, mode=DEFAULT_MODE, fast=True)
 fs = partial(black.format_str, mode=DEFAULT_MODE)
 

From db30456916ca733d011a2774e66beb3dd7064e14 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Mon, 26 Apr 2021 11:28:42 -0400
Subject: [PATCH 0149/1034] Don't strip parens in assert / return with assign
 expr (#2143)

Black would previously strip the parenthesis away from statements like this these ones:

    assert (spam := 12 + 1)
    return (cheese := 1 - 12)

Which happens to be invalid code. Now before making the parenthesis invisible, Black
checks if the assignment expression's parent is an assert stamtment, aborting if True.

Raise, yield, and await are already handled fine.

I added a bunch of test cases from the PEP defining asssignment expressions (PEP 572).
---
 CHANGES.md                          |  3 ++
 src/black/__init__.py               |  7 +++-
 tests/data/pep_572_remove_parens.py | 52 +++++++++++++++++++++++++++++
 3 files changed, 61 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index aa08396e491..9fe6b7e3fa4 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -8,6 +8,9 @@
   in the name of the cache file. Without this fix, changes in these flags would not take
   effect if the cache had already been populated. (#2131)
 
+- Don't remove necessary parentheses from assignment expression containing assert /
+  return statements. (#2143)
+
 ### 21.4b0
 
 #### _Black_
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 00d3729c835..99afc7d3c50 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -5613,7 +5613,12 @@ def maybe_make_parens_invisible_in_atom(node: LN, parent: LN) -> bool:
         return False
 
     if is_walrus_assignment(node):
-        if parent.type in [syms.annassign, syms.expr_stmt]:
+        if parent.type in [
+            syms.annassign,
+            syms.expr_stmt,
+            syms.assert_stmt,
+            syms.return_stmt,
+        ]:
             return False
 
     first = node.children[0]
diff --git a/tests/data/pep_572_remove_parens.py b/tests/data/pep_572_remove_parens.py
index 04cc75bc36c..9a804859a09 100644
--- a/tests/data/pep_572_remove_parens.py
+++ b/tests/data/pep_572_remove_parens.py
@@ -17,6 +17,32 @@
 
 a, b = (test := (1, 2))
 
+# see also https://github.com/psf/black/issues/2139
+assert (foo := 42 - 12)
+
+foo(x=(y := f(x)))
+
+
+def foo(answer=(p := 42)):
+    ...
+
+
+def foo2(answer: (p := 42) = 5):
+    ...
+
+
+lambda: (x := 1)
+
+# we don't touch expressions in f-strings but if we do one day, don't break 'em
+f'{(x:=10)}'
+
+
+def a():
+    return (x := 3)
+    await (b := 1)
+    yield (a := 2)
+    raise (c := 3)
+
 # output
 if foo := 0:
     pass
@@ -36,3 +62,29 @@
 test: int = (test2 := 2)
 
 a, b = (test := (1, 2))
+
+# see also https://github.com/psf/black/issues/2139
+assert (foo := 42 - 12)
+
+foo(x=(y := f(x)))
+
+
+def foo(answer=(p := 42)):
+    ...
+
+
+def foo2(answer: (p := 42) = 5):
+    ...
+
+
+lambda: (x := 1)
+
+# we don't touch expressions in f-strings but if we do one day, don't break 'em
+f"{(x:=10)}"
+
+
+def a():
+    return (x := 3)
+    await (b := 1)
+    yield (a := 2)
+    raise (c := 3)

From 97c24664c5bc251f7b67756b8b184962ca44b6d9 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Mon, 26 Apr 2021 13:26:03 -0400
Subject: [PATCH 0150/1034] Symlink docs/change_log.md to CHANGES.md, don't
 copy (#2146)

Super duper janky stopgap fix until I get my documentation reorganization
work done and merged
---
 docs/change_log.md | 537 +--------------------------------------------
 docs/conf.py       |   2 +-
 2 files changed, 2 insertions(+), 537 deletions(-)
 mode change 100644 => 120000 docs/change_log.md

diff --git a/docs/change_log.md b/docs/change_log.md
deleted file mode 100644
index 01c27553fca..00000000000
--- a/docs/change_log.md
+++ /dev/null
@@ -1,536 +0,0 @@
-[//]: # "NOTE: THIS FILE WAS AUTOGENERATED FROM CHANGES.md"
-
-## Change Log
-
-### Unreleased
-
-#### _Black_
-
-- `Black` now respects `--skip-string-normalization` when normalizing multiline
-  docstring quotes (#1637)
-
-- `Black` no longer removes all empty lines between non-function code and decorators
-  when formatting typing stubs. Now `Black` enforces a single empty line. (#1646)
-
-- `Black` no longer adds an incorrect space after a parenthesized assignment expression
-  in if/while statements (#1655)
-
-- fixed a crash when PWD=/ on POSIX (#1631)
-
-- fixed "I/O operation on closed file" when using --diff (#1664)
-
-- Prevent coloured diff output being interleaved with multiple files (#1673)
-
-- Added support for PEP 614 relaxed decorator syntax on python 3.9 (#1711)
-
-- Added parsing support for unparenthesized tuples and yield expressions in annotated
-  assignments (#1835)
-
-- use lowercase hex strings (#1692)
-
-- added `--extend-exclude` argument (#1571)
-
-#### _Packaging_
-
-- Self-contained native _Black_ binaries are now provided for releases via GitHub
-  Releases (#1743)
-
-### 20.8b1
-
-#### _Packaging_
-
-- explicitly depend on Click 7.1.2 or newer as `Black` no longer works with versions
-  older than 7.0
-
-### 20.8b0
-
-#### _Black_
-
-- re-implemented support for explicit trailing commas: now it works consistently within
-  any bracket pair, including nested structures (#1288 and duplicates)
-
-- `Black` now reindents docstrings when reindenting code around it (#1053)
-
-- `Black` now shows colored diffs (#1266)
-
-- `Black` is now packaged using 'py3' tagged wheels (#1388)
-
-- `Black` now supports Python 3.8 code, e.g. star expressions in return statements
-  (#1121)
-
-- `Black` no longer normalizes capital R-string prefixes as those have a
-  community-accepted meaning (#1244)
-
-- `Black` now uses exit code 2 when specified configuration file doesn't exit (#1361)
-
-- `Black` now works on AWS Lambda (#1141)
-
-- added `--force-exclude` argument (#1032)
-
-- removed deprecated `--py36` option (#1236)
-
-- fixed `--diff` output when EOF is encountered (#526)
-
-- fixed `# fmt: off` handling around decorators (#560)
-
-- fixed unstable formatting with some `# type: ignore` comments (#1113)
-
-- fixed invalid removal on organizing brackets followed by indexing (#1575)
-
-- introduced `black-primer`, a CI tool that allows us to run regression tests against
-  existing open source users of Black (#1402)
-
-- introduced property-based fuzzing to our test suite based on Hypothesis and
-  Hypothersmith (#1566)
-
-- implemented experimental and disabled by default long string rewrapping (#1132),
-  hidden under a `--experimental-string-processing` flag while it's being worked on;
-  this is an undocumented and unsupported feature, you lose Internet points for
-  depending on it (#1609)
-
-#### Vim plugin
-
-- prefer virtualenv packages over global packages (#1383)
-
-### 19.10b0
-
-- added support for PEP 572 assignment expressions (#711)
-
-- added support for PEP 570 positional-only arguments (#943)
-
-- added support for async generators (#593)
-
-- added support for pre-splitting collections by putting an explicit trailing comma
-  inside (#826)
-
-- added `black -c` as a way to format code passed from the command line (#761)
-
-- --safe now works with Python 2 code (#840)
-
-- fixed grammar selection for Python 2-specific code (#765)
-
-- fixed feature detection for trailing commas in function definitions and call sites
-  (#763)
-
-- `# fmt: off`/`# fmt: on` comment pairs placed multiple times within the same block of
-  code now behave correctly (#1005)
-
-- _Black_ no longer crashes on Windows machines with more than 61 cores (#838)
-
-- _Black_ no longer crashes on standalone comments prepended with a backslash (#767)
-
-- _Black_ no longer crashes on `from` ... `import` blocks with comments (#829)
-
-- _Black_ no longer crashes on Python 3.7 on some platform configurations (#494)
-
-- _Black_ no longer fails on comments in from-imports (#671)
-
-- _Black_ no longer fails when the file starts with a backslash (#922)
-
-- _Black_ no longer merges regular comments with type comments (#1027)
-
-- _Black_ no longer splits long lines that contain type comments (#997)
-
-- removed unnecessary parentheses around `yield` expressions (#834)
-
-- added parentheses around long tuples in unpacking assignments (#832)
-
-- added parentheses around complex powers when they are prefixed by a unary operator
-  (#646)
-
-- fixed bug that led _Black_ format some code with a line length target of 1 (#762)
-
-- _Black_ no longer introduces quotes in f-string subexpressions on string boundaries
-  (#863)
-
-- if _Black_ puts parenthesis around a single expression, it moves comments to the
-  wrapped expression instead of after the brackets (#872)
-
-- `blackd` now returns the version of _Black_ in the response headers (#1013)
-
-- `blackd` can now output the diff of formats on source code when the `X-Diff` header is
-  provided (#969)
-
-### 19.3b0
-
-- new option `--target-version` to control which Python versions _Black_-formatted code
-  should target (#618)
-
-- deprecated `--py36` (use `--target-version=py36` instead) (#724)
-
-- _Black_ no longer normalizes numeric literals to include `_` separators (#696)
-
-- long `del` statements are now split into multiple lines (#698)
-
-- type comments are no longer mangled in function signatures
-
-- improved performance of formatting deeply nested data structures (#509)
-
-- _Black_ now properly formats multiple files in parallel on Windows (#632)
-
-- _Black_ now creates cache files atomically which allows it to be used in parallel
-  pipelines (like `xargs -P8`) (#673)
-
-- _Black_ now correctly indents comments in files that were previously formatted with
-  tabs (#262)
-
-- `blackd` now supports CORS (#622)
-
-### 18.9b0
-
-- numeric literals are now formatted by _Black_ (#452, #461, #464, #469):
-
-  - numeric literals are normalized to include `_` separators on Python 3.6+ code
-
-  - added `--skip-numeric-underscore-normalization` to disable the above behavior and
-    leave numeric underscores as they were in the input
-
-  - code with `_` in numeric literals is recognized as Python 3.6+
-
-  - most letters in numeric literals are lowercased (e.g., in `1e10`, `0x01`)
-
-  - hexadecimal digits are always uppercased (e.g. `0xBADC0DE`)
-
-- added `blackd`, see [its documentation](#blackd) for more info (#349)
-
-- adjacent string literals are now correctly split into multiple lines (#463)
-
-- trailing comma is now added to single imports that don't fit on a line (#250)
-
-- cache is now populated when `--check` is successful for a file which speeds up
-  consecutive checks of properly formatted unmodified files (#448)
-
-- whitespace at the beginning of the file is now removed (#399)
-
-- fixed mangling [pweave](http://mpastell.com/pweave/) and
-  [Spyder IDE](https://www.spyder-ide.org/) special comments (#532)
-
-- fixed unstable formatting when unpacking big tuples (#267)
-
-- fixed parsing of `__future__` imports with renames (#389)
-
-- fixed scope of `# fmt: off` when directly preceding `yield` and other nodes (#385)
-
-- fixed formatting of lambda expressions with default arguments (#468)
-
-- fixed `async for` statements: _Black_ no longer breaks them into separate lines (#372)
-
-- note: the Vim plugin stopped registering `,=` as a default chord as it turned out to
-  be a bad idea (#415)
-
-### 18.6b4
-
-- hotfix: don't freeze when multiple comments directly precede `# fmt: off` (#371)
-
-### 18.6b3
-
-- typing stub files (`.pyi`) now have blank lines added after constants (#340)
-
-- `# fmt: off` and `# fmt: on` are now much more dependable:
-
-  - they now work also within bracket pairs (#329)
-
-  - they now correctly work across function/class boundaries (#335)
-
-  - they now work when an indentation block starts with empty lines or misaligned
-    comments (#334)
-
-- made Click not fail on invalid environments; note that Click is right but the
-  likelihood we'll need to access non-ASCII file paths when dealing with Python source
-  code is low (#277)
-
-- fixed improper formatting of f-strings with quotes inside interpolated expressions
-  (#322)
-
-- fixed unnecessary slowdown when long list literals where found in a file
-
-- fixed unnecessary slowdown on AST nodes with very many siblings
-
-- fixed cannibalizing backslashes during string normalization
-
-- fixed a crash due to symbolic links pointing outside of the project directory (#338)
-
-### 18.6b2
-
-- added `--config` (#65)
-
-- added `-h` equivalent to `--help` (#316)
-
-- fixed improper unmodified file caching when `-S` was used
-
-- fixed extra space in string unpacking (#305)
-
-- fixed formatting of empty triple quoted strings (#313)
-
-- fixed unnecessary slowdown in comment placement calculation on lines without comments
-
-### 18.6b1
-
-- hotfix: don't output human-facing information on stdout (#299)
-
-- hotfix: don't output cake emoji on non-zero return code (#300)
-
-### 18.6b0
-
-- added `--include` and `--exclude` (#270)
-
-- added `--skip-string-normalization` (#118)
-
-- added `--verbose` (#283)
-
-- the header output in `--diff` now actually conforms to the unified diff spec
-
-- fixed long trivial assignments being wrapped in unnecessary parentheses (#273)
-
-- fixed unnecessary parentheses when a line contained multiline strings (#232)
-
-- fixed stdin handling not working correctly if an old version of Click was used (#276)
-
-- _Black_ now preserves line endings when formatting a file in place (#258)
-
-### 18.5b1
-
-- added `--pyi` (#249)
-
-- added `--py36` (#249)
-
-- Python grammar pickle caches are stored with the formatting caches, making _Black_
-  work in environments where site-packages is not user-writable (#192)
-
-- _Black_ now enforces a PEP 257 empty line after a class-level docstring (and/or
-  fields) and the first method
-
-- fixed invalid code produced when standalone comments were present in a trailer that
-  was omitted from line splitting on a large expression (#237)
-
-- fixed optional parentheses being removed within `# fmt: off` sections (#224)
-
-- fixed invalid code produced when stars in very long imports were incorrectly wrapped
-  in optional parentheses (#234)
-
-- fixed unstable formatting when inline comments were moved around in a trailer that was
-  omitted from line splitting on a large expression (#238)
-
-- fixed extra empty line between a class declaration and the first method if no class
-  docstring or fields are present (#219)
-
-- fixed extra empty line between a function signature and an inner function or inner
-  class (#196)
-
-### 18.5b0
-
-- call chains are now formatted according to the
-  [fluent interfaces](https://en.wikipedia.org/wiki/Fluent_interface) style (#67)
-
-- data structure literals (tuples, lists, dictionaries, and sets) are now also always
-  exploded like imports when they don't fit in a single line (#152)
-
-- slices are now formatted according to PEP 8 (#178)
-
-- parentheses are now also managed automatically on the right-hand side of assignments
-  and return statements (#140)
-
-- math operators now use their respective priorities for delimiting multiline
-  expressions (#148)
-
-- optional parentheses are now omitted on expressions that start or end with a bracket
-  and only contain a single operator (#177)
-
-- empty parentheses in a class definition are now removed (#145, #180)
-
-- string prefixes are now standardized to lowercase and `u` is removed on Python 3.6+
-  only code and Python 2.7+ code with the `unicode_literals` future import (#188, #198,
-  #199)
-
-- typing stub files (`.pyi`) are now formatted in a style that is consistent with PEP
-  484 (#207, #210)
-
-- progress when reformatting many files is now reported incrementally
-
-- fixed trailers (content with brackets) being unnecessarily exploded into their own
-  lines after a dedented closing bracket (#119)
-
-- fixed an invalid trailing comma sometimes left in imports (#185)
-
-- fixed non-deterministic formatting when multiple pairs of removable parentheses were
-  used (#183)
-
-- fixed multiline strings being unnecessarily wrapped in optional parentheses in long
-  assignments (#215)
-
-- fixed not splitting long from-imports with only a single name
-
-- fixed Python 3.6+ file discovery by also looking at function calls with unpacking.
-  This fixed non-deterministic formatting if trailing commas where used both in function
-  signatures with stars and function calls with stars but the former would be
-  reformatted to a single line.
-
-- fixed crash on dealing with optional parentheses (#193)
-
-- fixed "is", "is not", "in", and "not in" not considered operators for splitting
-  purposes
-
-- fixed crash when dead symlinks where encountered
-
-### 18.4a4
-
-- don't populate the cache on `--check` (#175)
-
-### 18.4a3
-
-- added a "cache"; files already reformatted that haven't changed on disk won't be
-  reformatted again (#109)
-
-- `--check` and `--diff` are no longer mutually exclusive (#149)
-
-- generalized star expression handling, including double stars; this fixes
-  multiplication making expressions "unsafe" for trailing commas (#132)
-
-- _Black_ no longer enforces putting empty lines behind control flow statements (#90)
-
-- _Black_ now splits imports like "Mode 3 + trailing comma" of isort (#127)
-
-- fixed comment indentation when a standalone comment closes a block (#16, #32)
-
-- fixed standalone comments receiving extra empty lines if immediately preceding a
-  class, def, or decorator (#56, #154)
-
-- fixed `--diff` not showing entire path (#130)
-
-- fixed parsing of complex expressions after star and double stars in function calls
-  (#2)
-
-- fixed invalid splitting on comma in lambda arguments (#133)
-
-- fixed missing splits of ternary expressions (#141)
-
-### 18.4a2
-
-- fixed parsing of unaligned standalone comments (#99, #112)
-
-- fixed placement of dictionary unpacking inside dictionary literals (#111)
-
-- Vim plugin now works on Windows, too
-
-- fixed unstable formatting when encountering unnecessarily escaped quotes in a string
-  (#120)
-
-### 18.4a1
-
-- added `--quiet` (#78)
-
-- added automatic parentheses management (#4)
-
-- added [pre-commit](https://pre-commit.com) integration (#103, #104)
-
-- fixed reporting on `--check` with multiple files (#101, #102)
-
-- fixed removing backslash escapes from raw strings (#100, #105)
-
-### 18.4a0
-
-- added `--diff` (#87)
-
-- add line breaks before all delimiters, except in cases like commas, to better comply
-  with PEP 8 (#73)
-
-- standardize string literals to use double quotes (almost) everywhere (#75)
-
-- fixed handling of standalone comments within nested bracketed expressions; _Black_
-  will no longer produce super long lines or put all standalone comments at the end of
-  the expression (#22)
-
-- fixed 18.3a4 regression: don't crash and burn on empty lines with trailing whitespace
-  (#80)
-
-- fixed 18.3a4 regression: `# yapf: disable` usage as trailing comment would cause
-  _Black_ to not emit the rest of the file (#95)
-
-- when CTRL+C is pressed while formatting many files, _Black_ no longer freaks out with
-  a flurry of asyncio-related exceptions
-
-- only allow up to two empty lines on module level and only single empty lines within
-  functions (#74)
-
-### 18.3a4
-
-- `# fmt: off` and `# fmt: on` are implemented (#5)
-
-- automatic detection of deprecated Python 2 forms of print statements and exec
-  statements in the formatted file (#49)
-
-- use proper spaces for complex expressions in default values of typed function
-  arguments (#60)
-
-- only return exit code 1 when --check is used (#50)
-
-- don't remove single trailing commas from square bracket indexing (#59)
-
-- don't omit whitespace if the previous factor leaf wasn't a math operator (#55)
-
-- omit extra space in kwarg unpacking if it's the first argument (#46)
-
-- omit extra space in
-  [Sphinx auto-attribute comments](http://www.sphinx-doc.org/en/stable/ext/autodoc.html#directive-autoattribute)
-  (#68)
-
-### 18.3a3
-
-- don't remove single empty lines outside of bracketed expressions (#19)
-
-- added ability to pipe formatting from stdin to stdin (#25)
-
-- restored ability to format code with legacy usage of `async` as a name (#20, #42)
-
-- even better handling of numpy-style array indexing (#33, again)
-
-### 18.3a2
-
-- changed positioning of binary operators to occur at beginning of lines instead of at
-  the end, following
-  [a recent change to PEP 8](https://github.com/python/peps/commit/c59c4376ad233a62ca4b3a6060c81368bd21e85b)
-  (#21)
-
-- ignore empty bracket pairs while splitting. This avoids very weirdly looking
-  formattings (#34, #35)
-
-- remove a trailing comma if there is a single argument to a call
-
-- if top level functions were separated by a comment, don't put four empty lines after
-  the upper function
-
-- fixed unstable formatting of newlines with imports
-
-- fixed unintentional folding of post scriptum standalone comments into last statement
-  if it was a simple statement (#18, #28)
-
-- fixed missing space in numpy-style array indexing (#33)
-
-- fixed spurious space after star-based unary expressions (#31)
-
-### 18.3a1
-
-- added `--check`
-
-- only put trailing commas in function signatures and calls if it's safe to do so. If
-  the file is Python 3.6+ it's always safe, otherwise only safe if there are no `*args`
-  or `**kwargs` used in the signature or call. (#8)
-
-- fixed invalid spacing of dots in relative imports (#6, #13)
-
-- fixed invalid splitting after comma on unpacked variables in for-loops (#23)
-
-- fixed spurious space in parenthesized set expressions (#7)
-
-- fixed spurious space after opening parentheses and in default arguments (#14, #17)
-
-- fixed spurious space after unary operators when the operand was a complex expression
-  (#15)
-
-### 18.3a0
-
-- first published version, Happy 🍰 Day 2018!
-
-- alpha quality
-
-- date-versioned (see: https://calver.org/)
diff --git a/docs/change_log.md b/docs/change_log.md
new file mode 120000
index 00000000000..cf547089dc1
--- /dev/null
+++ b/docs/change_log.md
@@ -0,0 +1 @@
+../CHANGES.md
\ No newline at end of file
diff --git a/docs/conf.py b/docs/conf.py
index 7381c9d6423..ec6aad9a27b 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -219,7 +219,6 @@ def process_sections(
     DocSection("blackd", CURRENT_DIR / "blackd.md"),
     DocSection("black_primer", CURRENT_DIR / "black_primer.md"),
     DocSection("contributing_to_black", CURRENT_DIR / ".." / "CONTRIBUTING.md"),
-    DocSection("change_log", CURRENT_DIR / ".." / "CHANGES.md"),
 ]
 
 # Sphinx complains when there is a source file that isn't referenced in any of the docs.
@@ -231,6 +230,7 @@ def process_sections(
     "pragmatism",
     "testimonials",
     "used_by",
+    "change_log",
 }
 
 make_pypi_svg(release)

From 557b54aa60e9abbb93e5737512d9963e640f2d1f Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Mon, 26 Apr 2021 10:42:16 -0700
Subject: [PATCH 0151/1034] Fix crash on docstrings ending with "\ " (#2142)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Łukasz Langa <lukasz@langa.pl>
---
 CHANGES.md              |  2 ++
 src/black/__init__.py   |  8 +++++++-
 tests/data/docstring.py | 31 +++++++++++++++++++++++++++++++
 3 files changed, 40 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index 9fe6b7e3fa4..814956c80ba 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -4,6 +4,8 @@
 
 #### _Black_
 
+- Fix crash on docstrings ending with "\ ". (#2142)
+
 - Reflect the `--skip-magic-trailing-comma` and `--experimental-string-processing` flags
   in the name of the cache file. Without this fix, changes in these flags would not take
   effect if the cache had already been populated. (#2131)
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 99afc7d3c50..051de5d13df 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -2186,7 +2186,13 @@ def visit_STRING(self, leaf: Leaf) -> Iterator[Line]:
                 if docstring[0] == quote_char:
                     docstring = " " + docstring
                 if docstring[-1] == quote_char:
-                    docstring = docstring + " "
+                    docstring += " "
+                if docstring[-1] == "\\":
+                    backslash_count = len(docstring) - len(docstring.rstrip("\\"))
+                    if backslash_count % 2:
+                        # Odd number of tailing backslashes, add some padding to
+                        # avoid escaping the closing string quote.
+                        docstring += " "
             else:
                 # Add some padding if the docstring is empty.
                 docstring = " "
diff --git a/tests/data/docstring.py b/tests/data/docstring.py
index 9e1c2441e0e..ee6d0c051d7 100644
--- a/tests/data/docstring.py
+++ b/tests/data/docstring.py
@@ -158,6 +158,22 @@ def docstring_with_inline_tabs_and_tab_indentation():
 	"""
 	pass
 
+
+def backslash_space():
+    """\ """
+
+
+def multiline_backslash_1():
+  '''
+  hey\there\
+  \ '''
+
+
+def multiline_backslash_2():
+  '''
+  hey there \ '''
+
+
 # output
 
 class MyClass:
@@ -316,3 +332,18 @@ def docstring_with_inline_tabs_and_tab_indentation():
     line ends with some tabs
     """
     pass
+
+
+def backslash_space():
+    """\ """
+
+
+def multiline_backslash_1():
+    """
+  hey\there\
+  \ """
+
+
+def multiline_backslash_2():
+    """
+    hey there \ """

From eaa337f176b086a9ebd91884c0b9d9a96772aeb3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C5=81ukasz=20Langa?= <lukasz@langa.pl>
Date: Mon, 26 Apr 2021 20:24:06 +0200
Subject: [PATCH 0152/1034] Add more tests for fancy whitespace (#2147)

---
 CHANGES.md                                    |  2 +
 tests/data/docstring.py                       | 28 +++++++++++++
 .../data/docstring_no_string_normalization.py | 40 +++++++++++++++++++
 3 files changed, 70 insertions(+)

diff --git a/CHANGES.md b/CHANGES.md
index 814956c80ba..a3bf5565967 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -6,6 +6,8 @@
 
 - Fix crash on docstrings ending with "\ ". (#2142)
 
+- Fix crash when atypical whitespace is cleaned out of dostrings (#2120)
+
 - Reflect the `--skip-magic-trailing-comma` and `--experimental-string-processing` flags
   in the name of the cache file. Without this fix, changes in these flags would not take
   effect if the cache had already been populated. (#2131)
diff --git a/tests/data/docstring.py b/tests/data/docstring.py
index ee6d0c051d7..e977619e482 100644
--- a/tests/data/docstring.py
+++ b/tests/data/docstring.py
@@ -174,6 +174,20 @@ def multiline_backslash_2():
   hey there \ '''
 
 
+def multiline_backslash_3():
+  '''
+  already escaped \\ '''
+
+
+def my_god_its_full_of_stars_1():
+    "I'm sorry Dave\u2001"
+
+
+# the space below is actually a \u2001, removed in output
+def my_god_its_full_of_stars_2():
+    "I'm sorry Dave "
+
+
 # output
 
 class MyClass:
@@ -347,3 +361,17 @@ def multiline_backslash_1():
 def multiline_backslash_2():
     """
     hey there \ """
+
+
+def multiline_backslash_3():
+    """
+    already escaped \\"""
+
+
+def my_god_its_full_of_stars_1():
+    "I'm sorry Dave\u2001"
+
+
+# the space below is actually a \u2001, removed in output
+def my_god_its_full_of_stars_2():
+    "I'm sorry Dave"
\ No newline at end of file
diff --git a/tests/data/docstring_no_string_normalization.py b/tests/data/docstring_no_string_normalization.py
index 0457fcf114f..a90b578f09a 100644
--- a/tests/data/docstring_no_string_normalization.py
+++ b/tests/data/docstring_no_string_normalization.py
@@ -102,6 +102,26 @@ def shockingly_the_quotes_are_normalized_v2():
     '''
     pass
 
+
+def backslash_space():
+    '\ '
+
+
+def multiline_backslash_1():
+  '''
+  hey\there\
+  \ '''
+
+
+def multiline_backslash_2():
+  '''
+  hey there \ '''
+
+
+def multiline_backslash_3():
+  '''
+  already escaped \\ '''
+
 # output
 
 class ALonelyClass:
@@ -207,3 +227,23 @@ def shockingly_the_quotes_are_normalized_v2():
     Docstring Docstring Docstring
     '''
     pass
+
+
+def backslash_space():
+    '\ '
+
+
+def multiline_backslash_1():
+    '''
+  hey\there\
+  \ '''
+
+
+def multiline_backslash_2():
+    '''
+    hey there \ '''
+
+
+def multiline_backslash_3():
+    '''
+    already escaped \\'''

From a0b4e609a7393fac11ecc94eb859c1e85b540036 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C5=81ukasz=20Langa?= <lukasz@langa.pl>
Date: Mon, 26 Apr 2021 21:22:25 +0200
Subject: [PATCH 0153/1034] Bump pathspec to >= 0.8.1 to solve invalid
 .gitignore exclusion handling (#2084)

Also made the Click requirement in Pipfile consistent with setup.py and bumped mypy.
---
 Pipfile      |   6 +-
 Pipfile.lock | 697 +++++++++++++++++++++++++--------------------------
 setup.py     |   2 +-
 3 files changed, 344 insertions(+), 361 deletions(-)

diff --git a/Pipfile b/Pipfile
index 32fb867415f..40f3d607653 100644
--- a/Pipfile
+++ b/Pipfile
@@ -9,7 +9,7 @@ coverage = "*"
 docutils = "==0.15"  # not a direct dependency, see https://github.com/pypa/pipenv/issues/3865
 flake8 = "*"
 flake8-bugbear = "*"
-mypy = ">=0.782"
+mypy = ">=0.812"
 pre-commit = "*"
 readme_renderer = "*"
 recommonmark = "*"
@@ -23,9 +23,9 @@ black = {editable = true, extras = ["d"], path = "."}
 aiohttp = ">=3.3.2"
 aiohttp-cors = "*"
 appdirs = "*"
-click = ">=7.0"
+click = ">=7.1.2"
 mypy_extensions = ">=0.4.3"
-pathspec = ">=0.6"
+pathspec = ">=0.8.1"
 regex = ">=2020.1.8"
 toml = ">=0.10.1"
 typed-ast = "==1.4.2"
diff --git a/Pipfile.lock b/Pipfile.lock
index 3d908dc90f3..8a16a75026a 100644
--- a/Pipfile.lock
+++ b/Pipfile.lock
@@ -16,46 +16,46 @@
     "default": {
         "aiohttp": {
             "hashes": [
-                "sha256:119feb2bd551e58d83d1b38bfa4cb921af8ddedec9fad7183132db334c3133e0",
-                "sha256:16d0683ef8a6d803207f02b899c928223eb219111bd52420ef3d7a8aa76227b6",
-                "sha256:2eb3efe243e0f4ecbb654b08444ae6ffab37ac0ef8f69d3a2ffb958905379daf",
-                "sha256:2ffea7904e70350da429568113ae422c88d2234ae776519549513c8f217f58a9",
-                "sha256:40bd1b101b71a18a528ffce812cc14ff77d4a2a1272dfb8b11b200967489ef3e",
-                "sha256:418597633b5cd9639e514b1d748f358832c08cd5d9ef0870026535bd5eaefdd0",
-                "sha256:481d4b96969fbfdcc3ff35eea5305d8565a8300410d3d269ccac69e7256b1329",
-                "sha256:4c1bdbfdd231a20eee3e56bd0ac1cd88c4ff41b64ab679ed65b75c9c74b6c5c2",
-                "sha256:5563ad7fde451b1986d42b9bb9140e2599ecf4f8e42241f6da0d3d624b776f40",
-                "sha256:58c62152c4c8731a3152e7e650b29ace18304d086cb5552d317a54ff2749d32a",
-                "sha256:5b50e0b9460100fe05d7472264d1975f21ac007b35dcd6fd50279b72925a27f4",
-                "sha256:5d84ecc73141d0a0d61ece0742bb7ff5751b0657dab8405f899d3ceb104cc7de",
-                "sha256:5dde6d24bacac480be03f4f864e9a67faac5032e28841b00533cd168ab39cad9",
-                "sha256:5e91e927003d1ed9283dee9abcb989334fc8e72cf89ebe94dc3e07e3ff0b11e9",
-                "sha256:62bc216eafac3204877241569209d9ba6226185aa6d561c19159f2e1cbb6abfb",
-                "sha256:6c8200abc9dc5f27203986100579fc19ccad7a832c07d2bc151ce4ff17190076",
-                "sha256:6ca56bdfaf825f4439e9e3673775e1032d8b6ea63b8953d3812c71bd6a8b81de",
-                "sha256:71680321a8a7176a58dfbc230789790639db78dad61a6e120b39f314f43f1907",
-                "sha256:7c7820099e8b3171e54e7eedc33e9450afe7cd08172632d32128bd527f8cb77d",
-                "sha256:7dbd087ff2f4046b9b37ba28ed73f15fd0bc9f4fdc8ef6781913da7f808d9536",
-                "sha256:822bd4fd21abaa7b28d65fc9871ecabaddc42767884a626317ef5b75c20e8a2d",
-                "sha256:8ec1a38074f68d66ccb467ed9a673a726bb397142c273f90d4ba954666e87d54",
-                "sha256:950b7ef08b2afdab2488ee2edaff92a03ca500a48f1e1aaa5900e73d6cf992bc",
-                "sha256:99c5a5bf7135607959441b7d720d96c8e5c46a1f96e9d6d4c9498be8d5f24212",
-                "sha256:b84ad94868e1e6a5e30d30ec419956042815dfaea1b1df1cef623e4564c374d9",
-                "sha256:bc3d14bf71a3fb94e5acf5bbf67331ab335467129af6416a437bd6024e4f743d",
-                "sha256:c2a80fd9a8d7e41b4e38ea9fe149deed0d6aaede255c497e66b8213274d6d61b",
-                "sha256:c44d3c82a933c6cbc21039326767e778eface44fca55c65719921c4b9661a3f7",
-                "sha256:cc31e906be1cc121ee201adbdf844522ea3349600dd0a40366611ca18cd40e81",
-                "sha256:d5d102e945ecca93bcd9801a7bb2fa703e37ad188a2f81b1e65e4abe4b51b00c",
-                "sha256:dd7936f2a6daa861143e376b3a1fb56e9b802f4980923594edd9ca5670974895",
-                "sha256:dee68ec462ff10c1d836c0ea2642116aba6151c6880b688e56b4c0246770f297",
-                "sha256:e76e78863a4eaec3aee5722d85d04dcbd9844bc6cd3bfa6aa880ff46ad16bfcb",
-                "sha256:eab51036cac2da8a50d7ff0ea30be47750547c9aa1aa2cf1a1b710a1827e7dbe",
-                "sha256:f4496d8d04da2e98cc9133e238ccebf6a13ef39a93da2e87146c8c8ac9768242",
-                "sha256:fbd3b5e18d34683decc00d9a360179ac1e7a320a5fee10ab8053ffd6deab76e0",
-                "sha256:feb24ff1226beeb056e247cf2e24bba5232519efb5645121c4aea5b6ad74c1f2"
+                "sha256:02f46fc0e3c5ac58b80d4d56eb0a7c7d97fcef69ace9326289fb9f1955e65cfe",
+                "sha256:0563c1b3826945eecd62186f3f5c7d31abb7391fedc893b7e2b26303b5a9f3fe",
+                "sha256:114b281e4d68302a324dd33abb04778e8557d88947875cbf4e842c2c01a030c5",
+                "sha256:14762875b22d0055f05d12abc7f7d61d5fd4fe4642ce1a249abdf8c700bf1fd8",
+                "sha256:15492a6368d985b76a2a5fdd2166cddfea5d24e69eefed4630cbaae5c81d89bd",
+                "sha256:17c073de315745a1510393a96e680d20af8e67e324f70b42accbd4cb3315c9fb",
+                "sha256:209b4a8ee987eccc91e2bd3ac36adee0e53a5970b8ac52c273f7f8fd4872c94c",
+                "sha256:230a8f7e24298dea47659251abc0fd8b3c4e38a664c59d4b89cca7f6c09c9e87",
+                "sha256:2e19413bf84934d651344783c9f5e22dee452e251cfd220ebadbed2d9931dbf0",
+                "sha256:393f389841e8f2dfc86f774ad22f00923fdee66d238af89b70ea314c4aefd290",
+                "sha256:3cf75f7cdc2397ed4442594b935a11ed5569961333d49b7539ea741be2cc79d5",
+                "sha256:3d78619672183be860b96ed96f533046ec97ca067fd46ac1f6a09cd9b7484287",
+                "sha256:40eced07f07a9e60e825554a31f923e8d3997cfc7fb31dbc1328c70826e04cde",
+                "sha256:493d3299ebe5f5a7c66b9819eacdcfbbaaf1a8e84911ddffcdc48888497afecf",
+                "sha256:4b302b45040890cea949ad092479e01ba25911a15e648429c7c5aae9650c67a8",
+                "sha256:515dfef7f869a0feb2afee66b957cc7bbe9ad0cdee45aec7fdc623f4ecd4fb16",
+                "sha256:547da6cacac20666422d4882cfcd51298d45f7ccb60a04ec27424d2f36ba3eaf",
+                "sha256:5df68496d19f849921f05f14f31bd6ef53ad4b00245da3195048c69934521809",
+                "sha256:64322071e046020e8797117b3658b9c2f80e3267daec409b350b6a7a05041213",
+                "sha256:7615dab56bb07bff74bc865307aeb89a8bfd9941d2ef9d817b9436da3a0ea54f",
+                "sha256:79ebfc238612123a713a457d92afb4096e2148be17df6c50fb9bf7a81c2f8013",
+                "sha256:7b18b97cf8ee5452fa5f4e3af95d01d84d86d32c5e2bfa260cf041749d66360b",
+                "sha256:932bb1ea39a54e9ea27fc9232163059a0b8855256f4052e776357ad9add6f1c9",
+                "sha256:a00bb73540af068ca7390e636c01cbc4f644961896fa9363154ff43fd37af2f5",
+                "sha256:a5ca29ee66f8343ed336816c553e82d6cade48a3ad702b9ffa6125d187e2dedb",
+                "sha256:af9aa9ef5ba1fd5b8c948bb11f44891968ab30356d65fd0cc6707d989cd521df",
+                "sha256:bb437315738aa441251214dad17428cafda9cdc9729499f1d6001748e1d432f4",
+                "sha256:bdb230b4943891321e06fc7def63c7aace16095be7d9cf3b1e01be2f10fba439",
+                "sha256:c6e9dcb4cb338d91a73f178d866d051efe7c62a7166653a91e7d9fb18274058f",
+                "sha256:cffe3ab27871bc3ea47df5d8f7013945712c46a3cc5a95b6bee15887f1675c22",
+                "sha256:d012ad7911653a906425d8473a1465caa9f8dea7fcf07b6d870397b774ea7c0f",
+                "sha256:d9e13b33afd39ddeb377eff2c1c4f00544e191e1d1dee5b6c51ddee8ea6f0cf5",
+                "sha256:e4b2b334e68b18ac9817d828ba44d8fcb391f6acb398bcc5062b14b2cbeac970",
+                "sha256:e54962802d4b8b18b6207d4a927032826af39395a3bd9196a5af43fc4e60b009",
+                "sha256:f705e12750171c0ab4ef2a3c76b9a4024a62c4103e3a55dd6f99265b9bc6fcfc",
+                "sha256:f881853d2643a29e643609da57b96d5f9c9b93f62429dcc1cbb413c7d07f0e1a",
+                "sha256:fe60131d21b31fd1a14bd43e6bb88256f69dfc3188b3a89d736d6c71ed43ec95"
             ],
             "index": "pypi",
-            "version": "==3.7.4"
+            "version": "==3.7.4.post0"
         },
         "aiohttp-cors": {
             "hashes": [
@@ -78,6 +78,7 @@
                 "sha256:0c3c816a028d47f659d6ff5c745cb2acf1f966da1fe5c19c77a70282b25f4c5f",
                 "sha256:4291ca197d287d274d0b6cb5d6f8f8f82d434ed288f962539ff18cc9012f9ea3"
             ],
+            "markers": "python_full_version >= '3.5.3'",
             "version": "==3.0.1"
         },
         "attrs": {
@@ -85,6 +86,7 @@
                 "sha256:31b2eced602aa8423c2aea9c76a724617ed67cf9513173fd3a4f03e3a929c7e6",
                 "sha256:832aa3cde19744e49938b91fea06d69ecb9e649c93ba974535d08ad92164f700"
             ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==20.3.0"
         },
         "black": {
@@ -96,10 +98,11 @@
         },
         "chardet": {
             "hashes": [
-                "sha256:84ab92ed1c4d4f16916e05906b6b75a6c0fb5db821cc65e70cbd64a3e2a5eaae",
-                "sha256:fc323ffcaeaed0e0a02bf4d117757b98aed530d9ed4531e3e15460124c106691"
+                "sha256:0d6f53a15db4120f2b08c94f11e7d93d2c911ee118b6b30a04ec3ee8310179fa",
+                "sha256:f864054d66fd9118f2e67044ac8981a54775ec5b67aed0441892edb553d21da5"
             ],
-            "version": "==3.0.4"
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
+            "version": "==4.0.0"
         },
         "click": {
             "hashes": [
@@ -115,13 +118,16 @@
                 "sha256:6988bd2b895eef432d562370bb707d540f32f7360ab13da45340101bc2307d84"
             ],
             "index": "pypi",
-            "version": "==0.6"
+            "python_version <": "3.7",
+            "version": "==0.6",
+            "version >": "0.6"
         },
         "idna": {
             "hashes": [
                 "sha256:5205d03e7bcbb919cc9c19885f9920d622ca52448306f2377daede5cf3faac16",
                 "sha256:c5b02147e01ea9920e6b0a3f1f7bb833612d507592c837a6c49552768f4054e1"
             ],
+            "markers": "python_version >= '3.4'",
             "version": "==3.1"
         },
         "multidict": {
@@ -164,6 +170,7 @@
                 "sha256:f21756997ad8ef815d8ef3d34edd98804ab5ea337feedcd62fb52d22bf531281",
                 "sha256:fc13a9524bc18b6fb6e0dbec3533ba0496bbed167c56d0aabefd965584557d80"
             ],
+            "markers": "python_version >= '3.6'",
             "version": "==5.1.0"
         },
         "mypy-extensions": {
@@ -184,50 +191,58 @@
         },
         "regex": {
             "hashes": [
-                "sha256:02951b7dacb123d8ea6da44fe45ddd084aa6777d4b2454fa0da61d569c6fa538",
-                "sha256:0d08e71e70c0237883d0bef12cad5145b84c3705e9c6a588b2a9c7080e5af2a4",
-                "sha256:1862a9d9194fae76a7aaf0150d5f2a8ec1da89e8b55890b1786b8f88a0f619dc",
-                "sha256:1ab79fcb02b930de09c76d024d279686ec5d532eb814fd0ed1e0051eb8bd2daa",
-                "sha256:1fa7ee9c2a0e30405e21031d07d7ba8617bc590d391adfc2b7f1e8b99f46f444",
-                "sha256:262c6825b309e6485ec2493ffc7e62a13cf13fb2a8b6d212f72bd53ad34118f1",
-                "sha256:2a11a3e90bd9901d70a5b31d7dd85114755a581a5da3fc996abfefa48aee78af",
-                "sha256:2c99e97d388cd0a8d30f7c514d67887d8021541b875baf09791a3baad48bb4f8",
-                "sha256:3128e30d83f2e70b0bed9b2a34e92707d0877e460b402faca908c6667092ada9",
-                "sha256:38c8fd190db64f513fe4e1baa59fed086ae71fa45083b6936b52d34df8f86a88",
-                "sha256:3bddc701bdd1efa0d5264d2649588cbfda549b2899dc8d50417e47a82e1387ba",
-                "sha256:4902e6aa086cbb224241adbc2f06235927d5cdacffb2425c73e6570e8d862364",
-                "sha256:49cae022fa13f09be91b2c880e58e14b6da5d10639ed45ca69b85faf039f7a4e",
-                "sha256:56e01daca75eae420bce184edd8bb341c8eebb19dd3bce7266332258f9fb9dd7",
-                "sha256:5862975b45d451b6db51c2e654990c1820523a5b07100fc6903e9c86575202a0",
-                "sha256:6a8ce43923c518c24a2579fda49f093f1397dad5d18346211e46f134fc624e31",
-                "sha256:6c54ce4b5d61a7129bad5c5dc279e222afd00e721bf92f9ef09e4fae28755683",
-                "sha256:6e4b08c6f8daca7d8f07c8d24e4331ae7953333dbd09c648ed6ebd24db5a10ee",
-                "sha256:717881211f46de3ab130b58ec0908267961fadc06e44f974466d1887f865bd5b",
-                "sha256:749078d1eb89484db5f34b4012092ad14b327944ee7f1c4f74d6279a6e4d1884",
-                "sha256:7913bd25f4ab274ba37bc97ad0e21c31004224ccb02765ad984eef43e04acc6c",
-                "sha256:7a25fcbeae08f96a754b45bdc050e1fb94b95cab046bf56b016c25e9ab127b3e",
-                "sha256:83d6b356e116ca119db8e7c6fc2983289d87b27b3fac238cfe5dca529d884562",
-                "sha256:8b882a78c320478b12ff024e81dc7d43c1462aa4a3341c754ee65d857a521f85",
-                "sha256:8f6a2229e8ad946e36815f2a03386bb8353d4bde368fdf8ca5f0cb97264d3b5c",
-                "sha256:9801c4c1d9ae6a70aeb2128e5b4b68c45d4f0af0d1535500884d644fa9b768c6",
-                "sha256:a15f64ae3a027b64496a71ab1f722355e570c3fac5ba2801cafce846bf5af01d",
-                "sha256:a3d748383762e56337c39ab35c6ed4deb88df5326f97a38946ddd19028ecce6b",
-                "sha256:a63f1a07932c9686d2d416fb295ec2c01ab246e89b4d58e5fa468089cab44b70",
-                "sha256:b2b1a5ddae3677d89b686e5c625fc5547c6e492bd755b520de5332773a8af06b",
-                "sha256:b2f4007bff007c96a173e24dcda236e5e83bde4358a557f9ccf5e014439eae4b",
-                "sha256:baf378ba6151f6e272824b86a774326f692bc2ef4cc5ce8d5bc76e38c813a55f",
-                "sha256:bafb01b4688833e099d79e7efd23f99172f501a15c44f21ea2118681473fdba0",
-                "sha256:bba349276b126947b014e50ab3316c027cac1495992f10e5682dc677b3dfa0c5",
-                "sha256:c084582d4215593f2f1d28b65d2a2f3aceff8342aa85afd7be23a9cad74a0de5",
-                "sha256:d1ebb090a426db66dd80df8ca85adc4abfcbad8a7c2e9a5ec7513ede522e0a8f",
-                "sha256:d2d8ce12b7c12c87e41123997ebaf1a5767a5be3ec545f64675388970f415e2e",
-                "sha256:e32f5f3d1b1c663af7f9c4c1e72e6ffe9a78c03a31e149259f531e0fed826512",
-                "sha256:e3faaf10a0d1e8e23a9b51d1900b72e1635c2d5b0e1bea1c18022486a8e2e52d",
-                "sha256:f7d29a6fc4760300f86ae329e3b6ca28ea9c20823df123a2ea8693e967b29917",
-                "sha256:f8f295db00ef5f8bae530fc39af0b40486ca6068733fb860b42115052206466f"
+                "sha256:01afaf2ec48e196ba91b37451aa353cb7eda77efe518e481707e0515025f0cd5",
+                "sha256:11d773d75fa650cd36f68d7ca936e3c7afaae41b863b8c387a22aaa78d3c5c79",
+                "sha256:18c071c3eb09c30a264879f0d310d37fe5d3a3111662438889ae2eb6fc570c31",
+                "sha256:1e1c20e29358165242928c2de1482fb2cf4ea54a6a6dea2bd7a0e0d8ee321500",
+                "sha256:281d2fd05555079448537fe108d79eb031b403dac622621c78944c235f3fcf11",
+                "sha256:314d66636c494ed9c148a42731b3834496cc9a2c4251b1661e40936814542b14",
+                "sha256:32e65442138b7b76dd8173ffa2cf67356b7bc1768851dded39a7a13bf9223da3",
+                "sha256:339456e7d8c06dd36a22e451d58ef72cef293112b559010db3d054d5560ef439",
+                "sha256:3916d08be28a1149fb97f7728fca1f7c15d309a9f9682d89d79db75d5e52091c",
+                "sha256:3a9cd17e6e5c7eb328517969e0cb0c3d31fd329298dd0c04af99ebf42e904f82",
+                "sha256:47bf5bf60cf04d72bf6055ae5927a0bd9016096bf3d742fa50d9bf9f45aa0711",
+                "sha256:4c46e22a0933dd783467cf32b3516299fb98cfebd895817d685130cc50cd1093",
+                "sha256:4c557a7b470908b1712fe27fb1ef20772b78079808c87d20a90d051660b1d69a",
+                "sha256:52ba3d3f9b942c49d7e4bc105bb28551c44065f139a65062ab7912bef10c9afb",
+                "sha256:563085e55b0d4fb8f746f6a335893bda5c2cef43b2f0258fe1020ab1dd874df8",
+                "sha256:598585c9f0af8374c28edd609eb291b5726d7cbce16be6a8b95aa074d252ee17",
+                "sha256:619d71c59a78b84d7f18891fe914446d07edd48dc8328c8e149cbe0929b4e000",
+                "sha256:67bdb9702427ceddc6ef3dc382455e90f785af4c13d495f9626861763ee13f9d",
+                "sha256:6d1b01031dedf2503631d0903cb563743f397ccaf6607a5e3b19a3d76fc10480",
+                "sha256:741a9647fcf2e45f3a1cf0e24f5e17febf3efe8d4ba1281dcc3aa0459ef424dc",
+                "sha256:7c2a1af393fcc09e898beba5dd59196edaa3116191cc7257f9224beaed3e1aa0",
+                "sha256:7d9884d86dd4dd489e981d94a65cd30d6f07203d90e98f6f657f05170f6324c9",
+                "sha256:90f11ff637fe8798933fb29f5ae1148c978cccb0452005bf4c69e13db951e765",
+                "sha256:919859aa909429fb5aa9cf8807f6045592c85ef56fdd30a9a3747e513db2536e",
+                "sha256:96fcd1888ab4d03adfc9303a7b3c0bd78c5412b2bfbe76db5b56d9eae004907a",
+                "sha256:97f29f57d5b84e73fbaf99ab3e26134e6687348e95ef6b48cfd2c06807005a07",
+                "sha256:980d7be47c84979d9136328d882f67ec5e50008681d94ecc8afa8a65ed1f4a6f",
+                "sha256:a91aa8619b23b79bcbeb37abe286f2f408d2f2d6f29a17237afda55bb54e7aac",
+                "sha256:ade17eb5d643b7fead300a1641e9f45401c98eee23763e9ed66a43f92f20b4a7",
+                "sha256:b9c3db21af35e3b3c05764461b262d6f05bbca08a71a7849fd79d47ba7bc33ed",
+                "sha256:bd28bc2e3a772acbb07787c6308e00d9626ff89e3bfcdebe87fa5afbfdedf968",
+                "sha256:bf5824bfac591ddb2c1f0a5f4ab72da28994548c708d2191e3b87dd207eb3ad7",
+                "sha256:c0502c0fadef0d23b128605d69b58edb2c681c25d44574fc673b0e52dce71ee2",
+                "sha256:c38c71df845e2aabb7fb0b920d11a1b5ac8526005e533a8920aea97efb8ec6a4",
+                "sha256:ce15b6d103daff8e9fee13cf7f0add05245a05d866e73926c358e871221eae87",
+                "sha256:d3029c340cfbb3ac0a71798100ccc13b97dddf373a4ae56b6a72cf70dfd53bc8",
+                "sha256:e512d8ef5ad7b898cdb2d8ee1cb09a8339e4f8be706d27eaa180c2f177248a10",
+                "sha256:e8e5b509d5c2ff12f8418006d5a90e9436766133b564db0abaec92fd27fcee29",
+                "sha256:ee54ff27bf0afaf4c3b3a62bcd016c12c3fdb4ec4f413391a90bd38bc3624605",
+                "sha256:fa4537fb4a98fe8fde99626e4681cc644bdcf2a795038533f9f711513a862ae6",
+                "sha256:fd45ff9293d9274c5008a2054ecef86a9bfe819a67c7be1afb65e69b405b3042"
             ],
             "index": "pypi",
-            "version": "==2020.11.13"
+            "version": "==2021.4.4"
+        },
+        "setuptools-scm": {
+            "hashes": [
+                "sha256:c3bd5f701c8def44a5c0bfe8d407bef3f80342217ef3492b951f3777bd2d915c",
+                "sha256:d1925a69cb07e9b29416a275b9fadb009a23c148ace905b2fb220649a6c18e92"
+            ],
+            "markers": "python_version >= '3.6'",
+            "version": "==6.0.1"
         },
         "toml": {
             "hashes": [
@@ -280,7 +295,9 @@
                 "sha256:dafc7639cde7f1b6e1acc0f457842a83e722ccca8eef5270af2d74792619a89f"
             ],
             "index": "pypi",
-            "version": "==3.7.4.3"
+            "python_version <": "3.8",
+            "version": "==3.7.4.3",
+            "version >=": "3.7.4"
         },
         "yarl": {
             "hashes": [
@@ -322,52 +339,53 @@
                 "sha256:f0b059678fd549c66b89bed03efcabb009075bd131c248ecdf087bdb6faba24a",
                 "sha256:fcbb48a93e8699eae920f8d92f7160c03567b421bc17362a9ffbbd706a816f71"
             ],
+            "markers": "python_version >= '3.6'",
             "version": "==1.6.3"
         }
     },
     "develop": {
         "aiohttp": {
             "hashes": [
-                "sha256:119feb2bd551e58d83d1b38bfa4cb921af8ddedec9fad7183132db334c3133e0",
-                "sha256:16d0683ef8a6d803207f02b899c928223eb219111bd52420ef3d7a8aa76227b6",
-                "sha256:2eb3efe243e0f4ecbb654b08444ae6ffab37ac0ef8f69d3a2ffb958905379daf",
-                "sha256:2ffea7904e70350da429568113ae422c88d2234ae776519549513c8f217f58a9",
-                "sha256:40bd1b101b71a18a528ffce812cc14ff77d4a2a1272dfb8b11b200967489ef3e",
-                "sha256:418597633b5cd9639e514b1d748f358832c08cd5d9ef0870026535bd5eaefdd0",
-                "sha256:481d4b96969fbfdcc3ff35eea5305d8565a8300410d3d269ccac69e7256b1329",
-                "sha256:4c1bdbfdd231a20eee3e56bd0ac1cd88c4ff41b64ab679ed65b75c9c74b6c5c2",
-                "sha256:5563ad7fde451b1986d42b9bb9140e2599ecf4f8e42241f6da0d3d624b776f40",
-                "sha256:58c62152c4c8731a3152e7e650b29ace18304d086cb5552d317a54ff2749d32a",
-                "sha256:5b50e0b9460100fe05d7472264d1975f21ac007b35dcd6fd50279b72925a27f4",
-                "sha256:5d84ecc73141d0a0d61ece0742bb7ff5751b0657dab8405f899d3ceb104cc7de",
-                "sha256:5dde6d24bacac480be03f4f864e9a67faac5032e28841b00533cd168ab39cad9",
-                "sha256:5e91e927003d1ed9283dee9abcb989334fc8e72cf89ebe94dc3e07e3ff0b11e9",
-                "sha256:62bc216eafac3204877241569209d9ba6226185aa6d561c19159f2e1cbb6abfb",
-                "sha256:6c8200abc9dc5f27203986100579fc19ccad7a832c07d2bc151ce4ff17190076",
-                "sha256:6ca56bdfaf825f4439e9e3673775e1032d8b6ea63b8953d3812c71bd6a8b81de",
-                "sha256:71680321a8a7176a58dfbc230789790639db78dad61a6e120b39f314f43f1907",
-                "sha256:7c7820099e8b3171e54e7eedc33e9450afe7cd08172632d32128bd527f8cb77d",
-                "sha256:7dbd087ff2f4046b9b37ba28ed73f15fd0bc9f4fdc8ef6781913da7f808d9536",
-                "sha256:822bd4fd21abaa7b28d65fc9871ecabaddc42767884a626317ef5b75c20e8a2d",
-                "sha256:8ec1a38074f68d66ccb467ed9a673a726bb397142c273f90d4ba954666e87d54",
-                "sha256:950b7ef08b2afdab2488ee2edaff92a03ca500a48f1e1aaa5900e73d6cf992bc",
-                "sha256:99c5a5bf7135607959441b7d720d96c8e5c46a1f96e9d6d4c9498be8d5f24212",
-                "sha256:b84ad94868e1e6a5e30d30ec419956042815dfaea1b1df1cef623e4564c374d9",
-                "sha256:bc3d14bf71a3fb94e5acf5bbf67331ab335467129af6416a437bd6024e4f743d",
-                "sha256:c2a80fd9a8d7e41b4e38ea9fe149deed0d6aaede255c497e66b8213274d6d61b",
-                "sha256:c44d3c82a933c6cbc21039326767e778eface44fca55c65719921c4b9661a3f7",
-                "sha256:cc31e906be1cc121ee201adbdf844522ea3349600dd0a40366611ca18cd40e81",
-                "sha256:d5d102e945ecca93bcd9801a7bb2fa703e37ad188a2f81b1e65e4abe4b51b00c",
-                "sha256:dd7936f2a6daa861143e376b3a1fb56e9b802f4980923594edd9ca5670974895",
-                "sha256:dee68ec462ff10c1d836c0ea2642116aba6151c6880b688e56b4c0246770f297",
-                "sha256:e76e78863a4eaec3aee5722d85d04dcbd9844bc6cd3bfa6aa880ff46ad16bfcb",
-                "sha256:eab51036cac2da8a50d7ff0ea30be47750547c9aa1aa2cf1a1b710a1827e7dbe",
-                "sha256:f4496d8d04da2e98cc9133e238ccebf6a13ef39a93da2e87146c8c8ac9768242",
-                "sha256:fbd3b5e18d34683decc00d9a360179ac1e7a320a5fee10ab8053ffd6deab76e0",
-                "sha256:feb24ff1226beeb056e247cf2e24bba5232519efb5645121c4aea5b6ad74c1f2"
+                "sha256:02f46fc0e3c5ac58b80d4d56eb0a7c7d97fcef69ace9326289fb9f1955e65cfe",
+                "sha256:0563c1b3826945eecd62186f3f5c7d31abb7391fedc893b7e2b26303b5a9f3fe",
+                "sha256:114b281e4d68302a324dd33abb04778e8557d88947875cbf4e842c2c01a030c5",
+                "sha256:14762875b22d0055f05d12abc7f7d61d5fd4fe4642ce1a249abdf8c700bf1fd8",
+                "sha256:15492a6368d985b76a2a5fdd2166cddfea5d24e69eefed4630cbaae5c81d89bd",
+                "sha256:17c073de315745a1510393a96e680d20af8e67e324f70b42accbd4cb3315c9fb",
+                "sha256:209b4a8ee987eccc91e2bd3ac36adee0e53a5970b8ac52c273f7f8fd4872c94c",
+                "sha256:230a8f7e24298dea47659251abc0fd8b3c4e38a664c59d4b89cca7f6c09c9e87",
+                "sha256:2e19413bf84934d651344783c9f5e22dee452e251cfd220ebadbed2d9931dbf0",
+                "sha256:393f389841e8f2dfc86f774ad22f00923fdee66d238af89b70ea314c4aefd290",
+                "sha256:3cf75f7cdc2397ed4442594b935a11ed5569961333d49b7539ea741be2cc79d5",
+                "sha256:3d78619672183be860b96ed96f533046ec97ca067fd46ac1f6a09cd9b7484287",
+                "sha256:40eced07f07a9e60e825554a31f923e8d3997cfc7fb31dbc1328c70826e04cde",
+                "sha256:493d3299ebe5f5a7c66b9819eacdcfbbaaf1a8e84911ddffcdc48888497afecf",
+                "sha256:4b302b45040890cea949ad092479e01ba25911a15e648429c7c5aae9650c67a8",
+                "sha256:515dfef7f869a0feb2afee66b957cc7bbe9ad0cdee45aec7fdc623f4ecd4fb16",
+                "sha256:547da6cacac20666422d4882cfcd51298d45f7ccb60a04ec27424d2f36ba3eaf",
+                "sha256:5df68496d19f849921f05f14f31bd6ef53ad4b00245da3195048c69934521809",
+                "sha256:64322071e046020e8797117b3658b9c2f80e3267daec409b350b6a7a05041213",
+                "sha256:7615dab56bb07bff74bc865307aeb89a8bfd9941d2ef9d817b9436da3a0ea54f",
+                "sha256:79ebfc238612123a713a457d92afb4096e2148be17df6c50fb9bf7a81c2f8013",
+                "sha256:7b18b97cf8ee5452fa5f4e3af95d01d84d86d32c5e2bfa260cf041749d66360b",
+                "sha256:932bb1ea39a54e9ea27fc9232163059a0b8855256f4052e776357ad9add6f1c9",
+                "sha256:a00bb73540af068ca7390e636c01cbc4f644961896fa9363154ff43fd37af2f5",
+                "sha256:a5ca29ee66f8343ed336816c553e82d6cade48a3ad702b9ffa6125d187e2dedb",
+                "sha256:af9aa9ef5ba1fd5b8c948bb11f44891968ab30356d65fd0cc6707d989cd521df",
+                "sha256:bb437315738aa441251214dad17428cafda9cdc9729499f1d6001748e1d432f4",
+                "sha256:bdb230b4943891321e06fc7def63c7aace16095be7d9cf3b1e01be2f10fba439",
+                "sha256:c6e9dcb4cb338d91a73f178d866d051efe7c62a7166653a91e7d9fb18274058f",
+                "sha256:cffe3ab27871bc3ea47df5d8f7013945712c46a3cc5a95b6bee15887f1675c22",
+                "sha256:d012ad7911653a906425d8473a1465caa9f8dea7fcf07b6d870397b774ea7c0f",
+                "sha256:d9e13b33afd39ddeb377eff2c1c4f00544e191e1d1dee5b6c51ddee8ea6f0cf5",
+                "sha256:e4b2b334e68b18ac9817d828ba44d8fcb391f6acb398bcc5062b14b2cbeac970",
+                "sha256:e54962802d4b8b18b6207d4a927032826af39395a3bd9196a5af43fc4e60b009",
+                "sha256:f705e12750171c0ab4ef2a3c76b9a4024a62c4103e3a55dd6f99265b9bc6fcfc",
+                "sha256:f881853d2643a29e643609da57b96d5f9c9b93f62429dcc1cbb413c7d07f0e1a",
+                "sha256:fe60131d21b31fd1a14bd43e6bb88256f69dfc3188b3a89d736d6c71ed43ec95"
             ],
             "index": "pypi",
-            "version": "==3.7.4"
+            "version": "==3.7.4.post0"
         },
         "aiohttp-cors": {
             "hashes": [
@@ -397,6 +415,7 @@
                 "sha256:0c3c816a028d47f659d6ff5c745cb2acf1f966da1fe5c19c77a70282b25f4c5f",
                 "sha256:4291ca197d287d274d0b6cb5d6f8f8f82d434ed288f962539ff18cc9012f9ea3"
             ],
+            "markers": "python_full_version >= '3.5.3'",
             "version": "==3.0.1"
         },
         "attrs": {
@@ -404,6 +423,7 @@
                 "sha256:31b2eced602aa8423c2aea9c76a724617ed67cf9513173fd3a4f03e3a929c7e6",
                 "sha256:832aa3cde19744e49938b91fea06d69ecb9e649c93ba974535d08ad92164f700"
             ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==20.3.0"
         },
         "babel": {
@@ -411,6 +431,7 @@
                 "sha256:9d35c22fcc79893c3ecc85ac4a56cde1ecf3f19c540bba0922308a6c06ca6fa5",
                 "sha256:da031ab54472314f210b0adcff1588ee5d1d1d0ba4dbd07b94dba82bde791e05"
             ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==2.9.0"
         },
         "black": {
@@ -425,6 +446,7 @@
                 "sha256:6123ddc1052673e52bab52cdc955bcb57a015264a1c57d37bea2f6b817af0125",
                 "sha256:98b3170739e5e83dd9dc19633f074727ad848cbedb6026708c8ac2d3b697a433"
             ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
             "version": "==3.3.0"
         },
         "certifi": {
@@ -434,61 +456,21 @@
             ],
             "version": "==2020.12.5"
         },
-        "cffi": {
-            "hashes": [
-                "sha256:005a36f41773e148deac64b08f233873a4d0c18b053d37da83f6af4d9087b813",
-                "sha256:0857f0ae312d855239a55c81ef453ee8fd24136eaba8e87a2eceba644c0d4c06",
-                "sha256:1071534bbbf8cbb31b498d5d9db0f274f2f7a865adca4ae429e147ba40f73dea",
-                "sha256:158d0d15119b4b7ff6b926536763dc0714313aa59e320ddf787502c70c4d4bee",
-                "sha256:1f436816fc868b098b0d63b8920de7d208c90a67212546d02f84fe78a9c26396",
-                "sha256:2894f2df484ff56d717bead0a5c2abb6b9d2bf26d6960c4604d5c48bbc30ee73",
-                "sha256:29314480e958fd8aab22e4a58b355b629c59bf5f2ac2492b61e3dc06d8c7a315",
-                "sha256:34eff4b97f3d982fb93e2831e6750127d1355a923ebaeeb565407b3d2f8d41a1",
-                "sha256:35f27e6eb43380fa080dccf676dece30bef72e4a67617ffda586641cd4508d49",
-                "sha256:3d3dd4c9e559eb172ecf00a2a7517e97d1e96de2a5e610bd9b68cea3925b4892",
-                "sha256:43e0b9d9e2c9e5d152946b9c5fe062c151614b262fda2e7b201204de0b99e482",
-                "sha256:48e1c69bbacfc3d932221851b39d49e81567a4d4aac3b21258d9c24578280058",
-                "sha256:51182f8927c5af975fece87b1b369f722c570fe169f9880764b1ee3bca8347b5",
-                "sha256:58e3f59d583d413809d60779492342801d6e82fefb89c86a38e040c16883be53",
-                "sha256:5de7970188bb46b7bf9858eb6890aad302577a5f6f75091fd7cdd3ef13ef3045",
-                "sha256:65fa59693c62cf06e45ddbb822165394a288edce9e276647f0046e1ec26920f3",
-                "sha256:69e395c24fc60aad6bb4fa7e583698ea6cc684648e1ffb7fe85e3c1ca131a7d5",
-                "sha256:6c97d7350133666fbb5cf4abdc1178c812cb205dc6f41d174a7b0f18fb93337e",
-                "sha256:6e4714cc64f474e4d6e37cfff31a814b509a35cb17de4fb1999907575684479c",
-                "sha256:72d8d3ef52c208ee1c7b2e341f7d71c6fd3157138abf1a95166e6165dd5d4369",
-                "sha256:8ae6299f6c68de06f136f1f9e69458eae58f1dacf10af5c17353eae03aa0d827",
-                "sha256:8b198cec6c72df5289c05b05b8b0969819783f9418e0409865dac47288d2a053",
-                "sha256:99cd03ae7988a93dd00bcd9d0b75e1f6c426063d6f03d2f90b89e29b25b82dfa",
-                "sha256:9cf8022fb8d07a97c178b02327b284521c7708d7c71a9c9c355c178ac4bbd3d4",
-                "sha256:9de2e279153a443c656f2defd67769e6d1e4163952b3c622dcea5b08a6405322",
-                "sha256:9e93e79c2551ff263400e1e4be085a1210e12073a31c2011dbbda14bda0c6132",
-                "sha256:9ff227395193126d82e60319a673a037d5de84633f11279e336f9c0f189ecc62",
-                "sha256:a465da611f6fa124963b91bf432d960a555563efe4ed1cc403ba5077b15370aa",
-                "sha256:ad17025d226ee5beec591b52800c11680fca3df50b8b29fe51d882576e039ee0",
-                "sha256:afb29c1ba2e5a3736f1c301d9d0abe3ec8b86957d04ddfa9d7a6a42b9367e396",
-                "sha256:b85eb46a81787c50650f2392b9b4ef23e1f126313b9e0e9013b35c15e4288e2e",
-                "sha256:bb89f306e5da99f4d922728ddcd6f7fcebb3241fc40edebcb7284d7514741991",
-                "sha256:cbde590d4faaa07c72bf979734738f328d239913ba3e043b1e98fe9a39f8b2b6",
-                "sha256:cd2868886d547469123fadc46eac7ea5253ea7fcb139f12e1dfc2bbd406427d1",
-                "sha256:d42b11d692e11b6634f7613ad8df5d6d5f8875f5d48939520d351007b3c13406",
-                "sha256:f2d45f97ab6bb54753eab54fffe75aaf3de4ff2341c9daee1987ee1837636f1d",
-                "sha256:fd78e5fee591709f32ef6edb9a015b4aa1a5022598e36227500c8f4e02328d9c"
-            ],
-            "version": "==1.14.5"
-        },
         "cfgv": {
             "hashes": [
                 "sha256:32e43d604bbe7896fe7c248a9c2276447dbef840feb28fe20494f62af110211d",
                 "sha256:cf22deb93d4bcf92f345a5c3cd39d3d41d6340adc60c78bbbd6588c384fda6a1"
             ],
+            "markers": "python_full_version >= '3.6.1'",
             "version": "==3.2.0"
         },
         "chardet": {
             "hashes": [
-                "sha256:84ab92ed1c4d4f16916e05906b6b75a6c0fb5db821cc65e70cbd64a3e2a5eaae",
-                "sha256:fc323ffcaeaed0e0a02bf4d117757b98aed530d9ed4531e3e15460124c106691"
+                "sha256:0d6f53a15db4120f2b08c94f11e7d93d2c911ee118b6b30a04ec3ee8310179fa",
+                "sha256:f864054d66fd9118f2e67044ac8981a54775ec5b67aed0441892edb553d21da5"
             ],
-            "version": "==3.0.4"
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
+            "version": "==4.0.0"
         },
         "click": {
             "hashes": [
@@ -503,6 +485,7 @@
                 "sha256:5941b2b48a20143d2267e95b1c2a7603ce057ee39fd88e7329b0c292aa16869b",
                 "sha256:9f47eda37229f68eee03b24b9748937c7dc3868f906e8ba69fbcbdd3bc5dc3e2"
             ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
             "version": "==0.4.4"
         },
         "commonmark": {
@@ -514,75 +497,61 @@
         },
         "coverage": {
             "hashes": [
-                "sha256:08b3ba72bd981531fd557f67beee376d6700fba183b167857038997ba30dd297",
-                "sha256:2757fa64e11ec12220968f65d086b7a29b6583d16e9a544c889b22ba98555ef1",
-                "sha256:3102bb2c206700a7d28181dbe04d66b30780cde1d1c02c5f3c165cf3d2489497",
-                "sha256:3498b27d8236057def41de3585f317abae235dd3a11d33e01736ffedb2ef8606",
-                "sha256:378ac77af41350a8c6b8801a66021b52da8a05fd77e578b7380e876c0ce4f528",
-                "sha256:38f16b1317b8dd82df67ed5daa5f5e7c959e46579840d77a67a4ceb9cef0a50b",
-                "sha256:3911c2ef96e5ddc748a3c8b4702c61986628bb719b8378bf1e4a6184bbd48fe4",
-                "sha256:3a3c3f8863255f3c31db3889f8055989527173ef6192a283eb6f4db3c579d830",
-                "sha256:3b14b1da110ea50c8bcbadc3b82c3933974dbeea1832e814aab93ca1163cd4c1",
-                "sha256:535dc1e6e68fad5355f9984d5637c33badbdc987b0c0d303ee95a6c979c9516f",
-                "sha256:6f61319e33222591f885c598e3e24f6a4be3533c1d70c19e0dc59e83a71ce27d",
-                "sha256:723d22d324e7997a651478e9c5a3120a0ecbc9a7e94071f7e1954562a8806cf3",
-                "sha256:76b2775dda7e78680d688daabcb485dc87cf5e3184a0b3e012e1d40e38527cc8",
-                "sha256:782a5c7df9f91979a7a21792e09b34a658058896628217ae6362088b123c8500",
-                "sha256:7e4d159021c2029b958b2363abec4a11db0ce8cd43abb0d9ce44284cb97217e7",
-                "sha256:8dacc4073c359f40fcf73aede8428c35f84639baad7e1b46fce5ab7a8a7be4bb",
-                "sha256:8f33d1156241c43755137288dea619105477961cfa7e47f48dbf96bc2c30720b",
-                "sha256:8ffd4b204d7de77b5dd558cdff986a8274796a1e57813ed005b33fd97e29f059",
-                "sha256:93a280c9eb736a0dcca19296f3c30c720cb41a71b1f9e617f341f0a8e791a69b",
-                "sha256:9a4f66259bdd6964d8cf26142733c81fb562252db74ea367d9beb4f815478e72",
-                "sha256:9a9d4ff06804920388aab69c5ea8a77525cf165356db70131616acd269e19b36",
-                "sha256:a2070c5affdb3a5e751f24208c5c4f3d5f008fa04d28731416e023c93b275277",
-                "sha256:a4857f7e2bc6921dbd487c5c88b84f5633de3e7d416c4dc0bb70256775551a6c",
-                "sha256:a607ae05b6c96057ba86c811d9c43423f35e03874ffb03fbdcd45e0637e8b631",
-                "sha256:a66ca3bdf21c653e47f726ca57f46ba7fc1f260ad99ba783acc3e58e3ebdb9ff",
-                "sha256:ab110c48bc3d97b4d19af41865e14531f300b482da21783fdaacd159251890e8",
-                "sha256:b239711e774c8eb910e9b1ac719f02f5ae4bf35fa0420f438cdc3a7e4e7dd6ec",
-                "sha256:be0416074d7f253865bb67630cf7210cbc14eb05f4099cc0f82430135aaa7a3b",
-                "sha256:c46643970dff9f5c976c6512fd35768c4a3819f01f61169d8cdac3f9290903b7",
-                "sha256:c5ec71fd4a43b6d84ddb88c1df94572479d9a26ef3f150cef3dacefecf888105",
-                "sha256:c6e5174f8ca585755988bc278c8bb5d02d9dc2e971591ef4a1baabdf2d99589b",
-                "sha256:c89b558f8a9a5a6f2cfc923c304d49f0ce629c3bd85cb442ca258ec20366394c",
-                "sha256:cc44e3545d908ecf3e5773266c487ad1877be718d9dc65fc7eb6e7d14960985b",
-                "sha256:cc6f8246e74dd210d7e2b56c76ceaba1cc52b025cd75dbe96eb48791e0250e98",
-                "sha256:cd556c79ad665faeae28020a0ab3bda6cd47d94bec48e36970719b0b86e4dcf4",
-                "sha256:ce6f3a147b4b1a8b09aae48517ae91139b1b010c5f36423fa2b866a8b23df879",
-                "sha256:ceb499d2b3d1d7b7ba23abe8bf26df5f06ba8c71127f188333dddcf356b4b63f",
-                "sha256:cef06fb382557f66d81d804230c11ab292d94b840b3cb7bf4450778377b592f4",
-                "sha256:e448f56cfeae7b1b3b5bcd99bb377cde7c4eb1970a525c770720a352bc4c8044",
-                "sha256:e52d3d95df81c8f6b2a1685aabffadf2d2d9ad97203a40f8d61e51b70f191e4e",
-                "sha256:ee2f1d1c223c3d2c24e3afbb2dd38be3f03b1a8d6a83ee3d9eb8c36a52bee899",
-                "sha256:f2c6888eada180814b8583c3e793f3f343a692fc802546eed45f40a001b1169f",
-                "sha256:f51dbba78d68a44e99d484ca8c8f604f17e957c1ca09c3ebc2c7e3bbd9ba0448",
-                "sha256:f54de00baf200b4539a5a092a759f000b5f45fd226d6d25a76b0dff71177a714",
-                "sha256:fa10fee7e32213f5c7b0d6428ea92e3a3fdd6d725590238a3f92c0de1c78b9d2",
-                "sha256:fabeeb121735d47d8eab8671b6b031ce08514c86b7ad8f7d5490a7b6dcd6267d",
-                "sha256:fac3c432851038b3e6afe086f777732bcf7f6ebbfd90951fa04ee53db6d0bcdd",
-                "sha256:fda29412a66099af6d6de0baa6bd7c52674de177ec2ad2630ca264142d69c6c7",
-                "sha256:ff1330e8bc996570221b450e2d539134baa9465f5cb98aff0e0f73f34172e0ae"
+                "sha256:004d1880bed2d97151facef49f08e255a20ceb6f9432df75f4eef018fdd5a78c",
+                "sha256:01d84219b5cdbfc8122223b39a954820929497a1cb1422824bb86b07b74594b6",
+                "sha256:040af6c32813fa3eae5305d53f18875bedd079960822ef8ec067a66dd8afcd45",
+                "sha256:06191eb60f8d8a5bc046f3799f8a07a2d7aefb9504b0209aff0b47298333302a",
+                "sha256:13034c4409db851670bc9acd836243aeee299949bd5673e11844befcb0149f03",
+                "sha256:13c4ee887eca0f4c5a247b75398d4114c37882658300e153113dafb1d76de529",
+                "sha256:184a47bbe0aa6400ed2d41d8e9ed868b8205046518c52464fde713ea06e3a74a",
+                "sha256:18ba8bbede96a2c3dde7b868de9dcbd55670690af0988713f0603f037848418a",
+                "sha256:1aa846f56c3d49205c952d8318e76ccc2ae23303351d9270ab220004c580cfe2",
+                "sha256:217658ec7187497e3f3ebd901afdca1af062b42cfe3e0dafea4cced3983739f6",
+                "sha256:24d4a7de75446be83244eabbff746d66b9240ae020ced65d060815fac3423759",
+                "sha256:2910f4d36a6a9b4214bb7038d537f015346f413a975d57ca6b43bf23d6563b53",
+                "sha256:2949cad1c5208b8298d5686d5a85b66aae46d73eec2c3e08c817dd3513e5848a",
+                "sha256:2a3859cb82dcbda1cfd3e6f71c27081d18aa251d20a17d87d26d4cd216fb0af4",
+                "sha256:2cafbbb3af0733db200c9b5f798d18953b1a304d3f86a938367de1567f4b5bff",
+                "sha256:2e0d881ad471768bf6e6c2bf905d183543f10098e3b3640fc029509530091502",
+                "sha256:30c77c1dc9f253283e34c27935fded5015f7d1abe83bc7821680ac444eaf7793",
+                "sha256:3487286bc29a5aa4b93a072e9592f22254291ce96a9fbc5251f566b6b7343cdb",
+                "sha256:372da284cfd642d8e08ef606917846fa2ee350f64994bebfbd3afb0040436905",
+                "sha256:41179b8a845742d1eb60449bdb2992196e211341818565abded11cfa90efb821",
+                "sha256:44d654437b8ddd9eee7d1eaee28b7219bec228520ff809af170488fd2fed3e2b",
+                "sha256:4a7697d8cb0f27399b0e393c0b90f0f1e40c82023ea4d45d22bce7032a5d7b81",
+                "sha256:51cb9476a3987c8967ebab3f0fe144819781fca264f57f89760037a2ea191cb0",
+                "sha256:52596d3d0e8bdf3af43db3e9ba8dcdaac724ba7b5ca3f6358529d56f7a166f8b",
+                "sha256:53194af30d5bad77fcba80e23a1441c71abfb3e01192034f8246e0d8f99528f3",
+                "sha256:5fec2d43a2cc6965edc0bb9e83e1e4b557f76f843a77a2496cbe719583ce8184",
+                "sha256:6c90e11318f0d3c436a42409f2749ee1a115cd8b067d7f14c148f1ce5574d701",
+                "sha256:74d881fc777ebb11c63736622b60cb9e4aee5cace591ce274fb69e582a12a61a",
+                "sha256:7501140f755b725495941b43347ba8a2777407fc7f250d4f5a7d2a1050ba8e82",
+                "sha256:796c9c3c79747146ebd278dbe1e5c5c05dd6b10cc3bcb8389dfdf844f3ead638",
+                "sha256:869a64f53488f40fa5b5b9dcb9e9b2962a66a87dab37790f3fcfb5144b996ef5",
+                "sha256:8963a499849a1fc54b35b1c9f162f4108017b2e6db2c46c1bed93a72262ed083",
+                "sha256:8d0a0725ad7c1a0bcd8d1b437e191107d457e2ec1084b9f190630a4fb1af78e6",
+                "sha256:900fbf7759501bc7807fd6638c947d7a831fc9fdf742dc10f02956ff7220fa90",
+                "sha256:92b017ce34b68a7d67bd6d117e6d443a9bf63a2ecf8567bb3d8c6c7bc5014465",
+                "sha256:970284a88b99673ccb2e4e334cfb38a10aab7cd44f7457564d11898a74b62d0a",
+                "sha256:972c85d205b51e30e59525694670de6a8a89691186012535f9d7dbaa230e42c3",
+                "sha256:9a1ef3b66e38ef8618ce5fdc7bea3d9f45f3624e2a66295eea5e57966c85909e",
+                "sha256:af0e781009aaf59e25c5a678122391cb0f345ac0ec272c7961dc5455e1c40066",
+                "sha256:b6d534e4b2ab35c9f93f46229363e17f63c53ad01330df9f2d6bd1187e5eaacf",
+                "sha256:b7895207b4c843c76a25ab8c1e866261bcfe27bfaa20c192de5190121770672b",
+                "sha256:c0891a6a97b09c1f3e073a890514d5012eb256845c451bd48f7968ef939bf4ae",
+                "sha256:c2723d347ab06e7ddad1a58b2a821218239249a9e4365eaff6649d31180c1669",
+                "sha256:d1f8bf7b90ba55699b3a5e44930e93ff0189aa27186e96071fac7dd0d06a1873",
+                "sha256:d1f9ce122f83b2305592c11d64f181b87153fc2c2bbd3bb4a3dde8303cfb1a6b",
+                "sha256:d314ed732c25d29775e84a960c3c60808b682c08d86602ec2c3008e1202e3bb6",
+                "sha256:d636598c8305e1f90b439dbf4f66437de4a5e3c31fdf47ad29542478c8508bbb",
+                "sha256:deee1077aae10d8fa88cb02c845cfba9b62c55e1183f52f6ae6a2df6a2187160",
+                "sha256:ebe78fe9a0e874362175b02371bdfbee64d8edc42a044253ddf4ee7d3c15212c",
+                "sha256:f030f8873312a16414c0d8e1a1ddff2d3235655a2174e3648b4fa66b3f2f1079",
+                "sha256:f0b278ce10936db1a37e6954e15a3730bea96a0997c26d7fee88e6c396c2086d",
+                "sha256:f11642dddbb0253cc8853254301b51390ba0081750a8ac03f20ea8103f0c56b6"
             ],
             "index": "pypi",
-            "version": "==5.3.1"
-        },
-        "cryptography": {
-            "hashes": [
-                "sha256:0f1212a66329c80d68aeeb39b8a16d54ef57071bf22ff4e521657b27372e327d",
-                "sha256:1e056c28420c072c5e3cb36e2b23ee55e260cb04eee08f702e0edfec3fb51959",
-                "sha256:240f5c21aef0b73f40bb9f78d2caff73186700bf1bc6b94285699aff98cc16c6",
-                "sha256:26965837447f9c82f1855e0bc8bc4fb910240b6e0d16a664bb722df3b5b06873",
-                "sha256:37340614f8a5d2fb9aeea67fd159bfe4f5f4ed535b1090ce8ec428b2f15a11f2",
-                "sha256:3d10de8116d25649631977cb37da6cbdd2d6fa0e0281d014a5b7d337255ca713",
-                "sha256:3d8427734c781ea5f1b41d6589c293089704d4759e34597dce91014ac125aad1",
-                "sha256:7ec5d3b029f5fa2b179325908b9cd93db28ab7b85bb6c1db56b10e0b54235177",
-                "sha256:8e56e16617872b0957d1c9742a3f94b43533447fd78321514abbe7db216aa250",
-                "sha256:de4e5f7f68220d92b7637fc99847475b59154b7a1b3868fb7385337af54ac9ca",
-                "sha256:eb8cc2afe8b05acbd84a43905832ec78e7b3873fb124ca190f574dca7389a87d",
-                "sha256:ee77aa129f481be46f8d92a1a7db57269a2f23052d5f2433b4621bb457081cc9"
-            ],
-            "version": "==3.4.7"
+            "version": "==5.5"
         },
         "distlib": {
             "hashes": [
@@ -594,6 +563,7 @@
         "docutils": {
             "hashes": [
                 "sha256:54a349c622ff31c91cbec43b0b512f113b5b24daf00e2ea530bb1bd9aac14849",
+                "sha256:ba4584f9107571ced0d2c7f56a5499c696215ba90797849c92d395979da68521",
                 "sha256:d2ddba74835cb090a1b627d3de4e7835c628d07ee461f7b4480f51af2fe4d448"
             ],
             "index": "pypi",
@@ -608,32 +578,34 @@
         },
         "flake8": {
             "hashes": [
-                "sha256:749dbbd6bfd0cf1318af27bf97a14e28e5ff548ef8e5b1566ccfb25a11e7c839",
-                "sha256:aadae8761ec651813c24be05c6f7b4680857ef6afaae4651a4eccaef97ce6c3b"
+                "sha256:1aa8990be1e689d96c745c5682b687ea49f2e05a443aff1f8251092b0014e378",
+                "sha256:3b9f848952dddccf635be78098ca75010f073bfe14d2c6bda867154bea728d2a"
             ],
             "index": "pypi",
-            "version": "==3.8.4"
+            "version": "==3.9.1"
         },
         "flake8-bugbear": {
             "hashes": [
-                "sha256:528020129fea2dea33a466b9d64ab650aa3e5f9ffc788b70ea4bc6cf18283538",
-                "sha256:f35b8135ece7a014bc0aee5b5d485334ac30a6da48494998cc1fabf7ec70d703"
+                "sha256:2346c81f889955b39e4a368eb7d508de723d9de05716c287dc860a4073dc57e7",
+                "sha256:4f305dca96be62bf732a218fe6f1825472a621d3452c5b994d8f89dae21dbafa"
             ],
             "index": "pypi",
-            "version": "==20.11.1"
+            "version": "==21.4.3"
         },
         "identify": {
             "hashes": [
-                "sha256:43cb1965e84cdd247e875dec6d13332ef5be355ddc16776396d98089b9053d87",
-                "sha256:c7c0f590526008911ccc5ceee6ed7b085cbc92f7b6591d0ee5913a130ad64034"
+                "sha256:9bcc312d4e2fa96c7abebcdfb1119563b511b5e3985ac52f60d9116277865b2e",
+                "sha256:ad9f3fa0c2316618dc4d840f627d474ab6de106392a4f00221820200f490f5a8"
             ],
-            "version": "==2.2.2"
+            "markers": "python_full_version >= '3.6.1'",
+            "version": "==2.2.4"
         },
         "idna": {
             "hashes": [
                 "sha256:5205d03e7bcbb919cc9c19885f9920d622ca52448306f2377daede5cf3faac16",
                 "sha256:c5b02147e01ea9920e6b0a3f1f7bb833612d507592c837a6c49552768f4054e1"
             ],
+            "markers": "python_version >= '3.4'",
             "version": "==3.1"
         },
         "imagesize": {
@@ -641,28 +613,23 @@
                 "sha256:6965f19a6a2039c7d48bca7dba2473069ff854c36ae6f19d2cde309d998228a1",
                 "sha256:b1f6b5a4eab1f73479a50fb79fcf729514a900c341d8503d62a62dbc4127a2b1"
             ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==1.2.0"
         },
         "importlib-metadata": {
             "hashes": [
-                "sha256:c9db46394197244adf2f0b08ec5bc3cf16757e9590b02af1fca085c16c0d600a",
-                "sha256:d2d46ef77ffc85cbf7dac7e81dd663fde71c45326131bea8033b9bad42268ebe"
-            ],
-            "version": "==3.10.0"
-        },
-        "jeepney": {
-            "hashes": [
-                "sha256:7d59b6622675ca9e993a6bd38de845051d315f8b0c72cca3aef733a20b648657",
-                "sha256:aec56c0eb1691a841795111e184e13cad504f7703b9a64f63020816afa79a8ae"
+                "sha256:8c501196e49fb9df5df43833bdb1e4328f64847763ec8a50703148b73784d581",
+                "sha256:d7eb1dea6d6a6086f8be21784cc9e3bcfa55872b52309bc5fad53a8ea444465d"
             ],
-            "markers": "sys_platform == 'linux'",
-            "version": "==0.6.0"
+            "markers": "python_version >= '3.6'",
+            "version": "==4.0.1"
         },
         "jinja2": {
             "hashes": [
                 "sha256:03e47ad063331dd6a3f04a43eddca8a966a26ba0c5b7207a9a9e4e08f1b29419",
                 "sha256:a6d58433de0ae800347cab1fa3043cebbabe8baa9d29e668f1c768cb87a333c6"
             ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
             "version": "==2.11.3"
         },
         "keyring": {
@@ -670,6 +637,7 @@
                 "sha256:045703609dd3fccfcdb27da201684278823b72af515aedec1a8515719a038cb8",
                 "sha256:8f607d7d1cc502c43a932a275a56fe47db50271904513a379d39df1af277ac48"
             ],
+            "markers": "python_version >= '3.6'",
             "version": "==23.0.1"
         },
         "markupsafe": {
@@ -727,6 +695,7 @@
                 "sha256:e8313f01ba26fbbe36c7be1966a7b7424942f670f38e666995b88d012765b9be",
                 "sha256:feb7b34d6325451ef96bc0e36e1a6c0c1c64bc1fbec4b854f4529e51887b1621"
             ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==1.1.1"
         },
         "mccabe": {
@@ -776,27 +745,36 @@
                 "sha256:f21756997ad8ef815d8ef3d34edd98804ab5ea337feedcd62fb52d22bf531281",
                 "sha256:fc13a9524bc18b6fb6e0dbec3533ba0496bbed167c56d0aabefd965584557d80"
             ],
+            "markers": "python_version >= '3.6'",
             "version": "==5.1.0"
         },
         "mypy": {
             "hashes": [
-                "sha256:0a0d102247c16ce93c97066443d11e2d36e6cc2a32d8ccc1f705268970479324",
-                "sha256:0d34d6b122597d48a36d6c59e35341f410d4abfa771d96d04ae2c468dd201abc",
-                "sha256:2170492030f6faa537647d29945786d297e4862765f0b4ac5930ff62e300d802",
-                "sha256:2842d4fbd1b12ab422346376aad03ff5d0805b706102e475e962370f874a5122",
-                "sha256:2b21ba45ad9ef2e2eb88ce4aeadd0112d0f5026418324176fd494a6824b74975",
-                "sha256:72060bf64f290fb629bd4a67c707a66fd88ca26e413a91384b18db3876e57ed7",
-                "sha256:af4e9ff1834e565f1baa74ccf7ae2564ae38c8df2a85b057af1dbbc958eb6666",
-                "sha256:bd03b3cf666bff8d710d633d1c56ab7facbdc204d567715cb3b9f85c6e94f669",
-                "sha256:c614194e01c85bb2e551c421397e49afb2872c88b5830e3554f0519f9fb1c178",
-                "sha256:cf4e7bf7f1214826cf7333627cb2547c0db7e3078723227820d0a2490f117a01",
-                "sha256:da56dedcd7cd502ccd3c5dddc656cb36113dd793ad466e894574125945653cea",
-                "sha256:e86bdace26c5fe9cf8cb735e7cedfe7850ad92b327ac5d797c656717d2ca66de",
-                "sha256:e97e9c13d67fbe524be17e4d8025d51a7dca38f90de2e462243ab8ed8a9178d1",
-                "sha256:eea260feb1830a627fb526d22fbb426b750d9f5a47b624e8d5e7e004359b219c"
+                "sha256:0d0a87c0e7e3a9becdfbe936c981d32e5ee0ccda3e0f07e1ef2c3d1a817cf73e",
+                "sha256:25adde9b862f8f9aac9d2d11971f226bd4c8fbaa89fb76bdadb267ef22d10064",
+                "sha256:28fb5479c494b1bab244620685e2eb3c3f988d71fd5d64cc753195e8ed53df7c",
+                "sha256:2f9b3407c58347a452fc0736861593e105139b905cca7d097e413453a1d650b4",
+                "sha256:33f159443db0829d16f0a8d83d94df3109bb6dd801975fe86bacb9bf71628e97",
+                "sha256:3f2aca7f68580dc2508289c729bd49ee929a436208d2b2b6aab15745a70a57df",
+                "sha256:499c798053cdebcaa916eef8cd733e5584b5909f789de856b482cd7d069bdad8",
+                "sha256:4eec37370483331d13514c3f55f446fc5248d6373e7029a29ecb7b7494851e7a",
+                "sha256:552a815579aa1e995f39fd05dde6cd378e191b063f031f2acfe73ce9fb7f9e56",
+                "sha256:5873888fff1c7cf5b71efbe80e0e73153fe9212fafdf8e44adfe4c20ec9f82d7",
+                "sha256:61a3d5b97955422964be6b3baf05ff2ce7f26f52c85dd88db11d5e03e146a3a6",
+                "sha256:674e822aa665b9fd75130c6c5f5ed9564a38c6cea6a6432ce47eafb68ee578c5",
+                "sha256:7ce3175801d0ae5fdfa79b4f0cfed08807af4d075b402b7e294e6aa72af9aa2a",
+                "sha256:9743c91088d396c1a5a3c9978354b61b0382b4e3c440ce83cf77994a43e8c521",
+                "sha256:9f94aac67a2045ec719ffe6111df543bac7874cee01f41928f6969756e030564",
+                "sha256:a26f8ec704e5a7423c8824d425086705e381b4f1dfdef6e3a1edab7ba174ec49",
+                "sha256:abf7e0c3cf117c44d9285cc6128856106183938c68fd4944763003decdcfeb66",
+                "sha256:b09669bcda124e83708f34a94606e01b614fa71931d356c1f1a5297ba11f110a",
+                "sha256:cd07039aa5df222037005b08fbbfd69b3ab0b0bd7a07d7906de75ae52c4e3119",
+                "sha256:d23e0ea196702d918b60c8288561e722bf437d82cb7ef2edcd98cfa38905d506",
+                "sha256:d65cc1df038ef55a99e617431f0553cd77763869eebdf9042403e16089fe746c",
+                "sha256:d7da2e1d5f558c37d6e8c1246f1aec1e7349e4913d8fb3cb289a35de573fe2eb"
             ],
             "index": "pypi",
-            "version": "==0.790"
+            "version": "==0.812"
         },
         "mypy-extensions": {
             "hashes": [
@@ -808,16 +786,17 @@
         },
         "nodeenv": {
             "hashes": [
-                "sha256:5304d424c529c997bc888453aeaa6362d242b6b4631e90f3d4bf1b290f1c84a9",
-                "sha256:ab45090ae383b716c4ef89e690c41ff8c2b257b85b309f01f3654df3d084bd7c"
+                "sha256:3ef13ff90291ba2a4a7a4ff9a979b63ffdd00a464dbe04acf0ea6471517a4c2b",
+                "sha256:621e6b7076565ddcacd2db0294c0381e01fd28945ab36bcf00f41c5daf63bef7"
             ],
-            "version": "==1.5.0"
+            "version": "==1.6.0"
         },
         "packaging": {
             "hashes": [
                 "sha256:5b327ac1320dc863dca72f4514ecc086f31186744b84a230374cc1fd776feae5",
                 "sha256:67714da7f7bc052e064859c05c595155bd1ee9f69f76557e21f051443c20947a"
             ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==20.9"
         },
         "pathspec": {
@@ -837,38 +816,34 @@
         },
         "pre-commit": {
             "hashes": [
-                "sha256:6c86d977d00ddc8a60d68eec19f51ef212d9462937acf3ea37c7adec32284ac0",
-                "sha256:ee784c11953e6d8badb97d19bc46b997a3a9eded849881ec587accd8608d74a4"
+                "sha256:70c5ec1f30406250b706eda35e868b87e3e4ba099af8787e3e8b4b01e84f4712",
+                "sha256:900d3c7e1bf4cf0374bb2893c24c23304952181405b4d88c9c40b72bda1bb8a9"
             ],
             "index": "pypi",
-            "version": "==2.9.3"
+            "version": "==2.12.1"
         },
         "pycodestyle": {
             "hashes": [
-                "sha256:2295e7b2f6b5bd100585ebcb1f616591b652db8a741695b3d8f5d28bdc934367",
-                "sha256:c58a7d2815e0e8d7972bf1803331fb0152f867bd89adf8a01dfd55085434192e"
+                "sha256:514f76d918fcc0b55c6680472f0a37970994e07bbb80725808c17089be302068",
+                "sha256:c389c1d06bf7904078ca03399a4816f974a1d590090fecea0c63ec26ebaf1cef"
             ],
-            "version": "==2.6.0"
-        },
-        "pycparser": {
-            "hashes": [
-                "sha256:2d475327684562c3a96cc71adf7dc8c4f0565175cf86b6d7a404ff4c771f15f0",
-                "sha256:7582ad22678f0fcd81102833f60ef8d0e57288b6b5fb00323d101be910e35705"
-            ],
-            "version": "==2.20"
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
+            "version": "==2.7.0"
         },
         "pyflakes": {
             "hashes": [
-                "sha256:0d94e0e05a19e57a99444b6ddcf9a6eb2e5c68d3ca1e98e90707af8152c90a92",
-                "sha256:35b2d75ee967ea93b55750aa9edbbf72813e06a66ba54438df2cfac9e3c27fc8"
+                "sha256:7893783d01b8a89811dd72d7dfd4d84ff098e5eed95cfa8905b22bbffe52efc3",
+                "sha256:f5bc8ecabc05bb9d291eb5203d6810b49040f6ff446a756326104746cc00c1db"
             ],
-            "version": "==2.2.0"
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
+            "version": "==2.3.1"
         },
         "pygments": {
             "hashes": [
                 "sha256:2656e1a6edcdabf4275f9a3640db59fd5de107d88e8663c5d4e9a0fa62f77f94",
                 "sha256:534ef71d539ae97d4c3a4cf7d6f110f214b0e687e92f9cb9d2a3b0d3101289c8"
             ],
+            "markers": "python_version >= '3.5'",
             "version": "==2.8.1"
         },
         "pyparsing": {
@@ -876,6 +851,7 @@
                 "sha256:c203ec8783bf771a155b207279b9bccb8dea02d8f0c9e5f8ead507bc3246ecc1",
                 "sha256:ef9d7589ef3c200abe66653d3f1ab1033c3c419ae9b9bdb1240a85b024efc88b"
             ],
+            "markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==2.4.7"
         },
         "pytz": {
@@ -917,15 +893,16 @@
                 "sha256:fdc842473cd33f45ff6bce46aea678a54e3d21f1b61a7750ce3c498eedfe25d6",
                 "sha256:fe69978f3f768926cfa37b867e3843918e012cf83f680806599ddce33c2c68b0"
             ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4, 3.5'",
             "version": "==5.4.1"
         },
         "readme-renderer": {
             "hashes": [
-                "sha256:267854ac3b1530633c2394ead828afcd060fc273217c42ac36b6be9c42cd9a9d",
-                "sha256:6b7e5aa59210a40de72eb79931491eaf46fefca2952b9181268bd7c7c65c260a"
+                "sha256:63b4075c6698fcfa78e584930f07f39e05d46f3ec97f65006e430b595ca6348c",
+                "sha256:92fd5ac2bf8677f310f3303aa4bce5b9d5f9f2094ab98c29f13791d7b805a3db"
             ],
             "index": "pypi",
-            "version": "==28.0"
+            "version": "==29.0"
         },
         "recommonmark": {
             "hashes": [
@@ -937,56 +914,57 @@
         },
         "regex": {
             "hashes": [
-                "sha256:02951b7dacb123d8ea6da44fe45ddd084aa6777d4b2454fa0da61d569c6fa538",
-                "sha256:0d08e71e70c0237883d0bef12cad5145b84c3705e9c6a588b2a9c7080e5af2a4",
-                "sha256:1862a9d9194fae76a7aaf0150d5f2a8ec1da89e8b55890b1786b8f88a0f619dc",
-                "sha256:1ab79fcb02b930de09c76d024d279686ec5d532eb814fd0ed1e0051eb8bd2daa",
-                "sha256:1fa7ee9c2a0e30405e21031d07d7ba8617bc590d391adfc2b7f1e8b99f46f444",
-                "sha256:262c6825b309e6485ec2493ffc7e62a13cf13fb2a8b6d212f72bd53ad34118f1",
-                "sha256:2a11a3e90bd9901d70a5b31d7dd85114755a581a5da3fc996abfefa48aee78af",
-                "sha256:2c99e97d388cd0a8d30f7c514d67887d8021541b875baf09791a3baad48bb4f8",
-                "sha256:3128e30d83f2e70b0bed9b2a34e92707d0877e460b402faca908c6667092ada9",
-                "sha256:38c8fd190db64f513fe4e1baa59fed086ae71fa45083b6936b52d34df8f86a88",
-                "sha256:3bddc701bdd1efa0d5264d2649588cbfda549b2899dc8d50417e47a82e1387ba",
-                "sha256:4902e6aa086cbb224241adbc2f06235927d5cdacffb2425c73e6570e8d862364",
-                "sha256:49cae022fa13f09be91b2c880e58e14b6da5d10639ed45ca69b85faf039f7a4e",
-                "sha256:56e01daca75eae420bce184edd8bb341c8eebb19dd3bce7266332258f9fb9dd7",
-                "sha256:5862975b45d451b6db51c2e654990c1820523a5b07100fc6903e9c86575202a0",
-                "sha256:6a8ce43923c518c24a2579fda49f093f1397dad5d18346211e46f134fc624e31",
-                "sha256:6c54ce4b5d61a7129bad5c5dc279e222afd00e721bf92f9ef09e4fae28755683",
-                "sha256:6e4b08c6f8daca7d8f07c8d24e4331ae7953333dbd09c648ed6ebd24db5a10ee",
-                "sha256:717881211f46de3ab130b58ec0908267961fadc06e44f974466d1887f865bd5b",
-                "sha256:749078d1eb89484db5f34b4012092ad14b327944ee7f1c4f74d6279a6e4d1884",
-                "sha256:7913bd25f4ab274ba37bc97ad0e21c31004224ccb02765ad984eef43e04acc6c",
-                "sha256:7a25fcbeae08f96a754b45bdc050e1fb94b95cab046bf56b016c25e9ab127b3e",
-                "sha256:83d6b356e116ca119db8e7c6fc2983289d87b27b3fac238cfe5dca529d884562",
-                "sha256:8b882a78c320478b12ff024e81dc7d43c1462aa4a3341c754ee65d857a521f85",
-                "sha256:8f6a2229e8ad946e36815f2a03386bb8353d4bde368fdf8ca5f0cb97264d3b5c",
-                "sha256:9801c4c1d9ae6a70aeb2128e5b4b68c45d4f0af0d1535500884d644fa9b768c6",
-                "sha256:a15f64ae3a027b64496a71ab1f722355e570c3fac5ba2801cafce846bf5af01d",
-                "sha256:a3d748383762e56337c39ab35c6ed4deb88df5326f97a38946ddd19028ecce6b",
-                "sha256:a63f1a07932c9686d2d416fb295ec2c01ab246e89b4d58e5fa468089cab44b70",
-                "sha256:b2b1a5ddae3677d89b686e5c625fc5547c6e492bd755b520de5332773a8af06b",
-                "sha256:b2f4007bff007c96a173e24dcda236e5e83bde4358a557f9ccf5e014439eae4b",
-                "sha256:baf378ba6151f6e272824b86a774326f692bc2ef4cc5ce8d5bc76e38c813a55f",
-                "sha256:bafb01b4688833e099d79e7efd23f99172f501a15c44f21ea2118681473fdba0",
-                "sha256:bba349276b126947b014e50ab3316c027cac1495992f10e5682dc677b3dfa0c5",
-                "sha256:c084582d4215593f2f1d28b65d2a2f3aceff8342aa85afd7be23a9cad74a0de5",
-                "sha256:d1ebb090a426db66dd80df8ca85adc4abfcbad8a7c2e9a5ec7513ede522e0a8f",
-                "sha256:d2d8ce12b7c12c87e41123997ebaf1a5767a5be3ec545f64675388970f415e2e",
-                "sha256:e32f5f3d1b1c663af7f9c4c1e72e6ffe9a78c03a31e149259f531e0fed826512",
-                "sha256:e3faaf10a0d1e8e23a9b51d1900b72e1635c2d5b0e1bea1c18022486a8e2e52d",
-                "sha256:f7d29a6fc4760300f86ae329e3b6ca28ea9c20823df123a2ea8693e967b29917",
-                "sha256:f8f295db00ef5f8bae530fc39af0b40486ca6068733fb860b42115052206466f"
+                "sha256:01afaf2ec48e196ba91b37451aa353cb7eda77efe518e481707e0515025f0cd5",
+                "sha256:11d773d75fa650cd36f68d7ca936e3c7afaae41b863b8c387a22aaa78d3c5c79",
+                "sha256:18c071c3eb09c30a264879f0d310d37fe5d3a3111662438889ae2eb6fc570c31",
+                "sha256:1e1c20e29358165242928c2de1482fb2cf4ea54a6a6dea2bd7a0e0d8ee321500",
+                "sha256:281d2fd05555079448537fe108d79eb031b403dac622621c78944c235f3fcf11",
+                "sha256:314d66636c494ed9c148a42731b3834496cc9a2c4251b1661e40936814542b14",
+                "sha256:32e65442138b7b76dd8173ffa2cf67356b7bc1768851dded39a7a13bf9223da3",
+                "sha256:339456e7d8c06dd36a22e451d58ef72cef293112b559010db3d054d5560ef439",
+                "sha256:3916d08be28a1149fb97f7728fca1f7c15d309a9f9682d89d79db75d5e52091c",
+                "sha256:3a9cd17e6e5c7eb328517969e0cb0c3d31fd329298dd0c04af99ebf42e904f82",
+                "sha256:47bf5bf60cf04d72bf6055ae5927a0bd9016096bf3d742fa50d9bf9f45aa0711",
+                "sha256:4c46e22a0933dd783467cf32b3516299fb98cfebd895817d685130cc50cd1093",
+                "sha256:4c557a7b470908b1712fe27fb1ef20772b78079808c87d20a90d051660b1d69a",
+                "sha256:52ba3d3f9b942c49d7e4bc105bb28551c44065f139a65062ab7912bef10c9afb",
+                "sha256:563085e55b0d4fb8f746f6a335893bda5c2cef43b2f0258fe1020ab1dd874df8",
+                "sha256:598585c9f0af8374c28edd609eb291b5726d7cbce16be6a8b95aa074d252ee17",
+                "sha256:619d71c59a78b84d7f18891fe914446d07edd48dc8328c8e149cbe0929b4e000",
+                "sha256:67bdb9702427ceddc6ef3dc382455e90f785af4c13d495f9626861763ee13f9d",
+                "sha256:6d1b01031dedf2503631d0903cb563743f397ccaf6607a5e3b19a3d76fc10480",
+                "sha256:741a9647fcf2e45f3a1cf0e24f5e17febf3efe8d4ba1281dcc3aa0459ef424dc",
+                "sha256:7c2a1af393fcc09e898beba5dd59196edaa3116191cc7257f9224beaed3e1aa0",
+                "sha256:7d9884d86dd4dd489e981d94a65cd30d6f07203d90e98f6f657f05170f6324c9",
+                "sha256:90f11ff637fe8798933fb29f5ae1148c978cccb0452005bf4c69e13db951e765",
+                "sha256:919859aa909429fb5aa9cf8807f6045592c85ef56fdd30a9a3747e513db2536e",
+                "sha256:96fcd1888ab4d03adfc9303a7b3c0bd78c5412b2bfbe76db5b56d9eae004907a",
+                "sha256:97f29f57d5b84e73fbaf99ab3e26134e6687348e95ef6b48cfd2c06807005a07",
+                "sha256:980d7be47c84979d9136328d882f67ec5e50008681d94ecc8afa8a65ed1f4a6f",
+                "sha256:a91aa8619b23b79bcbeb37abe286f2f408d2f2d6f29a17237afda55bb54e7aac",
+                "sha256:ade17eb5d643b7fead300a1641e9f45401c98eee23763e9ed66a43f92f20b4a7",
+                "sha256:b9c3db21af35e3b3c05764461b262d6f05bbca08a71a7849fd79d47ba7bc33ed",
+                "sha256:bd28bc2e3a772acbb07787c6308e00d9626ff89e3bfcdebe87fa5afbfdedf968",
+                "sha256:bf5824bfac591ddb2c1f0a5f4ab72da28994548c708d2191e3b87dd207eb3ad7",
+                "sha256:c0502c0fadef0d23b128605d69b58edb2c681c25d44574fc673b0e52dce71ee2",
+                "sha256:c38c71df845e2aabb7fb0b920d11a1b5ac8526005e533a8920aea97efb8ec6a4",
+                "sha256:ce15b6d103daff8e9fee13cf7f0add05245a05d866e73926c358e871221eae87",
+                "sha256:d3029c340cfbb3ac0a71798100ccc13b97dddf373a4ae56b6a72cf70dfd53bc8",
+                "sha256:e512d8ef5ad7b898cdb2d8ee1cb09a8339e4f8be706d27eaa180c2f177248a10",
+                "sha256:e8e5b509d5c2ff12f8418006d5a90e9436766133b564db0abaec92fd27fcee29",
+                "sha256:ee54ff27bf0afaf4c3b3a62bcd016c12c3fdb4ec4f413391a90bd38bc3624605",
+                "sha256:fa4537fb4a98fe8fde99626e4681cc644bdcf2a795038533f9f711513a862ae6",
+                "sha256:fd45ff9293d9274c5008a2054ecef86a9bfe819a67c7be1afb65e69b405b3042"
             ],
             "index": "pypi",
-            "version": "==2020.11.13"
+            "version": "==2021.4.4"
         },
         "requests": {
             "hashes": [
                 "sha256:27973dd4a904a4f13b263a19c866c13b92a39ed1c964655f025f3f8d3d75b804",
                 "sha256:c210084e36a42ae6b9219e00e48287def368a26d03a048ddad7bfee44f75871e"
             ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
             "version": "==2.25.1"
         },
         "requests-toolbelt": {
@@ -1003,27 +981,20 @@
             ],
             "version": "==1.4.0"
         },
-        "secretstorage": {
-            "hashes": [
-                "sha256:422d82c36172d88d6a0ed5afdec956514b189ddbfb72fefab0c8a1cee4eaf71f",
-                "sha256:fd666c51a6bf200643495a04abb261f83229dcb6fd8472ec393df7ffc8b6f195"
-            ],
-            "markers": "sys_platform == 'linux'",
-            "version": "==3.3.1"
-        },
         "setuptools-scm": {
             "hashes": [
-                "sha256:62fa535edb31ece9fa65dc9dcb3056145b8020c8c26c0ef1018aef33db95c40d",
-                "sha256:c85b6b46d0edd40d2301038cdea96bb6adc14d62ef943e75afb08b3e7bcf142a"
+                "sha256:c3bd5f701c8def44a5c0bfe8d407bef3f80342217ef3492b951f3777bd2d915c",
+                "sha256:d1925a69cb07e9b29416a275b9fadb009a23c148ace905b2fb220649a6c18e92"
             ],
-            "index": "pypi",
-            "version": "==5.0.1"
+            "markers": "python_version >= '3.6'",
+            "version": "==6.0.1"
         },
         "six": {
             "hashes": [
                 "sha256:30639c035cdb23534cd4aa2dd52c3bf48f06e5f4a941509c8bafd8ce11080259",
                 "sha256:8b74bedcbbbaca38ff6d7491d76f2b06b3592611af620f8426e82dddb04a5ced"
             ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==1.15.0"
         },
         "snowballstemmer": {
@@ -1035,17 +1006,18 @@
         },
         "sphinx": {
             "hashes": [
-                "sha256:aeef652b14629431c82d3fe994ce39ead65b3fe87cf41b9a3714168ff8b83376",
-                "sha256:e450cb205ff8924611085183bf1353da26802ae73d9251a8fcdf220a8f8712ef"
+                "sha256:19010b7b9fa0dc7756a6e105b2aacd3a80f798af3c25c273be64d7beeb482cb1",
+                "sha256:2320d4e994a191f4b4be27da514e46b3d6b420f2ff895d064f52415d342461e8"
             ],
             "index": "pypi",
-            "version": "==3.4.1"
+            "version": "==3.5.4"
         },
         "sphinxcontrib-applehelp": {
             "hashes": [
                 "sha256:806111e5e962be97c29ec4c1e7fe277bfd19e9652fb1a4392105b43e01af885a",
                 "sha256:a072735ec80e7675e3f432fcae8610ecf509c5f1869d17e2eecff44389cdbc58"
             ],
+            "markers": "python_version >= '3.5'",
             "version": "==1.0.2"
         },
         "sphinxcontrib-devhelp": {
@@ -1053,6 +1025,7 @@
                 "sha256:8165223f9a335cc1af7ffe1ed31d2871f325254c0423bc0c4c7cd1c1e4734a2e",
                 "sha256:ff7f1afa7b9642e7060379360a67e9c41e8f3121f2ce9164266f61b9f4b338e4"
             ],
+            "markers": "python_version >= '3.5'",
             "version": "==1.0.2"
         },
         "sphinxcontrib-htmlhelp": {
@@ -1060,6 +1033,7 @@
                 "sha256:3c0bc24a2c41e340ac37c85ced6dafc879ab485c095b1d65d2461ac2f7cca86f",
                 "sha256:e8f5bb7e31b2dbb25b9cc435c8ab7a79787ebf7f906155729338f3156d93659b"
             ],
+            "markers": "python_version >= '3.5'",
             "version": "==1.0.3"
         },
         "sphinxcontrib-jsmath": {
@@ -1067,6 +1041,7 @@
                 "sha256:2ec2eaebfb78f3f2078e73666b1415417a116cc848b72e5172e596c871103178",
                 "sha256:a9925e4a4587247ed2191a22df5f6970656cb8ca2bd6284309578f2153e0c4b8"
             ],
+            "markers": "python_version >= '3.5'",
             "version": "==1.0.1"
         },
         "sphinxcontrib-qthelp": {
@@ -1074,6 +1049,7 @@
                 "sha256:4c33767ee058b70dba89a6fc5c1892c0d57a54be67ddd3e7875a18d14cba5a72",
                 "sha256:bd9fc24bcb748a8d51fd4ecaade681350aa63009a347a8c14e637895444dfab6"
             ],
+            "markers": "python_version >= '3.5'",
             "version": "==1.0.3"
         },
         "sphinxcontrib-serializinghtml": {
@@ -1081,6 +1057,7 @@
                 "sha256:eaa0eccc86e982a9b939b2b82d12cc5d013385ba5eadcc7e4fed23f4405f77bc",
                 "sha256:f242a81d423f59617a8e5cf16f5d4d74e28ee9a66f9e5b637a18082991db5a9a"
             ],
+            "markers": "python_version >= '3.5'",
             "version": "==1.1.4"
         },
         "toml": {
@@ -1096,15 +1073,16 @@
                 "sha256:daec693491c52e9498632dfbe9ccfc4882a557f5fa08982db1b4d3adbe0887c3",
                 "sha256:ebdebdb95e3477ceea267decfc0784859aa3df3e27e22d23b83e9b272bf157ae"
             ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==4.60.0"
         },
         "twine": {
             "hashes": [
-                "sha256:2f6942ec2a17417e19d2dd372fc4faa424c87ee9ce49b4e20c427eb00a0f3f41",
-                "sha256:fcffa8fc37e8083a5be0728371f299598870ee1eccc94e9a25cef7b1dcfa8297"
+                "sha256:16f706f2f1687d7ce30e7effceee40ed0a09b7c33b9abb5ef6434e5551565d83",
+                "sha256:a56c985264b991dc8a8f4234eb80c5af87fa8080d0c224ad8f2cd05a2c22e83b"
             ],
             "index": "pypi",
-            "version": "==3.3.0"
+            "version": "==3.4.1"
         },
         "typed-ast": {
             "hashes": [
@@ -1149,22 +1127,25 @@
                 "sha256:dafc7639cde7f1b6e1acc0f457842a83e722ccca8eef5270af2d74792619a89f"
             ],
             "index": "pypi",
-            "version": "==3.7.4.3"
+            "python_version <": "3.8",
+            "version": "==3.7.4.3",
+            "version >=": "3.7.4"
         },
         "urllib3": {
             "hashes": [
                 "sha256:2f4da4594db7e1e110a944bb1b551fdf4e6c136ad42e4234131391e21eb5b0df",
                 "sha256:e7b021f7241115872f92f43c6508082facffbd1c048e3c6e2bb9c2a157e28937"
             ],
-            "index": "pypi",
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4' and python_version < '4'",
             "version": "==1.26.4"
         },
         "virtualenv": {
             "hashes": [
-                "sha256:49ec4eb4c224c6f7dd81bb6d0a28a09ecae5894f4e593c89b0db0885f565a107",
-                "sha256:83f95875d382c7abafe06bd2a4cdd1b363e1bb77e02f155ebe8ac082a916b37c"
+                "sha256:09c61377ef072f43568207dc8e46ddeac6bcdcaf288d49011bda0e7f4d38c4a2",
+                "sha256:a935126db63128861987a7d5d30e23e8ec045a73840eeccb467c148514e29535"
             ],
-            "version": "==20.4.3"
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
+            "version": "==20.4.4"
         },
         "webencodings": {
             "hashes": [
@@ -1221,6 +1202,7 @@
                 "sha256:f0b059678fd549c66b89bed03efcabb009075bd131c248ecdf087bdb6faba24a",
                 "sha256:fcbb48a93e8699eae920f8d92f7160c03567b421bc17362a9ffbbd706a816f71"
             ],
+            "markers": "python_version >= '3.6'",
             "version": "==1.6.3"
         },
         "zipp": {
@@ -1228,6 +1210,7 @@
                 "sha256:3607921face881ba3e026887d8150cca609d517579abe052ac81fc5aeffdbd76",
                 "sha256:51cb66cc54621609dd593d1787f286ee42a5c0adbb4b29abea5a63edc3e03098"
             ],
+            "markers": "python_version >= '3.6'",
             "version": "==3.4.1"
         }
     }
diff --git a/setup.py b/setup.py
index 856c7fadb0c..0928c63afc2 100644
--- a/setup.py
+++ b/setup.py
@@ -73,7 +73,7 @@ def get_long_description() -> str:
         "toml>=0.10.1",
         "typed-ast>=1.4.2; python_version < '3.8'",
         "regex>=2020.1.8",
-        "pathspec>=0.6, <1",
+        "pathspec>=0.8.1, <1",
         "dataclasses>=0.6; python_version < '3.7'",
         "typing_extensions>=3.7.4; python_version < '3.8'",
         "mypy_extensions>=0.4.3",

From b55ea63ff4858109fe4606a6caafb03fda946743 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Mon, 26 Apr 2021 16:26:43 -0400
Subject: [PATCH 0154/1034] Stop stripping parens in even more illegal spots
 (#2148)

We're only fixing them so fuzzers don't yell at us when we break "valid"
code. I mean "valid" because some of the examples aren't even accepted by
Python.
---
 src/black/__init__.py                      |  3 +++
 tests/data/pep_572_do_not_remove_parens.py | 21 +++++++++++++++++++++
 tests/data/pep_572_remove_parens.py        | 15 +++++++++++++++
 tests/test_black.py                        |  8 ++++++++
 4 files changed, 47 insertions(+)
 create mode 100644 tests/data/pep_572_do_not_remove_parens.py

diff --git a/src/black/__init__.py b/src/black/__init__.py
index 051de5d13df..015ca415f1c 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -5624,6 +5624,9 @@ def maybe_make_parens_invisible_in_atom(node: LN, parent: LN) -> bool:
             syms.expr_stmt,
             syms.assert_stmt,
             syms.return_stmt,
+            # these ones aren't useful to end users, but they do please fuzzers
+            syms.for_stmt,
+            syms.del_stmt,
         ]:
             return False
 
diff --git a/tests/data/pep_572_do_not_remove_parens.py b/tests/data/pep_572_do_not_remove_parens.py
new file mode 100644
index 00000000000..20e80a69377
--- /dev/null
+++ b/tests/data/pep_572_do_not_remove_parens.py
@@ -0,0 +1,21 @@
+# Most of the following examples are really dumb, some of them aren't even accepted by Python,
+# we're fixing them only so fuzzers (which follow the grammar which actually allows these
+# examples matter of fact!) don't yell at us :p
+
+del (a := [1])
+
+try:
+    pass
+except (a := 1) as (b := why_does_this_exist):
+    pass
+
+for (z := 124) in (x := -124):
+    pass
+
+with (y := [3, 2, 1]) as (funfunfun := indeed):
+    pass
+
+
+@(please := stop)
+def sigh():
+    pass
diff --git a/tests/data/pep_572_remove_parens.py b/tests/data/pep_572_remove_parens.py
index 9a804859a09..9718d95b499 100644
--- a/tests/data/pep_572_remove_parens.py
+++ b/tests/data/pep_572_remove_parens.py
@@ -33,6 +33,9 @@ def foo2(answer: (p := 42) = 5):
 
 lambda: (x := 1)
 
+a[(x := 12)]
+a[:(x := 13)]
+
 # we don't touch expressions in f-strings but if we do one day, don't break 'em
 f'{(x:=10)}'
 
@@ -43,6 +46,10 @@ def a():
     yield (a := 2)
     raise (c := 3)
 
+def this_is_so_dumb() -> (please := no):
+    pass
+
+
 # output
 if foo := 0:
     pass
@@ -79,6 +86,9 @@ def foo2(answer: (p := 42) = 5):
 
 lambda: (x := 1)
 
+a[(x := 12)]
+a[:(x := 13)]
+
 # we don't touch expressions in f-strings but if we do one day, don't break 'em
 f"{(x:=10)}"
 
@@ -88,3 +98,8 @@ def a():
     await (b := 1)
     yield (a := 2)
     raise (c := 3)
+
+
+def this_is_so_dumb() -> (please := no):
+    pass
+
diff --git a/tests/test_black.py b/tests/test_black.py
index 88ea31777fb..c643f27cacf 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -290,6 +290,14 @@ def test_pep_572_remove_parens(self) -> None:
         if sys.version_info >= (3, 8):
             black.assert_equivalent(source, actual)
 
+    @patch("black.dump_to_file", dump_to_stderr)
+    def test_pep_572_do_not_remove_parens(self) -> None:
+        source, expected = read_data("pep_572_do_not_remove_parens")
+        # the AST safety checks will fail, but that's expected, just make sure no
+        # parentheses are touched
+        actual = black.format_str(source, mode=DEFAULT_MODE)
+        self.assertFormatEqual(expected, actual)
+
     def test_pep_572_version_detection(self) -> None:
         source, _ = read_data("pep_572")
         root = black.lib2to3_parse(source)

From 303a0b2c4d0c828ba6cd4ef6d480f1ff2b5a11c6 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Mon, 26 Apr 2021 16:59:45 -0400
Subject: [PATCH 0155/1034] Maintainers += Richard Si (aka ichard26) (#2149)

---
 README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index ed9f105f5aa..8d6adb0567e 100644
--- a/README.md
+++ b/README.md
@@ -539,8 +539,8 @@ Maintained with [Carol Willing](mailto:carolcode@willingconsulting.com),
 [Carl Meyer](mailto:carl@oddbird.net),
 [Jelle Zijlstra](mailto:jelle.zijlstra@gmail.com),
 [Mika Naylor](mailto:mail@autophagy.io),
-[Zsolt Dollenstein](mailto:zsol.zsol@gmail.com), and
-[Cooper Lees](mailto:me@cooperlees.com).
+[Zsolt Dollenstein](mailto:zsol.zsol@gmail.com),
+[Cooper Lees](mailto:me@cooperlees.com), and Richard Si.
 
 Multiple contributions by:
 

From 1728bb441e6cc3ba5a5ce52ec62014bbfa435a82 Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Tue, 27 Apr 2021 07:40:08 -0700
Subject: [PATCH 0156/1034] Update CHANGELOG for 21.4b1 release (#2151)

* Update CHANGELOG for 21.4b1 release

* Add pathspec minimum bump + update primer not to expect changes for virtualenv
---
 CHANGES.md                   | 6 +++++-
 src/black_primer/primer.json | 2 +-
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index a3bf5565967..d114c5136ff 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,6 +1,6 @@
 ## Change Log
 
-### Unreleased
+### 21.4b1
 
 #### _Black_
 
@@ -15,6 +15,10 @@
 - Don't remove necessary parentheses from assignment expression containing assert /
   return statements. (#2143)
 
+#### _Packaging_
+
+- Bump pathspec to >= 0.8.1 to solve invalid .gitignore exclusion handling
+
 ### 21.4b0
 
 #### _Black_
diff --git a/src/black_primer/primer.json b/src/black_primer/primer.json
index 7a6f5abf408..d38e01dd707 100644
--- a/src/black_primer/primer.json
+++ b/src/black_primer/primer.json
@@ -112,7 +112,7 @@
     },
     "virtualenv": {
       "cli_arguments": [],
-      "expect_formatting_changes": true,
+      "expect_formatting_changes": false,
       "git_clone_url": "https://github.com/pypa/virtualenv.git",
       "long_checkout": false,
       "py_versions": ["all"]

From 82a53999ea971895e2836df39be1ec9110ec102c Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Tue, 27 Apr 2021 08:33:51 -0700
Subject: [PATCH 0157/1034] Add pyanalyze and typeshed to black-primer (#2152)

pyanalyze is one of my projects and it uses `--experimental-string-processing`.

typeshed has a lot of stub files.
---
 src/black_primer/primer.json | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/src/black_primer/primer.json b/src/black_primer/primer.json
index d38e01dd707..75469ad815b 100644
--- a/src/black_primer/primer.json
+++ b/src/black_primer/primer.json
@@ -75,6 +75,13 @@
       "long_checkout": false,
       "py_versions": ["all"]
     },
+    "pyanalyze": {
+      "cli_arguments": [],
+      "expect_formatting_changes": false,
+      "git_clone_url": "https://github.com/quora/pyanalyze.git",
+      "long_checkout": false,
+      "py_versions": ["all"]
+    },
     "pyramid": {
       "cli_arguments": [],
       "expect_formatting_changes": true,
@@ -110,6 +117,13 @@
       "long_checkout": false,
       "py_versions": ["all"]
     },
+    "typeshed": {
+      "cli_arguments": [],
+      "expect_formatting_changes": true,
+      "git_clone_url": "https://github.com/python/typeshed.git",
+      "long_checkout": false,
+      "py_versions": ["all"]
+    },
     "virtualenv": {
       "cli_arguments": [],
       "expect_formatting_changes": false,

From 76e1602d60391cca1bb3b21a9ef6ed07a1bca17d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miro=20Hron=C4=8Dok?= <miro@hroncok.cz>
Date: Tue, 27 Apr 2021 17:58:39 +0200
Subject: [PATCH 0158/1034] Install primer.json (used by black-primer by
 default) with black (#2154)

Fixes https://github.com/psf/black/issues/2153
---
 CHANGES.md | 6 ++++++
 setup.py   | 6 +++++-
 2 files changed, 11 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index d114c5136ff..37b5da6a40d 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,5 +1,11 @@
 ## Change Log
 
+### Unreleased
+
+#### _Packaging_
+
+- Install `primer.json` (used by `black-primer` by default) with black. (#2154)
+
 ### 21.4b1
 
 #### _Black_
diff --git a/setup.py b/setup.py
index 0928c63afc2..f1792a46fe8 100644
--- a/setup.py
+++ b/setup.py
@@ -64,7 +64,11 @@ def get_long_description() -> str:
     ext_modules=ext_modules,
     packages=["blackd", "black", "blib2to3", "blib2to3.pgen2", "black_primer"],
     package_dir={"": "src"},
-    package_data={"blib2to3": ["*.txt"], "black": ["py.typed"]},
+    package_data={
+        "blib2to3": ["*.txt"],
+        "black": ["py.typed"],
+        "black_primer": ["primer.json"],
+    },
     python_requires=">=3.6.2",
     zip_safe=False,
     install_requires=[

From 807a65f9d59d97a606575dc69110d7a5dfd98641 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Tue, 27 Apr 2021 14:00:17 -0700
Subject: [PATCH 0159/1034] Update discussion of AST safety check in README
 (#2159)

---
 CHANGES.md | 5 +++++
 README.md  | 6 ++++--
 2 files changed, 9 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 37b5da6a40d..a30668d33b2 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -2,6 +2,11 @@
 
 ### Unreleased
 
+#### _Black_
+
+- Clarify that _Black_ may change the AST, especially when cleaning up docstrings.
+  (#2159)
+
 #### _Packaging_
 
 - Install `primer.json` (used by `black-primer` by default) with black. (#2154)
diff --git a/README.md b/README.md
index 8d6adb0567e..c7577fbbd04 100644
--- a/README.md
+++ b/README.md
@@ -238,8 +238,10 @@ change in the future**. That being said, no drastic stylistic changes are planne
 mostly responses to bug reports.
 
 Also, as a temporary safety measure, _Black_ will check that the reformatted code still
-produces a valid AST that is equivalent to the original. This slows it down. If you're
-feeling confident, use `--fast`.
+produces a valid AST that is mostly equivalent to the original. This slows it down. If
+you're feeling confident, use `--fast`. In a few contexts, Black does make changes to
+the AST: it cleans up whitespace in docstrings, adds or removes parentheses in some
+`del` statements, and may move around type comments.
 
 ## The _Black_ code style
 

From ad1696422b7343a0cfea3c4b304e6acfa15d3cff Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Tue, 27 Apr 2021 14:16:35 -0700
Subject: [PATCH 0160/1034] Ignore inaccessible user config (#2158)

Fixes #2157
---
 CHANGES.md            |  2 ++
 src/black/__init__.py | 13 +++++++++++--
 2 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index a30668d33b2..cae61f25b4e 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -4,6 +4,8 @@
 
 #### _Black_
 
+- Fix crash if the user configuration directory is inaccessible. (#2158)
+
 - Clarify that _Black_ may change the AST, especially when cleaning up docstrings.
   (#2159)
 
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 015ca415f1c..1c69cc41cdc 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -311,8 +311,17 @@ def find_pyproject_toml(path_search_start: Tuple[str, ...]) -> Optional[str]:
     if path_pyproject_toml.is_file():
         return str(path_pyproject_toml)
 
-    path_user_pyproject_toml = find_user_pyproject_toml()
-    return str(path_user_pyproject_toml) if path_user_pyproject_toml.is_file() else None
+    try:
+        path_user_pyproject_toml = find_user_pyproject_toml()
+        return (
+            str(path_user_pyproject_toml)
+            if path_user_pyproject_toml.is_file()
+            else None
+        )
+    except PermissionError as e:
+        # We do not have access to the user-level config directory, so ignore it.
+        err(f"Ignoring user configuration directory due to {e!r}")
+        return None
 
 
 def parse_pyproject_toml(path_config: str) -> Dict[str, Any]:

From 04fd4432f6c6007e419d7174930569a75ea60fed Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Tue, 27 Apr 2021 20:10:44 -0700
Subject: [PATCH 0161/1034] Add automatic version tagging to Docker CI Pushes
 (#2132)

* Add automatic version tagging to Docker Uploads
- If the git comment has a tag, set that on the docker images pushed
- If we don't have a tag, we just set `latest_non_release`

* Add trigger on release creation too

* Make prettier happy omn docker.yml
---
 .github/workflows/docker.yml | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
index 09390130b3d..7eaf233ab9c 100644
--- a/.github/workflows/docker.yml
+++ b/.github/workflows/docker.yml
@@ -4,6 +4,8 @@ on:
   push:
     branches:
       - "master"
+  release:
+    types: created
 
 jobs:
   docker:
@@ -24,13 +26,18 @@ jobs:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
+      - name: Check + set version tag
+        run:
+          echo "GIT_TAG=$(git describe --candidates=0 --tags 2> /dev/null || echo
+          latest_non_release)" >> $GITHUB_ENV
+
       - name: Build and push
         uses: docker/build-push-action@v2
         with:
           context: .
           platforms: linux/amd64,linux/arm64
           push: true
-          tags: pyfound/black:latest
+          tags: pyfound/black:latest,pyfound/black:${{ env.GIT_TAG }}
 
       - name: Image digest
         run: echo ${{ steps.docker_build.outputs.digest }}

From 89a856d742d31054bc31a6ff7ffc6ad2d24377d5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miro=20Hron=C4=8Dok?= <miro@hroncok.cz>
Date: Wed, 28 Apr 2021 16:07:15 +0200
Subject: [PATCH 0162/1034] Remove useless shebangs in non-executable files
 (#2161)

Such shebangs are only ever used if the file is executed directly, i.e.:

    $ /usr/lib/python3.9/site-packages/black_primer/cli.py

But that doesn't work:

    $ /usr/lib/python3.9/site-packages/black_primer/cli.py
    bash: /usr/lib/python3.9/site-packages/black_primer/cli.py: Permission denied

The lib file even has: "lib is a library, funnily enough"
---
 src/black_primer/cli.py | 2 --
 src/black_primer/lib.py | 2 --
 2 files changed, 4 deletions(-)

diff --git a/src/black_primer/cli.py b/src/black_primer/cli.py
index 5903adc72d4..b2d4159b1da 100644
--- a/src/black_primer/cli.py
+++ b/src/black_primer/cli.py
@@ -1,5 +1,3 @@
-#!/usr/bin/env python3
-
 # coding=utf8
 
 import asyncio
diff --git a/src/black_primer/lib.py b/src/black_primer/lib.py
index 7999f6a3e36..ecc704f2cca 100644
--- a/src/black_primer/lib.py
+++ b/src/black_primer/lib.py
@@ -1,5 +1,3 @@
-#!/usr/bin/env python3
-
 import asyncio
 import errno
 import json

From 682077c15e914fa661879003e186ffc90ac66dcc Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Wed, 28 Apr 2021 07:21:56 -0700
Subject: [PATCH 0163/1034] Update CHANGELOG for 21.4b2 release (#2162)

---
 CHANGES.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index cae61f25b4e..5b9f574a408 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,6 +1,6 @@
 ## Change Log
 
-### Unreleased
+### 21.4b2
 
 #### _Black_
 

From b39999da7f451c285befac217f1f9a685774b34d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C5=81ukasz=20Langa?= <lukasz@langa.pl>
Date: Wed, 28 Apr 2021 16:48:04 +0200
Subject: [PATCH 0164/1034] Elaborate on what AST changes Black might perform

---
 CHANGES.md                   |  5 +++--
 README.md                    | 10 +++++-----
 docs/the_black_code_style.md | 29 +++++++++++++++++++++++++++++
 3 files changed, 37 insertions(+), 7 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 5b9f574a408..6675c484c75 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -6,8 +6,9 @@
 
 - Fix crash if the user configuration directory is inaccessible. (#2158)
 
-- Clarify that _Black_ may change the AST, especially when cleaning up docstrings.
-  (#2159)
+- Clarify
+  [circumstances](https://github.com/psf/black/blob/master/docs/the_black_code_style.md#pragmatism)
+  in which _Black_ may change the AST (#2159)
 
 #### _Packaging_
 
diff --git a/README.md b/README.md
index c7577fbbd04..41cea761df5 100644
--- a/README.md
+++ b/README.md
@@ -237,11 +237,11 @@ is that **until the formatter becomes stable, you should expect some formatting
 change in the future**. That being said, no drastic stylistic changes are planned,
 mostly responses to bug reports.
 
-Also, as a temporary safety measure, _Black_ will check that the reformatted code still
-produces a valid AST that is mostly equivalent to the original. This slows it down. If
-you're feeling confident, use `--fast`. In a few contexts, Black does make changes to
-the AST: it cleans up whitespace in docstrings, adds or removes parentheses in some
-`del` statements, and may move around type comments.
+Also, as a safety measure which slows down processing, _Black_ will check that the
+reformatted code still produces a valid AST that is effectively equivalent to the
+original (see the
+[Pragmatism](https://github.com/psf/black/blob/master/docs/the_black_code_style.md#pragmatism)
+section for details). If you're feeling confident, use `--fast`.
 
 ## The _Black_ code style
 
diff --git a/docs/the_black_code_style.md b/docs/the_black_code_style.md
index 67ccb8aab11..39a452ff9a8 100644
--- a/docs/the_black_code_style.md
+++ b/docs/the_black_code_style.md
@@ -464,3 +464,32 @@ exception to this rule is r-strings. It turns out that the very popular
 default by (among others) GitHub and Visual Studio Code, differentiates between
 r-strings and R-strings. The former are syntax highlighted as regular expressions while
 the latter are treated as true raw strings with no special semantics.
+
+### AST before and after formatting
+
+When run with `--safe`, _Black_ checks that the code before and after is semantically
+equivalent. This check is done by comparing the AST of the source with the AST of the
+target. There are three limited cases in which the AST does differ:
+
+1. _Black_ cleans up leading and trailing whitespace of docstrings, re-indenting them if
+   needed. It's been one of the most popular user-reported features for the formatter to
+   fix whitespace issues with docstrings. While the result is technically an AST
+   difference, due to the various possibilities of forming docstrings, all realtime use
+   of docstrings that we're aware of sanitizes indentation and leading/trailing
+   whitespace anyway.
+
+2. _Black_ manages optional parentheses for some statements. In the case of the `del`
+   statement, presence of wrapping parentheses or lack of thereof changes the resulting
+   AST but is semantically equivalent in the interpreter.
+
+3. _Black_ might move comments around, which includes type comments. Those are part of
+   the AST as of Python 3.8. While the tool implements a number of special cases for
+   those comments, there is no guarantee they will remain where they were in the source.
+   Note that this doesn't change runtime behavior of the source code.
+
+To put things in perspective, the code equivalence check is a feature of _Black_ which
+other formatters don't implement at all. It is of crucial importance to us to ensure
+code behaves the way it did before it got reformatted. We treat this as a feature and
+there are no plans to relax this in the future. The exceptions enumerated above stem
+from either user feedback or implementation details of the tool. In each case we made
+due diligence to ensure that the AST divergence is of no practical consequence.

From 00491e1dcb19a795867249471ca5bb95efcd8cd3 Mon Sep 17 00:00:00 2001
From: Kaleb Barrett <dev.ktbarrett@gmail.com>
Date: Sat, 1 May 2021 13:47:59 -0500
Subject: [PATCH 0165/1034] Add ability to pass posargs to pytest run in
 tox.ini (#2173)

---
 tox.ini | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tox.ini b/tox.ini
index 71b02e920c7..affc3c9876a 100644
--- a/tox.ini
+++ b/tox.ini
@@ -9,7 +9,7 @@ deps =
 commands =
     pip install -e .[d,python2]
     coverage erase
-    coverage run -m pytest tests
+    coverage run -m pytest tests {posargs}
     coverage report
 
 [testenv:fuzz]

From 24bd6b983ac459eabd9352eb816be53e7f447812 Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <hugovk@users.noreply.github.com>
Date: Sat, 1 May 2021 22:17:20 +0300
Subject: [PATCH 0166/1034] Tox has been formatted with Black 21.4b0 (#2175)

---
 src/black_primer/primer.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/black_primer/primer.json b/src/black_primer/primer.json
index 75469ad815b..5017a5625a3 100644
--- a/src/black_primer/primer.json
+++ b/src/black_primer/primer.json
@@ -112,7 +112,7 @@
     },
     "tox": {
       "cli_arguments": [],
-      "expect_formatting_changes": true,
+      "expect_formatting_changes": false,
       "git_clone_url": "https://github.com/tox-dev/tox.git",
       "long_checkout": false,
       "py_versions": ["all"]

From 35e8d1560d68e8113ff926a9f832582f8f4a694f Mon Sep 17 00:00:00 2001
From: Bryan Forbes <bryan@reigndropsfall.net>
Date: Sun, 2 May 2021 07:48:54 -0500
Subject: [PATCH 0167/1034] Set `is_pyi` if `stdin_filename` ends with `.pyi`
 (#2169)

Fixes #2167

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 CHANGES.md            |  6 ++++++
 src/black/__init__.py |  2 ++
 tests/test_black.py   | 32 +++++++++++++++++++++++++++++---
 3 files changed, 37 insertions(+), 3 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 6675c484c75..321f8c083b2 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,5 +1,11 @@
 ## Change Log
 
+### Unreleased
+
+#### _Black_
+
+- Set `--pyi` mode if `--stdin-filename` ends in `.pyi` (#2169)
+
 ### 21.4b2
 
 #### _Black_
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 1c69cc41cdc..49d088b531d 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -755,6 +755,8 @@ def reformat_one(
             is_stdin = False
 
         if is_stdin:
+            if src.suffix == ".pyi":
+                mode = replace(mode, is_pyi=True)
             if format_stdin_to_stdout(fast=fast, write_back=write_back, mode=mode):
                 changed = Changed.YES
         else:
diff --git a/tests/test_black.py b/tests/test_black.py
index c643f27cacf..43368d4bbe9 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -1578,8 +1578,34 @@ def test_reformat_one_with_stdin_filename(self) -> None:
                 mode=DEFAULT_MODE,
                 report=report,
             )
-            fsts.assert_called_once()
-            # __BLACK_STDIN_FILENAME__ should have been striped
+            fsts.assert_called_once_with(
+                fast=True, write_back=black.WriteBack.YES, mode=DEFAULT_MODE
+            )
+            # __BLACK_STDIN_FILENAME__ should have been stripped
+            report.done.assert_called_with(expected, black.Changed.YES)
+
+    def test_reformat_one_with_stdin_filename_pyi(self) -> None:
+        with patch(
+            "black.format_stdin_to_stdout",
+            return_value=lambda *args, **kwargs: black.Changed.YES,
+        ) as fsts:
+            report = MagicMock()
+            p = "foo.pyi"
+            path = Path(f"__BLACK_STDIN_FILENAME__{p}")
+            expected = Path(p)
+            black.reformat_one(
+                path,
+                fast=True,
+                write_back=black.WriteBack.YES,
+                mode=DEFAULT_MODE,
+                report=report,
+            )
+            fsts.assert_called_once_with(
+                fast=True,
+                write_back=black.WriteBack.YES,
+                mode=replace(DEFAULT_MODE, is_pyi=True),
+            )
+            # __BLACK_STDIN_FILENAME__ should have been stripped
             report.done.assert_called_with(expected, black.Changed.YES)
 
     def test_reformat_one_with_stdin_and_existing_path(self) -> None:
@@ -1603,7 +1629,7 @@ def test_reformat_one_with_stdin_and_existing_path(self) -> None:
                 report=report,
             )
             fsts.assert_called_once()
-            # __BLACK_STDIN_FILENAME__ should have been striped
+            # __BLACK_STDIN_FILENAME__ should have been stripped
             report.done.assert_called_with(expected, black.Changed.YES)
 
     def test_gitignore_exclude(self) -> None:

From a669b64091c149132f4e234abd230f7b33d692e8 Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Mon, 3 May 2021 14:58:17 -0700
Subject: [PATCH 0168/1034] primer: Renable pandas (#2185)

- It no longer crashes black so we should test on it's code
- Update django reason to name the file causing error
  - Seems it has a syntax error on purpose
---
 src/black_primer/primer.json | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/src/black_primer/primer.json b/src/black_primer/primer.json
index 5017a5625a3..137d075c68e 100644
--- a/src/black_primer/primer.json
+++ b/src/black_primer/primer.json
@@ -30,7 +30,7 @@
       "py_versions": ["all"]
     },
     "django": {
-      "disabled_reason": "black --check --diff returned 123 on two files",
+      "disabled_reason": "black --check --diff returned 123 on tests_syntax_error.py",
       "disabled": true,
       "cli_arguments": [],
       "expect_formatting_changes": true,
@@ -53,8 +53,6 @@
       "py_versions": ["all"]
     },
     "pandas": {
-      "disabled_reason": "black --check --diff returned 123 on one file",
-      "disabled": true,
       "cli_arguments": [],
       "expect_formatting_changes": true,
       "git_clone_url": "https://github.com/pandas-dev/pandas.git",

From a18c7bc09942951e93cbd142fb7384aa2af18951 Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Tue, 4 May 2021 01:44:40 -0700
Subject: [PATCH 0169/1034] primer: Add `--no-diff` option (#2187)

- Allow runs with no code diff output
- This is handy for reducing output to see which file is erroring

Test:
- Edit config for 'channels' to expect no changes and run with `--no-diff` and see no diff output
---
 CHANGES.md              |  1 +
 src/black_primer/cli.py | 15 ++++++++++++++-
 src/black_primer/lib.py | 25 +++++++++++++++++++++----
 tests/test_primer.py    |  1 +
 4 files changed, 37 insertions(+), 5 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 321f8c083b2..7741d92772d 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -5,6 +5,7 @@
 #### _Black_
 
 - Set `--pyi` mode if `--stdin-filename` ends in `.pyi` (#2169)
+- Add `--no-diff` to black-primer to suppress formatting changes (#2187)
 
 ### 21.4b2
 
diff --git a/src/black_primer/cli.py b/src/black_primer/cli.py
index b2d4159b1da..00b54d6511f 100644
--- a/src/black_primer/cli.py
+++ b/src/black_primer/cli.py
@@ -39,6 +39,7 @@ async def async_main(
     debug: bool,
     keep: bool,
     long_checkouts: bool,
+    no_diff: bool,
     rebase: bool,
     workdir: str,
     workers: int,
@@ -54,7 +55,13 @@ async def async_main(
 
     try:
         ret_val = await lib.process_queue(
-            config, work_path, workers, keep, long_checkouts, rebase
+            config,
+            work_path,
+            workers,
+            keep,
+            long_checkouts,
+            rebase,
+            no_diff,
         )
         return int(ret_val)
     finally:
@@ -95,6 +102,12 @@ async def async_main(
     show_default=True,
     help="Pull big projects to test",
 )
+@click.option(
+    "--no-diff",
+    is_flag=True,
+    show_default=True,
+    help="Disable showing source file changes in black output",
+)
 @click.option(
     "-R",
     "--rebase",
diff --git a/src/black_primer/lib.py b/src/black_primer/lib.py
index ecc704f2cca..aba694b0e60 100644
--- a/src/black_primer/lib.py
+++ b/src/black_primer/lib.py
@@ -112,13 +112,20 @@ def analyze_results(project_count: int, results: Results) -> int:
 
 
 async def black_run(
-    repo_path: Path, project_config: Dict[str, Any], results: Results
+    repo_path: Path,
+    project_config: Dict[str, Any],
+    results: Results,
+    no_diff: bool = False,
 ) -> None:
     """Run Black and record failures"""
     cmd = [str(which(BLACK_BINARY))]
     if "cli_arguments" in project_config and project_config["cli_arguments"]:
         cmd.extend(*project_config["cli_arguments"])
-    cmd.extend(["--check", "--diff", "."])
+    cmd.append("--check")
+    if no_diff:
+        cmd.append(".")
+    else:
+        cmd.extend(["--diff", "."])
 
     with TemporaryDirectory() as tmp_path:
         # Prevent reading top-level user configs by manipulating envionment variables
@@ -246,6 +253,7 @@ async def project_runner(
     long_checkouts: bool = False,
     rebase: bool = False,
     keep: bool = False,
+    no_diff: bool = False,
 ) -> None:
     """Check out project and run Black on it + record result"""
     loop = asyncio.get_event_loop()
@@ -284,7 +292,7 @@ async def project_runner(
         repo_path = await git_checkout_or_rebase(work_path, project_config, rebase)
         if not repo_path:
             continue
-        await black_run(repo_path, project_config, results)
+        await black_run(repo_path, project_config, results, no_diff)
 
         if not keep:
             LOG.debug(f"Removing {repo_path}")
@@ -303,6 +311,7 @@ async def process_queue(
     keep: bool = False,
     long_checkouts: bool = False,
     rebase: bool = False,
+    no_diff: bool = False,
 ) -> int:
     """
     Process the queue with X workers and evaluate results
@@ -330,7 +339,15 @@ async def process_queue(
     await asyncio.gather(
         *[
             project_runner(
-                i, config, queue, work_path, results, long_checkouts, rebase, keep
+                i,
+                config,
+                queue,
+                work_path,
+                results,
+                long_checkouts,
+                rebase,
+                keep,
+                no_diff,
             )
             for i in range(workers)
         ]
diff --git a/tests/test_primer.py b/tests/test_primer.py
index a8ad8a7c5af..8bfecd61a57 100644
--- a/tests/test_primer.py
+++ b/tests/test_primer.py
@@ -198,6 +198,7 @@ def test_async_main(self) -> None:
             "rebase": False,
             "workdir": str(work_dir),
             "workers": 69,
+            "no_diff": False,
         }
         with patch("black_primer.cli.lib.process_queue", return_zero):
             return_val = loop.run_until_complete(cli.async_main(**args))

From e42f9921e291790202147c1e3dc1a3df7036c652 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Tue, 4 May 2021 04:46:46 -0400
Subject: [PATCH 0170/1034] Detect `'@' dotted_name '(' ')' NEWLINE` as a
 simple decorator (#2182)

Previously the RELAXED_DECORATOR detection would be falsely True on that
example. The problem was that an argument-less parentheses pair didn't
pass the `is_simple_decorator_trailer` check even it should. OTOH a
parentheses pair containing an argument or more passed as expected.
---
 CHANGES.md               | 3 +++
 src/black/__init__.py    | 7 +++++++
 tests/data/decorators.py | 6 ++++++
 3 files changed, 16 insertions(+)

diff --git a/CHANGES.md b/CHANGES.md
index 7741d92772d..00d6782dc6b 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -7,6 +7,9 @@
 - Set `--pyi` mode if `--stdin-filename` ends in `.pyi` (#2169)
 - Add `--no-diff` to black-primer to suppress formatting changes (#2187)
 
+- Stop detecting target version as Python 3.9+ with pre-PEP-614 decorators that are
+  being called but with no arguments (#2182)
+
 ### 21.4b2
 
 #### _Black_
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 49d088b531d..cf257876c03 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -5761,6 +5761,13 @@ def is_simple_decorator_trailer(node: LN, last: bool = False) -> bool:
             and node.children[0].type == token.DOT
             and node.children[1].type == token.NAME
         )
+        # last trailer can be an argument-less parentheses pair
+        or (
+            last
+            and len(node.children) == 2
+            and node.children[0].type == token.LPAR
+            and node.children[1].type == token.RPAR
+        )
         # last trailer can be arguments
         or (
             last
diff --git a/tests/data/decorators.py b/tests/data/decorators.py
index acfad51fcb8..a0f38ca7b9d 100644
--- a/tests/data/decorators.py
+++ b/tests/data/decorators.py
@@ -13,6 +13,12 @@ def f():
 
 ##
 
+@decorator()
+def f():
+    ...
+
+##
+
 @decorator(arg)
 def f():
     ...

From 204f76e0c02a12aeccb3ab708fe41f7e95435a29 Mon Sep 17 00:00:00 2001
From: KotlinIsland <65446343+KotlinIsland@users.noreply.github.com>
Date: Tue, 4 May 2021 18:47:22 +1000
Subject: [PATCH 0171/1034] add test configurations that don't contain python2
 optional install (#2190)

add test for negative scenario: formatting python2 code
tag python2 only tests

Co-authored-by: KotlinIsland <kotlinisland@users.noreply.github.com>
---
 pyproject.toml       |  3 +++
 tests/test_black.py  | 30 ++++++++++++++++++++++++++++++
 tests/test_format.py | 16 +++++++++++++---
 tox.ini              |  6 ++++--
 4 files changed, 50 insertions(+), 5 deletions(-)

diff --git a/pyproject.toml b/pyproject.toml
index 7f632f2839d..ca75f8f92ef 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -25,3 +25,6 @@ extend-exclude = '''
 [build-system]
 requires = ["setuptools>=41.0", "setuptools-scm", "wheel"]
 build-backend = "setuptools.build_meta"
+
+[tool.pytest.ini_options]
+markers = ['python2', "without_python2"]
\ No newline at end of file
diff --git a/tests/test_black.py b/tests/test_black.py
index 43368d4bbe9..7d855cab3d3 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -24,6 +24,7 @@
     Iterator,
     TypeVar,
 )
+import pytest
 import unittest
 from unittest.mock import patch, MagicMock
 
@@ -459,6 +460,34 @@ def test_skip_magic_trailing_comma(self) -> None:
             )
             self.assertEqual(expected, actual, msg)
 
+    @pytest.mark.without_python2
+    def test_python2_should_fail_without_optional_install(self) -> None:
+        # python 3.7 and below will install typed-ast and will be able to parse Python 2
+        if sys.version_info < (3, 8):
+            return
+        source = "x = 1234l"
+        tmp_file = Path(black.dump_to_file(source))
+        try:
+            runner = BlackRunner()
+            result = runner.invoke(black.main, [str(tmp_file)])
+            self.assertEqual(result.exit_code, 123)
+        finally:
+            os.unlink(tmp_file)
+        actual = (
+            runner.stderr_bytes.decode()
+            .replace("\n", "")
+            .replace("\\n", "")
+            .replace("\\r", "")
+            .replace("\r", "")
+        )
+        msg = (
+            "The requested source code has invalid Python 3 syntax."
+            "If you are trying to format Python 2 files please reinstall Black"
+            " with the 'python2' extra: `python3 -m pip install black[python2]`."
+        )
+        self.assertIn(msg, actual)
+
+    @pytest.mark.python2
     @patch("black.dump_to_file", dump_to_stderr)
     def test_python2_print_function(self) -> None:
         source, expected = read_data("python2_print_function")
@@ -1971,6 +2000,7 @@ def test_bpo_2142_workaround(self) -> None:
         actual = diff_header.sub(DETERMINISTIC_HEADER, actual)
         self.assertEqual(actual, expected)
 
+    @pytest.mark.python2
     def test_docstring_reformat_for_py27(self) -> None:
         """
         Check that stripping trailing whitespace from Python 2 docstrings
diff --git a/tests/test_format.py b/tests/test_format.py
index e1335aedf43..78f2b558a4f 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -1,6 +1,7 @@
 from unittest.mock import patch
 
 import black
+import pytest
 from parameterized import parameterized
 
 from tests.util import (
@@ -46,9 +47,6 @@
     "function2",
     "function_trailing_comma",
     "import_spacing",
-    "numeric_literals_py2",
-    "python2",
-    "python2_unicode_literals",
     "remove_parens",
     "slices",
     "string_prefixes",
@@ -56,6 +54,12 @@
     "tupleassign",
 ]
 
+SIMPLE_CASES_PY2 = [
+    "numeric_literals_py2",
+    "python2",
+    "python2_unicode_literals",
+]
+
 EXPERIMENTAL_STRING_PROCESSING_CASES = [
     "cantfit",
     "comments7",
@@ -86,6 +90,12 @@
 
 
 class TestSimpleFormat(BlackBaseTestCase):
+    @parameterized.expand(SIMPLE_CASES_PY2)
+    @pytest.mark.python2
+    @patch("black.dump_to_file", dump_to_stderr)
+    def test_simple_format_py2(self, filename: str) -> None:
+        self.check_file(filename, DEFAULT_MODE)
+
     @parameterized.expand(SIMPLE_CASES)
     @patch("black.dump_to_file", dump_to_stderr)
     def test_simple_format(self, filename: str) -> None:
diff --git a/tox.ini b/tox.ini
index affc3c9876a..cbb0f75d145 100644
--- a/tox.ini
+++ b/tox.ini
@@ -7,9 +7,11 @@ skip_install = True
 deps =
     -r{toxinidir}/test_requirements.txt
 commands =
-    pip install -e .[d,python2]
+    pip install -e .[d]
     coverage erase
-    coverage run -m pytest tests {posargs}
+    coverage run -m pytest tests -m "not python2" {posargs}
+    pip install -e .[d,python2]
+    coverage run -m pytest tests -m "not without_python2" {posargs}
     coverage report
 
 [testenv:fuzz]

From 5918a016ff82e5fa12097d07b1624a89ec4e60ac Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Tue, 4 May 2021 04:47:59 -0400
Subject: [PATCH 0172/1034] Drop Travis CI and migrate Coveralls (#2186)

Travis CI for Open Source is shutting down in a few weeks so the queue
for jobs is insane due to lower resources. I'm 99.99% sure we don't need
it as our Test, Lint, Docs, Upload / Package, Primer, and Fuzz workflows
are all on GitHub Actions. So even though we *can* migrate to the .com
version with its 1000 free Linux minutes(?), I don't think we need to.

more information here:
- https://blog.travis-ci.com/oss-announcement
- https://blog.travis-ci.com/2020-11-02-travis-ci-new-billing
- https://docs.travis-ci.com/user/migrate/open-source-repository-migration

This commit does the following:
- delete the Travis CI configuration
- add to the GHA test workflows so coverage continues to be recorded
  - tweaked coverage configuration so this wouldn't break
- remove any references to Travis CI in the docs (i.e. readme + sphinx
  docs)

Regarding the Travis CI to GitHub Actions Coveralls transition, the
official action doesn't support the coverage files produced by coverage.py
unfornately. Also no, I don't really know what I am doing so don't @ me
if this breaks :p (well you can, but don't expect me to be THAT useful).

The Coveralls setup has two downfalls AFAIK:
- Only Linux runs are used because AndreMiras/coveralls-python-action
  only supports Linux. Although this isn't a big issue since the Travis
  Coveralls configuration only used Linux data too.
- Pull requests from an internal branch (i.e. one on psf/black) will be
  marked as a push coverage build by Coveralls since our anti-duplicate-
  workflows system runs under the push even for such cases.
---
 .coveragerc                |  3 +++
 .github/workflows/test.yml | 31 +++++++++++++++++++++++++++++++
 .travis.yml                | 31 -------------------------------
 README.md                  |  1 -
 docs/conf.py               |  1 -
 5 files changed, 34 insertions(+), 33 deletions(-)
 delete mode 100644 .travis.yml

diff --git a/.coveragerc b/.coveragerc
index 32a8da521ba..f05041ca1dc 100644
--- a/.coveragerc
+++ b/.coveragerc
@@ -3,3 +3,6 @@ omit =
   src/blib2to3/*
   tests/data/*
   */site-packages/*
+
+[run]
+relative_files = True
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index bec769064c2..03adc7f0bea 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -34,3 +34,34 @@ jobs:
       - name: Unit tests
         run: |
           tox -e py
+
+      - name: Publish coverage to Coveralls
+        # If pushed / is a pull request against main repo AND
+        # we're running on Linux (this action only supports Linux)
+        if:
+          ((github.event_name == 'push' && github.repository == 'psf/black') ||
+          github.event.pull_request.base.repo.full_name == 'psf/black') && matrix.os ==
+          'ubuntu-latest'
+
+        uses: AndreMiras/coveralls-python-action@v20201129
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          parallel: true
+          flag-name: py${{ matrix.python-version }}-${{ matrix.os }}
+          debug: true
+
+  coveralls-finish:
+    needs: build
+    # If pushed / is a pull request against main repo
+    if:
+      (github.event_name == 'push' && github.repository == 'psf/black') ||
+      github.event.pull_request.base.repo.full_name == 'psf/black'
+
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Coveralls finished
+        uses: AndreMiras/coveralls-python-action@v20201129
+        with:
+          parallel-finished: true
+          debug: true
diff --git a/.travis.yml b/.travis.yml
deleted file mode 100644
index e782272e813..00000000000
--- a/.travis.yml
+++ /dev/null
@@ -1,31 +0,0 @@
-language: python
-cache:
-  pip: true
-  directories:
-    - $HOME/.cache/pre-commit
-env:
-  - TEST_CMD="tox -e py"
-install:
-  - pip install coverage coveralls pre-commit tox
-  - pip install -e '.[d]'
-script:
-  - $TEST_CMD
-after_success:
-  - coveralls
-notifications:
-  on_success: change
-  on_failure: always
-matrix:
-  include:
-    - name: "lint"
-      python: 3.7
-      env:
-        - TEST_CMD="pre-commit run --all-files --show-diff-on-failure"
-    - name: "3.6"
-      python: 3.6
-    - name: "3.7"
-      python: 3.7
-    - name: "3.8"
-      python: 3.8
-    - name: "3.9"
-      python: 3.9
diff --git a/README.md b/README.md
index 41cea761df5..696bfa7e064 100644
--- a/README.md
+++ b/README.md
@@ -3,7 +3,6 @@
 <h2 align="center">The Uncompromising Code Formatter</h2>
 
 <p align="center">
-<a href="https://travis-ci.com/psf/black"><img alt="Build Status" src="https://travis-ci.com/psf/black.svg?branch=master"></a>
 <a href="/psf/black/actions"><img alt="Actions Status" src="https://github.com/psf/black/workflows/Test/badge.svg"></a>
 <a href="/psf/black/actions"><img alt="Actions Status" src="https://github.com/psf/black/workflows/Primer/badge.svg"></a>
 <a href="https://black.readthedocs.io/en/stable/?badge=stable"><img alt="Documentation Status" src="https://readthedocs.org/projects/black/badge/?version=stable"></a>
diff --git a/docs/conf.py b/docs/conf.py
index ec6aad9a27b..9e03d05e937 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -314,7 +314,6 @@ def process_sections(
     "show_powered_by": True,
     "fixed_sidebar": True,
     "logo": "logo2.png",
-    "travis_button": True,
 }
 
 

From 0c60ccc06646030bd48d4e160c6aae755307c2d9 Mon Sep 17 00:00:00 2001
From: reka <382113+reka@users.noreply.github.com>
Date: Tue, 4 May 2021 10:48:59 +0200
Subject: [PATCH 0173/1034] compatible isort config: mention profile first
 (#2180)

Change the order of possible ways to configure isort:
1. using the profile black
2. custom configuration

Formats section:
change the examples to use the profile black

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 docs/compatible_configs.md | 50 +++++++++++++++++---------------------
 1 file changed, 22 insertions(+), 28 deletions(-)

diff --git a/docs/compatible_configs.md b/docs/compatible_configs.md
index a4f83ee472f..de81769f72d 100644
--- a/docs/compatible_configs.md
+++ b/docs/compatible_configs.md
@@ -19,7 +19,24 @@ Compatible configuration files can be
 _Black_ also formats imports, but in a different way from isort's defaults which leads
 to conflicting changes.
 
-### Configuration
+### Profile
+
+Since version 5.0.0, isort supports
+[profiles](https://pycqa.github.io/isort/docs/configuration/profiles/) to allow easy
+interoperability with common code styles. You can set the black profile in any of the
+[config files](https://pycqa.github.io/isort/docs/configuration/config_files/) supported
+by isort. Below, an example for `pyproject.toml`:
+
+```toml
+[tool.isort]
+profile = "black"
+```
+
+### Custom Configuration
+
+If you're using an isort version that is older than 5.0.0 or you have some custom
+configuration for _Black_, you can tweak your isort configuration to make it compatible
+with _Black_. Below, an example for `.isort.cfg`:
 
 ```
 multi_line_output = 3
@@ -72,9 +89,6 @@ works the same as with _Black_.
 
 **Please note** `ensure_newline_before_comments = True` only works since isort >= 5 but
 does not break older versions so you can keep it if you are running previous versions.
-If only isort >= 5 is used you can add `profile = black` instead of all the options
-since [profiles](https://timothycrosley.github.io/isort/docs/configuration/profiles/)
-are available and do the configuring for you.
 
 ### Formats
 
@@ -83,12 +97,7 @@ are available and do the configuring for you.
 
 ```cfg
 [settings]
-multi_line_output = 3
-include_trailing_comma = True
-force_grid_wrap = 0
-use_parentheses = True
-ensure_newline_before_comments = True
-line_length = 88
+profile = black
 ```
 
 </details>
@@ -98,12 +107,7 @@ line_length = 88
 
 ```cfg
 [isort]
-multi_line_output = 3
-include_trailing_comma = True
-force_grid_wrap = 0
-use_parentheses = True
-ensure_newline_before_comments = True
-line_length = 88
+profile = black
 ```
 
 </details>
@@ -113,12 +117,7 @@ line_length = 88
 
 ```toml
 [tool.isort]
-multi_line_output = 3
-include_trailing_comma = true
-force_grid_wrap = 0
-use_parentheses = true
-ensure_newline_before_comments = true
-line_length = 88
+profile = 'black'
 ```
 
 </details>
@@ -128,12 +127,7 @@ line_length = 88
 
 ```ini
 [*.py]
-multi_line_output = 3
-include_trailing_comma = True
-force_grid_wrap = 0
-use_parentheses = True
-ensure_newline_before_comments = True
-line_length = 88
+profile = black
 ```
 
 </details>

From 267bc5dde9f4e5e4b6dacdf79cf1688ffe9b7715 Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <hugovk@users.noreply.github.com>
Date: Tue, 4 May 2021 14:41:04 +0300
Subject: [PATCH 0174/1034] Use pre-commit/action to simplify CI (#2191)

---
 .github/workflows/lint.yml | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index 2480a5ec131..51f6d02e2e6 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -22,8 +22,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          python -m pip install --upgrade pre-commit
           python -m pip install -e '.[d]'
 
       - name: Lint
-        run: pre-commit run --all-files --show-diff-on-failure
+        uses: pre-commit/action@v2.0.2

From d8a034f9b69b3a214e01985e741c4418ae562e2e Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Tue, 4 May 2021 11:07:08 -0700
Subject: [PATCH 0175/1034] Update CHANGES.md for 21.5b0 release (#2192)

* Update CHANGES.md for 21.5b0 release

* Make prettier happy
---
 CHANGES.md | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 00d6782dc6b..becf69904fb 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,15 +1,17 @@
 ## Change Log
 
-### Unreleased
+### 21.5b0
 
 #### _Black_
 
 - Set `--pyi` mode if `--stdin-filename` ends in `.pyi` (#2169)
-- Add `--no-diff` to black-primer to suppress formatting changes (#2187)
-
 - Stop detecting target version as Python 3.9+ with pre-PEP-614 decorators that are
   being called but with no arguments (#2182)
 
+#### _Black-Primer_
+
+- Add `--no-diff` to black-primer to suppress formatting changes (#2187)
+
 ### 21.4b2
 
 #### _Black_

From 14c76e89716b5b53c97ece80bb935ea956b7dd89 Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Tue, 4 May 2021 12:49:20 -0700
Subject: [PATCH 0176/1034] Disable pandas while we look into #2193 (#2195)

---
 src/black_primer/primer.json | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/src/black_primer/primer.json b/src/black_primer/primer.json
index 137d075c68e..78c1e2acdef 100644
--- a/src/black_primer/primer.json
+++ b/src/black_primer/primer.json
@@ -53,6 +53,8 @@
       "py_versions": ["all"]
     },
     "pandas": {
+      "disabled_reason": "black-primer runs failing on Pandas - #2193",
+      "disabled": true,
       "cli_arguments": [],
       "expect_formatting_changes": true,
       "git_clone_url": "https://github.com/pandas-dev/pandas.git",

From 07c8812937cf75ac5bc7ceac07ef5ea383f10f2f Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Wed, 5 May 2021 08:33:23 -0700
Subject: [PATCH 0177/1034] Enable ` --experimental-string-processing` on most
 primer projects (#2184)

* Enable ` --experimental-string-processing` on all primer projects
- We want to make this default so need to test it more
- Fixed splat/star bug in extending black args for each project

* Disable sqlalchemy due to crash
---
 src/black_primer/lib.py      |  2 +-
 src/black_primer/primer.json | 47 ++++++++++++++++++------------------
 2 files changed, 25 insertions(+), 24 deletions(-)

diff --git a/src/black_primer/lib.py b/src/black_primer/lib.py
index aba694b0e60..3ce383f17ce 100644
--- a/src/black_primer/lib.py
+++ b/src/black_primer/lib.py
@@ -120,7 +120,7 @@ async def black_run(
     """Run Black and record failures"""
     cmd = [str(which(BLACK_BINARY))]
     if "cli_arguments" in project_config and project_config["cli_arguments"]:
-        cmd.extend(*project_config["cli_arguments"])
+        cmd.extend(project_config["cli_arguments"])
     cmd.append("--check")
     if no_diff:
         cmd.append(".")
diff --git a/src/black_primer/primer.json b/src/black_primer/primer.json
index 78c1e2acdef..76ed4820487 100644
--- a/src/black_primer/primer.json
+++ b/src/black_primer/primer.json
@@ -2,28 +2,28 @@
   "configuration_format_version": 20200509,
   "projects": {
     "aioexabgp": {
-      "cli_arguments": [],
+      "cli_arguments": ["--experimental-string-processing"],
       "expect_formatting_changes": false,
       "git_clone_url": "https://github.com/cooperlees/aioexabgp.git",
       "long_checkout": false,
       "py_versions": ["all"]
     },
     "attrs": {
-      "cli_arguments": [],
+      "cli_arguments": ["--experimental-string-processing"],
       "expect_formatting_changes": true,
       "git_clone_url": "https://github.com/python-attrs/attrs.git",
       "long_checkout": false,
       "py_versions": ["all"]
     },
     "bandersnatch": {
-      "cli_arguments": [],
-      "expect_formatting_changes": false,
+      "cli_arguments": ["--experimental-string-processing"],
+      "expect_formatting_changes": true,
       "git_clone_url": "https://github.com/pypa/bandersnatch.git",
       "long_checkout": false,
       "py_versions": ["all"]
     },
     "channels": {
-      "cli_arguments": [],
+      "cli_arguments": ["--experimental-string-processing"],
       "expect_formatting_changes": true,
       "git_clone_url": "https://github.com/django/channels.git",
       "long_checkout": false,
@@ -32,22 +32,22 @@
     "django": {
       "disabled_reason": "black --check --diff returned 123 on tests_syntax_error.py",
       "disabled": true,
-      "cli_arguments": [],
+      "cli_arguments": ["--experimental-string-processing"],
       "expect_formatting_changes": true,
       "git_clone_url": "https://github.com/django/django.git",
       "long_checkout": false,
       "py_versions": ["all"]
     },
     "flake8-bugbear": {
-      "cli_arguments": [],
+      "cli_arguments": ["--experimental-string-processing"],
       "expect_formatting_changes": false,
       "git_clone_url": "https://github.com/PyCQA/flake8-bugbear.git",
       "long_checkout": false,
       "py_versions": ["all"]
     },
     "hypothesis": {
-      "cli_arguments": [],
-      "expect_formatting_changes": false,
+      "cli_arguments": ["--experimental-string-processing"],
+      "expect_formatting_changes": true,
       "git_clone_url": "https://github.com/HypothesisWorks/hypothesis.git",
       "long_checkout": false,
       "py_versions": ["all"]
@@ -55,55 +55,56 @@
     "pandas": {
       "disabled_reason": "black-primer runs failing on Pandas - #2193",
       "disabled": true,
-      "cli_arguments": [],
+      "cli_arguments": ["--experimental-string-processing"],
       "expect_formatting_changes": true,
       "git_clone_url": "https://github.com/pandas-dev/pandas.git",
       "long_checkout": false,
       "py_versions": ["all"]
     },
     "pillow": {
-      "cli_arguments": [],
+      "cli_arguments": ["--experimental-string-processing"],
       "expect_formatting_changes": true,
       "git_clone_url": "https://github.com/python-pillow/Pillow.git",
       "long_checkout": false,
       "py_versions": ["all"]
     },
     "poetry": {
-      "cli_arguments": [],
+      "cli_arguments": ["--experimental-string-processing"],
       "expect_formatting_changes": true,
       "git_clone_url": "https://github.com/python-poetry/poetry.git",
       "long_checkout": false,
       "py_versions": ["all"]
     },
     "pyanalyze": {
-      "cli_arguments": [],
+      "cli_arguments": ["--experimental-string-processing"],
       "expect_formatting_changes": false,
       "git_clone_url": "https://github.com/quora/pyanalyze.git",
       "long_checkout": false,
       "py_versions": ["all"]
     },
     "pyramid": {
-      "cli_arguments": [],
+      "cli_arguments": ["--experimental-string-processing"],
       "expect_formatting_changes": true,
       "git_clone_url": "https://github.com/Pylons/pyramid.git",
       "long_checkout": false,
       "py_versions": ["all"]
     },
     "ptr": {
-      "cli_arguments": [],
+      "cli_arguments": ["--experimental-string-processing"],
       "expect_formatting_changes": true,
       "git_clone_url": "https://github.com/facebookincubator/ptr.git",
       "long_checkout": false,
       "py_versions": ["all"]
     },
     "pytest": {
-      "cli_arguments": [],
-      "expect_formatting_changes": false,
+      "cli_arguments": ["--experimental-string-processing"],
+      "expect_formatting_changes": true,
       "git_clone_url": "https://github.com/pytest-dev/pytest.git",
       "long_checkout": false,
       "py_versions": ["all"]
     },
     "sqlalchemy": {
+      "no_cli_args_reason": "breaks black with new string parsing - #2188",
       "cli_arguments": [],
       "expect_formatting_changes": true,
       "git_clone_url": "https://github.com/sqlalchemy/sqlalchemy.git",
@@ -111,28 +112,28 @@
       "py_versions": ["all"]
     },
     "tox": {
-      "cli_arguments": [],
-      "expect_formatting_changes": false,
+      "cli_arguments": ["--experimental-string-processing"],
+      "expect_formatting_changes": true,
       "git_clone_url": "https://github.com/tox-dev/tox.git",
       "long_checkout": false,
       "py_versions": ["all"]
     },
     "typeshed": {
-      "cli_arguments": [],
+      "cli_arguments": ["--experimental-string-processing"],
       "expect_formatting_changes": true,
       "git_clone_url": "https://github.com/python/typeshed.git",
       "long_checkout": false,
       "py_versions": ["all"]
     },
     "virtualenv": {
-      "cli_arguments": [],
-      "expect_formatting_changes": false,
+      "cli_arguments": ["--experimental-string-processing"],
+      "expect_formatting_changes": true,
       "git_clone_url": "https://github.com/pypa/virtualenv.git",
       "long_checkout": false,
       "py_versions": ["all"]
     },
     "warehouse": {
-      "cli_arguments": [],
+      "cli_arguments": ["--experimental-string-processing"],
       "expect_formatting_changes": true,
       "git_clone_url": "https://github.com/pypa/warehouse.git",
       "long_checkout": false,

From 5316836393682c6ec6a05d69c549d8167f46d8f6 Mon Sep 17 00:00:00 2001
From: Shota Ray Imaki <shota.imaki.0801@gmail.com>
Date: Thu, 6 May 2021 11:25:43 +0900
Subject: [PATCH 0178/1034] Simplify GitHub Action entrypoint (#2119)

This commit simplifies entrypoint.sh for GitHub Actions by removing
duplication of args and black_args (cf. #1909).

The reason why #1909 uses the input id black_args is to avoid an overlap
with args, but this naming seems redundant. So let me suggest option
and src, which are consistent with CLI. Backward compatibility is
guaranteed; Users can still use black_args as well.

Commit history pre-merge:
* Simplify GitHub Action entrypoint (#1909)
* Fix prettier
* Emit a warning message when `black_args` is used

  This deprecation should be visible in GitHub Action's UI now.

  Co-authored-by: Shota Ray Imaki <shota.imaki.0801@gmail.com>
  Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 README.md            | 14 ++++++++------
 action.yml           | 12 +++++++++++-
 action/entrypoint.sh | 21 ++++++---------------
 3 files changed, 25 insertions(+), 22 deletions(-)

diff --git a/README.md b/README.md
index 696bfa7e064..6443569d0d0 100644
--- a/README.md
+++ b/README.md
@@ -425,15 +425,17 @@ jobs:
       - uses: actions/checkout@v2
       - uses: actions/setup-python@v2
       - uses: psf/black@stable
-        with:
-          args: ". --check"
 ```
 
-### Inputs
+You may use `options` (Default is `'--check --diff'`) and `src` (Default is `'.'`) as
+follows:
 
-#### `black_args`
-
-**optional**: Black input arguments. Defaults to `. --check --diff`.
+```yaml
+- uses: psf/black@stable
+  with:
+    options: "--check --verbose"
+    src: "./src"
+```
 
 ## Ignoring unmodified files
 
diff --git a/action.yml b/action.yml
index 59b16a9fb6c..827e971801b 100644
--- a/action.yml
+++ b/action.yml
@@ -2,8 +2,18 @@ name: "Black"
 description: "The uncompromising Python code formatter."
 author: "Łukasz Langa and contributors to Black"
 inputs:
+  options:
+    description:
+      "Options passed to black. Use `black --help` to see available options. Default:
+      '--check'"
+    required: false
+    default: "--check --diff"
+  src:
+    description: "Source to run black. Default: '.'"
+    required: false
+    default: "."
   black_args:
-    description: "Black input arguments."
+    description: "[DEPRECATED] Black input arguments."
     required: false
     default: ""
 branding:
diff --git a/action/entrypoint.sh b/action/entrypoint.sh
index 50f9472cc5f..fc66e24f53a 100755
--- a/action/entrypoint.sh
+++ b/action/entrypoint.sh
@@ -1,17 +1,8 @@
-#!/bin/bash
-set -e
+#!/bin/bash -e
 
-# If no arguments are given use current working directory
-black_args=(".")
-if [ "$#" -eq 0 ] && [ "${INPUT_BLACK_ARGS}" != "" ]; then
-  black_args+=(${INPUT_BLACK_ARGS})
-elif [ "$#" -ne 0 ] && [ "${INPUT_BLACK_ARGS}" != "" ]; then
-  black_args+=($* ${INPUT_BLACK_ARGS})
-elif [ "$#" -ne 0 ] && [ "${INPUT_BLACK_ARGS}" == "" ]; then
-  black_args+=($*)
-else
-  # Default (if no args provided).
-  black_args+=("--check" "--diff")
-fi
+if [ -n $INPUT_BLACK_ARGS ]; then
+  echo '::warning::Input `with.black_args` is deprecated. Use `with.options` and `with.src` instead.'
+  black $INPUT_BLACK_ARGS
+  exit $?
 
-sh -c "black . ${black_args[*]}"
+black $INPUT_OPTIONS $INPUT_SRC

From 4b7b5ed5b8630a906e2ef3a405134131651a251e Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Thu, 6 May 2021 15:21:13 -0400
Subject: [PATCH 0179/1034] Fix broken Action entrypoint (#2202)

---
 action/entrypoint.sh | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/action/entrypoint.sh b/action/entrypoint.sh
index fc66e24f53a..30bf4eb688f 100755
--- a/action/entrypoint.sh
+++ b/action/entrypoint.sh
@@ -1,8 +1,9 @@
 #!/bin/bash -e
 
-if [ -n $INPUT_BLACK_ARGS ]; then
+if [ -n "$INPUT_BLACK_ARGS" ]; then
   echo '::warning::Input `with.black_args` is deprecated. Use `with.options` and `with.src` instead.'
   black $INPUT_BLACK_ARGS
   exit $?
+fi
 
 black $INPUT_OPTIONS $INPUT_SRC

From 1fe2efd8573a63ffc76c69320720d349b21897da Mon Sep 17 00:00:00 2001
From: Kaleb Barrett <dev.ktbarrett@gmail.com>
Date: Fri, 7 May 2021 07:54:21 -0500
Subject: [PATCH 0180/1034] Do not use gitignore if explicitly passing excludes
 (#2170)

Closes #2164.

Changes behavior of how .gitignore is handled. With this change, the rules in .gitignore are only used as a fallback if no exclusion rule is explicitly passed on the command line or in pyproject.toml. Previously they were used regardless if explicit exclusion rules were specified, preventing any overriding of .gitignore rules.

Those that depend only on .gitignore for their exclusion rules will not be affected. Those that use both .gitignore and exclude will find that exclude will act more like actually specifying exclude and not just another extra-excludes. If the previous behavior was desired, they should move their rules from exclude to extra-excludes.
---
 CHANGES.md                                    |  3 ++
 src/black/__init__.py                         | 25 ++++++++++-------
 tests/data/include_exclude_tests/.gitignore   |  1 +
 .../data/include_exclude_tests/pyproject.toml |  3 ++
 tests/test_black.py                           | 28 +++++++++++++++++++
 5 files changed, 50 insertions(+), 10 deletions(-)
 create mode 100644 tests/data/include_exclude_tests/.gitignore
 create mode 100644 tests/data/include_exclude_tests/pyproject.toml

diff --git a/CHANGES.md b/CHANGES.md
index becf69904fb..b81e6eb4411 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -22,6 +22,9 @@
   [circumstances](https://github.com/psf/black/blob/master/docs/the_black_code_style.md#pragmatism)
   in which _Black_ may change the AST (#2159)
 
+- Allow `.gitignore` rules to be overridden by specifying `exclude` in `pyproject.toml`
+  or on the command line. (#2170)
+
 #### _Packaging_
 
 - Install `primer.json` (used by `black-primer` by default) with black. (#2154)
diff --git a/src/black/__init__.py b/src/black/__init__.py
index cf257876c03..e47aa21d435 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -492,15 +492,15 @@ def validate_regex(
 @click.option(
     "--exclude",
     type=str,
-    default=DEFAULT_EXCLUDES,
     callback=validate_regex,
     help=(
         "A regular expression that matches files and directories that should be"
         " excluded on recursive searches. An empty value means no paths are excluded."
         " Use forward slashes for directories on all platforms (Windows, too)."
-        " Exclusions are calculated first, inclusions later."
+        " Exclusions are calculated first, inclusions later. [default:"
+        f" {DEFAULT_EXCLUDES}]"
     ),
-    show_default=True,
+    show_default=False,
 )
 @click.option(
     "--extend-exclude",
@@ -587,7 +587,7 @@ def main(
     quiet: bool,
     verbose: bool,
     include: Pattern,
-    exclude: Pattern,
+    exclude: Optional[Pattern],
     extend_exclude: Optional[Pattern],
     force_exclude: Optional[Pattern],
     stdin_filename: Optional[str],
@@ -662,7 +662,7 @@ def get_sources(
     quiet: bool,
     verbose: bool,
     include: Pattern[str],
-    exclude: Pattern[str],
+    exclude: Optional[Pattern[str]],
     extend_exclude: Optional[Pattern[str]],
     force_exclude: Optional[Pattern[str]],
     report: "Report",
@@ -673,7 +673,12 @@ def get_sources(
     root = find_project_root(src)
     sources: Set[Path] = set()
     path_empty(src, "No Path provided. Nothing to do 😴", quiet, verbose, ctx)
-    gitignore = get_gitignore(root)
+
+    if exclude is None:
+        exclude = re_compile_maybe_verbose(DEFAULT_EXCLUDES)
+        gitignore = get_gitignore(root)
+    else:
+        gitignore = None
 
     for s in src:
         if s == "-" and stdin_filename:
@@ -6215,12 +6220,12 @@ def path_is_excluded(
 def gen_python_files(
     paths: Iterable[Path],
     root: Path,
-    include: Optional[Pattern[str]],
+    include: Pattern[str],
     exclude: Pattern[str],
     extend_exclude: Optional[Pattern[str]],
     force_exclude: Optional[Pattern[str]],
     report: "Report",
-    gitignore: PathSpec,
+    gitignore: Optional[PathSpec],
 ) -> Iterator[Path]:
     """Generate all files under `path` whose paths are not excluded by the
     `exclude_regex`, `extend_exclude`, or `force_exclude` regexes,
@@ -6236,8 +6241,8 @@ def gen_python_files(
         if normalized_path is None:
             continue
 
-        # First ignore files matching .gitignore
-        if gitignore.match_file(normalized_path):
+        # First ignore files matching .gitignore, if passed
+        if gitignore is not None and gitignore.match_file(normalized_path):
             report.path_ignored(child, "matches the .gitignore file content")
             continue
 
diff --git a/tests/data/include_exclude_tests/.gitignore b/tests/data/include_exclude_tests/.gitignore
new file mode 100644
index 00000000000..91f34560522
--- /dev/null
+++ b/tests/data/include_exclude_tests/.gitignore
@@ -0,0 +1 @@
+dont_exclude/
diff --git a/tests/data/include_exclude_tests/pyproject.toml b/tests/data/include_exclude_tests/pyproject.toml
new file mode 100644
index 00000000000..9ba7ec26980
--- /dev/null
+++ b/tests/data/include_exclude_tests/pyproject.toml
@@ -0,0 +1,3 @@
+[build-system]
+requires = ["setuptools>=41.0", "setuptools-scm", "wheel"]
+build-backend = "setuptools.build_meta"
diff --git a/tests/test_black.py b/tests/test_black.py
index 7d855cab3d3..9b2bfcd740e 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -1418,6 +1418,32 @@ def test_include_exclude(self) -> None:
         )
         self.assertEqual(sorted(expected), sorted(sources))
 
+    def test_gitingore_used_as_default(self) -> None:
+        path = Path(THIS_DIR / "data" / "include_exclude_tests")
+        include = re.compile(r"\.pyi?$")
+        extend_exclude = re.compile(r"/exclude/")
+        src = str(path / "b/")
+        report = black.Report()
+        expected: List[Path] = [
+            path / "b/.definitely_exclude/a.py",
+            path / "b/.definitely_exclude/a.pyi",
+        ]
+        sources = list(
+            black.get_sources(
+                ctx=FakeContext(),
+                src=(src,),
+                quiet=True,
+                verbose=False,
+                include=include,
+                exclude=None,
+                extend_exclude=extend_exclude,
+                force_exclude=None,
+                report=report,
+                stdin_filename=None,
+            )
+        )
+        self.assertEqual(sorted(expected), sorted(sources))
+
     @patch("black.find_project_root", lambda *args: THIS_DIR.resolve())
     def test_exclude_for_issue_1572(self) -> None:
         # Exclude shouldn't touch files that were explicitly given to Black through the
@@ -1705,6 +1731,8 @@ def test_empty_include(self) -> None:
             Path(path / "b/.definitely_exclude/a.pie"),
             Path(path / "b/.definitely_exclude/a.py"),
             Path(path / "b/.definitely_exclude/a.pyi"),
+            Path(path / ".gitignore"),
+            Path(path / "pyproject.toml"),
         ]
         this_abs = THIS_DIR.resolve()
         sources.extend(

From e4b4fb02b91e0f5a60a9678604653aecedff513b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C5=81ukasz=20Langa?= <lukasz@langa.pl>
Date: Fri, 7 May 2021 15:03:13 +0200
Subject: [PATCH 0181/1034] Use optional tests for "no_python2" to simplify
 local testing (#2203)

---
 pyproject.toml      |   5 +-
 tests/conftest.py   |   1 +
 tests/optional.py   | 119 ++++++++++++++++++++++++++++++++++++++++++++
 tests/test_black.py |  10 ++--
 tox.ini             |   4 +-
 5 files changed, 133 insertions(+), 6 deletions(-)
 create mode 100644 tests/conftest.py
 create mode 100644 tests/optional.py

diff --git a/pyproject.toml b/pyproject.toml
index ca75f8f92ef..e89cc7a6c9b 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -27,4 +27,7 @@ requires = ["setuptools>=41.0", "setuptools-scm", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [tool.pytest.ini_options]
-markers = ['python2', "without_python2"]
\ No newline at end of file
+# Option below requires `tests/optional.py`
+optional-tests = [
+  "no_python2: run when `python2` extra NOT installed",
+]
\ No newline at end of file
diff --git a/tests/conftest.py b/tests/conftest.py
new file mode 100644
index 00000000000..67517268d1b
--- /dev/null
+++ b/tests/conftest.py
@@ -0,0 +1 @@
+pytest_plugins = ["tests.optional"]
diff --git a/tests/optional.py b/tests/optional.py
new file mode 100644
index 00000000000..e12b94cd29e
--- /dev/null
+++ b/tests/optional.py
@@ -0,0 +1,119 @@
+"""
+Allows configuring optional test markers in config, see pyproject.toml.
+
+Run optional tests with `pytest --run-optional=...`.
+
+Mark tests to run only if an optional test ISN'T selected by prepending the mark with
+"no_".
+
+You can specify a "no_" prefix straight in config, in which case you can mark tests
+to run when this tests ISN'T selected by omitting the "no_" prefix.
+
+Specifying the name of the default behavior in `--run-optional=` is harmless.
+
+Adapted from https://pypi.org/project/pytest-optional-tests/, (c) 2019 Reece Hart
+"""
+
+from functools import lru_cache
+import itertools
+import logging
+import re
+from typing import FrozenSet, List, Set, TYPE_CHECKING
+
+import pytest
+from _pytest.store import StoreKey
+
+log = logging.getLogger(__name__)
+
+
+if TYPE_CHECKING:
+    from _pytest.config.argparsing import Parser
+    from _pytest.config import Config
+    from _pytest.mark.structures import MarkDecorator
+    from _pytest.nodes import Node
+
+
+ALL_POSSIBLE_OPTIONAL_MARKERS = StoreKey[FrozenSet[str]]()
+ENABLED_OPTIONAL_MARKERS = StoreKey[FrozenSet[str]]()
+
+
+def pytest_addoption(parser: "Parser") -> None:
+    group = parser.getgroup("collect")
+    group.addoption(
+        "--run-optional",
+        action="append",
+        dest="run_optional",
+        default=None,
+        help="Optional test markers to run; comma-separated",
+    )
+    parser.addini("optional-tests", "List of optional tests markers", "linelist")
+
+
+def pytest_configure(config: "Config") -> None:
+    """Optional tests are markers.
+
+    Use the syntax in https://docs.pytest.org/en/stable/mark.html#registering-marks.
+    """
+    ot_ini = config.inicfg.get("optional-tests") or []
+    ot_markers = set()
+    ot_run: Set[str] = set()
+    if isinstance(ot_ini, str):
+        ot_ini = ot_ini.strip().split("\n")
+    marker_re = re.compile(r"^\s*(?P<no>no_)?(?P<marker>\w+)(:\s*(?P<description>.*))?")
+    for ot in ot_ini:
+        m = marker_re.match(ot)
+        if not m:
+            raise ValueError(f"{ot!r} doesn't match pytest marker syntax")
+
+        marker = (m.group("no") or "") + m.group("marker")
+        description = m.group("description")
+        config.addinivalue_line("markers", f"{marker}: {description}")
+        config.addinivalue_line(
+            "markers", f"{no(marker)}: run when `{marker}` not passed"
+        )
+        ot_markers.add(marker)
+
+    # collect requested optional tests
+    passed_args = config.getoption("run_optional")
+    if passed_args:
+        ot_run.update(itertools.chain.from_iterable(a.split(",") for a in passed_args))
+    ot_run |= {no(excluded) for excluded in ot_markers - ot_run}
+    ot_markers |= {no(m) for m in ot_markers}
+
+    log.info("optional tests to run:", ot_run)
+    unknown_tests = ot_run - ot_markers
+    if unknown_tests:
+        raise ValueError(f"Unknown optional tests wanted: {unknown_tests!r}")
+
+    store = config._store
+    store[ALL_POSSIBLE_OPTIONAL_MARKERS] = frozenset(ot_markers)
+    store[ENABLED_OPTIONAL_MARKERS] = frozenset(ot_run)
+
+
+def pytest_collection_modifyitems(config: "Config", items: "List[Node]") -> None:
+    store = config._store
+    all_possible_optional_markers = store[ALL_POSSIBLE_OPTIONAL_MARKERS]
+    enabled_optional_markers = store[ENABLED_OPTIONAL_MARKERS]
+
+    for item in items:
+        all_markers_on_test = set(m.name for m in item.iter_markers())
+        optional_markers_on_test = all_markers_on_test & all_possible_optional_markers
+        if not optional_markers_on_test or (
+            optional_markers_on_test & enabled_optional_markers
+        ):
+            continue
+        log.info("skipping non-requested optional", item)
+        item.add_marker(skip_mark(frozenset(optional_markers_on_test)))
+
+
+@lru_cache()
+def skip_mark(tests: FrozenSet[str]) -> "MarkDecorator":
+    names = ", ".join(sorted(tests))
+    return pytest.mark.skip(reason=f"Marked with disabled optional tests ({names})")
+
+
+@lru_cache()
+def no(name: str) -> str:
+    if name.startswith("no_"):
+        return name[len("no_") :]
+    return "no_" + name
diff --git a/tests/test_black.py b/tests/test_black.py
index 9b2bfcd740e..b8e526a953e 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -460,11 +460,15 @@ def test_skip_magic_trailing_comma(self) -> None:
             )
             self.assertEqual(expected, actual, msg)
 
-    @pytest.mark.without_python2
+    @pytest.mark.no_python2
     def test_python2_should_fail_without_optional_install(self) -> None:
-        # python 3.7 and below will install typed-ast and will be able to parse Python 2
         if sys.version_info < (3, 8):
-            return
+            self.skipTest(
+                "Python 3.6 and 3.7 will install typed-ast to work and as such will be"
+                " able to parse Python 2 syntax without explicitly specifying the"
+                " python2 extra"
+            )
+
         source = "x = 1234l"
         tmp_file = Path(black.dump_to_file(source))
         try:
diff --git a/tox.ini b/tox.ini
index cbb0f75d145..317bf485375 100644
--- a/tox.ini
+++ b/tox.ini
@@ -9,9 +9,9 @@ deps =
 commands =
     pip install -e .[d]
     coverage erase
-    coverage run -m pytest tests -m "not python2" {posargs}
+    coverage run -m pytest tests --run-optional=no_python2 {posargs}
     pip install -e .[d,python2]
-    coverage run -m pytest tests -m "not without_python2" {posargs}
+    coverage run -m pytest tests --run-optional=python2 {posargs}
     coverage report
 
 [testenv:fuzz]

From d0e06b53b09248be34c1d5c0fa8f050bff1d201c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C5=81ukasz=20Langa?= <lukasz@langa.pl>
Date: Fri, 7 May 2021 16:33:36 +0200
Subject: [PATCH 0182/1034] Mark blackd tests with the `blackd` optional marker
 (#2204)

This is a follow-up of #2203 that uses a pytest marker instead of a bunch of
`skipUnless`.  Similarly to the Python 2 tests, they are running by default and
will crash on an unsuspecting contributor with missing dependencies.  This is
by design, we WANT contributors to test everything.  Unless we actually don't
and then we can run:

  pytest --run-optional=no_blackd

Relatedly, bump required aiohttp to 3.6.0 at least to get rid of expected
failures on Python 3.8 (see 6b5eb7d4651c7333cc3f5df4bf7aa7a1f1ffb45b).
---
 Pipfile              |  2 +-
 pyproject.toml       |  1 +
 setup.py             |  2 +-
 tests/test_blackd.py | 32 +++-----------------------------
 tests/util.py        | 14 +-------------
 5 files changed, 7 insertions(+), 44 deletions(-)

diff --git a/Pipfile b/Pipfile
index 40f3d607653..68562f5e53f 100644
--- a/Pipfile
+++ b/Pipfile
@@ -20,7 +20,7 @@ wheel = ">=0.31.1"
 black = {editable = true, extras = ["d"], path = "."}
 
 [packages]
-aiohttp = ">=3.3.2"
+aiohttp = ">=3.6.0"
 aiohttp-cors = "*"
 appdirs = "*"
 click = ">=7.1.2"
diff --git a/pyproject.toml b/pyproject.toml
index e89cc7a6c9b..4d6777ef6ec 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -30,4 +30,5 @@ build-backend = "setuptools.build_meta"
 # Option below requires `tests/optional.py`
 optional-tests = [
   "no_python2: run when `python2` extra NOT installed",
+  "no_blackd: run when `d` extra NOT installed",
 ]
\ No newline at end of file
diff --git a/setup.py b/setup.py
index f1792a46fe8..af93d0f453a 100644
--- a/setup.py
+++ b/setup.py
@@ -83,7 +83,7 @@ def get_long_description() -> str:
         "mypy_extensions>=0.4.3",
     ],
     extras_require={
-        "d": ["aiohttp>=3.3.2", "aiohttp-cors"],
+        "d": ["aiohttp>=3.6.0", "aiohttp-cors"],
         "colorama": ["colorama>=0.4.3"],
         "python2": ["typed-ast>=1.4.2"],
     },
diff --git a/tests/test_blackd.py b/tests/test_blackd.py
index 9127297c54f..9ca19d49dc6 100644
--- a/tests/test_blackd.py
+++ b/tests/test_blackd.py
@@ -1,10 +1,10 @@
 import re
-import unittest
 from unittest.mock import patch
 
 from click.testing import CliRunner
+import pytest
 
-from tests.util import read_data, DETERMINISTIC_HEADER, skip_if_exception
+from tests.util import read_data, DETERMINISTIC_HEADER
 
 try:
     import blackd
@@ -16,8 +16,8 @@
     has_blackd_deps = True
 
 
+@pytest.mark.blackd
 class BlackDTestCase(AioHTTPTestCase):
-    @unittest.skipUnless(has_blackd_deps, "blackd's dependencies are not installed")
     def test_blackd_main(self) -> None:
         with patch("blackd.web.run_app"):
             result = CliRunner().invoke(blackd.main, [])
@@ -28,10 +28,6 @@ def test_blackd_main(self) -> None:
     async def get_application(self) -> web.Application:
         return blackd.make_app()
 
-    # TODO: remove these decorators once the below is released
-    # https://github.com/aio-libs/aiohttp/pull/3727
-    @skip_if_exception("ClientOSError")
-    @unittest.skipUnless(has_blackd_deps, "blackd's dependencies are not installed")
     @unittest_run_loop
     async def test_blackd_request_needs_formatting(self) -> None:
         response = await self.client.post("/", data=b"print('hello world')")
@@ -39,16 +35,12 @@ async def test_blackd_request_needs_formatting(self) -> None:
         self.assertEqual(response.charset, "utf8")
         self.assertEqual(await response.read(), b'print("hello world")\n')
 
-    @skip_if_exception("ClientOSError")
-    @unittest.skipUnless(has_blackd_deps, "blackd's dependencies are not installed")
     @unittest_run_loop
     async def test_blackd_request_no_change(self) -> None:
         response = await self.client.post("/", data=b'print("hello world")\n')
         self.assertEqual(response.status, 204)
         self.assertEqual(await response.read(), b"")
 
-    @skip_if_exception("ClientOSError")
-    @unittest.skipUnless(has_blackd_deps, "blackd's dependencies are not installed")
     @unittest_run_loop
     async def test_blackd_request_syntax_error(self) -> None:
         response = await self.client.post("/", data=b"what even ( is")
@@ -59,8 +51,6 @@ async def test_blackd_request_syntax_error(self) -> None:
             msg=f"Expected error to start with 'Cannot parse', got {repr(content)}",
         )
 
-    @skip_if_exception("ClientOSError")
-    @unittest.skipUnless(has_blackd_deps, "blackd's dependencies are not installed")
     @unittest_run_loop
     async def test_blackd_unsupported_version(self) -> None:
         response = await self.client.post(
@@ -68,8 +58,6 @@ async def test_blackd_unsupported_version(self) -> None:
         )
         self.assertEqual(response.status, 501)
 
-    @skip_if_exception("ClientOSError")
-    @unittest.skipUnless(has_blackd_deps, "blackd's dependencies are not installed")
     @unittest_run_loop
     async def test_blackd_supported_version(self) -> None:
         response = await self.client.post(
@@ -77,8 +65,6 @@ async def test_blackd_supported_version(self) -> None:
         )
         self.assertEqual(response.status, 200)
 
-    @skip_if_exception("ClientOSError")
-    @unittest.skipUnless(has_blackd_deps, "blackd's dependencies are not installed")
     @unittest_run_loop
     async def test_blackd_invalid_python_variant(self) -> None:
         async def check(header_value: str, expected_status: int = 400) -> None:
@@ -97,8 +83,6 @@ async def check(header_value: str, expected_status: int = 400) -> None:
         await check("pypy3.0")
         await check("jython3.4")
 
-    @skip_if_exception("ClientOSError")
-    @unittest.skipUnless(has_blackd_deps, "blackd's dependencies are not installed")
     @unittest_run_loop
     async def test_blackd_pyi(self) -> None:
         source, expected = read_data("stub.pyi")
@@ -108,8 +92,6 @@ async def test_blackd_pyi(self) -> None:
         self.assertEqual(response.status, 200)
         self.assertEqual(await response.text(), expected)
 
-    @skip_if_exception("ClientOSError")
-    @unittest.skipUnless(has_blackd_deps, "blackd's dependencies are not installed")
     @unittest_run_loop
     async def test_blackd_diff(self) -> None:
         diff_header = re.compile(
@@ -128,8 +110,6 @@ async def test_blackd_diff(self) -> None:
         actual = diff_header.sub(DETERMINISTIC_HEADER, actual)
         self.assertEqual(actual, expected)
 
-    @skip_if_exception("ClientOSError")
-    @unittest.skipUnless(has_blackd_deps, "blackd's dependencies are not installed")
     @unittest_run_loop
     async def test_blackd_python_variant(self) -> None:
         code = (
@@ -166,8 +146,6 @@ async def check(header_value: str, expected_status: int) -> None:
         await check("py34,py36", 204)
         await check("34", 204)
 
-    @skip_if_exception("ClientOSError")
-    @unittest.skipUnless(has_blackd_deps, "blackd's dependencies are not installed")
     @unittest_run_loop
     async def test_blackd_line_length(self) -> None:
         response = await self.client.post(
@@ -175,8 +153,6 @@ async def test_blackd_line_length(self) -> None:
         )
         self.assertEqual(response.status, 200)
 
-    @skip_if_exception("ClientOSError")
-    @unittest.skipUnless(has_blackd_deps, "blackd's dependencies are not installed")
     @unittest_run_loop
     async def test_blackd_invalid_line_length(self) -> None:
         response = await self.client.post(
@@ -184,8 +160,6 @@ async def test_blackd_invalid_line_length(self) -> None:
         )
         self.assertEqual(response.status, 400)
 
-    @skip_if_exception("ClientOSError")
-    @unittest.skipUnless(has_blackd_deps, "blackd's dependencies are not installed")
     @unittest_run_loop
     async def test_blackd_response_black_version_header(self) -> None:
         response = await self.client.post("/")
diff --git a/tests/util.py b/tests/util.py
index ad9866975ac..3670952ba8c 100644
--- a/tests/util.py
+++ b/tests/util.py
@@ -1,8 +1,7 @@
 import os
 import unittest
-from contextlib import contextmanager
 from pathlib import Path
-from typing import List, Tuple, Iterator, Any
+from typing import List, Tuple, Any
 import black
 from functools import partial
 
@@ -45,17 +44,6 @@ def assertFormatEqual(self, expected: str, actual: str) -> None:
         self.assertMultiLineEqual(expected, actual)
 
 
-@contextmanager
-def skip_if_exception(e: str) -> Iterator[None]:
-    try:
-        yield
-    except Exception as exc:
-        if exc.__class__.__name__ == e:
-            unittest.skip(f"Encountered expected exception {exc}, skipping")
-        else:
-            raise
-
-
 def read_data(name: str, data: bool = True) -> Tuple[str, str]:
     """read_data('test_name') -> 'input', 'output'"""
     if not name.endswith((".py", ".pyi", ".out", ".diff")):

From 4fc1354aeb6b217cd18dbdb2a0c41373fa9d8056 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Fri, 7 May 2021 10:41:55 -0400
Subject: [PATCH 0183/1034] Speed up test suite via distributed testing (#2196)

* Speed up test suite via distributed testing

Since we now run the test suite twice, one with Python 2 and another
without, full test runs are getting pretty slow. Let's try to
fix that with parallization.

Also use verbose mode on CI since more logs is usually better since
getting more is quite literally impossible.

The main issue we'll face with this is we'll hit
https://github.com/pytest-dev/pytest-xdist/issues/620 sometimes
(although pretty rarely). I suppose we can test this and see if how bad
this bug is for us, and revert if necessary down the line.

Also let's have some colours :tada:
---
 .coveragerc                | 1 +
 .github/workflows/test.yml | 2 +-
 test_requirements.txt      | 2 ++
 tox.ini                    | 4 ++--
 4 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/.coveragerc b/.coveragerc
index f05041ca1dc..5577e496a57 100644
--- a/.coveragerc
+++ b/.coveragerc
@@ -3,6 +3,7 @@ omit =
   src/blib2to3/*
   tests/data/*
   */site-packages/*
+  .tox/*
 
 [run]
 relative_files = True
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 03adc7f0bea..2cfbab67ce1 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -33,7 +33,7 @@ jobs:
 
       - name: Unit tests
         run: |
-          tox -e py
+          tox -e py -- -v --color=yes
 
       - name: Publish coverage to Coveralls
         # If pushed / is a pull request against main repo AND
diff --git a/test_requirements.txt b/test_requirements.txt
index a1464e90686..31ab2d05fea 100644
--- a/test_requirements.txt
+++ b/test_requirements.txt
@@ -3,5 +3,7 @@ pre-commit
 pytest >= 6.1.1
 pytest-mock >= 3.3.1
 pytest-cases >= 2.3.0
+pytest-xdist >= 2.2.1
+pytest-cov >= 2.11.1
 parameterized >= 0.7.4
 tox
diff --git a/tox.ini b/tox.ini
index 317bf485375..2379500f55a 100644
--- a/tox.ini
+++ b/tox.ini
@@ -9,9 +9,9 @@ deps =
 commands =
     pip install -e .[d]
     coverage erase
-    coverage run -m pytest tests --run-optional=no_python2 {posargs}
+    pytest tests --run-optional no_python2 --numprocesses auto --cov {posargs}
     pip install -e .[d,python2]
-    coverage run -m pytest tests --run-optional=python2 {posargs}
+    pytest tests --run-optional python2 --numprocesses auto --cov --cov-append {posargs}
     coverage report
 
 [testenv:fuzz]

From f2ea461e9e9fa5c47bb61fd72d512c748928badc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C5=81ukasz=20Langa?= <lukasz@langa.pl>
Date: Sat, 8 May 2021 11:29:47 +0200
Subject: [PATCH 0184/1034] Refactor `src/black/__init__.py` into many files
 (#2206)

* Move string-related utility to functions to strings.py, const.py
* Move Leaf/Node-related functionality to nodes.py
* Move comment-related functions to comments.py
* Move caching to cache.py and Mode/TargetVersion/Feature to mode.py
* Move some leftover functions to nodes.py, comments.py, strings.py
* Add missing files to source list for test runs
* Move line-related functionality into lines.py, brackets into brackets.py
* Move transformers to trans.py
* Move file handling, output, parsing, concurrency, debug, and report
* Move two more functions to nodes.py
* Add CHANGES
* Add numeric.py
* Add linegen.py
* More docstrings
* Include new files in tests

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 CHANGES.md               |    6 +
 src/black/__init__.py    | 6394 ++------------------------------------
 src/black/brackets.py    |  334 ++
 src/black/cache.py       |   83 +
 src/black/comments.py    |  269 ++
 src/black/concurrency.py |   39 +
 src/black/const.py       |    4 +
 src/black/debug.py       |   48 +
 src/black/files.py       |  241 ++
 src/black/linegen.py     |  984 ++++++
 src/black/lines.py       |  734 +++++
 src/black/mode.py        |  123 +
 src/black/nodes.py       |  843 +++++
 src/black/numerics.py    |   65 +
 src/black/output.py      |   83 +
 src/black/parsing.py     |  215 ++
 src/black/report.py      |  100 +
 src/black/rusty.py       |   28 +
 src/black/strings.py     |  216 ++
 src/black/trans.py       | 1925 ++++++++++++
 tests/test_black.py      |   43 +-
 tests/test_format.py     |   30 +-
 tests/util.py            |   19 +-
 23 files changed, 6586 insertions(+), 6240 deletions(-)
 create mode 100644 src/black/brackets.py
 create mode 100644 src/black/cache.py
 create mode 100644 src/black/comments.py
 create mode 100644 src/black/concurrency.py
 create mode 100644 src/black/const.py
 create mode 100644 src/black/debug.py
 create mode 100644 src/black/files.py
 create mode 100644 src/black/linegen.py
 create mode 100644 src/black/lines.py
 create mode 100644 src/black/mode.py
 create mode 100644 src/black/nodes.py
 create mode 100644 src/black/numerics.py
 create mode 100644 src/black/output.py
 create mode 100644 src/black/parsing.py
 create mode 100644 src/black/report.py
 create mode 100644 src/black/rusty.py
 create mode 100644 src/black/strings.py
 create mode 100644 src/black/trans.py

diff --git a/CHANGES.md b/CHANGES.md
index b81e6eb4411..8cbdeca44f7 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,5 +1,11 @@
 ## Change Log
 
+### Unreleased
+
+#### _Black_
+
+- Refactor `src/black/__init__.py` into many files (#2206)
+
 ### 21.5b0
 
 #### _Black_
diff --git a/src/black/__init__.py b/src/black/__init__.py
index e47aa21d435..c61bc8c1d60 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -1,167 +1,70 @@
-import ast
 import asyncio
-from abc import ABC, abstractmethod
-from collections import defaultdict
 from concurrent.futures import Executor, ThreadPoolExecutor, ProcessPoolExecutor
 from contextlib import contextmanager
 from datetime import datetime
 from enum import Enum
-from functools import lru_cache, partial, wraps
 import io
-import itertools
-import logging
 from multiprocessing import Manager, freeze_support
 import os
 from pathlib import Path
-import pickle
 import regex as re
 import signal
 import sys
-import tempfile
 import tokenize
 import traceback
 from typing import (
     Any,
-    Callable,
-    Collection,
     Dict,
     Generator,
-    Generic,
-    Iterable,
     Iterator,
     List,
     Optional,
     Pattern,
-    Sequence,
     Set,
     Sized,
     Tuple,
-    Type,
-    TypeVar,
     Union,
-    cast,
-    TYPE_CHECKING,
 )
-from mypy_extensions import mypyc_attr
 
-from appdirs import user_cache_dir
-from dataclasses import dataclass, field, replace
+from dataclasses import replace
 import click
-import toml
-
-try:
-    from typed_ast import ast3, ast27
-except ImportError:
-    if sys.version_info < (3, 8):
-        print(
-            "The typed_ast package is not installed.\n"
-            "You can install it with `python3 -m pip install typed-ast`.",
-            file=sys.stderr,
-        )
-        sys.exit(1)
-    else:
-        ast3 = ast27 = ast
 
-from pathspec import PathSpec
+from black.const import DEFAULT_LINE_LENGTH, DEFAULT_INCLUDES, DEFAULT_EXCLUDES
+from black.const import STDIN_PLACEHOLDER
+from black.nodes import STARS, syms, is_simple_decorator_expression
+from black.lines import Line, EmptyLineTracker
+from black.linegen import transform_line, LineGenerator, LN
+from black.comments import normalize_fmt_off
+from black.mode import Mode, TargetVersion
+from black.mode import Feature, supports_feature, VERSION_TO_FEATURES
+from black.cache import read_cache, write_cache, get_cache_info, filter_cached, Cache
+from black.concurrency import cancel, shutdown
+from black.output import dump_to_file, diff, color_diff, out, err
+from black.report import Report, Changed
+from black.files import find_project_root, find_pyproject_toml, parse_pyproject_toml
+from black.files import gen_python_files, get_gitignore, normalize_path_maybe_ignore
+from black.files import wrap_stream_for_windows
+from black.parsing import InvalidInput  # noqa F401
+from black.parsing import lib2to3_parse, parse_ast, stringify_ast
+
 
 # lib2to3 fork
-from blib2to3.pytree import Node, Leaf, type_repr
-from blib2to3 import pygram, pytree
-from blib2to3.pgen2 import driver, token
-from blib2to3.pgen2.grammar import Grammar
-from blib2to3.pgen2.parse import ParseError
+from blib2to3.pytree import Node, Leaf
+from blib2to3.pgen2 import token
 
 from _black_version import version as __version__
 
-if sys.version_info < (3, 8):
-    from typing_extensions import Final
-else:
-    from typing import Final
-
-if TYPE_CHECKING:
-    import colorama  # noqa: F401
-
-DEFAULT_LINE_LENGTH = 88
-DEFAULT_EXCLUDES = r"/(\.direnv|\.eggs|\.git|\.hg|\.mypy_cache|\.nox|\.tox|\.venv|venv|\.svn|_build|buck-out|build|dist)/"  # noqa: B950
-DEFAULT_INCLUDES = r"\.pyi?$"
-CACHE_DIR = Path(user_cache_dir("black", version=__version__))
-STDIN_PLACEHOLDER = "__BLACK_STDIN_FILENAME__"
-
-STRING_PREFIX_CHARS: Final = "furbFURB"  # All possible string prefix characters.
-
 
 # types
 FileContent = str
 Encoding = str
 NewLine = str
-Depth = int
-NodeType = int
-ParserState = int
-LeafID = int
-StringID = int
-Priority = int
-Index = int
-LN = Union[Leaf, Node]
-Transformer = Callable[["Line", Collection["Feature"]], Iterator["Line"]]
-Timestamp = float
-FileSize = int
-CacheInfo = Tuple[Timestamp, FileSize]
-Cache = Dict[str, CacheInfo]
-out = partial(click.secho, bold=True, err=True)
-err = partial(click.secho, fg="red", err=True)
-
-pygram.initialize(CACHE_DIR)
-syms = pygram.python_symbols
 
 
 class NothingChanged(UserWarning):
     """Raised when reformatted code is the same as source."""
 
 
-class CannotTransform(Exception):
-    """Base class for errors raised by Transformers."""
-
-
-class CannotSplit(CannotTransform):
-    """A readable split that fits the allotted line length is impossible."""
-
-
-class InvalidInput(ValueError):
-    """Raised when input source code fails all parse attempts."""
-
-
-class BracketMatchError(KeyError):
-    """Raised when an opening bracket is unable to be matched to a closing bracket."""
-
-
-T = TypeVar("T")
-E = TypeVar("E", bound=Exception)
-
-
-class Ok(Generic[T]):
-    def __init__(self, value: T) -> None:
-        self._value = value
-
-    def ok(self) -> T:
-        return self._value
-
-
-class Err(Generic[E]):
-    def __init__(self, e: E) -> None:
-        self._e = e
-
-    def err(self) -> E:
-        return self._e
-
-
-# The 'Result' return type is used to implement an error-handling model heavily
-# influenced by that used by the Rust programming language
-# (see https://doc.rust-lang.org/book/ch09-00-error-handling.html).
-Result = Union[Ok[T], Err[E]]
-TResult = Result[T, CannotTransform]  # (T)ransform Result
-TMatchResult = TResult[Index]
-
-
 class WriteBack(Enum):
     NO = 0
     YES = 1
@@ -182,158 +85,10 @@ def from_configuration(
         return cls.DIFF if diff else cls.YES
 
 
-class Changed(Enum):
-    NO = 0
-    CACHED = 1
-    YES = 2
-
-
-class TargetVersion(Enum):
-    PY27 = 2
-    PY33 = 3
-    PY34 = 4
-    PY35 = 5
-    PY36 = 6
-    PY37 = 7
-    PY38 = 8
-    PY39 = 9
-
-    def is_python2(self) -> bool:
-        return self is TargetVersion.PY27
-
-
-class Feature(Enum):
-    # All string literals are unicode
-    UNICODE_LITERALS = 1
-    F_STRINGS = 2
-    NUMERIC_UNDERSCORES = 3
-    TRAILING_COMMA_IN_CALL = 4
-    TRAILING_COMMA_IN_DEF = 5
-    # The following two feature-flags are mutually exclusive, and exactly one should be
-    # set for every version of python.
-    ASYNC_IDENTIFIERS = 6
-    ASYNC_KEYWORDS = 7
-    ASSIGNMENT_EXPRESSIONS = 8
-    POS_ONLY_ARGUMENTS = 9
-    RELAXED_DECORATORS = 10
-    FORCE_OPTIONAL_PARENTHESES = 50
-
-
-VERSION_TO_FEATURES: Dict[TargetVersion, Set[Feature]] = {
-    TargetVersion.PY27: {Feature.ASYNC_IDENTIFIERS},
-    TargetVersion.PY33: {Feature.UNICODE_LITERALS, Feature.ASYNC_IDENTIFIERS},
-    TargetVersion.PY34: {Feature.UNICODE_LITERALS, Feature.ASYNC_IDENTIFIERS},
-    TargetVersion.PY35: {
-        Feature.UNICODE_LITERALS,
-        Feature.TRAILING_COMMA_IN_CALL,
-        Feature.ASYNC_IDENTIFIERS,
-    },
-    TargetVersion.PY36: {
-        Feature.UNICODE_LITERALS,
-        Feature.F_STRINGS,
-        Feature.NUMERIC_UNDERSCORES,
-        Feature.TRAILING_COMMA_IN_CALL,
-        Feature.TRAILING_COMMA_IN_DEF,
-        Feature.ASYNC_IDENTIFIERS,
-    },
-    TargetVersion.PY37: {
-        Feature.UNICODE_LITERALS,
-        Feature.F_STRINGS,
-        Feature.NUMERIC_UNDERSCORES,
-        Feature.TRAILING_COMMA_IN_CALL,
-        Feature.TRAILING_COMMA_IN_DEF,
-        Feature.ASYNC_KEYWORDS,
-    },
-    TargetVersion.PY38: {
-        Feature.UNICODE_LITERALS,
-        Feature.F_STRINGS,
-        Feature.NUMERIC_UNDERSCORES,
-        Feature.TRAILING_COMMA_IN_CALL,
-        Feature.TRAILING_COMMA_IN_DEF,
-        Feature.ASYNC_KEYWORDS,
-        Feature.ASSIGNMENT_EXPRESSIONS,
-        Feature.POS_ONLY_ARGUMENTS,
-    },
-    TargetVersion.PY39: {
-        Feature.UNICODE_LITERALS,
-        Feature.F_STRINGS,
-        Feature.NUMERIC_UNDERSCORES,
-        Feature.TRAILING_COMMA_IN_CALL,
-        Feature.TRAILING_COMMA_IN_DEF,
-        Feature.ASYNC_KEYWORDS,
-        Feature.ASSIGNMENT_EXPRESSIONS,
-        Feature.RELAXED_DECORATORS,
-        Feature.POS_ONLY_ARGUMENTS,
-    },
-}
-
-
-@dataclass
-class Mode:
-    target_versions: Set[TargetVersion] = field(default_factory=set)
-    line_length: int = DEFAULT_LINE_LENGTH
-    string_normalization: bool = True
-    is_pyi: bool = False
-    magic_trailing_comma: bool = True
-    experimental_string_processing: bool = False
-
-    def get_cache_key(self) -> str:
-        if self.target_versions:
-            version_str = ",".join(
-                str(version.value)
-                for version in sorted(self.target_versions, key=lambda v: v.value)
-            )
-        else:
-            version_str = "-"
-        parts = [
-            version_str,
-            str(self.line_length),
-            str(int(self.string_normalization)),
-            str(int(self.is_pyi)),
-            str(int(self.magic_trailing_comma)),
-            str(int(self.experimental_string_processing)),
-        ]
-        return ".".join(parts)
-
-
 # Legacy name, left for integrations.
 FileMode = Mode
 
 
-def supports_feature(target_versions: Set[TargetVersion], feature: Feature) -> bool:
-    return all(feature in VERSION_TO_FEATURES[version] for version in target_versions)
-
-
-def find_pyproject_toml(path_search_start: Tuple[str, ...]) -> Optional[str]:
-    """Find the absolute filepath to a pyproject.toml if it exists"""
-    path_project_root = find_project_root(path_search_start)
-    path_pyproject_toml = path_project_root / "pyproject.toml"
-    if path_pyproject_toml.is_file():
-        return str(path_pyproject_toml)
-
-    try:
-        path_user_pyproject_toml = find_user_pyproject_toml()
-        return (
-            str(path_user_pyproject_toml)
-            if path_user_pyproject_toml.is_file()
-            else None
-        )
-    except PermissionError as e:
-        # We do not have access to the user-level config directory, so ignore it.
-        err(f"Ignoring user configuration directory due to {e!r}")
-        return None
-
-
-def parse_pyproject_toml(path_config: str) -> Dict[str, Any]:
-    """Parse a pyproject toml file, pulling out relevant parts for Black
-
-    If parsing fails, will raise a toml.TomlDecodeError
-    """
-    pyproject_toml = toml.load(path_config)
-    config = pyproject_toml.get("tool", {}).get("black", {})
-    return {k.replace("--", "").replace("-", "_"): v for k, v in config.items()}
-
-
 def read_pyproject_toml(
     ctx: click.Context, param: click.Parameter, value: Optional[str]
 ) -> Optional[str]:
@@ -349,7 +104,7 @@ def read_pyproject_toml(
 
     try:
         config = parse_pyproject_toml(value)
-    except (toml.TomlDecodeError, OSError) as e:
+    except (OSError, ValueError) as e:
         raise click.FileError(
             filename=value, hint=f"Error reading configuration file: {e}"
         )
@@ -391,6 +146,17 @@ def target_version_option_callback(
     return [TargetVersion[val.upper()] for val in v]
 
 
+def re_compile_maybe_verbose(regex: str) -> Pattern[str]:
+    """Compile a regular expression string in `regex`.
+
+    If it contains newlines, use verbose mode.
+    """
+    if "\n" in regex:
+        regex = "(?x)" + regex
+    compiled: Pattern[str] = re.compile(regex)
+    return compiled
+
+
 def validate_regex(
     ctx: click.Context,
     param: click.Parameter,
@@ -945,42 +711,6 @@ def format_file_in_place(
     return True
 
 
-def color_diff(contents: str) -> str:
-    """Inject the ANSI color codes to the diff."""
-    lines = contents.split("\n")
-    for i, line in enumerate(lines):
-        if line.startswith("+++") or line.startswith("---"):
-            line = "\033[1;37m" + line + "\033[0m"  # bold white, reset
-        elif line.startswith("@@"):
-            line = "\033[36m" + line + "\033[0m"  # cyan, reset
-        elif line.startswith("+"):
-            line = "\033[32m" + line + "\033[0m"  # green, reset
-        elif line.startswith("-"):
-            line = "\033[31m" + line + "\033[0m"  # red, reset
-        lines[i] = line
-    return "\n".join(lines)
-
-
-def wrap_stream_for_windows(
-    f: io.TextIOWrapper,
-) -> Union[io.TextIOWrapper, "colorama.AnsiToWin32"]:
-    """
-    Wrap stream with colorama's wrap_stream so colors are shown on Windows.
-
-    If `colorama` is unavailable, the original stream is returned unmodified.
-    Otherwise, the `wrap_stream()` function determines whether the stream needs
-    to be wrapped for a Windows environment and will accordingly either return
-    an `AnsiToWin32` wrapper or the original stream.
-    """
-    try:
-        from colorama.initialise import wrap_stream
-    except ImportError:
-        return f
-    else:
-        # Set `strip=False` to avoid needing to modify test_express_diff_with_color.
-        return wrap_stream(f, convert=None, strip=False, autoreset=False, wrap=True)
-
-
 def format_stdin_to_stdout(
     fast: bool, *, write_back: WriteBack = WriteBack.NO, mode: Mode
 ) -> bool:
@@ -1127,5896 +857,197 @@ def decode_bytes(src: bytes) -> Tuple[FileContent, Encoding, NewLine]:
         return tiow.read(), encoding, newline
 
 
-def get_grammars(target_versions: Set[TargetVersion]) -> List[Grammar]:
-    if not target_versions:
-        # No target_version specified, so try all grammars.
-        return [
-            # Python 3.7+
-            pygram.python_grammar_no_print_statement_no_exec_statement_async_keywords,
-            # Python 3.0-3.6
-            pygram.python_grammar_no_print_statement_no_exec_statement,
-            # Python 2.7 with future print_function import
-            pygram.python_grammar_no_print_statement,
-            # Python 2.7
-            pygram.python_grammar,
-        ]
-
-    if all(version.is_python2() for version in target_versions):
-        # Python 2-only code, so try Python 2 grammars.
-        return [
-            # Python 2.7 with future print_function import
-            pygram.python_grammar_no_print_statement,
-            # Python 2.7
-            pygram.python_grammar,
-        ]
-
-    # Python 3-compatible code, so only try Python 3 grammar.
-    grammars = []
-    # If we have to parse both, try to parse async as a keyword first
-    if not supports_feature(target_versions, Feature.ASYNC_IDENTIFIERS):
-        # Python 3.7+
-        grammars.append(
-            pygram.python_grammar_no_print_statement_no_exec_statement_async_keywords
-        )
-    if not supports_feature(target_versions, Feature.ASYNC_KEYWORDS):
-        # Python 3.0-3.6
-        grammars.append(pygram.python_grammar_no_print_statement_no_exec_statement)
-    # At least one of the above branches must have been taken, because every Python
-    # version has exactly one of the two 'ASYNC_*' flags
-    return grammars
-
-
-def lib2to3_parse(src_txt: str, target_versions: Iterable[TargetVersion] = ()) -> Node:
-    """Given a string with source, return the lib2to3 Node."""
-    if not src_txt.endswith("\n"):
-        src_txt += "\n"
-
-    for grammar in get_grammars(set(target_versions)):
-        drv = driver.Driver(grammar, pytree.convert)
-        try:
-            result = drv.parse_string(src_txt, True)
-            break
-
-        except ParseError as pe:
-            lineno, column = pe.context[1]
-            lines = src_txt.splitlines()
-            try:
-                faulty_line = lines[lineno - 1]
-            except IndexError:
-                faulty_line = "<line number missing in source>"
-            exc = InvalidInput(f"Cannot parse: {lineno}:{column}: {faulty_line}")
-    else:
-        raise exc from None
-
-    if isinstance(result, Leaf):
-        result = Node(syms.file_input, [result])
-    return result
-
-
-def lib2to3_unparse(node: Node) -> str:
-    """Given a lib2to3 node, return its string representation."""
-    code = str(node)
-    return code
-
-
-class Visitor(Generic[T]):
-    """Basic lib2to3 visitor that yields things of type `T` on `visit()`."""
+def get_features_used(node: Node) -> Set[Feature]:
+    """Return a set of (relatively) new Python features used in this file.
 
-    def visit(self, node: LN) -> Iterator[T]:
-        """Main method to visit `node` and its children.
+    Currently looking for:
+    - f-strings;
+    - underscores in numeric literals;
+    - trailing commas after * or ** in function signatures and calls;
+    - positional only arguments in function signatures and lambdas;
+    - assignment expression;
+    - relaxed decorator syntax;
+    """
+    features: Set[Feature] = set()
+    for n in node.pre_order():
+        if n.type == token.STRING:
+            value_head = n.value[:2]  # type: ignore
+            if value_head in {'f"', 'F"', "f'", "F'", "rf", "fr", "RF", "FR"}:
+                features.add(Feature.F_STRINGS)
 
-        It tries to find a `visit_*()` method for the given `node.type`, like
-        `visit_simple_stmt` for Node objects or `visit_INDENT` for Leaf objects.
-        If no dedicated `visit_*()` method is found, chooses `visit_default()`
-        instead.
+        elif n.type == token.NUMBER:
+            if "_" in n.value:  # type: ignore
+                features.add(Feature.NUMERIC_UNDERSCORES)
 
-        Then yields objects of type `T` from the selected visitor.
-        """
-        if node.type < 256:
-            name = token.tok_name[node.type]
-        else:
-            name = str(type_repr(node.type))
-        # We explicitly branch on whether a visitor exists (instead of
-        # using self.visit_default as the default arg to getattr) in order
-        # to save needing to create a bound method object and so mypyc can
-        # generate a native call to visit_default.
-        visitf = getattr(self, f"visit_{name}", None)
-        if visitf:
-            yield from visitf(node)
-        else:
-            yield from self.visit_default(node)
-
-    def visit_default(self, node: LN) -> Iterator[T]:
-        """Default `visit_*()` implementation. Recurses to children of `node`."""
-        if isinstance(node, Node):
-            for child in node.children:
-                yield from self.visit(child)
-
-
-@dataclass
-class DebugVisitor(Visitor[T]):
-    tree_depth: int = 0
-
-    def visit_default(self, node: LN) -> Iterator[T]:
-        indent = " " * (2 * self.tree_depth)
-        if isinstance(node, Node):
-            _type = type_repr(node.type)
-            out(f"{indent}{_type}", fg="yellow")
-            self.tree_depth += 1
-            for child in node.children:
-                yield from self.visit(child)
-
-            self.tree_depth -= 1
-            out(f"{indent}/{_type}", fg="yellow", bold=False)
-        else:
-            _type = token.tok_name.get(node.type, str(node.type))
-            out(f"{indent}{_type}", fg="blue", nl=False)
-            if node.prefix:
-                # We don't have to handle prefixes for `Node` objects since
-                # that delegates to the first child anyway.
-                out(f" {node.prefix!r}", fg="green", bold=False, nl=False)
-            out(f" {node.value!r}", fg="blue", bold=False)
+        elif n.type == token.SLASH:
+            if n.parent and n.parent.type in {syms.typedargslist, syms.arglist}:
+                features.add(Feature.POS_ONLY_ARGUMENTS)
 
-    @classmethod
-    def show(cls, code: Union[str, Leaf, Node]) -> None:
-        """Pretty-print the lib2to3 AST of a given string of `code`.
-
-        Convenience method for debugging.
-        """
-        v: DebugVisitor[None] = DebugVisitor()
-        if isinstance(code, str):
-            code = lib2to3_parse(code)
-        list(v.visit(code))
-
-
-WHITESPACE: Final = {token.DEDENT, token.INDENT, token.NEWLINE}
-STATEMENT: Final = {
-    syms.if_stmt,
-    syms.while_stmt,
-    syms.for_stmt,
-    syms.try_stmt,
-    syms.except_clause,
-    syms.with_stmt,
-    syms.funcdef,
-    syms.classdef,
-}
-STANDALONE_COMMENT: Final = 153
-token.tok_name[STANDALONE_COMMENT] = "STANDALONE_COMMENT"
-LOGIC_OPERATORS: Final = {"and", "or"}
-COMPARATORS: Final = {
-    token.LESS,
-    token.GREATER,
-    token.EQEQUAL,
-    token.NOTEQUAL,
-    token.LESSEQUAL,
-    token.GREATEREQUAL,
-}
-MATH_OPERATORS: Final = {
-    token.VBAR,
-    token.CIRCUMFLEX,
-    token.AMPER,
-    token.LEFTSHIFT,
-    token.RIGHTSHIFT,
-    token.PLUS,
-    token.MINUS,
-    token.STAR,
-    token.SLASH,
-    token.DOUBLESLASH,
-    token.PERCENT,
-    token.AT,
-    token.TILDE,
-    token.DOUBLESTAR,
-}
-STARS: Final = {token.STAR, token.DOUBLESTAR}
-VARARGS_SPECIALS: Final = STARS | {token.SLASH}
-VARARGS_PARENTS: Final = {
-    syms.arglist,
-    syms.argument,  # double star in arglist
-    syms.trailer,  # single argument to call
-    syms.typedargslist,
-    syms.varargslist,  # lambdas
-}
-UNPACKING_PARENTS: Final = {
-    syms.atom,  # single element of a list or set literal
-    syms.dictsetmaker,
-    syms.listmaker,
-    syms.testlist_gexp,
-    syms.testlist_star_expr,
-}
-TEST_DESCENDANTS: Final = {
-    syms.test,
-    syms.lambdef,
-    syms.or_test,
-    syms.and_test,
-    syms.not_test,
-    syms.comparison,
-    syms.star_expr,
-    syms.expr,
-    syms.xor_expr,
-    syms.and_expr,
-    syms.shift_expr,
-    syms.arith_expr,
-    syms.trailer,
-    syms.term,
-    syms.power,
-}
-ASSIGNMENTS: Final = {
-    "=",
-    "+=",
-    "-=",
-    "*=",
-    "@=",
-    "/=",
-    "%=",
-    "&=",
-    "|=",
-    "^=",
-    "<<=",
-    ">>=",
-    "**=",
-    "//=",
-}
-COMPREHENSION_PRIORITY: Final = 20
-COMMA_PRIORITY: Final = 18
-TERNARY_PRIORITY: Final = 16
-LOGIC_PRIORITY: Final = 14
-STRING_PRIORITY: Final = 12
-COMPARATOR_PRIORITY: Final = 10
-MATH_PRIORITIES: Final = {
-    token.VBAR: 9,
-    token.CIRCUMFLEX: 8,
-    token.AMPER: 7,
-    token.LEFTSHIFT: 6,
-    token.RIGHTSHIFT: 6,
-    token.PLUS: 5,
-    token.MINUS: 5,
-    token.STAR: 4,
-    token.SLASH: 4,
-    token.DOUBLESLASH: 4,
-    token.PERCENT: 4,
-    token.AT: 4,
-    token.TILDE: 3,
-    token.DOUBLESTAR: 2,
-}
-DOT_PRIORITY: Final = 1
-
-
-@dataclass
-class BracketTracker:
-    """Keeps track of brackets on a line."""
-
-    depth: int = 0
-    bracket_match: Dict[Tuple[Depth, NodeType], Leaf] = field(default_factory=dict)
-    delimiters: Dict[LeafID, Priority] = field(default_factory=dict)
-    previous: Optional[Leaf] = None
-    _for_loop_depths: List[int] = field(default_factory=list)
-    _lambda_argument_depths: List[int] = field(default_factory=list)
-    invisible: List[Leaf] = field(default_factory=list)
-
-    def mark(self, leaf: Leaf) -> None:
-        """Mark `leaf` with bracket-related metadata. Keep track of delimiters.
-
-        All leaves receive an int `bracket_depth` field that stores how deep
-        within brackets a given leaf is. 0 means there are no enclosing brackets
-        that started on this line.
-
-        If a leaf is itself a closing bracket, it receives an `opening_bracket`
-        field that it forms a pair with. This is a one-directional link to
-        avoid reference cycles.
-
-        If a leaf is a delimiter (a token on which Black can split the line if
-        needed) and it's on depth 0, its `id()` is stored in the tracker's
-        `delimiters` field.
-        """
-        if leaf.type == token.COMMENT:
-            return
-
-        self.maybe_decrement_after_for_loop_variable(leaf)
-        self.maybe_decrement_after_lambda_arguments(leaf)
-        if leaf.type in CLOSING_BRACKETS:
-            self.depth -= 1
-            try:
-                opening_bracket = self.bracket_match.pop((self.depth, leaf.type))
-            except KeyError as e:
-                raise BracketMatchError(
-                    "Unable to match a closing bracket to the following opening"
-                    f" bracket: {leaf}"
-                ) from e
-            leaf.opening_bracket = opening_bracket
-            if not leaf.value:
-                self.invisible.append(leaf)
-        leaf.bracket_depth = self.depth
-        if self.depth == 0:
-            delim = is_split_before_delimiter(leaf, self.previous)
-            if delim and self.previous is not None:
-                self.delimiters[id(self.previous)] = delim
-            else:
-                delim = is_split_after_delimiter(leaf, self.previous)
-                if delim:
-                    self.delimiters[id(leaf)] = delim
-        if leaf.type in OPENING_BRACKETS:
-            self.bracket_match[self.depth, BRACKET[leaf.type]] = leaf
-            self.depth += 1
-            if not leaf.value:
-                self.invisible.append(leaf)
-        self.previous = leaf
-        self.maybe_increment_lambda_arguments(leaf)
-        self.maybe_increment_for_loop_variable(leaf)
-
-    def any_open_brackets(self) -> bool:
-        """Return True if there is an yet unmatched open bracket on the line."""
-        return bool(self.bracket_match)
-
-    def max_delimiter_priority(self, exclude: Iterable[LeafID] = ()) -> Priority:
-        """Return the highest priority of a delimiter found on the line.
-
-        Values are consistent with what `is_split_*_delimiter()` return.
-        Raises ValueError on no delimiters.
-        """
-        return max(v for k, v in self.delimiters.items() if k not in exclude)
-
-    def delimiter_count_with_priority(self, priority: Priority = 0) -> int:
-        """Return the number of delimiters with the given `priority`.
-
-        If no `priority` is passed, defaults to max priority on the line.
-        """
-        if not self.delimiters:
-            return 0
-
-        priority = priority or self.max_delimiter_priority()
-        return sum(1 for p in self.delimiters.values() if p == priority)
-
-    def maybe_increment_for_loop_variable(self, leaf: Leaf) -> bool:
-        """In a for loop, or comprehension, the variables are often unpacks.
-
-        To avoid splitting on the comma in this situation, increase the depth of
-        tokens between `for` and `in`.
-        """
-        if leaf.type == token.NAME and leaf.value == "for":
-            self.depth += 1
-            self._for_loop_depths.append(self.depth)
-            return True
+        elif n.type == token.COLONEQUAL:
+            features.add(Feature.ASSIGNMENT_EXPRESSIONS)
 
-        return False
+        elif n.type == syms.decorator:
+            if len(n.children) > 1 and not is_simple_decorator_expression(
+                n.children[1]
+            ):
+                features.add(Feature.RELAXED_DECORATORS)
 
-    def maybe_decrement_after_for_loop_variable(self, leaf: Leaf) -> bool:
-        """See `maybe_increment_for_loop_variable` above for explanation."""
-        if (
-            self._for_loop_depths
-            and self._for_loop_depths[-1] == self.depth
-            and leaf.type == token.NAME
-            and leaf.value == "in"
+        elif (
+            n.type in {syms.typedargslist, syms.arglist}
+            and n.children
+            and n.children[-1].type == token.COMMA
         ):
-            self.depth -= 1
-            self._for_loop_depths.pop()
-            return True
-
-        return False
+            if n.type == syms.typedargslist:
+                feature = Feature.TRAILING_COMMA_IN_DEF
+            else:
+                feature = Feature.TRAILING_COMMA_IN_CALL
 
-    def maybe_increment_lambda_arguments(self, leaf: Leaf) -> bool:
-        """In a lambda expression, there might be more than one argument.
+            for ch in n.children:
+                if ch.type in STARS:
+                    features.add(feature)
 
-        To avoid splitting on the comma in this situation, increase the depth of
-        tokens between `lambda` and `:`.
-        """
-        if leaf.type == token.NAME and leaf.value == "lambda":
-            self.depth += 1
-            self._lambda_argument_depths.append(self.depth)
-            return True
+                if ch.type == syms.argument:
+                    for argch in ch.children:
+                        if argch.type in STARS:
+                            features.add(feature)
 
-        return False
+    return features
 
-    def maybe_decrement_after_lambda_arguments(self, leaf: Leaf) -> bool:
-        """See `maybe_increment_lambda_arguments` above for explanation."""
-        if (
-            self._lambda_argument_depths
-            and self._lambda_argument_depths[-1] == self.depth
-            and leaf.type == token.COLON
-        ):
-            self.depth -= 1
-            self._lambda_argument_depths.pop()
-            return True
 
-        return False
+def detect_target_versions(node: Node) -> Set[TargetVersion]:
+    """Detect the version to target based on the nodes used."""
+    features = get_features_used(node)
+    return {
+        version for version in TargetVersion if features <= VERSION_TO_FEATURES[version]
+    }
 
-    def get_open_lsqb(self) -> Optional[Leaf]:
-        """Return the most recent opening square bracket (if any)."""
-        return self.bracket_match.get((self.depth - 1, token.RSQB))
-
-
-@dataclass
-class Line:
-    """Holds leaves and comments. Can be printed with `str(line)`."""
-
-    mode: Mode
-    depth: int = 0
-    leaves: List[Leaf] = field(default_factory=list)
-    # keys ordered like `leaves`
-    comments: Dict[LeafID, List[Leaf]] = field(default_factory=dict)
-    bracket_tracker: BracketTracker = field(default_factory=BracketTracker)
-    inside_brackets: bool = False
-    should_split_rhs: bool = False
-    magic_trailing_comma: Optional[Leaf] = None
-
-    def append(self, leaf: Leaf, preformatted: bool = False) -> None:
-        """Add a new `leaf` to the end of the line.
-
-        Unless `preformatted` is True, the `leaf` will receive a new consistent
-        whitespace prefix and metadata applied by :class:`BracketTracker`.
-        Trailing commas are maybe removed, unpacked for loop variables are
-        demoted from being delimiters.
-
-        Inline comments are put aside.
-        """
-        has_value = leaf.type in BRACKETS or bool(leaf.value.strip())
-        if not has_value:
-            return
-
-        if token.COLON == leaf.type and self.is_class_paren_empty:
-            del self.leaves[-2:]
-        if self.leaves and not preformatted:
-            # Note: at this point leaf.prefix should be empty except for
-            # imports, for which we only preserve newlines.
-            leaf.prefix += whitespace(
-                leaf, complex_subscript=self.is_complex_subscript(leaf)
-            )
-        if self.inside_brackets or not preformatted:
-            self.bracket_tracker.mark(leaf)
-            if self.mode.magic_trailing_comma:
-                if self.has_magic_trailing_comma(leaf):
-                    self.magic_trailing_comma = leaf
-            elif self.has_magic_trailing_comma(leaf, ensure_removable=True):
-                self.remove_trailing_comma()
-        if not self.append_comment(leaf):
-            self.leaves.append(leaf)
-
-    def append_safe(self, leaf: Leaf, preformatted: bool = False) -> None:
-        """Like :func:`append()` but disallow invalid standalone comment structure.
-
-        Raises ValueError when any `leaf` is appended after a standalone comment
-        or when a standalone comment is not the first leaf on the line.
-        """
-        if self.bracket_tracker.depth == 0:
-            if self.is_comment:
-                raise ValueError("cannot append to standalone comments")
-
-            if self.leaves and leaf.type == STANDALONE_COMMENT:
-                raise ValueError(
-                    "cannot append standalone comments to a populated line"
-                )
 
-        self.append(leaf, preformatted=preformatted)
-
-    @property
-    def is_comment(self) -> bool:
-        """Is this line a standalone comment?"""
-        return len(self.leaves) == 1 and self.leaves[0].type == STANDALONE_COMMENT
-
-    @property
-    def is_decorator(self) -> bool:
-        """Is this line a decorator?"""
-        return bool(self) and self.leaves[0].type == token.AT
-
-    @property
-    def is_import(self) -> bool:
-        """Is this an import line?"""
-        return bool(self) and is_import(self.leaves[0])
-
-    @property
-    def is_class(self) -> bool:
-        """Is this line a class definition?"""
-        return (
-            bool(self)
-            and self.leaves[0].type == token.NAME
-            and self.leaves[0].value == "class"
-        )
+def get_future_imports(node: Node) -> Set[str]:
+    """Return a set of __future__ imports in the file."""
+    imports: Set[str] = set()
 
-    @property
-    def is_stub_class(self) -> bool:
-        """Is this line a class definition with a body consisting only of "..."?"""
-        return self.is_class and self.leaves[-3:] == [
-            Leaf(token.DOT, ".") for _ in range(3)
-        ]
-
-    @property
-    def is_def(self) -> bool:
-        """Is this a function definition? (Also returns True for async defs.)"""
-        try:
-            first_leaf = self.leaves[0]
-        except IndexError:
-            return False
-
-        try:
-            second_leaf: Optional[Leaf] = self.leaves[1]
-        except IndexError:
-            second_leaf = None
-        return (first_leaf.type == token.NAME and first_leaf.value == "def") or (
-            first_leaf.type == token.ASYNC
-            and second_leaf is not None
-            and second_leaf.type == token.NAME
-            and second_leaf.value == "def"
-        )
+    def get_imports_from_children(children: List[LN]) -> Generator[str, None, None]:
+        for child in children:
+            if isinstance(child, Leaf):
+                if child.type == token.NAME:
+                    yield child.value
 
-    @property
-    def is_class_paren_empty(self) -> bool:
-        """Is this a class with no base classes but using parentheses?
-
-        Those are unnecessary and should be removed.
-        """
-        return (
-            bool(self)
-            and len(self.leaves) == 4
-            and self.is_class
-            and self.leaves[2].type == token.LPAR
-            and self.leaves[2].value == "("
-            and self.leaves[3].type == token.RPAR
-            and self.leaves[3].value == ")"
-        )
+            elif child.type == syms.import_as_name:
+                orig_name = child.children[0]
+                assert isinstance(orig_name, Leaf), "Invalid syntax parsing imports"
+                assert orig_name.type == token.NAME, "Invalid syntax parsing imports"
+                yield orig_name.value
 
-    @property
-    def is_triple_quoted_string(self) -> bool:
-        """Is the line a triple quoted string?"""
-        return (
-            bool(self)
-            and self.leaves[0].type == token.STRING
-            and self.leaves[0].value.startswith(('"""', "'''"))
-        )
+            elif child.type == syms.import_as_names:
+                yield from get_imports_from_children(child.children)
 
-    def contains_standalone_comments(self, depth_limit: int = sys.maxsize) -> bool:
-        """If so, needs to be split before emitting."""
-        for leaf in self.leaves:
-            if leaf.type == STANDALONE_COMMENT and leaf.bracket_depth <= depth_limit:
-                return True
+            else:
+                raise AssertionError("Invalid syntax parsing imports")
 
-        return False
+    for child in node.children:
+        if child.type != syms.simple_stmt:
+            break
 
-    def contains_uncollapsable_type_comments(self) -> bool:
-        ignored_ids = set()
-        try:
-            last_leaf = self.leaves[-1]
-            ignored_ids.add(id(last_leaf))
-            if last_leaf.type == token.COMMA or (
-                last_leaf.type == token.RPAR and not last_leaf.value
+        first_child = child.children[0]
+        if isinstance(first_child, Leaf):
+            # Continue looking if we see a docstring; otherwise stop.
+            if (
+                len(child.children) == 2
+                and first_child.type == token.STRING
+                and child.children[1].type == token.NEWLINE
             ):
-                # When trailing commas or optional parens are inserted by Black for
-                # consistency, comments after the previous last element are not moved
-                # (they don't have to, rendering will still be correct).  So we ignore
-                # trailing commas and invisible.
-                last_leaf = self.leaves[-2]
-                ignored_ids.add(id(last_leaf))
-        except IndexError:
-            return False
-
-        # A type comment is uncollapsable if it is attached to a leaf
-        # that isn't at the end of the line (since that could cause it
-        # to get associated to a different argument) or if there are
-        # comments before it (since that could cause it to get hidden
-        # behind a comment.
-        comment_seen = False
-        for leaf_id, comments in self.comments.items():
-            for comment in comments:
-                if is_type_comment(comment):
-                    if comment_seen or (
-                        not is_type_comment(comment, " ignore")
-                        and leaf_id not in ignored_ids
-                    ):
-                        return True
-
-                comment_seen = True
-
-        return False
-
-    def contains_unsplittable_type_ignore(self) -> bool:
-        if not self.leaves:
-            return False
-
-        # If a 'type: ignore' is attached to the end of a line, we
-        # can't split the line, because we can't know which of the
-        # subexpressions the ignore was meant to apply to.
-        #
-        # We only want this to apply to actual physical lines from the
-        # original source, though: we don't want the presence of a
-        # 'type: ignore' at the end of a multiline expression to
-        # justify pushing it all onto one line. Thus we
-        # (unfortunately) need to check the actual source lines and
-        # only report an unsplittable 'type: ignore' if this line was
-        # one line in the original code.
-
-        # Grab the first and last line numbers, skipping generated leaves
-        first_line = next((leaf.lineno for leaf in self.leaves if leaf.lineno != 0), 0)
-        last_line = next(
-            (leaf.lineno for leaf in reversed(self.leaves) if leaf.lineno != 0), 0
-        )
-
-        if first_line == last_line:
-            # We look at the last two leaves since a comma or an
-            # invisible paren could have been added at the end of the
-            # line.
-            for node in self.leaves[-2:]:
-                for comment in self.comments.get(id(node), []):
-                    if is_type_comment(comment, " ignore"):
-                        return True
-
-        return False
-
-    def contains_multiline_strings(self) -> bool:
-        return any(is_multiline_string(leaf) for leaf in self.leaves)
-
-    def has_magic_trailing_comma(
-        self, closing: Leaf, ensure_removable: bool = False
-    ) -> bool:
-        """Return True if we have a magic trailing comma, that is when:
-        - there's a trailing comma here
-        - it's not a one-tuple
-        Additionally, if ensure_removable:
-        - it's not from square bracket indexing
-        """
-        if not (
-            closing.type in CLOSING_BRACKETS
-            and self.leaves
-            and self.leaves[-1].type == token.COMMA
-        ):
-            return False
-
-        if closing.type == token.RBRACE:
-            return True
-
-        if closing.type == token.RSQB:
-            if not ensure_removable:
-                return True
-            comma = self.leaves[-1]
-            return bool(comma.parent and comma.parent.type == syms.listmaker)
+                continue
 
-        if self.is_import:
-            return True
+            break
 
-        if not is_one_tuple_between(closing.opening_bracket, closing, self.leaves):
-            return True
+        elif first_child.type == syms.import_from:
+            module_name = first_child.children[1]
+            if not isinstance(module_name, Leaf) or module_name.value != "__future__":
+                break
 
-        return False
+            imports |= set(get_imports_from_children(first_child.children[3:]))
+        else:
+            break
 
-    def append_comment(self, comment: Leaf) -> bool:
-        """Add an inline or standalone comment to the line."""
-        if (
-            comment.type == STANDALONE_COMMENT
-            and self.bracket_tracker.any_open_brackets()
-        ):
-            comment.prefix = ""
-            return False
-
-        if comment.type != token.COMMENT:
-            return False
-
-        if not self.leaves:
-            comment.type = STANDALONE_COMMENT
-            comment.prefix = ""
-            return False
-
-        last_leaf = self.leaves[-1]
-        if (
-            last_leaf.type == token.RPAR
-            and not last_leaf.value
-            and last_leaf.parent
-            and len(list(last_leaf.parent.leaves())) <= 3
-            and not is_type_comment(comment)
-        ):
-            # Comments on an optional parens wrapping a single leaf should belong to
-            # the wrapped node except if it's a type comment. Pinning the comment like
-            # this avoids unstable formatting caused by comment migration.
-            if len(self.leaves) < 2:
-                comment.type = STANDALONE_COMMENT
-                comment.prefix = ""
-                return False
-
-            last_leaf = self.leaves[-2]
-        self.comments.setdefault(id(last_leaf), []).append(comment)
-        return True
+    return imports
 
-    def comments_after(self, leaf: Leaf) -> List[Leaf]:
-        """Generate comments that should appear directly after `leaf`."""
-        return self.comments.get(id(leaf), [])
 
-    def remove_trailing_comma(self) -> None:
-        """Remove the trailing comma and moves the comments attached to it."""
-        trailing_comma = self.leaves.pop()
-        trailing_comma_comments = self.comments.pop(id(trailing_comma), [])
-        self.comments.setdefault(id(self.leaves[-1]), []).extend(
-            trailing_comma_comments
+def assert_equivalent(src: str, dst: str, *, pass_num: int = 1) -> None:
+    """Raise AssertionError if `src` and `dst` aren't equivalent."""
+    try:
+        src_ast = parse_ast(src)
+    except Exception as exc:
+        raise AssertionError(
+            "cannot use --safe with this file; failed to parse source file.  AST"
+            f" error message: {exc}"
         )
 
-    def is_complex_subscript(self, leaf: Leaf) -> bool:
-        """Return True iff `leaf` is part of a slice with non-trivial exprs."""
-        open_lsqb = self.bracket_tracker.get_open_lsqb()
-        if open_lsqb is None:
-            return False
-
-        subscript_start = open_lsqb.next_sibling
+    try:
+        dst_ast = parse_ast(dst)
+    except Exception as exc:
+        log = dump_to_file("".join(traceback.format_tb(exc.__traceback__)), dst)
+        raise AssertionError(
+            f"INTERNAL ERROR: Black produced invalid code on pass {pass_num}: {exc}. "
+            "Please report a bug on https://github.com/psf/black/issues.  "
+            f"This invalid output might be helpful: {log}"
+        ) from None
 
-        if isinstance(subscript_start, Node):
-            if subscript_start.type == syms.listmaker:
-                return False
+    src_ast_str = "\n".join(stringify_ast(src_ast))
+    dst_ast_str = "\n".join(stringify_ast(dst_ast))
+    if src_ast_str != dst_ast_str:
+        log = dump_to_file(diff(src_ast_str, dst_ast_str, "src", "dst"))
+        raise AssertionError(
+            "INTERNAL ERROR: Black produced code that is not equivalent to the"
+            f" source on pass {pass_num}.  Please report a bug on "
+            f"https://github.com/psf/black/issues.  This diff might be helpful: {log}"
+        ) from None
 
-            if subscript_start.type == syms.subscriptlist:
-                subscript_start = child_towards(subscript_start, leaf)
-        return subscript_start is not None and any(
-            n.type in TEST_DESCENDANTS for n in subscript_start.pre_order()
-        )
 
-    def clone(self) -> "Line":
-        return Line(
-            mode=self.mode,
-            depth=self.depth,
-            inside_brackets=self.inside_brackets,
-            should_split_rhs=self.should_split_rhs,
-            magic_trailing_comma=self.magic_trailing_comma,
+def assert_stable(src: str, dst: str, mode: Mode) -> None:
+    """Raise AssertionError if `dst` reformats differently the second time."""
+    newdst = format_str(dst, mode=mode)
+    if dst != newdst:
+        log = dump_to_file(
+            str(mode),
+            diff(src, dst, "source", "first pass"),
+            diff(dst, newdst, "first pass", "second pass"),
         )
+        raise AssertionError(
+            "INTERNAL ERROR: Black produced different code on the second pass of the"
+            " formatter.  Please report a bug on https://github.com/psf/black/issues."
+            f"  This diff might be helpful: {log}"
+        ) from None
 
-    def __str__(self) -> str:
-        """Render the line."""
-        if not self:
-            return "\n"
 
-        indent = "    " * self.depth
-        leaves = iter(self.leaves)
-        first = next(leaves)
-        res = f"{first.prefix}{indent}{first.value}"
-        for leaf in leaves:
-            res += str(leaf)
-        for comment in itertools.chain.from_iterable(self.comments.values()):
-            res += str(comment)
+@contextmanager
+def nullcontext() -> Iterator[None]:
+    """Return an empty context manager.
 
-        return res + "\n"
+    To be used like `nullcontext` in Python 3.7.
+    """
+    yield
 
-    def __bool__(self) -> bool:
-        """Return True if the line has leaves or comments."""
-        return bool(self.leaves or self.comments)
 
+def patch_click() -> None:
+    """Make Click not crash.
 
-@dataclass
-class EmptyLineTracker:
-    """Provides a stateful method that returns the number of potential extra
-    empty lines needed before and after the currently processed line.
+    On certain misconfigured environments, Python 3 selects the ASCII encoding as the
+    default which restricts paths that it can access during the lifetime of the
+    application.  Click refuses to work in this scenario by raising a RuntimeError.
 
-    Note: this tracker works on lines that haven't been split yet.  It assumes
-    the prefix of the first leaf consists of optional newlines.  Those newlines
-    are consumed by `maybe_empty_lines()` and included in the computation.
+    In case of Black the likelihood that non-ASCII characters are going to be used in
+    file paths is minimal since it's Python source code.  Moreover, this crash was
+    spurious on Python 3.7 thanks to PEP 538 and PEP 540.
     """
+    try:
+        from click import core
+        from click import _unicodefun  # type: ignore
+    except ModuleNotFoundError:
+        return
 
-    is_pyi: bool = False
-    previous_line: Optional[Line] = None
-    previous_after: int = 0
-    previous_defs: List[int] = field(default_factory=list)
-
-    def maybe_empty_lines(self, current_line: Line) -> Tuple[int, int]:
-        """Return the number of extra empty lines before and after the `current_line`.
-
-        This is for separating `def`, `async def` and `class` with extra empty
-        lines (two on module-level).
-        """
-        before, after = self._maybe_empty_lines(current_line)
-        before = (
-            # Black should not insert empty lines at the beginning
-            # of the file
-            0
-            if self.previous_line is None
-            else before - self.previous_after
-        )
-        self.previous_after = after
-        self.previous_line = current_line
-        return before, after
-
-    def _maybe_empty_lines(self, current_line: Line) -> Tuple[int, int]:
-        max_allowed = 1
-        if current_line.depth == 0:
-            max_allowed = 1 if self.is_pyi else 2
-        if current_line.leaves:
-            # Consume the first leaf's extra newlines.
-            first_leaf = current_line.leaves[0]
-            before = first_leaf.prefix.count("\n")
-            before = min(before, max_allowed)
-            first_leaf.prefix = ""
-        else:
-            before = 0
-        depth = current_line.depth
-        while self.previous_defs and self.previous_defs[-1] >= depth:
-            self.previous_defs.pop()
-            if self.is_pyi:
-                before = 0 if depth else 1
-            else:
-                before = 1 if depth else 2
-        if current_line.is_decorator or current_line.is_def or current_line.is_class:
-            return self._maybe_empty_lines_for_class_or_def(current_line, before)
-
-        if (
-            self.previous_line
-            and self.previous_line.is_import
-            and not current_line.is_import
-            and depth == self.previous_line.depth
-        ):
-            return (before or 1), 0
-
-        if (
-            self.previous_line
-            and self.previous_line.is_class
-            and current_line.is_triple_quoted_string
-        ):
-            return before, 1
-
-        return before, 0
-
-    def _maybe_empty_lines_for_class_or_def(
-        self, current_line: Line, before: int
-    ) -> Tuple[int, int]:
-        if not current_line.is_decorator:
-            self.previous_defs.append(current_line.depth)
-        if self.previous_line is None:
-            # Don't insert empty lines before the first line in the file.
-            return 0, 0
-
-        if self.previous_line.is_decorator:
-            if self.is_pyi and current_line.is_stub_class:
-                # Insert an empty line after a decorated stub class
-                return 0, 1
-
-            return 0, 0
-
-        if self.previous_line.depth < current_line.depth and (
-            self.previous_line.is_class or self.previous_line.is_def
-        ):
-            return 0, 0
-
-        if (
-            self.previous_line.is_comment
-            and self.previous_line.depth == current_line.depth
-            and before == 0
-        ):
-            return 0, 0
-
-        if self.is_pyi:
-            if self.previous_line.depth > current_line.depth:
-                newlines = 1
-            elif current_line.is_class or self.previous_line.is_class:
-                if current_line.is_stub_class and self.previous_line.is_stub_class:
-                    # No blank line between classes with an empty body
-                    newlines = 0
-                else:
-                    newlines = 1
-            elif (
-                current_line.is_def or current_line.is_decorator
-            ) and not self.previous_line.is_def:
-                # Blank line between a block of functions (maybe with preceding
-                # decorators) and a block of non-functions
-                newlines = 1
-            else:
-                newlines = 0
-        else:
-            newlines = 2
-        if current_line.depth and newlines:
-            newlines -= 1
-        return newlines, 0
-
-
-@dataclass
-class LineGenerator(Visitor[Line]):
-    """Generates reformatted Line objects.  Empty lines are not emitted.
-
-    Note: destroys the tree it's visiting by mutating prefixes of its leaves
-    in ways that will no longer stringify to valid Python code on the tree.
-    """
-
-    mode: Mode
-    remove_u_prefix: bool = False
-    current_line: Line = field(init=False)
-
-    def line(self, indent: int = 0) -> Iterator[Line]:
-        """Generate a line.
-
-        If the line is empty, only emit if it makes sense.
-        If the line is too long, split it first and then generate.
-
-        If any lines were generated, set up a new current_line.
-        """
-        if not self.current_line:
-            self.current_line.depth += indent
-            return  # Line is empty, don't emit. Creating a new one unnecessary.
-
-        complete_line = self.current_line
-        self.current_line = Line(mode=self.mode, depth=complete_line.depth + indent)
-        yield complete_line
-
-    def visit_default(self, node: LN) -> Iterator[Line]:
-        """Default `visit_*()` implementation. Recurses to children of `node`."""
-        if isinstance(node, Leaf):
-            any_open_brackets = self.current_line.bracket_tracker.any_open_brackets()
-            for comment in generate_comments(node):
-                if any_open_brackets:
-                    # any comment within brackets is subject to splitting
-                    self.current_line.append(comment)
-                elif comment.type == token.COMMENT:
-                    # regular trailing comment
-                    self.current_line.append(comment)
-                    yield from self.line()
-
-                else:
-                    # regular standalone comment
-                    yield from self.line()
-
-                    self.current_line.append(comment)
-                    yield from self.line()
-
-            normalize_prefix(node, inside_brackets=any_open_brackets)
-            if self.mode.string_normalization and node.type == token.STRING:
-                normalize_string_prefix(node, remove_u_prefix=self.remove_u_prefix)
-                normalize_string_quotes(node)
-            if node.type == token.NUMBER:
-                normalize_numeric_literal(node)
-            if node.type not in WHITESPACE:
-                self.current_line.append(node)
-        yield from super().visit_default(node)
-
-    def visit_INDENT(self, node: Leaf) -> Iterator[Line]:
-        """Increase indentation level, maybe yield a line."""
-        # In blib2to3 INDENT never holds comments.
-        yield from self.line(+1)
-        yield from self.visit_default(node)
-
-    def visit_DEDENT(self, node: Leaf) -> Iterator[Line]:
-        """Decrease indentation level, maybe yield a line."""
-        # The current line might still wait for trailing comments.  At DEDENT time
-        # there won't be any (they would be prefixes on the preceding NEWLINE).
-        # Emit the line then.
-        yield from self.line()
-
-        # While DEDENT has no value, its prefix may contain standalone comments
-        # that belong to the current indentation level.  Get 'em.
-        yield from self.visit_default(node)
-
-        # Finally, emit the dedent.
-        yield from self.line(-1)
-
-    def visit_stmt(
-        self, node: Node, keywords: Set[str], parens: Set[str]
-    ) -> Iterator[Line]:
-        """Visit a statement.
-
-        This implementation is shared for `if`, `while`, `for`, `try`, `except`,
-        `def`, `with`, `class`, `assert` and assignments.
-
-        The relevant Python language `keywords` for a given statement will be
-        NAME leaves within it. This methods puts those on a separate line.
-
-        `parens` holds a set of string leaf values immediately after which
-        invisible parens should be put.
-        """
-        normalize_invisible_parens(node, parens_after=parens)
-        for child in node.children:
-            if child.type == token.NAME and child.value in keywords:  # type: ignore
-                yield from self.line()
-
-            yield from self.visit(child)
-
-    def visit_suite(self, node: Node) -> Iterator[Line]:
-        """Visit a suite."""
-        if self.mode.is_pyi and is_stub_suite(node):
-            yield from self.visit(node.children[2])
-        else:
-            yield from self.visit_default(node)
-
-    def visit_simple_stmt(self, node: Node) -> Iterator[Line]:
-        """Visit a statement without nested statements."""
-        if first_child_is_arith(node):
-            wrap_in_parentheses(node, node.children[0], visible=False)
-        is_suite_like = node.parent and node.parent.type in STATEMENT
-        if is_suite_like:
-            if self.mode.is_pyi and is_stub_body(node):
-                yield from self.visit_default(node)
-            else:
-                yield from self.line(+1)
-                yield from self.visit_default(node)
-                yield from self.line(-1)
-
-        else:
-            if (
-                not self.mode.is_pyi
-                or not node.parent
-                or not is_stub_suite(node.parent)
-            ):
-                yield from self.line()
-            yield from self.visit_default(node)
-
-    def visit_async_stmt(self, node: Node) -> Iterator[Line]:
-        """Visit `async def`, `async for`, `async with`."""
-        yield from self.line()
-
-        children = iter(node.children)
-        for child in children:
-            yield from self.visit(child)
-
-            if child.type == token.ASYNC:
-                break
-
-        internal_stmt = next(children)
-        for child in internal_stmt.children:
-            yield from self.visit(child)
-
-    def visit_decorators(self, node: Node) -> Iterator[Line]:
-        """Visit decorators."""
-        for child in node.children:
-            yield from self.line()
-            yield from self.visit(child)
-
-    def visit_SEMI(self, leaf: Leaf) -> Iterator[Line]:
-        """Remove a semicolon and put the other statement on a separate line."""
-        yield from self.line()
-
-    def visit_ENDMARKER(self, leaf: Leaf) -> Iterator[Line]:
-        """End of file. Process outstanding comments and end with a newline."""
-        yield from self.visit_default(leaf)
-        yield from self.line()
-
-    def visit_STANDALONE_COMMENT(self, leaf: Leaf) -> Iterator[Line]:
-        if not self.current_line.bracket_tracker.any_open_brackets():
-            yield from self.line()
-        yield from self.visit_default(leaf)
-
-    def visit_factor(self, node: Node) -> Iterator[Line]:
-        """Force parentheses between a unary op and a binary power:
-
-        -2 ** 8 -> -(2 ** 8)
-        """
-        _operator, operand = node.children
-        if (
-            operand.type == syms.power
-            and len(operand.children) == 3
-            and operand.children[1].type == token.DOUBLESTAR
-        ):
-            lpar = Leaf(token.LPAR, "(")
-            rpar = Leaf(token.RPAR, ")")
-            index = operand.remove() or 0
-            node.insert_child(index, Node(syms.atom, [lpar, operand, rpar]))
-        yield from self.visit_default(node)
-
-    def visit_STRING(self, leaf: Leaf) -> Iterator[Line]:
-        if is_docstring(leaf) and "\\\n" not in leaf.value:
-            # We're ignoring docstrings with backslash newline escapes because changing
-            # indentation of those changes the AST representation of the code.
-            prefix = get_string_prefix(leaf.value)
-            docstring = leaf.value[len(prefix) :]  # Remove the prefix
-            quote_char = docstring[0]
-            # A natural way to remove the outer quotes is to do:
-            #   docstring = docstring.strip(quote_char)
-            # but that breaks on """""x""" (which is '""x').
-            # So we actually need to remove the first character and the next two
-            # characters but only if they are the same as the first.
-            quote_len = 1 if docstring[1] != quote_char else 3
-            docstring = docstring[quote_len:-quote_len]
-
-            if is_multiline_string(leaf):
-                indent = " " * 4 * self.current_line.depth
-                docstring = fix_docstring(docstring, indent)
-            else:
-                docstring = docstring.strip()
-
-            if docstring:
-                # Add some padding if the docstring starts / ends with a quote mark.
-                if docstring[0] == quote_char:
-                    docstring = " " + docstring
-                if docstring[-1] == quote_char:
-                    docstring += " "
-                if docstring[-1] == "\\":
-                    backslash_count = len(docstring) - len(docstring.rstrip("\\"))
-                    if backslash_count % 2:
-                        # Odd number of tailing backslashes, add some padding to
-                        # avoid escaping the closing string quote.
-                        docstring += " "
-            else:
-                # Add some padding if the docstring is empty.
-                docstring = " "
-
-            # We could enforce triple quotes at this point.
-            quote = quote_char * quote_len
-            leaf.value = prefix + quote + docstring + quote
-
-        yield from self.visit_default(leaf)
-
-    def __post_init__(self) -> None:
-        """You are in a twisty little maze of passages."""
-        self.current_line = Line(mode=self.mode)
-
-        v = self.visit_stmt
-        Ø: Set[str] = set()
-        self.visit_assert_stmt = partial(v, keywords={"assert"}, parens={"assert", ","})
-        self.visit_if_stmt = partial(
-            v, keywords={"if", "else", "elif"}, parens={"if", "elif"}
-        )
-        self.visit_while_stmt = partial(v, keywords={"while", "else"}, parens={"while"})
-        self.visit_for_stmt = partial(v, keywords={"for", "else"}, parens={"for", "in"})
-        self.visit_try_stmt = partial(
-            v, keywords={"try", "except", "else", "finally"}, parens=Ø
-        )
-        self.visit_except_clause = partial(v, keywords={"except"}, parens=Ø)
-        self.visit_with_stmt = partial(v, keywords={"with"}, parens=Ø)
-        self.visit_funcdef = partial(v, keywords={"def"}, parens=Ø)
-        self.visit_classdef = partial(v, keywords={"class"}, parens=Ø)
-        self.visit_expr_stmt = partial(v, keywords=Ø, parens=ASSIGNMENTS)
-        self.visit_return_stmt = partial(v, keywords={"return"}, parens={"return"})
-        self.visit_import_from = partial(v, keywords=Ø, parens={"import"})
-        self.visit_del_stmt = partial(v, keywords=Ø, parens={"del"})
-        self.visit_async_funcdef = self.visit_async_stmt
-        self.visit_decorated = self.visit_decorators
-
-
-IMPLICIT_TUPLE = {syms.testlist, syms.testlist_star_expr, syms.exprlist}
-BRACKET = {token.LPAR: token.RPAR, token.LSQB: token.RSQB, token.LBRACE: token.RBRACE}
-OPENING_BRACKETS = set(BRACKET.keys())
-CLOSING_BRACKETS = set(BRACKET.values())
-BRACKETS = OPENING_BRACKETS | CLOSING_BRACKETS
-ALWAYS_NO_SPACE = CLOSING_BRACKETS | {token.COMMA, STANDALONE_COMMENT}
-
-
-def whitespace(leaf: Leaf, *, complex_subscript: bool) -> str:  # noqa: C901
-    """Return whitespace prefix if needed for the given `leaf`.
-
-    `complex_subscript` signals whether the given leaf is part of a subscription
-    which has non-trivial arguments, like arithmetic expressions or function calls.
-    """
-    NO = ""
-    SPACE = " "
-    DOUBLESPACE = "  "
-    t = leaf.type
-    p = leaf.parent
-    v = leaf.value
-    if t in ALWAYS_NO_SPACE:
-        return NO
-
-    if t == token.COMMENT:
-        return DOUBLESPACE
-
-    assert p is not None, f"INTERNAL ERROR: hand-made leaf without parent: {leaf!r}"
-    if t == token.COLON and p.type not in {
-        syms.subscript,
-        syms.subscriptlist,
-        syms.sliceop,
-    }:
-        return NO
-
-    prev = leaf.prev_sibling
-    if not prev:
-        prevp = preceding_leaf(p)
-        if not prevp or prevp.type in OPENING_BRACKETS:
-            return NO
-
-        if t == token.COLON:
-            if prevp.type == token.COLON:
-                return NO
-
-            elif prevp.type != token.COMMA and not complex_subscript:
-                return NO
-
-            return SPACE
-
-        if prevp.type == token.EQUAL:
-            if prevp.parent:
-                if prevp.parent.type in {
-                    syms.arglist,
-                    syms.argument,
-                    syms.parameters,
-                    syms.varargslist,
-                }:
-                    return NO
-
-                elif prevp.parent.type == syms.typedargslist:
-                    # A bit hacky: if the equal sign has whitespace, it means we
-                    # previously found it's a typed argument.  So, we're using
-                    # that, too.
-                    return prevp.prefix
-
-        elif prevp.type in VARARGS_SPECIALS:
-            if is_vararg(prevp, within=VARARGS_PARENTS | UNPACKING_PARENTS):
-                return NO
-
-        elif prevp.type == token.COLON:
-            if prevp.parent and prevp.parent.type in {syms.subscript, syms.sliceop}:
-                return SPACE if complex_subscript else NO
-
-        elif (
-            prevp.parent
-            and prevp.parent.type == syms.factor
-            and prevp.type in MATH_OPERATORS
-        ):
-            return NO
-
-        elif (
-            prevp.type == token.RIGHTSHIFT
-            and prevp.parent
-            and prevp.parent.type == syms.shift_expr
-            and prevp.prev_sibling
-            and prevp.prev_sibling.type == token.NAME
-            and prevp.prev_sibling.value == "print"  # type: ignore
-        ):
-            # Python 2 print chevron
-            return NO
-        elif prevp.type == token.AT and p.parent and p.parent.type == syms.decorator:
-            # no space in decorators
-            return NO
-
-    elif prev.type in OPENING_BRACKETS:
-        return NO
-
-    if p.type in {syms.parameters, syms.arglist}:
-        # untyped function signatures or calls
-        if not prev or prev.type != token.COMMA:
-            return NO
-
-    elif p.type == syms.varargslist:
-        # lambdas
-        if prev and prev.type != token.COMMA:
-            return NO
-
-    elif p.type == syms.typedargslist:
-        # typed function signatures
-        if not prev:
-            return NO
-
-        if t == token.EQUAL:
-            if prev.type != syms.tname:
-                return NO
-
-        elif prev.type == token.EQUAL:
-            # A bit hacky: if the equal sign has whitespace, it means we
-            # previously found it's a typed argument.  So, we're using that, too.
-            return prev.prefix
-
-        elif prev.type != token.COMMA:
-            return NO
-
-    elif p.type == syms.tname:
-        # type names
-        if not prev:
-            prevp = preceding_leaf(p)
-            if not prevp or prevp.type != token.COMMA:
-                return NO
-
-    elif p.type == syms.trailer:
-        # attributes and calls
-        if t == token.LPAR or t == token.RPAR:
-            return NO
-
-        if not prev:
-            if t == token.DOT:
-                prevp = preceding_leaf(p)
-                if not prevp or prevp.type != token.NUMBER:
-                    return NO
-
-            elif t == token.LSQB:
-                return NO
-
-        elif prev.type != token.COMMA:
-            return NO
-
-    elif p.type == syms.argument:
-        # single argument
-        if t == token.EQUAL:
-            return NO
-
-        if not prev:
-            prevp = preceding_leaf(p)
-            if not prevp or prevp.type == token.LPAR:
-                return NO
-
-        elif prev.type in {token.EQUAL} | VARARGS_SPECIALS:
-            return NO
-
-    elif p.type == syms.decorator:
-        # decorators
-        return NO
-
-    elif p.type == syms.dotted_name:
-        if prev:
-            return NO
-
-        prevp = preceding_leaf(p)
-        if not prevp or prevp.type == token.AT or prevp.type == token.DOT:
-            return NO
-
-    elif p.type == syms.classdef:
-        if t == token.LPAR:
-            return NO
-
-        if prev and prev.type == token.LPAR:
-            return NO
-
-    elif p.type in {syms.subscript, syms.sliceop}:
-        # indexing
-        if not prev:
-            assert p.parent is not None, "subscripts are always parented"
-            if p.parent.type == syms.subscriptlist:
-                return SPACE
-
-            return NO
-
-        elif not complex_subscript:
-            return NO
-
-    elif p.type == syms.atom:
-        if prev and t == token.DOT:
-            # dots, but not the first one.
-            return NO
-
-    elif p.type == syms.dictsetmaker:
-        # dict unpacking
-        if prev and prev.type == token.DOUBLESTAR:
-            return NO
-
-    elif p.type in {syms.factor, syms.star_expr}:
-        # unary ops
-        if not prev:
-            prevp = preceding_leaf(p)
-            if not prevp or prevp.type in OPENING_BRACKETS:
-                return NO
-
-            prevp_parent = prevp.parent
-            assert prevp_parent is not None
-            if prevp.type == token.COLON and prevp_parent.type in {
-                syms.subscript,
-                syms.sliceop,
-            }:
-                return NO
-
-            elif prevp.type == token.EQUAL and prevp_parent.type == syms.argument:
-                return NO
-
-        elif t in {token.NAME, token.NUMBER, token.STRING}:
-            return NO
-
-    elif p.type == syms.import_from:
-        if t == token.DOT:
-            if prev and prev.type == token.DOT:
-                return NO
-
-        elif t == token.NAME:
-            if v == "import":
-                return SPACE
-
-            if prev and prev.type == token.DOT:
-                return NO
-
-    elif p.type == syms.sliceop:
-        return NO
-
-    return SPACE
-
-
-def preceding_leaf(node: Optional[LN]) -> Optional[Leaf]:
-    """Return the first leaf that precedes `node`, if any."""
-    while node:
-        res = node.prev_sibling
-        if res:
-            if isinstance(res, Leaf):
-                return res
-
-            try:
-                return list(res.leaves())[-1]
-
-            except IndexError:
-                return None
-
-        node = node.parent
-    return None
-
-
-def prev_siblings_are(node: Optional[LN], tokens: List[Optional[NodeType]]) -> bool:
-    """Return if the `node` and its previous siblings match types against the provided
-    list of tokens; the provided `node`has its type matched against the last element in
-    the list.  `None` can be used as the first element to declare that the start of the
-    list is anchored at the start of its parent's children."""
-    if not tokens:
-        return True
-    if tokens[-1] is None:
-        return node is None
-    if not node:
-        return False
-    if node.type != tokens[-1]:
-        return False
-    return prev_siblings_are(node.prev_sibling, tokens[:-1])
-
-
-def child_towards(ancestor: Node, descendant: LN) -> Optional[LN]:
-    """Return the child of `ancestor` that contains `descendant`."""
-    node: Optional[LN] = descendant
-    while node and node.parent != ancestor:
-        node = node.parent
-    return node
-
-
-def container_of(leaf: Leaf) -> LN:
-    """Return `leaf` or one of its ancestors that is the topmost container of it.
-
-    By "container" we mean a node where `leaf` is the very first child.
-    """
-    same_prefix = leaf.prefix
-    container: LN = leaf
-    while container:
-        parent = container.parent
-        if parent is None:
-            break
-
-        if parent.children[0].prefix != same_prefix:
-            break
-
-        if parent.type == syms.file_input:
-            break
-
-        if parent.prev_sibling is not None and parent.prev_sibling.type in BRACKETS:
-            break
-
-        container = parent
-    return container
-
-
-def is_split_after_delimiter(leaf: Leaf, previous: Optional[Leaf] = None) -> Priority:
-    """Return the priority of the `leaf` delimiter, given a line break after it.
-
-    The delimiter priorities returned here are from those delimiters that would
-    cause a line break after themselves.
-
-    Higher numbers are higher priority.
-    """
-    if leaf.type == token.COMMA:
-        return COMMA_PRIORITY
-
-    return 0
-
-
-def is_split_before_delimiter(leaf: Leaf, previous: Optional[Leaf] = None) -> Priority:
-    """Return the priority of the `leaf` delimiter, given a line break before it.
-
-    The delimiter priorities returned here are from those delimiters that would
-    cause a line break before themselves.
-
-    Higher numbers are higher priority.
-    """
-    if is_vararg(leaf, within=VARARGS_PARENTS | UNPACKING_PARENTS):
-        # * and ** might also be MATH_OPERATORS but in this case they are not.
-        # Don't treat them as a delimiter.
-        return 0
-
-    if (
-        leaf.type == token.DOT
-        and leaf.parent
-        and leaf.parent.type not in {syms.import_from, syms.dotted_name}
-        and (previous is None or previous.type in CLOSING_BRACKETS)
-    ):
-        return DOT_PRIORITY
-
-    if (
-        leaf.type in MATH_OPERATORS
-        and leaf.parent
-        and leaf.parent.type not in {syms.factor, syms.star_expr}
-    ):
-        return MATH_PRIORITIES[leaf.type]
-
-    if leaf.type in COMPARATORS:
-        return COMPARATOR_PRIORITY
-
-    if (
-        leaf.type == token.STRING
-        and previous is not None
-        and previous.type == token.STRING
-    ):
-        return STRING_PRIORITY
-
-    if leaf.type not in {token.NAME, token.ASYNC}:
-        return 0
-
-    if (
-        leaf.value == "for"
-        and leaf.parent
-        and leaf.parent.type in {syms.comp_for, syms.old_comp_for}
-        or leaf.type == token.ASYNC
-    ):
-        if (
-            not isinstance(leaf.prev_sibling, Leaf)
-            or leaf.prev_sibling.value != "async"
-        ):
-            return COMPREHENSION_PRIORITY
-
-    if (
-        leaf.value == "if"
-        and leaf.parent
-        and leaf.parent.type in {syms.comp_if, syms.old_comp_if}
-    ):
-        return COMPREHENSION_PRIORITY
-
-    if leaf.value in {"if", "else"} and leaf.parent and leaf.parent.type == syms.test:
-        return TERNARY_PRIORITY
-
-    if leaf.value == "is":
-        return COMPARATOR_PRIORITY
-
-    if (
-        leaf.value == "in"
-        and leaf.parent
-        and leaf.parent.type in {syms.comp_op, syms.comparison}
-        and not (
-            previous is not None
-            and previous.type == token.NAME
-            and previous.value == "not"
-        )
-    ):
-        return COMPARATOR_PRIORITY
-
-    if (
-        leaf.value == "not"
-        and leaf.parent
-        and leaf.parent.type == syms.comp_op
-        and not (
-            previous is not None
-            and previous.type == token.NAME
-            and previous.value == "is"
-        )
-    ):
-        return COMPARATOR_PRIORITY
-
-    if leaf.value in LOGIC_OPERATORS and leaf.parent:
-        return LOGIC_PRIORITY
-
-    return 0
-
-
-FMT_OFF = {"# fmt: off", "# fmt:off", "# yapf: disable"}
-FMT_SKIP = {"# fmt: skip", "# fmt:skip"}
-FMT_PASS = {*FMT_OFF, *FMT_SKIP}
-FMT_ON = {"# fmt: on", "# fmt:on", "# yapf: enable"}
-
-
-def generate_comments(leaf: LN) -> Iterator[Leaf]:
-    """Clean the prefix of the `leaf` and generate comments from it, if any.
-
-    Comments in lib2to3 are shoved into the whitespace prefix.  This happens
-    in `pgen2/driver.py:Driver.parse_tokens()`.  This was a brilliant implementation
-    move because it does away with modifying the grammar to include all the
-    possible places in which comments can be placed.
-
-    The sad consequence for us though is that comments don't "belong" anywhere.
-    This is why this function generates simple parentless Leaf objects for
-    comments.  We simply don't know what the correct parent should be.
-
-    No matter though, we can live without this.  We really only need to
-    differentiate between inline and standalone comments.  The latter don't
-    share the line with any code.
-
-    Inline comments are emitted as regular token.COMMENT leaves.  Standalone
-    are emitted with a fake STANDALONE_COMMENT token identifier.
-    """
-    for pc in list_comments(leaf.prefix, is_endmarker=leaf.type == token.ENDMARKER):
-        yield Leaf(pc.type, pc.value, prefix="\n" * pc.newlines)
-
-
-@dataclass
-class ProtoComment:
-    """Describes a piece of syntax that is a comment.
-
-    It's not a :class:`blib2to3.pytree.Leaf` so that:
-
-    * it can be cached (`Leaf` objects should not be reused more than once as
-      they store their lineno, column, prefix, and parent information);
-    * `newlines` and `consumed` fields are kept separate from the `value`. This
-      simplifies handling of special marker comments like ``# fmt: off/on``.
-    """
-
-    type: int  # token.COMMENT or STANDALONE_COMMENT
-    value: str  # content of the comment
-    newlines: int  # how many newlines before the comment
-    consumed: int  # how many characters of the original leaf's prefix did we consume
-
-
-@lru_cache(maxsize=4096)
-def list_comments(prefix: str, *, is_endmarker: bool) -> List[ProtoComment]:
-    """Return a list of :class:`ProtoComment` objects parsed from the given `prefix`."""
-    result: List[ProtoComment] = []
-    if not prefix or "#" not in prefix:
-        return result
-
-    consumed = 0
-    nlines = 0
-    ignored_lines = 0
-    for index, line in enumerate(re.split("\r?\n", prefix)):
-        consumed += len(line) + 1  # adding the length of the split '\n'
-        line = line.lstrip()
-        if not line:
-            nlines += 1
-        if not line.startswith("#"):
-            # Escaped newlines outside of a comment are not really newlines at
-            # all. We treat a single-line comment following an escaped newline
-            # as a simple trailing comment.
-            if line.endswith("\\"):
-                ignored_lines += 1
-            continue
-
-        if index == ignored_lines and not is_endmarker:
-            comment_type = token.COMMENT  # simple trailing comment
-        else:
-            comment_type = STANDALONE_COMMENT
-        comment = make_comment(line)
-        result.append(
-            ProtoComment(
-                type=comment_type, value=comment, newlines=nlines, consumed=consumed
-            )
-        )
-        nlines = 0
-    return result
-
-
-def make_comment(content: str) -> str:
-    """Return a consistently formatted comment from the given `content` string.
-
-    All comments (except for "##", "#!", "#:", '#'", "#%%") should have a single
-    space between the hash sign and the content.
-
-    If `content` didn't start with a hash sign, one is provided.
-    """
-    content = content.rstrip()
-    if not content:
-        return "#"
-
-    if content[0] == "#":
-        content = content[1:]
-    NON_BREAKING_SPACE = " "
-    if (
-        content
-        and content[0] == NON_BREAKING_SPACE
-        and not content.lstrip().startswith("type:")
-    ):
-        content = " " + content[1:]  # Replace NBSP by a simple space
-    if content and content[0] not in " !:#'%":
-        content = " " + content
-    return "#" + content
-
-
-def transform_line(
-    line: Line, mode: Mode, features: Collection[Feature] = ()
-) -> Iterator[Line]:
-    """Transform a `line`, potentially splitting it into many lines.
-
-    They should fit in the allotted `line_length` but might not be able to.
-
-    `features` are syntactical features that may be used in the output.
-    """
-    if line.is_comment:
-        yield line
-        return
-
-    line_str = line_to_string(line)
-
-    def init_st(ST: Type[StringTransformer]) -> StringTransformer:
-        """Initialize StringTransformer"""
-        return ST(mode.line_length, mode.string_normalization)
-
-    string_merge = init_st(StringMerger)
-    string_paren_strip = init_st(StringParenStripper)
-    string_split = init_st(StringSplitter)
-    string_paren_wrap = init_st(StringParenWrapper)
-
-    transformers: List[Transformer]
-    if (
-        not line.contains_uncollapsable_type_comments()
-        and not line.should_split_rhs
-        and not line.magic_trailing_comma
-        and (
-            is_line_short_enough(line, line_length=mode.line_length, line_str=line_str)
-            or line.contains_unsplittable_type_ignore()
-        )
-        and not (line.inside_brackets and line.contains_standalone_comments())
-    ):
-        # Only apply basic string preprocessing, since lines shouldn't be split here.
-        if mode.experimental_string_processing:
-            transformers = [string_merge, string_paren_strip]
-        else:
-            transformers = []
-    elif line.is_def:
-        transformers = [left_hand_split]
-    else:
-
-        def rhs(line: Line, features: Collection[Feature]) -> Iterator[Line]:
-            """Wraps calls to `right_hand_split`.
-
-            The calls increasingly `omit` right-hand trailers (bracket pairs with
-            content), meaning the trailers get glued together to split on another
-            bracket pair instead.
-            """
-            for omit in generate_trailers_to_omit(line, mode.line_length):
-                lines = list(
-                    right_hand_split(line, mode.line_length, features, omit=omit)
-                )
-                # Note: this check is only able to figure out if the first line of the
-                # *current* transformation fits in the line length.  This is true only
-                # for simple cases.  All others require running more transforms via
-                # `transform_line()`.  This check doesn't know if those would succeed.
-                if is_line_short_enough(lines[0], line_length=mode.line_length):
-                    yield from lines
-                    return
-
-            # All splits failed, best effort split with no omits.
-            # This mostly happens to multiline strings that are by definition
-            # reported as not fitting a single line, as well as lines that contain
-            # trailing commas (those have to be exploded).
-            yield from right_hand_split(
-                line, line_length=mode.line_length, features=features
-            )
-
-        if mode.experimental_string_processing:
-            if line.inside_brackets:
-                transformers = [
-                    string_merge,
-                    string_paren_strip,
-                    string_split,
-                    delimiter_split,
-                    standalone_comment_split,
-                    string_paren_wrap,
-                    rhs,
-                ]
-            else:
-                transformers = [
-                    string_merge,
-                    string_paren_strip,
-                    string_split,
-                    string_paren_wrap,
-                    rhs,
-                ]
-        else:
-            if line.inside_brackets:
-                transformers = [delimiter_split, standalone_comment_split, rhs]
-            else:
-                transformers = [rhs]
-
-    for transform in transformers:
-        # We are accumulating lines in `result` because we might want to abort
-        # mission and return the original line in the end, or attempt a different
-        # split altogether.
-        try:
-            result = run_transformer(line, transform, mode, features, line_str=line_str)
-        except CannotTransform:
-            continue
-        else:
-            yield from result
-            break
-
-    else:
-        yield line
-
-
-@dataclass  # type: ignore
-class StringTransformer(ABC):
-    """
-    An implementation of the Transformer protocol that relies on its
-    subclasses overriding the template methods `do_match(...)` and
-    `do_transform(...)`.
-
-    This Transformer works exclusively on strings (for example, by merging
-    or splitting them).
-
-    The following sections can be found among the docstrings of each concrete
-    StringTransformer subclass.
-
-    Requirements:
-        Which requirements must be met of the given Line for this
-        StringTransformer to be applied?
-
-    Transformations:
-        If the given Line meets all of the above requirements, which string
-        transformations can you expect to be applied to it by this
-        StringTransformer?
-
-    Collaborations:
-        What contractual agreements does this StringTransformer have with other
-        StringTransfomers? Such collaborations should be eliminated/minimized
-        as much as possible.
-    """
-
-    line_length: int
-    normalize_strings: bool
-    __name__ = "StringTransformer"
-
-    @abstractmethod
-    def do_match(self, line: Line) -> TMatchResult:
-        """
-        Returns:
-            * Ok(string_idx) such that `line.leaves[string_idx]` is our target
-            string, if a match was able to be made.
-                OR
-            * Err(CannotTransform), if a match was not able to be made.
-        """
-
-    @abstractmethod
-    def do_transform(self, line: Line, string_idx: int) -> Iterator[TResult[Line]]:
-        """
-        Yields:
-            * Ok(new_line) where new_line is the new transformed line.
-                OR
-            * Err(CannotTransform) if the transformation failed for some reason. The
-            `do_match(...)` template method should usually be used to reject
-            the form of the given Line, but in some cases it is difficult to
-            know whether or not a Line meets the StringTransformer's
-            requirements until the transformation is already midway.
-
-        Side Effects:
-            This method should NOT mutate @line directly, but it MAY mutate the
-            Line's underlying Node structure. (WARNING: If the underlying Node
-            structure IS altered, then this method should NOT be allowed to
-            yield an CannotTransform after that point.)
-        """
-
-    def __call__(self, line: Line, _features: Collection[Feature]) -> Iterator[Line]:
-        """
-        StringTransformer instances have a call signature that mirrors that of
-        the Transformer type.
-
-        Raises:
-            CannotTransform(...) if the concrete StringTransformer class is unable
-            to transform @line.
-        """
-        # Optimization to avoid calling `self.do_match(...)` when the line does
-        # not contain any string.
-        if not any(leaf.type == token.STRING for leaf in line.leaves):
-            raise CannotTransform("There are no strings in this line.")
-
-        match_result = self.do_match(line)
-
-        if isinstance(match_result, Err):
-            cant_transform = match_result.err()
-            raise CannotTransform(
-                f"The string transformer {self.__class__.__name__} does not recognize"
-                " this line as one that it can transform."
-            ) from cant_transform
-
-        string_idx = match_result.ok()
-
-        for line_result in self.do_transform(line, string_idx):
-            if isinstance(line_result, Err):
-                cant_transform = line_result.err()
-                raise CannotTransform(
-                    "StringTransformer failed while attempting to transform string."
-                ) from cant_transform
-            line = line_result.ok()
-            yield line
-
-
-@dataclass
-class CustomSplit:
-    """A custom (i.e. manual) string split.
-
-    A single CustomSplit instance represents a single substring.
-
-    Examples:
-        Consider the following string:
-        ```
-        "Hi there friend."
-        " This is a custom"
-        f" string {split}."
-        ```
-
-        This string will correspond to the following three CustomSplit instances:
-        ```
-        CustomSplit(False, 16)
-        CustomSplit(False, 17)
-        CustomSplit(True, 16)
-        ```
-    """
-
-    has_prefix: bool
-    break_idx: int
-
-
-class CustomSplitMapMixin:
-    """
-    This mixin class is used to map merged strings to a sequence of
-    CustomSplits, which will then be used to re-split the strings iff none of
-    the resultant substrings go over the configured max line length.
-    """
-
-    _Key = Tuple[StringID, str]
-    _CUSTOM_SPLIT_MAP: Dict[_Key, Tuple[CustomSplit, ...]] = defaultdict(tuple)
-
-    @staticmethod
-    def _get_key(string: str) -> "CustomSplitMapMixin._Key":
-        """
-        Returns:
-            A unique identifier that is used internally to map @string to a
-            group of custom splits.
-        """
-        return (id(string), string)
-
-    def add_custom_splits(
-        self, string: str, custom_splits: Iterable[CustomSplit]
-    ) -> None:
-        """Custom Split Map Setter Method
-
-        Side Effects:
-            Adds a mapping from @string to the custom splits @custom_splits.
-        """
-        key = self._get_key(string)
-        self._CUSTOM_SPLIT_MAP[key] = tuple(custom_splits)
-
-    def pop_custom_splits(self, string: str) -> List[CustomSplit]:
-        """Custom Split Map Getter Method
-
-        Returns:
-            * A list of the custom splits that are mapped to @string, if any
-            exist.
-                OR
-            * [], otherwise.
-
-        Side Effects:
-            Deletes the mapping between @string and its associated custom
-            splits (which are returned to the caller).
-        """
-        key = self._get_key(string)
-
-        custom_splits = self._CUSTOM_SPLIT_MAP[key]
-        del self._CUSTOM_SPLIT_MAP[key]
-
-        return list(custom_splits)
-
-    def has_custom_splits(self, string: str) -> bool:
-        """
-        Returns:
-            True iff @string is associated with a set of custom splits.
-        """
-        key = self._get_key(string)
-        return key in self._CUSTOM_SPLIT_MAP
-
-
-class StringMerger(CustomSplitMapMixin, StringTransformer):
-    """StringTransformer that merges strings together.
-
-    Requirements:
-        (A) The line contains adjacent strings such that ALL of the validation checks
-        listed in StringMerger.__validate_msg(...)'s docstring pass.
-            OR
-        (B) The line contains a string which uses line continuation backslashes.
-
-    Transformations:
-        Depending on which of the two requirements above where met, either:
-
-        (A) The string group associated with the target string is merged.
-            OR
-        (B) All line-continuation backslashes are removed from the target string.
-
-    Collaborations:
-        StringMerger provides custom split information to StringSplitter.
-    """
-
-    def do_match(self, line: Line) -> TMatchResult:
-        LL = line.leaves
-
-        is_valid_index = is_valid_index_factory(LL)
-
-        for (i, leaf) in enumerate(LL):
-            if (
-                leaf.type == token.STRING
-                and is_valid_index(i + 1)
-                and LL[i + 1].type == token.STRING
-            ):
-                return Ok(i)
-
-            if leaf.type == token.STRING and "\\\n" in leaf.value:
-                return Ok(i)
-
-        return TErr("This line has no strings that need merging.")
-
-    def do_transform(self, line: Line, string_idx: int) -> Iterator[TResult[Line]]:
-        new_line = line
-        rblc_result = self.__remove_backslash_line_continuation_chars(
-            new_line, string_idx
-        )
-        if isinstance(rblc_result, Ok):
-            new_line = rblc_result.ok()
-
-        msg_result = self.__merge_string_group(new_line, string_idx)
-        if isinstance(msg_result, Ok):
-            new_line = msg_result.ok()
-
-        if isinstance(rblc_result, Err) and isinstance(msg_result, Err):
-            msg_cant_transform = msg_result.err()
-            rblc_cant_transform = rblc_result.err()
-            cant_transform = CannotTransform(
-                "StringMerger failed to merge any strings in this line."
-            )
-
-            # Chain the errors together using `__cause__`.
-            msg_cant_transform.__cause__ = rblc_cant_transform
-            cant_transform.__cause__ = msg_cant_transform
-
-            yield Err(cant_transform)
-        else:
-            yield Ok(new_line)
-
-    @staticmethod
-    def __remove_backslash_line_continuation_chars(
-        line: Line, string_idx: int
-    ) -> TResult[Line]:
-        """
-        Merge strings that were split across multiple lines using
-        line-continuation backslashes.
-
-        Returns:
-            Ok(new_line), if @line contains backslash line-continuation
-            characters.
-                OR
-            Err(CannotTransform), otherwise.
-        """
-        LL = line.leaves
-
-        string_leaf = LL[string_idx]
-        if not (
-            string_leaf.type == token.STRING
-            and "\\\n" in string_leaf.value
-            and not has_triple_quotes(string_leaf.value)
-        ):
-            return TErr(
-                f"String leaf {string_leaf} does not contain any backslash line"
-                " continuation characters."
-            )
-
-        new_line = line.clone()
-        new_line.comments = line.comments.copy()
-        append_leaves(new_line, line, LL)
-
-        new_string_leaf = new_line.leaves[string_idx]
-        new_string_leaf.value = new_string_leaf.value.replace("\\\n", "")
-
-        return Ok(new_line)
-
-    def __merge_string_group(self, line: Line, string_idx: int) -> TResult[Line]:
-        """
-        Merges string group (i.e. set of adjacent strings) where the first
-        string in the group is `line.leaves[string_idx]`.
-
-        Returns:
-            Ok(new_line), if ALL of the validation checks found in
-            __validate_msg(...) pass.
-                OR
-            Err(CannotTransform), otherwise.
-        """
-        LL = line.leaves
-
-        is_valid_index = is_valid_index_factory(LL)
-
-        vresult = self.__validate_msg(line, string_idx)
-        if isinstance(vresult, Err):
-            return vresult
-
-        # If the string group is wrapped inside an Atom node, we must make sure
-        # to later replace that Atom with our new (merged) string leaf.
-        atom_node = LL[string_idx].parent
-
-        # We will place BREAK_MARK in between every two substrings that we
-        # merge. We will then later go through our final result and use the
-        # various instances of BREAK_MARK we find to add the right values to
-        # the custom split map.
-        BREAK_MARK = "@@@@@ BLACK BREAKPOINT MARKER @@@@@"
-
-        QUOTE = LL[string_idx].value[-1]
-
-        def make_naked(string: str, string_prefix: str) -> str:
-            """Strip @string (i.e. make it a "naked" string)
-
-            Pre-conditions:
-                * assert_is_leaf_string(@string)
-
-            Returns:
-                A string that is identical to @string except that
-                @string_prefix has been stripped, the surrounding QUOTE
-                characters have been removed, and any remaining QUOTE
-                characters have been escaped.
-            """
-            assert_is_leaf_string(string)
-
-            RE_EVEN_BACKSLASHES = r"(?:(?<!\\)(?:\\\\)*)"
-            naked_string = string[len(string_prefix) + 1 : -1]
-            naked_string = re.sub(
-                "(" + RE_EVEN_BACKSLASHES + ")" + QUOTE, r"\1\\" + QUOTE, naked_string
-            )
-            return naked_string
-
-        # Holds the CustomSplit objects that will later be added to the custom
-        # split map.
-        custom_splits = []
-
-        # Temporary storage for the 'has_prefix' part of the CustomSplit objects.
-        prefix_tracker = []
-
-        # Sets the 'prefix' variable. This is the prefix that the final merged
-        # string will have.
-        next_str_idx = string_idx
-        prefix = ""
-        while (
-            not prefix
-            and is_valid_index(next_str_idx)
-            and LL[next_str_idx].type == token.STRING
-        ):
-            prefix = get_string_prefix(LL[next_str_idx].value)
-            next_str_idx += 1
-
-        # The next loop merges the string group. The final string will be
-        # contained in 'S'.
-        #
-        # The following convenience variables are used:
-        #
-        #   S: string
-        #   NS: naked string
-        #   SS: next string
-        #   NSS: naked next string
-        S = ""
-        NS = ""
-        num_of_strings = 0
-        next_str_idx = string_idx
-        while is_valid_index(next_str_idx) and LL[next_str_idx].type == token.STRING:
-            num_of_strings += 1
-
-            SS = LL[next_str_idx].value
-            next_prefix = get_string_prefix(SS)
-
-            # If this is an f-string group but this substring is not prefixed
-            # with 'f'...
-            if "f" in prefix and "f" not in next_prefix:
-                # Then we must escape any braces contained in this substring.
-                SS = re.subf(r"(\{|\})", "{1}{1}", SS)
-
-            NSS = make_naked(SS, next_prefix)
-
-            has_prefix = bool(next_prefix)
-            prefix_tracker.append(has_prefix)
-
-            S = prefix + QUOTE + NS + NSS + BREAK_MARK + QUOTE
-            NS = make_naked(S, prefix)
-
-            next_str_idx += 1
-
-        S_leaf = Leaf(token.STRING, S)
-        if self.normalize_strings:
-            normalize_string_quotes(S_leaf)
-
-        # Fill the 'custom_splits' list with the appropriate CustomSplit objects.
-        temp_string = S_leaf.value[len(prefix) + 1 : -1]
-        for has_prefix in prefix_tracker:
-            mark_idx = temp_string.find(BREAK_MARK)
-            assert (
-                mark_idx >= 0
-            ), "Logic error while filling the custom string breakpoint cache."
-
-            temp_string = temp_string[mark_idx + len(BREAK_MARK) :]
-            breakpoint_idx = mark_idx + (len(prefix) if has_prefix else 0) + 1
-            custom_splits.append(CustomSplit(has_prefix, breakpoint_idx))
-
-        string_leaf = Leaf(token.STRING, S_leaf.value.replace(BREAK_MARK, ""))
-
-        if atom_node is not None:
-            replace_child(atom_node, string_leaf)
-
-        # Build the final line ('new_line') that this method will later return.
-        new_line = line.clone()
-        for (i, leaf) in enumerate(LL):
-            if i == string_idx:
-                new_line.append(string_leaf)
-
-            if string_idx <= i < string_idx + num_of_strings:
-                for comment_leaf in line.comments_after(LL[i]):
-                    new_line.append(comment_leaf, preformatted=True)
-                continue
-
-            append_leaves(new_line, line, [leaf])
-
-        self.add_custom_splits(string_leaf.value, custom_splits)
-        return Ok(new_line)
-
-    @staticmethod
-    def __validate_msg(line: Line, string_idx: int) -> TResult[None]:
-        """Validate (M)erge (S)tring (G)roup
-
-        Transform-time string validation logic for __merge_string_group(...).
-
-        Returns:
-            * Ok(None), if ALL validation checks (listed below) pass.
-                OR
-            * Err(CannotTransform), if any of the following are true:
-                - The target string group does not contain ANY stand-alone comments.
-                - The target string is not in a string group (i.e. it has no
-                  adjacent strings).
-                - The string group has more than one inline comment.
-                - The string group has an inline comment that appears to be a pragma.
-                - The set of all string prefixes in the string group is of
-                  length greater than one and is not equal to {"", "f"}.
-                - The string group consists of raw strings.
-        """
-        # We first check for "inner" stand-alone comments (i.e. stand-alone
-        # comments that have a string leaf before them AND after them).
-        for inc in [1, -1]:
-            i = string_idx
-            found_sa_comment = False
-            is_valid_index = is_valid_index_factory(line.leaves)
-            while is_valid_index(i) and line.leaves[i].type in [
-                token.STRING,
-                STANDALONE_COMMENT,
-            ]:
-                if line.leaves[i].type == STANDALONE_COMMENT:
-                    found_sa_comment = True
-                elif found_sa_comment:
-                    return TErr(
-                        "StringMerger does NOT merge string groups which contain "
-                        "stand-alone comments."
-                    )
-
-                i += inc
-
-        num_of_inline_string_comments = 0
-        set_of_prefixes = set()
-        num_of_strings = 0
-        for leaf in line.leaves[string_idx:]:
-            if leaf.type != token.STRING:
-                # If the string group is trailed by a comma, we count the
-                # comments trailing the comma to be one of the string group's
-                # comments.
-                if leaf.type == token.COMMA and id(leaf) in line.comments:
-                    num_of_inline_string_comments += 1
-                break
-
-            if has_triple_quotes(leaf.value):
-                return TErr("StringMerger does NOT merge multiline strings.")
-
-            num_of_strings += 1
-            prefix = get_string_prefix(leaf.value)
-            if "r" in prefix:
-                return TErr("StringMerger does NOT merge raw strings.")
-
-            set_of_prefixes.add(prefix)
-
-            if id(leaf) in line.comments:
-                num_of_inline_string_comments += 1
-                if contains_pragma_comment(line.comments[id(leaf)]):
-                    return TErr("Cannot merge strings which have pragma comments.")
-
-        if num_of_strings < 2:
-            return TErr(
-                f"Not enough strings to merge (num_of_strings={num_of_strings})."
-            )
-
-        if num_of_inline_string_comments > 1:
-            return TErr(
-                f"Too many inline string comments ({num_of_inline_string_comments})."
-            )
-
-        if len(set_of_prefixes) > 1 and set_of_prefixes != {"", "f"}:
-            return TErr(f"Too many different prefixes ({set_of_prefixes}).")
-
-        return Ok(None)
-
-
-class StringParenStripper(StringTransformer):
-    """StringTransformer that strips surrounding parentheses from strings.
-
-    Requirements:
-        The line contains a string which is surrounded by parentheses and:
-            - The target string is NOT the only argument to a function call.
-            - The target string is NOT a "pointless" string.
-            - If the target string contains a PERCENT, the brackets are not
-              preceeded or followed by an operator with higher precedence than
-              PERCENT.
-
-    Transformations:
-        The parentheses mentioned in the 'Requirements' section are stripped.
-
-    Collaborations:
-        StringParenStripper has its own inherent usefulness, but it is also
-        relied on to clean up the parentheses created by StringParenWrapper (in
-        the event that they are no longer needed).
-    """
-
-    def do_match(self, line: Line) -> TMatchResult:
-        LL = line.leaves
-
-        is_valid_index = is_valid_index_factory(LL)
-
-        for (idx, leaf) in enumerate(LL):
-            # Should be a string...
-            if leaf.type != token.STRING:
-                continue
-
-            # If this is a "pointless" string...
-            if (
-                leaf.parent
-                and leaf.parent.parent
-                and leaf.parent.parent.type == syms.simple_stmt
-            ):
-                continue
-
-            # Should be preceded by a non-empty LPAR...
-            if (
-                not is_valid_index(idx - 1)
-                or LL[idx - 1].type != token.LPAR
-                or is_empty_lpar(LL[idx - 1])
-            ):
-                continue
-
-            # That LPAR should NOT be preceded by a function name or a closing
-            # bracket (which could be a function which returns a function or a
-            # list/dictionary that contains a function)...
-            if is_valid_index(idx - 2) and (
-                LL[idx - 2].type == token.NAME or LL[idx - 2].type in CLOSING_BRACKETS
-            ):
-                continue
-
-            string_idx = idx
-
-            # Skip the string trailer, if one exists.
-            string_parser = StringParser()
-            next_idx = string_parser.parse(LL, string_idx)
-
-            # if the leaves in the parsed string include a PERCENT, we need to
-            # make sure the initial LPAR is NOT preceded by an operator with
-            # higher or equal precedence to PERCENT
-            if is_valid_index(idx - 2):
-                # mypy can't quite follow unless we name this
-                before_lpar = LL[idx - 2]
-                if token.PERCENT in {leaf.type for leaf in LL[idx - 1 : next_idx]} and (
-                    (
-                        before_lpar.type
-                        in {
-                            token.STAR,
-                            token.AT,
-                            token.SLASH,
-                            token.DOUBLESLASH,
-                            token.PERCENT,
-                            token.TILDE,
-                            token.DOUBLESTAR,
-                            token.AWAIT,
-                            token.LSQB,
-                            token.LPAR,
-                        }
-                    )
-                    or (
-                        # only unary PLUS/MINUS
-                        before_lpar.parent
-                        and before_lpar.parent.type == syms.factor
-                        and (before_lpar.type in {token.PLUS, token.MINUS})
-                    )
-                ):
-                    continue
-
-            # Should be followed by a non-empty RPAR...
-            if (
-                is_valid_index(next_idx)
-                and LL[next_idx].type == token.RPAR
-                and not is_empty_rpar(LL[next_idx])
-            ):
-                # That RPAR should NOT be followed by anything with higher
-                # precedence than PERCENT
-                if is_valid_index(next_idx + 1) and LL[next_idx + 1].type in {
-                    token.DOUBLESTAR,
-                    token.LSQB,
-                    token.LPAR,
-                    token.DOT,
-                }:
-                    continue
-
-                return Ok(string_idx)
-
-        return TErr("This line has no strings wrapped in parens.")
-
-    def do_transform(self, line: Line, string_idx: int) -> Iterator[TResult[Line]]:
-        LL = line.leaves
-
-        string_parser = StringParser()
-        rpar_idx = string_parser.parse(LL, string_idx)
-
-        for leaf in (LL[string_idx - 1], LL[rpar_idx]):
-            if line.comments_after(leaf):
-                yield TErr(
-                    "Will not strip parentheses which have comments attached to them."
-                )
-                return
-
-        new_line = line.clone()
-        new_line.comments = line.comments.copy()
-        try:
-            append_leaves(new_line, line, LL[: string_idx - 1])
-        except BracketMatchError:
-            # HACK: I believe there is currently a bug somewhere in
-            # right_hand_split() that is causing brackets to not be tracked
-            # properly by a shared BracketTracker.
-            append_leaves(new_line, line, LL[: string_idx - 1], preformatted=True)
-
-        string_leaf = Leaf(token.STRING, LL[string_idx].value)
-        LL[string_idx - 1].remove()
-        replace_child(LL[string_idx], string_leaf)
-        new_line.append(string_leaf)
-
-        append_leaves(
-            new_line, line, LL[string_idx + 1 : rpar_idx] + LL[rpar_idx + 1 :]
-        )
-
-        LL[rpar_idx].remove()
-
-        yield Ok(new_line)
-
-
-class BaseStringSplitter(StringTransformer):
-    """
-    Abstract class for StringTransformers which transform a Line's strings by splitting
-    them or placing them on their own lines where necessary to avoid going over
-    the configured line length.
-
-    Requirements:
-        * The target string value is responsible for the line going over the
-        line length limit. It follows that after all of black's other line
-        split methods have been exhausted, this line (or one of the resulting
-        lines after all line splits are performed) would still be over the
-        line_length limit unless we split this string.
-            AND
-        * The target string is NOT a "pointless" string (i.e. a string that has
-        no parent or siblings).
-            AND
-        * The target string is not followed by an inline comment that appears
-        to be a pragma.
-            AND
-        * The target string is not a multiline (i.e. triple-quote) string.
-    """
-
-    @abstractmethod
-    def do_splitter_match(self, line: Line) -> TMatchResult:
-        """
-        BaseStringSplitter asks its clients to override this method instead of
-        `StringTransformer.do_match(...)`.
-
-        Follows the same protocol as `StringTransformer.do_match(...)`.
-
-        Refer to `help(StringTransformer.do_match)` for more information.
-        """
-
-    def do_match(self, line: Line) -> TMatchResult:
-        match_result = self.do_splitter_match(line)
-        if isinstance(match_result, Err):
-            return match_result
-
-        string_idx = match_result.ok()
-        vresult = self.__validate(line, string_idx)
-        if isinstance(vresult, Err):
-            return vresult
-
-        return match_result
-
-    def __validate(self, line: Line, string_idx: int) -> TResult[None]:
-        """
-        Checks that @line meets all of the requirements listed in this classes'
-        docstring. Refer to `help(BaseStringSplitter)` for a detailed
-        description of those requirements.
-
-        Returns:
-            * Ok(None), if ALL of the requirements are met.
-                OR
-            * Err(CannotTransform), if ANY of the requirements are NOT met.
-        """
-        LL = line.leaves
-
-        string_leaf = LL[string_idx]
-
-        max_string_length = self.__get_max_string_length(line, string_idx)
-        if len(string_leaf.value) <= max_string_length:
-            return TErr(
-                "The string itself is not what is causing this line to be too long."
-            )
-
-        if not string_leaf.parent or [L.type for L in string_leaf.parent.children] == [
-            token.STRING,
-            token.NEWLINE,
-        ]:
-            return TErr(
-                f"This string ({string_leaf.value}) appears to be pointless (i.e. has"
-                " no parent)."
-            )
-
-        if id(line.leaves[string_idx]) in line.comments and contains_pragma_comment(
-            line.comments[id(line.leaves[string_idx])]
-        ):
-            return TErr(
-                "Line appears to end with an inline pragma comment. Splitting the line"
-                " could modify the pragma's behavior."
-            )
-
-        if has_triple_quotes(string_leaf.value):
-            return TErr("We cannot split multiline strings.")
-
-        return Ok(None)
-
-    def __get_max_string_length(self, line: Line, string_idx: int) -> int:
-        """
-        Calculates the max string length used when attempting to determine
-        whether or not the target string is responsible for causing the line to
-        go over the line length limit.
-
-        WARNING: This method is tightly coupled to both StringSplitter and
-        (especially) StringParenWrapper. There is probably a better way to
-        accomplish what is being done here.
-
-        Returns:
-            max_string_length: such that `line.leaves[string_idx].value >
-            max_string_length` implies that the target string IS responsible
-            for causing this line to exceed the line length limit.
-        """
-        LL = line.leaves
-
-        is_valid_index = is_valid_index_factory(LL)
-
-        # We use the shorthand "WMA4" in comments to abbreviate "We must
-        # account for". When giving examples, we use STRING to mean some/any
-        # valid string.
-        #
-        # Finally, we use the following convenience variables:
-        #
-        #   P:  The leaf that is before the target string leaf.
-        #   N:  The leaf that is after the target string leaf.
-        #   NN: The leaf that is after N.
-
-        # WMA4 the whitespace at the beginning of the line.
-        offset = line.depth * 4
-
-        if is_valid_index(string_idx - 1):
-            p_idx = string_idx - 1
-            if (
-                LL[string_idx - 1].type == token.LPAR
-                and LL[string_idx - 1].value == ""
-                and string_idx >= 2
-            ):
-                # If the previous leaf is an empty LPAR placeholder, we should skip it.
-                p_idx -= 1
-
-            P = LL[p_idx]
-            if P.type == token.PLUS:
-                # WMA4 a space and a '+' character (e.g. `+ STRING`).
-                offset += 2
-
-            if P.type == token.COMMA:
-                # WMA4 a space, a comma, and a closing bracket [e.g. `), STRING`].
-                offset += 3
-
-            if P.type in [token.COLON, token.EQUAL, token.NAME]:
-                # This conditional branch is meant to handle dictionary keys,
-                # variable assignments, 'return STRING' statement lines, and
-                # 'else STRING' ternary expression lines.
-
-                # WMA4 a single space.
-                offset += 1
-
-                # WMA4 the lengths of any leaves that came before that space,
-                # but after any closing bracket before that space.
-                for leaf in reversed(LL[: p_idx + 1]):
-                    offset += len(str(leaf))
-                    if leaf.type in CLOSING_BRACKETS:
-                        break
-
-        if is_valid_index(string_idx + 1):
-            N = LL[string_idx + 1]
-            if N.type == token.RPAR and N.value == "" and len(LL) > string_idx + 2:
-                # If the next leaf is an empty RPAR placeholder, we should skip it.
-                N = LL[string_idx + 2]
-
-            if N.type == token.COMMA:
-                # WMA4 a single comma at the end of the string (e.g `STRING,`).
-                offset += 1
-
-            if is_valid_index(string_idx + 2):
-                NN = LL[string_idx + 2]
-
-                if N.type == token.DOT and NN.type == token.NAME:
-                    # This conditional branch is meant to handle method calls invoked
-                    # off of a string literal up to and including the LPAR character.
-
-                    # WMA4 the '.' character.
-                    offset += 1
-
-                    if (
-                        is_valid_index(string_idx + 3)
-                        and LL[string_idx + 3].type == token.LPAR
-                    ):
-                        # WMA4 the left parenthesis character.
-                        offset += 1
-
-                    # WMA4 the length of the method's name.
-                    offset += len(NN.value)
-
-        has_comments = False
-        for comment_leaf in line.comments_after(LL[string_idx]):
-            if not has_comments:
-                has_comments = True
-                # WMA4 two spaces before the '#' character.
-                offset += 2
-
-            # WMA4 the length of the inline comment.
-            offset += len(comment_leaf.value)
-
-        max_string_length = self.line_length - offset
-        return max_string_length
-
-
-class StringSplitter(CustomSplitMapMixin, BaseStringSplitter):
-    """
-    StringTransformer that splits "atom" strings (i.e. strings which exist on
-    lines by themselves).
-
-    Requirements:
-        * The line consists ONLY of a single string (with the exception of a
-        '+' symbol which MAY exist at the start of the line), MAYBE a string
-        trailer, and MAYBE a trailing comma.
-            AND
-        * All of the requirements listed in BaseStringSplitter's docstring.
-
-    Transformations:
-        The string mentioned in the 'Requirements' section is split into as
-        many substrings as necessary to adhere to the configured line length.
-
-        In the final set of substrings, no substring should be smaller than
-        MIN_SUBSTR_SIZE characters.
-
-        The string will ONLY be split on spaces (i.e. each new substring should
-        start with a space). Note that the string will NOT be split on a space
-        which is escaped with a backslash.
-
-        If the string is an f-string, it will NOT be split in the middle of an
-        f-expression (e.g. in f"FooBar: {foo() if x else bar()}", {foo() if x
-        else bar()} is an f-expression).
-
-        If the string that is being split has an associated set of custom split
-        records and those custom splits will NOT result in any line going over
-        the configured line length, those custom splits are used. Otherwise the
-        string is split as late as possible (from left-to-right) while still
-        adhering to the transformation rules listed above.
-
-    Collaborations:
-        StringSplitter relies on StringMerger to construct the appropriate
-        CustomSplit objects and add them to the custom split map.
-    """
-
-    MIN_SUBSTR_SIZE = 6
-    # Matches an "f-expression" (e.g. {var}) that might be found in an f-string.
-    RE_FEXPR = r"""
-    (?<!\{) (?:\{\{)* \{ (?!\{)
-        (?:
-            [^\{\}]
-            | \{\{
-            | \}\}
-            | (?R)
-        )+?
-    (?<!\}) \} (?:\}\})* (?!\})
-    """
-
-    def do_splitter_match(self, line: Line) -> TMatchResult:
-        LL = line.leaves
-
-        is_valid_index = is_valid_index_factory(LL)
-
-        idx = 0
-
-        # The first leaf MAY be a '+' symbol...
-        if is_valid_index(idx) and LL[idx].type == token.PLUS:
-            idx += 1
-
-        # The next/first leaf MAY be an empty LPAR...
-        if is_valid_index(idx) and is_empty_lpar(LL[idx]):
-            idx += 1
-
-        # The next/first leaf MUST be a string...
-        if not is_valid_index(idx) or LL[idx].type != token.STRING:
-            return TErr("Line does not start with a string.")
-
-        string_idx = idx
-
-        # Skip the string trailer, if one exists.
-        string_parser = StringParser()
-        idx = string_parser.parse(LL, string_idx)
-
-        # That string MAY be followed by an empty RPAR...
-        if is_valid_index(idx) and is_empty_rpar(LL[idx]):
-            idx += 1
-
-        # That string / empty RPAR leaf MAY be followed by a comma...
-        if is_valid_index(idx) and LL[idx].type == token.COMMA:
-            idx += 1
-
-        # But no more leaves are allowed...
-        if is_valid_index(idx):
-            return TErr("This line does not end with a string.")
-
-        return Ok(string_idx)
-
-    def do_transform(self, line: Line, string_idx: int) -> Iterator[TResult[Line]]:
-        LL = line.leaves
-
-        QUOTE = LL[string_idx].value[-1]
-
-        is_valid_index = is_valid_index_factory(LL)
-        insert_str_child = insert_str_child_factory(LL[string_idx])
-
-        prefix = get_string_prefix(LL[string_idx].value)
-
-        # We MAY choose to drop the 'f' prefix from substrings that don't
-        # contain any f-expressions, but ONLY if the original f-string
-        # contains at least one f-expression. Otherwise, we will alter the AST
-        # of the program.
-        drop_pointless_f_prefix = ("f" in prefix) and re.search(
-            self.RE_FEXPR, LL[string_idx].value, re.VERBOSE
-        )
-
-        first_string_line = True
-        starts_with_plus = LL[0].type == token.PLUS
-
-        def line_needs_plus() -> bool:
-            return first_string_line and starts_with_plus
-
-        def maybe_append_plus(new_line: Line) -> None:
-            """
-            Side Effects:
-                If @line starts with a plus and this is the first line we are
-                constructing, this function appends a PLUS leaf to @new_line
-                and replaces the old PLUS leaf in the node structure. Otherwise
-                this function does nothing.
-            """
-            if line_needs_plus():
-                plus_leaf = Leaf(token.PLUS, "+")
-                replace_child(LL[0], plus_leaf)
-                new_line.append(plus_leaf)
-
-        ends_with_comma = (
-            is_valid_index(string_idx + 1) and LL[string_idx + 1].type == token.COMMA
-        )
-
-        def max_last_string() -> int:
-            """
-            Returns:
-                The max allowed length of the string value used for the last
-                line we will construct.
-            """
-            result = self.line_length
-            result -= line.depth * 4
-            result -= 1 if ends_with_comma else 0
-            result -= 2 if line_needs_plus() else 0
-            return result
-
-        # --- Calculate Max Break Index (for string value)
-        # We start with the line length limit
-        max_break_idx = self.line_length
-        # The last index of a string of length N is N-1.
-        max_break_idx -= 1
-        # Leading whitespace is not present in the string value (e.g. Leaf.value).
-        max_break_idx -= line.depth * 4
-        if max_break_idx < 0:
-            yield TErr(
-                f"Unable to split {LL[string_idx].value} at such high of a line depth:"
-                f" {line.depth}"
-            )
-            return
-
-        # Check if StringMerger registered any custom splits.
-        custom_splits = self.pop_custom_splits(LL[string_idx].value)
-        # We use them ONLY if none of them would produce lines that exceed the
-        # line limit.
-        use_custom_breakpoints = bool(
-            custom_splits
-            and all(csplit.break_idx <= max_break_idx for csplit in custom_splits)
-        )
-
-        # Temporary storage for the remaining chunk of the string line that
-        # can't fit onto the line currently being constructed.
-        rest_value = LL[string_idx].value
-
-        def more_splits_should_be_made() -> bool:
-            """
-            Returns:
-                True iff `rest_value` (the remaining string value from the last
-                split), should be split again.
-            """
-            if use_custom_breakpoints:
-                return len(custom_splits) > 1
-            else:
-                return len(rest_value) > max_last_string()
-
-        string_line_results: List[Ok[Line]] = []
-        while more_splits_should_be_made():
-            if use_custom_breakpoints:
-                # Custom User Split (manual)
-                csplit = custom_splits.pop(0)
-                break_idx = csplit.break_idx
-            else:
-                # Algorithmic Split (automatic)
-                max_bidx = max_break_idx - 2 if line_needs_plus() else max_break_idx
-                maybe_break_idx = self.__get_break_idx(rest_value, max_bidx)
-                if maybe_break_idx is None:
-                    # If we are unable to algorithmically determine a good split
-                    # and this string has custom splits registered to it, we
-                    # fall back to using them--which means we have to start
-                    # over from the beginning.
-                    if custom_splits:
-                        rest_value = LL[string_idx].value
-                        string_line_results = []
-                        first_string_line = True
-                        use_custom_breakpoints = True
-                        continue
-
-                    # Otherwise, we stop splitting here.
-                    break
-
-                break_idx = maybe_break_idx
-
-            # --- Construct `next_value`
-            next_value = rest_value[:break_idx] + QUOTE
-            if (
-                # Are we allowed to try to drop a pointless 'f' prefix?
-                drop_pointless_f_prefix
-                # If we are, will we be successful?
-                and next_value != self.__normalize_f_string(next_value, prefix)
-            ):
-                # If the current custom split did NOT originally use a prefix,
-                # then `csplit.break_idx` will be off by one after removing
-                # the 'f' prefix.
-                break_idx = (
-                    break_idx + 1
-                    if use_custom_breakpoints and not csplit.has_prefix
-                    else break_idx
-                )
-                next_value = rest_value[:break_idx] + QUOTE
-                next_value = self.__normalize_f_string(next_value, prefix)
-
-            # --- Construct `next_leaf`
-            next_leaf = Leaf(token.STRING, next_value)
-            insert_str_child(next_leaf)
-            self.__maybe_normalize_string_quotes(next_leaf)
-
-            # --- Construct `next_line`
-            next_line = line.clone()
-            maybe_append_plus(next_line)
-            next_line.append(next_leaf)
-            string_line_results.append(Ok(next_line))
-
-            rest_value = prefix + QUOTE + rest_value[break_idx:]
-            first_string_line = False
-
-        yield from string_line_results
-
-        if drop_pointless_f_prefix:
-            rest_value = self.__normalize_f_string(rest_value, prefix)
-
-        rest_leaf = Leaf(token.STRING, rest_value)
-        insert_str_child(rest_leaf)
-
-        # NOTE: I could not find a test case that verifies that the following
-        # line is actually necessary, but it seems to be. Otherwise we risk
-        # not normalizing the last substring, right?
-        self.__maybe_normalize_string_quotes(rest_leaf)
-
-        last_line = line.clone()
-        maybe_append_plus(last_line)
-
-        # If there are any leaves to the right of the target string...
-        if is_valid_index(string_idx + 1):
-            # We use `temp_value` here to determine how long the last line
-            # would be if we were to append all the leaves to the right of the
-            # target string to the last string line.
-            temp_value = rest_value
-            for leaf in LL[string_idx + 1 :]:
-                temp_value += str(leaf)
-                if leaf.type == token.LPAR:
-                    break
-
-            # Try to fit them all on the same line with the last substring...
-            if (
-                len(temp_value) <= max_last_string()
-                or LL[string_idx + 1].type == token.COMMA
-            ):
-                last_line.append(rest_leaf)
-                append_leaves(last_line, line, LL[string_idx + 1 :])
-                yield Ok(last_line)
-            # Otherwise, place the last substring on one line and everything
-            # else on a line below that...
-            else:
-                last_line.append(rest_leaf)
-                yield Ok(last_line)
-
-                non_string_line = line.clone()
-                append_leaves(non_string_line, line, LL[string_idx + 1 :])
-                yield Ok(non_string_line)
-        # Else the target string was the last leaf...
-        else:
-            last_line.append(rest_leaf)
-            last_line.comments = line.comments.copy()
-            yield Ok(last_line)
-
-    def __get_break_idx(self, string: str, max_break_idx: int) -> Optional[int]:
-        """
-        This method contains the algorithm that StringSplitter uses to
-        determine which character to split each string at.
-
-        Args:
-            @string: The substring that we are attempting to split.
-            @max_break_idx: The ideal break index. We will return this value if it
-            meets all the necessary conditions. In the likely event that it
-            doesn't we will try to find the closest index BELOW @max_break_idx
-            that does. If that fails, we will expand our search by also
-            considering all valid indices ABOVE @max_break_idx.
-
-        Pre-Conditions:
-            * assert_is_leaf_string(@string)
-            * 0 <= @max_break_idx < len(@string)
-
-        Returns:
-            break_idx, if an index is able to be found that meets all of the
-            conditions listed in the 'Transformations' section of this classes'
-            docstring.
-                OR
-            None, otherwise.
-        """
-        is_valid_index = is_valid_index_factory(string)
-
-        assert is_valid_index(max_break_idx)
-        assert_is_leaf_string(string)
-
-        _fexpr_slices: Optional[List[Tuple[Index, Index]]] = None
-
-        def fexpr_slices() -> Iterator[Tuple[Index, Index]]:
-            """
-            Yields:
-                All ranges of @string which, if @string were to be split there,
-                would result in the splitting of an f-expression (which is NOT
-                allowed).
-            """
-            nonlocal _fexpr_slices
-
-            if _fexpr_slices is None:
-                _fexpr_slices = []
-                for match in re.finditer(self.RE_FEXPR, string, re.VERBOSE):
-                    _fexpr_slices.append(match.span())
-
-            yield from _fexpr_slices
-
-        is_fstring = "f" in get_string_prefix(string)
-
-        def breaks_fstring_expression(i: Index) -> bool:
-            """
-            Returns:
-                True iff returning @i would result in the splitting of an
-                f-expression (which is NOT allowed).
-            """
-            if not is_fstring:
-                return False
-
-            for (start, end) in fexpr_slices():
-                if start <= i < end:
-                    return True
-
-            return False
-
-        def passes_all_checks(i: Index) -> bool:
-            """
-            Returns:
-                True iff ALL of the conditions listed in the 'Transformations'
-                section of this classes' docstring would be be met by returning @i.
-            """
-            is_space = string[i] == " "
-
-            is_not_escaped = True
-            j = i - 1
-            while is_valid_index(j) and string[j] == "\\":
-                is_not_escaped = not is_not_escaped
-                j -= 1
-
-            is_big_enough = (
-                len(string[i:]) >= self.MIN_SUBSTR_SIZE
-                and len(string[:i]) >= self.MIN_SUBSTR_SIZE
-            )
-            return (
-                is_space
-                and is_not_escaped
-                and is_big_enough
-                and not breaks_fstring_expression(i)
-            )
-
-        # First, we check all indices BELOW @max_break_idx.
-        break_idx = max_break_idx
-        while is_valid_index(break_idx - 1) and not passes_all_checks(break_idx):
-            break_idx -= 1
-
-        if not passes_all_checks(break_idx):
-            # If that fails, we check all indices ABOVE @max_break_idx.
-            #
-            # If we are able to find a valid index here, the next line is going
-            # to be longer than the specified line length, but it's probably
-            # better than doing nothing at all.
-            break_idx = max_break_idx + 1
-            while is_valid_index(break_idx + 1) and not passes_all_checks(break_idx):
-                break_idx += 1
-
-            if not is_valid_index(break_idx) or not passes_all_checks(break_idx):
-                return None
-
-        return break_idx
-
-    def __maybe_normalize_string_quotes(self, leaf: Leaf) -> None:
-        if self.normalize_strings:
-            normalize_string_quotes(leaf)
-
-    def __normalize_f_string(self, string: str, prefix: str) -> str:
-        """
-        Pre-Conditions:
-            * assert_is_leaf_string(@string)
-
-        Returns:
-            * If @string is an f-string that contains no f-expressions, we
-            return a string identical to @string except that the 'f' prefix
-            has been stripped and all double braces (i.e. '{{' or '}}') have
-            been normalized (i.e. turned into '{' or '}').
-                OR
-            * Otherwise, we return @string.
-        """
-        assert_is_leaf_string(string)
-
-        if "f" in prefix and not re.search(self.RE_FEXPR, string, re.VERBOSE):
-            new_prefix = prefix.replace("f", "")
-
-            temp = string[len(prefix) :]
-            temp = re.sub(r"\{\{", "{", temp)
-            temp = re.sub(r"\}\}", "}", temp)
-            new_string = temp
-
-            return f"{new_prefix}{new_string}"
-        else:
-            return string
-
-
-class StringParenWrapper(CustomSplitMapMixin, BaseStringSplitter):
-    """
-    StringTransformer that splits non-"atom" strings (i.e. strings that do not
-    exist on lines by themselves).
-
-    Requirements:
-        All of the requirements listed in BaseStringSplitter's docstring in
-        addition to the requirements listed below:
-
-        * The line is a return/yield statement, which returns/yields a string.
-            OR
-        * The line is part of a ternary expression (e.g. `x = y if cond else
-        z`) such that the line starts with `else <string>`, where <string> is
-        some string.
-            OR
-        * The line is an assert statement, which ends with a string.
-            OR
-        * The line is an assignment statement (e.g. `x = <string>` or `x +=
-        <string>`) such that the variable is being assigned the value of some
-        string.
-            OR
-        * The line is a dictionary key assignment where some valid key is being
-        assigned the value of some string.
-
-    Transformations:
-        The chosen string is wrapped in parentheses and then split at the LPAR.
-
-        We then have one line which ends with an LPAR and another line that
-        starts with the chosen string. The latter line is then split again at
-        the RPAR. This results in the RPAR (and possibly a trailing comma)
-        being placed on its own line.
-
-        NOTE: If any leaves exist to the right of the chosen string (except
-        for a trailing comma, which would be placed after the RPAR), those
-        leaves are placed inside the parentheses.  In effect, the chosen
-        string is not necessarily being "wrapped" by parentheses. We can,
-        however, count on the LPAR being placed directly before the chosen
-        string.
-
-        In other words, StringParenWrapper creates "atom" strings. These
-        can then be split again by StringSplitter, if necessary.
-
-    Collaborations:
-        In the event that a string line split by StringParenWrapper is
-        changed such that it no longer needs to be given its own line,
-        StringParenWrapper relies on StringParenStripper to clean up the
-        parentheses it created.
-    """
-
-    def do_splitter_match(self, line: Line) -> TMatchResult:
-        LL = line.leaves
-
-        string_idx = (
-            self._return_match(LL)
-            or self._else_match(LL)
-            or self._assert_match(LL)
-            or self._assign_match(LL)
-            or self._dict_match(LL)
-        )
-
-        if string_idx is not None:
-            string_value = line.leaves[string_idx].value
-            # If the string has no spaces...
-            if " " not in string_value:
-                # And will still violate the line length limit when split...
-                max_string_length = self.line_length - ((line.depth + 1) * 4)
-                if len(string_value) > max_string_length:
-                    # And has no associated custom splits...
-                    if not self.has_custom_splits(string_value):
-                        # Then we should NOT put this string on its own line.
-                        return TErr(
-                            "We do not wrap long strings in parentheses when the"
-                            " resultant line would still be over the specified line"
-                            " length and can't be split further by StringSplitter."
-                        )
-            return Ok(string_idx)
-
-        return TErr("This line does not contain any non-atomic strings.")
-
-    @staticmethod
-    def _return_match(LL: List[Leaf]) -> Optional[int]:
-        """
-        Returns:
-            string_idx such that @LL[string_idx] is equal to our target (i.e.
-            matched) string, if this line matches the return/yield statement
-            requirements listed in the 'Requirements' section of this classes'
-            docstring.
-                OR
-            None, otherwise.
-        """
-        # If this line is apart of a return/yield statement and the first leaf
-        # contains either the "return" or "yield" keywords...
-        if parent_type(LL[0]) in [syms.return_stmt, syms.yield_expr] and LL[
-            0
-        ].value in ["return", "yield"]:
-            is_valid_index = is_valid_index_factory(LL)
-
-            idx = 2 if is_valid_index(1) and is_empty_par(LL[1]) else 1
-            # The next visible leaf MUST contain a string...
-            if is_valid_index(idx) and LL[idx].type == token.STRING:
-                return idx
-
-        return None
-
-    @staticmethod
-    def _else_match(LL: List[Leaf]) -> Optional[int]:
-        """
-        Returns:
-            string_idx such that @LL[string_idx] is equal to our target (i.e.
-            matched) string, if this line matches the ternary expression
-            requirements listed in the 'Requirements' section of this classes'
-            docstring.
-                OR
-            None, otherwise.
-        """
-        # If this line is apart of a ternary expression and the first leaf
-        # contains the "else" keyword...
-        if (
-            parent_type(LL[0]) == syms.test
-            and LL[0].type == token.NAME
-            and LL[0].value == "else"
-        ):
-            is_valid_index = is_valid_index_factory(LL)
-
-            idx = 2 if is_valid_index(1) and is_empty_par(LL[1]) else 1
-            # The next visible leaf MUST contain a string...
-            if is_valid_index(idx) and LL[idx].type == token.STRING:
-                return idx
-
-        return None
-
-    @staticmethod
-    def _assert_match(LL: List[Leaf]) -> Optional[int]:
-        """
-        Returns:
-            string_idx such that @LL[string_idx] is equal to our target (i.e.
-            matched) string, if this line matches the assert statement
-            requirements listed in the 'Requirements' section of this classes'
-            docstring.
-                OR
-            None, otherwise.
-        """
-        # If this line is apart of an assert statement and the first leaf
-        # contains the "assert" keyword...
-        if parent_type(LL[0]) == syms.assert_stmt and LL[0].value == "assert":
-            is_valid_index = is_valid_index_factory(LL)
-
-            for (i, leaf) in enumerate(LL):
-                # We MUST find a comma...
-                if leaf.type == token.COMMA:
-                    idx = i + 2 if is_empty_par(LL[i + 1]) else i + 1
-
-                    # That comma MUST be followed by a string...
-                    if is_valid_index(idx) and LL[idx].type == token.STRING:
-                        string_idx = idx
-
-                        # Skip the string trailer, if one exists.
-                        string_parser = StringParser()
-                        idx = string_parser.parse(LL, string_idx)
-
-                        # But no more leaves are allowed...
-                        if not is_valid_index(idx):
-                            return string_idx
-
-        return None
-
-    @staticmethod
-    def _assign_match(LL: List[Leaf]) -> Optional[int]:
-        """
-        Returns:
-            string_idx such that @LL[string_idx] is equal to our target (i.e.
-            matched) string, if this line matches the assignment statement
-            requirements listed in the 'Requirements' section of this classes'
-            docstring.
-                OR
-            None, otherwise.
-        """
-        # If this line is apart of an expression statement or is a function
-        # argument AND the first leaf contains a variable name...
-        if (
-            parent_type(LL[0]) in [syms.expr_stmt, syms.argument, syms.power]
-            and LL[0].type == token.NAME
-        ):
-            is_valid_index = is_valid_index_factory(LL)
-
-            for (i, leaf) in enumerate(LL):
-                # We MUST find either an '=' or '+=' symbol...
-                if leaf.type in [token.EQUAL, token.PLUSEQUAL]:
-                    idx = i + 2 if is_empty_par(LL[i + 1]) else i + 1
-
-                    # That symbol MUST be followed by a string...
-                    if is_valid_index(idx) and LL[idx].type == token.STRING:
-                        string_idx = idx
-
-                        # Skip the string trailer, if one exists.
-                        string_parser = StringParser()
-                        idx = string_parser.parse(LL, string_idx)
-
-                        # The next leaf MAY be a comma iff this line is apart
-                        # of a function argument...
-                        if (
-                            parent_type(LL[0]) == syms.argument
-                            and is_valid_index(idx)
-                            and LL[idx].type == token.COMMA
-                        ):
-                            idx += 1
-
-                        # But no more leaves are allowed...
-                        if not is_valid_index(idx):
-                            return string_idx
-
-        return None
-
-    @staticmethod
-    def _dict_match(LL: List[Leaf]) -> Optional[int]:
-        """
-        Returns:
-            string_idx such that @LL[string_idx] is equal to our target (i.e.
-            matched) string, if this line matches the dictionary key assignment
-            statement requirements listed in the 'Requirements' section of this
-            classes' docstring.
-                OR
-            None, otherwise.
-        """
-        # If this line is apart of a dictionary key assignment...
-        if syms.dictsetmaker in [parent_type(LL[0]), parent_type(LL[0].parent)]:
-            is_valid_index = is_valid_index_factory(LL)
-
-            for (i, leaf) in enumerate(LL):
-                # We MUST find a colon...
-                if leaf.type == token.COLON:
-                    idx = i + 2 if is_empty_par(LL[i + 1]) else i + 1
-
-                    # That colon MUST be followed by a string...
-                    if is_valid_index(idx) and LL[idx].type == token.STRING:
-                        string_idx = idx
-
-                        # Skip the string trailer, if one exists.
-                        string_parser = StringParser()
-                        idx = string_parser.parse(LL, string_idx)
-
-                        # That string MAY be followed by a comma...
-                        if is_valid_index(idx) and LL[idx].type == token.COMMA:
-                            idx += 1
-
-                        # But no more leaves are allowed...
-                        if not is_valid_index(idx):
-                            return string_idx
-
-        return None
-
-    def do_transform(self, line: Line, string_idx: int) -> Iterator[TResult[Line]]:
-        LL = line.leaves
-
-        is_valid_index = is_valid_index_factory(LL)
-        insert_str_child = insert_str_child_factory(LL[string_idx])
-
-        comma_idx = -1
-        ends_with_comma = False
-        if LL[comma_idx].type == token.COMMA:
-            ends_with_comma = True
-
-        leaves_to_steal_comments_from = [LL[string_idx]]
-        if ends_with_comma:
-            leaves_to_steal_comments_from.append(LL[comma_idx])
-
-        # --- First Line
-        first_line = line.clone()
-        left_leaves = LL[:string_idx]
-
-        # We have to remember to account for (possibly invisible) LPAR and RPAR
-        # leaves that already wrapped the target string. If these leaves do
-        # exist, we will replace them with our own LPAR and RPAR leaves.
-        old_parens_exist = False
-        if left_leaves and left_leaves[-1].type == token.LPAR:
-            old_parens_exist = True
-            leaves_to_steal_comments_from.append(left_leaves[-1])
-            left_leaves.pop()
-
-        append_leaves(first_line, line, left_leaves)
-
-        lpar_leaf = Leaf(token.LPAR, "(")
-        if old_parens_exist:
-            replace_child(LL[string_idx - 1], lpar_leaf)
-        else:
-            insert_str_child(lpar_leaf)
-        first_line.append(lpar_leaf)
-
-        # We throw inline comments that were originally to the right of the
-        # target string to the top line. They will now be shown to the right of
-        # the LPAR.
-        for leaf in leaves_to_steal_comments_from:
-            for comment_leaf in line.comments_after(leaf):
-                first_line.append(comment_leaf, preformatted=True)
-
-        yield Ok(first_line)
-
-        # --- Middle (String) Line
-        # We only need to yield one (possibly too long) string line, since the
-        # `StringSplitter` will break it down further if necessary.
-        string_value = LL[string_idx].value
-        string_line = Line(
-            mode=line.mode,
-            depth=line.depth + 1,
-            inside_brackets=True,
-            should_split_rhs=line.should_split_rhs,
-            magic_trailing_comma=line.magic_trailing_comma,
-        )
-        string_leaf = Leaf(token.STRING, string_value)
-        insert_str_child(string_leaf)
-        string_line.append(string_leaf)
-
-        old_rpar_leaf = None
-        if is_valid_index(string_idx + 1):
-            right_leaves = LL[string_idx + 1 :]
-            if ends_with_comma:
-                right_leaves.pop()
-
-            if old_parens_exist:
-                assert (
-                    right_leaves and right_leaves[-1].type == token.RPAR
-                ), "Apparently, old parentheses do NOT exist?!"
-                old_rpar_leaf = right_leaves.pop()
-
-            append_leaves(string_line, line, right_leaves)
-
-        yield Ok(string_line)
-
-        # --- Last Line
-        last_line = line.clone()
-        last_line.bracket_tracker = first_line.bracket_tracker
-
-        new_rpar_leaf = Leaf(token.RPAR, ")")
-        if old_rpar_leaf is not None:
-            replace_child(old_rpar_leaf, new_rpar_leaf)
-        else:
-            insert_str_child(new_rpar_leaf)
-        last_line.append(new_rpar_leaf)
-
-        # If the target string ended with a comma, we place this comma to the
-        # right of the RPAR on the last line.
-        if ends_with_comma:
-            comma_leaf = Leaf(token.COMMA, ",")
-            replace_child(LL[comma_idx], comma_leaf)
-            last_line.append(comma_leaf)
-
-        yield Ok(last_line)
-
-
-class StringParser:
-    """
-    A state machine that aids in parsing a string's "trailer", which can be
-    either non-existent, an old-style formatting sequence (e.g. `% varX` or `%
-    (varX, varY)`), or a method-call / attribute access (e.g. `.format(varX,
-    varY)`).
-
-    NOTE: A new StringParser object MUST be instantiated for each string
-    trailer we need to parse.
-
-    Examples:
-        We shall assume that `line` equals the `Line` object that corresponds
-        to the following line of python code:
-        ```
-        x = "Some {}.".format("String") + some_other_string
-        ```
-
-        Furthermore, we will assume that `string_idx` is some index such that:
-        ```
-        assert line.leaves[string_idx].value == "Some {}."
-        ```
-
-        The following code snippet then holds:
-        ```
-        string_parser = StringParser()
-        idx = string_parser.parse(line.leaves, string_idx)
-        assert line.leaves[idx].type == token.PLUS
-        ```
-    """
-
-    DEFAULT_TOKEN = -1
-
-    # String Parser States
-    START = 1
-    DOT = 2
-    NAME = 3
-    PERCENT = 4
-    SINGLE_FMT_ARG = 5
-    LPAR = 6
-    RPAR = 7
-    DONE = 8
-
-    # Lookup Table for Next State
-    _goto: Dict[Tuple[ParserState, NodeType], ParserState] = {
-        # A string trailer may start with '.' OR '%'.
-        (START, token.DOT): DOT,
-        (START, token.PERCENT): PERCENT,
-        (START, DEFAULT_TOKEN): DONE,
-        # A '.' MUST be followed by an attribute or method name.
-        (DOT, token.NAME): NAME,
-        # A method name MUST be followed by an '(', whereas an attribute name
-        # is the last symbol in the string trailer.
-        (NAME, token.LPAR): LPAR,
-        (NAME, DEFAULT_TOKEN): DONE,
-        # A '%' symbol can be followed by an '(' or a single argument (e.g. a
-        # string or variable name).
-        (PERCENT, token.LPAR): LPAR,
-        (PERCENT, DEFAULT_TOKEN): SINGLE_FMT_ARG,
-        # If a '%' symbol is followed by a single argument, that argument is
-        # the last leaf in the string trailer.
-        (SINGLE_FMT_ARG, DEFAULT_TOKEN): DONE,
-        # If present, a ')' symbol is the last symbol in a string trailer.
-        # (NOTE: LPARS and nested RPARS are not included in this lookup table,
-        # since they are treated as a special case by the parsing logic in this
-        # classes' implementation.)
-        (RPAR, DEFAULT_TOKEN): DONE,
-    }
-
-    def __init__(self) -> None:
-        self._state = self.START
-        self._unmatched_lpars = 0
-
-    def parse(self, leaves: List[Leaf], string_idx: int) -> int:
-        """
-        Pre-conditions:
-            * @leaves[@string_idx].type == token.STRING
-
-        Returns:
-            The index directly after the last leaf which is apart of the string
-            trailer, if a "trailer" exists.
-                OR
-            @string_idx + 1, if no string "trailer" exists.
-        """
-        assert leaves[string_idx].type == token.STRING
-
-        idx = string_idx + 1
-        while idx < len(leaves) and self._next_state(leaves[idx]):
-            idx += 1
-        return idx
-
-    def _next_state(self, leaf: Leaf) -> bool:
-        """
-        Pre-conditions:
-            * On the first call to this function, @leaf MUST be the leaf that
-            was directly after the string leaf in question (e.g. if our target
-            string is `line.leaves[i]` then the first call to this method must
-            be `line.leaves[i + 1]`).
-            * On the next call to this function, the leaf parameter passed in
-            MUST be the leaf directly following @leaf.
-
-        Returns:
-            True iff @leaf is apart of the string's trailer.
-        """
-        # We ignore empty LPAR or RPAR leaves.
-        if is_empty_par(leaf):
-            return True
-
-        next_token = leaf.type
-        if next_token == token.LPAR:
-            self._unmatched_lpars += 1
-
-        current_state = self._state
-
-        # The LPAR parser state is a special case. We will return True until we
-        # find the matching RPAR token.
-        if current_state == self.LPAR:
-            if next_token == token.RPAR:
-                self._unmatched_lpars -= 1
-                if self._unmatched_lpars == 0:
-                    self._state = self.RPAR
-        # Otherwise, we use a lookup table to determine the next state.
-        else:
-            # If the lookup table matches the current state to the next
-            # token, we use the lookup table.
-            if (current_state, next_token) in self._goto:
-                self._state = self._goto[current_state, next_token]
-            else:
-                # Otherwise, we check if a the current state was assigned a
-                # default.
-                if (current_state, self.DEFAULT_TOKEN) in self._goto:
-                    self._state = self._goto[current_state, self.DEFAULT_TOKEN]
-                # If no default has been assigned, then this parser has a logic
-                # error.
-                else:
-                    raise RuntimeError(f"{self.__class__.__name__} LOGIC ERROR!")
-
-            if self._state == self.DONE:
-                return False
-
-        return True
-
-
-def TErr(err_msg: str) -> Err[CannotTransform]:
-    """(T)ransform Err
-
-    Convenience function used when working with the TResult type.
-    """
-    cant_transform = CannotTransform(err_msg)
-    return Err(cant_transform)
-
-
-def contains_pragma_comment(comment_list: List[Leaf]) -> bool:
-    """
-    Returns:
-        True iff one of the comments in @comment_list is a pragma used by one
-        of the more common static analysis tools for python (e.g. mypy, flake8,
-        pylint).
-    """
-    for comment in comment_list:
-        if comment.value.startswith(("# type:", "# noqa", "# pylint:")):
-            return True
-
-    return False
-
-
-def insert_str_child_factory(string_leaf: Leaf) -> Callable[[LN], None]:
-    """
-    Factory for a convenience function that is used to orphan @string_leaf
-    and then insert multiple new leaves into the same part of the node
-    structure that @string_leaf had originally occupied.
-
-    Examples:
-        Let `string_leaf = Leaf(token.STRING, '"foo"')` and `N =
-        string_leaf.parent`. Assume the node `N` has the following
-        original structure:
-
-        Node(
-            expr_stmt, [
-                Leaf(NAME, 'x'),
-                Leaf(EQUAL, '='),
-                Leaf(STRING, '"foo"'),
-            ]
-        )
-
-        We then run the code snippet shown below.
-        ```
-        insert_str_child = insert_str_child_factory(string_leaf)
-
-        lpar = Leaf(token.LPAR, '(')
-        insert_str_child(lpar)
-
-        bar = Leaf(token.STRING, '"bar"')
-        insert_str_child(bar)
-
-        rpar = Leaf(token.RPAR, ')')
-        insert_str_child(rpar)
-        ```
-
-        After which point, it follows that `string_leaf.parent is None` and
-        the node `N` now has the following structure:
-
-        Node(
-            expr_stmt, [
-                Leaf(NAME, 'x'),
-                Leaf(EQUAL, '='),
-                Leaf(LPAR, '('),
-                Leaf(STRING, '"bar"'),
-                Leaf(RPAR, ')'),
-            ]
-        )
-    """
-    string_parent = string_leaf.parent
-    string_child_idx = string_leaf.remove()
-
-    def insert_str_child(child: LN) -> None:
-        nonlocal string_child_idx
-
-        assert string_parent is not None
-        assert string_child_idx is not None
-
-        string_parent.insert_child(string_child_idx, child)
-        string_child_idx += 1
-
-    return insert_str_child
-
-
-def has_triple_quotes(string: str) -> bool:
-    """
-    Returns:
-        True iff @string starts with three quotation characters.
-    """
-    raw_string = string.lstrip(STRING_PREFIX_CHARS)
-    return raw_string[:3] in {'"""', "'''"}
-
-
-def parent_type(node: Optional[LN]) -> Optional[NodeType]:
-    """
-    Returns:
-        @node.parent.type, if @node is not None and has a parent.
-            OR
-        None, otherwise.
-    """
-    if node is None or node.parent is None:
-        return None
-
-    return node.parent.type
-
-
-def is_empty_par(leaf: Leaf) -> bool:
-    return is_empty_lpar(leaf) or is_empty_rpar(leaf)
-
-
-def is_empty_lpar(leaf: Leaf) -> bool:
-    return leaf.type == token.LPAR and leaf.value == ""
-
-
-def is_empty_rpar(leaf: Leaf) -> bool:
-    return leaf.type == token.RPAR and leaf.value == ""
-
-
-def is_valid_index_factory(seq: Sequence[Any]) -> Callable[[int], bool]:
-    """
-    Examples:
-        ```
-        my_list = [1, 2, 3]
-
-        is_valid_index = is_valid_index_factory(my_list)
-
-        assert is_valid_index(0)
-        assert is_valid_index(2)
-
-        assert not is_valid_index(3)
-        assert not is_valid_index(-1)
-        ```
-    """
-
-    def is_valid_index(idx: int) -> bool:
-        """
-        Returns:
-            True iff @idx is positive AND seq[@idx] does NOT raise an
-            IndexError.
-        """
-        return 0 <= idx < len(seq)
-
-    return is_valid_index
-
-
-def line_to_string(line: Line) -> str:
-    """Returns the string representation of @line.
-
-    WARNING: This is known to be computationally expensive.
-    """
-    return str(line).strip("\n")
-
-
-def append_leaves(
-    new_line: Line, old_line: Line, leaves: List[Leaf], preformatted: bool = False
-) -> None:
-    """
-    Append leaves (taken from @old_line) to @new_line, making sure to fix the
-    underlying Node structure where appropriate.
-
-    All of the leaves in @leaves are duplicated. The duplicates are then
-    appended to @new_line and used to replace their originals in the underlying
-    Node structure. Any comments attached to the old leaves are reattached to
-    the new leaves.
-
-    Pre-conditions:
-        set(@leaves) is a subset of set(@old_line.leaves).
-    """
-    for old_leaf in leaves:
-        new_leaf = Leaf(old_leaf.type, old_leaf.value)
-        replace_child(old_leaf, new_leaf)
-        new_line.append(new_leaf, preformatted=preformatted)
-
-        for comment_leaf in old_line.comments_after(old_leaf):
-            new_line.append(comment_leaf, preformatted=True)
-
-
-def replace_child(old_child: LN, new_child: LN) -> None:
-    """
-    Side Effects:
-        * If @old_child.parent is set, replace @old_child with @new_child in
-        @old_child's underlying Node structure.
-            OR
-        * Otherwise, this function does nothing.
-    """
-    parent = old_child.parent
-    if not parent:
-        return
-
-    child_idx = old_child.remove()
-    if child_idx is not None:
-        parent.insert_child(child_idx, new_child)
-
-
-def get_string_prefix(string: str) -> str:
-    """
-    Pre-conditions:
-        * assert_is_leaf_string(@string)
-
-    Returns:
-        @string's prefix (e.g. '', 'r', 'f', or 'rf').
-    """
-    assert_is_leaf_string(string)
-
-    prefix = ""
-    prefix_idx = 0
-    while string[prefix_idx] in STRING_PREFIX_CHARS:
-        prefix += string[prefix_idx].lower()
-        prefix_idx += 1
-
-    return prefix
-
-
-def assert_is_leaf_string(string: str) -> None:
-    """
-    Checks the pre-condition that @string has the format that you would expect
-    of `leaf.value` where `leaf` is some Leaf such that `leaf.type ==
-    token.STRING`. A more precise description of the pre-conditions that are
-    checked are listed below.
-
-    Pre-conditions:
-        * @string starts with either ', ", <prefix>', or <prefix>" where
-        `set(<prefix>)` is some subset of `set(STRING_PREFIX_CHARS)`.
-        * @string ends with a quote character (' or ").
-
-    Raises:
-        AssertionError(...) if the pre-conditions listed above are not
-        satisfied.
-    """
-    dquote_idx = string.find('"')
-    squote_idx = string.find("'")
-    if -1 in [dquote_idx, squote_idx]:
-        quote_idx = max(dquote_idx, squote_idx)
-    else:
-        quote_idx = min(squote_idx, dquote_idx)
-
-    assert (
-        0 <= quote_idx < len(string) - 1
-    ), f"{string!r} is missing a starting quote character (' or \")."
-    assert string[-1] in (
-        "'",
-        '"',
-    ), f"{string!r} is missing an ending quote character (' or \")."
-    assert set(string[:quote_idx]).issubset(
-        set(STRING_PREFIX_CHARS)
-    ), f"{set(string[:quote_idx])} is NOT a subset of {set(STRING_PREFIX_CHARS)}."
-
-
-def left_hand_split(line: Line, _features: Collection[Feature] = ()) -> Iterator[Line]:
-    """Split line into many lines, starting with the first matching bracket pair.
-
-    Note: this usually looks weird, only use this for function definitions.
-    Prefer RHS otherwise.  This is why this function is not symmetrical with
-    :func:`right_hand_split` which also handles optional parentheses.
-    """
-    tail_leaves: List[Leaf] = []
-    body_leaves: List[Leaf] = []
-    head_leaves: List[Leaf] = []
-    current_leaves = head_leaves
-    matching_bracket: Optional[Leaf] = None
-    for leaf in line.leaves:
-        if (
-            current_leaves is body_leaves
-            and leaf.type in CLOSING_BRACKETS
-            and leaf.opening_bracket is matching_bracket
-        ):
-            current_leaves = tail_leaves if body_leaves else head_leaves
-        current_leaves.append(leaf)
-        if current_leaves is head_leaves:
-            if leaf.type in OPENING_BRACKETS:
-                matching_bracket = leaf
-                current_leaves = body_leaves
-    if not matching_bracket:
-        raise CannotSplit("No brackets found")
-
-    head = bracket_split_build_line(head_leaves, line, matching_bracket)
-    body = bracket_split_build_line(body_leaves, line, matching_bracket, is_body=True)
-    tail = bracket_split_build_line(tail_leaves, line, matching_bracket)
-    bracket_split_succeeded_or_raise(head, body, tail)
-    for result in (head, body, tail):
-        if result:
-            yield result
-
-
-def right_hand_split(
-    line: Line,
-    line_length: int,
-    features: Collection[Feature] = (),
-    omit: Collection[LeafID] = (),
-) -> Iterator[Line]:
-    """Split line into many lines, starting with the last matching bracket pair.
-
-    If the split was by optional parentheses, attempt splitting without them, too.
-    `omit` is a collection of closing bracket IDs that shouldn't be considered for
-    this split.
-
-    Note: running this function modifies `bracket_depth` on the leaves of `line`.
-    """
-    tail_leaves: List[Leaf] = []
-    body_leaves: List[Leaf] = []
-    head_leaves: List[Leaf] = []
-    current_leaves = tail_leaves
-    opening_bracket: Optional[Leaf] = None
-    closing_bracket: Optional[Leaf] = None
-    for leaf in reversed(line.leaves):
-        if current_leaves is body_leaves:
-            if leaf is opening_bracket:
-                current_leaves = head_leaves if body_leaves else tail_leaves
-        current_leaves.append(leaf)
-        if current_leaves is tail_leaves:
-            if leaf.type in CLOSING_BRACKETS and id(leaf) not in omit:
-                opening_bracket = leaf.opening_bracket
-                closing_bracket = leaf
-                current_leaves = body_leaves
-    if not (opening_bracket and closing_bracket and head_leaves):
-        # If there is no opening or closing_bracket that means the split failed and
-        # all content is in the tail.  Otherwise, if `head_leaves` are empty, it means
-        # the matching `opening_bracket` wasn't available on `line` anymore.
-        raise CannotSplit("No brackets found")
-
-    tail_leaves.reverse()
-    body_leaves.reverse()
-    head_leaves.reverse()
-    head = bracket_split_build_line(head_leaves, line, opening_bracket)
-    body = bracket_split_build_line(body_leaves, line, opening_bracket, is_body=True)
-    tail = bracket_split_build_line(tail_leaves, line, opening_bracket)
-    bracket_split_succeeded_or_raise(head, body, tail)
-    if (
-        Feature.FORCE_OPTIONAL_PARENTHESES not in features
-        # the opening bracket is an optional paren
-        and opening_bracket.type == token.LPAR
-        and not opening_bracket.value
-        # the closing bracket is an optional paren
-        and closing_bracket.type == token.RPAR
-        and not closing_bracket.value
-        # it's not an import (optional parens are the only thing we can split on
-        # in this case; attempting a split without them is a waste of time)
-        and not line.is_import
-        # there are no standalone comments in the body
-        and not body.contains_standalone_comments(0)
-        # and we can actually remove the parens
-        and can_omit_invisible_parens(body, line_length, omit_on_explode=omit)
-    ):
-        omit = {id(closing_bracket), *omit}
-        try:
-            yield from right_hand_split(line, line_length, features=features, omit=omit)
-            return
-
-        except CannotSplit:
-            if not (
-                can_be_split(body)
-                or is_line_short_enough(body, line_length=line_length)
-            ):
-                raise CannotSplit(
-                    "Splitting failed, body is still too long and can't be split."
-                )
-
-            elif head.contains_multiline_strings() or tail.contains_multiline_strings():
-                raise CannotSplit(
-                    "The current optional pair of parentheses is bound to fail to"
-                    " satisfy the splitting algorithm because the head or the tail"
-                    " contains multiline strings which by definition never fit one"
-                    " line."
-                )
-
-    ensure_visible(opening_bracket)
-    ensure_visible(closing_bracket)
-    for result in (head, body, tail):
-        if result:
-            yield result
-
-
-def bracket_split_succeeded_or_raise(head: Line, body: Line, tail: Line) -> None:
-    """Raise :exc:`CannotSplit` if the last left- or right-hand split failed.
-
-    Do nothing otherwise.
-
-    A left- or right-hand split is based on a pair of brackets. Content before
-    (and including) the opening bracket is left on one line, content inside the
-    brackets is put on a separate line, and finally content starting with and
-    following the closing bracket is put on a separate line.
-
-    Those are called `head`, `body`, and `tail`, respectively. If the split
-    produced the same line (all content in `head`) or ended up with an empty `body`
-    and the `tail` is just the closing bracket, then it's considered failed.
-    """
-    tail_len = len(str(tail).strip())
-    if not body:
-        if tail_len == 0:
-            raise CannotSplit("Splitting brackets produced the same line")
-
-        elif tail_len < 3:
-            raise CannotSplit(
-                f"Splitting brackets on an empty body to save {tail_len} characters is"
-                " not worth it"
-            )
-
-
-def bracket_split_build_line(
-    leaves: List[Leaf], original: Line, opening_bracket: Leaf, *, is_body: bool = False
-) -> Line:
-    """Return a new line with given `leaves` and respective comments from `original`.
-
-    If `is_body` is True, the result line is one-indented inside brackets and as such
-    has its first leaf's prefix normalized and a trailing comma added when expected.
-    """
-    result = Line(mode=original.mode, depth=original.depth)
-    if is_body:
-        result.inside_brackets = True
-        result.depth += 1
-        if leaves:
-            # Since body is a new indent level, remove spurious leading whitespace.
-            normalize_prefix(leaves[0], inside_brackets=True)
-            # Ensure a trailing comma for imports and standalone function arguments, but
-            # be careful not to add one after any comments or within type annotations.
-            no_commas = (
-                original.is_def
-                and opening_bracket.value == "("
-                and not any(leaf.type == token.COMMA for leaf in leaves)
-            )
-
-            if original.is_import or no_commas:
-                for i in range(len(leaves) - 1, -1, -1):
-                    if leaves[i].type == STANDALONE_COMMENT:
-                        continue
-
-                    if leaves[i].type != token.COMMA:
-                        new_comma = Leaf(token.COMMA, ",")
-                        leaves.insert(i + 1, new_comma)
-                    break
-
-    # Populate the line
-    for leaf in leaves:
-        result.append(leaf, preformatted=True)
-        for comment_after in original.comments_after(leaf):
-            result.append(comment_after, preformatted=True)
-    if is_body and should_split_line(result, opening_bracket):
-        result.should_split_rhs = True
-    return result
-
-
-def dont_increase_indentation(split_func: Transformer) -> Transformer:
-    """Normalize prefix of the first leaf in every line returned by `split_func`.
-
-    This is a decorator over relevant split functions.
-    """
-
-    @wraps(split_func)
-    def split_wrapper(line: Line, features: Collection[Feature] = ()) -> Iterator[Line]:
-        for line in split_func(line, features):
-            normalize_prefix(line.leaves[0], inside_brackets=True)
-            yield line
-
-    return split_wrapper
-
-
-@dont_increase_indentation
-def delimiter_split(line: Line, features: Collection[Feature] = ()) -> Iterator[Line]:
-    """Split according to delimiters of the highest priority.
-
-    If the appropriate Features are given, the split will add trailing commas
-    also in function signatures and calls that contain `*` and `**`.
-    """
-    try:
-        last_leaf = line.leaves[-1]
-    except IndexError:
-        raise CannotSplit("Line empty")
-
-    bt = line.bracket_tracker
-    try:
-        delimiter_priority = bt.max_delimiter_priority(exclude={id(last_leaf)})
-    except ValueError:
-        raise CannotSplit("No delimiters found")
-
-    if delimiter_priority == DOT_PRIORITY:
-        if bt.delimiter_count_with_priority(delimiter_priority) == 1:
-            raise CannotSplit("Splitting a single attribute from its owner looks wrong")
-
-    current_line = Line(
-        mode=line.mode, depth=line.depth, inside_brackets=line.inside_brackets
-    )
-    lowest_depth = sys.maxsize
-    trailing_comma_safe = True
-
-    def append_to_line(leaf: Leaf) -> Iterator[Line]:
-        """Append `leaf` to current line or to new line if appending impossible."""
-        nonlocal current_line
-        try:
-            current_line.append_safe(leaf, preformatted=True)
-        except ValueError:
-            yield current_line
-
-            current_line = Line(
-                mode=line.mode, depth=line.depth, inside_brackets=line.inside_brackets
-            )
-            current_line.append(leaf)
-
-    for leaf in line.leaves:
-        yield from append_to_line(leaf)
-
-        for comment_after in line.comments_after(leaf):
-            yield from append_to_line(comment_after)
-
-        lowest_depth = min(lowest_depth, leaf.bracket_depth)
-        if leaf.bracket_depth == lowest_depth:
-            if is_vararg(leaf, within={syms.typedargslist}):
-                trailing_comma_safe = (
-                    trailing_comma_safe and Feature.TRAILING_COMMA_IN_DEF in features
-                )
-            elif is_vararg(leaf, within={syms.arglist, syms.argument}):
-                trailing_comma_safe = (
-                    trailing_comma_safe and Feature.TRAILING_COMMA_IN_CALL in features
-                )
-
-        leaf_priority = bt.delimiters.get(id(leaf))
-        if leaf_priority == delimiter_priority:
-            yield current_line
-
-            current_line = Line(
-                mode=line.mode, depth=line.depth, inside_brackets=line.inside_brackets
-            )
-    if current_line:
-        if (
-            trailing_comma_safe
-            and delimiter_priority == COMMA_PRIORITY
-            and current_line.leaves[-1].type != token.COMMA
-            and current_line.leaves[-1].type != STANDALONE_COMMENT
-        ):
-            new_comma = Leaf(token.COMMA, ",")
-            current_line.append(new_comma)
-        yield current_line
-
-
-@dont_increase_indentation
-def standalone_comment_split(
-    line: Line, features: Collection[Feature] = ()
-) -> Iterator[Line]:
-    """Split standalone comments from the rest of the line."""
-    if not line.contains_standalone_comments(0):
-        raise CannotSplit("Line does not have any standalone comments")
-
-    current_line = Line(
-        mode=line.mode, depth=line.depth, inside_brackets=line.inside_brackets
-    )
-
-    def append_to_line(leaf: Leaf) -> Iterator[Line]:
-        """Append `leaf` to current line or to new line if appending impossible."""
-        nonlocal current_line
-        try:
-            current_line.append_safe(leaf, preformatted=True)
-        except ValueError:
-            yield current_line
-
-            current_line = Line(
-                line.mode, depth=line.depth, inside_brackets=line.inside_brackets
-            )
-            current_line.append(leaf)
-
-    for leaf in line.leaves:
-        yield from append_to_line(leaf)
-
-        for comment_after in line.comments_after(leaf):
-            yield from append_to_line(comment_after)
-
-    if current_line:
-        yield current_line
-
-
-def is_import(leaf: Leaf) -> bool:
-    """Return True if the given leaf starts an import statement."""
-    p = leaf.parent
-    t = leaf.type
-    v = leaf.value
-    return bool(
-        t == token.NAME
-        and (
-            (v == "import" and p and p.type == syms.import_name)
-            or (v == "from" and p and p.type == syms.import_from)
-        )
-    )
-
-
-def is_type_comment(leaf: Leaf, suffix: str = "") -> bool:
-    """Return True if the given leaf is a special comment.
-    Only returns true for type comments for now."""
-    t = leaf.type
-    v = leaf.value
-    return t in {token.COMMENT, STANDALONE_COMMENT} and v.startswith("# type:" + suffix)
-
-
-def normalize_prefix(leaf: Leaf, *, inside_brackets: bool) -> None:
-    """Leave existing extra newlines if not `inside_brackets`. Remove everything
-    else.
-
-    Note: don't use backslashes for formatting or you'll lose your voting rights.
-    """
-    if not inside_brackets:
-        spl = leaf.prefix.split("#")
-        if "\\" not in spl[0]:
-            nl_count = spl[-1].count("\n")
-            if len(spl) > 1:
-                nl_count -= 1
-            leaf.prefix = "\n" * nl_count
-            return
-
-    leaf.prefix = ""
-
-
-def normalize_string_prefix(leaf: Leaf, remove_u_prefix: bool = False) -> None:
-    """Make all string prefixes lowercase.
-
-    If remove_u_prefix is given, also removes any u prefix from the string.
-
-    Note: Mutates its argument.
-    """
-    match = re.match(r"^([" + STRING_PREFIX_CHARS + r"]*)(.*)$", leaf.value, re.DOTALL)
-    assert match is not None, f"failed to match string {leaf.value!r}"
-    orig_prefix = match.group(1)
-    new_prefix = orig_prefix.replace("F", "f").replace("B", "b").replace("U", "u")
-    if remove_u_prefix:
-        new_prefix = new_prefix.replace("u", "")
-    leaf.value = f"{new_prefix}{match.group(2)}"
-
-
-def normalize_string_quotes(leaf: Leaf) -> None:
-    """Prefer double quotes but only if it doesn't cause more escaping.
-
-    Adds or removes backslashes as appropriate. Doesn't parse and fix
-    strings nested in f-strings (yet).
-
-    Note: Mutates its argument.
-    """
-    value = leaf.value.lstrip(STRING_PREFIX_CHARS)
-    if value[:3] == '"""':
-        return
-
-    elif value[:3] == "'''":
-        orig_quote = "'''"
-        new_quote = '"""'
-    elif value[0] == '"':
-        orig_quote = '"'
-        new_quote = "'"
-    else:
-        orig_quote = "'"
-        new_quote = '"'
-    first_quote_pos = leaf.value.find(orig_quote)
-    if first_quote_pos == -1:
-        return  # There's an internal error
-
-    prefix = leaf.value[:first_quote_pos]
-    unescaped_new_quote = re.compile(rf"(([^\\]|^)(\\\\)*){new_quote}")
-    escaped_new_quote = re.compile(rf"([^\\]|^)\\((?:\\\\)*){new_quote}")
-    escaped_orig_quote = re.compile(rf"([^\\]|^)\\((?:\\\\)*){orig_quote}")
-    body = leaf.value[first_quote_pos + len(orig_quote) : -len(orig_quote)]
-    if "r" in prefix.casefold():
-        if unescaped_new_quote.search(body):
-            # There's at least one unescaped new_quote in this raw string
-            # so converting is impossible
-            return
-
-        # Do not introduce or remove backslashes in raw strings
-        new_body = body
-    else:
-        # remove unnecessary escapes
-        new_body = sub_twice(escaped_new_quote, rf"\1\2{new_quote}", body)
-        if body != new_body:
-            # Consider the string without unnecessary escapes as the original
-            body = new_body
-            leaf.value = f"{prefix}{orig_quote}{body}{orig_quote}"
-        new_body = sub_twice(escaped_orig_quote, rf"\1\2{orig_quote}", new_body)
-        new_body = sub_twice(unescaped_new_quote, rf"\1\\{new_quote}", new_body)
-    if "f" in prefix.casefold():
-        matches = re.findall(
-            r"""
-            (?:[^{]|^)\{  # start of the string or a non-{ followed by a single {
-                ([^{].*?)  # contents of the brackets except if begins with {{
-            \}(?:[^}]|$)  # A } followed by end of the string or a non-}
-            """,
-            new_body,
-            re.VERBOSE,
-        )
-        for m in matches:
-            if "\\" in str(m):
-                # Do not introduce backslashes in interpolated expressions
-                return
-
-    if new_quote == '"""' and new_body[-1:] == '"':
-        # edge case:
-        new_body = new_body[:-1] + '\\"'
-    orig_escape_count = body.count("\\")
-    new_escape_count = new_body.count("\\")
-    if new_escape_count > orig_escape_count:
-        return  # Do not introduce more escaping
-
-    if new_escape_count == orig_escape_count and orig_quote == '"':
-        return  # Prefer double quotes
-
-    leaf.value = f"{prefix}{new_quote}{new_body}{new_quote}"
-
-
-def normalize_numeric_literal(leaf: Leaf) -> None:
-    """Normalizes numeric (float, int, and complex) literals.
-
-    All letters used in the representation are normalized to lowercase (except
-    in Python 2 long literals).
-    """
-    text = leaf.value.lower()
-    if text.startswith(("0o", "0b")):
-        # Leave octal and binary literals alone.
-        pass
-    elif text.startswith("0x"):
-        text = format_hex(text)
-    elif "e" in text:
-        text = format_scientific_notation(text)
-    elif text.endswith(("j", "l")):
-        text = format_long_or_complex_number(text)
-    else:
-        text = format_float_or_int_string(text)
-    leaf.value = text
-
-
-def format_hex(text: str) -> str:
-    """
-    Formats a hexadecimal string like "0x12B3"
-    """
-    before, after = text[:2], text[2:]
-    return f"{before}{after.upper()}"
-
-
-def format_scientific_notation(text: str) -> str:
-    """Formats a numeric string utilizing scentific notation"""
-    before, after = text.split("e")
-    sign = ""
-    if after.startswith("-"):
-        after = after[1:]
-        sign = "-"
-    elif after.startswith("+"):
-        after = after[1:]
-    before = format_float_or_int_string(before)
-    return f"{before}e{sign}{after}"
-
-
-def format_long_or_complex_number(text: str) -> str:
-    """Formats a long or complex string like `10L` or `10j`"""
-    number = text[:-1]
-    suffix = text[-1]
-    # Capitalize in "2L" because "l" looks too similar to "1".
-    if suffix == "l":
-        suffix = "L"
-    return f"{format_float_or_int_string(number)}{suffix}"
-
-
-def format_float_or_int_string(text: str) -> str:
-    """Formats a float string like "1.0"."""
-    if "." not in text:
-        return text
-
-    before, after = text.split(".")
-    return f"{before or 0}.{after or 0}"
-
-
-def normalize_invisible_parens(node: Node, parens_after: Set[str]) -> None:
-    """Make existing optional parentheses invisible or create new ones.
-
-    `parens_after` is a set of string leaf values immediately after which parens
-    should be put.
-
-    Standardizes on visible parentheses for single-element tuples, and keeps
-    existing visible parentheses for other tuples and generator expressions.
-    """
-    for pc in list_comments(node.prefix, is_endmarker=False):
-        if pc.value in FMT_OFF:
-            # This `node` has a prefix with `# fmt: off`, don't mess with parens.
-            return
-    check_lpar = False
-    for index, child in enumerate(list(node.children)):
-        # Fixes a bug where invisible parens are not properly stripped from
-        # assignment statements that contain type annotations.
-        if isinstance(child, Node) and child.type == syms.annassign:
-            normalize_invisible_parens(child, parens_after=parens_after)
-
-        # Add parentheses around long tuple unpacking in assignments.
-        if (
-            index == 0
-            and isinstance(child, Node)
-            and child.type == syms.testlist_star_expr
-        ):
-            check_lpar = True
-
-        if check_lpar:
-            if child.type == syms.atom:
-                if maybe_make_parens_invisible_in_atom(child, parent=node):
-                    wrap_in_parentheses(node, child, visible=False)
-            elif is_one_tuple(child):
-                wrap_in_parentheses(node, child, visible=True)
-            elif node.type == syms.import_from:
-                # "import from" nodes store parentheses directly as part of
-                # the statement
-                if child.type == token.LPAR:
-                    # make parentheses invisible
-                    child.value = ""  # type: ignore
-                    node.children[-1].value = ""  # type: ignore
-                elif child.type != token.STAR:
-                    # insert invisible parentheses
-                    node.insert_child(index, Leaf(token.LPAR, ""))
-                    node.append_child(Leaf(token.RPAR, ""))
-                break
-
-            elif not (isinstance(child, Leaf) and is_multiline_string(child)):
-                wrap_in_parentheses(node, child, visible=False)
-
-        check_lpar = isinstance(child, Leaf) and child.value in parens_after
-
-
-def normalize_fmt_off(node: Node) -> None:
-    """Convert content between `# fmt: off`/`# fmt: on` into standalone comments."""
-    try_again = True
-    while try_again:
-        try_again = convert_one_fmt_off_pair(node)
-
-
-def convert_one_fmt_off_pair(node: Node) -> bool:
-    """Convert content of a single `# fmt: off`/`# fmt: on` into a standalone comment.
-
-    Returns True if a pair was converted.
-    """
-    for leaf in node.leaves():
-        previous_consumed = 0
-        for comment in list_comments(leaf.prefix, is_endmarker=False):
-            if comment.value not in FMT_PASS:
-                previous_consumed = comment.consumed
-                continue
-            # We only want standalone comments. If there's no previous leaf or
-            # the previous leaf is indentation, it's a standalone comment in
-            # disguise.
-            if comment.value in FMT_PASS and comment.type != STANDALONE_COMMENT:
-                prev = preceding_leaf(leaf)
-                if prev:
-                    if comment.value in FMT_OFF and prev.type not in WHITESPACE:
-                        continue
-                    if comment.value in FMT_SKIP and prev.type in WHITESPACE:
-                        continue
-
-            ignored_nodes = list(generate_ignored_nodes(leaf, comment))
-            if not ignored_nodes:
-                continue
-
-            first = ignored_nodes[0]  # Can be a container node with the `leaf`.
-            parent = first.parent
-            prefix = first.prefix
-            first.prefix = prefix[comment.consumed :]
-            hidden_value = "".join(str(n) for n in ignored_nodes)
-            if comment.value in FMT_OFF:
-                hidden_value = comment.value + "\n" + hidden_value
-            if comment.value in FMT_SKIP:
-                hidden_value += "  " + comment.value
-            if hidden_value.endswith("\n"):
-                # That happens when one of the `ignored_nodes` ended with a NEWLINE
-                # leaf (possibly followed by a DEDENT).
-                hidden_value = hidden_value[:-1]
-            first_idx: Optional[int] = None
-            for ignored in ignored_nodes:
-                index = ignored.remove()
-                if first_idx is None:
-                    first_idx = index
-            assert parent is not None, "INTERNAL ERROR: fmt: on/off handling (1)"
-            assert first_idx is not None, "INTERNAL ERROR: fmt: on/off handling (2)"
-            parent.insert_child(
-                first_idx,
-                Leaf(
-                    STANDALONE_COMMENT,
-                    hidden_value,
-                    prefix=prefix[:previous_consumed] + "\n" * comment.newlines,
-                ),
-            )
-            return True
-
-    return False
-
-
-def generate_ignored_nodes(leaf: Leaf, comment: ProtoComment) -> Iterator[LN]:
-    """Starting from the container of `leaf`, generate all leaves until `# fmt: on`.
-
-    If comment is skip, returns leaf only.
-    Stops at the end of the block.
-    """
-    container: Optional[LN] = container_of(leaf)
-    if comment.value in FMT_SKIP:
-        prev_sibling = leaf.prev_sibling
-        if comment.value in leaf.prefix and prev_sibling is not None:
-            leaf.prefix = leaf.prefix.replace(comment.value, "")
-            siblings = [prev_sibling]
-            while (
-                "\n" not in prev_sibling.prefix
-                and prev_sibling.prev_sibling is not None
-            ):
-                prev_sibling = prev_sibling.prev_sibling
-                siblings.insert(0, prev_sibling)
-            for sibling in siblings:
-                yield sibling
-        elif leaf.parent is not None:
-            yield leaf.parent
-        return
-    while container is not None and container.type != token.ENDMARKER:
-        if is_fmt_on(container):
-            return
-
-        # fix for fmt: on in children
-        if contains_fmt_on_at_column(container, leaf.column):
-            for child in container.children:
-                if contains_fmt_on_at_column(child, leaf.column):
-                    return
-                yield child
-        else:
-            yield container
-            container = container.next_sibling
-
-
-def is_fmt_on(container: LN) -> bool:
-    """Determine whether formatting is switched on within a container.
-    Determined by whether the last `# fmt:` comment is `on` or `off`.
-    """
-    fmt_on = False
-    for comment in list_comments(container.prefix, is_endmarker=False):
-        if comment.value in FMT_ON:
-            fmt_on = True
-        elif comment.value in FMT_OFF:
-            fmt_on = False
-    return fmt_on
-
-
-def contains_fmt_on_at_column(container: LN, column: int) -> bool:
-    """Determine if children at a given column have formatting switched on."""
-    for child in container.children:
-        if (
-            isinstance(child, Node)
-            and first_leaf_column(child) == column
-            or isinstance(child, Leaf)
-            and child.column == column
-        ):
-            if is_fmt_on(child):
-                return True
-
-    return False
-
-
-def first_leaf_column(node: Node) -> Optional[int]:
-    """Returns the column of the first leaf child of a node."""
-    for child in node.children:
-        if isinstance(child, Leaf):
-            return child.column
-    return None
-
-
-def maybe_make_parens_invisible_in_atom(node: LN, parent: LN) -> bool:
-    """If it's safe, make the parens in the atom `node` invisible, recursively.
-    Additionally, remove repeated, adjacent invisible parens from the atom `node`
-    as they are redundant.
-
-    Returns whether the node should itself be wrapped in invisible parentheses.
-
-    """
-
-    if (
-        node.type != syms.atom
-        or is_empty_tuple(node)
-        or is_one_tuple(node)
-        or (is_yield(node) and parent.type != syms.expr_stmt)
-        or max_delimiter_priority_in_atom(node) >= COMMA_PRIORITY
-    ):
-        return False
-
-    if is_walrus_assignment(node):
-        if parent.type in [
-            syms.annassign,
-            syms.expr_stmt,
-            syms.assert_stmt,
-            syms.return_stmt,
-            # these ones aren't useful to end users, but they do please fuzzers
-            syms.for_stmt,
-            syms.del_stmt,
-        ]:
-            return False
-
-    first = node.children[0]
-    last = node.children[-1]
-    if first.type == token.LPAR and last.type == token.RPAR:
-        middle = node.children[1]
-        # make parentheses invisible
-        first.value = ""  # type: ignore
-        last.value = ""  # type: ignore
-        maybe_make_parens_invisible_in_atom(middle, parent=parent)
-
-        if is_atom_with_invisible_parens(middle):
-            # Strip the invisible parens from `middle` by replacing
-            # it with the child in-between the invisible parens
-            middle.replace(middle.children[1])
-
-        return False
-
-    return True
-
-
-def is_atom_with_invisible_parens(node: LN) -> bool:
-    """Given a `LN`, determines whether it's an atom `node` with invisible
-    parens. Useful in dedupe-ing and normalizing parens.
-    """
-    if isinstance(node, Leaf) or node.type != syms.atom:
-        return False
-
-    first, last = node.children[0], node.children[-1]
-    return (
-        isinstance(first, Leaf)
-        and first.type == token.LPAR
-        and first.value == ""
-        and isinstance(last, Leaf)
-        and last.type == token.RPAR
-        and last.value == ""
-    )
-
-
-def is_empty_tuple(node: LN) -> bool:
-    """Return True if `node` holds an empty tuple."""
-    return (
-        node.type == syms.atom
-        and len(node.children) == 2
-        and node.children[0].type == token.LPAR
-        and node.children[1].type == token.RPAR
-    )
-
-
-def unwrap_singleton_parenthesis(node: LN) -> Optional[LN]:
-    """Returns `wrapped` if `node` is of the shape ( wrapped ).
-
-    Parenthesis can be optional. Returns None otherwise"""
-    if len(node.children) != 3:
-        return None
-
-    lpar, wrapped, rpar = node.children
-    if not (lpar.type == token.LPAR and rpar.type == token.RPAR):
-        return None
-
-    return wrapped
-
-
-def first_child_is_arith(node: Node) -> bool:
-    """Whether first child is an arithmetic or a binary arithmetic expression"""
-    expr_types = {
-        syms.arith_expr,
-        syms.shift_expr,
-        syms.xor_expr,
-        syms.and_expr,
-    }
-    return bool(node.children and node.children[0].type in expr_types)
-
-
-def wrap_in_parentheses(parent: Node, child: LN, *, visible: bool = True) -> None:
-    """Wrap `child` in parentheses.
-
-    This replaces `child` with an atom holding the parentheses and the old
-    child.  That requires moving the prefix.
-
-    If `visible` is False, the leaves will be valueless (and thus invisible).
-    """
-    lpar = Leaf(token.LPAR, "(" if visible else "")
-    rpar = Leaf(token.RPAR, ")" if visible else "")
-    prefix = child.prefix
-    child.prefix = ""
-    index = child.remove() or 0
-    new_child = Node(syms.atom, [lpar, child, rpar])
-    new_child.prefix = prefix
-    parent.insert_child(index, new_child)
-
-
-def is_one_tuple(node: LN) -> bool:
-    """Return True if `node` holds a tuple with one element, with or without parens."""
-    if node.type == syms.atom:
-        gexp = unwrap_singleton_parenthesis(node)
-        if gexp is None or gexp.type != syms.testlist_gexp:
-            return False
-
-        return len(gexp.children) == 2 and gexp.children[1].type == token.COMMA
-
-    return (
-        node.type in IMPLICIT_TUPLE
-        and len(node.children) == 2
-        and node.children[1].type == token.COMMA
-    )
-
-
-def is_walrus_assignment(node: LN) -> bool:
-    """Return True iff `node` is of the shape ( test := test )"""
-    inner = unwrap_singleton_parenthesis(node)
-    return inner is not None and inner.type == syms.namedexpr_test
-
-
-def is_simple_decorator_trailer(node: LN, last: bool = False) -> bool:
-    """Return True iff `node` is a trailer valid in a simple decorator"""
-    return node.type == syms.trailer and (
-        (
-            len(node.children) == 2
-            and node.children[0].type == token.DOT
-            and node.children[1].type == token.NAME
-        )
-        # last trailer can be an argument-less parentheses pair
-        or (
-            last
-            and len(node.children) == 2
-            and node.children[0].type == token.LPAR
-            and node.children[1].type == token.RPAR
-        )
-        # last trailer can be arguments
-        or (
-            last
-            and len(node.children) == 3
-            and node.children[0].type == token.LPAR
-            # and node.children[1].type == syms.argument
-            and node.children[2].type == token.RPAR
-        )
-    )
-
-
-def is_simple_decorator_expression(node: LN) -> bool:
-    """Return True iff `node` could be a 'dotted name' decorator
-
-    This function takes the node of the 'namedexpr_test' of the new decorator
-    grammar and test if it would be valid under the old decorator grammar.
-
-    The old grammar was: decorator: @ dotted_name [arguments] NEWLINE
-    The new grammar is : decorator: @ namedexpr_test NEWLINE
-    """
-    if node.type == token.NAME:
-        return True
-    if node.type == syms.power:
-        if node.children:
-            return (
-                node.children[0].type == token.NAME
-                and all(map(is_simple_decorator_trailer, node.children[1:-1]))
-                and (
-                    len(node.children) < 2
-                    or is_simple_decorator_trailer(node.children[-1], last=True)
-                )
-            )
-    return False
-
-
-def is_yield(node: LN) -> bool:
-    """Return True if `node` holds a `yield` or `yield from` expression."""
-    if node.type == syms.yield_expr:
-        return True
-
-    if node.type == token.NAME and node.value == "yield":  # type: ignore
-        return True
-
-    if node.type != syms.atom:
-        return False
-
-    if len(node.children) != 3:
-        return False
-
-    lpar, expr, rpar = node.children
-    if lpar.type == token.LPAR and rpar.type == token.RPAR:
-        return is_yield(expr)
-
-    return False
-
-
-def is_vararg(leaf: Leaf, within: Set[NodeType]) -> bool:
-    """Return True if `leaf` is a star or double star in a vararg or kwarg.
-
-    If `within` includes VARARGS_PARENTS, this applies to function signatures.
-    If `within` includes UNPACKING_PARENTS, it applies to right hand-side
-    extended iterable unpacking (PEP 3132) and additional unpacking
-    generalizations (PEP 448).
-    """
-    if leaf.type not in VARARGS_SPECIALS or not leaf.parent:
-        return False
-
-    p = leaf.parent
-    if p.type == syms.star_expr:
-        # Star expressions are also used as assignment targets in extended
-        # iterable unpacking (PEP 3132).  See what its parent is instead.
-        if not p.parent:
-            return False
-
-        p = p.parent
-
-    return p.type in within
-
-
-def is_multiline_string(leaf: Leaf) -> bool:
-    """Return True if `leaf` is a multiline string that actually spans many lines."""
-    return has_triple_quotes(leaf.value) and "\n" in leaf.value
-
-
-def is_stub_suite(node: Node) -> bool:
-    """Return True if `node` is a suite with a stub body."""
-    if (
-        len(node.children) != 4
-        or node.children[0].type != token.NEWLINE
-        or node.children[1].type != token.INDENT
-        or node.children[3].type != token.DEDENT
-    ):
-        return False
-
-    return is_stub_body(node.children[2])
-
-
-def is_stub_body(node: LN) -> bool:
-    """Return True if `node` is a simple statement containing an ellipsis."""
-    if not isinstance(node, Node) or node.type != syms.simple_stmt:
-        return False
-
-    if len(node.children) != 2:
-        return False
-
-    child = node.children[0]
-    return (
-        child.type == syms.atom
-        and len(child.children) == 3
-        and all(leaf == Leaf(token.DOT, ".") for leaf in child.children)
-    )
-
-
-def max_delimiter_priority_in_atom(node: LN) -> Priority:
-    """Return maximum delimiter priority inside `node`.
-
-    This is specific to atoms with contents contained in a pair of parentheses.
-    If `node` isn't an atom or there are no enclosing parentheses, returns 0.
-    """
-    if node.type != syms.atom:
-        return 0
-
-    first = node.children[0]
-    last = node.children[-1]
-    if not (first.type == token.LPAR and last.type == token.RPAR):
-        return 0
-
-    bt = BracketTracker()
-    for c in node.children[1:-1]:
-        if isinstance(c, Leaf):
-            bt.mark(c)
-        else:
-            for leaf in c.leaves():
-                bt.mark(leaf)
-    try:
-        return bt.max_delimiter_priority()
-
-    except ValueError:
-        return 0
-
-
-def ensure_visible(leaf: Leaf) -> None:
-    """Make sure parentheses are visible.
-
-    They could be invisible as part of some statements (see
-    :func:`normalize_invisible_parens` and :func:`visit_import_from`).
-    """
-    if leaf.type == token.LPAR:
-        leaf.value = "("
-    elif leaf.type == token.RPAR:
-        leaf.value = ")"
-
-
-def should_split_line(line: Line, opening_bracket: Leaf) -> bool:
-    """Should `line` be immediately split with `delimiter_split()` after RHS?"""
-
-    if not (opening_bracket.parent and opening_bracket.value in "[{("):
-        return False
-
-    # We're essentially checking if the body is delimited by commas and there's more
-    # than one of them (we're excluding the trailing comma and if the delimiter priority
-    # is still commas, that means there's more).
-    exclude = set()
-    trailing_comma = False
-    try:
-        last_leaf = line.leaves[-1]
-        if last_leaf.type == token.COMMA:
-            trailing_comma = True
-            exclude.add(id(last_leaf))
-        max_priority = line.bracket_tracker.max_delimiter_priority(exclude=exclude)
-    except (IndexError, ValueError):
-        return False
-
-    return max_priority == COMMA_PRIORITY and (
-        (line.mode.magic_trailing_comma and trailing_comma)
-        # always explode imports
-        or opening_bracket.parent.type in {syms.atom, syms.import_from}
-    )
-
-
-def is_one_tuple_between(opening: Leaf, closing: Leaf, leaves: List[Leaf]) -> bool:
-    """Return True if content between `opening` and `closing` looks like a one-tuple."""
-    if opening.type != token.LPAR and closing.type != token.RPAR:
-        return False
-
-    depth = closing.bracket_depth + 1
-    for _opening_index, leaf in enumerate(leaves):
-        if leaf is opening:
-            break
-
-    else:
-        raise LookupError("Opening paren not found in `leaves`")
-
-    commas = 0
-    _opening_index += 1
-    for leaf in leaves[_opening_index:]:
-        if leaf is closing:
-            break
-
-        bracket_depth = leaf.bracket_depth
-        if bracket_depth == depth and leaf.type == token.COMMA:
-            commas += 1
-            if leaf.parent and leaf.parent.type in {
-                syms.arglist,
-                syms.typedargslist,
-            }:
-                commas += 1
-                break
-
-    return commas < 2
-
-
-def get_features_used(node: Node) -> Set[Feature]:
-    """Return a set of (relatively) new Python features used in this file.
-
-    Currently looking for:
-    - f-strings;
-    - underscores in numeric literals;
-    - trailing commas after * or ** in function signatures and calls;
-    - positional only arguments in function signatures and lambdas;
-    - assignment expression;
-    - relaxed decorator syntax;
-    """
-    features: Set[Feature] = set()
-    for n in node.pre_order():
-        if n.type == token.STRING:
-            value_head = n.value[:2]  # type: ignore
-            if value_head in {'f"', 'F"', "f'", "F'", "rf", "fr", "RF", "FR"}:
-                features.add(Feature.F_STRINGS)
-
-        elif n.type == token.NUMBER:
-            if "_" in n.value:  # type: ignore
-                features.add(Feature.NUMERIC_UNDERSCORES)
-
-        elif n.type == token.SLASH:
-            if n.parent and n.parent.type in {syms.typedargslist, syms.arglist}:
-                features.add(Feature.POS_ONLY_ARGUMENTS)
-
-        elif n.type == token.COLONEQUAL:
-            features.add(Feature.ASSIGNMENT_EXPRESSIONS)
-
-        elif n.type == syms.decorator:
-            if len(n.children) > 1 and not is_simple_decorator_expression(
-                n.children[1]
-            ):
-                features.add(Feature.RELAXED_DECORATORS)
-
-        elif (
-            n.type in {syms.typedargslist, syms.arglist}
-            and n.children
-            and n.children[-1].type == token.COMMA
-        ):
-            if n.type == syms.typedargslist:
-                feature = Feature.TRAILING_COMMA_IN_DEF
-            else:
-                feature = Feature.TRAILING_COMMA_IN_CALL
-
-            for ch in n.children:
-                if ch.type in STARS:
-                    features.add(feature)
-
-                if ch.type == syms.argument:
-                    for argch in ch.children:
-                        if argch.type in STARS:
-                            features.add(feature)
-
-    return features
-
-
-def detect_target_versions(node: Node) -> Set[TargetVersion]:
-    """Detect the version to target based on the nodes used."""
-    features = get_features_used(node)
-    return {
-        version for version in TargetVersion if features <= VERSION_TO_FEATURES[version]
-    }
-
-
-def generate_trailers_to_omit(line: Line, line_length: int) -> Iterator[Set[LeafID]]:
-    """Generate sets of closing bracket IDs that should be omitted in a RHS.
-
-    Brackets can be omitted if the entire trailer up to and including
-    a preceding closing bracket fits in one line.
-
-    Yielded sets are cumulative (contain results of previous yields, too).  First
-    set is empty, unless the line should explode, in which case bracket pairs until
-    the one that needs to explode are omitted.
-    """
-
-    omit: Set[LeafID] = set()
-    if not line.magic_trailing_comma:
-        yield omit
-
-    length = 4 * line.depth
-    opening_bracket: Optional[Leaf] = None
-    closing_bracket: Optional[Leaf] = None
-    inner_brackets: Set[LeafID] = set()
-    for index, leaf, leaf_length in enumerate_with_length(line, reversed=True):
-        length += leaf_length
-        if length > line_length:
-            break
-
-        has_inline_comment = leaf_length > len(leaf.value) + len(leaf.prefix)
-        if leaf.type == STANDALONE_COMMENT or has_inline_comment:
-            break
-
-        if opening_bracket:
-            if leaf is opening_bracket:
-                opening_bracket = None
-            elif leaf.type in CLOSING_BRACKETS:
-                prev = line.leaves[index - 1] if index > 0 else None
-                if (
-                    prev
-                    and prev.type == token.COMMA
-                    and not is_one_tuple_between(
-                        leaf.opening_bracket, leaf, line.leaves
-                    )
-                ):
-                    # Never omit bracket pairs with trailing commas.
-                    # We need to explode on those.
-                    break
-
-                inner_brackets.add(id(leaf))
-        elif leaf.type in CLOSING_BRACKETS:
-            prev = line.leaves[index - 1] if index > 0 else None
-            if prev and prev.type in OPENING_BRACKETS:
-                # Empty brackets would fail a split so treat them as "inner"
-                # brackets (e.g. only add them to the `omit` set if another
-                # pair of brackets was good enough.
-                inner_brackets.add(id(leaf))
-                continue
-
-            if closing_bracket:
-                omit.add(id(closing_bracket))
-                omit.update(inner_brackets)
-                inner_brackets.clear()
-                yield omit
-
-            if (
-                prev
-                and prev.type == token.COMMA
-                and not is_one_tuple_between(leaf.opening_bracket, leaf, line.leaves)
-            ):
-                # Never omit bracket pairs with trailing commas.
-                # We need to explode on those.
-                break
-
-            if leaf.value:
-                opening_bracket = leaf.opening_bracket
-                closing_bracket = leaf
-
-
-def get_future_imports(node: Node) -> Set[str]:
-    """Return a set of __future__ imports in the file."""
-    imports: Set[str] = set()
-
-    def get_imports_from_children(children: List[LN]) -> Generator[str, None, None]:
-        for child in children:
-            if isinstance(child, Leaf):
-                if child.type == token.NAME:
-                    yield child.value
-
-            elif child.type == syms.import_as_name:
-                orig_name = child.children[0]
-                assert isinstance(orig_name, Leaf), "Invalid syntax parsing imports"
-                assert orig_name.type == token.NAME, "Invalid syntax parsing imports"
-                yield orig_name.value
-
-            elif child.type == syms.import_as_names:
-                yield from get_imports_from_children(child.children)
-
-            else:
-                raise AssertionError("Invalid syntax parsing imports")
-
-    for child in node.children:
-        if child.type != syms.simple_stmt:
-            break
-
-        first_child = child.children[0]
-        if isinstance(first_child, Leaf):
-            # Continue looking if we see a docstring; otherwise stop.
-            if (
-                len(child.children) == 2
-                and first_child.type == token.STRING
-                and child.children[1].type == token.NEWLINE
-            ):
-                continue
-
-            break
-
-        elif first_child.type == syms.import_from:
-            module_name = first_child.children[1]
-            if not isinstance(module_name, Leaf) or module_name.value != "__future__":
-                break
-
-            imports |= set(get_imports_from_children(first_child.children[3:]))
-        else:
-            break
-
-    return imports
-
-
-@lru_cache()
-def get_gitignore(root: Path) -> PathSpec:
-    """Return a PathSpec matching gitignore content if present."""
-    gitignore = root / ".gitignore"
-    lines: List[str] = []
-    if gitignore.is_file():
-        with gitignore.open() as gf:
-            lines = gf.readlines()
-    return PathSpec.from_lines("gitwildmatch", lines)
-
-
-def normalize_path_maybe_ignore(
-    path: Path, root: Path, report: "Report"
-) -> Optional[str]:
-    """Normalize `path`. May return `None` if `path` was ignored.
-
-    `report` is where "path ignored" output goes.
-    """
-    try:
-        abspath = path if path.is_absolute() else Path.cwd() / path
-        normalized_path = abspath.resolve().relative_to(root).as_posix()
-    except OSError as e:
-        report.path_ignored(path, f"cannot be read because {e}")
-        return None
-
-    except ValueError:
-        if path.is_symlink():
-            report.path_ignored(path, f"is a symbolic link that points outside {root}")
-            return None
-
-        raise
-
-    return normalized_path
-
-
-def path_is_excluded(
-    normalized_path: str,
-    pattern: Optional[Pattern[str]],
-) -> bool:
-    match = pattern.search(normalized_path) if pattern else None
-    return bool(match and match.group(0))
-
-
-def gen_python_files(
-    paths: Iterable[Path],
-    root: Path,
-    include: Pattern[str],
-    exclude: Pattern[str],
-    extend_exclude: Optional[Pattern[str]],
-    force_exclude: Optional[Pattern[str]],
-    report: "Report",
-    gitignore: Optional[PathSpec],
-) -> Iterator[Path]:
-    """Generate all files under `path` whose paths are not excluded by the
-    `exclude_regex`, `extend_exclude`, or `force_exclude` regexes,
-    but are included by the `include` regex.
-
-    Symbolic links pointing outside of the `root` directory are ignored.
-
-    `report` is where output about exclusions goes.
-    """
-    assert root.is_absolute(), f"INTERNAL ERROR: `root` must be absolute but is {root}"
-    for child in paths:
-        normalized_path = normalize_path_maybe_ignore(child, root, report)
-        if normalized_path is None:
-            continue
-
-        # First ignore files matching .gitignore, if passed
-        if gitignore is not None and gitignore.match_file(normalized_path):
-            report.path_ignored(child, "matches the .gitignore file content")
-            continue
-
-        # Then ignore with `--exclude` `--extend-exclude` and `--force-exclude` options.
-        normalized_path = "/" + normalized_path
-        if child.is_dir():
-            normalized_path += "/"
-
-        if path_is_excluded(normalized_path, exclude):
-            report.path_ignored(child, "matches the --exclude regular expression")
-            continue
-
-        if path_is_excluded(normalized_path, extend_exclude):
-            report.path_ignored(
-                child, "matches the --extend-exclude regular expression"
-            )
-            continue
-
-        if path_is_excluded(normalized_path, force_exclude):
-            report.path_ignored(child, "matches the --force-exclude regular expression")
-            continue
-
-        if child.is_dir():
-            yield from gen_python_files(
-                child.iterdir(),
-                root,
-                include,
-                exclude,
-                extend_exclude,
-                force_exclude,
-                report,
-                gitignore,
-            )
-
-        elif child.is_file():
-            include_match = include.search(normalized_path) if include else True
-            if include_match:
-                yield child
-
-
-@lru_cache()
-def find_project_root(srcs: Tuple[str, ...]) -> Path:
-    """Return a directory containing .git, .hg, or pyproject.toml.
-
-    That directory will be a common parent of all files and directories
-    passed in `srcs`.
-
-    If no directory in the tree contains a marker that would specify it's the
-    project root, the root of the file system is returned.
-    """
-    if not srcs:
-        return Path("/").resolve()
-
-    path_srcs = [Path(Path.cwd(), src).resolve() for src in srcs]
-
-    # A list of lists of parents for each 'src'. 'src' is included as a
-    # "parent" of itself if it is a directory
-    src_parents = [
-        list(path.parents) + ([path] if path.is_dir() else []) for path in path_srcs
-    ]
-
-    common_base = max(
-        set.intersection(*(set(parents) for parents in src_parents)),
-        key=lambda path: path.parts,
-    )
-
-    for directory in (common_base, *common_base.parents):
-        if (directory / ".git").exists():
-            return directory
-
-        if (directory / ".hg").is_dir():
-            return directory
-
-        if (directory / "pyproject.toml").is_file():
-            return directory
-
-    return directory
-
-
-@lru_cache()
-def find_user_pyproject_toml() -> Path:
-    r"""Return the path to the top-level user configuration for black.
-
-    This looks for ~\.black on Windows and ~/.config/black on Linux and other
-    Unix systems.
-    """
-    if sys.platform == "win32":
-        # Windows
-        user_config_path = Path.home() / ".black"
-    else:
-        config_root = os.environ.get("XDG_CONFIG_HOME", "~/.config")
-        user_config_path = Path(config_root).expanduser() / "black"
-    return user_config_path.resolve()
-
-
-@dataclass
-class Report:
-    """Provides a reformatting counter. Can be rendered with `str(report)`."""
-
-    check: bool = False
-    diff: bool = False
-    quiet: bool = False
-    verbose: bool = False
-    change_count: int = 0
-    same_count: int = 0
-    failure_count: int = 0
-
-    def done(self, src: Path, changed: Changed) -> None:
-        """Increment the counter for successful reformatting. Write out a message."""
-        if changed is Changed.YES:
-            reformatted = "would reformat" if self.check or self.diff else "reformatted"
-            if self.verbose or not self.quiet:
-                out(f"{reformatted} {src}")
-            self.change_count += 1
-        else:
-            if self.verbose:
-                if changed is Changed.NO:
-                    msg = f"{src} already well formatted, good job."
-                else:
-                    msg = f"{src} wasn't modified on disk since last run."
-                out(msg, bold=False)
-            self.same_count += 1
-
-    def failed(self, src: Path, message: str) -> None:
-        """Increment the counter for failed reformatting. Write out a message."""
-        err(f"error: cannot format {src}: {message}")
-        self.failure_count += 1
-
-    def path_ignored(self, path: Path, message: str) -> None:
-        if self.verbose:
-            out(f"{path} ignored: {message}", bold=False)
-
-    @property
-    def return_code(self) -> int:
-        """Return the exit code that the app should use.
-
-        This considers the current state of changed files and failures:
-        - if there were any failures, return 123;
-        - if any files were changed and --check is being used, return 1;
-        - otherwise return 0.
-        """
-        # According to http://tldp.org/LDP/abs/html/exitcodes.html starting with
-        # 126 we have special return codes reserved by the shell.
-        if self.failure_count:
-            return 123
-
-        elif self.change_count and self.check:
-            return 1
-
-        return 0
-
-    def __str__(self) -> str:
-        """Render a color report of the current state.
-
-        Use `click.unstyle` to remove colors.
-        """
-        if self.check or self.diff:
-            reformatted = "would be reformatted"
-            unchanged = "would be left unchanged"
-            failed = "would fail to reformat"
-        else:
-            reformatted = "reformatted"
-            unchanged = "left unchanged"
-            failed = "failed to reformat"
-        report = []
-        if self.change_count:
-            s = "s" if self.change_count > 1 else ""
-            report.append(
-                click.style(f"{self.change_count} file{s} {reformatted}", bold=True)
-            )
-        if self.same_count:
-            s = "s" if self.same_count > 1 else ""
-            report.append(f"{self.same_count} file{s} {unchanged}")
-        if self.failure_count:
-            s = "s" if self.failure_count > 1 else ""
-            report.append(
-                click.style(f"{self.failure_count} file{s} {failed}", fg="red")
-            )
-        return ", ".join(report) + "."
-
-
-def parse_ast(src: str) -> Union[ast.AST, ast3.AST, ast27.AST]:
-    filename = "<unknown>"
-    if sys.version_info >= (3, 8):
-        # TODO: support Python 4+ ;)
-        for minor_version in range(sys.version_info[1], 4, -1):
-            try:
-                return ast.parse(src, filename, feature_version=(3, minor_version))
-            except SyntaxError:
-                continue
-    else:
-        for feature_version in (7, 6):
-            try:
-                return ast3.parse(src, filename, feature_version=feature_version)
-            except SyntaxError:
-                continue
-    if ast27.__name__ == "ast":
-        raise SyntaxError(
-            "The requested source code has invalid Python 3 syntax.\n"
-            "If you are trying to format Python 2 files please reinstall Black"
-            " with the 'python2' extra: `python3 -m pip install black[python2]`."
-        )
-    return ast27.parse(src)
-
-
-def _fixup_ast_constants(
-    node: Union[ast.AST, ast3.AST, ast27.AST]
-) -> Union[ast.AST, ast3.AST, ast27.AST]:
-    """Map ast nodes deprecated in 3.8 to Constant."""
-    if isinstance(node, (ast.Str, ast3.Str, ast27.Str, ast.Bytes, ast3.Bytes)):
-        return ast.Constant(value=node.s)
-
-    if isinstance(node, (ast.Num, ast3.Num, ast27.Num)):
-        return ast.Constant(value=node.n)
-
-    if isinstance(node, (ast.NameConstant, ast3.NameConstant)):
-        return ast.Constant(value=node.value)
-
-    return node
-
-
-def _stringify_ast(
-    node: Union[ast.AST, ast3.AST, ast27.AST], depth: int = 0
-) -> Iterator[str]:
-    """Simple visitor generating strings to compare ASTs by content."""
-
-    node = _fixup_ast_constants(node)
-
-    yield f"{'  ' * depth}{node.__class__.__name__}("
-
-    for field in sorted(node._fields):  # noqa: F402
-        # TypeIgnore has only one field 'lineno' which breaks this comparison
-        type_ignore_classes = (ast3.TypeIgnore, ast27.TypeIgnore)
-        if sys.version_info >= (3, 8):
-            type_ignore_classes += (ast.TypeIgnore,)
-        if isinstance(node, type_ignore_classes):
-            break
-
-        try:
-            value = getattr(node, field)
-        except AttributeError:
-            continue
-
-        yield f"{'  ' * (depth+1)}{field}="
-
-        if isinstance(value, list):
-            for item in value:
-                # Ignore nested tuples within del statements, because we may insert
-                # parentheses and they change the AST.
-                if (
-                    field == "targets"
-                    and isinstance(node, (ast.Delete, ast3.Delete, ast27.Delete))
-                    and isinstance(item, (ast.Tuple, ast3.Tuple, ast27.Tuple))
-                ):
-                    for item in item.elts:
-                        yield from _stringify_ast(item, depth + 2)
-
-                elif isinstance(item, (ast.AST, ast3.AST, ast27.AST)):
-                    yield from _stringify_ast(item, depth + 2)
-
-        elif isinstance(value, (ast.AST, ast3.AST, ast27.AST)):
-            yield from _stringify_ast(value, depth + 2)
-
-        else:
-            # Constant strings may be indented across newlines, if they are
-            # docstrings; fold spaces after newlines when comparing. Similarly,
-            # trailing and leading space may be removed.
-            # Note that when formatting Python 2 code, at least with Windows
-            # line-endings, docstrings can end up here as bytes instead of
-            # str so make sure that we handle both cases.
-            if (
-                isinstance(node, ast.Constant)
-                and field == "value"
-                and isinstance(value, (str, bytes))
-            ):
-                lineend = "\n" if isinstance(value, str) else b"\n"
-                # To normalize, we strip any leading and trailing space from
-                # each line...
-                stripped = [line.strip() for line in value.splitlines()]
-                normalized = lineend.join(stripped)  # type: ignore[attr-defined]
-                # ...and remove any blank lines at the beginning and end of
-                # the whole string
-                normalized = normalized.strip()
-            else:
-                normalized = value
-            yield f"{'  ' * (depth+2)}{normalized!r},  # {value.__class__.__name__}"
-
-    yield f"{'  ' * depth})  # /{node.__class__.__name__}"
-
-
-def assert_equivalent(src: str, dst: str, *, pass_num: int = 1) -> None:
-    """Raise AssertionError if `src` and `dst` aren't equivalent."""
-    try:
-        src_ast = parse_ast(src)
-    except Exception as exc:
-        raise AssertionError(
-            "cannot use --safe with this file; failed to parse source file.  AST"
-            f" error message: {exc}"
-        )
-
-    try:
-        dst_ast = parse_ast(dst)
-    except Exception as exc:
-        log = dump_to_file("".join(traceback.format_tb(exc.__traceback__)), dst)
-        raise AssertionError(
-            f"INTERNAL ERROR: Black produced invalid code on pass {pass_num}: {exc}. "
-            "Please report a bug on https://github.com/psf/black/issues.  "
-            f"This invalid output might be helpful: {log}"
-        ) from None
-
-    src_ast_str = "\n".join(_stringify_ast(src_ast))
-    dst_ast_str = "\n".join(_stringify_ast(dst_ast))
-    if src_ast_str != dst_ast_str:
-        log = dump_to_file(diff(src_ast_str, dst_ast_str, "src", "dst"))
-        raise AssertionError(
-            "INTERNAL ERROR: Black produced code that is not equivalent to the"
-            f" source on pass {pass_num}.  Please report a bug on "
-            f"https://github.com/psf/black/issues.  This diff might be helpful: {log}"
-        ) from None
-
-
-def assert_stable(src: str, dst: str, mode: Mode) -> None:
-    """Raise AssertionError if `dst` reformats differently the second time."""
-    newdst = format_str(dst, mode=mode)
-    if dst != newdst:
-        log = dump_to_file(
-            str(mode),
-            diff(src, dst, "source", "first pass"),
-            diff(dst, newdst, "first pass", "second pass"),
-        )
-        raise AssertionError(
-            "INTERNAL ERROR: Black produced different code on the second pass of the"
-            " formatter.  Please report a bug on https://github.com/psf/black/issues."
-            f"  This diff might be helpful: {log}"
-        ) from None
-
-
-@mypyc_attr(patchable=True)
-def dump_to_file(*output: str, ensure_final_newline: bool = True) -> str:
-    """Dump `output` to a temporary file. Return path to the file."""
-    with tempfile.NamedTemporaryFile(
-        mode="w", prefix="blk_", suffix=".log", delete=False, encoding="utf8"
-    ) as f:
-        for lines in output:
-            f.write(lines)
-            if ensure_final_newline and lines and lines[-1] != "\n":
-                f.write("\n")
-    return f.name
-
-
-@contextmanager
-def nullcontext() -> Iterator[None]:
-    """Return an empty context manager.
-
-    To be used like `nullcontext` in Python 3.7.
-    """
-    yield
-
-
-def diff(a: str, b: str, a_name: str, b_name: str) -> str:
-    """Return a unified diff string between strings `a` and `b`."""
-    import difflib
-
-    a_lines = [line for line in a.splitlines(keepends=True)]
-    b_lines = [line for line in b.splitlines(keepends=True)]
-    diff_lines = []
-    for line in difflib.unified_diff(
-        a_lines, b_lines, fromfile=a_name, tofile=b_name, n=5
-    ):
-        # Work around https://bugs.python.org/issue2142
-        # See https://www.gnu.org/software/diffutils/manual/html_node/Incomplete-Lines.html
-        if line[-1] == "\n":
-            diff_lines.append(line)
-        else:
-            diff_lines.append(line + "\n")
-            diff_lines.append("\\ No newline at end of file\n")
-    return "".join(diff_lines)
-
-
-def cancel(tasks: Iterable["asyncio.Task[Any]"]) -> None:
-    """asyncio signal handler that cancels all `tasks` and reports to stderr."""
-    err("Aborted!")
-    for task in tasks:
-        task.cancel()
-
-
-def shutdown(loop: asyncio.AbstractEventLoop) -> None:
-    """Cancel all pending tasks on `loop`, wait for them, and close the loop."""
-    try:
-        if sys.version_info[:2] >= (3, 7):
-            all_tasks = asyncio.all_tasks
-        else:
-            all_tasks = asyncio.Task.all_tasks
-        # This part is borrowed from asyncio/runners.py in Python 3.7b2.
-        to_cancel = [task for task in all_tasks(loop) if not task.done()]
-        if not to_cancel:
-            return
-
-        for task in to_cancel:
-            task.cancel()
-        loop.run_until_complete(
-            asyncio.gather(*to_cancel, loop=loop, return_exceptions=True)
-        )
-    finally:
-        # `concurrent.futures.Future` objects cannot be cancelled once they
-        # are already running. There might be some when the `shutdown()` happened.
-        # Silence their logger's spew about the event loop being closed.
-        cf_logger = logging.getLogger("concurrent.futures")
-        cf_logger.setLevel(logging.CRITICAL)
-        loop.close()
-
-
-def sub_twice(regex: Pattern[str], replacement: str, original: str) -> str:
-    """Replace `regex` with `replacement` twice on `original`.
-
-    This is used by string normalization to perform replaces on
-    overlapping matches.
-    """
-    return regex.sub(replacement, regex.sub(replacement, original))
-
-
-def re_compile_maybe_verbose(regex: str) -> Pattern[str]:
-    """Compile a regular expression string in `regex`.
-
-    If it contains newlines, use verbose mode.
-    """
-    if "\n" in regex:
-        regex = "(?x)" + regex
-    compiled: Pattern[str] = re.compile(regex)
-    return compiled
-
-
-def enumerate_reversed(sequence: Sequence[T]) -> Iterator[Tuple[Index, T]]:
-    """Like `reversed(enumerate(sequence))` if that were possible."""
-    index = len(sequence) - 1
-    for element in reversed(sequence):
-        yield (index, element)
-        index -= 1
-
-
-def enumerate_with_length(
-    line: Line, reversed: bool = False
-) -> Iterator[Tuple[Index, Leaf, int]]:
-    """Return an enumeration of leaves with their length.
-
-    Stops prematurely on multiline strings and standalone comments.
-    """
-    op = cast(
-        Callable[[Sequence[Leaf]], Iterator[Tuple[Index, Leaf]]],
-        enumerate_reversed if reversed else enumerate,
-    )
-    for index, leaf in op(line.leaves):
-        length = len(leaf.prefix) + len(leaf.value)
-        if "\n" in leaf.value:
-            return  # Multiline strings, we can't continue.
-
-        for comment in line.comments_after(leaf):
-            length += len(comment.value)
-
-        yield index, leaf, length
-
-
-def is_line_short_enough(line: Line, *, line_length: int, line_str: str = "") -> bool:
-    """Return True if `line` is no longer than `line_length`.
-
-    Uses the provided `line_str` rendering, if any, otherwise computes a new one.
-    """
-    if not line_str:
-        line_str = line_to_string(line)
-    return (
-        len(line_str) <= line_length
-        and "\n" not in line_str  # multiline strings
-        and not line.contains_standalone_comments()
-    )
-
-
-def can_be_split(line: Line) -> bool:
-    """Return False if the line cannot be split *for sure*.
-
-    This is not an exhaustive search but a cheap heuristic that we can use to
-    avoid some unfortunate formattings (mostly around wrapping unsplittable code
-    in unnecessary parentheses).
-    """
-    leaves = line.leaves
-    if len(leaves) < 2:
-        return False
-
-    if leaves[0].type == token.STRING and leaves[1].type == token.DOT:
-        call_count = 0
-        dot_count = 0
-        next = leaves[-1]
-        for leaf in leaves[-2::-1]:
-            if leaf.type in OPENING_BRACKETS:
-                if next.type not in CLOSING_BRACKETS:
-                    return False
-
-                call_count += 1
-            elif leaf.type == token.DOT:
-                dot_count += 1
-            elif leaf.type == token.NAME:
-                if not (next.type == token.DOT or next.type in OPENING_BRACKETS):
-                    return False
-
-            elif leaf.type not in CLOSING_BRACKETS:
-                return False
-
-            if dot_count > 1 and call_count > 1:
-                return False
-
-    return True
-
-
-def can_omit_invisible_parens(
-    line: Line,
-    line_length: int,
-    omit_on_explode: Collection[LeafID] = (),
-) -> bool:
-    """Does `line` have a shape safe to reformat without optional parens around it?
-
-    Returns True for only a subset of potentially nice looking formattings but
-    the point is to not return false positives that end up producing lines that
-    are too long.
-    """
-    bt = line.bracket_tracker
-    if not bt.delimiters:
-        # Without delimiters the optional parentheses are useless.
-        return True
-
-    max_priority = bt.max_delimiter_priority()
-    if bt.delimiter_count_with_priority(max_priority) > 1:
-        # With more than one delimiter of a kind the optional parentheses read better.
-        return False
-
-    if max_priority == DOT_PRIORITY:
-        # A single stranded method call doesn't require optional parentheses.
-        return True
-
-    assert len(line.leaves) >= 2, "Stranded delimiter"
-
-    # With a single delimiter, omit if the expression starts or ends with
-    # a bracket.
-    first = line.leaves[0]
-    second = line.leaves[1]
-    if first.type in OPENING_BRACKETS and second.type not in CLOSING_BRACKETS:
-        if _can_omit_opening_paren(line, first=first, line_length=line_length):
-            return True
-
-        # Note: we are not returning False here because a line might have *both*
-        # a leading opening bracket and a trailing closing bracket.  If the
-        # opening bracket doesn't match our rule, maybe the closing will.
-
-    penultimate = line.leaves[-2]
-    last = line.leaves[-1]
-    if line.magic_trailing_comma:
-        try:
-            penultimate, last = last_two_except(line.leaves, omit=omit_on_explode)
-        except LookupError:
-            # Turns out we'd omit everything.  We cannot skip the optional parentheses.
-            return False
-
-    if (
-        last.type == token.RPAR
-        or last.type == token.RBRACE
-        or (
-            # don't use indexing for omitting optional parentheses;
-            # it looks weird
-            last.type == token.RSQB
-            and last.parent
-            and last.parent.type != syms.trailer
-        )
-    ):
-        if penultimate.type in OPENING_BRACKETS:
-            # Empty brackets don't help.
-            return False
-
-        if is_multiline_string(first):
-            # Additional wrapping of a multiline string in this situation is
-            # unnecessary.
-            return True
-
-        if line.magic_trailing_comma and penultimate.type == token.COMMA:
-            # The rightmost non-omitted bracket pair is the one we want to explode on.
-            return True
-
-        if _can_omit_closing_paren(line, last=last, line_length=line_length):
-            return True
-
-    return False
-
-
-def _can_omit_opening_paren(line: Line, *, first: Leaf, line_length: int) -> bool:
-    """See `can_omit_invisible_parens`."""
-    remainder = False
-    length = 4 * line.depth
-    _index = -1
-    for _index, leaf, leaf_length in enumerate_with_length(line):
-        if leaf.type in CLOSING_BRACKETS and leaf.opening_bracket is first:
-            remainder = True
-        if remainder:
-            length += leaf_length
-            if length > line_length:
-                break
-
-            if leaf.type in OPENING_BRACKETS:
-                # There are brackets we can further split on.
-                remainder = False
-
-    else:
-        # checked the entire string and line length wasn't exceeded
-        if len(line.leaves) == _index + 1:
-            return True
-
-    return False
-
-
-def _can_omit_closing_paren(line: Line, *, last: Leaf, line_length: int) -> bool:
-    """See `can_omit_invisible_parens`."""
-    length = 4 * line.depth
-    seen_other_brackets = False
-    for _index, leaf, leaf_length in enumerate_with_length(line):
-        length += leaf_length
-        if leaf is last.opening_bracket:
-            if seen_other_brackets or length <= line_length:
-                return True
-
-        elif leaf.type in OPENING_BRACKETS:
-            # There are brackets we can further split on.
-            seen_other_brackets = True
-
-    return False
-
-
-def last_two_except(leaves: List[Leaf], omit: Collection[LeafID]) -> Tuple[Leaf, Leaf]:
-    """Return (penultimate, last) leaves skipping brackets in `omit` and contents."""
-    stop_after = None
-    last = None
-    for leaf in reversed(leaves):
-        if stop_after:
-            if leaf is stop_after:
-                stop_after = None
-            continue
-
-        if last:
-            return leaf, last
-
-        if id(leaf) in omit:
-            stop_after = leaf.opening_bracket
-        else:
-            last = leaf
-    else:
-        raise LookupError("Last two leaves were also skipped")
-
-
-def run_transformer(
-    line: Line,
-    transform: Transformer,
-    mode: Mode,
-    features: Collection[Feature],
-    *,
-    line_str: str = "",
-) -> List[Line]:
-    if not line_str:
-        line_str = line_to_string(line)
-    result: List[Line] = []
-    for transformed_line in transform(line, features):
-        if str(transformed_line).strip("\n") == line_str:
-            raise CannotTransform("Line transformer returned an unchanged result")
-
-        result.extend(transform_line(transformed_line, mode=mode, features=features))
-
-    if not (
-        transform.__name__ == "rhs"
-        and line.bracket_tracker.invisible
-        and not any(bracket.value for bracket in line.bracket_tracker.invisible)
-        and not line.contains_multiline_strings()
-        and not result[0].contains_uncollapsable_type_comments()
-        and not result[0].contains_unsplittable_type_ignore()
-        and not is_line_short_enough(result[0], line_length=mode.line_length)
-    ):
-        return result
-
-    line_copy = line.clone()
-    append_leaves(line_copy, line, line.leaves)
-    features_fop = set(features) | {Feature.FORCE_OPTIONAL_PARENTHESES}
-    second_opinion = run_transformer(
-        line_copy, transform, mode, features_fop, line_str=line_str
-    )
-    if all(
-        is_line_short_enough(ln, line_length=mode.line_length) for ln in second_opinion
-    ):
-        result = second_opinion
-    return result
-
-
-def get_cache_file(mode: Mode) -> Path:
-    return CACHE_DIR / f"cache.{mode.get_cache_key()}.pickle"
-
-
-def read_cache(mode: Mode) -> Cache:
-    """Read the cache if it exists and is well formed.
-
-    If it is not well formed, the call to write_cache later should resolve the issue.
-    """
-    cache_file = get_cache_file(mode)
-    if not cache_file.exists():
-        return {}
-
-    with cache_file.open("rb") as fobj:
-        try:
-            cache: Cache = pickle.load(fobj)
-        except (pickle.UnpicklingError, ValueError):
-            return {}
-
-    return cache
-
-
-def get_cache_info(path: Path) -> CacheInfo:
-    """Return the information used to check if a file is already formatted or not."""
-    stat = path.stat()
-    return stat.st_mtime, stat.st_size
-
-
-def filter_cached(cache: Cache, sources: Iterable[Path]) -> Tuple[Set[Path], Set[Path]]:
-    """Split an iterable of paths in `sources` into two sets.
-
-    The first contains paths of files that modified on disk or are not in the
-    cache. The other contains paths to non-modified files.
-    """
-    todo, done = set(), set()
-    for src in sources:
-        res_src = src.resolve()
-        if cache.get(str(res_src)) != get_cache_info(res_src):
-            todo.add(src)
-        else:
-            done.add(src)
-    return todo, done
-
-
-def write_cache(cache: Cache, sources: Iterable[Path], mode: Mode) -> None:
-    """Update the cache file."""
-    cache_file = get_cache_file(mode)
-    try:
-        CACHE_DIR.mkdir(parents=True, exist_ok=True)
-        new_cache = {
-            **cache,
-            **{str(src.resolve()): get_cache_info(src) for src in sources},
-        }
-        with tempfile.NamedTemporaryFile(dir=str(cache_file.parent), delete=False) as f:
-            pickle.dump(new_cache, f, protocol=4)
-        os.replace(f.name, cache_file)
-    except OSError:
-        pass
-
-
-def patch_click() -> None:
-    """Make Click not crash.
-
-    On certain misconfigured environments, Python 3 selects the ASCII encoding as the
-    default which restricts paths that it can access during the lifetime of the
-    application.  Click refuses to work in this scenario by raising a RuntimeError.
-
-    In case of Black the likelihood that non-ASCII characters are going to be used in
-    file paths is minimal since it's Python source code.  Moreover, this crash was
-    spurious on Python 3.7 thanks to PEP 538 and PEP 540.
-    """
-    try:
-        from click import core
-        from click import _unicodefun  # type: ignore
-    except ModuleNotFoundError:
-        return
-
-    for module in (core, _unicodefun):
-        if hasattr(module, "_verify_python3_env"):
-            module._verify_python3_env = lambda: None
+    for module in (core, _unicodefun):
+        if hasattr(module, "_verify_python3_env"):
+            module._verify_python3_env = lambda: None
 
 
 def patched_main() -> None:
@@ -7025,66 +1056,5 @@ def patched_main() -> None:
     main()
 
 
-def is_docstring(leaf: Leaf) -> bool:
-    if prev_siblings_are(
-        leaf.parent, [None, token.NEWLINE, token.INDENT, syms.simple_stmt]
-    ):
-        return True
-
-    # Multiline docstring on the same line as the `def`.
-    if prev_siblings_are(leaf.parent, [syms.parameters, token.COLON, syms.simple_stmt]):
-        # `syms.parameters` is only used in funcdefs and async_funcdefs in the Python
-        # grammar. We're safe to return True without further checks.
-        return True
-
-    return False
-
-
-def lines_with_leading_tabs_expanded(s: str) -> List[str]:
-    """
-    Splits string into lines and expands only leading tabs (following the normal
-    Python rules)
-    """
-    lines = []
-    for line in s.splitlines():
-        # Find the index of the first non-whitespace character after a string of
-        # whitespace that includes at least one tab
-        match = re.match(r"\s*\t+\s*(\S)", line)
-        if match:
-            first_non_whitespace_idx = match.start(1)
-
-            lines.append(
-                line[:first_non_whitespace_idx].expandtabs()
-                + line[first_non_whitespace_idx:]
-            )
-        else:
-            lines.append(line)
-    return lines
-
-
-def fix_docstring(docstring: str, prefix: str) -> str:
-    # https://www.python.org/dev/peps/pep-0257/#handling-docstring-indentation
-    if not docstring:
-        return ""
-    lines = lines_with_leading_tabs_expanded(docstring)
-    # Determine minimum indentation (first line doesn't count):
-    indent = sys.maxsize
-    for line in lines[1:]:
-        stripped = line.lstrip()
-        if stripped:
-            indent = min(indent, len(line) - len(stripped))
-    # Remove indentation (first line is special):
-    trimmed = [lines[0].strip()]
-    if indent < sys.maxsize:
-        last_line_idx = len(lines) - 2
-        for i, line in enumerate(lines[1:]):
-            stripped_line = line[indent:].rstrip()
-            if stripped_line or i == last_line_idx:
-                trimmed.append(prefix + stripped_line)
-            else:
-                trimmed.append("")
-    return "\n".join(trimmed)
-
-
 if __name__ == "__main__":
     patched_main()
diff --git a/src/black/brackets.py b/src/black/brackets.py
new file mode 100644
index 00000000000..bb865a0d5b7
--- /dev/null
+++ b/src/black/brackets.py
@@ -0,0 +1,334 @@
+"""Builds on top of nodes.py to track brackets."""
+
+from dataclasses import dataclass, field
+import sys
+from typing import Dict, Iterable, List, Optional, Tuple, Union
+
+if sys.version_info < (3, 8):
+    from typing_extensions import Final
+else:
+    from typing import Final
+
+from blib2to3.pytree import Leaf, Node
+from blib2to3.pgen2 import token
+
+from black.nodes import syms, is_vararg, VARARGS_PARENTS, UNPACKING_PARENTS
+from black.nodes import BRACKET, OPENING_BRACKETS, CLOSING_BRACKETS
+from black.nodes import MATH_OPERATORS, COMPARATORS, LOGIC_OPERATORS
+
+# types
+LN = Union[Leaf, Node]
+Depth = int
+LeafID = int
+NodeType = int
+Priority = int
+
+
+COMPREHENSION_PRIORITY: Final = 20
+COMMA_PRIORITY: Final = 18
+TERNARY_PRIORITY: Final = 16
+LOGIC_PRIORITY: Final = 14
+STRING_PRIORITY: Final = 12
+COMPARATOR_PRIORITY: Final = 10
+MATH_PRIORITIES: Final = {
+    token.VBAR: 9,
+    token.CIRCUMFLEX: 8,
+    token.AMPER: 7,
+    token.LEFTSHIFT: 6,
+    token.RIGHTSHIFT: 6,
+    token.PLUS: 5,
+    token.MINUS: 5,
+    token.STAR: 4,
+    token.SLASH: 4,
+    token.DOUBLESLASH: 4,
+    token.PERCENT: 4,
+    token.AT: 4,
+    token.TILDE: 3,
+    token.DOUBLESTAR: 2,
+}
+DOT_PRIORITY: Final = 1
+
+
+class BracketMatchError(KeyError):
+    """Raised when an opening bracket is unable to be matched to a closing bracket."""
+
+
+@dataclass
+class BracketTracker:
+    """Keeps track of brackets on a line."""
+
+    depth: int = 0
+    bracket_match: Dict[Tuple[Depth, NodeType], Leaf] = field(default_factory=dict)
+    delimiters: Dict[LeafID, Priority] = field(default_factory=dict)
+    previous: Optional[Leaf] = None
+    _for_loop_depths: List[int] = field(default_factory=list)
+    _lambda_argument_depths: List[int] = field(default_factory=list)
+    invisible: List[Leaf] = field(default_factory=list)
+
+    def mark(self, leaf: Leaf) -> None:
+        """Mark `leaf` with bracket-related metadata. Keep track of delimiters.
+
+        All leaves receive an int `bracket_depth` field that stores how deep
+        within brackets a given leaf is. 0 means there are no enclosing brackets
+        that started on this line.
+
+        If a leaf is itself a closing bracket, it receives an `opening_bracket`
+        field that it forms a pair with. This is a one-directional link to
+        avoid reference cycles.
+
+        If a leaf is a delimiter (a token on which Black can split the line if
+        needed) and it's on depth 0, its `id()` is stored in the tracker's
+        `delimiters` field.
+        """
+        if leaf.type == token.COMMENT:
+            return
+
+        self.maybe_decrement_after_for_loop_variable(leaf)
+        self.maybe_decrement_after_lambda_arguments(leaf)
+        if leaf.type in CLOSING_BRACKETS:
+            self.depth -= 1
+            try:
+                opening_bracket = self.bracket_match.pop((self.depth, leaf.type))
+            except KeyError as e:
+                raise BracketMatchError(
+                    "Unable to match a closing bracket to the following opening"
+                    f" bracket: {leaf}"
+                ) from e
+            leaf.opening_bracket = opening_bracket
+            if not leaf.value:
+                self.invisible.append(leaf)
+        leaf.bracket_depth = self.depth
+        if self.depth == 0:
+            delim = is_split_before_delimiter(leaf, self.previous)
+            if delim and self.previous is not None:
+                self.delimiters[id(self.previous)] = delim
+            else:
+                delim = is_split_after_delimiter(leaf, self.previous)
+                if delim:
+                    self.delimiters[id(leaf)] = delim
+        if leaf.type in OPENING_BRACKETS:
+            self.bracket_match[self.depth, BRACKET[leaf.type]] = leaf
+            self.depth += 1
+            if not leaf.value:
+                self.invisible.append(leaf)
+        self.previous = leaf
+        self.maybe_increment_lambda_arguments(leaf)
+        self.maybe_increment_for_loop_variable(leaf)
+
+    def any_open_brackets(self) -> bool:
+        """Return True if there is an yet unmatched open bracket on the line."""
+        return bool(self.bracket_match)
+
+    def max_delimiter_priority(self, exclude: Iterable[LeafID] = ()) -> Priority:
+        """Return the highest priority of a delimiter found on the line.
+
+        Values are consistent with what `is_split_*_delimiter()` return.
+        Raises ValueError on no delimiters.
+        """
+        return max(v for k, v in self.delimiters.items() if k not in exclude)
+
+    def delimiter_count_with_priority(self, priority: Priority = 0) -> int:
+        """Return the number of delimiters with the given `priority`.
+
+        If no `priority` is passed, defaults to max priority on the line.
+        """
+        if not self.delimiters:
+            return 0
+
+        priority = priority or self.max_delimiter_priority()
+        return sum(1 for p in self.delimiters.values() if p == priority)
+
+    def maybe_increment_for_loop_variable(self, leaf: Leaf) -> bool:
+        """In a for loop, or comprehension, the variables are often unpacks.
+
+        To avoid splitting on the comma in this situation, increase the depth of
+        tokens between `for` and `in`.
+        """
+        if leaf.type == token.NAME and leaf.value == "for":
+            self.depth += 1
+            self._for_loop_depths.append(self.depth)
+            return True
+
+        return False
+
+    def maybe_decrement_after_for_loop_variable(self, leaf: Leaf) -> bool:
+        """See `maybe_increment_for_loop_variable` above for explanation."""
+        if (
+            self._for_loop_depths
+            and self._for_loop_depths[-1] == self.depth
+            and leaf.type == token.NAME
+            and leaf.value == "in"
+        ):
+            self.depth -= 1
+            self._for_loop_depths.pop()
+            return True
+
+        return False
+
+    def maybe_increment_lambda_arguments(self, leaf: Leaf) -> bool:
+        """In a lambda expression, there might be more than one argument.
+
+        To avoid splitting on the comma in this situation, increase the depth of
+        tokens between `lambda` and `:`.
+        """
+        if leaf.type == token.NAME and leaf.value == "lambda":
+            self.depth += 1
+            self._lambda_argument_depths.append(self.depth)
+            return True
+
+        return False
+
+    def maybe_decrement_after_lambda_arguments(self, leaf: Leaf) -> bool:
+        """See `maybe_increment_lambda_arguments` above for explanation."""
+        if (
+            self._lambda_argument_depths
+            and self._lambda_argument_depths[-1] == self.depth
+            and leaf.type == token.COLON
+        ):
+            self.depth -= 1
+            self._lambda_argument_depths.pop()
+            return True
+
+        return False
+
+    def get_open_lsqb(self) -> Optional[Leaf]:
+        """Return the most recent opening square bracket (if any)."""
+        return self.bracket_match.get((self.depth - 1, token.RSQB))
+
+
+def is_split_after_delimiter(leaf: Leaf, previous: Optional[Leaf] = None) -> Priority:
+    """Return the priority of the `leaf` delimiter, given a line break after it.
+
+    The delimiter priorities returned here are from those delimiters that would
+    cause a line break after themselves.
+
+    Higher numbers are higher priority.
+    """
+    if leaf.type == token.COMMA:
+        return COMMA_PRIORITY
+
+    return 0
+
+
+def is_split_before_delimiter(leaf: Leaf, previous: Optional[Leaf] = None) -> Priority:
+    """Return the priority of the `leaf` delimiter, given a line break before it.
+
+    The delimiter priorities returned here are from those delimiters that would
+    cause a line break before themselves.
+
+    Higher numbers are higher priority.
+    """
+    if is_vararg(leaf, within=VARARGS_PARENTS | UNPACKING_PARENTS):
+        # * and ** might also be MATH_OPERATORS but in this case they are not.
+        # Don't treat them as a delimiter.
+        return 0
+
+    if (
+        leaf.type == token.DOT
+        and leaf.parent
+        and leaf.parent.type not in {syms.import_from, syms.dotted_name}
+        and (previous is None or previous.type in CLOSING_BRACKETS)
+    ):
+        return DOT_PRIORITY
+
+    if (
+        leaf.type in MATH_OPERATORS
+        and leaf.parent
+        and leaf.parent.type not in {syms.factor, syms.star_expr}
+    ):
+        return MATH_PRIORITIES[leaf.type]
+
+    if leaf.type in COMPARATORS:
+        return COMPARATOR_PRIORITY
+
+    if (
+        leaf.type == token.STRING
+        and previous is not None
+        and previous.type == token.STRING
+    ):
+        return STRING_PRIORITY
+
+    if leaf.type not in {token.NAME, token.ASYNC}:
+        return 0
+
+    if (
+        leaf.value == "for"
+        and leaf.parent
+        and leaf.parent.type in {syms.comp_for, syms.old_comp_for}
+        or leaf.type == token.ASYNC
+    ):
+        if (
+            not isinstance(leaf.prev_sibling, Leaf)
+            or leaf.prev_sibling.value != "async"
+        ):
+            return COMPREHENSION_PRIORITY
+
+    if (
+        leaf.value == "if"
+        and leaf.parent
+        and leaf.parent.type in {syms.comp_if, syms.old_comp_if}
+    ):
+        return COMPREHENSION_PRIORITY
+
+    if leaf.value in {"if", "else"} and leaf.parent and leaf.parent.type == syms.test:
+        return TERNARY_PRIORITY
+
+    if leaf.value == "is":
+        return COMPARATOR_PRIORITY
+
+    if (
+        leaf.value == "in"
+        and leaf.parent
+        and leaf.parent.type in {syms.comp_op, syms.comparison}
+        and not (
+            previous is not None
+            and previous.type == token.NAME
+            and previous.value == "not"
+        )
+    ):
+        return COMPARATOR_PRIORITY
+
+    if (
+        leaf.value == "not"
+        and leaf.parent
+        and leaf.parent.type == syms.comp_op
+        and not (
+            previous is not None
+            and previous.type == token.NAME
+            and previous.value == "is"
+        )
+    ):
+        return COMPARATOR_PRIORITY
+
+    if leaf.value in LOGIC_OPERATORS and leaf.parent:
+        return LOGIC_PRIORITY
+
+    return 0
+
+
+def max_delimiter_priority_in_atom(node: LN) -> Priority:
+    """Return maximum delimiter priority inside `node`.
+
+    This is specific to atoms with contents contained in a pair of parentheses.
+    If `node` isn't an atom or there are no enclosing parentheses, returns 0.
+    """
+    if node.type != syms.atom:
+        return 0
+
+    first = node.children[0]
+    last = node.children[-1]
+    if not (first.type == token.LPAR and last.type == token.RPAR):
+        return 0
+
+    bt = BracketTracker()
+    for c in node.children[1:-1]:
+        if isinstance(c, Leaf):
+            bt.mark(c)
+        else:
+            for leaf in c.leaves():
+                bt.mark(leaf)
+    try:
+        return bt.max_delimiter_priority()
+
+    except ValueError:
+        return 0
diff --git a/src/black/cache.py b/src/black/cache.py
new file mode 100644
index 00000000000..017a2a91362
--- /dev/null
+++ b/src/black/cache.py
@@ -0,0 +1,83 @@
+"""Caching of formatted files with feature-based invalidation."""
+
+import os
+import pickle
+from pathlib import Path
+import tempfile
+from typing import Dict, Iterable, Set, Tuple
+
+from appdirs import user_cache_dir
+
+from black.mode import Mode
+
+from _black_version import version as __version__
+
+
+# types
+Timestamp = float
+FileSize = int
+CacheInfo = Tuple[Timestamp, FileSize]
+Cache = Dict[str, CacheInfo]
+
+
+CACHE_DIR = Path(user_cache_dir("black", version=__version__))
+
+
+def read_cache(mode: Mode) -> Cache:
+    """Read the cache if it exists and is well formed.
+
+    If it is not well formed, the call to write_cache later should resolve the issue.
+    """
+    cache_file = get_cache_file(mode)
+    if not cache_file.exists():
+        return {}
+
+    with cache_file.open("rb") as fobj:
+        try:
+            cache: Cache = pickle.load(fobj)
+        except (pickle.UnpicklingError, ValueError):
+            return {}
+
+    return cache
+
+
+def get_cache_file(mode: Mode) -> Path:
+    return CACHE_DIR / f"cache.{mode.get_cache_key()}.pickle"
+
+
+def get_cache_info(path: Path) -> CacheInfo:
+    """Return the information used to check if a file is already formatted or not."""
+    stat = path.stat()
+    return stat.st_mtime, stat.st_size
+
+
+def filter_cached(cache: Cache, sources: Iterable[Path]) -> Tuple[Set[Path], Set[Path]]:
+    """Split an iterable of paths in `sources` into two sets.
+
+    The first contains paths of files that modified on disk or are not in the
+    cache. The other contains paths to non-modified files.
+    """
+    todo, done = set(), set()
+    for src in sources:
+        res_src = src.resolve()
+        if cache.get(str(res_src)) != get_cache_info(res_src):
+            todo.add(src)
+        else:
+            done.add(src)
+    return todo, done
+
+
+def write_cache(cache: Cache, sources: Iterable[Path], mode: Mode) -> None:
+    """Update the cache file."""
+    cache_file = get_cache_file(mode)
+    try:
+        CACHE_DIR.mkdir(parents=True, exist_ok=True)
+        new_cache = {
+            **cache,
+            **{str(src.resolve()): get_cache_info(src) for src in sources},
+        }
+        with tempfile.NamedTemporaryFile(dir=str(cache_file.parent), delete=False) as f:
+            pickle.dump(new_cache, f, protocol=4)
+        os.replace(f.name, cache_file)
+    except OSError:
+        pass
diff --git a/src/black/comments.py b/src/black/comments.py
new file mode 100644
index 00000000000..415e391b2a7
--- /dev/null
+++ b/src/black/comments.py
@@ -0,0 +1,269 @@
+from dataclasses import dataclass
+from functools import lru_cache
+import regex as re
+from typing import Iterator, List, Optional, Union
+
+from blib2to3.pytree import Node, Leaf
+from blib2to3.pgen2 import token
+
+from black.nodes import first_leaf_column, preceding_leaf, container_of
+from black.nodes import STANDALONE_COMMENT, WHITESPACE
+
+# types
+LN = Union[Leaf, Node]
+
+
+FMT_OFF = {"# fmt: off", "# fmt:off", "# yapf: disable"}
+FMT_SKIP = {"# fmt: skip", "# fmt:skip"}
+FMT_PASS = {*FMT_OFF, *FMT_SKIP}
+FMT_ON = {"# fmt: on", "# fmt:on", "# yapf: enable"}
+
+
+@dataclass
+class ProtoComment:
+    """Describes a piece of syntax that is a comment.
+
+    It's not a :class:`blib2to3.pytree.Leaf` so that:
+
+    * it can be cached (`Leaf` objects should not be reused more than once as
+      they store their lineno, column, prefix, and parent information);
+    * `newlines` and `consumed` fields are kept separate from the `value`. This
+      simplifies handling of special marker comments like ``# fmt: off/on``.
+    """
+
+    type: int  # token.COMMENT or STANDALONE_COMMENT
+    value: str  # content of the comment
+    newlines: int  # how many newlines before the comment
+    consumed: int  # how many characters of the original leaf's prefix did we consume
+
+
+def generate_comments(leaf: LN) -> Iterator[Leaf]:
+    """Clean the prefix of the `leaf` and generate comments from it, if any.
+
+    Comments in lib2to3 are shoved into the whitespace prefix.  This happens
+    in `pgen2/driver.py:Driver.parse_tokens()`.  This was a brilliant implementation
+    move because it does away with modifying the grammar to include all the
+    possible places in which comments can be placed.
+
+    The sad consequence for us though is that comments don't "belong" anywhere.
+    This is why this function generates simple parentless Leaf objects for
+    comments.  We simply don't know what the correct parent should be.
+
+    No matter though, we can live without this.  We really only need to
+    differentiate between inline and standalone comments.  The latter don't
+    share the line with any code.
+
+    Inline comments are emitted as regular token.COMMENT leaves.  Standalone
+    are emitted with a fake STANDALONE_COMMENT token identifier.
+    """
+    for pc in list_comments(leaf.prefix, is_endmarker=leaf.type == token.ENDMARKER):
+        yield Leaf(pc.type, pc.value, prefix="\n" * pc.newlines)
+
+
+@lru_cache(maxsize=4096)
+def list_comments(prefix: str, *, is_endmarker: bool) -> List[ProtoComment]:
+    """Return a list of :class:`ProtoComment` objects parsed from the given `prefix`."""
+    result: List[ProtoComment] = []
+    if not prefix or "#" not in prefix:
+        return result
+
+    consumed = 0
+    nlines = 0
+    ignored_lines = 0
+    for index, line in enumerate(re.split("\r?\n", prefix)):
+        consumed += len(line) + 1  # adding the length of the split '\n'
+        line = line.lstrip()
+        if not line:
+            nlines += 1
+        if not line.startswith("#"):
+            # Escaped newlines outside of a comment are not really newlines at
+            # all. We treat a single-line comment following an escaped newline
+            # as a simple trailing comment.
+            if line.endswith("\\"):
+                ignored_lines += 1
+            continue
+
+        if index == ignored_lines and not is_endmarker:
+            comment_type = token.COMMENT  # simple trailing comment
+        else:
+            comment_type = STANDALONE_COMMENT
+        comment = make_comment(line)
+        result.append(
+            ProtoComment(
+                type=comment_type, value=comment, newlines=nlines, consumed=consumed
+            )
+        )
+        nlines = 0
+    return result
+
+
+def make_comment(content: str) -> str:
+    """Return a consistently formatted comment from the given `content` string.
+
+    All comments (except for "##", "#!", "#:", '#'", "#%%") should have a single
+    space between the hash sign and the content.
+
+    If `content` didn't start with a hash sign, one is provided.
+    """
+    content = content.rstrip()
+    if not content:
+        return "#"
+
+    if content[0] == "#":
+        content = content[1:]
+    NON_BREAKING_SPACE = " "
+    if (
+        content
+        and content[0] == NON_BREAKING_SPACE
+        and not content.lstrip().startswith("type:")
+    ):
+        content = " " + content[1:]  # Replace NBSP by a simple space
+    if content and content[0] not in " !:#'%":
+        content = " " + content
+    return "#" + content
+
+
+def normalize_fmt_off(node: Node) -> None:
+    """Convert content between `# fmt: off`/`# fmt: on` into standalone comments."""
+    try_again = True
+    while try_again:
+        try_again = convert_one_fmt_off_pair(node)
+
+
+def convert_one_fmt_off_pair(node: Node) -> bool:
+    """Convert content of a single `# fmt: off`/`# fmt: on` into a standalone comment.
+
+    Returns True if a pair was converted.
+    """
+    for leaf in node.leaves():
+        previous_consumed = 0
+        for comment in list_comments(leaf.prefix, is_endmarker=False):
+            if comment.value not in FMT_PASS:
+                previous_consumed = comment.consumed
+                continue
+            # We only want standalone comments. If there's no previous leaf or
+            # the previous leaf is indentation, it's a standalone comment in
+            # disguise.
+            if comment.value in FMT_PASS and comment.type != STANDALONE_COMMENT:
+                prev = preceding_leaf(leaf)
+                if prev:
+                    if comment.value in FMT_OFF and prev.type not in WHITESPACE:
+                        continue
+                    if comment.value in FMT_SKIP and prev.type in WHITESPACE:
+                        continue
+
+            ignored_nodes = list(generate_ignored_nodes(leaf, comment))
+            if not ignored_nodes:
+                continue
+
+            first = ignored_nodes[0]  # Can be a container node with the `leaf`.
+            parent = first.parent
+            prefix = first.prefix
+            first.prefix = prefix[comment.consumed :]
+            hidden_value = "".join(str(n) for n in ignored_nodes)
+            if comment.value in FMT_OFF:
+                hidden_value = comment.value + "\n" + hidden_value
+            if comment.value in FMT_SKIP:
+                hidden_value += "  " + comment.value
+            if hidden_value.endswith("\n"):
+                # That happens when one of the `ignored_nodes` ended with a NEWLINE
+                # leaf (possibly followed by a DEDENT).
+                hidden_value = hidden_value[:-1]
+            first_idx: Optional[int] = None
+            for ignored in ignored_nodes:
+                index = ignored.remove()
+                if first_idx is None:
+                    first_idx = index
+            assert parent is not None, "INTERNAL ERROR: fmt: on/off handling (1)"
+            assert first_idx is not None, "INTERNAL ERROR: fmt: on/off handling (2)"
+            parent.insert_child(
+                first_idx,
+                Leaf(
+                    STANDALONE_COMMENT,
+                    hidden_value,
+                    prefix=prefix[:previous_consumed] + "\n" * comment.newlines,
+                ),
+            )
+            return True
+
+    return False
+
+
+def generate_ignored_nodes(leaf: Leaf, comment: ProtoComment) -> Iterator[LN]:
+    """Starting from the container of `leaf`, generate all leaves until `# fmt: on`.
+
+    If comment is skip, returns leaf only.
+    Stops at the end of the block.
+    """
+    container: Optional[LN] = container_of(leaf)
+    if comment.value in FMT_SKIP:
+        prev_sibling = leaf.prev_sibling
+        if comment.value in leaf.prefix and prev_sibling is not None:
+            leaf.prefix = leaf.prefix.replace(comment.value, "")
+            siblings = [prev_sibling]
+            while (
+                "\n" not in prev_sibling.prefix
+                and prev_sibling.prev_sibling is not None
+            ):
+                prev_sibling = prev_sibling.prev_sibling
+                siblings.insert(0, prev_sibling)
+            for sibling in siblings:
+                yield sibling
+        elif leaf.parent is not None:
+            yield leaf.parent
+        return
+    while container is not None and container.type != token.ENDMARKER:
+        if is_fmt_on(container):
+            return
+
+        # fix for fmt: on in children
+        if contains_fmt_on_at_column(container, leaf.column):
+            for child in container.children:
+                if contains_fmt_on_at_column(child, leaf.column):
+                    return
+                yield child
+        else:
+            yield container
+            container = container.next_sibling
+
+
+def is_fmt_on(container: LN) -> bool:
+    """Determine whether formatting is switched on within a container.
+    Determined by whether the last `# fmt:` comment is `on` or `off`.
+    """
+    fmt_on = False
+    for comment in list_comments(container.prefix, is_endmarker=False):
+        if comment.value in FMT_ON:
+            fmt_on = True
+        elif comment.value in FMT_OFF:
+            fmt_on = False
+    return fmt_on
+
+
+def contains_fmt_on_at_column(container: LN, column: int) -> bool:
+    """Determine if children at a given column have formatting switched on."""
+    for child in container.children:
+        if (
+            isinstance(child, Node)
+            and first_leaf_column(child) == column
+            or isinstance(child, Leaf)
+            and child.column == column
+        ):
+            if is_fmt_on(child):
+                return True
+
+    return False
+
+
+def contains_pragma_comment(comment_list: List[Leaf]) -> bool:
+    """
+    Returns:
+        True iff one of the comments in @comment_list is a pragma used by one
+        of the more common static analysis tools for python (e.g. mypy, flake8,
+        pylint).
+    """
+    for comment in comment_list:
+        if comment.value.startswith(("# type:", "# noqa", "# pylint:")):
+            return True
+
+    return False
diff --git a/src/black/concurrency.py b/src/black/concurrency.py
new file mode 100644
index 00000000000..119a9a71faf
--- /dev/null
+++ b/src/black/concurrency.py
@@ -0,0 +1,39 @@
+import asyncio
+import logging
+import sys
+from typing import Any, Iterable
+
+from black.output import err
+
+
+def cancel(tasks: Iterable["asyncio.Task[Any]"]) -> None:
+    """asyncio signal handler that cancels all `tasks` and reports to stderr."""
+    err("Aborted!")
+    for task in tasks:
+        task.cancel()
+
+
+def shutdown(loop: asyncio.AbstractEventLoop) -> None:
+    """Cancel all pending tasks on `loop`, wait for them, and close the loop."""
+    try:
+        if sys.version_info[:2] >= (3, 7):
+            all_tasks = asyncio.all_tasks
+        else:
+            all_tasks = asyncio.Task.all_tasks
+        # This part is borrowed from asyncio/runners.py in Python 3.7b2.
+        to_cancel = [task for task in all_tasks(loop) if not task.done()]
+        if not to_cancel:
+            return
+
+        for task in to_cancel:
+            task.cancel()
+        loop.run_until_complete(
+            asyncio.gather(*to_cancel, loop=loop, return_exceptions=True)
+        )
+    finally:
+        # `concurrent.futures.Future` objects cannot be cancelled once they
+        # are already running. There might be some when the `shutdown()` happened.
+        # Silence their logger's spew about the event loop being closed.
+        cf_logger = logging.getLogger("concurrent.futures")
+        cf_logger.setLevel(logging.CRITICAL)
+        loop.close()
diff --git a/src/black/const.py b/src/black/const.py
new file mode 100644
index 00000000000..821258588ab
--- /dev/null
+++ b/src/black/const.py
@@ -0,0 +1,4 @@
+DEFAULT_LINE_LENGTH = 88
+DEFAULT_EXCLUDES = r"/(\.direnv|\.eggs|\.git|\.hg|\.mypy_cache|\.nox|\.tox|\.venv|venv|\.svn|_build|buck-out|build|dist)/"  # noqa: B950
+DEFAULT_INCLUDES = r"\.pyi?$"
+STDIN_PLACEHOLDER = "__BLACK_STDIN_FILENAME__"
diff --git a/src/black/debug.py b/src/black/debug.py
new file mode 100644
index 00000000000..5143076ab35
--- /dev/null
+++ b/src/black/debug.py
@@ -0,0 +1,48 @@
+from dataclasses import dataclass
+from typing import Iterator, TypeVar, Union
+
+from blib2to3.pytree import Node, Leaf, type_repr
+from blib2to3.pgen2 import token
+
+from black.nodes import Visitor
+from black.output import out
+from black.parsing import lib2to3_parse
+
+LN = Union[Leaf, Node]
+T = TypeVar("T")
+
+
+@dataclass
+class DebugVisitor(Visitor[T]):
+    tree_depth: int = 0
+
+    def visit_default(self, node: LN) -> Iterator[T]:
+        indent = " " * (2 * self.tree_depth)
+        if isinstance(node, Node):
+            _type = type_repr(node.type)
+            out(f"{indent}{_type}", fg="yellow")
+            self.tree_depth += 1
+            for child in node.children:
+                yield from self.visit(child)
+
+            self.tree_depth -= 1
+            out(f"{indent}/{_type}", fg="yellow", bold=False)
+        else:
+            _type = token.tok_name.get(node.type, str(node.type))
+            out(f"{indent}{_type}", fg="blue", nl=False)
+            if node.prefix:
+                # We don't have to handle prefixes for `Node` objects since
+                # that delegates to the first child anyway.
+                out(f" {node.prefix!r}", fg="green", bold=False, nl=False)
+            out(f" {node.value!r}", fg="blue", bold=False)
+
+    @classmethod
+    def show(cls, code: Union[str, Leaf, Node]) -> None:
+        """Pretty-print the lib2to3 AST of a given string of `code`.
+
+        Convenience method for debugging.
+        """
+        v: DebugVisitor[None] = DebugVisitor()
+        if isinstance(code, str):
+            code = lib2to3_parse(code)
+        list(v.visit(code))
diff --git a/src/black/files.py b/src/black/files.py
new file mode 100644
index 00000000000..1be560643a1
--- /dev/null
+++ b/src/black/files.py
@@ -0,0 +1,241 @@
+from functools import lru_cache
+import io
+import os
+from pathlib import Path
+import sys
+from typing import (
+    Any,
+    Dict,
+    Iterable,
+    Iterator,
+    List,
+    Optional,
+    Pattern,
+    Sequence,
+    Tuple,
+    Union,
+    TYPE_CHECKING,
+)
+
+from pathspec import PathSpec
+import toml
+
+from black.output import err
+from black.report import Report
+
+if TYPE_CHECKING:
+    import colorama  # noqa: F401
+
+
+@lru_cache()
+def find_project_root(srcs: Sequence[str]) -> Path:
+    """Return a directory containing .git, .hg, or pyproject.toml.
+
+    That directory will be a common parent of all files and directories
+    passed in `srcs`.
+
+    If no directory in the tree contains a marker that would specify it's the
+    project root, the root of the file system is returned.
+    """
+    if not srcs:
+        return Path("/").resolve()
+
+    path_srcs = [Path(Path.cwd(), src).resolve() for src in srcs]
+
+    # A list of lists of parents for each 'src'. 'src' is included as a
+    # "parent" of itself if it is a directory
+    src_parents = [
+        list(path.parents) + ([path] if path.is_dir() else []) for path in path_srcs
+    ]
+
+    common_base = max(
+        set.intersection(*(set(parents) for parents in src_parents)),
+        key=lambda path: path.parts,
+    )
+
+    for directory in (common_base, *common_base.parents):
+        if (directory / ".git").exists():
+            return directory
+
+        if (directory / ".hg").is_dir():
+            return directory
+
+        if (directory / "pyproject.toml").is_file():
+            return directory
+
+    return directory
+
+
+def find_pyproject_toml(path_search_start: Tuple[str, ...]) -> Optional[str]:
+    """Find the absolute filepath to a pyproject.toml if it exists"""
+    path_project_root = find_project_root(path_search_start)
+    path_pyproject_toml = path_project_root / "pyproject.toml"
+    if path_pyproject_toml.is_file():
+        return str(path_pyproject_toml)
+
+    try:
+        path_user_pyproject_toml = find_user_pyproject_toml()
+        return (
+            str(path_user_pyproject_toml)
+            if path_user_pyproject_toml.is_file()
+            else None
+        )
+    except PermissionError as e:
+        # We do not have access to the user-level config directory, so ignore it.
+        err(f"Ignoring user configuration directory due to {e!r}")
+        return None
+
+
+def parse_pyproject_toml(path_config: str) -> Dict[str, Any]:
+    """Parse a pyproject toml file, pulling out relevant parts for Black
+
+    If parsing fails, will raise a toml.TomlDecodeError
+    """
+    pyproject_toml = toml.load(path_config)
+    config = pyproject_toml.get("tool", {}).get("black", {})
+    return {k.replace("--", "").replace("-", "_"): v for k, v in config.items()}
+
+
+@lru_cache()
+def find_user_pyproject_toml() -> Path:
+    r"""Return the path to the top-level user configuration for black.
+
+    This looks for ~\.black on Windows and ~/.config/black on Linux and other
+    Unix systems.
+    """
+    if sys.platform == "win32":
+        # Windows
+        user_config_path = Path.home() / ".black"
+    else:
+        config_root = os.environ.get("XDG_CONFIG_HOME", "~/.config")
+        user_config_path = Path(config_root).expanduser() / "black"
+    return user_config_path.resolve()
+
+
+@lru_cache()
+def get_gitignore(root: Path) -> PathSpec:
+    """Return a PathSpec matching gitignore content if present."""
+    gitignore = root / ".gitignore"
+    lines: List[str] = []
+    if gitignore.is_file():
+        with gitignore.open() as gf:
+            lines = gf.readlines()
+    return PathSpec.from_lines("gitwildmatch", lines)
+
+
+def normalize_path_maybe_ignore(
+    path: Path, root: Path, report: Report
+) -> Optional[str]:
+    """Normalize `path`. May return `None` if `path` was ignored.
+
+    `report` is where "path ignored" output goes.
+    """
+    try:
+        abspath = path if path.is_absolute() else Path.cwd() / path
+        normalized_path = abspath.resolve().relative_to(root).as_posix()
+    except OSError as e:
+        report.path_ignored(path, f"cannot be read because {e}")
+        return None
+
+    except ValueError:
+        if path.is_symlink():
+            report.path_ignored(path, f"is a symbolic link that points outside {root}")
+            return None
+
+        raise
+
+    return normalized_path
+
+
+def path_is_excluded(
+    normalized_path: str,
+    pattern: Optional[Pattern[str]],
+) -> bool:
+    match = pattern.search(normalized_path) if pattern else None
+    return bool(match and match.group(0))
+
+
+def gen_python_files(
+    paths: Iterable[Path],
+    root: Path,
+    include: Pattern[str],
+    exclude: Pattern[str],
+    extend_exclude: Optional[Pattern[str]],
+    force_exclude: Optional[Pattern[str]],
+    report: Report,
+    gitignore: Optional[PathSpec],
+) -> Iterator[Path]:
+    """Generate all files under `path` whose paths are not excluded by the
+    `exclude_regex`, `extend_exclude`, or `force_exclude` regexes,
+    but are included by the `include` regex.
+
+    Symbolic links pointing outside of the `root` directory are ignored.
+
+    `report` is where output about exclusions goes.
+    """
+    assert root.is_absolute(), f"INTERNAL ERROR: `root` must be absolute but is {root}"
+    for child in paths:
+        normalized_path = normalize_path_maybe_ignore(child, root, report)
+        if normalized_path is None:
+            continue
+
+        # First ignore files matching .gitignore, if passed
+        if gitignore is not None and gitignore.match_file(normalized_path):
+            report.path_ignored(child, "matches the .gitignore file content")
+            continue
+
+        # Then ignore with `--exclude` `--extend-exclude` and `--force-exclude` options.
+        normalized_path = "/" + normalized_path
+        if child.is_dir():
+            normalized_path += "/"
+
+        if path_is_excluded(normalized_path, exclude):
+            report.path_ignored(child, "matches the --exclude regular expression")
+            continue
+
+        if path_is_excluded(normalized_path, extend_exclude):
+            report.path_ignored(
+                child, "matches the --extend-exclude regular expression"
+            )
+            continue
+
+        if path_is_excluded(normalized_path, force_exclude):
+            report.path_ignored(child, "matches the --force-exclude regular expression")
+            continue
+
+        if child.is_dir():
+            yield from gen_python_files(
+                child.iterdir(),
+                root,
+                include,
+                exclude,
+                extend_exclude,
+                force_exclude,
+                report,
+                gitignore,
+            )
+
+        elif child.is_file():
+            include_match = include.search(normalized_path) if include else True
+            if include_match:
+                yield child
+
+
+def wrap_stream_for_windows(
+    f: io.TextIOWrapper,
+) -> Union[io.TextIOWrapper, "colorama.AnsiToWin32"]:
+    """
+    Wrap stream with colorama's wrap_stream so colors are shown on Windows.
+
+    If `colorama` is unavailable, the original stream is returned unmodified.
+    Otherwise, the `wrap_stream()` function determines whether the stream needs
+    to be wrapped for a Windows environment and will accordingly either return
+    an `AnsiToWin32` wrapper or the original stream.
+    """
+    try:
+        from colorama.initialise import wrap_stream
+    except ImportError:
+        return f
+    else:
+        # Set `strip=False` to avoid needing to modify test_express_diff_with_color.
+        return wrap_stream(f, convert=None, strip=False, autoreset=False, wrap=True)
diff --git a/src/black/linegen.py b/src/black/linegen.py
new file mode 100644
index 00000000000..2e16b6fde44
--- /dev/null
+++ b/src/black/linegen.py
@@ -0,0 +1,984 @@
+"""
+Generating lines of code.
+"""
+from functools import partial, wraps
+import sys
+from typing import Collection, Iterator, List, Optional, Set, Union
+
+from dataclasses import dataclass, field
+
+from black.nodes import WHITESPACE, STATEMENT, STANDALONE_COMMENT
+from black.nodes import ASSIGNMENTS, OPENING_BRACKETS, CLOSING_BRACKETS
+from black.nodes import Visitor, syms, first_child_is_arith, ensure_visible
+from black.nodes import is_docstring, is_empty_tuple, is_one_tuple, is_one_tuple_between
+from black.nodes import is_walrus_assignment, is_yield, is_vararg, is_multiline_string
+from black.nodes import is_stub_suite, is_stub_body, is_atom_with_invisible_parens
+from black.nodes import wrap_in_parentheses
+from black.brackets import max_delimiter_priority_in_atom
+from black.brackets import DOT_PRIORITY, COMMA_PRIORITY
+from black.lines import Line, line_to_string, is_line_short_enough
+from black.lines import can_omit_invisible_parens, can_be_split, append_leaves
+from black.comments import generate_comments, list_comments, FMT_OFF
+from black.numerics import normalize_numeric_literal
+from black.strings import get_string_prefix, fix_docstring
+from black.strings import normalize_string_prefix, normalize_string_quotes
+from black.trans import Transformer, CannotTransform, StringMerger
+from black.trans import StringSplitter, StringParenWrapper, StringParenStripper
+from black.mode import Mode
+from black.mode import Feature
+
+from blib2to3.pytree import Node, Leaf
+from blib2to3.pgen2 import token
+
+
+# types
+LeafID = int
+LN = Union[Leaf, Node]
+
+
+class CannotSplit(CannotTransform):
+    """A readable split that fits the allotted line length is impossible."""
+
+
+@dataclass
+class LineGenerator(Visitor[Line]):
+    """Generates reformatted Line objects.  Empty lines are not emitted.
+
+    Note: destroys the tree it's visiting by mutating prefixes of its leaves
+    in ways that will no longer stringify to valid Python code on the tree.
+    """
+
+    mode: Mode
+    remove_u_prefix: bool = False
+    current_line: Line = field(init=False)
+
+    def line(self, indent: int = 0) -> Iterator[Line]:
+        """Generate a line.
+
+        If the line is empty, only emit if it makes sense.
+        If the line is too long, split it first and then generate.
+
+        If any lines were generated, set up a new current_line.
+        """
+        if not self.current_line:
+            self.current_line.depth += indent
+            return  # Line is empty, don't emit. Creating a new one unnecessary.
+
+        complete_line = self.current_line
+        self.current_line = Line(mode=self.mode, depth=complete_line.depth + indent)
+        yield complete_line
+
+    def visit_default(self, node: LN) -> Iterator[Line]:
+        """Default `visit_*()` implementation. Recurses to children of `node`."""
+        if isinstance(node, Leaf):
+            any_open_brackets = self.current_line.bracket_tracker.any_open_brackets()
+            for comment in generate_comments(node):
+                if any_open_brackets:
+                    # any comment within brackets is subject to splitting
+                    self.current_line.append(comment)
+                elif comment.type == token.COMMENT:
+                    # regular trailing comment
+                    self.current_line.append(comment)
+                    yield from self.line()
+
+                else:
+                    # regular standalone comment
+                    yield from self.line()
+
+                    self.current_line.append(comment)
+                    yield from self.line()
+
+            normalize_prefix(node, inside_brackets=any_open_brackets)
+            if self.mode.string_normalization and node.type == token.STRING:
+                node.value = normalize_string_prefix(
+                    node.value, remove_u_prefix=self.remove_u_prefix
+                )
+                node.value = normalize_string_quotes(node.value)
+            if node.type == token.NUMBER:
+                normalize_numeric_literal(node)
+            if node.type not in WHITESPACE:
+                self.current_line.append(node)
+        yield from super().visit_default(node)
+
+    def visit_INDENT(self, node: Leaf) -> Iterator[Line]:
+        """Increase indentation level, maybe yield a line."""
+        # In blib2to3 INDENT never holds comments.
+        yield from self.line(+1)
+        yield from self.visit_default(node)
+
+    def visit_DEDENT(self, node: Leaf) -> Iterator[Line]:
+        """Decrease indentation level, maybe yield a line."""
+        # The current line might still wait for trailing comments.  At DEDENT time
+        # there won't be any (they would be prefixes on the preceding NEWLINE).
+        # Emit the line then.
+        yield from self.line()
+
+        # While DEDENT has no value, its prefix may contain standalone comments
+        # that belong to the current indentation level.  Get 'em.
+        yield from self.visit_default(node)
+
+        # Finally, emit the dedent.
+        yield from self.line(-1)
+
+    def visit_stmt(
+        self, node: Node, keywords: Set[str], parens: Set[str]
+    ) -> Iterator[Line]:
+        """Visit a statement.
+
+        This implementation is shared for `if`, `while`, `for`, `try`, `except`,
+        `def`, `with`, `class`, `assert` and assignments.
+
+        The relevant Python language `keywords` for a given statement will be
+        NAME leaves within it. This methods puts those on a separate line.
+
+        `parens` holds a set of string leaf values immediately after which
+        invisible parens should be put.
+        """
+        normalize_invisible_parens(node, parens_after=parens)
+        for child in node.children:
+            if child.type == token.NAME and child.value in keywords:  # type: ignore
+                yield from self.line()
+
+            yield from self.visit(child)
+
+    def visit_suite(self, node: Node) -> Iterator[Line]:
+        """Visit a suite."""
+        if self.mode.is_pyi and is_stub_suite(node):
+            yield from self.visit(node.children[2])
+        else:
+            yield from self.visit_default(node)
+
+    def visit_simple_stmt(self, node: Node) -> Iterator[Line]:
+        """Visit a statement without nested statements."""
+        if first_child_is_arith(node):
+            wrap_in_parentheses(node, node.children[0], visible=False)
+        is_suite_like = node.parent and node.parent.type in STATEMENT
+        if is_suite_like:
+            if self.mode.is_pyi and is_stub_body(node):
+                yield from self.visit_default(node)
+            else:
+                yield from self.line(+1)
+                yield from self.visit_default(node)
+                yield from self.line(-1)
+
+        else:
+            if (
+                not self.mode.is_pyi
+                or not node.parent
+                or not is_stub_suite(node.parent)
+            ):
+                yield from self.line()
+            yield from self.visit_default(node)
+
+    def visit_async_stmt(self, node: Node) -> Iterator[Line]:
+        """Visit `async def`, `async for`, `async with`."""
+        yield from self.line()
+
+        children = iter(node.children)
+        for child in children:
+            yield from self.visit(child)
+
+            if child.type == token.ASYNC:
+                break
+
+        internal_stmt = next(children)
+        for child in internal_stmt.children:
+            yield from self.visit(child)
+
+    def visit_decorators(self, node: Node) -> Iterator[Line]:
+        """Visit decorators."""
+        for child in node.children:
+            yield from self.line()
+            yield from self.visit(child)
+
+    def visit_SEMI(self, leaf: Leaf) -> Iterator[Line]:
+        """Remove a semicolon and put the other statement on a separate line."""
+        yield from self.line()
+
+    def visit_ENDMARKER(self, leaf: Leaf) -> Iterator[Line]:
+        """End of file. Process outstanding comments and end with a newline."""
+        yield from self.visit_default(leaf)
+        yield from self.line()
+
+    def visit_STANDALONE_COMMENT(self, leaf: Leaf) -> Iterator[Line]:
+        if not self.current_line.bracket_tracker.any_open_brackets():
+            yield from self.line()
+        yield from self.visit_default(leaf)
+
+    def visit_factor(self, node: Node) -> Iterator[Line]:
+        """Force parentheses between a unary op and a binary power:
+
+        -2 ** 8 -> -(2 ** 8)
+        """
+        _operator, operand = node.children
+        if (
+            operand.type == syms.power
+            and len(operand.children) == 3
+            and operand.children[1].type == token.DOUBLESTAR
+        ):
+            lpar = Leaf(token.LPAR, "(")
+            rpar = Leaf(token.RPAR, ")")
+            index = operand.remove() or 0
+            node.insert_child(index, Node(syms.atom, [lpar, operand, rpar]))
+        yield from self.visit_default(node)
+
+    def visit_STRING(self, leaf: Leaf) -> Iterator[Line]:
+        if is_docstring(leaf) and "\\\n" not in leaf.value:
+            # We're ignoring docstrings with backslash newline escapes because changing
+            # indentation of those changes the AST representation of the code.
+            prefix = get_string_prefix(leaf.value)
+            docstring = leaf.value[len(prefix) :]  # Remove the prefix
+            quote_char = docstring[0]
+            # A natural way to remove the outer quotes is to do:
+            #   docstring = docstring.strip(quote_char)
+            # but that breaks on """""x""" (which is '""x').
+            # So we actually need to remove the first character and the next two
+            # characters but only if they are the same as the first.
+            quote_len = 1 if docstring[1] != quote_char else 3
+            docstring = docstring[quote_len:-quote_len]
+
+            if is_multiline_string(leaf):
+                indent = " " * 4 * self.current_line.depth
+                docstring = fix_docstring(docstring, indent)
+            else:
+                docstring = docstring.strip()
+
+            if docstring:
+                # Add some padding if the docstring starts / ends with a quote mark.
+                if docstring[0] == quote_char:
+                    docstring = " " + docstring
+                if docstring[-1] == quote_char:
+                    docstring += " "
+                if docstring[-1] == "\\":
+                    backslash_count = len(docstring) - len(docstring.rstrip("\\"))
+                    if backslash_count % 2:
+                        # Odd number of tailing backslashes, add some padding to
+                        # avoid escaping the closing string quote.
+                        docstring += " "
+            else:
+                # Add some padding if the docstring is empty.
+                docstring = " "
+
+            # We could enforce triple quotes at this point.
+            quote = quote_char * quote_len
+            leaf.value = prefix + quote + docstring + quote
+
+        yield from self.visit_default(leaf)
+
+    def __post_init__(self) -> None:
+        """You are in a twisty little maze of passages."""
+        self.current_line = Line(mode=self.mode)
+
+        v = self.visit_stmt
+        Ø: Set[str] = set()
+        self.visit_assert_stmt = partial(v, keywords={"assert"}, parens={"assert", ","})
+        self.visit_if_stmt = partial(
+            v, keywords={"if", "else", "elif"}, parens={"if", "elif"}
+        )
+        self.visit_while_stmt = partial(v, keywords={"while", "else"}, parens={"while"})
+        self.visit_for_stmt = partial(v, keywords={"for", "else"}, parens={"for", "in"})
+        self.visit_try_stmt = partial(
+            v, keywords={"try", "except", "else", "finally"}, parens=Ø
+        )
+        self.visit_except_clause = partial(v, keywords={"except"}, parens=Ø)
+        self.visit_with_stmt = partial(v, keywords={"with"}, parens=Ø)
+        self.visit_funcdef = partial(v, keywords={"def"}, parens=Ø)
+        self.visit_classdef = partial(v, keywords={"class"}, parens=Ø)
+        self.visit_expr_stmt = partial(v, keywords=Ø, parens=ASSIGNMENTS)
+        self.visit_return_stmt = partial(v, keywords={"return"}, parens={"return"})
+        self.visit_import_from = partial(v, keywords=Ø, parens={"import"})
+        self.visit_del_stmt = partial(v, keywords=Ø, parens={"del"})
+        self.visit_async_funcdef = self.visit_async_stmt
+        self.visit_decorated = self.visit_decorators
+
+
+def transform_line(
+    line: Line, mode: Mode, features: Collection[Feature] = ()
+) -> Iterator[Line]:
+    """Transform a `line`, potentially splitting it into many lines.
+
+    They should fit in the allotted `line_length` but might not be able to.
+
+    `features` are syntactical features that may be used in the output.
+    """
+    if line.is_comment:
+        yield line
+        return
+
+    line_str = line_to_string(line)
+
+    ll = mode.line_length
+    sn = mode.string_normalization
+    string_merge = StringMerger(ll, sn)
+    string_paren_strip = StringParenStripper(ll, sn)
+    string_split = StringSplitter(ll, sn)
+    string_paren_wrap = StringParenWrapper(ll, sn)
+
+    transformers: List[Transformer]
+    if (
+        not line.contains_uncollapsable_type_comments()
+        and not line.should_split_rhs
+        and not line.magic_trailing_comma
+        and (
+            is_line_short_enough(line, line_length=mode.line_length, line_str=line_str)
+            or line.contains_unsplittable_type_ignore()
+        )
+        and not (line.inside_brackets and line.contains_standalone_comments())
+    ):
+        # Only apply basic string preprocessing, since lines shouldn't be split here.
+        if mode.experimental_string_processing:
+            transformers = [string_merge, string_paren_strip]
+        else:
+            transformers = []
+    elif line.is_def:
+        transformers = [left_hand_split]
+    else:
+
+        def rhs(line: Line, features: Collection[Feature]) -> Iterator[Line]:
+            """Wraps calls to `right_hand_split`.
+
+            The calls increasingly `omit` right-hand trailers (bracket pairs with
+            content), meaning the trailers get glued together to split on another
+            bracket pair instead.
+            """
+            for omit in generate_trailers_to_omit(line, mode.line_length):
+                lines = list(
+                    right_hand_split(line, mode.line_length, features, omit=omit)
+                )
+                # Note: this check is only able to figure out if the first line of the
+                # *current* transformation fits in the line length.  This is true only
+                # for simple cases.  All others require running more transforms via
+                # `transform_line()`.  This check doesn't know if those would succeed.
+                if is_line_short_enough(lines[0], line_length=mode.line_length):
+                    yield from lines
+                    return
+
+            # All splits failed, best effort split with no omits.
+            # This mostly happens to multiline strings that are by definition
+            # reported as not fitting a single line, as well as lines that contain
+            # trailing commas (those have to be exploded).
+            yield from right_hand_split(
+                line, line_length=mode.line_length, features=features
+            )
+
+        if mode.experimental_string_processing:
+            if line.inside_brackets:
+                transformers = [
+                    string_merge,
+                    string_paren_strip,
+                    string_split,
+                    delimiter_split,
+                    standalone_comment_split,
+                    string_paren_wrap,
+                    rhs,
+                ]
+            else:
+                transformers = [
+                    string_merge,
+                    string_paren_strip,
+                    string_split,
+                    string_paren_wrap,
+                    rhs,
+                ]
+        else:
+            if line.inside_brackets:
+                transformers = [delimiter_split, standalone_comment_split, rhs]
+            else:
+                transformers = [rhs]
+
+    for transform in transformers:
+        # We are accumulating lines in `result` because we might want to abort
+        # mission and return the original line in the end, or attempt a different
+        # split altogether.
+        try:
+            result = run_transformer(line, transform, mode, features, line_str=line_str)
+        except CannotTransform:
+            continue
+        else:
+            yield from result
+            break
+
+    else:
+        yield line
+
+
+def left_hand_split(line: Line, _features: Collection[Feature] = ()) -> Iterator[Line]:
+    """Split line into many lines, starting with the first matching bracket pair.
+
+    Note: this usually looks weird, only use this for function definitions.
+    Prefer RHS otherwise.  This is why this function is not symmetrical with
+    :func:`right_hand_split` which also handles optional parentheses.
+    """
+    tail_leaves: List[Leaf] = []
+    body_leaves: List[Leaf] = []
+    head_leaves: List[Leaf] = []
+    current_leaves = head_leaves
+    matching_bracket: Optional[Leaf] = None
+    for leaf in line.leaves:
+        if (
+            current_leaves is body_leaves
+            and leaf.type in CLOSING_BRACKETS
+            and leaf.opening_bracket is matching_bracket
+        ):
+            current_leaves = tail_leaves if body_leaves else head_leaves
+        current_leaves.append(leaf)
+        if current_leaves is head_leaves:
+            if leaf.type in OPENING_BRACKETS:
+                matching_bracket = leaf
+                current_leaves = body_leaves
+    if not matching_bracket:
+        raise CannotSplit("No brackets found")
+
+    head = bracket_split_build_line(head_leaves, line, matching_bracket)
+    body = bracket_split_build_line(body_leaves, line, matching_bracket, is_body=True)
+    tail = bracket_split_build_line(tail_leaves, line, matching_bracket)
+    bracket_split_succeeded_or_raise(head, body, tail)
+    for result in (head, body, tail):
+        if result:
+            yield result
+
+
+def right_hand_split(
+    line: Line,
+    line_length: int,
+    features: Collection[Feature] = (),
+    omit: Collection[LeafID] = (),
+) -> Iterator[Line]:
+    """Split line into many lines, starting with the last matching bracket pair.
+
+    If the split was by optional parentheses, attempt splitting without them, too.
+    `omit` is a collection of closing bracket IDs that shouldn't be considered for
+    this split.
+
+    Note: running this function modifies `bracket_depth` on the leaves of `line`.
+    """
+    tail_leaves: List[Leaf] = []
+    body_leaves: List[Leaf] = []
+    head_leaves: List[Leaf] = []
+    current_leaves = tail_leaves
+    opening_bracket: Optional[Leaf] = None
+    closing_bracket: Optional[Leaf] = None
+    for leaf in reversed(line.leaves):
+        if current_leaves is body_leaves:
+            if leaf is opening_bracket:
+                current_leaves = head_leaves if body_leaves else tail_leaves
+        current_leaves.append(leaf)
+        if current_leaves is tail_leaves:
+            if leaf.type in CLOSING_BRACKETS and id(leaf) not in omit:
+                opening_bracket = leaf.opening_bracket
+                closing_bracket = leaf
+                current_leaves = body_leaves
+    if not (opening_bracket and closing_bracket and head_leaves):
+        # If there is no opening or closing_bracket that means the split failed and
+        # all content is in the tail.  Otherwise, if `head_leaves` are empty, it means
+        # the matching `opening_bracket` wasn't available on `line` anymore.
+        raise CannotSplit("No brackets found")
+
+    tail_leaves.reverse()
+    body_leaves.reverse()
+    head_leaves.reverse()
+    head = bracket_split_build_line(head_leaves, line, opening_bracket)
+    body = bracket_split_build_line(body_leaves, line, opening_bracket, is_body=True)
+    tail = bracket_split_build_line(tail_leaves, line, opening_bracket)
+    bracket_split_succeeded_or_raise(head, body, tail)
+    if (
+        Feature.FORCE_OPTIONAL_PARENTHESES not in features
+        # the opening bracket is an optional paren
+        and opening_bracket.type == token.LPAR
+        and not opening_bracket.value
+        # the closing bracket is an optional paren
+        and closing_bracket.type == token.RPAR
+        and not closing_bracket.value
+        # it's not an import (optional parens are the only thing we can split on
+        # in this case; attempting a split without them is a waste of time)
+        and not line.is_import
+        # there are no standalone comments in the body
+        and not body.contains_standalone_comments(0)
+        # and we can actually remove the parens
+        and can_omit_invisible_parens(body, line_length, omit_on_explode=omit)
+    ):
+        omit = {id(closing_bracket), *omit}
+        try:
+            yield from right_hand_split(line, line_length, features=features, omit=omit)
+            return
+
+        except CannotSplit:
+            if not (
+                can_be_split(body)
+                or is_line_short_enough(body, line_length=line_length)
+            ):
+                raise CannotSplit(
+                    "Splitting failed, body is still too long and can't be split."
+                )
+
+            elif head.contains_multiline_strings() or tail.contains_multiline_strings():
+                raise CannotSplit(
+                    "The current optional pair of parentheses is bound to fail to"
+                    " satisfy the splitting algorithm because the head or the tail"
+                    " contains multiline strings which by definition never fit one"
+                    " line."
+                )
+
+    ensure_visible(opening_bracket)
+    ensure_visible(closing_bracket)
+    for result in (head, body, tail):
+        if result:
+            yield result
+
+
+def bracket_split_succeeded_or_raise(head: Line, body: Line, tail: Line) -> None:
+    """Raise :exc:`CannotSplit` if the last left- or right-hand split failed.
+
+    Do nothing otherwise.
+
+    A left- or right-hand split is based on a pair of brackets. Content before
+    (and including) the opening bracket is left on one line, content inside the
+    brackets is put on a separate line, and finally content starting with and
+    following the closing bracket is put on a separate line.
+
+    Those are called `head`, `body`, and `tail`, respectively. If the split
+    produced the same line (all content in `head`) or ended up with an empty `body`
+    and the `tail` is just the closing bracket, then it's considered failed.
+    """
+    tail_len = len(str(tail).strip())
+    if not body:
+        if tail_len == 0:
+            raise CannotSplit("Splitting brackets produced the same line")
+
+        elif tail_len < 3:
+            raise CannotSplit(
+                f"Splitting brackets on an empty body to save {tail_len} characters is"
+                " not worth it"
+            )
+
+
+def bracket_split_build_line(
+    leaves: List[Leaf], original: Line, opening_bracket: Leaf, *, is_body: bool = False
+) -> Line:
+    """Return a new line with given `leaves` and respective comments from `original`.
+
+    If `is_body` is True, the result line is one-indented inside brackets and as such
+    has its first leaf's prefix normalized and a trailing comma added when expected.
+    """
+    result = Line(mode=original.mode, depth=original.depth)
+    if is_body:
+        result.inside_brackets = True
+        result.depth += 1
+        if leaves:
+            # Since body is a new indent level, remove spurious leading whitespace.
+            normalize_prefix(leaves[0], inside_brackets=True)
+            # Ensure a trailing comma for imports and standalone function arguments, but
+            # be careful not to add one after any comments or within type annotations.
+            no_commas = (
+                original.is_def
+                and opening_bracket.value == "("
+                and not any(leaf.type == token.COMMA for leaf in leaves)
+            )
+
+            if original.is_import or no_commas:
+                for i in range(len(leaves) - 1, -1, -1):
+                    if leaves[i].type == STANDALONE_COMMENT:
+                        continue
+
+                    if leaves[i].type != token.COMMA:
+                        new_comma = Leaf(token.COMMA, ",")
+                        leaves.insert(i + 1, new_comma)
+                    break
+
+    # Populate the line
+    for leaf in leaves:
+        result.append(leaf, preformatted=True)
+        for comment_after in original.comments_after(leaf):
+            result.append(comment_after, preformatted=True)
+    if is_body and should_split_line(result, opening_bracket):
+        result.should_split_rhs = True
+    return result
+
+
+def dont_increase_indentation(split_func: Transformer) -> Transformer:
+    """Normalize prefix of the first leaf in every line returned by `split_func`.
+
+    This is a decorator over relevant split functions.
+    """
+
+    @wraps(split_func)
+    def split_wrapper(line: Line, features: Collection[Feature] = ()) -> Iterator[Line]:
+        for line in split_func(line, features):
+            normalize_prefix(line.leaves[0], inside_brackets=True)
+            yield line
+
+    return split_wrapper
+
+
+@dont_increase_indentation
+def delimiter_split(line: Line, features: Collection[Feature] = ()) -> Iterator[Line]:
+    """Split according to delimiters of the highest priority.
+
+    If the appropriate Features are given, the split will add trailing commas
+    also in function signatures and calls that contain `*` and `**`.
+    """
+    try:
+        last_leaf = line.leaves[-1]
+    except IndexError:
+        raise CannotSplit("Line empty")
+
+    bt = line.bracket_tracker
+    try:
+        delimiter_priority = bt.max_delimiter_priority(exclude={id(last_leaf)})
+    except ValueError:
+        raise CannotSplit("No delimiters found")
+
+    if delimiter_priority == DOT_PRIORITY:
+        if bt.delimiter_count_with_priority(delimiter_priority) == 1:
+            raise CannotSplit("Splitting a single attribute from its owner looks wrong")
+
+    current_line = Line(
+        mode=line.mode, depth=line.depth, inside_brackets=line.inside_brackets
+    )
+    lowest_depth = sys.maxsize
+    trailing_comma_safe = True
+
+    def append_to_line(leaf: Leaf) -> Iterator[Line]:
+        """Append `leaf` to current line or to new line if appending impossible."""
+        nonlocal current_line
+        try:
+            current_line.append_safe(leaf, preformatted=True)
+        except ValueError:
+            yield current_line
+
+            current_line = Line(
+                mode=line.mode, depth=line.depth, inside_brackets=line.inside_brackets
+            )
+            current_line.append(leaf)
+
+    for leaf in line.leaves:
+        yield from append_to_line(leaf)
+
+        for comment_after in line.comments_after(leaf):
+            yield from append_to_line(comment_after)
+
+        lowest_depth = min(lowest_depth, leaf.bracket_depth)
+        if leaf.bracket_depth == lowest_depth:
+            if is_vararg(leaf, within={syms.typedargslist}):
+                trailing_comma_safe = (
+                    trailing_comma_safe and Feature.TRAILING_COMMA_IN_DEF in features
+                )
+            elif is_vararg(leaf, within={syms.arglist, syms.argument}):
+                trailing_comma_safe = (
+                    trailing_comma_safe and Feature.TRAILING_COMMA_IN_CALL in features
+                )
+
+        leaf_priority = bt.delimiters.get(id(leaf))
+        if leaf_priority == delimiter_priority:
+            yield current_line
+
+            current_line = Line(
+                mode=line.mode, depth=line.depth, inside_brackets=line.inside_brackets
+            )
+    if current_line:
+        if (
+            trailing_comma_safe
+            and delimiter_priority == COMMA_PRIORITY
+            and current_line.leaves[-1].type != token.COMMA
+            and current_line.leaves[-1].type != STANDALONE_COMMENT
+        ):
+            new_comma = Leaf(token.COMMA, ",")
+            current_line.append(new_comma)
+        yield current_line
+
+
+@dont_increase_indentation
+def standalone_comment_split(
+    line: Line, features: Collection[Feature] = ()
+) -> Iterator[Line]:
+    """Split standalone comments from the rest of the line."""
+    if not line.contains_standalone_comments(0):
+        raise CannotSplit("Line does not have any standalone comments")
+
+    current_line = Line(
+        mode=line.mode, depth=line.depth, inside_brackets=line.inside_brackets
+    )
+
+    def append_to_line(leaf: Leaf) -> Iterator[Line]:
+        """Append `leaf` to current line or to new line if appending impossible."""
+        nonlocal current_line
+        try:
+            current_line.append_safe(leaf, preformatted=True)
+        except ValueError:
+            yield current_line
+
+            current_line = Line(
+                line.mode, depth=line.depth, inside_brackets=line.inside_brackets
+            )
+            current_line.append(leaf)
+
+    for leaf in line.leaves:
+        yield from append_to_line(leaf)
+
+        for comment_after in line.comments_after(leaf):
+            yield from append_to_line(comment_after)
+
+    if current_line:
+        yield current_line
+
+
+def normalize_prefix(leaf: Leaf, *, inside_brackets: bool) -> None:
+    """Leave existing extra newlines if not `inside_brackets`. Remove everything
+    else.
+
+    Note: don't use backslashes for formatting or you'll lose your voting rights.
+    """
+    if not inside_brackets:
+        spl = leaf.prefix.split("#")
+        if "\\" not in spl[0]:
+            nl_count = spl[-1].count("\n")
+            if len(spl) > 1:
+                nl_count -= 1
+            leaf.prefix = "\n" * nl_count
+            return
+
+    leaf.prefix = ""
+
+
+def normalize_invisible_parens(node: Node, parens_after: Set[str]) -> None:
+    """Make existing optional parentheses invisible or create new ones.
+
+    `parens_after` is a set of string leaf values immediately after which parens
+    should be put.
+
+    Standardizes on visible parentheses for single-element tuples, and keeps
+    existing visible parentheses for other tuples and generator expressions.
+    """
+    for pc in list_comments(node.prefix, is_endmarker=False):
+        if pc.value in FMT_OFF:
+            # This `node` has a prefix with `# fmt: off`, don't mess with parens.
+            return
+    check_lpar = False
+    for index, child in enumerate(list(node.children)):
+        # Fixes a bug where invisible parens are not properly stripped from
+        # assignment statements that contain type annotations.
+        if isinstance(child, Node) and child.type == syms.annassign:
+            normalize_invisible_parens(child, parens_after=parens_after)
+
+        # Add parentheses around long tuple unpacking in assignments.
+        if (
+            index == 0
+            and isinstance(child, Node)
+            and child.type == syms.testlist_star_expr
+        ):
+            check_lpar = True
+
+        if check_lpar:
+            if child.type == syms.atom:
+                if maybe_make_parens_invisible_in_atom(child, parent=node):
+                    wrap_in_parentheses(node, child, visible=False)
+            elif is_one_tuple(child):
+                wrap_in_parentheses(node, child, visible=True)
+            elif node.type == syms.import_from:
+                # "import from" nodes store parentheses directly as part of
+                # the statement
+                if child.type == token.LPAR:
+                    # make parentheses invisible
+                    child.value = ""  # type: ignore
+                    node.children[-1].value = ""  # type: ignore
+                elif child.type != token.STAR:
+                    # insert invisible parentheses
+                    node.insert_child(index, Leaf(token.LPAR, ""))
+                    node.append_child(Leaf(token.RPAR, ""))
+                break
+
+            elif not (isinstance(child, Leaf) and is_multiline_string(child)):
+                wrap_in_parentheses(node, child, visible=False)
+
+        check_lpar = isinstance(child, Leaf) and child.value in parens_after
+
+
+def maybe_make_parens_invisible_in_atom(node: LN, parent: LN) -> bool:
+    """If it's safe, make the parens in the atom `node` invisible, recursively.
+    Additionally, remove repeated, adjacent invisible parens from the atom `node`
+    as they are redundant.
+
+    Returns whether the node should itself be wrapped in invisible parentheses.
+
+    """
+
+    if (
+        node.type != syms.atom
+        or is_empty_tuple(node)
+        or is_one_tuple(node)
+        or (is_yield(node) and parent.type != syms.expr_stmt)
+        or max_delimiter_priority_in_atom(node) >= COMMA_PRIORITY
+    ):
+        return False
+
+    if is_walrus_assignment(node):
+        if parent.type in [
+            syms.annassign,
+            syms.expr_stmt,
+            syms.assert_stmt,
+            syms.return_stmt,
+            # these ones aren't useful to end users, but they do please fuzzers
+            syms.for_stmt,
+            syms.del_stmt,
+        ]:
+            return False
+
+    first = node.children[0]
+    last = node.children[-1]
+    if first.type == token.LPAR and last.type == token.RPAR:
+        middle = node.children[1]
+        # make parentheses invisible
+        first.value = ""  # type: ignore
+        last.value = ""  # type: ignore
+        maybe_make_parens_invisible_in_atom(middle, parent=parent)
+
+        if is_atom_with_invisible_parens(middle):
+            # Strip the invisible parens from `middle` by replacing
+            # it with the child in-between the invisible parens
+            middle.replace(middle.children[1])
+
+        return False
+
+    return True
+
+
+def should_split_line(line: Line, opening_bracket: Leaf) -> bool:
+    """Should `line` be immediately split with `delimiter_split()` after RHS?"""
+
+    if not (opening_bracket.parent and opening_bracket.value in "[{("):
+        return False
+
+    # We're essentially checking if the body is delimited by commas and there's more
+    # than one of them (we're excluding the trailing comma and if the delimiter priority
+    # is still commas, that means there's more).
+    exclude = set()
+    trailing_comma = False
+    try:
+        last_leaf = line.leaves[-1]
+        if last_leaf.type == token.COMMA:
+            trailing_comma = True
+            exclude.add(id(last_leaf))
+        max_priority = line.bracket_tracker.max_delimiter_priority(exclude=exclude)
+    except (IndexError, ValueError):
+        return False
+
+    return max_priority == COMMA_PRIORITY and (
+        (line.mode.magic_trailing_comma and trailing_comma)
+        # always explode imports
+        or opening_bracket.parent.type in {syms.atom, syms.import_from}
+    )
+
+
+def generate_trailers_to_omit(line: Line, line_length: int) -> Iterator[Set[LeafID]]:
+    """Generate sets of closing bracket IDs that should be omitted in a RHS.
+
+    Brackets can be omitted if the entire trailer up to and including
+    a preceding closing bracket fits in one line.
+
+    Yielded sets are cumulative (contain results of previous yields, too).  First
+    set is empty, unless the line should explode, in which case bracket pairs until
+    the one that needs to explode are omitted.
+    """
+
+    omit: Set[LeafID] = set()
+    if not line.magic_trailing_comma:
+        yield omit
+
+    length = 4 * line.depth
+    opening_bracket: Optional[Leaf] = None
+    closing_bracket: Optional[Leaf] = None
+    inner_brackets: Set[LeafID] = set()
+    for index, leaf, leaf_length in line.enumerate_with_length(reversed=True):
+        length += leaf_length
+        if length > line_length:
+            break
+
+        has_inline_comment = leaf_length > len(leaf.value) + len(leaf.prefix)
+        if leaf.type == STANDALONE_COMMENT or has_inline_comment:
+            break
+
+        if opening_bracket:
+            if leaf is opening_bracket:
+                opening_bracket = None
+            elif leaf.type in CLOSING_BRACKETS:
+                prev = line.leaves[index - 1] if index > 0 else None
+                if (
+                    prev
+                    and prev.type == token.COMMA
+                    and not is_one_tuple_between(
+                        leaf.opening_bracket, leaf, line.leaves
+                    )
+                ):
+                    # Never omit bracket pairs with trailing commas.
+                    # We need to explode on those.
+                    break
+
+                inner_brackets.add(id(leaf))
+        elif leaf.type in CLOSING_BRACKETS:
+            prev = line.leaves[index - 1] if index > 0 else None
+            if prev and prev.type in OPENING_BRACKETS:
+                # Empty brackets would fail a split so treat them as "inner"
+                # brackets (e.g. only add them to the `omit` set if another
+                # pair of brackets was good enough.
+                inner_brackets.add(id(leaf))
+                continue
+
+            if closing_bracket:
+                omit.add(id(closing_bracket))
+                omit.update(inner_brackets)
+                inner_brackets.clear()
+                yield omit
+
+            if (
+                prev
+                and prev.type == token.COMMA
+                and not is_one_tuple_between(leaf.opening_bracket, leaf, line.leaves)
+            ):
+                # Never omit bracket pairs with trailing commas.
+                # We need to explode on those.
+                break
+
+            if leaf.value:
+                opening_bracket = leaf.opening_bracket
+                closing_bracket = leaf
+
+
+def run_transformer(
+    line: Line,
+    transform: Transformer,
+    mode: Mode,
+    features: Collection[Feature],
+    *,
+    line_str: str = "",
+) -> List[Line]:
+    if not line_str:
+        line_str = line_to_string(line)
+    result: List[Line] = []
+    for transformed_line in transform(line, features):
+        if str(transformed_line).strip("\n") == line_str:
+            raise CannotTransform("Line transformer returned an unchanged result")
+
+        result.extend(transform_line(transformed_line, mode=mode, features=features))
+
+    if not (
+        transform.__name__ == "rhs"
+        and line.bracket_tracker.invisible
+        and not any(bracket.value for bracket in line.bracket_tracker.invisible)
+        and not line.contains_multiline_strings()
+        and not result[0].contains_uncollapsable_type_comments()
+        and not result[0].contains_unsplittable_type_ignore()
+        and not is_line_short_enough(result[0], line_length=mode.line_length)
+    ):
+        return result
+
+    line_copy = line.clone()
+    append_leaves(line_copy, line, line.leaves)
+    features_fop = set(features) | {Feature.FORCE_OPTIONAL_PARENTHESES}
+    second_opinion = run_transformer(
+        line_copy, transform, mode, features_fop, line_str=line_str
+    )
+    if all(
+        is_line_short_enough(ln, line_length=mode.line_length) for ln in second_opinion
+    ):
+        result = second_opinion
+    return result
diff --git a/src/black/lines.py b/src/black/lines.py
new file mode 100644
index 00000000000..63225c0e6d3
--- /dev/null
+++ b/src/black/lines.py
@@ -0,0 +1,734 @@
+from dataclasses import dataclass, field
+import itertools
+import sys
+from typing import (
+    Callable,
+    Collection,
+    Dict,
+    Iterator,
+    List,
+    Optional,
+    Sequence,
+    Tuple,
+    TypeVar,
+    cast,
+)
+
+from blib2to3.pytree import Node, Leaf
+from blib2to3.pgen2 import token
+
+from black.brackets import BracketTracker, DOT_PRIORITY
+from black.mode import Mode
+from black.nodes import STANDALONE_COMMENT, TEST_DESCENDANTS
+from black.nodes import BRACKETS, OPENING_BRACKETS, CLOSING_BRACKETS
+from black.nodes import syms, whitespace, replace_child, child_towards
+from black.nodes import is_multiline_string, is_import, is_type_comment, last_two_except
+from black.nodes import is_one_tuple_between
+
+# types
+T = TypeVar("T")
+Index = int
+LeafID = int
+
+
+@dataclass
+class Line:
+    """Holds leaves and comments. Can be printed with `str(line)`."""
+
+    mode: Mode
+    depth: int = 0
+    leaves: List[Leaf] = field(default_factory=list)
+    # keys ordered like `leaves`
+    comments: Dict[LeafID, List[Leaf]] = field(default_factory=dict)
+    bracket_tracker: BracketTracker = field(default_factory=BracketTracker)
+    inside_brackets: bool = False
+    should_split_rhs: bool = False
+    magic_trailing_comma: Optional[Leaf] = None
+
+    def append(self, leaf: Leaf, preformatted: bool = False) -> None:
+        """Add a new `leaf` to the end of the line.
+
+        Unless `preformatted` is True, the `leaf` will receive a new consistent
+        whitespace prefix and metadata applied by :class:`BracketTracker`.
+        Trailing commas are maybe removed, unpacked for loop variables are
+        demoted from being delimiters.
+
+        Inline comments are put aside.
+        """
+        has_value = leaf.type in BRACKETS or bool(leaf.value.strip())
+        if not has_value:
+            return
+
+        if token.COLON == leaf.type and self.is_class_paren_empty:
+            del self.leaves[-2:]
+        if self.leaves and not preformatted:
+            # Note: at this point leaf.prefix should be empty except for
+            # imports, for which we only preserve newlines.
+            leaf.prefix += whitespace(
+                leaf, complex_subscript=self.is_complex_subscript(leaf)
+            )
+        if self.inside_brackets or not preformatted:
+            self.bracket_tracker.mark(leaf)
+            if self.mode.magic_trailing_comma:
+                if self.has_magic_trailing_comma(leaf):
+                    self.magic_trailing_comma = leaf
+            elif self.has_magic_trailing_comma(leaf, ensure_removable=True):
+                self.remove_trailing_comma()
+        if not self.append_comment(leaf):
+            self.leaves.append(leaf)
+
+    def append_safe(self, leaf: Leaf, preformatted: bool = False) -> None:
+        """Like :func:`append()` but disallow invalid standalone comment structure.
+
+        Raises ValueError when any `leaf` is appended after a standalone comment
+        or when a standalone comment is not the first leaf on the line.
+        """
+        if self.bracket_tracker.depth == 0:
+            if self.is_comment:
+                raise ValueError("cannot append to standalone comments")
+
+            if self.leaves and leaf.type == STANDALONE_COMMENT:
+                raise ValueError(
+                    "cannot append standalone comments to a populated line"
+                )
+
+        self.append(leaf, preformatted=preformatted)
+
+    @property
+    def is_comment(self) -> bool:
+        """Is this line a standalone comment?"""
+        return len(self.leaves) == 1 and self.leaves[0].type == STANDALONE_COMMENT
+
+    @property
+    def is_decorator(self) -> bool:
+        """Is this line a decorator?"""
+        return bool(self) and self.leaves[0].type == token.AT
+
+    @property
+    def is_import(self) -> bool:
+        """Is this an import line?"""
+        return bool(self) and is_import(self.leaves[0])
+
+    @property
+    def is_class(self) -> bool:
+        """Is this line a class definition?"""
+        return (
+            bool(self)
+            and self.leaves[0].type == token.NAME
+            and self.leaves[0].value == "class"
+        )
+
+    @property
+    def is_stub_class(self) -> bool:
+        """Is this line a class definition with a body consisting only of "..."?"""
+        return self.is_class and self.leaves[-3:] == [
+            Leaf(token.DOT, ".") for _ in range(3)
+        ]
+
+    @property
+    def is_def(self) -> bool:
+        """Is this a function definition? (Also returns True for async defs.)"""
+        try:
+            first_leaf = self.leaves[0]
+        except IndexError:
+            return False
+
+        try:
+            second_leaf: Optional[Leaf] = self.leaves[1]
+        except IndexError:
+            second_leaf = None
+        return (first_leaf.type == token.NAME and first_leaf.value == "def") or (
+            first_leaf.type == token.ASYNC
+            and second_leaf is not None
+            and second_leaf.type == token.NAME
+            and second_leaf.value == "def"
+        )
+
+    @property
+    def is_class_paren_empty(self) -> bool:
+        """Is this a class with no base classes but using parentheses?
+
+        Those are unnecessary and should be removed.
+        """
+        return (
+            bool(self)
+            and len(self.leaves) == 4
+            and self.is_class
+            and self.leaves[2].type == token.LPAR
+            and self.leaves[2].value == "("
+            and self.leaves[3].type == token.RPAR
+            and self.leaves[3].value == ")"
+        )
+
+    @property
+    def is_triple_quoted_string(self) -> bool:
+        """Is the line a triple quoted string?"""
+        return (
+            bool(self)
+            and self.leaves[0].type == token.STRING
+            and self.leaves[0].value.startswith(('"""', "'''"))
+        )
+
+    def contains_standalone_comments(self, depth_limit: int = sys.maxsize) -> bool:
+        """If so, needs to be split before emitting."""
+        for leaf in self.leaves:
+            if leaf.type == STANDALONE_COMMENT and leaf.bracket_depth <= depth_limit:
+                return True
+
+        return False
+
+    def contains_uncollapsable_type_comments(self) -> bool:
+        ignored_ids = set()
+        try:
+            last_leaf = self.leaves[-1]
+            ignored_ids.add(id(last_leaf))
+            if last_leaf.type == token.COMMA or (
+                last_leaf.type == token.RPAR and not last_leaf.value
+            ):
+                # When trailing commas or optional parens are inserted by Black for
+                # consistency, comments after the previous last element are not moved
+                # (they don't have to, rendering will still be correct).  So we ignore
+                # trailing commas and invisible.
+                last_leaf = self.leaves[-2]
+                ignored_ids.add(id(last_leaf))
+        except IndexError:
+            return False
+
+        # A type comment is uncollapsable if it is attached to a leaf
+        # that isn't at the end of the line (since that could cause it
+        # to get associated to a different argument) or if there are
+        # comments before it (since that could cause it to get hidden
+        # behind a comment.
+        comment_seen = False
+        for leaf_id, comments in self.comments.items():
+            for comment in comments:
+                if is_type_comment(comment):
+                    if comment_seen or (
+                        not is_type_comment(comment, " ignore")
+                        and leaf_id not in ignored_ids
+                    ):
+                        return True
+
+                comment_seen = True
+
+        return False
+
+    def contains_unsplittable_type_ignore(self) -> bool:
+        if not self.leaves:
+            return False
+
+        # If a 'type: ignore' is attached to the end of a line, we
+        # can't split the line, because we can't know which of the
+        # subexpressions the ignore was meant to apply to.
+        #
+        # We only want this to apply to actual physical lines from the
+        # original source, though: we don't want the presence of a
+        # 'type: ignore' at the end of a multiline expression to
+        # justify pushing it all onto one line. Thus we
+        # (unfortunately) need to check the actual source lines and
+        # only report an unsplittable 'type: ignore' if this line was
+        # one line in the original code.
+
+        # Grab the first and last line numbers, skipping generated leaves
+        first_line = next((leaf.lineno for leaf in self.leaves if leaf.lineno != 0), 0)
+        last_line = next(
+            (leaf.lineno for leaf in reversed(self.leaves) if leaf.lineno != 0), 0
+        )
+
+        if first_line == last_line:
+            # We look at the last two leaves since a comma or an
+            # invisible paren could have been added at the end of the
+            # line.
+            for node in self.leaves[-2:]:
+                for comment in self.comments.get(id(node), []):
+                    if is_type_comment(comment, " ignore"):
+                        return True
+
+        return False
+
+    def contains_multiline_strings(self) -> bool:
+        return any(is_multiline_string(leaf) for leaf in self.leaves)
+
+    def has_magic_trailing_comma(
+        self, closing: Leaf, ensure_removable: bool = False
+    ) -> bool:
+        """Return True if we have a magic trailing comma, that is when:
+        - there's a trailing comma here
+        - it's not a one-tuple
+        Additionally, if ensure_removable:
+        - it's not from square bracket indexing
+        """
+        if not (
+            closing.type in CLOSING_BRACKETS
+            and self.leaves
+            and self.leaves[-1].type == token.COMMA
+        ):
+            return False
+
+        if closing.type == token.RBRACE:
+            return True
+
+        if closing.type == token.RSQB:
+            if not ensure_removable:
+                return True
+            comma = self.leaves[-1]
+            return bool(comma.parent and comma.parent.type == syms.listmaker)
+
+        if self.is_import:
+            return True
+
+        if not is_one_tuple_between(closing.opening_bracket, closing, self.leaves):
+            return True
+
+        return False
+
+    def append_comment(self, comment: Leaf) -> bool:
+        """Add an inline or standalone comment to the line."""
+        if (
+            comment.type == STANDALONE_COMMENT
+            and self.bracket_tracker.any_open_brackets()
+        ):
+            comment.prefix = ""
+            return False
+
+        if comment.type != token.COMMENT:
+            return False
+
+        if not self.leaves:
+            comment.type = STANDALONE_COMMENT
+            comment.prefix = ""
+            return False
+
+        last_leaf = self.leaves[-1]
+        if (
+            last_leaf.type == token.RPAR
+            and not last_leaf.value
+            and last_leaf.parent
+            and len(list(last_leaf.parent.leaves())) <= 3
+            and not is_type_comment(comment)
+        ):
+            # Comments on an optional parens wrapping a single leaf should belong to
+            # the wrapped node except if it's a type comment. Pinning the comment like
+            # this avoids unstable formatting caused by comment migration.
+            if len(self.leaves) < 2:
+                comment.type = STANDALONE_COMMENT
+                comment.prefix = ""
+                return False
+
+            last_leaf = self.leaves[-2]
+        self.comments.setdefault(id(last_leaf), []).append(comment)
+        return True
+
+    def comments_after(self, leaf: Leaf) -> List[Leaf]:
+        """Generate comments that should appear directly after `leaf`."""
+        return self.comments.get(id(leaf), [])
+
+    def remove_trailing_comma(self) -> None:
+        """Remove the trailing comma and moves the comments attached to it."""
+        trailing_comma = self.leaves.pop()
+        trailing_comma_comments = self.comments.pop(id(trailing_comma), [])
+        self.comments.setdefault(id(self.leaves[-1]), []).extend(
+            trailing_comma_comments
+        )
+
+    def is_complex_subscript(self, leaf: Leaf) -> bool:
+        """Return True iff `leaf` is part of a slice with non-trivial exprs."""
+        open_lsqb = self.bracket_tracker.get_open_lsqb()
+        if open_lsqb is None:
+            return False
+
+        subscript_start = open_lsqb.next_sibling
+
+        if isinstance(subscript_start, Node):
+            if subscript_start.type == syms.listmaker:
+                return False
+
+            if subscript_start.type == syms.subscriptlist:
+                subscript_start = child_towards(subscript_start, leaf)
+        return subscript_start is not None and any(
+            n.type in TEST_DESCENDANTS for n in subscript_start.pre_order()
+        )
+
+    def enumerate_with_length(
+        self, reversed: bool = False
+    ) -> Iterator[Tuple[Index, Leaf, int]]:
+        """Return an enumeration of leaves with their length.
+
+        Stops prematurely on multiline strings and standalone comments.
+        """
+        op = cast(
+            Callable[[Sequence[Leaf]], Iterator[Tuple[Index, Leaf]]],
+            enumerate_reversed if reversed else enumerate,
+        )
+        for index, leaf in op(self.leaves):
+            length = len(leaf.prefix) + len(leaf.value)
+            if "\n" in leaf.value:
+                return  # Multiline strings, we can't continue.
+
+            for comment in self.comments_after(leaf):
+                length += len(comment.value)
+
+            yield index, leaf, length
+
+    def clone(self) -> "Line":
+        return Line(
+            mode=self.mode,
+            depth=self.depth,
+            inside_brackets=self.inside_brackets,
+            should_split_rhs=self.should_split_rhs,
+            magic_trailing_comma=self.magic_trailing_comma,
+        )
+
+    def __str__(self) -> str:
+        """Render the line."""
+        if not self:
+            return "\n"
+
+        indent = "    " * self.depth
+        leaves = iter(self.leaves)
+        first = next(leaves)
+        res = f"{first.prefix}{indent}{first.value}"
+        for leaf in leaves:
+            res += str(leaf)
+        for comment in itertools.chain.from_iterable(self.comments.values()):
+            res += str(comment)
+
+        return res + "\n"
+
+    def __bool__(self) -> bool:
+        """Return True if the line has leaves or comments."""
+        return bool(self.leaves or self.comments)
+
+
+@dataclass
+class EmptyLineTracker:
+    """Provides a stateful method that returns the number of potential extra
+    empty lines needed before and after the currently processed line.
+
+    Note: this tracker works on lines that haven't been split yet.  It assumes
+    the prefix of the first leaf consists of optional newlines.  Those newlines
+    are consumed by `maybe_empty_lines()` and included in the computation.
+    """
+
+    is_pyi: bool = False
+    previous_line: Optional[Line] = None
+    previous_after: int = 0
+    previous_defs: List[int] = field(default_factory=list)
+
+    def maybe_empty_lines(self, current_line: Line) -> Tuple[int, int]:
+        """Return the number of extra empty lines before and after the `current_line`.
+
+        This is for separating `def`, `async def` and `class` with extra empty
+        lines (two on module-level).
+        """
+        before, after = self._maybe_empty_lines(current_line)
+        before = (
+            # Black should not insert empty lines at the beginning
+            # of the file
+            0
+            if self.previous_line is None
+            else before - self.previous_after
+        )
+        self.previous_after = after
+        self.previous_line = current_line
+        return before, after
+
+    def _maybe_empty_lines(self, current_line: Line) -> Tuple[int, int]:
+        max_allowed = 1
+        if current_line.depth == 0:
+            max_allowed = 1 if self.is_pyi else 2
+        if current_line.leaves:
+            # Consume the first leaf's extra newlines.
+            first_leaf = current_line.leaves[0]
+            before = first_leaf.prefix.count("\n")
+            before = min(before, max_allowed)
+            first_leaf.prefix = ""
+        else:
+            before = 0
+        depth = current_line.depth
+        while self.previous_defs and self.previous_defs[-1] >= depth:
+            self.previous_defs.pop()
+            if self.is_pyi:
+                before = 0 if depth else 1
+            else:
+                before = 1 if depth else 2
+        if current_line.is_decorator or current_line.is_def or current_line.is_class:
+            return self._maybe_empty_lines_for_class_or_def(current_line, before)
+
+        if (
+            self.previous_line
+            and self.previous_line.is_import
+            and not current_line.is_import
+            and depth == self.previous_line.depth
+        ):
+            return (before or 1), 0
+
+        if (
+            self.previous_line
+            and self.previous_line.is_class
+            and current_line.is_triple_quoted_string
+        ):
+            return before, 1
+
+        return before, 0
+
+    def _maybe_empty_lines_for_class_or_def(
+        self, current_line: Line, before: int
+    ) -> Tuple[int, int]:
+        if not current_line.is_decorator:
+            self.previous_defs.append(current_line.depth)
+        if self.previous_line is None:
+            # Don't insert empty lines before the first line in the file.
+            return 0, 0
+
+        if self.previous_line.is_decorator:
+            if self.is_pyi and current_line.is_stub_class:
+                # Insert an empty line after a decorated stub class
+                return 0, 1
+
+            return 0, 0
+
+        if self.previous_line.depth < current_line.depth and (
+            self.previous_line.is_class or self.previous_line.is_def
+        ):
+            return 0, 0
+
+        if (
+            self.previous_line.is_comment
+            and self.previous_line.depth == current_line.depth
+            and before == 0
+        ):
+            return 0, 0
+
+        if self.is_pyi:
+            if self.previous_line.depth > current_line.depth:
+                newlines = 1
+            elif current_line.is_class or self.previous_line.is_class:
+                if current_line.is_stub_class and self.previous_line.is_stub_class:
+                    # No blank line between classes with an empty body
+                    newlines = 0
+                else:
+                    newlines = 1
+            elif (
+                current_line.is_def or current_line.is_decorator
+            ) and not self.previous_line.is_def:
+                # Blank line between a block of functions (maybe with preceding
+                # decorators) and a block of non-functions
+                newlines = 1
+            else:
+                newlines = 0
+        else:
+            newlines = 2
+        if current_line.depth and newlines:
+            newlines -= 1
+        return newlines, 0
+
+
+def enumerate_reversed(sequence: Sequence[T]) -> Iterator[Tuple[Index, T]]:
+    """Like `reversed(enumerate(sequence))` if that were possible."""
+    index = len(sequence) - 1
+    for element in reversed(sequence):
+        yield (index, element)
+        index -= 1
+
+
+def append_leaves(
+    new_line: Line, old_line: Line, leaves: List[Leaf], preformatted: bool = False
+) -> None:
+    """
+    Append leaves (taken from @old_line) to @new_line, making sure to fix the
+    underlying Node structure where appropriate.
+
+    All of the leaves in @leaves are duplicated. The duplicates are then
+    appended to @new_line and used to replace their originals in the underlying
+    Node structure. Any comments attached to the old leaves are reattached to
+    the new leaves.
+
+    Pre-conditions:
+        set(@leaves) is a subset of set(@old_line.leaves).
+    """
+    for old_leaf in leaves:
+        new_leaf = Leaf(old_leaf.type, old_leaf.value)
+        replace_child(old_leaf, new_leaf)
+        new_line.append(new_leaf, preformatted=preformatted)
+
+        for comment_leaf in old_line.comments_after(old_leaf):
+            new_line.append(comment_leaf, preformatted=True)
+
+
+def is_line_short_enough(line: Line, *, line_length: int, line_str: str = "") -> bool:
+    """Return True if `line` is no longer than `line_length`.
+
+    Uses the provided `line_str` rendering, if any, otherwise computes a new one.
+    """
+    if not line_str:
+        line_str = line_to_string(line)
+    return (
+        len(line_str) <= line_length
+        and "\n" not in line_str  # multiline strings
+        and not line.contains_standalone_comments()
+    )
+
+
+def can_be_split(line: Line) -> bool:
+    """Return False if the line cannot be split *for sure*.
+
+    This is not an exhaustive search but a cheap heuristic that we can use to
+    avoid some unfortunate formattings (mostly around wrapping unsplittable code
+    in unnecessary parentheses).
+    """
+    leaves = line.leaves
+    if len(leaves) < 2:
+        return False
+
+    if leaves[0].type == token.STRING and leaves[1].type == token.DOT:
+        call_count = 0
+        dot_count = 0
+        next = leaves[-1]
+        for leaf in leaves[-2::-1]:
+            if leaf.type in OPENING_BRACKETS:
+                if next.type not in CLOSING_BRACKETS:
+                    return False
+
+                call_count += 1
+            elif leaf.type == token.DOT:
+                dot_count += 1
+            elif leaf.type == token.NAME:
+                if not (next.type == token.DOT or next.type in OPENING_BRACKETS):
+                    return False
+
+            elif leaf.type not in CLOSING_BRACKETS:
+                return False
+
+            if dot_count > 1 and call_count > 1:
+                return False
+
+    return True
+
+
+def can_omit_invisible_parens(
+    line: Line,
+    line_length: int,
+    omit_on_explode: Collection[LeafID] = (),
+) -> bool:
+    """Does `line` have a shape safe to reformat without optional parens around it?
+
+    Returns True for only a subset of potentially nice looking formattings but
+    the point is to not return false positives that end up producing lines that
+    are too long.
+    """
+    bt = line.bracket_tracker
+    if not bt.delimiters:
+        # Without delimiters the optional parentheses are useless.
+        return True
+
+    max_priority = bt.max_delimiter_priority()
+    if bt.delimiter_count_with_priority(max_priority) > 1:
+        # With more than one delimiter of a kind the optional parentheses read better.
+        return False
+
+    if max_priority == DOT_PRIORITY:
+        # A single stranded method call doesn't require optional parentheses.
+        return True
+
+    assert len(line.leaves) >= 2, "Stranded delimiter"
+
+    # With a single delimiter, omit if the expression starts or ends with
+    # a bracket.
+    first = line.leaves[0]
+    second = line.leaves[1]
+    if first.type in OPENING_BRACKETS and second.type not in CLOSING_BRACKETS:
+        if _can_omit_opening_paren(line, first=first, line_length=line_length):
+            return True
+
+        # Note: we are not returning False here because a line might have *both*
+        # a leading opening bracket and a trailing closing bracket.  If the
+        # opening bracket doesn't match our rule, maybe the closing will.
+
+    penultimate = line.leaves[-2]
+    last = line.leaves[-1]
+    if line.magic_trailing_comma:
+        try:
+            penultimate, last = last_two_except(line.leaves, omit=omit_on_explode)
+        except LookupError:
+            # Turns out we'd omit everything.  We cannot skip the optional parentheses.
+            return False
+
+    if (
+        last.type == token.RPAR
+        or last.type == token.RBRACE
+        or (
+            # don't use indexing for omitting optional parentheses;
+            # it looks weird
+            last.type == token.RSQB
+            and last.parent
+            and last.parent.type != syms.trailer
+        )
+    ):
+        if penultimate.type in OPENING_BRACKETS:
+            # Empty brackets don't help.
+            return False
+
+        if is_multiline_string(first):
+            # Additional wrapping of a multiline string in this situation is
+            # unnecessary.
+            return True
+
+        if line.magic_trailing_comma and penultimate.type == token.COMMA:
+            # The rightmost non-omitted bracket pair is the one we want to explode on.
+            return True
+
+        if _can_omit_closing_paren(line, last=last, line_length=line_length):
+            return True
+
+    return False
+
+
+def _can_omit_opening_paren(line: Line, *, first: Leaf, line_length: int) -> bool:
+    """See `can_omit_invisible_parens`."""
+    remainder = False
+    length = 4 * line.depth
+    _index = -1
+    for _index, leaf, leaf_length in line.enumerate_with_length():
+        if leaf.type in CLOSING_BRACKETS and leaf.opening_bracket is first:
+            remainder = True
+        if remainder:
+            length += leaf_length
+            if length > line_length:
+                break
+
+            if leaf.type in OPENING_BRACKETS:
+                # There are brackets we can further split on.
+                remainder = False
+
+    else:
+        # checked the entire string and line length wasn't exceeded
+        if len(line.leaves) == _index + 1:
+            return True
+
+    return False
+
+
+def _can_omit_closing_paren(line: Line, *, last: Leaf, line_length: int) -> bool:
+    """See `can_omit_invisible_parens`."""
+    length = 4 * line.depth
+    seen_other_brackets = False
+    for _index, leaf, leaf_length in line.enumerate_with_length():
+        length += leaf_length
+        if leaf is last.opening_bracket:
+            if seen_other_brackets or length <= line_length:
+                return True
+
+        elif leaf.type in OPENING_BRACKETS:
+            # There are brackets we can further split on.
+            seen_other_brackets = True
+
+    return False
+
+
+def line_to_string(line: Line) -> str:
+    """Returns the string representation of @line.
+
+    WARNING: This is known to be computationally expensive.
+    """
+    return str(line).strip("\n")
diff --git a/src/black/mode.py b/src/black/mode.py
new file mode 100644
index 00000000000..e2ce322da5c
--- /dev/null
+++ b/src/black/mode.py
@@ -0,0 +1,123 @@
+"""Data structures configuring Black behavior.
+
+Mostly around Python language feature support per version and Black configuration
+chosen by the user.
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Dict, Set
+
+from black.const import DEFAULT_LINE_LENGTH
+
+
+class TargetVersion(Enum):
+    PY27 = 2
+    PY33 = 3
+    PY34 = 4
+    PY35 = 5
+    PY36 = 6
+    PY37 = 7
+    PY38 = 8
+    PY39 = 9
+
+    def is_python2(self) -> bool:
+        return self is TargetVersion.PY27
+
+
+class Feature(Enum):
+    # All string literals are unicode
+    UNICODE_LITERALS = 1
+    F_STRINGS = 2
+    NUMERIC_UNDERSCORES = 3
+    TRAILING_COMMA_IN_CALL = 4
+    TRAILING_COMMA_IN_DEF = 5
+    # The following two feature-flags are mutually exclusive, and exactly one should be
+    # set for every version of python.
+    ASYNC_IDENTIFIERS = 6
+    ASYNC_KEYWORDS = 7
+    ASSIGNMENT_EXPRESSIONS = 8
+    POS_ONLY_ARGUMENTS = 9
+    RELAXED_DECORATORS = 10
+    FORCE_OPTIONAL_PARENTHESES = 50
+
+
+VERSION_TO_FEATURES: Dict[TargetVersion, Set[Feature]] = {
+    TargetVersion.PY27: {Feature.ASYNC_IDENTIFIERS},
+    TargetVersion.PY33: {Feature.UNICODE_LITERALS, Feature.ASYNC_IDENTIFIERS},
+    TargetVersion.PY34: {Feature.UNICODE_LITERALS, Feature.ASYNC_IDENTIFIERS},
+    TargetVersion.PY35: {
+        Feature.UNICODE_LITERALS,
+        Feature.TRAILING_COMMA_IN_CALL,
+        Feature.ASYNC_IDENTIFIERS,
+    },
+    TargetVersion.PY36: {
+        Feature.UNICODE_LITERALS,
+        Feature.F_STRINGS,
+        Feature.NUMERIC_UNDERSCORES,
+        Feature.TRAILING_COMMA_IN_CALL,
+        Feature.TRAILING_COMMA_IN_DEF,
+        Feature.ASYNC_IDENTIFIERS,
+    },
+    TargetVersion.PY37: {
+        Feature.UNICODE_LITERALS,
+        Feature.F_STRINGS,
+        Feature.NUMERIC_UNDERSCORES,
+        Feature.TRAILING_COMMA_IN_CALL,
+        Feature.TRAILING_COMMA_IN_DEF,
+        Feature.ASYNC_KEYWORDS,
+    },
+    TargetVersion.PY38: {
+        Feature.UNICODE_LITERALS,
+        Feature.F_STRINGS,
+        Feature.NUMERIC_UNDERSCORES,
+        Feature.TRAILING_COMMA_IN_CALL,
+        Feature.TRAILING_COMMA_IN_DEF,
+        Feature.ASYNC_KEYWORDS,
+        Feature.ASSIGNMENT_EXPRESSIONS,
+        Feature.POS_ONLY_ARGUMENTS,
+    },
+    TargetVersion.PY39: {
+        Feature.UNICODE_LITERALS,
+        Feature.F_STRINGS,
+        Feature.NUMERIC_UNDERSCORES,
+        Feature.TRAILING_COMMA_IN_CALL,
+        Feature.TRAILING_COMMA_IN_DEF,
+        Feature.ASYNC_KEYWORDS,
+        Feature.ASSIGNMENT_EXPRESSIONS,
+        Feature.RELAXED_DECORATORS,
+        Feature.POS_ONLY_ARGUMENTS,
+    },
+}
+
+
+def supports_feature(target_versions: Set[TargetVersion], feature: Feature) -> bool:
+    return all(feature in VERSION_TO_FEATURES[version] for version in target_versions)
+
+
+@dataclass
+class Mode:
+    target_versions: Set[TargetVersion] = field(default_factory=set)
+    line_length: int = DEFAULT_LINE_LENGTH
+    string_normalization: bool = True
+    is_pyi: bool = False
+    magic_trailing_comma: bool = True
+    experimental_string_processing: bool = False
+
+    def get_cache_key(self) -> str:
+        if self.target_versions:
+            version_str = ",".join(
+                str(version.value)
+                for version in sorted(self.target_versions, key=lambda v: v.value)
+            )
+        else:
+            version_str = "-"
+        parts = [
+            version_str,
+            str(self.line_length),
+            str(int(self.string_normalization)),
+            str(int(self.is_pyi)),
+            str(int(self.magic_trailing_comma)),
+            str(int(self.experimental_string_processing)),
+        ]
+        return ".".join(parts)
diff --git a/src/black/nodes.py b/src/black/nodes.py
new file mode 100644
index 00000000000..e0db9a42426
--- /dev/null
+++ b/src/black/nodes.py
@@ -0,0 +1,843 @@
+"""
+blib2to3 Node/Leaf transformation-related utility functions.
+"""
+
+import sys
+from typing import (
+    Collection,
+    Generic,
+    Iterator,
+    List,
+    Optional,
+    Set,
+    Tuple,
+    TypeVar,
+    Union,
+)
+
+if sys.version_info < (3, 8):
+    from typing_extensions import Final
+else:
+    from typing import Final
+
+# lib2to3 fork
+from blib2to3.pytree import Node, Leaf, type_repr
+from blib2to3 import pygram
+from blib2to3.pgen2 import token
+
+from black.cache import CACHE_DIR
+from black.strings import has_triple_quotes
+
+
+pygram.initialize(CACHE_DIR)
+syms = pygram.python_symbols
+
+
+# types
+T = TypeVar("T")
+LN = Union[Leaf, Node]
+LeafID = int
+NodeType = int
+
+
+WHITESPACE: Final = {token.DEDENT, token.INDENT, token.NEWLINE}
+STATEMENT: Final = {
+    syms.if_stmt,
+    syms.while_stmt,
+    syms.for_stmt,
+    syms.try_stmt,
+    syms.except_clause,
+    syms.with_stmt,
+    syms.funcdef,
+    syms.classdef,
+}
+STANDALONE_COMMENT: Final = 153
+token.tok_name[STANDALONE_COMMENT] = "STANDALONE_COMMENT"
+LOGIC_OPERATORS: Final = {"and", "or"}
+COMPARATORS: Final = {
+    token.LESS,
+    token.GREATER,
+    token.EQEQUAL,
+    token.NOTEQUAL,
+    token.LESSEQUAL,
+    token.GREATEREQUAL,
+}
+MATH_OPERATORS: Final = {
+    token.VBAR,
+    token.CIRCUMFLEX,
+    token.AMPER,
+    token.LEFTSHIFT,
+    token.RIGHTSHIFT,
+    token.PLUS,
+    token.MINUS,
+    token.STAR,
+    token.SLASH,
+    token.DOUBLESLASH,
+    token.PERCENT,
+    token.AT,
+    token.TILDE,
+    token.DOUBLESTAR,
+}
+STARS: Final = {token.STAR, token.DOUBLESTAR}
+VARARGS_SPECIALS: Final = STARS | {token.SLASH}
+VARARGS_PARENTS: Final = {
+    syms.arglist,
+    syms.argument,  # double star in arglist
+    syms.trailer,  # single argument to call
+    syms.typedargslist,
+    syms.varargslist,  # lambdas
+}
+UNPACKING_PARENTS: Final = {
+    syms.atom,  # single element of a list or set literal
+    syms.dictsetmaker,
+    syms.listmaker,
+    syms.testlist_gexp,
+    syms.testlist_star_expr,
+}
+TEST_DESCENDANTS: Final = {
+    syms.test,
+    syms.lambdef,
+    syms.or_test,
+    syms.and_test,
+    syms.not_test,
+    syms.comparison,
+    syms.star_expr,
+    syms.expr,
+    syms.xor_expr,
+    syms.and_expr,
+    syms.shift_expr,
+    syms.arith_expr,
+    syms.trailer,
+    syms.term,
+    syms.power,
+}
+ASSIGNMENTS: Final = {
+    "=",
+    "+=",
+    "-=",
+    "*=",
+    "@=",
+    "/=",
+    "%=",
+    "&=",
+    "|=",
+    "^=",
+    "<<=",
+    ">>=",
+    "**=",
+    "//=",
+}
+
+IMPLICIT_TUPLE = {syms.testlist, syms.testlist_star_expr, syms.exprlist}
+BRACKET = {token.LPAR: token.RPAR, token.LSQB: token.RSQB, token.LBRACE: token.RBRACE}
+OPENING_BRACKETS = set(BRACKET.keys())
+CLOSING_BRACKETS = set(BRACKET.values())
+BRACKETS = OPENING_BRACKETS | CLOSING_BRACKETS
+ALWAYS_NO_SPACE = CLOSING_BRACKETS | {token.COMMA, STANDALONE_COMMENT}
+
+
+class Visitor(Generic[T]):
+    """Basic lib2to3 visitor that yields things of type `T` on `visit()`."""
+
+    def visit(self, node: LN) -> Iterator[T]:
+        """Main method to visit `node` and its children.
+
+        It tries to find a `visit_*()` method for the given `node.type`, like
+        `visit_simple_stmt` for Node objects or `visit_INDENT` for Leaf objects.
+        If no dedicated `visit_*()` method is found, chooses `visit_default()`
+        instead.
+
+        Then yields objects of type `T` from the selected visitor.
+        """
+        if node.type < 256:
+            name = token.tok_name[node.type]
+        else:
+            name = str(type_repr(node.type))
+        # We explicitly branch on whether a visitor exists (instead of
+        # using self.visit_default as the default arg to getattr) in order
+        # to save needing to create a bound method object and so mypyc can
+        # generate a native call to visit_default.
+        visitf = getattr(self, f"visit_{name}", None)
+        if visitf:
+            yield from visitf(node)
+        else:
+            yield from self.visit_default(node)
+
+    def visit_default(self, node: LN) -> Iterator[T]:
+        """Default `visit_*()` implementation. Recurses to children of `node`."""
+        if isinstance(node, Node):
+            for child in node.children:
+                yield from self.visit(child)
+
+
+def whitespace(leaf: Leaf, *, complex_subscript: bool) -> str:  # noqa: C901
+    """Return whitespace prefix if needed for the given `leaf`.
+
+    `complex_subscript` signals whether the given leaf is part of a subscription
+    which has non-trivial arguments, like arithmetic expressions or function calls.
+    """
+    NO = ""
+    SPACE = " "
+    DOUBLESPACE = "  "
+    t = leaf.type
+    p = leaf.parent
+    v = leaf.value
+    if t in ALWAYS_NO_SPACE:
+        return NO
+
+    if t == token.COMMENT:
+        return DOUBLESPACE
+
+    assert p is not None, f"INTERNAL ERROR: hand-made leaf without parent: {leaf!r}"
+    if t == token.COLON and p.type not in {
+        syms.subscript,
+        syms.subscriptlist,
+        syms.sliceop,
+    }:
+        return NO
+
+    prev = leaf.prev_sibling
+    if not prev:
+        prevp = preceding_leaf(p)
+        if not prevp or prevp.type in OPENING_BRACKETS:
+            return NO
+
+        if t == token.COLON:
+            if prevp.type == token.COLON:
+                return NO
+
+            elif prevp.type != token.COMMA and not complex_subscript:
+                return NO
+
+            return SPACE
+
+        if prevp.type == token.EQUAL:
+            if prevp.parent:
+                if prevp.parent.type in {
+                    syms.arglist,
+                    syms.argument,
+                    syms.parameters,
+                    syms.varargslist,
+                }:
+                    return NO
+
+                elif prevp.parent.type == syms.typedargslist:
+                    # A bit hacky: if the equal sign has whitespace, it means we
+                    # previously found it's a typed argument.  So, we're using
+                    # that, too.
+                    return prevp.prefix
+
+        elif prevp.type in VARARGS_SPECIALS:
+            if is_vararg(prevp, within=VARARGS_PARENTS | UNPACKING_PARENTS):
+                return NO
+
+        elif prevp.type == token.COLON:
+            if prevp.parent and prevp.parent.type in {syms.subscript, syms.sliceop}:
+                return SPACE if complex_subscript else NO
+
+        elif (
+            prevp.parent
+            and prevp.parent.type == syms.factor
+            and prevp.type in MATH_OPERATORS
+        ):
+            return NO
+
+        elif (
+            prevp.type == token.RIGHTSHIFT
+            and prevp.parent
+            and prevp.parent.type == syms.shift_expr
+            and prevp.prev_sibling
+            and prevp.prev_sibling.type == token.NAME
+            and prevp.prev_sibling.value == "print"  # type: ignore
+        ):
+            # Python 2 print chevron
+            return NO
+        elif prevp.type == token.AT and p.parent and p.parent.type == syms.decorator:
+            # no space in decorators
+            return NO
+
+    elif prev.type in OPENING_BRACKETS:
+        return NO
+
+    if p.type in {syms.parameters, syms.arglist}:
+        # untyped function signatures or calls
+        if not prev or prev.type != token.COMMA:
+            return NO
+
+    elif p.type == syms.varargslist:
+        # lambdas
+        if prev and prev.type != token.COMMA:
+            return NO
+
+    elif p.type == syms.typedargslist:
+        # typed function signatures
+        if not prev:
+            return NO
+
+        if t == token.EQUAL:
+            if prev.type != syms.tname:
+                return NO
+
+        elif prev.type == token.EQUAL:
+            # A bit hacky: if the equal sign has whitespace, it means we
+            # previously found it's a typed argument.  So, we're using that, too.
+            return prev.prefix
+
+        elif prev.type != token.COMMA:
+            return NO
+
+    elif p.type == syms.tname:
+        # type names
+        if not prev:
+            prevp = preceding_leaf(p)
+            if not prevp or prevp.type != token.COMMA:
+                return NO
+
+    elif p.type == syms.trailer:
+        # attributes and calls
+        if t == token.LPAR or t == token.RPAR:
+            return NO
+
+        if not prev:
+            if t == token.DOT:
+                prevp = preceding_leaf(p)
+                if not prevp or prevp.type != token.NUMBER:
+                    return NO
+
+            elif t == token.LSQB:
+                return NO
+
+        elif prev.type != token.COMMA:
+            return NO
+
+    elif p.type == syms.argument:
+        # single argument
+        if t == token.EQUAL:
+            return NO
+
+        if not prev:
+            prevp = preceding_leaf(p)
+            if not prevp or prevp.type == token.LPAR:
+                return NO
+
+        elif prev.type in {token.EQUAL} | VARARGS_SPECIALS:
+            return NO
+
+    elif p.type == syms.decorator:
+        # decorators
+        return NO
+
+    elif p.type == syms.dotted_name:
+        if prev:
+            return NO
+
+        prevp = preceding_leaf(p)
+        if not prevp or prevp.type == token.AT or prevp.type == token.DOT:
+            return NO
+
+    elif p.type == syms.classdef:
+        if t == token.LPAR:
+            return NO
+
+        if prev and prev.type == token.LPAR:
+            return NO
+
+    elif p.type in {syms.subscript, syms.sliceop}:
+        # indexing
+        if not prev:
+            assert p.parent is not None, "subscripts are always parented"
+            if p.parent.type == syms.subscriptlist:
+                return SPACE
+
+            return NO
+
+        elif not complex_subscript:
+            return NO
+
+    elif p.type == syms.atom:
+        if prev and t == token.DOT:
+            # dots, but not the first one.
+            return NO
+
+    elif p.type == syms.dictsetmaker:
+        # dict unpacking
+        if prev and prev.type == token.DOUBLESTAR:
+            return NO
+
+    elif p.type in {syms.factor, syms.star_expr}:
+        # unary ops
+        if not prev:
+            prevp = preceding_leaf(p)
+            if not prevp or prevp.type in OPENING_BRACKETS:
+                return NO
+
+            prevp_parent = prevp.parent
+            assert prevp_parent is not None
+            if prevp.type == token.COLON and prevp_parent.type in {
+                syms.subscript,
+                syms.sliceop,
+            }:
+                return NO
+
+            elif prevp.type == token.EQUAL and prevp_parent.type == syms.argument:
+                return NO
+
+        elif t in {token.NAME, token.NUMBER, token.STRING}:
+            return NO
+
+    elif p.type == syms.import_from:
+        if t == token.DOT:
+            if prev and prev.type == token.DOT:
+                return NO
+
+        elif t == token.NAME:
+            if v == "import":
+                return SPACE
+
+            if prev and prev.type == token.DOT:
+                return NO
+
+    elif p.type == syms.sliceop:
+        return NO
+
+    return SPACE
+
+
+def preceding_leaf(node: Optional[LN]) -> Optional[Leaf]:
+    """Return the first leaf that precedes `node`, if any."""
+    while node:
+        res = node.prev_sibling
+        if res:
+            if isinstance(res, Leaf):
+                return res
+
+            try:
+                return list(res.leaves())[-1]
+
+            except IndexError:
+                return None
+
+        node = node.parent
+    return None
+
+
+def prev_siblings_are(node: Optional[LN], tokens: List[Optional[NodeType]]) -> bool:
+    """Return if the `node` and its previous siblings match types against the provided
+    list of tokens; the provided `node`has its type matched against the last element in
+    the list.  `None` can be used as the first element to declare that the start of the
+    list is anchored at the start of its parent's children."""
+    if not tokens:
+        return True
+    if tokens[-1] is None:
+        return node is None
+    if not node:
+        return False
+    if node.type != tokens[-1]:
+        return False
+    return prev_siblings_are(node.prev_sibling, tokens[:-1])
+
+
+def last_two_except(leaves: List[Leaf], omit: Collection[LeafID]) -> Tuple[Leaf, Leaf]:
+    """Return (penultimate, last) leaves skipping brackets in `omit` and contents."""
+    stop_after = None
+    last = None
+    for leaf in reversed(leaves):
+        if stop_after:
+            if leaf is stop_after:
+                stop_after = None
+            continue
+
+        if last:
+            return leaf, last
+
+        if id(leaf) in omit:
+            stop_after = leaf.opening_bracket
+        else:
+            last = leaf
+    else:
+        raise LookupError("Last two leaves were also skipped")
+
+
+def parent_type(node: Optional[LN]) -> Optional[NodeType]:
+    """
+    Returns:
+        @node.parent.type, if @node is not None and has a parent.
+            OR
+        None, otherwise.
+    """
+    if node is None or node.parent is None:
+        return None
+
+    return node.parent.type
+
+
+def child_towards(ancestor: Node, descendant: LN) -> Optional[LN]:
+    """Return the child of `ancestor` that contains `descendant`."""
+    node: Optional[LN] = descendant
+    while node and node.parent != ancestor:
+        node = node.parent
+    return node
+
+
+def replace_child(old_child: LN, new_child: LN) -> None:
+    """
+    Side Effects:
+        * If @old_child.parent is set, replace @old_child with @new_child in
+        @old_child's underlying Node structure.
+            OR
+        * Otherwise, this function does nothing.
+    """
+    parent = old_child.parent
+    if not parent:
+        return
+
+    child_idx = old_child.remove()
+    if child_idx is not None:
+        parent.insert_child(child_idx, new_child)
+
+
+def container_of(leaf: Leaf) -> LN:
+    """Return `leaf` or one of its ancestors that is the topmost container of it.
+
+    By "container" we mean a node where `leaf` is the very first child.
+    """
+    same_prefix = leaf.prefix
+    container: LN = leaf
+    while container:
+        parent = container.parent
+        if parent is None:
+            break
+
+        if parent.children[0].prefix != same_prefix:
+            break
+
+        if parent.type == syms.file_input:
+            break
+
+        if parent.prev_sibling is not None and parent.prev_sibling.type in BRACKETS:
+            break
+
+        container = parent
+    return container
+
+
+def first_leaf_column(node: Node) -> Optional[int]:
+    """Returns the column of the first leaf child of a node."""
+    for child in node.children:
+        if isinstance(child, Leaf):
+            return child.column
+    return None
+
+
+def first_child_is_arith(node: Node) -> bool:
+    """Whether first child is an arithmetic or a binary arithmetic expression"""
+    expr_types = {
+        syms.arith_expr,
+        syms.shift_expr,
+        syms.xor_expr,
+        syms.and_expr,
+    }
+    return bool(node.children and node.children[0].type in expr_types)
+
+
+def is_docstring(leaf: Leaf) -> bool:
+    if prev_siblings_are(
+        leaf.parent, [None, token.NEWLINE, token.INDENT, syms.simple_stmt]
+    ):
+        return True
+
+    # Multiline docstring on the same line as the `def`.
+    if prev_siblings_are(leaf.parent, [syms.parameters, token.COLON, syms.simple_stmt]):
+        # `syms.parameters` is only used in funcdefs and async_funcdefs in the Python
+        # grammar. We're safe to return True without further checks.
+        return True
+
+    return False
+
+
+def is_empty_tuple(node: LN) -> bool:
+    """Return True if `node` holds an empty tuple."""
+    return (
+        node.type == syms.atom
+        and len(node.children) == 2
+        and node.children[0].type == token.LPAR
+        and node.children[1].type == token.RPAR
+    )
+
+
+def is_one_tuple(node: LN) -> bool:
+    """Return True if `node` holds a tuple with one element, with or without parens."""
+    if node.type == syms.atom:
+        gexp = unwrap_singleton_parenthesis(node)
+        if gexp is None or gexp.type != syms.testlist_gexp:
+            return False
+
+        return len(gexp.children) == 2 and gexp.children[1].type == token.COMMA
+
+    return (
+        node.type in IMPLICIT_TUPLE
+        and len(node.children) == 2
+        and node.children[1].type == token.COMMA
+    )
+
+
+def is_one_tuple_between(opening: Leaf, closing: Leaf, leaves: List[Leaf]) -> bool:
+    """Return True if content between `opening` and `closing` looks like a one-tuple."""
+    if opening.type != token.LPAR and closing.type != token.RPAR:
+        return False
+
+    depth = closing.bracket_depth + 1
+    for _opening_index, leaf in enumerate(leaves):
+        if leaf is opening:
+            break
+
+    else:
+        raise LookupError("Opening paren not found in `leaves`")
+
+    commas = 0
+    _opening_index += 1
+    for leaf in leaves[_opening_index:]:
+        if leaf is closing:
+            break
+
+        bracket_depth = leaf.bracket_depth
+        if bracket_depth == depth and leaf.type == token.COMMA:
+            commas += 1
+            if leaf.parent and leaf.parent.type in {
+                syms.arglist,
+                syms.typedargslist,
+            }:
+                commas += 1
+                break
+
+    return commas < 2
+
+
+def is_walrus_assignment(node: LN) -> bool:
+    """Return True iff `node` is of the shape ( test := test )"""
+    inner = unwrap_singleton_parenthesis(node)
+    return inner is not None and inner.type == syms.namedexpr_test
+
+
+def is_simple_decorator_trailer(node: LN, last: bool = False) -> bool:
+    """Return True iff `node` is a trailer valid in a simple decorator"""
+    return node.type == syms.trailer and (
+        (
+            len(node.children) == 2
+            and node.children[0].type == token.DOT
+            and node.children[1].type == token.NAME
+        )
+        # last trailer can be an argument-less parentheses pair
+        or (
+            last
+            and len(node.children) == 2
+            and node.children[0].type == token.LPAR
+            and node.children[1].type == token.RPAR
+        )
+        # last trailer can be arguments
+        or (
+            last
+            and len(node.children) == 3
+            and node.children[0].type == token.LPAR
+            # and node.children[1].type == syms.argument
+            and node.children[2].type == token.RPAR
+        )
+    )
+
+
+def is_simple_decorator_expression(node: LN) -> bool:
+    """Return True iff `node` could be a 'dotted name' decorator
+
+    This function takes the node of the 'namedexpr_test' of the new decorator
+    grammar and test if it would be valid under the old decorator grammar.
+
+    The old grammar was: decorator: @ dotted_name [arguments] NEWLINE
+    The new grammar is : decorator: @ namedexpr_test NEWLINE
+    """
+    if node.type == token.NAME:
+        return True
+    if node.type == syms.power:
+        if node.children:
+            return (
+                node.children[0].type == token.NAME
+                and all(map(is_simple_decorator_trailer, node.children[1:-1]))
+                and (
+                    len(node.children) < 2
+                    or is_simple_decorator_trailer(node.children[-1], last=True)
+                )
+            )
+    return False
+
+
+def is_yield(node: LN) -> bool:
+    """Return True if `node` holds a `yield` or `yield from` expression."""
+    if node.type == syms.yield_expr:
+        return True
+
+    if node.type == token.NAME and node.value == "yield":  # type: ignore
+        return True
+
+    if node.type != syms.atom:
+        return False
+
+    if len(node.children) != 3:
+        return False
+
+    lpar, expr, rpar = node.children
+    if lpar.type == token.LPAR and rpar.type == token.RPAR:
+        return is_yield(expr)
+
+    return False
+
+
+def is_vararg(leaf: Leaf, within: Set[NodeType]) -> bool:
+    """Return True if `leaf` is a star or double star in a vararg or kwarg.
+
+    If `within` includes VARARGS_PARENTS, this applies to function signatures.
+    If `within` includes UNPACKING_PARENTS, it applies to right hand-side
+    extended iterable unpacking (PEP 3132) and additional unpacking
+    generalizations (PEP 448).
+    """
+    if leaf.type not in VARARGS_SPECIALS or not leaf.parent:
+        return False
+
+    p = leaf.parent
+    if p.type == syms.star_expr:
+        # Star expressions are also used as assignment targets in extended
+        # iterable unpacking (PEP 3132).  See what its parent is instead.
+        if not p.parent:
+            return False
+
+        p = p.parent
+
+    return p.type in within
+
+
+def is_multiline_string(leaf: Leaf) -> bool:
+    """Return True if `leaf` is a multiline string that actually spans many lines."""
+    return has_triple_quotes(leaf.value) and "\n" in leaf.value
+
+
+def is_stub_suite(node: Node) -> bool:
+    """Return True if `node` is a suite with a stub body."""
+    if (
+        len(node.children) != 4
+        or node.children[0].type != token.NEWLINE
+        or node.children[1].type != token.INDENT
+        or node.children[3].type != token.DEDENT
+    ):
+        return False
+
+    return is_stub_body(node.children[2])
+
+
+def is_stub_body(node: LN) -> bool:
+    """Return True if `node` is a simple statement containing an ellipsis."""
+    if not isinstance(node, Node) or node.type != syms.simple_stmt:
+        return False
+
+    if len(node.children) != 2:
+        return False
+
+    child = node.children[0]
+    return (
+        child.type == syms.atom
+        and len(child.children) == 3
+        and all(leaf == Leaf(token.DOT, ".") for leaf in child.children)
+    )
+
+
+def is_atom_with_invisible_parens(node: LN) -> bool:
+    """Given a `LN`, determines whether it's an atom `node` with invisible
+    parens. Useful in dedupe-ing and normalizing parens.
+    """
+    if isinstance(node, Leaf) or node.type != syms.atom:
+        return False
+
+    first, last = node.children[0], node.children[-1]
+    return (
+        isinstance(first, Leaf)
+        and first.type == token.LPAR
+        and first.value == ""
+        and isinstance(last, Leaf)
+        and last.type == token.RPAR
+        and last.value == ""
+    )
+
+
+def is_empty_par(leaf: Leaf) -> bool:
+    return is_empty_lpar(leaf) or is_empty_rpar(leaf)
+
+
+def is_empty_lpar(leaf: Leaf) -> bool:
+    return leaf.type == token.LPAR and leaf.value == ""
+
+
+def is_empty_rpar(leaf: Leaf) -> bool:
+    return leaf.type == token.RPAR and leaf.value == ""
+
+
+def is_import(leaf: Leaf) -> bool:
+    """Return True if the given leaf starts an import statement."""
+    p = leaf.parent
+    t = leaf.type
+    v = leaf.value
+    return bool(
+        t == token.NAME
+        and (
+            (v == "import" and p and p.type == syms.import_name)
+            or (v == "from" and p and p.type == syms.import_from)
+        )
+    )
+
+
+def is_type_comment(leaf: Leaf, suffix: str = "") -> bool:
+    """Return True if the given leaf is a special comment.
+    Only returns true for type comments for now."""
+    t = leaf.type
+    v = leaf.value
+    return t in {token.COMMENT, STANDALONE_COMMENT} and v.startswith("# type:" + suffix)
+
+
+def wrap_in_parentheses(parent: Node, child: LN, *, visible: bool = True) -> None:
+    """Wrap `child` in parentheses.
+
+    This replaces `child` with an atom holding the parentheses and the old
+    child.  That requires moving the prefix.
+
+    If `visible` is False, the leaves will be valueless (and thus invisible).
+    """
+    lpar = Leaf(token.LPAR, "(" if visible else "")
+    rpar = Leaf(token.RPAR, ")" if visible else "")
+    prefix = child.prefix
+    child.prefix = ""
+    index = child.remove() or 0
+    new_child = Node(syms.atom, [lpar, child, rpar])
+    new_child.prefix = prefix
+    parent.insert_child(index, new_child)
+
+
+def unwrap_singleton_parenthesis(node: LN) -> Optional[LN]:
+    """Returns `wrapped` if `node` is of the shape ( wrapped ).
+
+    Parenthesis can be optional. Returns None otherwise"""
+    if len(node.children) != 3:
+        return None
+
+    lpar, wrapped, rpar = node.children
+    if not (lpar.type == token.LPAR and rpar.type == token.RPAR):
+        return None
+
+    return wrapped
+
+
+def ensure_visible(leaf: Leaf) -> None:
+    """Make sure parentheses are visible.
+
+    They could be invisible as part of some statements (see
+    :func:`normalize_invisible_parens` and :func:`visit_import_from`).
+    """
+    if leaf.type == token.LPAR:
+        leaf.value = "("
+    elif leaf.type == token.RPAR:
+        leaf.value = ")"
diff --git a/src/black/numerics.py b/src/black/numerics.py
new file mode 100644
index 00000000000..cb1c83e7b78
--- /dev/null
+++ b/src/black/numerics.py
@@ -0,0 +1,65 @@
+"""
+Formatting numeric literals.
+"""
+from blib2to3.pytree import Leaf
+
+
+def format_hex(text: str) -> str:
+    """
+    Formats a hexadecimal string like "0x12B3"
+    """
+    before, after = text[:2], text[2:]
+    return f"{before}{after.upper()}"
+
+
+def format_scientific_notation(text: str) -> str:
+    """Formats a numeric string utilizing scentific notation"""
+    before, after = text.split("e")
+    sign = ""
+    if after.startswith("-"):
+        after = after[1:]
+        sign = "-"
+    elif after.startswith("+"):
+        after = after[1:]
+    before = format_float_or_int_string(before)
+    return f"{before}e{sign}{after}"
+
+
+def format_long_or_complex_number(text: str) -> str:
+    """Formats a long or complex string like `10L` or `10j`"""
+    number = text[:-1]
+    suffix = text[-1]
+    # Capitalize in "2L" because "l" looks too similar to "1".
+    if suffix == "l":
+        suffix = "L"
+    return f"{format_float_or_int_string(number)}{suffix}"
+
+
+def format_float_or_int_string(text: str) -> str:
+    """Formats a float string like "1.0"."""
+    if "." not in text:
+        return text
+
+    before, after = text.split(".")
+    return f"{before or 0}.{after or 0}"
+
+
+def normalize_numeric_literal(leaf: Leaf) -> None:
+    """Normalizes numeric (float, int, and complex) literals.
+
+    All letters used in the representation are normalized to lowercase (except
+    in Python 2 long literals).
+    """
+    text = leaf.value.lower()
+    if text.startswith(("0o", "0b")):
+        # Leave octal and binary literals alone.
+        pass
+    elif text.startswith("0x"):
+        text = format_hex(text)
+    elif "e" in text:
+        text = format_scientific_notation(text)
+    elif text.endswith(("j", "l")):
+        text = format_long_or_complex_number(text)
+    else:
+        text = format_float_or_int_string(text)
+    leaf.value = text
diff --git a/src/black/output.py b/src/black/output.py
new file mode 100644
index 00000000000..6831524090d
--- /dev/null
+++ b/src/black/output.py
@@ -0,0 +1,83 @@
+"""Nice output for Black.
+
+The double calls are for patching purposes in tests.
+"""
+
+from typing import Any, Optional
+from mypy_extensions import mypyc_attr
+import tempfile
+
+from click import echo, style
+
+
+def _out(message: Optional[str] = None, nl: bool = True, **styles: Any) -> None:
+    if message is not None:
+        if "bold" not in styles:
+            styles["bold"] = True
+        message = style(message, **styles)
+    echo(message, nl=nl, err=True)
+
+
+def _err(message: Optional[str] = None, nl: bool = True, **styles: Any) -> None:
+    if message is not None:
+        if "fg" not in styles:
+            styles["fg"] = "red"
+        message = style(message, **styles)
+    echo(message, nl=nl, err=True)
+
+
+def out(message: Optional[str] = None, nl: bool = True, **styles: Any) -> None:
+    _out(message, nl=nl, **styles)
+
+
+def err(message: Optional[str] = None, nl: bool = True, **styles: Any) -> None:
+    _err(message, nl=nl, **styles)
+
+
+def diff(a: str, b: str, a_name: str, b_name: str) -> str:
+    """Return a unified diff string between strings `a` and `b`."""
+    import difflib
+
+    a_lines = [line for line in a.splitlines(keepends=True)]
+    b_lines = [line for line in b.splitlines(keepends=True)]
+    diff_lines = []
+    for line in difflib.unified_diff(
+        a_lines, b_lines, fromfile=a_name, tofile=b_name, n=5
+    ):
+        # Work around https://bugs.python.org/issue2142
+        # See https://www.gnu.org/software/diffutils/manual/html_node/Incomplete-Lines.html
+        if line[-1] == "\n":
+            diff_lines.append(line)
+        else:
+            diff_lines.append(line + "\n")
+            diff_lines.append("\\ No newline at end of file\n")
+    return "".join(diff_lines)
+
+
+def color_diff(contents: str) -> str:
+    """Inject the ANSI color codes to the diff."""
+    lines = contents.split("\n")
+    for i, line in enumerate(lines):
+        if line.startswith("+++") or line.startswith("---"):
+            line = "\033[1;37m" + line + "\033[0m"  # bold white, reset
+        elif line.startswith("@@"):
+            line = "\033[36m" + line + "\033[0m"  # cyan, reset
+        elif line.startswith("+"):
+            line = "\033[32m" + line + "\033[0m"  # green, reset
+        elif line.startswith("-"):
+            line = "\033[31m" + line + "\033[0m"  # red, reset
+        lines[i] = line
+    return "\n".join(lines)
+
+
+@mypyc_attr(patchable=True)
+def dump_to_file(*output: str, ensure_final_newline: bool = True) -> str:
+    """Dump `output` to a temporary file. Return path to the file."""
+    with tempfile.NamedTemporaryFile(
+        mode="w", prefix="blk_", suffix=".log", delete=False, encoding="utf8"
+    ) as f:
+        for lines in output:
+            f.write(lines)
+            if ensure_final_newline and lines and lines[-1] != "\n":
+                f.write("\n")
+    return f.name
diff --git a/src/black/parsing.py b/src/black/parsing.py
new file mode 100644
index 00000000000..8e9feea9120
--- /dev/null
+++ b/src/black/parsing.py
@@ -0,0 +1,215 @@
+"""
+Parse Python code and perform AST validation.
+"""
+import ast
+import sys
+from typing import Iterable, Iterator, List, Set, Union
+
+# lib2to3 fork
+from blib2to3.pytree import Node, Leaf
+from blib2to3 import pygram, pytree
+from blib2to3.pgen2 import driver
+from blib2to3.pgen2.grammar import Grammar
+from blib2to3.pgen2.parse import ParseError
+
+from black.mode import TargetVersion, Feature, supports_feature
+from black.nodes import syms
+
+try:
+    from typed_ast import ast3, ast27
+except ImportError:
+    if sys.version_info < (3, 8):
+        print(
+            "The typed_ast package is required but not installed.\n"
+            "You can upgrade to Python 3.8+ or install typed_ast with\n"
+            "`python3 -m pip install typed-ast`.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    else:
+        ast3 = ast27 = ast
+
+
+class InvalidInput(ValueError):
+    """Raised when input source code fails all parse attempts."""
+
+
+def get_grammars(target_versions: Set[TargetVersion]) -> List[Grammar]:
+    if not target_versions:
+        # No target_version specified, so try all grammars.
+        return [
+            # Python 3.7+
+            pygram.python_grammar_no_print_statement_no_exec_statement_async_keywords,
+            # Python 3.0-3.6
+            pygram.python_grammar_no_print_statement_no_exec_statement,
+            # Python 2.7 with future print_function import
+            pygram.python_grammar_no_print_statement,
+            # Python 2.7
+            pygram.python_grammar,
+        ]
+
+    if all(version.is_python2() for version in target_versions):
+        # Python 2-only code, so try Python 2 grammars.
+        return [
+            # Python 2.7 with future print_function import
+            pygram.python_grammar_no_print_statement,
+            # Python 2.7
+            pygram.python_grammar,
+        ]
+
+    # Python 3-compatible code, so only try Python 3 grammar.
+    grammars = []
+    # If we have to parse both, try to parse async as a keyword first
+    if not supports_feature(target_versions, Feature.ASYNC_IDENTIFIERS):
+        # Python 3.7+
+        grammars.append(
+            pygram.python_grammar_no_print_statement_no_exec_statement_async_keywords
+        )
+    if not supports_feature(target_versions, Feature.ASYNC_KEYWORDS):
+        # Python 3.0-3.6
+        grammars.append(pygram.python_grammar_no_print_statement_no_exec_statement)
+    # At least one of the above branches must have been taken, because every Python
+    # version has exactly one of the two 'ASYNC_*' flags
+    return grammars
+
+
+def lib2to3_parse(src_txt: str, target_versions: Iterable[TargetVersion] = ()) -> Node:
+    """Given a string with source, return the lib2to3 Node."""
+    if not src_txt.endswith("\n"):
+        src_txt += "\n"
+
+    for grammar in get_grammars(set(target_versions)):
+        drv = driver.Driver(grammar, pytree.convert)
+        try:
+            result = drv.parse_string(src_txt, True)
+            break
+
+        except ParseError as pe:
+            lineno, column = pe.context[1]
+            lines = src_txt.splitlines()
+            try:
+                faulty_line = lines[lineno - 1]
+            except IndexError:
+                faulty_line = "<line number missing in source>"
+            exc = InvalidInput(f"Cannot parse: {lineno}:{column}: {faulty_line}")
+    else:
+        raise exc from None
+
+    if isinstance(result, Leaf):
+        result = Node(syms.file_input, [result])
+    return result
+
+
+def lib2to3_unparse(node: Node) -> str:
+    """Given a lib2to3 node, return its string representation."""
+    code = str(node)
+    return code
+
+
+def parse_ast(src: str) -> Union[ast.AST, ast3.AST, ast27.AST]:
+    filename = "<unknown>"
+    if sys.version_info >= (3, 8):
+        # TODO: support Python 4+ ;)
+        for minor_version in range(sys.version_info[1], 4, -1):
+            try:
+                return ast.parse(src, filename, feature_version=(3, minor_version))
+            except SyntaxError:
+                continue
+    else:
+        for feature_version in (7, 6):
+            try:
+                return ast3.parse(src, filename, feature_version=feature_version)
+            except SyntaxError:
+                continue
+    if ast27.__name__ == "ast":
+        raise SyntaxError(
+            "The requested source code has invalid Python 3 syntax.\n"
+            "If you are trying to format Python 2 files please reinstall Black"
+            " with the 'python2' extra: `python3 -m pip install black[python2]`."
+        )
+    return ast27.parse(src)
+
+
+def stringify_ast(
+    node: Union[ast.AST, ast3.AST, ast27.AST], depth: int = 0
+) -> Iterator[str]:
+    """Simple visitor generating strings to compare ASTs by content."""
+
+    node = fixup_ast_constants(node)
+
+    yield f"{'  ' * depth}{node.__class__.__name__}("
+
+    for field in sorted(node._fields):  # noqa: F402
+        # TypeIgnore has only one field 'lineno' which breaks this comparison
+        type_ignore_classes = (ast3.TypeIgnore, ast27.TypeIgnore)
+        if sys.version_info >= (3, 8):
+            type_ignore_classes += (ast.TypeIgnore,)
+        if isinstance(node, type_ignore_classes):
+            break
+
+        try:
+            value = getattr(node, field)
+        except AttributeError:
+            continue
+
+        yield f"{'  ' * (depth+1)}{field}="
+
+        if isinstance(value, list):
+            for item in value:
+                # Ignore nested tuples within del statements, because we may insert
+                # parentheses and they change the AST.
+                if (
+                    field == "targets"
+                    and isinstance(node, (ast.Delete, ast3.Delete, ast27.Delete))
+                    and isinstance(item, (ast.Tuple, ast3.Tuple, ast27.Tuple))
+                ):
+                    for item in item.elts:
+                        yield from stringify_ast(item, depth + 2)
+
+                elif isinstance(item, (ast.AST, ast3.AST, ast27.AST)):
+                    yield from stringify_ast(item, depth + 2)
+
+        elif isinstance(value, (ast.AST, ast3.AST, ast27.AST)):
+            yield from stringify_ast(value, depth + 2)
+
+        else:
+            # Constant strings may be indented across newlines, if they are
+            # docstrings; fold spaces after newlines when comparing. Similarly,
+            # trailing and leading space may be removed.
+            # Note that when formatting Python 2 code, at least with Windows
+            # line-endings, docstrings can end up here as bytes instead of
+            # str so make sure that we handle both cases.
+            if (
+                isinstance(node, ast.Constant)
+                and field == "value"
+                and isinstance(value, (str, bytes))
+            ):
+                lineend = "\n" if isinstance(value, str) else b"\n"
+                # To normalize, we strip any leading and trailing space from
+                # each line...
+                stripped = [line.strip() for line in value.splitlines()]
+                normalized = lineend.join(stripped)  # type: ignore[attr-defined]
+                # ...and remove any blank lines at the beginning and end of
+                # the whole string
+                normalized = normalized.strip()
+            else:
+                normalized = value
+            yield f"{'  ' * (depth+2)}{normalized!r},  # {value.__class__.__name__}"
+
+    yield f"{'  ' * depth})  # /{node.__class__.__name__}"
+
+
+def fixup_ast_constants(
+    node: Union[ast.AST, ast3.AST, ast27.AST]
+) -> Union[ast.AST, ast3.AST, ast27.AST]:
+    """Map ast nodes deprecated in 3.8 to Constant."""
+    if isinstance(node, (ast.Str, ast3.Str, ast27.Str, ast.Bytes, ast3.Bytes)):
+        return ast.Constant(value=node.s)
+
+    if isinstance(node, (ast.Num, ast3.Num, ast27.Num)):
+        return ast.Constant(value=node.n)
+
+    if isinstance(node, (ast.NameConstant, ast3.NameConstant)):
+        return ast.Constant(value=node.value)
+
+    return node
diff --git a/src/black/report.py b/src/black/report.py
new file mode 100644
index 00000000000..8fc5da2e167
--- /dev/null
+++ b/src/black/report.py
@@ -0,0 +1,100 @@
+"""
+Summarize Black runs to users.
+"""
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+
+from click import style
+
+from black.output import out, err
+
+
+class Changed(Enum):
+    NO = 0
+    CACHED = 1
+    YES = 2
+
+
+@dataclass
+class Report:
+    """Provides a reformatting counter. Can be rendered with `str(report)`."""
+
+    check: bool = False
+    diff: bool = False
+    quiet: bool = False
+    verbose: bool = False
+    change_count: int = 0
+    same_count: int = 0
+    failure_count: int = 0
+
+    def done(self, src: Path, changed: Changed) -> None:
+        """Increment the counter for successful reformatting. Write out a message."""
+        if changed is Changed.YES:
+            reformatted = "would reformat" if self.check or self.diff else "reformatted"
+            if self.verbose or not self.quiet:
+                out(f"{reformatted} {src}")
+            self.change_count += 1
+        else:
+            if self.verbose:
+                if changed is Changed.NO:
+                    msg = f"{src} already well formatted, good job."
+                else:
+                    msg = f"{src} wasn't modified on disk since last run."
+                out(msg, bold=False)
+            self.same_count += 1
+
+    def failed(self, src: Path, message: str) -> None:
+        """Increment the counter for failed reformatting. Write out a message."""
+        err(f"error: cannot format {src}: {message}")
+        self.failure_count += 1
+
+    def path_ignored(self, path: Path, message: str) -> None:
+        if self.verbose:
+            out(f"{path} ignored: {message}", bold=False)
+
+    @property
+    def return_code(self) -> int:
+        """Return the exit code that the app should use.
+
+        This considers the current state of changed files and failures:
+        - if there were any failures, return 123;
+        - if any files were changed and --check is being used, return 1;
+        - otherwise return 0.
+        """
+        # According to http://tldp.org/LDP/abs/html/exitcodes.html starting with
+        # 126 we have special return codes reserved by the shell.
+        if self.failure_count:
+            return 123
+
+        elif self.change_count and self.check:
+            return 1
+
+        return 0
+
+    def __str__(self) -> str:
+        """Render a color report of the current state.
+
+        Use `click.unstyle` to remove colors.
+        """
+        if self.check or self.diff:
+            reformatted = "would be reformatted"
+            unchanged = "would be left unchanged"
+            failed = "would fail to reformat"
+        else:
+            reformatted = "reformatted"
+            unchanged = "left unchanged"
+            failed = "failed to reformat"
+        report = []
+        if self.change_count:
+            s = "s" if self.change_count > 1 else ""
+            report.append(
+                style(f"{self.change_count} file{s} {reformatted}", bold=True)
+            )
+        if self.same_count:
+            s = "s" if self.same_count > 1 else ""
+            report.append(f"{self.same_count} file{s} {unchanged}")
+        if self.failure_count:
+            s = "s" if self.failure_count > 1 else ""
+            report.append(style(f"{self.failure_count} file{s} {failed}", fg="red"))
+        return ", ".join(report) + "."
diff --git a/src/black/rusty.py b/src/black/rusty.py
new file mode 100644
index 00000000000..822e3d7858a
--- /dev/null
+++ b/src/black/rusty.py
@@ -0,0 +1,28 @@
+"""An error-handling model influenced by that used by the Rust programming language
+
+See https://doc.rust-lang.org/book/ch09-00-error-handling.html.
+"""
+from typing import Generic, TypeVar, Union
+
+
+T = TypeVar("T")
+E = TypeVar("E", bound=Exception)
+
+
+class Ok(Generic[T]):
+    def __init__(self, value: T) -> None:
+        self._value = value
+
+    def ok(self) -> T:
+        return self._value
+
+
+class Err(Generic[E]):
+    def __init__(self, e: E) -> None:
+        self._e = e
+
+    def err(self) -> E:
+        return self._e
+
+
+Result = Union[Ok[T], Err[E]]
diff --git a/src/black/strings.py b/src/black/strings.py
new file mode 100644
index 00000000000..5b443ddebc9
--- /dev/null
+++ b/src/black/strings.py
@@ -0,0 +1,216 @@
+"""
+Simple formatting on strings. Further string formatting code is in trans.py.
+"""
+
+import regex as re
+import sys
+from typing import List, Pattern
+
+
+STRING_PREFIX_CHARS = "furbFURB"  # All possible string prefix characters.
+
+
+def sub_twice(regex: Pattern[str], replacement: str, original: str) -> str:
+    """Replace `regex` with `replacement` twice on `original`.
+
+    This is used by string normalization to perform replaces on
+    overlapping matches.
+    """
+    return regex.sub(replacement, regex.sub(replacement, original))
+
+
+def has_triple_quotes(string: str) -> bool:
+    """
+    Returns:
+        True iff @string starts with three quotation characters.
+    """
+    raw_string = string.lstrip(STRING_PREFIX_CHARS)
+    return raw_string[:3] in {'"""', "'''"}
+
+
+def lines_with_leading_tabs_expanded(s: str) -> List[str]:
+    """
+    Splits string into lines and expands only leading tabs (following the normal
+    Python rules)
+    """
+    lines = []
+    for line in s.splitlines():
+        # Find the index of the first non-whitespace character after a string of
+        # whitespace that includes at least one tab
+        match = re.match(r"\s*\t+\s*(\S)", line)
+        if match:
+            first_non_whitespace_idx = match.start(1)
+
+            lines.append(
+                line[:first_non_whitespace_idx].expandtabs()
+                + line[first_non_whitespace_idx:]
+            )
+        else:
+            lines.append(line)
+    return lines
+
+
+def fix_docstring(docstring: str, prefix: str) -> str:
+    # https://www.python.org/dev/peps/pep-0257/#handling-docstring-indentation
+    if not docstring:
+        return ""
+    lines = lines_with_leading_tabs_expanded(docstring)
+    # Determine minimum indentation (first line doesn't count):
+    indent = sys.maxsize
+    for line in lines[1:]:
+        stripped = line.lstrip()
+        if stripped:
+            indent = min(indent, len(line) - len(stripped))
+    # Remove indentation (first line is special):
+    trimmed = [lines[0].strip()]
+    if indent < sys.maxsize:
+        last_line_idx = len(lines) - 2
+        for i, line in enumerate(lines[1:]):
+            stripped_line = line[indent:].rstrip()
+            if stripped_line or i == last_line_idx:
+                trimmed.append(prefix + stripped_line)
+            else:
+                trimmed.append("")
+    return "\n".join(trimmed)
+
+
+def get_string_prefix(string: str) -> str:
+    """
+    Pre-conditions:
+        * assert_is_leaf_string(@string)
+
+    Returns:
+        @string's prefix (e.g. '', 'r', 'f', or 'rf').
+    """
+    assert_is_leaf_string(string)
+
+    prefix = ""
+    prefix_idx = 0
+    while string[prefix_idx] in STRING_PREFIX_CHARS:
+        prefix += string[prefix_idx].lower()
+        prefix_idx += 1
+
+    return prefix
+
+
+def assert_is_leaf_string(string: str) -> None:
+    """
+    Checks the pre-condition that @string has the format that you would expect
+    of `leaf.value` where `leaf` is some Leaf such that `leaf.type ==
+    token.STRING`. A more precise description of the pre-conditions that are
+    checked are listed below.
+
+    Pre-conditions:
+        * @string starts with either ', ", <prefix>', or <prefix>" where
+        `set(<prefix>)` is some subset of `set(STRING_PREFIX_CHARS)`.
+        * @string ends with a quote character (' or ").
+
+    Raises:
+        AssertionError(...) if the pre-conditions listed above are not
+        satisfied.
+    """
+    dquote_idx = string.find('"')
+    squote_idx = string.find("'")
+    if -1 in [dquote_idx, squote_idx]:
+        quote_idx = max(dquote_idx, squote_idx)
+    else:
+        quote_idx = min(squote_idx, dquote_idx)
+
+    assert (
+        0 <= quote_idx < len(string) - 1
+    ), f"{string!r} is missing a starting quote character (' or \")."
+    assert string[-1] in (
+        "'",
+        '"',
+    ), f"{string!r} is missing an ending quote character (' or \")."
+    assert set(string[:quote_idx]).issubset(
+        set(STRING_PREFIX_CHARS)
+    ), f"{set(string[:quote_idx])} is NOT a subset of {set(STRING_PREFIX_CHARS)}."
+
+
+def normalize_string_prefix(s: str, remove_u_prefix: bool = False) -> str:
+    """Make all string prefixes lowercase.
+
+    If remove_u_prefix is given, also removes any u prefix from the string.
+    """
+    match = re.match(r"^([" + STRING_PREFIX_CHARS + r"]*)(.*)$", s, re.DOTALL)
+    assert match is not None, f"failed to match string {s!r}"
+    orig_prefix = match.group(1)
+    new_prefix = orig_prefix.replace("F", "f").replace("B", "b").replace("U", "u")
+    if remove_u_prefix:
+        new_prefix = new_prefix.replace("u", "")
+    return f"{new_prefix}{match.group(2)}"
+
+
+def normalize_string_quotes(s: str) -> str:
+    """Prefer double quotes but only if it doesn't cause more escaping.
+
+    Adds or removes backslashes as appropriate. Doesn't parse and fix
+    strings nested in f-strings.
+    """
+    value = s.lstrip(STRING_PREFIX_CHARS)
+    if value[:3] == '"""':
+        return s
+
+    elif value[:3] == "'''":
+        orig_quote = "'''"
+        new_quote = '"""'
+    elif value[0] == '"':
+        orig_quote = '"'
+        new_quote = "'"
+    else:
+        orig_quote = "'"
+        new_quote = '"'
+    first_quote_pos = s.find(orig_quote)
+    if first_quote_pos == -1:
+        return s  # There's an internal error
+
+    prefix = s[:first_quote_pos]
+    unescaped_new_quote = re.compile(rf"(([^\\]|^)(\\\\)*){new_quote}")
+    escaped_new_quote = re.compile(rf"([^\\]|^)\\((?:\\\\)*){new_quote}")
+    escaped_orig_quote = re.compile(rf"([^\\]|^)\\((?:\\\\)*){orig_quote}")
+    body = s[first_quote_pos + len(orig_quote) : -len(orig_quote)]
+    if "r" in prefix.casefold():
+        if unescaped_new_quote.search(body):
+            # There's at least one unescaped new_quote in this raw string
+            # so converting is impossible
+            return s
+
+        # Do not introduce or remove backslashes in raw strings
+        new_body = body
+    else:
+        # remove unnecessary escapes
+        new_body = sub_twice(escaped_new_quote, rf"\1\2{new_quote}", body)
+        if body != new_body:
+            # Consider the string without unnecessary escapes as the original
+            body = new_body
+            s = f"{prefix}{orig_quote}{body}{orig_quote}"
+        new_body = sub_twice(escaped_orig_quote, rf"\1\2{orig_quote}", new_body)
+        new_body = sub_twice(unescaped_new_quote, rf"\1\\{new_quote}", new_body)
+    if "f" in prefix.casefold():
+        matches = re.findall(
+            r"""
+            (?:[^{]|^)\{  # start of the string or a non-{ followed by a single {
+                ([^{].*?)  # contents of the brackets except if begins with {{
+            \}(?:[^}]|$)  # A } followed by end of the string or a non-}
+            """,
+            new_body,
+            re.VERBOSE,
+        )
+        for m in matches:
+            if "\\" in str(m):
+                # Do not introduce backslashes in interpolated expressions
+                return s
+
+    if new_quote == '"""' and new_body[-1:] == '"':
+        # edge case:
+        new_body = new_body[:-1] + '\\"'
+    orig_escape_count = body.count("\\")
+    new_escape_count = new_body.count("\\")
+    if new_escape_count > orig_escape_count:
+        return s  # Do not introduce more escaping
+
+    if new_escape_count == orig_escape_count and orig_quote == '"':
+        return s  # Prefer double quotes
+
+    return f"{prefix}{new_quote}{new_body}{new_quote}"
diff --git a/src/black/trans.py b/src/black/trans.py
new file mode 100644
index 00000000000..055f33c0ee2
--- /dev/null
+++ b/src/black/trans.py
@@ -0,0 +1,1925 @@
+"""
+String transformers that can split and merge strings.
+"""
+from abc import ABC, abstractmethod
+from collections import defaultdict
+from dataclasses import dataclass
+import regex as re
+from typing import (
+    Any,
+    Callable,
+    Collection,
+    Dict,
+    Iterable,
+    Iterator,
+    List,
+    Optional,
+    Sequence,
+    Tuple,
+    TypeVar,
+    Union,
+)
+
+from black.rusty import Result, Ok, Err
+
+from black.mode import Feature
+from black.nodes import syms, replace_child, parent_type
+from black.nodes import is_empty_par, is_empty_lpar, is_empty_rpar
+from black.nodes import CLOSING_BRACKETS, STANDALONE_COMMENT
+from black.lines import Line, append_leaves
+from black.brackets import BracketMatchError
+from black.comments import contains_pragma_comment
+from black.strings import has_triple_quotes, get_string_prefix, assert_is_leaf_string
+from black.strings import normalize_string_quotes
+
+from blib2to3.pytree import Leaf, Node
+from blib2to3.pgen2 import token
+
+
+class CannotTransform(Exception):
+    """Base class for errors raised by Transformers."""
+
+
+# types
+T = TypeVar("T")
+LN = Union[Leaf, Node]
+Transformer = Callable[[Line, Collection[Feature]], Iterator[Line]]
+Index = int
+NodeType = int
+ParserState = int
+StringID = int
+TResult = Result[T, CannotTransform]  # (T)ransform Result
+TMatchResult = TResult[Index]
+
+
+def TErr(err_msg: str) -> Err[CannotTransform]:
+    """(T)ransform Err
+
+    Convenience function used when working with the TResult type.
+    """
+    cant_transform = CannotTransform(err_msg)
+    return Err(cant_transform)
+
+
+@dataclass  # type: ignore
+class StringTransformer(ABC):
+    """
+    An implementation of the Transformer protocol that relies on its
+    subclasses overriding the template methods `do_match(...)` and
+    `do_transform(...)`.
+
+    This Transformer works exclusively on strings (for example, by merging
+    or splitting them).
+
+    The following sections can be found among the docstrings of each concrete
+    StringTransformer subclass.
+
+    Requirements:
+        Which requirements must be met of the given Line for this
+        StringTransformer to be applied?
+
+    Transformations:
+        If the given Line meets all of the above requirements, which string
+        transformations can you expect to be applied to it by this
+        StringTransformer?
+
+    Collaborations:
+        What contractual agreements does this StringTransformer have with other
+        StringTransfomers? Such collaborations should be eliminated/minimized
+        as much as possible.
+    """
+
+    line_length: int
+    normalize_strings: bool
+    __name__ = "StringTransformer"
+
+    @abstractmethod
+    def do_match(self, line: Line) -> TMatchResult:
+        """
+        Returns:
+            * Ok(string_idx) such that `line.leaves[string_idx]` is our target
+            string, if a match was able to be made.
+                OR
+            * Err(CannotTransform), if a match was not able to be made.
+        """
+
+    @abstractmethod
+    def do_transform(self, line: Line, string_idx: int) -> Iterator[TResult[Line]]:
+        """
+        Yields:
+            * Ok(new_line) where new_line is the new transformed line.
+                OR
+            * Err(CannotTransform) if the transformation failed for some reason. The
+            `do_match(...)` template method should usually be used to reject
+            the form of the given Line, but in some cases it is difficult to
+            know whether or not a Line meets the StringTransformer's
+            requirements until the transformation is already midway.
+
+        Side Effects:
+            This method should NOT mutate @line directly, but it MAY mutate the
+            Line's underlying Node structure. (WARNING: If the underlying Node
+            structure IS altered, then this method should NOT be allowed to
+            yield an CannotTransform after that point.)
+        """
+
+    def __call__(self, line: Line, _features: Collection[Feature]) -> Iterator[Line]:
+        """
+        StringTransformer instances have a call signature that mirrors that of
+        the Transformer type.
+
+        Raises:
+            CannotTransform(...) if the concrete StringTransformer class is unable
+            to transform @line.
+        """
+        # Optimization to avoid calling `self.do_match(...)` when the line does
+        # not contain any string.
+        if not any(leaf.type == token.STRING for leaf in line.leaves):
+            raise CannotTransform("There are no strings in this line.")
+
+        match_result = self.do_match(line)
+
+        if isinstance(match_result, Err):
+            cant_transform = match_result.err()
+            raise CannotTransform(
+                f"The string transformer {self.__class__.__name__} does not recognize"
+                " this line as one that it can transform."
+            ) from cant_transform
+
+        string_idx = match_result.ok()
+
+        for line_result in self.do_transform(line, string_idx):
+            if isinstance(line_result, Err):
+                cant_transform = line_result.err()
+                raise CannotTransform(
+                    "StringTransformer failed while attempting to transform string."
+                ) from cant_transform
+            line = line_result.ok()
+            yield line
+
+
+@dataclass
+class CustomSplit:
+    """A custom (i.e. manual) string split.
+
+    A single CustomSplit instance represents a single substring.
+
+    Examples:
+        Consider the following string:
+        ```
+        "Hi there friend."
+        " This is a custom"
+        f" string {split}."
+        ```
+
+        This string will correspond to the following three CustomSplit instances:
+        ```
+        CustomSplit(False, 16)
+        CustomSplit(False, 17)
+        CustomSplit(True, 16)
+        ```
+    """
+
+    has_prefix: bool
+    break_idx: int
+
+
+class CustomSplitMapMixin:
+    """
+    This mixin class is used to map merged strings to a sequence of
+    CustomSplits, which will then be used to re-split the strings iff none of
+    the resultant substrings go over the configured max line length.
+    """
+
+    _Key = Tuple[StringID, str]
+    _CUSTOM_SPLIT_MAP: Dict[_Key, Tuple[CustomSplit, ...]] = defaultdict(tuple)
+
+    @staticmethod
+    def _get_key(string: str) -> "CustomSplitMapMixin._Key":
+        """
+        Returns:
+            A unique identifier that is used internally to map @string to a
+            group of custom splits.
+        """
+        return (id(string), string)
+
+    def add_custom_splits(
+        self, string: str, custom_splits: Iterable[CustomSplit]
+    ) -> None:
+        """Custom Split Map Setter Method
+
+        Side Effects:
+            Adds a mapping from @string to the custom splits @custom_splits.
+        """
+        key = self._get_key(string)
+        self._CUSTOM_SPLIT_MAP[key] = tuple(custom_splits)
+
+    def pop_custom_splits(self, string: str) -> List[CustomSplit]:
+        """Custom Split Map Getter Method
+
+        Returns:
+            * A list of the custom splits that are mapped to @string, if any
+            exist.
+                OR
+            * [], otherwise.
+
+        Side Effects:
+            Deletes the mapping between @string and its associated custom
+            splits (which are returned to the caller).
+        """
+        key = self._get_key(string)
+
+        custom_splits = self._CUSTOM_SPLIT_MAP[key]
+        del self._CUSTOM_SPLIT_MAP[key]
+
+        return list(custom_splits)
+
+    def has_custom_splits(self, string: str) -> bool:
+        """
+        Returns:
+            True iff @string is associated with a set of custom splits.
+        """
+        key = self._get_key(string)
+        return key in self._CUSTOM_SPLIT_MAP
+
+
+class StringMerger(CustomSplitMapMixin, StringTransformer):
+    """StringTransformer that merges strings together.
+
+    Requirements:
+        (A) The line contains adjacent strings such that ALL of the validation checks
+        listed in StringMerger.__validate_msg(...)'s docstring pass.
+            OR
+        (B) The line contains a string which uses line continuation backslashes.
+
+    Transformations:
+        Depending on which of the two requirements above where met, either:
+
+        (A) The string group associated with the target string is merged.
+            OR
+        (B) All line-continuation backslashes are removed from the target string.
+
+    Collaborations:
+        StringMerger provides custom split information to StringSplitter.
+    """
+
+    def do_match(self, line: Line) -> TMatchResult:
+        LL = line.leaves
+
+        is_valid_index = is_valid_index_factory(LL)
+
+        for (i, leaf) in enumerate(LL):
+            if (
+                leaf.type == token.STRING
+                and is_valid_index(i + 1)
+                and LL[i + 1].type == token.STRING
+            ):
+                return Ok(i)
+
+            if leaf.type == token.STRING and "\\\n" in leaf.value:
+                return Ok(i)
+
+        return TErr("This line has no strings that need merging.")
+
+    def do_transform(self, line: Line, string_idx: int) -> Iterator[TResult[Line]]:
+        new_line = line
+        rblc_result = self._remove_backslash_line_continuation_chars(
+            new_line, string_idx
+        )
+        if isinstance(rblc_result, Ok):
+            new_line = rblc_result.ok()
+
+        msg_result = self._merge_string_group(new_line, string_idx)
+        if isinstance(msg_result, Ok):
+            new_line = msg_result.ok()
+
+        if isinstance(rblc_result, Err) and isinstance(msg_result, Err):
+            msg_cant_transform = msg_result.err()
+            rblc_cant_transform = rblc_result.err()
+            cant_transform = CannotTransform(
+                "StringMerger failed to merge any strings in this line."
+            )
+
+            # Chain the errors together using `__cause__`.
+            msg_cant_transform.__cause__ = rblc_cant_transform
+            cant_transform.__cause__ = msg_cant_transform
+
+            yield Err(cant_transform)
+        else:
+            yield Ok(new_line)
+
+    @staticmethod
+    def _remove_backslash_line_continuation_chars(
+        line: Line, string_idx: int
+    ) -> TResult[Line]:
+        """
+        Merge strings that were split across multiple lines using
+        line-continuation backslashes.
+
+        Returns:
+            Ok(new_line), if @line contains backslash line-continuation
+            characters.
+                OR
+            Err(CannotTransform), otherwise.
+        """
+        LL = line.leaves
+
+        string_leaf = LL[string_idx]
+        if not (
+            string_leaf.type == token.STRING
+            and "\\\n" in string_leaf.value
+            and not has_triple_quotes(string_leaf.value)
+        ):
+            return TErr(
+                f"String leaf {string_leaf} does not contain any backslash line"
+                " continuation characters."
+            )
+
+        new_line = line.clone()
+        new_line.comments = line.comments.copy()
+        append_leaves(new_line, line, LL)
+
+        new_string_leaf = new_line.leaves[string_idx]
+        new_string_leaf.value = new_string_leaf.value.replace("\\\n", "")
+
+        return Ok(new_line)
+
+    def _merge_string_group(self, line: Line, string_idx: int) -> TResult[Line]:
+        """
+        Merges string group (i.e. set of adjacent strings) where the first
+        string in the group is `line.leaves[string_idx]`.
+
+        Returns:
+            Ok(new_line), if ALL of the validation checks found in
+            __validate_msg(...) pass.
+                OR
+            Err(CannotTransform), otherwise.
+        """
+        LL = line.leaves
+
+        is_valid_index = is_valid_index_factory(LL)
+
+        vresult = self._validate_msg(line, string_idx)
+        if isinstance(vresult, Err):
+            return vresult
+
+        # If the string group is wrapped inside an Atom node, we must make sure
+        # to later replace that Atom with our new (merged) string leaf.
+        atom_node = LL[string_idx].parent
+
+        # We will place BREAK_MARK in between every two substrings that we
+        # merge. We will then later go through our final result and use the
+        # various instances of BREAK_MARK we find to add the right values to
+        # the custom split map.
+        BREAK_MARK = "@@@@@ BLACK BREAKPOINT MARKER @@@@@"
+
+        QUOTE = LL[string_idx].value[-1]
+
+        def make_naked(string: str, string_prefix: str) -> str:
+            """Strip @string (i.e. make it a "naked" string)
+
+            Pre-conditions:
+                * assert_is_leaf_string(@string)
+
+            Returns:
+                A string that is identical to @string except that
+                @string_prefix has been stripped, the surrounding QUOTE
+                characters have been removed, and any remaining QUOTE
+                characters have been escaped.
+            """
+            assert_is_leaf_string(string)
+
+            RE_EVEN_BACKSLASHES = r"(?:(?<!\\)(?:\\\\)*)"
+            naked_string = string[len(string_prefix) + 1 : -1]
+            naked_string = re.sub(
+                "(" + RE_EVEN_BACKSLASHES + ")" + QUOTE, r"\1\\" + QUOTE, naked_string
+            )
+            return naked_string
+
+        # Holds the CustomSplit objects that will later be added to the custom
+        # split map.
+        custom_splits = []
+
+        # Temporary storage for the 'has_prefix' part of the CustomSplit objects.
+        prefix_tracker = []
+
+        # Sets the 'prefix' variable. This is the prefix that the final merged
+        # string will have.
+        next_str_idx = string_idx
+        prefix = ""
+        while (
+            not prefix
+            and is_valid_index(next_str_idx)
+            and LL[next_str_idx].type == token.STRING
+        ):
+            prefix = get_string_prefix(LL[next_str_idx].value)
+            next_str_idx += 1
+
+        # The next loop merges the string group. The final string will be
+        # contained in 'S'.
+        #
+        # The following convenience variables are used:
+        #
+        #   S: string
+        #   NS: naked string
+        #   SS: next string
+        #   NSS: naked next string
+        S = ""
+        NS = ""
+        num_of_strings = 0
+        next_str_idx = string_idx
+        while is_valid_index(next_str_idx) and LL[next_str_idx].type == token.STRING:
+            num_of_strings += 1
+
+            SS = LL[next_str_idx].value
+            next_prefix = get_string_prefix(SS)
+
+            # If this is an f-string group but this substring is not prefixed
+            # with 'f'...
+            if "f" in prefix and "f" not in next_prefix:
+                # Then we must escape any braces contained in this substring.
+                SS = re.subf(r"(\{|\})", "{1}{1}", SS)
+
+            NSS = make_naked(SS, next_prefix)
+
+            has_prefix = bool(next_prefix)
+            prefix_tracker.append(has_prefix)
+
+            S = prefix + QUOTE + NS + NSS + BREAK_MARK + QUOTE
+            NS = make_naked(S, prefix)
+
+            next_str_idx += 1
+
+        S_leaf = Leaf(token.STRING, S)
+        if self.normalize_strings:
+            S_leaf.value = normalize_string_quotes(S_leaf.value)
+
+        # Fill the 'custom_splits' list with the appropriate CustomSplit objects.
+        temp_string = S_leaf.value[len(prefix) + 1 : -1]
+        for has_prefix in prefix_tracker:
+            mark_idx = temp_string.find(BREAK_MARK)
+            assert (
+                mark_idx >= 0
+            ), "Logic error while filling the custom string breakpoint cache."
+
+            temp_string = temp_string[mark_idx + len(BREAK_MARK) :]
+            breakpoint_idx = mark_idx + (len(prefix) if has_prefix else 0) + 1
+            custom_splits.append(CustomSplit(has_prefix, breakpoint_idx))
+
+        string_leaf = Leaf(token.STRING, S_leaf.value.replace(BREAK_MARK, ""))
+
+        if atom_node is not None:
+            replace_child(atom_node, string_leaf)
+
+        # Build the final line ('new_line') that this method will later return.
+        new_line = line.clone()
+        for (i, leaf) in enumerate(LL):
+            if i == string_idx:
+                new_line.append(string_leaf)
+
+            if string_idx <= i < string_idx + num_of_strings:
+                for comment_leaf in line.comments_after(LL[i]):
+                    new_line.append(comment_leaf, preformatted=True)
+                continue
+
+            append_leaves(new_line, line, [leaf])
+
+        self.add_custom_splits(string_leaf.value, custom_splits)
+        return Ok(new_line)
+
+    @staticmethod
+    def _validate_msg(line: Line, string_idx: int) -> TResult[None]:
+        """Validate (M)erge (S)tring (G)roup
+
+        Transform-time string validation logic for __merge_string_group(...).
+
+        Returns:
+            * Ok(None), if ALL validation checks (listed below) pass.
+                OR
+            * Err(CannotTransform), if any of the following are true:
+                - The target string group does not contain ANY stand-alone comments.
+                - The target string is not in a string group (i.e. it has no
+                  adjacent strings).
+                - The string group has more than one inline comment.
+                - The string group has an inline comment that appears to be a pragma.
+                - The set of all string prefixes in the string group is of
+                  length greater than one and is not equal to {"", "f"}.
+                - The string group consists of raw strings.
+        """
+        # We first check for "inner" stand-alone comments (i.e. stand-alone
+        # comments that have a string leaf before them AND after them).
+        for inc in [1, -1]:
+            i = string_idx
+            found_sa_comment = False
+            is_valid_index = is_valid_index_factory(line.leaves)
+            while is_valid_index(i) and line.leaves[i].type in [
+                token.STRING,
+                STANDALONE_COMMENT,
+            ]:
+                if line.leaves[i].type == STANDALONE_COMMENT:
+                    found_sa_comment = True
+                elif found_sa_comment:
+                    return TErr(
+                        "StringMerger does NOT merge string groups which contain "
+                        "stand-alone comments."
+                    )
+
+                i += inc
+
+        num_of_inline_string_comments = 0
+        set_of_prefixes = set()
+        num_of_strings = 0
+        for leaf in line.leaves[string_idx:]:
+            if leaf.type != token.STRING:
+                # If the string group is trailed by a comma, we count the
+                # comments trailing the comma to be one of the string group's
+                # comments.
+                if leaf.type == token.COMMA and id(leaf) in line.comments:
+                    num_of_inline_string_comments += 1
+                break
+
+            if has_triple_quotes(leaf.value):
+                return TErr("StringMerger does NOT merge multiline strings.")
+
+            num_of_strings += 1
+            prefix = get_string_prefix(leaf.value)
+            if "r" in prefix:
+                return TErr("StringMerger does NOT merge raw strings.")
+
+            set_of_prefixes.add(prefix)
+
+            if id(leaf) in line.comments:
+                num_of_inline_string_comments += 1
+                if contains_pragma_comment(line.comments[id(leaf)]):
+                    return TErr("Cannot merge strings which have pragma comments.")
+
+        if num_of_strings < 2:
+            return TErr(
+                f"Not enough strings to merge (num_of_strings={num_of_strings})."
+            )
+
+        if num_of_inline_string_comments > 1:
+            return TErr(
+                f"Too many inline string comments ({num_of_inline_string_comments})."
+            )
+
+        if len(set_of_prefixes) > 1 and set_of_prefixes != {"", "f"}:
+            return TErr(f"Too many different prefixes ({set_of_prefixes}).")
+
+        return Ok(None)
+
+
+class StringParenStripper(StringTransformer):
+    """StringTransformer that strips surrounding parentheses from strings.
+
+    Requirements:
+        The line contains a string which is surrounded by parentheses and:
+            - The target string is NOT the only argument to a function call.
+            - The target string is NOT a "pointless" string.
+            - If the target string contains a PERCENT, the brackets are not
+              preceeded or followed by an operator with higher precedence than
+              PERCENT.
+
+    Transformations:
+        The parentheses mentioned in the 'Requirements' section are stripped.
+
+    Collaborations:
+        StringParenStripper has its own inherent usefulness, but it is also
+        relied on to clean up the parentheses created by StringParenWrapper (in
+        the event that they are no longer needed).
+    """
+
+    def do_match(self, line: Line) -> TMatchResult:
+        LL = line.leaves
+
+        is_valid_index = is_valid_index_factory(LL)
+
+        for (idx, leaf) in enumerate(LL):
+            # Should be a string...
+            if leaf.type != token.STRING:
+                continue
+
+            # If this is a "pointless" string...
+            if (
+                leaf.parent
+                and leaf.parent.parent
+                and leaf.parent.parent.type == syms.simple_stmt
+            ):
+                continue
+
+            # Should be preceded by a non-empty LPAR...
+            if (
+                not is_valid_index(idx - 1)
+                or LL[idx - 1].type != token.LPAR
+                or is_empty_lpar(LL[idx - 1])
+            ):
+                continue
+
+            # That LPAR should NOT be preceded by a function name or a closing
+            # bracket (which could be a function which returns a function or a
+            # list/dictionary that contains a function)...
+            if is_valid_index(idx - 2) and (
+                LL[idx - 2].type == token.NAME or LL[idx - 2].type in CLOSING_BRACKETS
+            ):
+                continue
+
+            string_idx = idx
+
+            # Skip the string trailer, if one exists.
+            string_parser = StringParser()
+            next_idx = string_parser.parse(LL, string_idx)
+
+            # if the leaves in the parsed string include a PERCENT, we need to
+            # make sure the initial LPAR is NOT preceded by an operator with
+            # higher or equal precedence to PERCENT
+            if is_valid_index(idx - 2):
+                # mypy can't quite follow unless we name this
+                before_lpar = LL[idx - 2]
+                if token.PERCENT in {leaf.type for leaf in LL[idx - 1 : next_idx]} and (
+                    (
+                        before_lpar.type
+                        in {
+                            token.STAR,
+                            token.AT,
+                            token.SLASH,
+                            token.DOUBLESLASH,
+                            token.PERCENT,
+                            token.TILDE,
+                            token.DOUBLESTAR,
+                            token.AWAIT,
+                            token.LSQB,
+                            token.LPAR,
+                        }
+                    )
+                    or (
+                        # only unary PLUS/MINUS
+                        before_lpar.parent
+                        and before_lpar.parent.type == syms.factor
+                        and (before_lpar.type in {token.PLUS, token.MINUS})
+                    )
+                ):
+                    continue
+
+            # Should be followed by a non-empty RPAR...
+            if (
+                is_valid_index(next_idx)
+                and LL[next_idx].type == token.RPAR
+                and not is_empty_rpar(LL[next_idx])
+            ):
+                # That RPAR should NOT be followed by anything with higher
+                # precedence than PERCENT
+                if is_valid_index(next_idx + 1) and LL[next_idx + 1].type in {
+                    token.DOUBLESTAR,
+                    token.LSQB,
+                    token.LPAR,
+                    token.DOT,
+                }:
+                    continue
+
+                return Ok(string_idx)
+
+        return TErr("This line has no strings wrapped in parens.")
+
+    def do_transform(self, line: Line, string_idx: int) -> Iterator[TResult[Line]]:
+        LL = line.leaves
+
+        string_parser = StringParser()
+        rpar_idx = string_parser.parse(LL, string_idx)
+
+        for leaf in (LL[string_idx - 1], LL[rpar_idx]):
+            if line.comments_after(leaf):
+                yield TErr(
+                    "Will not strip parentheses which have comments attached to them."
+                )
+                return
+
+        new_line = line.clone()
+        new_line.comments = line.comments.copy()
+        try:
+            append_leaves(new_line, line, LL[: string_idx - 1])
+        except BracketMatchError:
+            # HACK: I believe there is currently a bug somewhere in
+            # right_hand_split() that is causing brackets to not be tracked
+            # properly by a shared BracketTracker.
+            append_leaves(new_line, line, LL[: string_idx - 1], preformatted=True)
+
+        string_leaf = Leaf(token.STRING, LL[string_idx].value)
+        LL[string_idx - 1].remove()
+        replace_child(LL[string_idx], string_leaf)
+        new_line.append(string_leaf)
+
+        append_leaves(
+            new_line, line, LL[string_idx + 1 : rpar_idx] + LL[rpar_idx + 1 :]
+        )
+
+        LL[rpar_idx].remove()
+
+        yield Ok(new_line)
+
+
+class BaseStringSplitter(StringTransformer):
+    """
+    Abstract class for StringTransformers which transform a Line's strings by splitting
+    them or placing them on their own lines where necessary to avoid going over
+    the configured line length.
+
+    Requirements:
+        * The target string value is responsible for the line going over the
+        line length limit. It follows that after all of black's other line
+        split methods have been exhausted, this line (or one of the resulting
+        lines after all line splits are performed) would still be over the
+        line_length limit unless we split this string.
+            AND
+        * The target string is NOT a "pointless" string (i.e. a string that has
+        no parent or siblings).
+            AND
+        * The target string is not followed by an inline comment that appears
+        to be a pragma.
+            AND
+        * The target string is not a multiline (i.e. triple-quote) string.
+    """
+
+    @abstractmethod
+    def do_splitter_match(self, line: Line) -> TMatchResult:
+        """
+        BaseStringSplitter asks its clients to override this method instead of
+        `StringTransformer.do_match(...)`.
+
+        Follows the same protocol as `StringTransformer.do_match(...)`.
+
+        Refer to `help(StringTransformer.do_match)` for more information.
+        """
+
+    def do_match(self, line: Line) -> TMatchResult:
+        match_result = self.do_splitter_match(line)
+        if isinstance(match_result, Err):
+            return match_result
+
+        string_idx = match_result.ok()
+        vresult = self._validate(line, string_idx)
+        if isinstance(vresult, Err):
+            return vresult
+
+        return match_result
+
+    def _validate(self, line: Line, string_idx: int) -> TResult[None]:
+        """
+        Checks that @line meets all of the requirements listed in this classes'
+        docstring. Refer to `help(BaseStringSplitter)` for a detailed
+        description of those requirements.
+
+        Returns:
+            * Ok(None), if ALL of the requirements are met.
+                OR
+            * Err(CannotTransform), if ANY of the requirements are NOT met.
+        """
+        LL = line.leaves
+
+        string_leaf = LL[string_idx]
+
+        max_string_length = self._get_max_string_length(line, string_idx)
+        if len(string_leaf.value) <= max_string_length:
+            return TErr(
+                "The string itself is not what is causing this line to be too long."
+            )
+
+        if not string_leaf.parent or [L.type for L in string_leaf.parent.children] == [
+            token.STRING,
+            token.NEWLINE,
+        ]:
+            return TErr(
+                f"This string ({string_leaf.value}) appears to be pointless (i.e. has"
+                " no parent)."
+            )
+
+        if id(line.leaves[string_idx]) in line.comments and contains_pragma_comment(
+            line.comments[id(line.leaves[string_idx])]
+        ):
+            return TErr(
+                "Line appears to end with an inline pragma comment. Splitting the line"
+                " could modify the pragma's behavior."
+            )
+
+        if has_triple_quotes(string_leaf.value):
+            return TErr("We cannot split multiline strings.")
+
+        return Ok(None)
+
+    def _get_max_string_length(self, line: Line, string_idx: int) -> int:
+        """
+        Calculates the max string length used when attempting to determine
+        whether or not the target string is responsible for causing the line to
+        go over the line length limit.
+
+        WARNING: This method is tightly coupled to both StringSplitter and
+        (especially) StringParenWrapper. There is probably a better way to
+        accomplish what is being done here.
+
+        Returns:
+            max_string_length: such that `line.leaves[string_idx].value >
+            max_string_length` implies that the target string IS responsible
+            for causing this line to exceed the line length limit.
+        """
+        LL = line.leaves
+
+        is_valid_index = is_valid_index_factory(LL)
+
+        # We use the shorthand "WMA4" in comments to abbreviate "We must
+        # account for". When giving examples, we use STRING to mean some/any
+        # valid string.
+        #
+        # Finally, we use the following convenience variables:
+        #
+        #   P:  The leaf that is before the target string leaf.
+        #   N:  The leaf that is after the target string leaf.
+        #   NN: The leaf that is after N.
+
+        # WMA4 the whitespace at the beginning of the line.
+        offset = line.depth * 4
+
+        if is_valid_index(string_idx - 1):
+            p_idx = string_idx - 1
+            if (
+                LL[string_idx - 1].type == token.LPAR
+                and LL[string_idx - 1].value == ""
+                and string_idx >= 2
+            ):
+                # If the previous leaf is an empty LPAR placeholder, we should skip it.
+                p_idx -= 1
+
+            P = LL[p_idx]
+            if P.type == token.PLUS:
+                # WMA4 a space and a '+' character (e.g. `+ STRING`).
+                offset += 2
+
+            if P.type == token.COMMA:
+                # WMA4 a space, a comma, and a closing bracket [e.g. `), STRING`].
+                offset += 3
+
+            if P.type in [token.COLON, token.EQUAL, token.NAME]:
+                # This conditional branch is meant to handle dictionary keys,
+                # variable assignments, 'return STRING' statement lines, and
+                # 'else STRING' ternary expression lines.
+
+                # WMA4 a single space.
+                offset += 1
+
+                # WMA4 the lengths of any leaves that came before that space,
+                # but after any closing bracket before that space.
+                for leaf in reversed(LL[: p_idx + 1]):
+                    offset += len(str(leaf))
+                    if leaf.type in CLOSING_BRACKETS:
+                        break
+
+        if is_valid_index(string_idx + 1):
+            N = LL[string_idx + 1]
+            if N.type == token.RPAR and N.value == "" and len(LL) > string_idx + 2:
+                # If the next leaf is an empty RPAR placeholder, we should skip it.
+                N = LL[string_idx + 2]
+
+            if N.type == token.COMMA:
+                # WMA4 a single comma at the end of the string (e.g `STRING,`).
+                offset += 1
+
+            if is_valid_index(string_idx + 2):
+                NN = LL[string_idx + 2]
+
+                if N.type == token.DOT and NN.type == token.NAME:
+                    # This conditional branch is meant to handle method calls invoked
+                    # off of a string literal up to and including the LPAR character.
+
+                    # WMA4 the '.' character.
+                    offset += 1
+
+                    if (
+                        is_valid_index(string_idx + 3)
+                        and LL[string_idx + 3].type == token.LPAR
+                    ):
+                        # WMA4 the left parenthesis character.
+                        offset += 1
+
+                    # WMA4 the length of the method's name.
+                    offset += len(NN.value)
+
+        has_comments = False
+        for comment_leaf in line.comments_after(LL[string_idx]):
+            if not has_comments:
+                has_comments = True
+                # WMA4 two spaces before the '#' character.
+                offset += 2
+
+            # WMA4 the length of the inline comment.
+            offset += len(comment_leaf.value)
+
+        max_string_length = self.line_length - offset
+        return max_string_length
+
+
+class StringSplitter(CustomSplitMapMixin, BaseStringSplitter):
+    """
+    StringTransformer that splits "atom" strings (i.e. strings which exist on
+    lines by themselves).
+
+    Requirements:
+        * The line consists ONLY of a single string (with the exception of a
+        '+' symbol which MAY exist at the start of the line), MAYBE a string
+        trailer, and MAYBE a trailing comma.
+            AND
+        * All of the requirements listed in BaseStringSplitter's docstring.
+
+    Transformations:
+        The string mentioned in the 'Requirements' section is split into as
+        many substrings as necessary to adhere to the configured line length.
+
+        In the final set of substrings, no substring should be smaller than
+        MIN_SUBSTR_SIZE characters.
+
+        The string will ONLY be split on spaces (i.e. each new substring should
+        start with a space). Note that the string will NOT be split on a space
+        which is escaped with a backslash.
+
+        If the string is an f-string, it will NOT be split in the middle of an
+        f-expression (e.g. in f"FooBar: {foo() if x else bar()}", {foo() if x
+        else bar()} is an f-expression).
+
+        If the string that is being split has an associated set of custom split
+        records and those custom splits will NOT result in any line going over
+        the configured line length, those custom splits are used. Otherwise the
+        string is split as late as possible (from left-to-right) while still
+        adhering to the transformation rules listed above.
+
+    Collaborations:
+        StringSplitter relies on StringMerger to construct the appropriate
+        CustomSplit objects and add them to the custom split map.
+    """
+
+    MIN_SUBSTR_SIZE = 6
+    # Matches an "f-expression" (e.g. {var}) that might be found in an f-string.
+    RE_FEXPR = r"""
+    (?<!\{) (?:\{\{)* \{ (?!\{)
+        (?:
+            [^\{\}]
+            | \{\{
+            | \}\}
+            | (?R)
+        )+?
+    (?<!\}) \} (?:\}\})* (?!\})
+    """
+
+    def do_splitter_match(self, line: Line) -> TMatchResult:
+        LL = line.leaves
+
+        is_valid_index = is_valid_index_factory(LL)
+
+        idx = 0
+
+        # The first leaf MAY be a '+' symbol...
+        if is_valid_index(idx) and LL[idx].type == token.PLUS:
+            idx += 1
+
+        # The next/first leaf MAY be an empty LPAR...
+        if is_valid_index(idx) and is_empty_lpar(LL[idx]):
+            idx += 1
+
+        # The next/first leaf MUST be a string...
+        if not is_valid_index(idx) or LL[idx].type != token.STRING:
+            return TErr("Line does not start with a string.")
+
+        string_idx = idx
+
+        # Skip the string trailer, if one exists.
+        string_parser = StringParser()
+        idx = string_parser.parse(LL, string_idx)
+
+        # That string MAY be followed by an empty RPAR...
+        if is_valid_index(idx) and is_empty_rpar(LL[idx]):
+            idx += 1
+
+        # That string / empty RPAR leaf MAY be followed by a comma...
+        if is_valid_index(idx) and LL[idx].type == token.COMMA:
+            idx += 1
+
+        # But no more leaves are allowed...
+        if is_valid_index(idx):
+            return TErr("This line does not end with a string.")
+
+        return Ok(string_idx)
+
+    def do_transform(self, line: Line, string_idx: int) -> Iterator[TResult[Line]]:
+        LL = line.leaves
+
+        QUOTE = LL[string_idx].value[-1]
+
+        is_valid_index = is_valid_index_factory(LL)
+        insert_str_child = insert_str_child_factory(LL[string_idx])
+
+        prefix = get_string_prefix(LL[string_idx].value)
+
+        # We MAY choose to drop the 'f' prefix from substrings that don't
+        # contain any f-expressions, but ONLY if the original f-string
+        # contains at least one f-expression. Otherwise, we will alter the AST
+        # of the program.
+        drop_pointless_f_prefix = ("f" in prefix) and re.search(
+            self.RE_FEXPR, LL[string_idx].value, re.VERBOSE
+        )
+
+        first_string_line = True
+        starts_with_plus = LL[0].type == token.PLUS
+
+        def line_needs_plus() -> bool:
+            return first_string_line and starts_with_plus
+
+        def maybe_append_plus(new_line: Line) -> None:
+            """
+            Side Effects:
+                If @line starts with a plus and this is the first line we are
+                constructing, this function appends a PLUS leaf to @new_line
+                and replaces the old PLUS leaf in the node structure. Otherwise
+                this function does nothing.
+            """
+            if line_needs_plus():
+                plus_leaf = Leaf(token.PLUS, "+")
+                replace_child(LL[0], plus_leaf)
+                new_line.append(plus_leaf)
+
+        ends_with_comma = (
+            is_valid_index(string_idx + 1) and LL[string_idx + 1].type == token.COMMA
+        )
+
+        def max_last_string() -> int:
+            """
+            Returns:
+                The max allowed length of the string value used for the last
+                line we will construct.
+            """
+            result = self.line_length
+            result -= line.depth * 4
+            result -= 1 if ends_with_comma else 0
+            result -= 2 if line_needs_plus() else 0
+            return result
+
+        # --- Calculate Max Break Index (for string value)
+        # We start with the line length limit
+        max_break_idx = self.line_length
+        # The last index of a string of length N is N-1.
+        max_break_idx -= 1
+        # Leading whitespace is not present in the string value (e.g. Leaf.value).
+        max_break_idx -= line.depth * 4
+        if max_break_idx < 0:
+            yield TErr(
+                f"Unable to split {LL[string_idx].value} at such high of a line depth:"
+                f" {line.depth}"
+            )
+            return
+
+        # Check if StringMerger registered any custom splits.
+        custom_splits = self.pop_custom_splits(LL[string_idx].value)
+        # We use them ONLY if none of them would produce lines that exceed the
+        # line limit.
+        use_custom_breakpoints = bool(
+            custom_splits
+            and all(csplit.break_idx <= max_break_idx for csplit in custom_splits)
+        )
+
+        # Temporary storage for the remaining chunk of the string line that
+        # can't fit onto the line currently being constructed.
+        rest_value = LL[string_idx].value
+
+        def more_splits_should_be_made() -> bool:
+            """
+            Returns:
+                True iff `rest_value` (the remaining string value from the last
+                split), should be split again.
+            """
+            if use_custom_breakpoints:
+                return len(custom_splits) > 1
+            else:
+                return len(rest_value) > max_last_string()
+
+        string_line_results: List[Ok[Line]] = []
+        while more_splits_should_be_made():
+            if use_custom_breakpoints:
+                # Custom User Split (manual)
+                csplit = custom_splits.pop(0)
+                break_idx = csplit.break_idx
+            else:
+                # Algorithmic Split (automatic)
+                max_bidx = max_break_idx - 2 if line_needs_plus() else max_break_idx
+                maybe_break_idx = self._get_break_idx(rest_value, max_bidx)
+                if maybe_break_idx is None:
+                    # If we are unable to algorithmically determine a good split
+                    # and this string has custom splits registered to it, we
+                    # fall back to using them--which means we have to start
+                    # over from the beginning.
+                    if custom_splits:
+                        rest_value = LL[string_idx].value
+                        string_line_results = []
+                        first_string_line = True
+                        use_custom_breakpoints = True
+                        continue
+
+                    # Otherwise, we stop splitting here.
+                    break
+
+                break_idx = maybe_break_idx
+
+            # --- Construct `next_value`
+            next_value = rest_value[:break_idx] + QUOTE
+            if (
+                # Are we allowed to try to drop a pointless 'f' prefix?
+                drop_pointless_f_prefix
+                # If we are, will we be successful?
+                and next_value != self._normalize_f_string(next_value, prefix)
+            ):
+                # If the current custom split did NOT originally use a prefix,
+                # then `csplit.break_idx` will be off by one after removing
+                # the 'f' prefix.
+                break_idx = (
+                    break_idx + 1
+                    if use_custom_breakpoints and not csplit.has_prefix
+                    else break_idx
+                )
+                next_value = rest_value[:break_idx] + QUOTE
+                next_value = self._normalize_f_string(next_value, prefix)
+
+            # --- Construct `next_leaf`
+            next_leaf = Leaf(token.STRING, next_value)
+            insert_str_child(next_leaf)
+            self._maybe_normalize_string_quotes(next_leaf)
+
+            # --- Construct `next_line`
+            next_line = line.clone()
+            maybe_append_plus(next_line)
+            next_line.append(next_leaf)
+            string_line_results.append(Ok(next_line))
+
+            rest_value = prefix + QUOTE + rest_value[break_idx:]
+            first_string_line = False
+
+        yield from string_line_results
+
+        if drop_pointless_f_prefix:
+            rest_value = self._normalize_f_string(rest_value, prefix)
+
+        rest_leaf = Leaf(token.STRING, rest_value)
+        insert_str_child(rest_leaf)
+
+        # NOTE: I could not find a test case that verifies that the following
+        # line is actually necessary, but it seems to be. Otherwise we risk
+        # not normalizing the last substring, right?
+        self._maybe_normalize_string_quotes(rest_leaf)
+
+        last_line = line.clone()
+        maybe_append_plus(last_line)
+
+        # If there are any leaves to the right of the target string...
+        if is_valid_index(string_idx + 1):
+            # We use `temp_value` here to determine how long the last line
+            # would be if we were to append all the leaves to the right of the
+            # target string to the last string line.
+            temp_value = rest_value
+            for leaf in LL[string_idx + 1 :]:
+                temp_value += str(leaf)
+                if leaf.type == token.LPAR:
+                    break
+
+            # Try to fit them all on the same line with the last substring...
+            if (
+                len(temp_value) <= max_last_string()
+                or LL[string_idx + 1].type == token.COMMA
+            ):
+                last_line.append(rest_leaf)
+                append_leaves(last_line, line, LL[string_idx + 1 :])
+                yield Ok(last_line)
+            # Otherwise, place the last substring on one line and everything
+            # else on a line below that...
+            else:
+                last_line.append(rest_leaf)
+                yield Ok(last_line)
+
+                non_string_line = line.clone()
+                append_leaves(non_string_line, line, LL[string_idx + 1 :])
+                yield Ok(non_string_line)
+        # Else the target string was the last leaf...
+        else:
+            last_line.append(rest_leaf)
+            last_line.comments = line.comments.copy()
+            yield Ok(last_line)
+
+    def _get_break_idx(self, string: str, max_break_idx: int) -> Optional[int]:
+        """
+        This method contains the algorithm that StringSplitter uses to
+        determine which character to split each string at.
+
+        Args:
+            @string: The substring that we are attempting to split.
+            @max_break_idx: The ideal break index. We will return this value if it
+            meets all the necessary conditions. In the likely event that it
+            doesn't we will try to find the closest index BELOW @max_break_idx
+            that does. If that fails, we will expand our search by also
+            considering all valid indices ABOVE @max_break_idx.
+
+        Pre-Conditions:
+            * assert_is_leaf_string(@string)
+            * 0 <= @max_break_idx < len(@string)
+
+        Returns:
+            break_idx, if an index is able to be found that meets all of the
+            conditions listed in the 'Transformations' section of this classes'
+            docstring.
+                OR
+            None, otherwise.
+        """
+        is_valid_index = is_valid_index_factory(string)
+
+        assert is_valid_index(max_break_idx)
+        assert_is_leaf_string(string)
+
+        _fexpr_slices: Optional[List[Tuple[Index, Index]]] = None
+
+        def fexpr_slices() -> Iterator[Tuple[Index, Index]]:
+            """
+            Yields:
+                All ranges of @string which, if @string were to be split there,
+                would result in the splitting of an f-expression (which is NOT
+                allowed).
+            """
+            nonlocal _fexpr_slices
+
+            if _fexpr_slices is None:
+                _fexpr_slices = []
+                for match in re.finditer(self.RE_FEXPR, string, re.VERBOSE):
+                    _fexpr_slices.append(match.span())
+
+            yield from _fexpr_slices
+
+        is_fstring = "f" in get_string_prefix(string)
+
+        def breaks_fstring_expression(i: Index) -> bool:
+            """
+            Returns:
+                True iff returning @i would result in the splitting of an
+                f-expression (which is NOT allowed).
+            """
+            if not is_fstring:
+                return False
+
+            for (start, end) in fexpr_slices():
+                if start <= i < end:
+                    return True
+
+            return False
+
+        def passes_all_checks(i: Index) -> bool:
+            """
+            Returns:
+                True iff ALL of the conditions listed in the 'Transformations'
+                section of this classes' docstring would be be met by returning @i.
+            """
+            is_space = string[i] == " "
+
+            is_not_escaped = True
+            j = i - 1
+            while is_valid_index(j) and string[j] == "\\":
+                is_not_escaped = not is_not_escaped
+                j -= 1
+
+            is_big_enough = (
+                len(string[i:]) >= self.MIN_SUBSTR_SIZE
+                and len(string[:i]) >= self.MIN_SUBSTR_SIZE
+            )
+            return (
+                is_space
+                and is_not_escaped
+                and is_big_enough
+                and not breaks_fstring_expression(i)
+            )
+
+        # First, we check all indices BELOW @max_break_idx.
+        break_idx = max_break_idx
+        while is_valid_index(break_idx - 1) and not passes_all_checks(break_idx):
+            break_idx -= 1
+
+        if not passes_all_checks(break_idx):
+            # If that fails, we check all indices ABOVE @max_break_idx.
+            #
+            # If we are able to find a valid index here, the next line is going
+            # to be longer than the specified line length, but it's probably
+            # better than doing nothing at all.
+            break_idx = max_break_idx + 1
+            while is_valid_index(break_idx + 1) and not passes_all_checks(break_idx):
+                break_idx += 1
+
+            if not is_valid_index(break_idx) or not passes_all_checks(break_idx):
+                return None
+
+        return break_idx
+
+    def _maybe_normalize_string_quotes(self, leaf: Leaf) -> None:
+        if self.normalize_strings:
+            leaf.value = normalize_string_quotes(leaf.value)
+
+    def _normalize_f_string(self, string: str, prefix: str) -> str:
+        """
+        Pre-Conditions:
+            * assert_is_leaf_string(@string)
+
+        Returns:
+            * If @string is an f-string that contains no f-expressions, we
+            return a string identical to @string except that the 'f' prefix
+            has been stripped and all double braces (i.e. '{{' or '}}') have
+            been normalized (i.e. turned into '{' or '}').
+                OR
+            * Otherwise, we return @string.
+        """
+        assert_is_leaf_string(string)
+
+        if "f" in prefix and not re.search(self.RE_FEXPR, string, re.VERBOSE):
+            new_prefix = prefix.replace("f", "")
+
+            temp = string[len(prefix) :]
+            temp = re.sub(r"\{\{", "{", temp)
+            temp = re.sub(r"\}\}", "}", temp)
+            new_string = temp
+
+            return f"{new_prefix}{new_string}"
+        else:
+            return string
+
+
+class StringParenWrapper(CustomSplitMapMixin, BaseStringSplitter):
+    """
+    StringTransformer that splits non-"atom" strings (i.e. strings that do not
+    exist on lines by themselves).
+
+    Requirements:
+        All of the requirements listed in BaseStringSplitter's docstring in
+        addition to the requirements listed below:
+
+        * The line is a return/yield statement, which returns/yields a string.
+            OR
+        * The line is part of a ternary expression (e.g. `x = y if cond else
+        z`) such that the line starts with `else <string>`, where <string> is
+        some string.
+            OR
+        * The line is an assert statement, which ends with a string.
+            OR
+        * The line is an assignment statement (e.g. `x = <string>` or `x +=
+        <string>`) such that the variable is being assigned the value of some
+        string.
+            OR
+        * The line is a dictionary key assignment where some valid key is being
+        assigned the value of some string.
+
+    Transformations:
+        The chosen string is wrapped in parentheses and then split at the LPAR.
+
+        We then have one line which ends with an LPAR and another line that
+        starts with the chosen string. The latter line is then split again at
+        the RPAR. This results in the RPAR (and possibly a trailing comma)
+        being placed on its own line.
+
+        NOTE: If any leaves exist to the right of the chosen string (except
+        for a trailing comma, which would be placed after the RPAR), those
+        leaves are placed inside the parentheses.  In effect, the chosen
+        string is not necessarily being "wrapped" by parentheses. We can,
+        however, count on the LPAR being placed directly before the chosen
+        string.
+
+        In other words, StringParenWrapper creates "atom" strings. These
+        can then be split again by StringSplitter, if necessary.
+
+    Collaborations:
+        In the event that a string line split by StringParenWrapper is
+        changed such that it no longer needs to be given its own line,
+        StringParenWrapper relies on StringParenStripper to clean up the
+        parentheses it created.
+    """
+
+    def do_splitter_match(self, line: Line) -> TMatchResult:
+        LL = line.leaves
+
+        string_idx = (
+            self._return_match(LL)
+            or self._else_match(LL)
+            or self._assert_match(LL)
+            or self._assign_match(LL)
+            or self._dict_match(LL)
+        )
+
+        if string_idx is not None:
+            string_value = line.leaves[string_idx].value
+            # If the string has no spaces...
+            if " " not in string_value:
+                # And will still violate the line length limit when split...
+                max_string_length = self.line_length - ((line.depth + 1) * 4)
+                if len(string_value) > max_string_length:
+                    # And has no associated custom splits...
+                    if not self.has_custom_splits(string_value):
+                        # Then we should NOT put this string on its own line.
+                        return TErr(
+                            "We do not wrap long strings in parentheses when the"
+                            " resultant line would still be over the specified line"
+                            " length and can't be split further by StringSplitter."
+                        )
+            return Ok(string_idx)
+
+        return TErr("This line does not contain any non-atomic strings.")
+
+    @staticmethod
+    def _return_match(LL: List[Leaf]) -> Optional[int]:
+        """
+        Returns:
+            string_idx such that @LL[string_idx] is equal to our target (i.e.
+            matched) string, if this line matches the return/yield statement
+            requirements listed in the 'Requirements' section of this classes'
+            docstring.
+                OR
+            None, otherwise.
+        """
+        # If this line is apart of a return/yield statement and the first leaf
+        # contains either the "return" or "yield" keywords...
+        if parent_type(LL[0]) in [syms.return_stmt, syms.yield_expr] and LL[
+            0
+        ].value in ["return", "yield"]:
+            is_valid_index = is_valid_index_factory(LL)
+
+            idx = 2 if is_valid_index(1) and is_empty_par(LL[1]) else 1
+            # The next visible leaf MUST contain a string...
+            if is_valid_index(idx) and LL[idx].type == token.STRING:
+                return idx
+
+        return None
+
+    @staticmethod
+    def _else_match(LL: List[Leaf]) -> Optional[int]:
+        """
+        Returns:
+            string_idx such that @LL[string_idx] is equal to our target (i.e.
+            matched) string, if this line matches the ternary expression
+            requirements listed in the 'Requirements' section of this classes'
+            docstring.
+                OR
+            None, otherwise.
+        """
+        # If this line is apart of a ternary expression and the first leaf
+        # contains the "else" keyword...
+        if (
+            parent_type(LL[0]) == syms.test
+            and LL[0].type == token.NAME
+            and LL[0].value == "else"
+        ):
+            is_valid_index = is_valid_index_factory(LL)
+
+            idx = 2 if is_valid_index(1) and is_empty_par(LL[1]) else 1
+            # The next visible leaf MUST contain a string...
+            if is_valid_index(idx) and LL[idx].type == token.STRING:
+                return idx
+
+        return None
+
+    @staticmethod
+    def _assert_match(LL: List[Leaf]) -> Optional[int]:
+        """
+        Returns:
+            string_idx such that @LL[string_idx] is equal to our target (i.e.
+            matched) string, if this line matches the assert statement
+            requirements listed in the 'Requirements' section of this classes'
+            docstring.
+                OR
+            None, otherwise.
+        """
+        # If this line is apart of an assert statement and the first leaf
+        # contains the "assert" keyword...
+        if parent_type(LL[0]) == syms.assert_stmt and LL[0].value == "assert":
+            is_valid_index = is_valid_index_factory(LL)
+
+            for (i, leaf) in enumerate(LL):
+                # We MUST find a comma...
+                if leaf.type == token.COMMA:
+                    idx = i + 2 if is_empty_par(LL[i + 1]) else i + 1
+
+                    # That comma MUST be followed by a string...
+                    if is_valid_index(idx) and LL[idx].type == token.STRING:
+                        string_idx = idx
+
+                        # Skip the string trailer, if one exists.
+                        string_parser = StringParser()
+                        idx = string_parser.parse(LL, string_idx)
+
+                        # But no more leaves are allowed...
+                        if not is_valid_index(idx):
+                            return string_idx
+
+        return None
+
+    @staticmethod
+    def _assign_match(LL: List[Leaf]) -> Optional[int]:
+        """
+        Returns:
+            string_idx such that @LL[string_idx] is equal to our target (i.e.
+            matched) string, if this line matches the assignment statement
+            requirements listed in the 'Requirements' section of this classes'
+            docstring.
+                OR
+            None, otherwise.
+        """
+        # If this line is apart of an expression statement or is a function
+        # argument AND the first leaf contains a variable name...
+        if (
+            parent_type(LL[0]) in [syms.expr_stmt, syms.argument, syms.power]
+            and LL[0].type == token.NAME
+        ):
+            is_valid_index = is_valid_index_factory(LL)
+
+            for (i, leaf) in enumerate(LL):
+                # We MUST find either an '=' or '+=' symbol...
+                if leaf.type in [token.EQUAL, token.PLUSEQUAL]:
+                    idx = i + 2 if is_empty_par(LL[i + 1]) else i + 1
+
+                    # That symbol MUST be followed by a string...
+                    if is_valid_index(idx) and LL[idx].type == token.STRING:
+                        string_idx = idx
+
+                        # Skip the string trailer, if one exists.
+                        string_parser = StringParser()
+                        idx = string_parser.parse(LL, string_idx)
+
+                        # The next leaf MAY be a comma iff this line is apart
+                        # of a function argument...
+                        if (
+                            parent_type(LL[0]) == syms.argument
+                            and is_valid_index(idx)
+                            and LL[idx].type == token.COMMA
+                        ):
+                            idx += 1
+
+                        # But no more leaves are allowed...
+                        if not is_valid_index(idx):
+                            return string_idx
+
+        return None
+
+    @staticmethod
+    def _dict_match(LL: List[Leaf]) -> Optional[int]:
+        """
+        Returns:
+            string_idx such that @LL[string_idx] is equal to our target (i.e.
+            matched) string, if this line matches the dictionary key assignment
+            statement requirements listed in the 'Requirements' section of this
+            classes' docstring.
+                OR
+            None, otherwise.
+        """
+        # If this line is apart of a dictionary key assignment...
+        if syms.dictsetmaker in [parent_type(LL[0]), parent_type(LL[0].parent)]:
+            is_valid_index = is_valid_index_factory(LL)
+
+            for (i, leaf) in enumerate(LL):
+                # We MUST find a colon...
+                if leaf.type == token.COLON:
+                    idx = i + 2 if is_empty_par(LL[i + 1]) else i + 1
+
+                    # That colon MUST be followed by a string...
+                    if is_valid_index(idx) and LL[idx].type == token.STRING:
+                        string_idx = idx
+
+                        # Skip the string trailer, if one exists.
+                        string_parser = StringParser()
+                        idx = string_parser.parse(LL, string_idx)
+
+                        # That string MAY be followed by a comma...
+                        if is_valid_index(idx) and LL[idx].type == token.COMMA:
+                            idx += 1
+
+                        # But no more leaves are allowed...
+                        if not is_valid_index(idx):
+                            return string_idx
+
+        return None
+
+    def do_transform(self, line: Line, string_idx: int) -> Iterator[TResult[Line]]:
+        LL = line.leaves
+
+        is_valid_index = is_valid_index_factory(LL)
+        insert_str_child = insert_str_child_factory(LL[string_idx])
+
+        comma_idx = -1
+        ends_with_comma = False
+        if LL[comma_idx].type == token.COMMA:
+            ends_with_comma = True
+
+        leaves_to_steal_comments_from = [LL[string_idx]]
+        if ends_with_comma:
+            leaves_to_steal_comments_from.append(LL[comma_idx])
+
+        # --- First Line
+        first_line = line.clone()
+        left_leaves = LL[:string_idx]
+
+        # We have to remember to account for (possibly invisible) LPAR and RPAR
+        # leaves that already wrapped the target string. If these leaves do
+        # exist, we will replace them with our own LPAR and RPAR leaves.
+        old_parens_exist = False
+        if left_leaves and left_leaves[-1].type == token.LPAR:
+            old_parens_exist = True
+            leaves_to_steal_comments_from.append(left_leaves[-1])
+            left_leaves.pop()
+
+        append_leaves(first_line, line, left_leaves)
+
+        lpar_leaf = Leaf(token.LPAR, "(")
+        if old_parens_exist:
+            replace_child(LL[string_idx - 1], lpar_leaf)
+        else:
+            insert_str_child(lpar_leaf)
+        first_line.append(lpar_leaf)
+
+        # We throw inline comments that were originally to the right of the
+        # target string to the top line. They will now be shown to the right of
+        # the LPAR.
+        for leaf in leaves_to_steal_comments_from:
+            for comment_leaf in line.comments_after(leaf):
+                first_line.append(comment_leaf, preformatted=True)
+
+        yield Ok(first_line)
+
+        # --- Middle (String) Line
+        # We only need to yield one (possibly too long) string line, since the
+        # `StringSplitter` will break it down further if necessary.
+        string_value = LL[string_idx].value
+        string_line = Line(
+            mode=line.mode,
+            depth=line.depth + 1,
+            inside_brackets=True,
+            should_split_rhs=line.should_split_rhs,
+            magic_trailing_comma=line.magic_trailing_comma,
+        )
+        string_leaf = Leaf(token.STRING, string_value)
+        insert_str_child(string_leaf)
+        string_line.append(string_leaf)
+
+        old_rpar_leaf = None
+        if is_valid_index(string_idx + 1):
+            right_leaves = LL[string_idx + 1 :]
+            if ends_with_comma:
+                right_leaves.pop()
+
+            if old_parens_exist:
+                assert (
+                    right_leaves and right_leaves[-1].type == token.RPAR
+                ), "Apparently, old parentheses do NOT exist?!"
+                old_rpar_leaf = right_leaves.pop()
+
+            append_leaves(string_line, line, right_leaves)
+
+        yield Ok(string_line)
+
+        # --- Last Line
+        last_line = line.clone()
+        last_line.bracket_tracker = first_line.bracket_tracker
+
+        new_rpar_leaf = Leaf(token.RPAR, ")")
+        if old_rpar_leaf is not None:
+            replace_child(old_rpar_leaf, new_rpar_leaf)
+        else:
+            insert_str_child(new_rpar_leaf)
+        last_line.append(new_rpar_leaf)
+
+        # If the target string ended with a comma, we place this comma to the
+        # right of the RPAR on the last line.
+        if ends_with_comma:
+            comma_leaf = Leaf(token.COMMA, ",")
+            replace_child(LL[comma_idx], comma_leaf)
+            last_line.append(comma_leaf)
+
+        yield Ok(last_line)
+
+
+class StringParser:
+    """
+    A state machine that aids in parsing a string's "trailer", which can be
+    either non-existent, an old-style formatting sequence (e.g. `% varX` or `%
+    (varX, varY)`), or a method-call / attribute access (e.g. `.format(varX,
+    varY)`).
+
+    NOTE: A new StringParser object MUST be instantiated for each string
+    trailer we need to parse.
+
+    Examples:
+        We shall assume that `line` equals the `Line` object that corresponds
+        to the following line of python code:
+        ```
+        x = "Some {}.".format("String") + some_other_string
+        ```
+
+        Furthermore, we will assume that `string_idx` is some index such that:
+        ```
+        assert line.leaves[string_idx].value == "Some {}."
+        ```
+
+        The following code snippet then holds:
+        ```
+        string_parser = StringParser()
+        idx = string_parser.parse(line.leaves, string_idx)
+        assert line.leaves[idx].type == token.PLUS
+        ```
+    """
+
+    DEFAULT_TOKEN = -1
+
+    # String Parser States
+    START = 1
+    DOT = 2
+    NAME = 3
+    PERCENT = 4
+    SINGLE_FMT_ARG = 5
+    LPAR = 6
+    RPAR = 7
+    DONE = 8
+
+    # Lookup Table for Next State
+    _goto: Dict[Tuple[ParserState, NodeType], ParserState] = {
+        # A string trailer may start with '.' OR '%'.
+        (START, token.DOT): DOT,
+        (START, token.PERCENT): PERCENT,
+        (START, DEFAULT_TOKEN): DONE,
+        # A '.' MUST be followed by an attribute or method name.
+        (DOT, token.NAME): NAME,
+        # A method name MUST be followed by an '(', whereas an attribute name
+        # is the last symbol in the string trailer.
+        (NAME, token.LPAR): LPAR,
+        (NAME, DEFAULT_TOKEN): DONE,
+        # A '%' symbol can be followed by an '(' or a single argument (e.g. a
+        # string or variable name).
+        (PERCENT, token.LPAR): LPAR,
+        (PERCENT, DEFAULT_TOKEN): SINGLE_FMT_ARG,
+        # If a '%' symbol is followed by a single argument, that argument is
+        # the last leaf in the string trailer.
+        (SINGLE_FMT_ARG, DEFAULT_TOKEN): DONE,
+        # If present, a ')' symbol is the last symbol in a string trailer.
+        # (NOTE: LPARS and nested RPARS are not included in this lookup table,
+        # since they are treated as a special case by the parsing logic in this
+        # classes' implementation.)
+        (RPAR, DEFAULT_TOKEN): DONE,
+    }
+
+    def __init__(self) -> None:
+        self._state = self.START
+        self._unmatched_lpars = 0
+
+    def parse(self, leaves: List[Leaf], string_idx: int) -> int:
+        """
+        Pre-conditions:
+            * @leaves[@string_idx].type == token.STRING
+
+        Returns:
+            The index directly after the last leaf which is apart of the string
+            trailer, if a "trailer" exists.
+                OR
+            @string_idx + 1, if no string "trailer" exists.
+        """
+        assert leaves[string_idx].type == token.STRING
+
+        idx = string_idx + 1
+        while idx < len(leaves) and self._next_state(leaves[idx]):
+            idx += 1
+        return idx
+
+    def _next_state(self, leaf: Leaf) -> bool:
+        """
+        Pre-conditions:
+            * On the first call to this function, @leaf MUST be the leaf that
+            was directly after the string leaf in question (e.g. if our target
+            string is `line.leaves[i]` then the first call to this method must
+            be `line.leaves[i + 1]`).
+            * On the next call to this function, the leaf parameter passed in
+            MUST be the leaf directly following @leaf.
+
+        Returns:
+            True iff @leaf is apart of the string's trailer.
+        """
+        # We ignore empty LPAR or RPAR leaves.
+        if is_empty_par(leaf):
+            return True
+
+        next_token = leaf.type
+        if next_token == token.LPAR:
+            self._unmatched_lpars += 1
+
+        current_state = self._state
+
+        # The LPAR parser state is a special case. We will return True until we
+        # find the matching RPAR token.
+        if current_state == self.LPAR:
+            if next_token == token.RPAR:
+                self._unmatched_lpars -= 1
+                if self._unmatched_lpars == 0:
+                    self._state = self.RPAR
+        # Otherwise, we use a lookup table to determine the next state.
+        else:
+            # If the lookup table matches the current state to the next
+            # token, we use the lookup table.
+            if (current_state, next_token) in self._goto:
+                self._state = self._goto[current_state, next_token]
+            else:
+                # Otherwise, we check if a the current state was assigned a
+                # default.
+                if (current_state, self.DEFAULT_TOKEN) in self._goto:
+                    self._state = self._goto[current_state, self.DEFAULT_TOKEN]
+                # If no default has been assigned, then this parser has a logic
+                # error.
+                else:
+                    raise RuntimeError(f"{self.__class__.__name__} LOGIC ERROR!")
+
+            if self._state == self.DONE:
+                return False
+
+        return True
+
+
+def insert_str_child_factory(string_leaf: Leaf) -> Callable[[LN], None]:
+    """
+    Factory for a convenience function that is used to orphan @string_leaf
+    and then insert multiple new leaves into the same part of the node
+    structure that @string_leaf had originally occupied.
+
+    Examples:
+        Let `string_leaf = Leaf(token.STRING, '"foo"')` and `N =
+        string_leaf.parent`. Assume the node `N` has the following
+        original structure:
+
+        Node(
+            expr_stmt, [
+                Leaf(NAME, 'x'),
+                Leaf(EQUAL, '='),
+                Leaf(STRING, '"foo"'),
+            ]
+        )
+
+        We then run the code snippet shown below.
+        ```
+        insert_str_child = insert_str_child_factory(string_leaf)
+
+        lpar = Leaf(token.LPAR, '(')
+        insert_str_child(lpar)
+
+        bar = Leaf(token.STRING, '"bar"')
+        insert_str_child(bar)
+
+        rpar = Leaf(token.RPAR, ')')
+        insert_str_child(rpar)
+        ```
+
+        After which point, it follows that `string_leaf.parent is None` and
+        the node `N` now has the following structure:
+
+        Node(
+            expr_stmt, [
+                Leaf(NAME, 'x'),
+                Leaf(EQUAL, '='),
+                Leaf(LPAR, '('),
+                Leaf(STRING, '"bar"'),
+                Leaf(RPAR, ')'),
+            ]
+        )
+    """
+    string_parent = string_leaf.parent
+    string_child_idx = string_leaf.remove()
+
+    def insert_str_child(child: LN) -> None:
+        nonlocal string_child_idx
+
+        assert string_parent is not None
+        assert string_child_idx is not None
+
+        string_parent.insert_child(string_child_idx, child)
+        string_child_idx += 1
+
+    return insert_str_child
+
+
+def is_valid_index_factory(seq: Sequence[Any]) -> Callable[[int], bool]:
+    """
+    Examples:
+        ```
+        my_list = [1, 2, 3]
+
+        is_valid_index = is_valid_index_factory(my_list)
+
+        assert is_valid_index(0)
+        assert is_valid_index(2)
+
+        assert not is_valid_index(3)
+        assert not is_valid_index(-1)
+        ```
+    """
+
+    def is_valid_index(idx: int) -> bool:
+        """
+        Returns:
+            True iff @idx is positive AND seq[@idx] does NOT raise an
+            IndexError.
+        """
+        return 0 <= idx < len(seq)
+
+    return is_valid_index
diff --git a/tests/test_black.py b/tests/test_black.py
index b8e526a953e..29a0731dd9d 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -34,6 +34,10 @@
 
 import black
 from black import Feature, TargetVersion
+from black.cache import get_cache_file
+from black.debug import DebugVisitor
+from black.report import Report
+import black.files
 
 from pathspec import PathSpec
 
@@ -69,7 +73,7 @@ def cache_dir(exists: bool = True) -> Iterator[Path]:
         cache_dir = Path(workspace)
         if not exists:
             cache_dir = cache_dir / "new"
-        with patch("black.CACHE_DIR", cache_dir):
+        with patch("black.cache.CACHE_DIR", cache_dir):
             yield cache_dir
 
 
@@ -582,7 +586,7 @@ def test_tab_comment_indentation(self) -> None:
         self.assertFormatEqual(contents_spc, fs(contents_tab))
 
     def test_report_verbose(self) -> None:
-        report = black.Report(verbose=True)
+        report = Report(verbose=True)
         out_lines = []
         err_lines = []
 
@@ -592,7 +596,7 @@ def out(msg: str, **kwargs: Any) -> None:
         def err(msg: str, **kwargs: Any) -> None:
             err_lines.append(msg)
 
-        with patch("black.out", out), patch("black.err", err):
+        with patch("black.output._out", out), patch("black.output._err", err):
             report.done(Path("f1"), black.Changed.NO)
             self.assertEqual(len(out_lines), 1)
             self.assertEqual(len(err_lines), 0)
@@ -684,7 +688,7 @@ def err(msg: str, **kwargs: Any) -> None:
             )
 
     def test_report_quiet(self) -> None:
-        report = black.Report(quiet=True)
+        report = Report(quiet=True)
         out_lines = []
         err_lines = []
 
@@ -694,7 +698,7 @@ def out(msg: str, **kwargs: Any) -> None:
         def err(msg: str, **kwargs: Any) -> None:
             err_lines.append(msg)
 
-        with patch("black.out", out), patch("black.err", err):
+        with patch("black.output._out", out), patch("black.output._err", err):
             report.done(Path("f1"), black.Changed.NO)
             self.assertEqual(len(out_lines), 0)
             self.assertEqual(len(err_lines), 0)
@@ -788,7 +792,7 @@ def out(msg: str, **kwargs: Any) -> None:
         def err(msg: str, **kwargs: Any) -> None:
             err_lines.append(msg)
 
-        with patch("black.out", out), patch("black.err", err):
+        with patch("black.output._out", out), patch("black.output._err", err):
             report.done(Path("f1"), black.Changed.NO)
             self.assertEqual(len(out_lines), 0)
             self.assertEqual(len(err_lines), 0)
@@ -1005,8 +1009,8 @@ def out(msg: str, **kwargs: Any) -> None:
         def err(msg: str, **kwargs: Any) -> None:
             err_lines.append(msg)
 
-        with patch("black.out", out), patch("black.err", err):
-            black.DebugVisitor.show(source)
+        with patch("black.debug.out", out):
+            DebugVisitor.show(source)
         actual = "\n".join(out_lines) + "\n"
         log_name = ""
         if expected != actual:
@@ -1054,7 +1058,7 @@ def out(msg: str, **kwargs: Any) -> None:
         def err(msg: str, **kwargs: Any) -> None:
             err_lines.append(msg)
 
-        with patch("black.out", out), patch("black.err", err):
+        with patch("black.output._out", out), patch("black.output._err", err):
             with self.assertRaises(AssertionError):
                 self.assertFormatEqual("j = [1, 2, 3]", "j = [1, 2, 3,]")
 
@@ -1066,7 +1070,7 @@ def err(msg: str, **kwargs: Any) -> None:
     def test_cache_broken_file(self) -> None:
         mode = DEFAULT_MODE
         with cache_dir() as workspace:
-            cache_file = black.get_cache_file(mode)
+            cache_file = get_cache_file(mode)
             with cache_file.open("w") as fobj:
                 fobj.write("this is not a pickle")
             self.assertEqual(black.read_cache(mode), {})
@@ -1120,7 +1124,7 @@ def test_no_cache_when_writeback_diff(self) -> None:
                 "black.write_cache"
             ) as write_cache:
                 self.invokeBlack([str(src), "--diff"])
-                cache_file = black.get_cache_file(mode)
+                cache_file = get_cache_file(mode)
                 self.assertFalse(cache_file.exists())
                 write_cache.assert_not_called()
                 read_cache.assert_not_called()
@@ -1135,7 +1139,7 @@ def test_no_cache_when_writeback_color_diff(self) -> None:
                 "black.write_cache"
             ) as write_cache:
                 self.invokeBlack([str(src), "--diff", "--color"])
-                cache_file = black.get_cache_file(mode)
+                cache_file = get_cache_file(mode)
                 self.assertFalse(cache_file.exists())
                 write_cache.assert_not_called()
                 read_cache.assert_not_called()
@@ -1173,7 +1177,7 @@ def test_no_cache_when_stdin(self) -> None:
                 black.main, ["-"], input=BytesIO(b"print('hello')")
             )
             self.assertEqual(result.exit_code, 0)
-            cache_file = black.get_cache_file(mode)
+            cache_file = get_cache_file(mode)
             self.assertFalse(cache_file.exists())
 
     def test_read_cache_no_cachefile(self) -> None:
@@ -1960,7 +1964,10 @@ def test_find_project_root(self) -> None:
             self.assertEqual(black.find_project_root((src_dir,)), src_dir.resolve())
             self.assertEqual(black.find_project_root((src_python,)), src_dir.resolve())
 
-    @patch("black.find_user_pyproject_toml", black.find_user_pyproject_toml.__wrapped__)
+    @patch(
+        "black.files.find_user_pyproject_toml",
+        black.files.find_user_pyproject_toml.__wrapped__,
+    )
     def test_find_user_pyproject_toml_linux(self) -> None:
         if system() == "Windows":
             return
@@ -1970,7 +1977,7 @@ def test_find_user_pyproject_toml_linux(self) -> None:
             tmp_user_config = Path(workspace) / "black"
             with patch.dict("os.environ", {"XDG_CONFIG_HOME": workspace}):
                 self.assertEqual(
-                    black.find_user_pyproject_toml(), tmp_user_config.resolve()
+                    black.files.find_user_pyproject_toml(), tmp_user_config.resolve()
                 )
 
         # Test fallback for XDG_CONFIG_HOME
@@ -1978,7 +1985,7 @@ def test_find_user_pyproject_toml_linux(self) -> None:
             os.environ.pop("XDG_CONFIG_HOME", None)
             fallback_user_config = Path("~/.config").expanduser() / "black"
             self.assertEqual(
-                black.find_user_pyproject_toml(), fallback_user_config.resolve()
+                black.files.find_user_pyproject_toml(), fallback_user_config.resolve()
             )
 
     def test_find_user_pyproject_toml_windows(self) -> None:
@@ -1986,7 +1993,9 @@ def test_find_user_pyproject_toml_windows(self) -> None:
             return
 
         user_config_path = Path.home() / ".black"
-        self.assertEqual(black.find_user_pyproject_toml(), user_config_path.resolve())
+        self.assertEqual(
+            black.files.find_user_pyproject_toml(), user_config_path.resolve()
+        )
 
     def test_bpo_33660_workaround(self) -> None:
         if system() == "Windows":
diff --git a/tests/test_format.py b/tests/test_format.py
index 78f2b558a4f..e59d5218d2e 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -71,10 +71,27 @@
 
 
 SOURCES = [
-    "tests/test_black.py",
-    "tests/test_format.py",
-    "tests/test_blackd.py",
     "src/black/__init__.py",
+    "src/black/__main__.py",
+    "src/black/brackets.py",
+    "src/black/cache.py",
+    "src/black/comments.py",
+    "src/black/concurrency.py",
+    "src/black/const.py",
+    "src/black/debug.py",
+    "src/black/files.py",
+    "src/black/linegen.py",
+    "src/black/lines.py",
+    "src/black/mode.py",
+    "src/black/nodes.py",
+    "src/black/numerics.py",
+    "src/black/output.py",
+    "src/black/parsing.py",
+    "src/black/report.py",
+    "src/black/rusty.py",
+    "src/black/strings.py",
+    "src/black/trans.py",
+    "src/blackd/__init__.py",
     "src/blib2to3/pygram.py",
     "src/blib2to3/pytree.py",
     "src/blib2to3/pgen2/conv.py",
@@ -86,6 +103,13 @@
     "src/blib2to3/pgen2/tokenize.py",
     "src/blib2to3/pgen2/token.py",
     "setup.py",
+    "tests/test_black.py",
+    "tests/test_blackd.py",
+    "tests/test_format.py",
+    "tests/test_primer.py",
+    "tests/optional.py",
+    "tests/util.py",
+    "tests/conftest.py",
 ]
 
 
diff --git a/tests/util.py b/tests/util.py
index 3670952ba8c..1e86a3f3d78 100644
--- a/tests/util.py
+++ b/tests/util.py
@@ -2,9 +2,12 @@
 import unittest
 from pathlib import Path
 from typing import List, Tuple, Any
-import black
 from functools import partial
 
+import black
+from black.output import out, err
+from black.debug import DebugVisitor
+
 THIS_DIR = Path(__file__).parent
 PROJECT_ROOT = THIS_DIR.parent
 EMPTY_LINE = "# EMPTY LINE WITH WHITESPACE" + " (this comment will be removed)"
@@ -26,21 +29,21 @@ class BlackBaseTestCase(unittest.TestCase):
 
     def assertFormatEqual(self, expected: str, actual: str) -> None:
         if actual != expected and not os.environ.get("SKIP_AST_PRINT"):
-            bdv: black.DebugVisitor[Any]
-            black.out("Expected tree:", fg="green")
+            bdv: DebugVisitor[Any]
+            out("Expected tree:", fg="green")
             try:
                 exp_node = black.lib2to3_parse(expected)
-                bdv = black.DebugVisitor()
+                bdv = DebugVisitor()
                 list(bdv.visit(exp_node))
             except Exception as ve:
-                black.err(str(ve))
-            black.out("Actual tree:", fg="red")
+                err(str(ve))
+            out("Actual tree:", fg="red")
             try:
                 exp_node = black.lib2to3_parse(actual)
-                bdv = black.DebugVisitor()
+                bdv = DebugVisitor()
                 list(bdv.visit(exp_node))
             except Exception as ve:
-                black.err(str(ve))
+                err(str(ve))
         self.assertMultiLineEqual(expected, actual)
 
 

From 036bea4aa0e2b9b3fe50d0d49addc811cce61fa4 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Sat, 8 May 2021 05:34:25 -0400
Subject: [PATCH 0185/1034] Speed up tests even more (#2205)

There's three optimizations in this commit:

1. Don't check if Black's output is stable or equivalant if no changes
   were made in the first place. It's not like passing the same code
   (for both source and actual) through black.assert_equivalent or
   black.assert_stable is useful. It's not a big deal for the smaller
   tests, but it eats a lot of time in tests/test_format.py since
   its test cases are big. This is also closer to how Black works IRL.

2. Use a smaller file for `test_root_logger_not_used_directly` since
   the logging it's checking happens during blib2to3's startup so the
   file doesn't really matter.

3. If we're checking a file is formatting (i.e. test_source_is_formatted)
   don't run Black over it again with `black.format_file_in_place`.
   `tests/test_format.py::TestSimpleFormat.check_file` is good enough.
---
 tests/test_black.py  | 7 ++++---
 tests/test_format.py | 7 +++----
 2 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/tests/test_black.py b/tests/test_black.py
index 29a0731dd9d..347eaf621fe 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -175,8 +175,9 @@ def test_piping(self) -> None:
         )
         self.assertEqual(result.exit_code, 0)
         self.assertFormatEqual(expected, result.output)
-        black.assert_equivalent(source, result.output)
-        black.assert_stable(source, result.output, DEFAULT_MODE)
+        if source != result.output:
+            black.assert_equivalent(source, result.output)
+            black.assert_stable(source, result.output, DEFAULT_MODE)
 
     def test_piping_diff(self) -> None:
         diff_header = re.compile(
@@ -1904,7 +1905,7 @@ def fail(*args: Any, **kwargs: Any) -> None:
             critical=fail,
             log=fail,
         ):
-            ff(THIS_FILE)
+            ff(THIS_DIR / "util.py")
 
     def test_invalid_config_return_code(self) -> None:
         tmp_file = Path(black.dump_to_file())
diff --git a/tests/test_format.py b/tests/test_format.py
index e59d5218d2e..5c78afe0ba6 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -7,7 +7,6 @@
 from tests.util import (
     BlackBaseTestCase,
     fs,
-    ff,
     DEFAULT_MODE,
     dump_to_stderr,
     read_data,
@@ -135,11 +134,11 @@ def test_experimental_format(self, filename: str) -> None:
     def test_source_is_formatted(self, filename: str) -> None:
         path = THIS_DIR.parent / filename
         self.check_file(str(path), DEFAULT_MODE, data=False)
-        self.assertFalse(ff(path))
 
     def check_file(self, filename: str, mode: black.Mode, *, data: bool = True) -> None:
         source, expected = read_data(filename, data=data)
         actual = fs(source, mode=mode)
         self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, mode)
+        if source != actual:
+            black.assert_equivalent(source, actual)
+            black.assert_stable(source, actual, mode)

From 62bfbd6a63dcac2f6f31eb014f69397c9eb967d2 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Sat, 8 May 2021 15:17:38 -0400
Subject: [PATCH 0186/1034] Reorganize docs v2 (GH-2174)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

I know I know, this is the second reorganization of the docs. I'm not
saying the first one was bad or anything... but.. actually wait nah,
*it was bad*.

Anyway, welcome to probably my biggest commit. The main thing with this
reorganization was to introduce nesting to the documentation! Having
all of the docs be part of the main TOC was becoming too much. There
wasn't much room to expand either. Finally, the old setup required
a documentation generation step which was just annoying.

The goals of this reorganization was to:

1. Significantly restructure the docs to be discoverable and
   understandable

2. Add room for further docs (like guides or contributing docs)

3. Get rid of the doc generation step (it was slow and frustrating)

4. Unblock other improvements and also just make contributing to the
   docs easier

Another important change with this is that we are no longer using GitHub
as a documentation host. While GitHub does support Markdown based docs
actually pretty well, the lack of any features outside of GitHub Flavoured
Markdown is quite limiting. ReadTheDocs is just much better suited for
documentation. You can use reST, MyST, CommonMark, and all of their
great features like toctrees and admonitions.

Related to this change, we're adopting MyST as our flavour of Markdown.
MyST introduces neat syntax extensions to Markdown that pretty much
gives us the best of both worlds. The ease of use and simplicity of MD
and the flexibility and expressiveness of reST. Also recommonmark is
deprecated now. This switch was possible now we don't use GH as a docs
host. MyST docs have to be built to really be usable / pretty, so the MD
docs are going to look pretty bad on GH, but that's fine now!

Another thing that should be noted is that the README has been stripped
of most content since it was confusing. Users would read the README and
then think some feature or bug was fixed already and is available in a
release when in reality, they weren't. They were reading effectively
the latest docs without knowing.

See also: https://github.com/psf/black/issues/1759

FYI: CommonMark is a rationalized version of Markdown syntax

--

Commit history before merge:

* Switch to MyST-Parser + doc config cleanup

  recommonmark is being deprecated in favour of MyST-Parser. This change
  is welcomed, especially since MyST-Parser has syntax extensions for the
  Commonmark standard. Effectively we get to use a language that's powerful
  and expressive like ReST, but get the simplicity of Markdown.

  The rest of this effort will be using some MyST features.

  This reorganization efforts aims to remove as much duplication as possible.
  The regeneration step once needed is gone, significantly simplifing our
  Sphinx documentation configuration.

* Tell pipenv we replaced recommonmark for MyST-Parser

  Also update `docs/requirements.txt`

* Delete all auto generated content
* Switch prettier for mdformat (plus a few plugins)

  **FYI: THIS WAS EFFECTIVELY REVERTED, SEE THIRD TO LAST COMMIT**

  prettier doesn't support MyST's syntax extensions which are going to be
  used in this reorganization effort so we have to switch formatter.

  Unfortanately mdformat's style is different from prettier's so time to
  reformat the whole repo too.

  We're excluding .github/ISSUE_TEMPLATE because I have no idea whether
  its changes are safe, so let's play it safe.

* Fix the heading levels in CHANGES.md + a link

  MyST-Parser / sphinx's linkcheck complains otherwise.

* Move reference docs into a docs/contributing dir

  They're for contributors of Black anyway. Also added a note in the
  summary document warning about the lack of attention the reference has
  been dealing with.

* Rewrite and setup the new landing page + main TOC

  - add some more detail about Black's beta status
  - add licensing info
  - add external links in the main TOC for GitHub, PyPI, and IRC
  - prepare main TOC for new structure

* Break out AUTHORS into its own file

  Not only was the AUTHORS list quite long, this makes it easy to include
  it in the Sphinx docs with just a simple symlink.

* Add license to docs via a simple include

  Yes the document is orphaned but it is linked to in the landing page
  (docs/index.rst).

* Add "The Black Code Style" section

  This mostly was a restructuring commit, there has been a few updates but
  not many. The main goal was to split "current style" and "planned
  changes to the style that haven't happened yet" to avoid confusion.

* Add "Getting Started" page

  This is basically a quick start + even more. This commit is certainly
  one of most creatively involved in this effort.

* Add "Usage and Configuration" section

  This commit was as much restructuring as new content. Instead of being
  in one giant file, usage and configuration documentation can expand
  without bloating a single file.

* Add "Integrations" section

Just a restructuring commit ...

* Add "Guides" section

  This is a promising area of documentation that could easily grow in the
  future, let's prepare for that!

* Add "Contributing" section

  This is also another area that I expect to see significant growth in.
  Contributors to Black could definitely do with some more specific docs
  that clears up certain parts of our slightly confusing project (it's
  only confusing because we're getting big and old!).

* Rewrite CONTRIBUTING.md to just point to RTD
* Rewrite README.md to delegate most info to RTD
* Address feedback + a lot of corrections and edits

  I know I said I wanted to do these after landing this but given there's
  going to be no time between this being merged and a release getting
  pushed, I want these changes to make it in.

  - drop the number flag for mdformat - to reduce diffs, see also:
    https://mdformat.readthedocs.io/en/stable/users/style.html#ordered-lists
  - the GH issue templates should be safe by mdformat, so get rid of the
    exclude
  - clarify our configuration position - i.e. stop claiming we don't have
    many options, instead say we want as little formatting knobs as
    possible
  - lots and lots of punctuation, spelling, and grammar corrections (thanks
    Jelle!)
  - use RTD as the source for the CHANGELOG too
  - visual style cleanups
  - add docs about our .gitignore behaviour
  - expand GHA Action docs
  - clarify we want the PR number in the CHANGELOG entry
  - claify Black's behaviour for with statements post Python 3.9
  - italicize a bunch of "Black"s

  Thank you goes to Jelle, Taneli (hukkinj1 on GH), Felix
  (felix-hilden on GH), and Wouter (wbolster on GH) for the feedback!

* Merge remote-tracking branch 'upstream/master' into reorganize-docs-v2

  merge conflicts suck, although these ones weren't too bad.

* Add changelog entry + fix merge conflict resolution error

  I consider this important enough to be worthy of a changelog entry :)

* Merge branch 'master' into reorganize-docs-v2

  Co-authored-by: Łukasz Langa <lukasz@langa.pl>

* Actually let's continue using prettier

  Prettier works fine for all of the default MyST syntax so let's not
  rock the boat as much. Dropping the mdformat commit was merge-conflict
  filled so here's additional commit instead.

* Address Cooper's, Taneli's, and Jelle's feedback

  Lots of wording improvements by Cooper. Taneli suggested to disable the
  enabled by default MyST syntax not supported by Prettier and I agreed.
  And Jelle found one more spelling error!

* More minor fixes
---
 .github/ISSUE_TEMPLATE/bug_report.md          |  14 +-
 .github/ISSUE_TEMPLATE/feature_request.md     |   2 +-
 AUTHORS.md                                    | 184 ++++++
 CHANGES.md                                    |  94 +--
 CONTRIBUTING.md                               | 114 +---
 Pipfile                                       |   2 +-
 Pipfile.lock                                  | 131 +++-
 README.md                                     | 621 ++----------------
 docs/authors.md                               | 188 +-----
 docs/black_primer.md                          | 120 ----
 docs/conf.py                                  | 229 +------
 docs/contributing/gauging_changes.md          |  61 ++
 docs/contributing/index.rst                   |  39 ++
 .../reference/reference_classes.rst           |   0
 .../reference/reference_exceptions.rst        |   0
 .../reference/reference_functions.rst         |   0
 .../reference/reference_summary.rst           |   5 +
 .../the_basics.md}                            |  35 +-
 docs/getting_started.md                       |  49 ++
 docs/github_actions.md                        |  27 -
 docs/guides/index.rst                         |  14 +
 .../introducing_black_to_your_project.md      |  50 ++
 .../using_black_with_other_tools.md}          |  36 +-
 docs/index.rst                                |  85 ++-
 docs/installation_and_usage.md                | 195 ------
 .../editors.md}                               |  52 +-
 docs/integrations/github_actions.md           |  35 +
 docs/integrations/index.rst                   |  28 +
 docs/integrations/source_version_control.md   |  14 +
 docs/license.rst                              |   6 +
 docs/pyproject_toml.md                        |  91 ---
 docs/requirements.txt                         |   5 +-
 docs/show_your_style.md                       |  19 -
 .../current_style.md}                         |  59 +-
 docs/the_black_code_style/future_style.md     |  35 +
 docs/the_black_code_style/index.rst           |  19 +
 .../black_as_a_server.md}                     |   6 +-
 .../file_collection_and_discovery.md}         |  18 +-
 docs/usage_and_configuration/index.rst        |  24 +
 docs/usage_and_configuration/the_basics.md    | 227 +++++++
 docs/version_control_integration.md           |  28 -
 41 files changed, 1200 insertions(+), 1761 deletions(-)
 create mode 100644 AUTHORS.md
 mode change 100644 => 120000 docs/authors.md
 delete mode 100644 docs/black_primer.md
 create mode 100644 docs/contributing/gauging_changes.md
 create mode 100644 docs/contributing/index.rst
 rename docs/{ => contributing}/reference/reference_classes.rst (100%)
 rename docs/{ => contributing}/reference/reference_exceptions.rst (100%)
 rename docs/{ => contributing}/reference/reference_functions.rst (100%)
 rename docs/{ => contributing}/reference/reference_summary.rst (51%)
 rename docs/{contributing_to_black.md => contributing/the_basics.md} (68%)
 create mode 100644 docs/getting_started.md
 delete mode 100644 docs/github_actions.md
 create mode 100644 docs/guides/index.rst
 create mode 100644 docs/guides/introducing_black_to_your_project.md
 rename docs/{compatible_configs.md => guides/using_black_with_other_tools.md} (92%)
 delete mode 100644 docs/installation_and_usage.md
 rename docs/{editor_integration.md => integrations/editors.md} (85%)
 create mode 100644 docs/integrations/github_actions.md
 create mode 100644 docs/integrations/index.rst
 create mode 100644 docs/integrations/source_version_control.md
 create mode 100644 docs/license.rst
 delete mode 100644 docs/pyproject_toml.md
 delete mode 100644 docs/show_your_style.md
 rename docs/{the_black_code_style.md => the_black_code_style/current_style.md} (91%)
 create mode 100644 docs/the_black_code_style/future_style.md
 create mode 100644 docs/the_black_code_style/index.rst
 rename docs/{blackd.md => usage_and_configuration/black_as_a_server.md} (98%)
 rename docs/{ignoring_unmodified_files.md => usage_and_configuration/file_collection_and_discovery.md} (61%)
 create mode 100644 docs/usage_and_configuration/index.rst
 create mode 100644 docs/usage_and_configuration/the_basics.md
 delete mode 100644 docs/version_control_integration.md

diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
index f4a438622aa..3b59906594a 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -11,21 +11,21 @@ assignees: ""
 **To Reproduce** Steps to reproduce the behavior:
 
 1. Take this file '...'
-2. Run _Black_ on it with these arguments '....'
-3. See error
+1. Run _Black_ on it with these arguments '....'
+1. See error
 
 **Expected behavior** A clear and concise description of what you expected to happen.
 
 **Environment (please complete the following information):**
 
-- Version: [e.g. master]
-- OS and Python version: [e.g. Linux/Python 3.7.4rc1]
+- Version: \[e.g. master\]
+- OS and Python version: \[e.g. Linux/Python 3.7.4rc1\]
 
 **Does this bug also happen on master?** To answer this, you have two options:
 
-1. Use the online formatter at https://black.now.sh/?version=master, which will use the
-   latest master branch.
-2. Or run _Black_ on your machine:
+1. Use the online formatter at <https://black.vercel.app/?version=master>, which will
+   use the latest master branch.
+1. Or run _Black_ on your machine:
    - create a new virtualenv (make sure it's the same Python version);
    - clone this repository;
    - run `pip install -e .[d,python2]`;
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
index 00dd5dd8fe5..56c2f0d0185 100644
--- a/.github/ISSUE_TEMPLATE/feature_request.md
+++ b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -7,7 +7,7 @@ assignees: ""
 ---
 
 **Is your feature request related to a problem? Please describe.** A clear and concise
-description of what the problem is. Ex. I'm always frustrated when [...]
+description of what the problem is. Ex. I'm always frustrated when \[...\]
 
 **Describe the solution you'd like** A clear and concise description of what you want to
 happen.
diff --git a/AUTHORS.md b/AUTHORS.md
new file mode 100644
index 00000000000..cb79dec3de3
--- /dev/null
+++ b/AUTHORS.md
@@ -0,0 +1,184 @@
+# Authors
+
+Glued together by [Łukasz Langa](mailto:lukasz@langa.pl).
+
+Maintained with [Carol Willing](mailto:carolcode@willingconsulting.com),
+[Carl Meyer](mailto:carl@oddbird.net),
+[Jelle Zijlstra](mailto:jelle.zijlstra@gmail.com),
+[Mika Naylor](mailto:mail@autophagy.io),
+[Zsolt Dollenstein](mailto:zsol.zsol@gmail.com),
+[Cooper Lees](mailto:me@cooperlees.com), and Richard Si.
+
+Multiple contributions by:
+
+- [Abdur-Rahmaan Janhangeer](mailto:arj.python@gmail.com)
+- [Adam Johnson](mailto:me@adamj.eu)
+- [Adam Williamson](mailto:adamw@happyassassin.net)
+- [Alexander Huynh](mailto:github@grande.coffee)
+- [Alex Vandiver](mailto:github@chmrr.net)
+- [Allan Simon](mailto:allan.simon@supinfo.com)
+- Anders-Petter Ljungquist
+- [Andrew Thorp](mailto:andrew.thorp.dev@gmail.com)
+- [Andrew Zhou](mailto:andrewfzhou@gmail.com)
+- [Andrey](mailto:dyuuus@yandex.ru)
+- [Andy Freeland](mailto:andy@andyfreeland.net)
+- [Anthony Sottile](mailto:asottile@umich.edu)
+- [Arjaan Buijk](mailto:arjaan.buijk@gmail.com)
+- [Arnav Borbornah](mailto:arnavborborah11@gmail.com)
+- [Artem Malyshev](mailto:proofit404@gmail.com)
+- [Asger Hautop Drewsen](mailto:asgerdrewsen@gmail.com)
+- [Augie Fackler](mailto:raf@durin42.com)
+- [Aviskar KC](mailto:aviskarkc10@gmail.com)
+- Batuhan Taşkaya
+- [Benjamin Wohlwend](mailto:bw@piquadrat.ch)
+- [Benjamin Woodruff](mailto:github@benjam.info)
+- [Bharat Raghunathan](mailto:bharatraghunthan9767@gmail.com)
+- [Brandt Bucher](mailto:brandtbucher@gmail.com)
+- [Brett Cannon](mailto:brett@python.org)
+- [Bryan Bugyi](mailto:bryan.bugyi@rutgers.edu)
+- [Bryan Forbes](mailto:bryan@reigndropsfall.net)
+- [Calum Lind](mailto:calumlind@gmail.com)
+- [Charles](mailto:peacech@gmail.com)
+- Charles Reid
+- [Christian Clauss](mailto:cclauss@bluewin.ch)
+- [Christian Heimes](mailto:christian@python.org)
+- [Chuck Wooters](mailto:chuck.wooters@microsoft.com)
+- [Chris Rose](mailto:offline@offby1.net)
+- Codey Oxley
+- [Cong](mailto:congusbongus@gmail.com)
+- [Cooper Ry Lees](mailto:me@cooperlees.com)
+- [Dan Davison](mailto:dandavison7@gmail.com)
+- [Daniel Hahler](mailto:github@thequod.de)
+- [Daniel M. Capella](mailto:polycitizen@gmail.com)
+- Daniele Esposti
+- [David Hotham](mailto:david.hotham@metaswitch.com)
+- [David Lukes](mailto:dafydd.lukes@gmail.com)
+- [David Szotten](mailto:davidszotten@gmail.com)
+- [Denis Laxalde](mailto:denis@laxalde.org)
+- [Douglas Thor](mailto:dthor@transphormusa.com)
+- dylanjblack
+- [Eli Treuherz](mailto:eli@treuherz.com)
+- [Emil Hessman](mailto:emil@hessman.se)
+- [Felix Kohlgrüber](mailto:felix.kohlgrueber@gmail.com)
+- [Florent Thiery](mailto:fthiery@gmail.com)
+- Francisco
+- [Giacomo Tagliabue](mailto:giacomo.tag@gmail.com)
+- [Greg Gandenberger](mailto:ggandenberger@shoprunner.com)
+- [Gregory P. Smith](mailto:greg@krypto.org)
+- Gustavo Camargo
+- hauntsaninja
+- [Hadi Alqattan](mailto:alqattanhadizaki@gmail.com)
+- [Heaford](mailto:dan@heaford.com)
+- [Hugo Barrera](mailto::hugo@barrera.io)
+- Hugo van Kemenade
+- [Hynek Schlawack](mailto:hs@ox.cx)
+- [Ivan Katanić](mailto:ivan.katanic@gmail.com)
+- [Jakub Kadlubiec](mailto:jakub.kadlubiec@skyscanner.net)
+- [Jakub Warczarek](mailto:jakub.warczarek@gmail.com)
+- [Jan Hnátek](mailto:jan.hnatek@gmail.com)
+- [Jason Fried](mailto:me@jasonfried.info)
+- [Jason Friedland](mailto:jason@friedland.id.au)
+- [jgirardet](mailto:ijkl@netc.fr)
+- Jim Brännlund
+- [Jimmy Jia](mailto:tesrin@gmail.com)
+- [Joe Antonakakis](mailto:jma353@cornell.edu)
+- [Jon Dufresne](mailto:jon.dufresne@gmail.com)
+- [Jonas Obrist](mailto:ojiidotch@gmail.com)
+- [Jonty Wareing](mailto:jonty@jonty.co.uk)
+- [Jose Nazario](mailto:jose.monkey.org@gmail.com)
+- [Joseph Larson](mailto:larson.joseph@gmail.com)
+- [Josh Bode](mailto:joshbode@fastmail.com)
+- [Josh Holland](mailto:anowlcalledjosh@gmail.com)
+- [Joshua Cannon](mailto:joshdcannon@gmail.com)
+- [José Padilla](mailto:jpadilla@webapplicate.com)
+- [Juan Luis Cano Rodríguez](mailto:hello@juanlu.space)
+- [kaiix](mailto:kvn.hou@gmail.com)
+- [Katie McLaughlin](mailto:katie@glasnt.com)
+- Katrin Leinweber
+- [Keith Smiley](mailto:keithbsmiley@gmail.com)
+- [Kenyon Ralph](mailto:kenyon@kenyonralph.com)
+- [Kevin Kirsche](mailto:Kev.Kirsche+GitHub@gmail.com)
+- [Kyle Hausmann](mailto:kyle.hausmann@gmail.com)
+- [Kyle Sunden](mailto:sunden@wisc.edu)
+- Lawrence Chan
+- [Linus Groh](mailto:mail@linusgroh.de)
+- [Loren Carvalho](mailto:comradeloren@gmail.com)
+- [Luka Sterbic](mailto:luka.sterbic@gmail.com)
+- [LukasDrude](mailto:mail@lukas-drude.de)
+- Mahmoud Hossam
+- Mariatta
+- [Matt VanEseltine](mailto:vaneseltine@gmail.com)
+- [Matthew Clapp](mailto:itsayellow+dev@gmail.com)
+- [Matthew Walster](mailto:matthew@walster.org)
+- Max Smolens
+- [Michael Aquilina](mailto:michaelaquilina@gmail.com)
+- [Michael Flaxman](mailto:michael.flaxman@gmail.com)
+- [Michael J. Sullivan](mailto:sully@msully.net)
+- [Michael McClimon](mailto:michael@mcclimon.org)
+- [Miguel Gaiowski](mailto:miggaiowski@gmail.com)
+- [Mike](mailto:roshi@fedoraproject.org)
+- [mikehoyio](mailto:mikehoy@gmail.com)
+- [Min ho Kim](mailto:minho42@gmail.com)
+- [Miroslav Shubernetskiy](mailto:miroslav@miki725.com)
+- MomIsBestFriend
+- [Nathan Goldbaum](mailto:ngoldbau@illinois.edu)
+- [Nathan Hunt](mailto:neighthan.hunt@gmail.com)
+- [Neraste](mailto:neraste.herr10@gmail.com)
+- [Nikolaus Waxweiler](mailto:madigens@gmail.com)
+- [Ofek Lev](mailto:ofekmeister@gmail.com)
+- [Osaetin Daniel](mailto:osaetindaniel@gmail.com)
+- [otstrel](mailto:otstrel@gmail.com)
+- [Pablo Galindo](mailto:Pablogsal@gmail.com)
+- [Paul Ganssle](mailto:p.ganssle@gmail.com)
+- [Paul Meinhardt](mailto:mnhrdt@gmail.com)
+- [Peter Bengtsson](mailto:mail@peterbe.com)
+- [Peter Grayson](mailto:pete@jpgrayson.net)
+- [Peter Stensmyr](mailto:peter.stensmyr@gmail.com)
+- pmacosta
+- [Quentin Pradet](mailto:quentin@pradet.me)
+- [Ralf Schmitt](mailto:ralf@systemexit.de)
+- [Ramón Valles](mailto:mroutis@protonmail.com)
+- [Richard Fearn](mailto:richardfearn@gmail.com)
+- [Rishikesh Jha](mailto:rishijha424@gmail.com)
+- [Rupert Bedford](mailto:rupert@rupertb.com)
+- Russell Davis
+- [Rémi Verschelde](mailto:rverschelde@gmail.com)
+- [Sami Salonen](mailto:sakki@iki.fi)
+- [Samuel Cormier-Iijima](mailto:samuel@cormier-iijima.com)
+- [Sanket Dasgupta](mailto:sanketdasgupta@gmail.com)
+- Sergi
+- [Scott Stevenson](mailto:scott@stevenson.io)
+- Shantanu
+- [shaoran](mailto:shaoran@sakuranohana.org)
+- [Shinya Fujino](mailto:shf0811@gmail.com)
+- springstan
+- [Stavros Korokithakis](mailto:hi@stavros.io)
+- [Stephen Rosen](mailto:sirosen@globus.org)
+- [Steven M. Vascellaro](mailto:S.Vascellaro@gmail.com)
+- [Sunil Kapil](mailto:snlkapil@gmail.com)
+- [Sébastien Eustace](mailto:sebastien.eustace@gmail.com)
+- [Tal Amuyal](mailto:TalAmuyal@gmail.com)
+- [Terrance](mailto:git@terrance.allofti.me)
+- [Thom Lu](mailto:thomas.c.lu@gmail.com)
+- [Thomas Grainger](mailto:tagrain@gmail.com)
+- [Tim Gates](mailto:tim.gates@iress.com)
+- [Tim Swast](mailto:swast@google.com)
+- [Timo](mailto:timo_tk@hotmail.com)
+- Toby Fleming
+- [Tom Christie](mailto:tom@tomchristie.com)
+- [Tony Narlock](mailto:tony@git-pull.com)
+- [Tsuyoshi Hombashi](mailto:tsuyoshi.hombashi@gmail.com)
+- [Tushar Chandra](mailto:tusharchandra2018@u.northwestern.edu)
+- [Tzu-ping Chung](mailto:uranusjr@gmail.com)
+- [Utsav Shah](mailto:ukshah2@illinois.edu)
+- utsav-dbx
+- vezeli
+- [Ville Skyttä](mailto:ville.skytta@iki.fi)
+- [Vishwas B Sharma](mailto:sharma.vishwas88@gmail.com)
+- [Vlad Emelianov](mailto:volshebnyi@gmail.com)
+- [williamfzc](mailto:178894043@qq.com)
+- [wouter bolsterlee](mailto:wouter@bolsterl.ee)
+- Yazdan
+- [Yngve Høiseth](mailto:yngve@hoiseth.net)
+- [Yurii Karabas](mailto:1998uriyyo@gmail.com)
+- [Zac Hatfield-Dodds](mailto:zac@zhd.dev)
diff --git a/CHANGES.md b/CHANGES.md
index 8cbdeca44f7..9b155924b7d 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,26 +1,32 @@
-## Change Log
+# Change Log
 
-### Unreleased
+## Unreleased
 
-#### _Black_
+### _Black_
 
 - Refactor `src/black/__init__.py` into many files (#2206)
 
-### 21.5b0
+### Documentation
 
-#### _Black_
+- Sigificantly 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)
+
+## 21.5b0
+
+### _Black_
 
 - Set `--pyi` mode if `--stdin-filename` ends in `.pyi` (#2169)
 - Stop detecting target version as Python 3.9+ with pre-PEP-614 decorators that are
   being called but with no arguments (#2182)
 
-#### _Black-Primer_
+### _Black-Primer_
 
 - Add `--no-diff` to black-primer to suppress formatting changes (#2187)
 
-### 21.4b2
+## 21.4b2
 
-#### _Black_
+### _Black_
 
 - Fix crash if the user configuration directory is inaccessible. (#2158)
 
@@ -31,15 +37,15 @@
 - Allow `.gitignore` rules to be overridden by specifying `exclude` in `pyproject.toml`
   or on the command line. (#2170)
 
-#### _Packaging_
+### _Packaging_
 
 - Install `primer.json` (used by `black-primer` by default) with black. (#2154)
 
-### 21.4b1
+## 21.4b1
 
-#### _Black_
+### _Black_
 
-- Fix crash on docstrings ending with "\ ". (#2142)
+- Fix crash on docstrings ending with "\\ ". (#2142)
 
 - Fix crash when atypical whitespace is cleaned out of dostrings (#2120)
 
@@ -50,13 +56,13 @@
 - Don't remove necessary parentheses from assignment expression containing assert /
   return statements. (#2143)
 
-#### _Packaging_
+### _Packaging_
 
 - Bump pathspec to >= 0.8.1 to solve invalid .gitignore exclusion handling
 
-### 21.4b0
+## 21.4b0
 
-#### _Black_
+### _Black_
 
 - Fixed a rare but annoying formatting instability created by the combination of
   optional trailing commas inserted by `Black` and optional parentheses looking at
@@ -112,21 +118,21 @@
 - Fixed "Black produced code that is not equivalent to the source" when formatting
   Python 2 docstrings (#2037)
 
-#### _Packaging_
+### _Packaging_
 
 - Self-contained native _Black_ binaries are now provided for releases via GitHub
   Releases (#1743)
 
-### 20.8b1
+## 20.8b1
 
-#### _Packaging_
+### _Packaging_
 
 - explicitly depend on Click 7.1.2 or newer as `Black` no longer works with versions
   older than 7.0
 
-### 20.8b0
+## 20.8b0
 
-#### _Black_
+### _Black_
 
 - re-implemented support for explicit trailing commas: now it works consistently within
   any bracket pair, including nested structures (#1288 and duplicates)
@@ -170,11 +176,11 @@
   this is an undocumented and unsupported feature, you lose Internet points for
   depending on it (#1609)
 
-#### Vim plugin
+### Vim plugin
 
 - prefer virtualenv packages over global packages (#1383)
 
-### 19.10b0
+## 19.10b0
 
 - added support for PEP 572 assignment expressions (#711)
 
@@ -233,7 +239,7 @@
 - `blackd` can now output the diff of formats on source code when the `X-Diff` header is
   provided (#969)
 
-### 19.3b0
+## 19.3b0
 
 - new option `--target-version` to control which Python versions _Black_-formatted code
   should target (#618)
@@ -258,7 +264,7 @@
 
 - `blackd` now supports CORS (#622)
 
-### 18.9b0
+## 18.9b0
 
 - numeric literals are now formatted by _Black_ (#452, #461, #464, #469):
 
@@ -273,7 +279,9 @@
 
   - hexadecimal digits are always uppercased (e.g. `0xBADC0DE`)
 
-- added `blackd`, see [its documentation](#blackd) for more info (#349)
+- added `blackd`, see
+  [its documentation](https://github.com/psf/black/blob/18.9b0/README.md#blackd) for
+  more info (#349)
 
 - adjacent string literals are now correctly split into multiple lines (#463)
 
@@ -300,11 +308,11 @@
 - note: the Vim plugin stopped registering `,=` as a default chord as it turned out to
   be a bad idea (#415)
 
-### 18.6b4
+## 18.6b4
 
 - hotfix: don't freeze when multiple comments directly precede `# fmt: off` (#371)
 
-### 18.6b3
+## 18.6b3
 
 - typing stub files (`.pyi`) now have blank lines added after constants (#340)
 
@@ -332,7 +340,7 @@
 
 - fixed a crash due to symbolic links pointing outside of the project directory (#338)
 
-### 18.6b2
+## 18.6b2
 
 - added `--config` (#65)
 
@@ -346,13 +354,13 @@
 
 - fixed unnecessary slowdown in comment placement calculation on lines without comments
 
-### 18.6b1
+## 18.6b1
 
 - hotfix: don't output human-facing information on stdout (#299)
 
 - hotfix: don't output cake emoji on non-zero return code (#300)
 
-### 18.6b0
+## 18.6b0
 
 - added `--include` and `--exclude` (#270)
 
@@ -370,7 +378,7 @@
 
 - _Black_ now preserves line endings when formatting a file in place (#258)
 
-### 18.5b1
+## 18.5b1
 
 - added `--pyi` (#249)
 
@@ -399,7 +407,7 @@
 - fixed extra empty line between a function signature and an inner function or inner
   class (#196)
 
-### 18.5b0
+## 18.5b0
 
 - call chains are now formatted according to the
   [fluent interfaces](https://en.wikipedia.org/wiki/Fluent_interface) style (#67)
@@ -454,11 +462,11 @@
 
 - fixed crash when dead symlinks where encountered
 
-### 18.4a4
+## 18.4a4
 
 - don't populate the cache on `--check` (#175)
 
-### 18.4a3
+## 18.4a3
 
 - added a "cache"; files already reformatted that haven't changed on disk won't be
   reformatted again (#109)
@@ -486,7 +494,7 @@
 
 - fixed missing splits of ternary expressions (#141)
 
-### 18.4a2
+## 18.4a2
 
 - fixed parsing of unaligned standalone comments (#99, #112)
 
@@ -497,7 +505,7 @@
 - fixed unstable formatting when encountering unnecessarily escaped quotes in a string
   (#120)
 
-### 18.4a1
+## 18.4a1
 
 - added `--quiet` (#78)
 
@@ -509,7 +517,7 @@
 
 - fixed removing backslash escapes from raw strings (#100, #105)
 
-### 18.4a0
+## 18.4a0
 
 - added `--diff` (#87)
 
@@ -534,7 +542,7 @@
 - only allow up to two empty lines on module level and only single empty lines within
   functions (#74)
 
-### 18.3a4
+## 18.3a4
 
 - `# fmt: off` and `# fmt: on` are implemented (#5)
 
@@ -556,7 +564,7 @@
   [Sphinx auto-attribute comments](http://www.sphinx-doc.org/en/stable/ext/autodoc.html#directive-autoattribute)
   (#68)
 
-### 18.3a3
+## 18.3a3
 
 - don't remove single empty lines outside of bracketed expressions (#19)
 
@@ -566,7 +574,7 @@
 
 - even better handling of numpy-style array indexing (#33, again)
 
-### 18.3a2
+## 18.3a2
 
 - changed positioning of binary operators to occur at beginning of lines instead of at
   the end, following
@@ -590,7 +598,7 @@
 
 - fixed spurious space after star-based unary expressions (#31)
 
-### 18.3a1
+## 18.3a1
 
 - added `--check`
 
@@ -609,10 +617,10 @@
 - fixed spurious space after unary operators when the operand was a complex expression
   (#15)
 
-### 18.3a0
+## 18.3a0
 
 - first published version, Happy 🍰 Day 2018!
 
 - alpha quality
 
-- date-versioned (see: https://calver.org/)
+- date-versioned (see: <https://calver.org/>)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index f2a4ee20c99..10f60422f04 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -3,114 +3,8 @@
 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?
 
-## Bird's eye view
+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_.
 
-In terms of inspiration, _Black_ is about as configurable as _gofmt_. This is
-deliberate.
-
-Bug reports and fixes are always welcome! Please follow the
-[issue template on GitHub](https://github.com/psf/black/issues/new) 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
-up, and so on - go for it! On the other hand, if your answer is "because I don't like a
-particular formatting" then you're not ready to embrace _Black_ yet. Such changes are
-unlikely to get accepted. You can still try but prepare to be disappointed.
-
-## Technicalities
-
-Development on the latest version of Python is preferred. As of this writing it's 3.9.
-You can use any operating system. I am using macOS myself and CentOS at work.
-
-Install all development dependencies using:
-
-```console
-$ pipenv install --dev
-$ pipenv shell
-$ pre-commit install
-```
-
-If you haven't used `pipenv` before but are comfortable with virtualenvs, just run
-`pip install pipenv` in the virtualenv you're already using and invoke the command above
-from the cloned _Black_ repo. It will do the correct thing.
-
-Non pipenv install works too:
-
-```console
-$ pip install -r test_requirements
-$ pip install -e .[d]
-```
-
-Before submitting pull requests, run lints and tests with the following commands from
-the root of the black repo:
-
-```console
-# Linting
-$ pre-commit run -a
-
-# Unit tests
-$ tox -e py
-
-# Optional Fuzz testing
-$ tox -e fuzz
-
-# Optional CI run to test your changes on many popular python projects
-$ black-primer [-k -w /tmp/black_test_repos]
-```
-
-### News / Changelog Requirement
-
-`Black` has CI that will check for an entry corresponding to your PR in `CHANGES.md`. If
-you feel this PR 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:
-
-```md
-- `Black` is now more awesome (#X)
-```
-
-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.
-
-### 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.
-
-### Docs Testing
-
-If you make changes to docs, you can test they still build locally too.
-
-```console
-$ pip install -r docs/requirements.txt
-$ pip install [-e] .[d]
-$ sphinx-build -a -b html -W docs/ docs/_build/
-```
-
-## black-primer
-
-`black-primer` is used by CI to pull down well-known _Black_ formatted projects and see
-if we get source code changes. It will error on formatting changes or errors. Please run
-before pushing your PR to see if you get the actions you would expect from _Black_ with
-your PR. You may need to change
-[primer.json](https://github.com/psf/black/blob/master/src/black_primer/primer.json)
-configuration for it to pass.
-
-For more `black-primer` information visit the
-[documentation](https://github.com/psf/black/blob/master/docs/black_primer.md).
-
-## 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.
-
-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.
-
-## Finally
-
-Thanks again for your interest in improving the project! You're taking action when most
-people decide to sit and watch.
+We look forward to your contributions!
diff --git a/Pipfile b/Pipfile
index 68562f5e53f..d1842ff749b 100644
--- a/Pipfile
+++ b/Pipfile
@@ -12,7 +12,7 @@ flake8-bugbear = "*"
 mypy = ">=0.812"
 pre-commit = "*"
 readme_renderer = "*"
-recommonmark = "*"
+MyST-Parser = ">=0.13.7"
 setuptools = ">=39.2.0"
 setuptools-scm = "*"
 twine = ">=1.11.0"
diff --git a/Pipfile.lock b/Pipfile.lock
index 8a16a75026a..f973c8423e8 100644
--- a/Pipfile.lock
+++ b/Pipfile.lock
@@ -1,7 +1,7 @@
 {
     "_meta": {
         "hash": {
-            "sha256": "1b075e0e344dad54944ed4474351c3f311accb67cbea2e0c381da3700b71f415"
+            "sha256": "62bc4bdb0117234d1f374b2dc0685369f6df7c7192d16409cc9c42a429770166"
         },
         "pipfile-spec": 6,
         "requires": {},
@@ -428,11 +428,11 @@
         },
         "babel": {
             "hashes": [
-                "sha256:9d35c22fcc79893c3ecc85ac4a56cde1ecf3f19c540bba0922308a6c06ca6fa5",
-                "sha256:da031ab54472314f210b0adcff1588ee5d1d1d0ba4dbd07b94dba82bde791e05"
+                "sha256:ab49e12b91d937cd11f0b67cb259a57ab4ad2b59ac7a3b41d6c06c0ac5b0def9",
+                "sha256:bc0c176f9f6a994582230df350aa6e05ba2ebe4b3ac317eab29d9be5d2768da0"
             ],
             "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==2.9.0"
+            "version": "==2.9.1"
         },
         "black": {
             "editable": true,
@@ -456,6 +456,48 @@
             ],
             "version": "==2020.12.5"
         },
+        "cffi": {
+            "hashes": [
+                "sha256:005a36f41773e148deac64b08f233873a4d0c18b053d37da83f6af4d9087b813",
+                "sha256:0857f0ae312d855239a55c81ef453ee8fd24136eaba8e87a2eceba644c0d4c06",
+                "sha256:1071534bbbf8cbb31b498d5d9db0f274f2f7a865adca4ae429e147ba40f73dea",
+                "sha256:158d0d15119b4b7ff6b926536763dc0714313aa59e320ddf787502c70c4d4bee",
+                "sha256:1f436816fc868b098b0d63b8920de7d208c90a67212546d02f84fe78a9c26396",
+                "sha256:2894f2df484ff56d717bead0a5c2abb6b9d2bf26d6960c4604d5c48bbc30ee73",
+                "sha256:29314480e958fd8aab22e4a58b355b629c59bf5f2ac2492b61e3dc06d8c7a315",
+                "sha256:34eff4b97f3d982fb93e2831e6750127d1355a923ebaeeb565407b3d2f8d41a1",
+                "sha256:35f27e6eb43380fa080dccf676dece30bef72e4a67617ffda586641cd4508d49",
+                "sha256:3d3dd4c9e559eb172ecf00a2a7517e97d1e96de2a5e610bd9b68cea3925b4892",
+                "sha256:43e0b9d9e2c9e5d152946b9c5fe062c151614b262fda2e7b201204de0b99e482",
+                "sha256:48e1c69bbacfc3d932221851b39d49e81567a4d4aac3b21258d9c24578280058",
+                "sha256:51182f8927c5af975fece87b1b369f722c570fe169f9880764b1ee3bca8347b5",
+                "sha256:58e3f59d583d413809d60779492342801d6e82fefb89c86a38e040c16883be53",
+                "sha256:5de7970188bb46b7bf9858eb6890aad302577a5f6f75091fd7cdd3ef13ef3045",
+                "sha256:65fa59693c62cf06e45ddbb822165394a288edce9e276647f0046e1ec26920f3",
+                "sha256:69e395c24fc60aad6bb4fa7e583698ea6cc684648e1ffb7fe85e3c1ca131a7d5",
+                "sha256:6c97d7350133666fbb5cf4abdc1178c812cb205dc6f41d174a7b0f18fb93337e",
+                "sha256:6e4714cc64f474e4d6e37cfff31a814b509a35cb17de4fb1999907575684479c",
+                "sha256:72d8d3ef52c208ee1c7b2e341f7d71c6fd3157138abf1a95166e6165dd5d4369",
+                "sha256:8ae6299f6c68de06f136f1f9e69458eae58f1dacf10af5c17353eae03aa0d827",
+                "sha256:8b198cec6c72df5289c05b05b8b0969819783f9418e0409865dac47288d2a053",
+                "sha256:99cd03ae7988a93dd00bcd9d0b75e1f6c426063d6f03d2f90b89e29b25b82dfa",
+                "sha256:9cf8022fb8d07a97c178b02327b284521c7708d7c71a9c9c355c178ac4bbd3d4",
+                "sha256:9de2e279153a443c656f2defd67769e6d1e4163952b3c622dcea5b08a6405322",
+                "sha256:9e93e79c2551ff263400e1e4be085a1210e12073a31c2011dbbda14bda0c6132",
+                "sha256:9ff227395193126d82e60319a673a037d5de84633f11279e336f9c0f189ecc62",
+                "sha256:a465da611f6fa124963b91bf432d960a555563efe4ed1cc403ba5077b15370aa",
+                "sha256:ad17025d226ee5beec591b52800c11680fca3df50b8b29fe51d882576e039ee0",
+                "sha256:afb29c1ba2e5a3736f1c301d9d0abe3ec8b86957d04ddfa9d7a6a42b9367e396",
+                "sha256:b85eb46a81787c50650f2392b9b4ef23e1f126313b9e0e9013b35c15e4288e2e",
+                "sha256:bb89f306e5da99f4d922728ddcd6f7fcebb3241fc40edebcb7284d7514741991",
+                "sha256:cbde590d4faaa07c72bf979734738f328d239913ba3e043b1e98fe9a39f8b2b6",
+                "sha256:cd2868886d547469123fadc46eac7ea5253ea7fcb139f12e1dfc2bbd406427d1",
+                "sha256:d42b11d692e11b6634f7613ad8df5d6d5f8875f5d48939520d351007b3c13406",
+                "sha256:f2d45f97ab6bb54753eab54fffe75aaf3de4ff2341c9daee1987ee1837636f1d",
+                "sha256:fd78e5fee591709f32ef6edb9a015b4aa1a5022598e36227500c8f4e02328d9c"
+            ],
+            "version": "==1.14.5"
+        },
         "cfgv": {
             "hashes": [
                 "sha256:32e43d604bbe7896fe7c248a9c2276447dbef840feb28fe20494f62af110211d",
@@ -488,13 +530,6 @@
             "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
             "version": "==0.4.4"
         },
-        "commonmark": {
-            "hashes": [
-                "sha256:452f9dc859be7f06631ddcb328b6919c67984aca654e5fefb3914d54691aed60",
-                "sha256:da2f38c92590f83de410ba1a3cbceafbc74fee9def35f9251ba9a971d6d66fd9"
-            ],
-            "version": "==0.9.1"
-        },
         "coverage": {
             "hashes": [
                 "sha256:004d1880bed2d97151facef49f08e255a20ceb6f9432df75f4eef018fdd5a78c",
@@ -553,6 +588,24 @@
             "index": "pypi",
             "version": "==5.5"
         },
+        "cryptography": {
+            "hashes": [
+                "sha256:0f1212a66329c80d68aeeb39b8a16d54ef57071bf22ff4e521657b27372e327d",
+                "sha256:1e056c28420c072c5e3cb36e2b23ee55e260cb04eee08f702e0edfec3fb51959",
+                "sha256:240f5c21aef0b73f40bb9f78d2caff73186700bf1bc6b94285699aff98cc16c6",
+                "sha256:26965837447f9c82f1855e0bc8bc4fb910240b6e0d16a664bb722df3b5b06873",
+                "sha256:37340614f8a5d2fb9aeea67fd159bfe4f5f4ed535b1090ce8ec428b2f15a11f2",
+                "sha256:3d10de8116d25649631977cb37da6cbdd2d6fa0e0281d014a5b7d337255ca713",
+                "sha256:3d8427734c781ea5f1b41d6589c293089704d4759e34597dce91014ac125aad1",
+                "sha256:7ec5d3b029f5fa2b179325908b9cd93db28ab7b85bb6c1db56b10e0b54235177",
+                "sha256:8e56e16617872b0957d1c9742a3f94b43533447fd78321514abbe7db216aa250",
+                "sha256:de4e5f7f68220d92b7637fc99847475b59154b7a1b3868fb7385337af54ac9ca",
+                "sha256:eb8cc2afe8b05acbd84a43905832ec78e7b3873fb124ca190f574dca7389a87d",
+                "sha256:ee77aa129f481be46f8d92a1a7db57269a2f23052d5f2433b4621bb457081cc9"
+            ],
+            "markers": "python_version >= '3.6'",
+            "version": "==3.4.7"
+        },
         "distlib": {
             "hashes": [
                 "sha256:8c09de2c67b3e7deef7184574fc060ab8a793e7adbb183d942c389c8b13c52fb",
@@ -624,6 +677,14 @@
             "markers": "python_version >= '3.6'",
             "version": "==4.0.1"
         },
+        "jeepney": {
+            "hashes": [
+                "sha256:7d59b6622675ca9e993a6bd38de845051d315f8b0c72cca3aef733a20b648657",
+                "sha256:aec56c0eb1691a841795111e184e13cad504f7703b9a64f63020816afa79a8ae"
+            ],
+            "markers": "sys_platform == 'linux'",
+            "version": "==0.6.0"
+        },
         "jinja2": {
             "hashes": [
                 "sha256:03e47ad063331dd6a3f04a43eddca8a966a26ba0c5b7207a9a9e4e08f1b29419",
@@ -640,6 +701,14 @@
             "markers": "python_version >= '3.6'",
             "version": "==23.0.1"
         },
+        "markdown-it-py": {
+            "hashes": [
+                "sha256:30b3e9f8198dc82a5df0dcb73fd31d56cd9a43bf8a747feb10b2ba74f962bcb1",
+                "sha256:c3b9f995be0792cbbc8ab2f53d74072eb7ff8a8b622be8d61d38ab879709eca3"
+            ],
+            "markers": "python_version ~= '3.6'",
+            "version": "==0.6.2"
+        },
         "markupsafe": {
             "hashes": [
                 "sha256:00bc623926325b26bb9605ae9eae8a215691f33cae5df11ca5424f06f2d1f473",
@@ -705,6 +774,14 @@
             ],
             "version": "==0.6.1"
         },
+        "mdit-py-plugins": {
+            "hashes": [
+                "sha256:1e467ca2ea056e8065cbd5d6c61e5052bb50826bde84c40f6a5ed77e82125710",
+                "sha256:77fd75dad81109ee91f30eb49146196f79afbbae041f298ae4886c8c2b5e23d7"
+            ],
+            "markers": "python_version ~= '3.6'",
+            "version": "==0.2.6"
+        },
         "multidict": {
             "hashes": [
                 "sha256:018132dbd8688c7a69ad89c4a3f39ea2f9f33302ebe567a879da8f4ca73f0d0a",
@@ -784,6 +861,14 @@
             "index": "pypi",
             "version": "==0.4.3"
         },
+        "myst-parser": {
+            "hashes": [
+                "sha256:260355b4da8e8865fe080b0638d7f1ab1791dc4bed02a7a48630b6bad4249219",
+                "sha256:e4bc99e43e19f70d22e528de8e7cce59f7e8e7c4c34dcba203de92de7a7c7c85"
+            ],
+            "index": "pypi",
+            "version": "==0.13.7"
+        },
         "nodeenv": {
             "hashes": [
                 "sha256:3ef13ff90291ba2a4a7a4ff9a979b63ffdd00a464dbe04acf0ea6471517a4c2b",
@@ -830,6 +915,14 @@
             "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==2.7.0"
         },
+        "pycparser": {
+            "hashes": [
+                "sha256:2d475327684562c3a96cc71adf7dc8c4f0565175cf86b6d7a404ff4c771f15f0",
+                "sha256:7582ad22678f0fcd81102833f60ef8d0e57288b6b5fb00323d101be910e35705"
+            ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
+            "version": "==2.20"
+        },
         "pyflakes": {
             "hashes": [
                 "sha256:7893783d01b8a89811dd72d7dfd4d84ff098e5eed95cfa8905b22bbffe52efc3",
@@ -904,14 +997,6 @@
             "index": "pypi",
             "version": "==29.0"
         },
-        "recommonmark": {
-            "hashes": [
-                "sha256:1b1db69af0231efce3fa21b94ff627ea33dee7079a01dd0a7f8482c3da148b3f",
-                "sha256:bdb4db649f2222dcd8d2d844f0006b958d627f732415d399791ee436a3686d67"
-            ],
-            "index": "pypi",
-            "version": "==0.7.1"
-        },
         "regex": {
             "hashes": [
                 "sha256:01afaf2ec48e196ba91b37451aa353cb7eda77efe518e481707e0515025f0cd5",
@@ -981,6 +1066,14 @@
             ],
             "version": "==1.4.0"
         },
+        "secretstorage": {
+            "hashes": [
+                "sha256:422d82c36172d88d6a0ed5afdec956514b189ddbfb72fefab0c8a1cee4eaf71f",
+                "sha256:fd666c51a6bf200643495a04abb261f83229dcb6fd8472ec393df7ffc8b6f195"
+            ],
+            "markers": "sys_platform == 'linux'",
+            "version": "==3.3.1"
+        },
         "setuptools-scm": {
             "hashes": [
                 "sha256:c3bd5f701c8def44a5c0bfe8d407bef3f80342217ef3492b951f3777bd2d915c",
diff --git a/README.md b/README.md
index 6443569d0d0..ceccbb79962 100644
--- a/README.md
+++ b/README.md
@@ -26,21 +26,12 @@ becomes transparent after a while and you can focus on the content instead.
 
 _Black_ makes code review faster by producing the smallest diffs possible.
 
-Try it out now using the [Black Playground](https://black.now.sh). Watch the
+Try it out now using the [Black Playground](https://black.vercel.app). Watch the
 [PyCon 2019 talk](https://youtu.be/esZLCuWs_2Y) to learn more.
 
 ---
 
-_Contents:_ **[Installation and usage](#installation-and-usage)** |
-**[Code style](#the-black-code-style)** | **[Pragmatism](#pragmatism)** |
-**[pyproject.toml](#pyprojecttoml)** | **[Editor integration](#editor-integration)** |
-**[blackd](#blackd)** | **[black-primer](#black-primer)** |
-**[Version control integration](#version-control-integration)** |
-**[GitHub Actions](#github-actions)** |
-**[Ignoring unmodified files](#ignoring-unmodified-files)** | **[Used by](#used-by)** |
-**[Testimonials](#testimonials)** | **[Show your style](#show-your-style)** |
-**[Contributing](#contributing-to-black)** | **[Change log](#change-log)** |
-**[Authors](#authors)**
+**[Read the documentation on ReadTheDocs!](https://black.readthedocs.io/en/stable)**
 
 ---
 
@@ -52,8 +43,6 @@ _Black_ can be installed by running `pip install black`. It requires Python 3.6.
 run. If you want to format Python 2 code as well, install with
 `pip install black[python2]`.
 
-#### Install from GitHub
-
 If you can't wait for the latest _hotness_ and want to install from GitHub, use:
 
 `pip install git+git://github.com/psf/black`
@@ -72,392 +61,72 @@ You can run _Black_ as a package if running it as a script doesn't work:
 python -m black {source_file_or_directory}
 ```
 
-### Command line options
-
-_Black_ doesn't provide many options. You can list them by running `black --help`:
-
-```text
-Usage: black [OPTIONS] [SRC]...
-
-  The uncompromising code formatter.
-
-Options:
-  -c, --code TEXT                 Format the code passed in as a string.
-  -l, --line-length INTEGER       How many characters per line to allow.
-                                  [default: 88]
-
-  -t, --target-version [py27|py33|py34|py35|py36|py37|py38|py39]
-                                  Python versions that should be supported by
-                                  Black's output. [default: per-file auto-
-                                  detection]
-
-  --pyi                           Format all input files like typing stubs
-                                  regardless of file extension (useful when
-                                  piping source on standard input).
-
-  -S, --skip-string-normalization
-                                  Don't normalize string quotes or prefixes.
-  -C, --skip-magic-trailing-comma
-                                  Don't use trailing commas as a reason to
-                                  split lines.
-
-  --check                         Don't write the files back, just return the
-                                  status. Return code 0 means nothing would
-                                  change. Return code 1 means some files
-                                  would be reformatted. Return code 123 means
-                                  there was an internal error.
-
-  --diff                          Don't write the files back, just output a
-                                  diff for each file on stdout.
-
-  --color / --no-color            Show colored diff. Only applies when
-                                  `--diff` is given.
-
-  --fast / --safe                 If --fast given, skip temporary sanity
-                                  checks. [default: --safe]
-
-  --include TEXT                  A regular expression that matches files and
-                                  directories that should be included on
-                                  recursive searches. An empty value means
-                                  all files are included regardless of the
-                                  name. Use forward slashes for directories
-                                  on all platforms (Windows, too). Exclusions
-                                  are calculated first, inclusions later.
-                                  [default: \.pyi?$]
-
-  --exclude TEXT                  A regular expression that matches files and
-                                  directories that should be excluded on
-                                  recursive searches. An empty value means no
-                                  paths are excluded. Use forward slashes for
-                                  directories on all platforms (Windows, too).
-                                  Exclusions are calculated first, inclusions
-                                  later. [default: /(\.direnv|\.eggs|\.git|\.
-                                  hg|\.mypy_cache|\.nox|\.tox|\.venv|venv|\.sv
-                                  n|_build|buck-out|build|dist)/]
-
-  --extend-exclude TEXT           Like --exclude, but adds additional files
-                                  and directories on top of the excluded
-                                  ones (useful if you simply want to add to
-                                  the default).
-
-  --force-exclude TEXT            Like --exclude, but files and directories
-                                  matching this regex will be excluded even
-                                  when they are passed explicitly as
-                                  arguments.
-
-
-  --stdin-filename TEXT           The name of the file when passing it through
-                                  stdin. Useful to make sure Black will
-                                  respect --force-exclude option on some
-                                  editors that rely on using stdin.
-
-  -q, --quiet                     Don't emit non-error messages to stderr.
-                                  Errors are still emitted; silence those with
-                                  2>/dev/null.
-
-  -v, --verbose                   Also emit messages to stderr about files
-                                  that were not changed or were ignored due to
-                                  exclusion patterns.
-
-  --version                       Show the version and exit.
-  --config FILE                   Read configuration from FILE path.
-  -h, --help                      Show this message and exit.
-```
-
-_Black_ is a well-behaved Unix-style command-line tool:
-
-- it does nothing if no sources are passed to it;
-- it will read from standard input and write to standard output if `-` is used as the
-  filename;
-- it only outputs messages to users on standard error;
-- exits with code 0 unless an internal error occurred (or `--check` was used).
-
-### Using _Black_ with other tools
-
-While _Black_ enforces formatting that conforms to PEP 8, other tools may raise warnings
-about _Black_'s changes or will overwrite _Black_'s changes. A good example of this is
-[isort](https://pypi.org/p/isort). Since _Black_ is barely configurable, these tools
-should be configured to neither warn about nor overwrite _Black_'s changes.
-
-Actual details on _Black_ compatible configurations for various tools can be found in
-[compatible_configs](https://github.com/psf/black/blob/master/docs/compatible_configs.md#black-compatible-configurations).
-
-### Migrating your code style without ruining git blame
-
-A long-standing argument against moving to automated code formatters like _Black_ is
-that the migration will clutter up the output of `git blame`. This was a valid argument,
-but since Git version 2.23, Git natively supports
-[ignoring revisions in blame](https://git-scm.com/docs/git-blame#Documentation/git-blame.txt---ignore-revltrevgt)
-with the `--ignore-rev` option. You can also pass a file listing the revisions to ignore
-using the `--ignore-revs-file` option. The changes made by the revision will be ignored
-when assigning blame. Lines modified by an ignored revision will be blamed on the
-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.
-
-```
-# Migrate code style to Black
-5b4ab991dede475d393e9d69ec388fd6bd949699
-```
-
-Afterwards, you can pass that file to `git blame` and see clean and meaningful blame
-information.
-
-```console
-$ git blame important.py --ignore-revs-file .git-blame-ignore-revs
-7a1ae265 (John Smith 2019-04-15 15:55:13 -0400 1) def very_important_function(text, file):
-abdfd8b0 (Alice Doe  2019-09-23 11:39:32 -0400 2)     text = text.lstrip()
-7a1ae265 (John Smith 2019-04-15 15:55:13 -0400 3)     with open(file, "r+") as f:
-7a1ae265 (John Smith 2019-04-15 15:55:13 -0400 4)         f.write(formatted)
-```
-
-You can even configure `git` to automatically ignore revisions listed in a file on every
-call to `git blame`.
-
-```console
-$ git config blame.ignoreRevsFile .git-blame-ignore-revs
-```
+Further information can be found in our docs:
 
-**The one caveat is that GitHub and GitLab do not yet support ignoring revisions using
-their native UI of blame.** 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) and please let GitHub
-know!)
+- [Usage and Configuration](https://black.readthedocs.io/en/stable/usage_and_configuration/index.html)
 
 ### NOTE: This is a beta product
 
 _Black_ is already [successfully used](https://github.com/psf/black#used-by) by many
-projects, small and big. It also sports a decent test suite. However, it is still very
-new. Things will probably be wonky for a while. This is made explicit by the "Beta"
-trove classifier, as well as by the "b" in the version number. What this means for you
-is that **until the formatter becomes stable, you should expect some formatting to
-change in the future**. That being said, no drastic stylistic changes are planned,
-mostly responses to bug reports.
+projects, small and big. Black has a comprehensive test suite, with efficient parallel
+tests, and our own auto formatting and parallel Continuous Integration runner. However,
+_Black_ is still beta. Things will probably be wonky for a while. This is made explicit
+by the "Beta" trove classifier, as well as by the "b" in the version number. What this
+means for you is that **until the formatter becomes stable, you should expect some
+formatting to change in the future**. That being said, no drastic stylistic changes are
+planned, mostly responses to bug reports.
 
 Also, as a safety measure which slows down processing, _Black_ will check that the
 reformatted code still produces a valid AST that is effectively equivalent to the
 original (see the
-[Pragmatism](https://github.com/psf/black/blob/master/docs/the_black_code_style.md#pragmatism)
+[Pragmatism](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#ast-before-and-after-formatting)
 section for details). If you're feeling confident, use `--fast`.
 
 ## The _Black_ code style
 
 _Black_ is a PEP 8 compliant opinionated formatter. _Black_ reformats entire files in
-place. It is not configurable. It doesn't take previous formatting into account. Your
-main option of configuring _Black_ is that it doesn't reformat blocks that start with
-`# fmt: off` and end with `# fmt: on`, or lines that ends with `# fmt: skip`. Pay
-attention that `# fmt: on/off` have to be on the same level of indentation. To learn
-more about _Black_'s opinions, to go
-[the_black_code_style](https://github.com/psf/black/blob/master/docs/the_black_code_style.md).
+place. Style configuration options are deliberately limited and rarely added. It doesn't
+take previous formatting into account (see [Pragmatism](#pragmatism) for exceptions).
+
+Our documentation covers the current _Black_ code style, but planned changes to it are
+also documented. They're both worth taking a look:
+
+- [The _Black_ Code Style: Current style](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html)
+- [The _Black_ Code Style: Future style](https://black.readthedocs.io/en/stable/the_black_code_style/future_style.html)
 
 Please refer to this document before submitting an issue. What seems like a bug might be
 intended behaviour.
 
-## Pragmatism
+### Pragmatism
 
 Early versions of _Black_ used to be absolutist in some respects. They took after its
 initial author. This was fine at the time as it made the implementation simpler and
 there were not many users anyway. Not many edge cases were reported. As a mature tool,
-_Black_ does make some exceptions to rules it otherwise holds. This
-[section](https://github.com/psf/black/blob/master/docs/the_black_code_style.md#pragmatism)
-of `the_black_code_style` describes what those exceptions are and why this is the case.
+_Black_ does make some exceptions to rules it otherwise holds.
+
+- [The _Black_ code style: Pragmatism](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#pragmatism)
 
 Please refer to this document before submitting an issue just like with the document
 above. What seems like a bug might be intended behaviour.
 
-## pyproject.toml
+## Configuration
 
 _Black_ is able to read project-specific default values for its command line options
 from a `pyproject.toml` file. This is especially useful for specifying custom
-`--include` and `--exclude`/`--extend-exclude` patterns for your project.
-
-**Pro-tip**: If you're asking yourself "Do I need to configure anything?" the answer is
-"No". _Black_ is all about sensible defaults.
-
-### What on Earth is a `pyproject.toml` file?
-
-[PEP 518](https://www.python.org/dev/peps/pep-0518/) defines `pyproject.toml` as a
-configuration file to store build system requirements for Python projects. With the help
-of tools like [Poetry](https://python-poetry.org/) or
-[Flit](https://flit.readthedocs.io/en/latest/) it can fully replace the need for
-`setup.py` and `setup.cfg` files.
-
-### Where _Black_ looks for the file
-
-By default _Black_ looks for `pyproject.toml` starting from the common base directory of
-all files and directories passed on the command line. If it's not there, it looks in
-parent directories. It stops looking when it finds the file, or a `.git` directory, or a
-`.hg` directory, or the root of the file system, whichever comes first.
-
-If you're formatting standard input, _Black_ will look for configuration starting from
-the current working directory.
-
-You can use a "global" configuration, stored in a specific location in your home
-directory. This will be used as a fallback configuration, that is, it will be used if
-and only if _Black_ doesn't find any configuration as mentioned above. Depending on your
-operating system, this configuration file should be stored as:
-
-- Windows: `~\.black`
-- Unix-like (Linux, MacOS, etc.): `$XDG_CONFIG_HOME/black` (`~/.config/black` if the
-  `XDG_CONFIG_HOME` environment variable is not set)
-
-Note that these are paths to the TOML file itself (meaning that they shouldn't be named
-as `pyproject.toml`), not directories where you store the configuration. Here, `~`
-refers to the path to your home directory. On Windows, this will be something like
-`C:\\Users\UserName`.
-
-You can also explicitly specify the path to a particular file that you want with
-`--config`. In this situation _Black_ will not look for any other file.
-
-If you're running with `--verbose`, you will see a blue message if a file was found and
-used.
-
-Please note `blackd` will not use `pyproject.toml` configuration.
-
-### Configuration format
-
-As the file extension suggests, `pyproject.toml` is a
-[TOML](https://github.com/toml-lang/toml) file. It contains separate sections for
-different tools. _Black_ is using the `[tool.black]` section. The option keys are the
-same as long names of options on the command line.
-
-Note that you have to use single-quoted strings in TOML for regular expressions. It's
-the equivalent of r-strings in Python. Multiline strings are treated as verbose regular
-expressions by Black. Use `[ ]` to denote a significant space character.
+`--include` and `--exclude`/`--force-exclude`/`--extend-exclude` patterns for your
+project.
 
-<details>
-<summary>Example <code>pyproject.toml</code></summary>
+You can find more details in our documentation:
 
-```toml
-[tool.black]
-line-length = 88
-target-version = ['py37']
-include = '\.pyi?$'
-extend-exclude = '''
-# A regex preceded with ^/ will apply only to files and directories
-# in the root of the project.
-^/foo.py  # exclude a file named foo.py in the root of the project (in addition to the defaults)
-'''
-```
-
-</details>
-
-### Lookup hierarchy
-
-Command-line options have defaults that you can see in `--help`. A `pyproject.toml` can
-override those defaults. Finally, options provided by the user on the command line
-override both.
-
-_Black_ will only ever use one `pyproject.toml` file during an entire run. It doesn't
-look for multiple files, and doesn't compose configuration from different levels of the
-file hierarchy.
-
-## Editor integration
-
-_Black_ can be integrated into many editors with plugins. They let you run _Black_ on
-your code with the ease of doing it in your editor. To get started using _Black_ in your
-editor of choice, please see
-[editor_integration](https://github.com/psf/black/blob/master/docs/editor_integration.md).
-
-Patches are welcome for editors without an editor integration or plugin! More
-information can be found in
-[editor_integration](https://github.com/psf/black/blob/master/docs/editor_integration.md#other-editors).
-
-## blackd
-
-`blackd` is a small HTTP server that exposes Black's functionality over a simple
-protocol. The main benefit of using it is to avoid paying the cost of starting up a new
-Black process every time you want to blacken a file. Please refer to
-[blackd](https://github.com/psf/black/blob/master/docs/blackd.md) to get the ball
-rolling.
-
-## black-primer
-
-`black-primer` is a tool built for CI (and humans) to have _Black_ `--check` a number of
-(configured in `primer.json`) Git accessible projects in parallel.
-[black_primer](https://github.com/psf/black/blob/master/docs/black_primer.md) has more
-information regarding its usage and configuration.
-
-(A PR adding Mercurial support will be accepted.)
-
-## Version control integration
-
-Use [pre-commit](https://pre-commit.com/). Once you
-[have it installed](https://pre-commit.com/#install), add this to the
-`.pre-commit-config.yaml` in your repository:
-
-```yaml
-repos:
-  - repo: https://github.com/psf/black
-    rev: 20.8b1 # Replace by any tag/version: https://github.com/psf/black/tags
-    hooks:
-      - id: black
-        language_version: python3 # Should be a command that runs python3.6+
-```
-
-Then run `pre-commit install` and you're ready to go.
-
-Avoid using `args` in the hook. Instead, store necessary configuration in
-`pyproject.toml` so that editors and command-line usage of Black all behave consistently
-for your project. See _Black_'s own
-[pyproject.toml](https://github.com/psf/black/blob/master/pyproject.toml) for an
-example.
+- [The basics: Configuration via a file](https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#configuration-via-a-file)
 
-If you're already using Python 3.7, switch the `language_version` accordingly. Finally,
-`stable` is a branch that tracks the latest release on PyPI. If you'd rather run on
-master, this is also an option.
+And if you're looking for more general configuration documentation:
 
-## GitHub Actions
+- [Usage and Configuration](https://black.readthedocs.io/en/stable/usage_and_configuration/index.html)
 
-Create a file named `.github/workflows/black.yml` inside your repository with:
-
-```yaml
-name: Lint
-
-on: [push, pull_request]
-
-jobs:
-  lint:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
-      - uses: psf/black@stable
-```
-
-You may use `options` (Default is `'--check --diff'`) and `src` (Default is `'.'`) as
-follows:
-
-```yaml
-- uses: psf/black@stable
-  with:
-    options: "--check --verbose"
-    src: "./src"
-```
-
-## Ignoring unmodified files
-
-_Black_ remembers files it has already formatted, unless the `--diff` flag is used or
-code is passed via standard input. This information is stored per-user. The exact
-location of the file depends on the _Black_ version and the system on which _Black_ is
-run. The file is non-portable. The standard location on common operating systems is:
-
-- Windows:
-  `C:\\Users\<username>\AppData\Local\black\black\Cache\<version>\cache.<line-length>.<file-mode>.pickle`
-- macOS:
-  `/Users/<username>/Library/Caches/black/<version>/cache.<line-length>.<file-mode>.pickle`
-- Linux:
-  `/home/<username>/.cache/black/<version>/cache.<line-length>.<file-mode>.pickle`
-
-`file-mode` is an int flag that determines whether the file was formatted as 3.6+ only,
-as .pyi, and whether string normalization was omitted.
-
-To override the location of these files on macOS or Linux, set the environment variable
-`XDG_CACHE_HOME` to your preferred location. For example, if you want to put the cache
-in the directory you're running _Black_ from, set `XDG_CACHE_HOME=.cache`. _Black_ will
-then write the above files to `.cache/black/<version>/`.
+**Pro-tip**: If you're asking yourself "Do I need to configure anything?" the answer is
+"No". _Black_ is all about sensible defaults. Applying those defaults will have your
+code in compliance with many other _Black_ formatted projects.
 
 ## Used by
 
@@ -513,209 +182,39 @@ Looks like this:
 
 MIT
 
-## Contributing to _Black_
+## Contributing
 
-In terms of inspiration, _Black_ is about as configurable as _gofmt_. This is
-deliberate.
+Welcome! Happy to see you willing to make the project better. You can get started by
+reading this:
 
-Bug reports and fixes are always welcome! However, 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 up, and so on - go for it! On the
-other hand, if your answer is "because I don't like a particular formatting" then you're
-not ready to embrace _Black_ yet. Such changes are unlikely to get accepted. You can
-still try but prepare to be disappointed.
+- [Contributing: The basics](https://black.readthedocs.io/en/latest/contributing/the_basics.html)
 
-More details can be found in
-[CONTRIBUTING](https://github.com/psf/black/blob/master/CONTRIBUTING.md).
+You can also take a look at the rest of the contributing docs or talk with the
+developers:
+
+- [Contributing documentation](https://black.readthedocs.io/en/latest/contributing/index.html)
+- [IRC channel on Freenode](https://webchat.freenode.net/?channels=%23blackformatter)
 
 ## Change log
 
-The log's become rather long. It moved to its own file.
+The log has become rather long. It moved to its own file.
 
-See [CHANGES](https://github.com/psf/black/blob/master/CHANGES.md).
+See [CHANGES](https://black.readthedocs.io/en/latest/change_log.html).
 
 ## Authors
 
-Glued together by [Łukasz Langa](mailto:lukasz@langa.pl).
-
-Maintained with [Carol Willing](mailto:carolcode@willingconsulting.com),
-[Carl Meyer](mailto:carl@oddbird.net),
-[Jelle Zijlstra](mailto:jelle.zijlstra@gmail.com),
-[Mika Naylor](mailto:mail@autophagy.io),
-[Zsolt Dollenstein](mailto:zsol.zsol@gmail.com),
-[Cooper Lees](mailto:me@cooperlees.com), and Richard Si.
-
-Multiple contributions by:
-
-- [Abdur-Rahmaan Janhangeer](mailto:arj.python@gmail.com)
-- [Adam Johnson](mailto:me@adamj.eu)
-- [Adam Williamson](mailto:adamw@happyassassin.net)
-- [Alexander Huynh](mailto:github@grande.coffee)
-- [Alex Vandiver](mailto:github@chmrr.net)
-- [Allan Simon](mailto:allan.simon@supinfo.com)
-- Anders-Petter Ljungquist
-- [Andrew Thorp](mailto:andrew.thorp.dev@gmail.com)
-- [Andrew Zhou](mailto:andrewfzhou@gmail.com)
-- [Andrey](mailto:dyuuus@yandex.ru)
-- [Andy Freeland](mailto:andy@andyfreeland.net)
-- [Anthony Sottile](mailto:asottile@umich.edu)
-- [Arjaan Buijk](mailto:arjaan.buijk@gmail.com)
-- [Arnav Borbornah](mailto:arnavborborah11@gmail.com)
-- [Artem Malyshev](mailto:proofit404@gmail.com)
-- [Asger Hautop Drewsen](mailto:asgerdrewsen@gmail.com)
-- [Augie Fackler](mailto:raf@durin42.com)
-- [Aviskar KC](mailto:aviskarkc10@gmail.com)
-- Batuhan Taşkaya
-- [Benjamin Wohlwend](mailto:bw@piquadrat.ch)
-- [Benjamin Woodruff](mailto:github@benjam.info)
-- [Bharat Raghunathan](mailto:bharatraghunthan9767@gmail.com)
-- [Brandt Bucher](mailto:brandtbucher@gmail.com)
-- [Brett Cannon](mailto:brett@python.org)
-- [Bryan Bugyi](mailto:bryan.bugyi@rutgers.edu)
-- [Bryan Forbes](mailto:bryan@reigndropsfall.net)
-- [Calum Lind](mailto:calumlind@gmail.com)
-- [Charles](mailto:peacech@gmail.com)
-- Charles Reid
-- [Christian Clauss](mailto:cclauss@bluewin.ch)
-- [Christian Heimes](mailto:christian@python.org)
-- [Chuck Wooters](mailto:chuck.wooters@microsoft.com)
-- [Chris Rose](mailto:offline@offby1.net)
-- Codey Oxley
-- [Cong](mailto:congusbongus@gmail.com)
-- [Cooper Ry Lees](mailto:me@cooperlees.com)
-- [Dan Davison](mailto:dandavison7@gmail.com)
-- [Daniel Hahler](mailto:github@thequod.de)
-- [Daniel M. Capella](mailto:polycitizen@gmail.com)
-- Daniele Esposti
-- [David Hotham](mailto:david.hotham@metaswitch.com)
-- [David Lukes](mailto:dafydd.lukes@gmail.com)
-- [David Szotten](mailto:davidszotten@gmail.com)
-- [Denis Laxalde](mailto:denis@laxalde.org)
-- [Douglas Thor](mailto:dthor@transphormusa.com)
-- dylanjblack
-- [Eli Treuherz](mailto:eli@treuherz.com)
-- [Emil Hessman](mailto:emil@hessman.se)
-- [Felix Kohlgrüber](mailto:felix.kohlgrueber@gmail.com)
-- [Florent Thiery](mailto:fthiery@gmail.com)
-- Francisco
-- [Giacomo Tagliabue](mailto:giacomo.tag@gmail.com)
-- [Greg Gandenberger](mailto:ggandenberger@shoprunner.com)
-- [Gregory P. Smith](mailto:greg@krypto.org)
-- Gustavo Camargo
-- hauntsaninja
-- [Hadi Alqattan](mailto:alqattanhadizaki@gmail.com)
-- [Heaford](mailto:dan@heaford.com)
-- [Hugo Barrera](mailto::hugo@barrera.io)
-- Hugo van Kemenade
-- [Hynek Schlawack](mailto:hs@ox.cx)
-- [Ivan Katanić](mailto:ivan.katanic@gmail.com)
-- [Jakub Kadlubiec](mailto:jakub.kadlubiec@skyscanner.net)
-- [Jakub Warczarek](mailto:jakub.warczarek@gmail.com)
-- [Jan Hnátek](mailto:jan.hnatek@gmail.com)
-- [Jason Fried](mailto:me@jasonfried.info)
-- [Jason Friedland](mailto:jason@friedland.id.au)
-- [jgirardet](mailto:ijkl@netc.fr)
-- Jim Brännlund
-- [Jimmy Jia](mailto:tesrin@gmail.com)
-- [Joe Antonakakis](mailto:jma353@cornell.edu)
-- [Jon Dufresne](mailto:jon.dufresne@gmail.com)
-- [Jonas Obrist](mailto:ojiidotch@gmail.com)
-- [Jonty Wareing](mailto:jonty@jonty.co.uk)
-- [Jose Nazario](mailto:jose.monkey.org@gmail.com)
-- [Joseph Larson](mailto:larson.joseph@gmail.com)
-- [Josh Bode](mailto:joshbode@fastmail.com)
-- [Josh Holland](mailto:anowlcalledjosh@gmail.com)
-- [Joshua Cannon](mailto:joshdcannon@gmail.com)
-- [José Padilla](mailto:jpadilla@webapplicate.com)
-- [Juan Luis Cano Rodríguez](mailto:hello@juanlu.space)
-- [kaiix](mailto:kvn.hou@gmail.com)
-- [Katie McLaughlin](mailto:katie@glasnt.com)
-- Katrin Leinweber
-- [Keith Smiley](mailto:keithbsmiley@gmail.com)
-- [Kenyon Ralph](mailto:kenyon@kenyonralph.com)
-- [Kevin Kirsche](mailto:Kev.Kirsche+GitHub@gmail.com)
-- [Kyle Hausmann](mailto:kyle.hausmann@gmail.com)
-- [Kyle Sunden](mailto:sunden@wisc.edu)
-- Lawrence Chan
-- [Linus Groh](mailto:mail@linusgroh.de)
-- [Loren Carvalho](mailto:comradeloren@gmail.com)
-- [Luka Sterbic](mailto:luka.sterbic@gmail.com)
-- [LukasDrude](mailto:mail@lukas-drude.de)
-- Mahmoud Hossam
-- Mariatta
-- [Matt VanEseltine](mailto:vaneseltine@gmail.com)
-- [Matthew Clapp](mailto:itsayellow+dev@gmail.com)
-- [Matthew Walster](mailto:matthew@walster.org)
-- Max Smolens
-- [Michael Aquilina](mailto:michaelaquilina@gmail.com)
-- [Michael Flaxman](mailto:michael.flaxman@gmail.com)
-- [Michael J. Sullivan](mailto:sully@msully.net)
-- [Michael McClimon](mailto:michael@mcclimon.org)
-- [Miguel Gaiowski](mailto:miggaiowski@gmail.com)
-- [Mike](mailto:roshi@fedoraproject.org)
-- [mikehoyio](mailto:mikehoy@gmail.com)
-- [Min ho Kim](mailto:minho42@gmail.com)
-- [Miroslav Shubernetskiy](mailto:miroslav@miki725.com)
-- MomIsBestFriend
-- [Nathan Goldbaum](mailto:ngoldbau@illinois.edu)
-- [Nathan Hunt](mailto:neighthan.hunt@gmail.com)
-- [Neraste](mailto:neraste.herr10@gmail.com)
-- [Nikolaus Waxweiler](mailto:madigens@gmail.com)
-- [Ofek Lev](mailto:ofekmeister@gmail.com)
-- [Osaetin Daniel](mailto:osaetindaniel@gmail.com)
-- [otstrel](mailto:otstrel@gmail.com)
-- [Pablo Galindo](mailto:Pablogsal@gmail.com)
-- [Paul Ganssle](mailto:p.ganssle@gmail.com)
-- [Paul Meinhardt](mailto:mnhrdt@gmail.com)
-- [Peter Bengtsson](mailto:mail@peterbe.com)
-- [Peter Grayson](mailto:pete@jpgrayson.net)
-- [Peter Stensmyr](mailto:peter.stensmyr@gmail.com)
-- pmacosta
-- [Quentin Pradet](mailto:quentin@pradet.me)
-- [Ralf Schmitt](mailto:ralf@systemexit.de)
-- [Ramón Valles](mailto:mroutis@protonmail.com)
-- [Richard Fearn](mailto:richardfearn@gmail.com)
-- Richard Si
-- [Rishikesh Jha](mailto:rishijha424@gmail.com)
-- [Rupert Bedford](mailto:rupert@rupertb.com)
-- Russell Davis
-- [Rémi Verschelde](mailto:rverschelde@gmail.com)
-- [Sami Salonen](mailto:sakki@iki.fi)
-- [Samuel Cormier-Iijima](mailto:samuel@cormier-iijima.com)
-- [Sanket Dasgupta](mailto:sanketdasgupta@gmail.com)
-- Sergi
-- [Scott Stevenson](mailto:scott@stevenson.io)
-- Shantanu
-- [shaoran](mailto:shaoran@sakuranohana.org)
-- [Shinya Fujino](mailto:shf0811@gmail.com)
-- springstan
-- [Stavros Korokithakis](mailto:hi@stavros.io)
-- [Stephen Rosen](mailto:sirosen@globus.org)
-- [Steven M. Vascellaro](mailto:S.Vascellaro@gmail.com)
-- [Sunil Kapil](mailto:snlkapil@gmail.com)
-- [Sébastien Eustace](mailto:sebastien.eustace@gmail.com)
-- [Tal Amuyal](mailto:TalAmuyal@gmail.com)
-- [Terrance](mailto:git@terrance.allofti.me)
-- [Thom Lu](mailto:thomas.c.lu@gmail.com)
-- [Thomas Grainger](mailto:tagrain@gmail.com)
-- [Tim Gates](mailto:tim.gates@iress.com)
-- [Tim Swast](mailto:swast@google.com)
-- [Timo](mailto:timo_tk@hotmail.com)
-- Toby Fleming
-- [Tom Christie](mailto:tom@tomchristie.com)
-- [Tony Narlock](mailto:tony@git-pull.com)
-- [Tsuyoshi Hombashi](mailto:tsuyoshi.hombashi@gmail.com)
-- [Tushar Chandra](mailto:tusharchandra2018@u.northwestern.edu)
-- [Tzu-ping Chung](mailto:uranusjr@gmail.com)
-- [Utsav Shah](mailto:ukshah2@illinois.edu)
-- utsav-dbx
-- vezeli
-- [Ville Skyttä](mailto:ville.skytta@iki.fi)
-- [Vishwas B Sharma](mailto:sharma.vishwas88@gmail.com)
-- [Vlad Emelianov](mailto:volshebnyi@gmail.com)
-- [williamfzc](mailto:178894043@qq.com)
-- [wouter bolsterlee](mailto:wouter@bolsterl.ee)
-- Yazdan
-- [Yngve Høiseth](mailto:yngve@hoiseth.net)
-- [Yurii Karabas](mailto:1998uriyyo@gmail.com)
-- [Zac Hatfield-Dodds](mailto:zac@zhd.dev)
+The author list is quite long nowadays, so it lives in its own file.
+
+See [AUTHORS.md](./AUTHORS.md)
+
+## Code of Conduct
+
+Everyone participating in the _Black_ project, and in particular in the issue tracker,
+pull requests, and social media activity, is expected to treat other people with respect
+and more generally to follow the guidelines articulated in the
+[Python Community Code of Conduct](https://www.python.org/psf/codeofconduct/).
+
+At the same time, humor is encouraged. In fact, basic familiarity with Monty Python's
+Flying Circus is expected. We are not savages.
+
+And if you _really_ need to slap somebody, do it with a fish while dancing.
diff --git a/docs/authors.md b/docs/authors.md
deleted file mode 100644
index 9f2ea0571b9..00000000000
--- a/docs/authors.md
+++ /dev/null
@@ -1,187 +0,0 @@
-[//]: # "NOTE: THIS FILE WAS AUTOGENERATED FROM README.md"
-
-# Authors
-
-Glued together by [Łukasz Langa](mailto:lukasz@langa.pl).
-
-Maintained with [Carol Willing](mailto:carolcode@willingconsulting.com),
-[Carl Meyer](mailto:carl@oddbird.net),
-[Jelle Zijlstra](mailto:jelle.zijlstra@gmail.com),
-[Mika Naylor](mailto:mail@autophagy.io),
-[Zsolt Dollenstein](mailto:zsol.zsol@gmail.com), and
-[Cooper Lees](mailto:me@cooperlees.com).
-
-Multiple contributions by:
-
-- [Abdur-Rahmaan Janhangeer](mailto:arj.python@gmail.com)
-- [Adam Johnson](mailto:me@adamj.eu)
-- [Adam Williamson](mailto:adamw@happyassassin.net)
-- [Alexander Huynh](mailto:github@grande.coffee)
-- [Alex Vandiver](mailto:github@chmrr.net)
-- [Allan Simon](mailto:allan.simon@supinfo.com)
-- Anders-Petter Ljungquist
-- [Andrew Thorp](mailto:andrew.thorp.dev@gmail.com)
-- [Andrew Zhou](mailto:andrewfzhou@gmail.com)
-- [Andrey](mailto:dyuuus@yandex.ru)
-- [Andy Freeland](mailto:andy@andyfreeland.net)
-- [Anthony Sottile](mailto:asottile@umich.edu)
-- [Arjaan Buijk](mailto:arjaan.buijk@gmail.com)
-- [Arnav Borbornah](mailto:arnavborborah11@gmail.com)
-- [Artem Malyshev](mailto:proofit404@gmail.com)
-- [Asger Hautop Drewsen](mailto:asgerdrewsen@gmail.com)
-- [Augie Fackler](mailto:raf@durin42.com)
-- [Aviskar KC](mailto:aviskarkc10@gmail.com)
-- Batuhan Taşkaya
-- [Benjamin Wohlwend](mailto:bw@piquadrat.ch)
-- [Benjamin Woodruff](mailto:github@benjam.info)
-- [Bharat Raghunathan](mailto:bharatraghunthan9767@gmail.com)
-- [Brandt Bucher](mailto:brandtbucher@gmail.com)
-- [Brett Cannon](mailto:brett@python.org)
-- [Bryan Bugyi](mailto:bryan.bugyi@rutgers.edu)
-- [Bryan Forbes](mailto:bryan@reigndropsfall.net)
-- [Calum Lind](mailto:calumlind@gmail.com)
-- [Charles](mailto:peacech@gmail.com)
-- Charles Reid
-- [Christian Clauss](mailto:cclauss@bluewin.ch)
-- [Christian Heimes](mailto:christian@python.org)
-- [Chuck Wooters](mailto:chuck.wooters@microsoft.com)
-- [Chris Rose](mailto:offline@offby1.net)
-- Codey Oxley
-- [Cong](mailto:congusbongus@gmail.com)
-- [Cooper Ry Lees](mailto:me@cooperlees.com)
-- [Dan Davison](mailto:dandavison7@gmail.com)
-- [Daniel Hahler](mailto:github@thequod.de)
-- [Daniel M. Capella](mailto:polycitizen@gmail.com)
-- Daniele Esposti
-- [David Hotham](mailto:david.hotham@metaswitch.com)
-- [David Lukes](mailto:dafydd.lukes@gmail.com)
-- [David Szotten](mailto:davidszotten@gmail.com)
-- [Denis Laxalde](mailto:denis@laxalde.org)
-- [Douglas Thor](mailto:dthor@transphormusa.com)
-- dylanjblack
-- [Eli Treuherz](mailto:eli@treuherz.com)
-- [Emil Hessman](mailto:emil@hessman.se)
-- [Felix Kohlgrüber](mailto:felix.kohlgrueber@gmail.com)
-- [Florent Thiery](mailto:fthiery@gmail.com)
-- Francisco
-- [Giacomo Tagliabue](mailto:giacomo.tag@gmail.com)
-- [Greg Gandenberger](mailto:ggandenberger@shoprunner.com)
-- [Gregory P. Smith](mailto:greg@krypto.org)
-- Gustavo Camargo
-- hauntsaninja
-- [Hadi Alqattan](mailto:alqattanhadizaki@gmail.com)
-- [Heaford](mailto:dan@heaford.com)
-- [Hugo Barrera](mailto::hugo@barrera.io)
-- Hugo van Kemenade
-- [Hynek Schlawack](mailto:hs@ox.cx)
-- [Ivan Katanić](mailto:ivan.katanic@gmail.com)
-- [Jakub Kadlubiec](mailto:jakub.kadlubiec@skyscanner.net)
-- [Jakub Warczarek](mailto:jakub.warczarek@gmail.com)
-- [Jan Hnátek](mailto:jan.hnatek@gmail.com)
-- [Jason Fried](mailto:me@jasonfried.info)
-- [Jason Friedland](mailto:jason@friedland.id.au)
-- [jgirardet](mailto:ijkl@netc.fr)
-- Jim Brännlund
-- [Jimmy Jia](mailto:tesrin@gmail.com)
-- [Joe Antonakakis](mailto:jma353@cornell.edu)
-- [Jon Dufresne](mailto:jon.dufresne@gmail.com)
-- [Jonas Obrist](mailto:ojiidotch@gmail.com)
-- [Jonty Wareing](mailto:jonty@jonty.co.uk)
-- [Jose Nazario](mailto:jose.monkey.org@gmail.com)
-- [Joseph Larson](mailto:larson.joseph@gmail.com)
-- [Josh Bode](mailto:joshbode@fastmail.com)
-- [Josh Holland](mailto:anowlcalledjosh@gmail.com)
-- [José Padilla](mailto:jpadilla@webapplicate.com)
-- [Juan Luis Cano Rodríguez](mailto:hello@juanlu.space)
-- [kaiix](mailto:kvn.hou@gmail.com)
-- [Katie McLaughlin](mailto:katie@glasnt.com)
-- Katrin Leinweber
-- [Keith Smiley](mailto:keithbsmiley@gmail.com)
-- [Kenyon Ralph](mailto:kenyon@kenyonralph.com)
-- [Kevin Kirsche](mailto:Kev.Kirsche+GitHub@gmail.com)
-- [Kyle Hausmann](mailto:kyle.hausmann@gmail.com)
-- [Kyle Sunden](mailto:sunden@wisc.edu)
-- Lawrence Chan
-- [Linus Groh](mailto:mail@linusgroh.de)
-- [Loren Carvalho](mailto:comradeloren@gmail.com)
-- [Luka Sterbic](mailto:luka.sterbic@gmail.com)
-- [LukasDrude](mailto:mail@lukas-drude.de)
-- Mahmoud Hossam
-- Mariatta
-- [Matt VanEseltine](mailto:vaneseltine@gmail.com)
-- [Matthew Clapp](mailto:itsayellow+dev@gmail.com)
-- [Matthew Walster](mailto:matthew@walster.org)
-- Max Smolens
-- [Michael Aquilina](mailto:michaelaquilina@gmail.com)
-- [Michael Flaxman](mailto:michael.flaxman@gmail.com)
-- [Michael J. Sullivan](mailto:sully@msully.net)
-- [Michael McClimon](mailto:michael@mcclimon.org)
-- [Miguel Gaiowski](mailto:miggaiowski@gmail.com)
-- [Mike](mailto:roshi@fedoraproject.org)
-- [mikehoyio](mailto:mikehoy@gmail.com)
-- [Min ho Kim](mailto:minho42@gmail.com)
-- [Miroslav Shubernetskiy](mailto:miroslav@miki725.com)
-- MomIsBestFriend
-- [Nathan Goldbaum](mailto:ngoldbau@illinois.edu)
-- [Nathan Hunt](mailto:neighthan.hunt@gmail.com)
-- [Neraste](mailto:neraste.herr10@gmail.com)
-- [Nikolaus Waxweiler](mailto:madigens@gmail.com)
-- [Ofek Lev](mailto:ofekmeister@gmail.com)
-- [Osaetin Daniel](mailto:osaetindaniel@gmail.com)
-- [otstrel](mailto:otstrel@gmail.com)
-- [Pablo Galindo](mailto:Pablogsal@gmail.com)
-- [Paul Ganssle](mailto:p.ganssle@gmail.com)
-- [Paul Meinhardt](mailto:mnhrdt@gmail.com)
-- [Paul "TBBle" Hampson](mailto:Paul.Hampson@Pobox.com)
-- [Peter Bengtsson](mailto:mail@peterbe.com)
-- [Peter Grayson](mailto:pete@jpgrayson.net)
-- [Peter Stensmyr](mailto:peter.stensmyr@gmail.com)
-- pmacosta
-- [Quentin Pradet](mailto:quentin@pradet.me)
-- [Ralf Schmitt](mailto:ralf@systemexit.de)
-- [Ramón Valles](mailto:mroutis@protonmail.com)
-- [Richard Fearn](mailto:richardfearn@gmail.com)
-- Richard Si
-- [Rishikesh Jha](mailto:rishijha424@gmail.com)
-- [Rupert Bedford](mailto:rupert@rupertb.com)
-- Russell Davis
-- [Rémi Verschelde](mailto:rverschelde@gmail.com)
-- [Sami Salonen](mailto:sakki@iki.fi)
-- [Samuel Cormier-Iijima](mailto:samuel@cormier-iijima.com)
-- [Sanket Dasgupta](mailto:sanketdasgupta@gmail.com)
-- Sergi
-- [Scott Stevenson](mailto:scott@stevenson.io)
-- Shantanu
-- [shaoran](mailto:shaoran@sakuranohana.org)
-- [Shinya Fujino](mailto:shf0811@gmail.com)
-- springstan
-- [Stavros Korokithakis](mailto:hi@stavros.io)
-- [Stephen Rosen](mailto:sirosen@globus.org)
-- [Steven M. Vascellaro](mailto:S.Vascellaro@gmail.com)
-- [Sunil Kapil](mailto:snlkapil@gmail.com)
-- [Sébastien Eustace](mailto:sebastien.eustace@gmail.com)
-- [Tal Amuyal](mailto:TalAmuyal@gmail.com)
-- [Terrance](mailto:git@terrance.allofti.me)
-- [Thom Lu](mailto:thomas.c.lu@gmail.com)
-- [Thomas Grainger](mailto:tagrain@gmail.com)
-- [Tim Gates](mailto:tim.gates@iress.com)
-- [Tim Swast](mailto:swast@google.com)
-- [Timo](mailto:timo_tk@hotmail.com)
-- Toby Fleming
-- [Tom Christie](mailto:tom@tomchristie.com)
-- [Tony Narlock](mailto:tony@git-pull.com)
-- [Tsuyoshi Hombashi](mailto:tsuyoshi.hombashi@gmail.com)
-- [Tushar Chandra](mailto:tusharchandra2018@u.northwestern.edu)
-- [Tzu-ping Chung](mailto:uranusjr@gmail.com)
-- [Utsav Shah](mailto:ukshah2@illinois.edu)
-- utsav-dbx
-- vezeli
-- [Ville Skyttä](mailto:ville.skytta@iki.fi)
-- [Vishwas B Sharma](mailto:sharma.vishwas88@gmail.com)
-- [Vlad Emelianov](mailto:volshebnyi@gmail.com)
-- [williamfzc](mailto:178894043@qq.com)
-- [wouter bolsterlee](mailto:wouter@bolsterl.ee)
-- Yazdan
-- [Yngve Høiseth](mailto:yngve@hoiseth.net)
-- [Yurii Karabas](mailto:1998uriyyo@gmail.com)
-- [Zac Hatfield-Dodds](mailto:zac@zhd.dev)
diff --git a/docs/authors.md b/docs/authors.md
new file mode 120000
index 00000000000..3234d6e0792
--- /dev/null
+++ b/docs/authors.md
@@ -0,0 +1 @@
+../AUTHORS.md
\ No newline at end of file
diff --git a/docs/black_primer.md b/docs/black_primer.md
deleted file mode 100644
index a2dd964b7dc..00000000000
--- a/docs/black_primer.md
+++ /dev/null
@@ -1,120 +0,0 @@
-# black-primer
-
-`black-primer` is a tool built for CI (and humans) to have _Black_ `--check` a number of
-(configured in `primer.json`) Git accessible projects in parallel. _(A PR will be
-accepted to add Mercurial support.)_
-
-## Run flow
-
-- Ensure we have a `black` + `git` in PATH
-- Load projects from `primer.json`
-- Run projects in parallel with `--worker` workers (defaults to CPU count / 2)
-  - Checkout projects
-  - Run black and record result
-  - Clean up repository checkout _(can optionally be disabled via `--keep`)_
-- Display results summary to screen
-- Default to cleaning up `--work-dir` (which defaults to tempfile schemantics)
-- Return
-  - 0 for successful run
-  - < 0 for environment / internal error
-  - \> 0 for each project with an error
-
-## Speed up runs 🏎
-
-If you're running locally yourself to test black on lots of code try:
-
-- Using `-k` / `--keep` + `-w` / `--work-dir` so you don't have to re-checkout the repo
-  each run
-
-## CLI arguments
-
-```text
-Usage: black-primer [OPTIONS]
-
-  primer - prime projects for blackening... 🏴
-
-Options:
-  -c, --config PATH      JSON config file path  [default: /Users/cooper/repos/
-                         black/src/black_primer/primer.json]
-
-  --debug                Turn on debug logging  [default: False]
-  -k, --keep             Keep workdir + repos post run  [default: False]
-  -L, --long-checkouts   Pull big projects to test  [default: False]
-  -R, --rebase           Rebase project if already checked out  [default:
-                         False]
-
-  -w, --workdir PATH     Directory path for repo checkouts  [default: /var/fol
-                         ders/tc/hbwxh76j1hn6gqjd2n2sjn4j9k1glp/T/primer.20200
-                         517125229]
-
-  -W, --workers INTEGER  Number of parallel worker coroutines  [default: 2]
-  -h, --help             Show this message and exit.
-```
-
-## Primer config file
-
-The config file is in JSON format. Its main element is the `"projects"` dictionary and
-each parameter is explained below:
-
-```json
-{
-  "projects": {
-    "00_Example": {
-      "cli_arguments": "List of extra CLI arguments to pass Black for this project",
-      "expect_formatting_changes": "Boolean to indicate that the version of Black is expected to cause changes",
-      "git_clone_url": "URL you would pass `git clone` to check out this repo",
-      "long_checkout": "Boolean to have repo skipped by default unless `--long-checkouts` is specified",
-      "py_versions": "List of major Python versions to run this project with - all will do as you'd expect - run on ALL versions"
-    },
-    "aioexabgp": {
-      "cli_arguments": [],
-      "expect_formatting_changes": true,
-      "git_clone_url": "https://github.com/cooperlees/aioexabgp.git",
-      "long_checkout": false,
-      "py_versions": ["all", "3.8"]
-    }
-  }
-}
-```
-
-An example primer config file is used by Black
-[here](https://github.com/psf/black/blob/master/src/black_primer/primer.json)
-
-## Example run
-
-```console
-cooper-mbp:black cooper$ ~/venvs/b/bin/black-primer
-[2020-05-17 13:06:40,830] INFO: 4 projects to run Black over (lib.py:270)
-[2020-05-17 13:06:44,215] INFO: Analyzing results (lib.py:285)
--- primer results 📊 --
-
-3 / 4 succeeded (75.0%) ✅
-1 / 4 FAILED (25.0%) 💩
- - 0 projects disabled by config
- - 0 projects skipped due to Python version
- - 0 skipped due to long checkout
-
-Failed projects:
-
-## flake8-bugbear:
- - Returned 1
- - stdout:
---- tests/b303_b304.py	2020-05-17 20:04:09.991227 +0000
-+++ tests/b303_b304.py	2020-05-17 20:06:42.753851 +0000
-@@ -26,11 +26,11 @@
-     maxint = 5  # this is okay
-     # the following should not crash
-     (a, b, c) = list(range(3))
-     # it is different than this
-     a, b, c = list(range(3))
--    a, b, c, = list(range(3))
-+    a, b, c = list(range(3))
-     # and different than this
-     (a, b), c = list(range(3))
-     a, *b, c = [1, 2, 3, 4, 5]
-     b[1:3] = [0, 0]
-
-would reformat tests/b303_b304.py
-Oh no! 💥 💔 💥
-1 file would be reformatted, 22 files would be left unchanged.
-```
diff --git a/docs/conf.py b/docs/conf.py
index 9e03d05e937..d5673738452 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -13,60 +13,11 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
 from pathlib import Path
-import re
 import string
-from typing import Callable, Dict, List, Optional, Pattern, Tuple, Set
-from dataclasses import dataclass
-import logging
 
 from pkg_resources import get_distribution
 
-logging.basicConfig(format="%(levelname)s: %(message)s", level=logging.INFO)
-
-LOG = logging.getLogger(__name__)
-
 CURRENT_DIR = Path(__file__).parent
-README = CURRENT_DIR / ".." / "README.md"
-REFERENCE_DIR = CURRENT_DIR / "reference"
-STATIC_DIR = CURRENT_DIR / "_static"
-
-
-@dataclass
-class SrcRange:
-    """Tracks which part of a file to get a section's content.
-
-    Data:
-        start_line: The line where the section starts (i.e. its sub-header) (inclusive).
-        end_line: The line where the section ends (usually next sub-header) (exclusive).
-    """
-
-    start_line: int
-    end_line: int
-
-
-@dataclass
-class DocSection:
-    """Tracks information about a section of documentation.
-
-    Data:
-        name: The section's name. This will used to detect duplicate sections.
-        src: The filepath to get its contents.
-        processors: The processors to run before writing the section to CURRENT_DIR.
-        out_filename: The filename to use when writing the section to CURRENT_DIR.
-        src_range: The line range of SRC to gets its contents.
-    """
-
-    name: str
-    src: Path
-    src_range: SrcRange = SrcRange(0, 1_000_000)
-    out_filename: str = ""
-    processors: Tuple[Callable, ...] = ()
-
-    def get_out_filename(self) -> str:
-        if not self.out_filename:
-            return self.name + ".md"
-        else:
-            return self.out_filename
 
 
 def make_pypi_svg(version: str) -> None:
@@ -78,131 +29,10 @@ def make_pypi_svg(version: str) -> None:
         f.write(svg)
 
 
-def make_filename(line: str) -> str:
-    non_letters: Pattern = re.compile(r"[^a-z]+")
-    filename: str = line[3:].rstrip().lower()
-    filename = non_letters.sub("_", filename)
-    if filename.startswith("_"):
-        filename = filename[1:]
-    if filename.endswith("_"):
-        filename = filename[:-1]
-    return filename + ".md"
-
-
-def get_contents(section: DocSection) -> str:
-    """Gets the contents for the DocSection."""
-    contents: List[str] = []
-    src: Path = section.src
-    start_line: int = section.src_range.start_line
-    end_line: int = section.src_range.end_line
-    with open(src, "r", encoding="utf-8") as f:
-        for lineno, line in enumerate(f, start=1):
-            if lineno >= start_line and lineno < end_line:
-                contents.append(line)
-    result = "".join(contents)
-    # Let's make Prettier happy with the amount of trailing newlines in the sections.
-    if result.endswith("\n\n"):
-        result = result[:-1]
-    if not result.endswith("\n"):
-        result = result + "\n"
-    return result
-
-
-def get_sections_from_readme() -> List[DocSection]:
-    """Gets the sections from README so they can be processed by process_sections.
-
-    It opens README and goes down line by line looking for sub-header lines which
-    denotes a section. Once it finds a sub-header line, it will create a DocSection
-    object with all of the information currently available. Then on every line, it will
-    track the ending line index of the section. And it repeats this for every sub-header
-    line it finds.
-    """
-    sections: List[DocSection] = []
-    section: Optional[DocSection] = None
-    with open(README, "r", encoding="utf-8") as f:
-        for lineno, line in enumerate(f, start=1):
-            if line.startswith("## "):
-                filename = make_filename(line)
-                section_name = filename[:-3]
-                section = DocSection(
-                    name=str(section_name),
-                    src=README,
-                    src_range=SrcRange(lineno, lineno),
-                    out_filename=filename,
-                    processors=(fix_headers,),
-                )
-                sections.append(section)
-            if section is not None:
-                section.src_range.end_line += 1
-    return sections
-
-
-def fix_headers(contents: str) -> str:
-    """Fixes the headers of sections copied from README.
-
-    Removes one octothorpe (#) from all headers since the contents are no longer nested
-    in a root document (i.e. the README).
-    """
-    lines: List[str] = contents.splitlines()
-    fixed_contents: List[str] = []
-    for line in lines:
-        if line.startswith("##"):
-            line = line[1:]
-        fixed_contents.append(line + "\n")  # splitlines strips the leading newlines
-    return "".join(fixed_contents)
-
-
-def process_sections(
-    custom_sections: List[DocSection], readme_sections: List[DocSection]
-) -> None:
-    """Reads, processes, and writes sections to CURRENT_DIR.
-
-    For each section, the contents will be fetched, processed by processors
-    required by the section, and written to CURRENT_DIR. If it encounters duplicate
-    sections (i.e. shares the same name attribute), it will skip processing the
-    duplicates.
-
-    It processes custom sections before the README generated sections so sections in the
-    README can be overwritten with custom options.
-    """
-    processed_sections: Dict[str, DocSection] = {}
-    modified_files: Set[Path] = set()
-    sections: List[DocSection] = custom_sections
-    sections.extend(readme_sections)
-    for section in sections:
-        if section.name in processed_sections:
-            LOG.warning(
-                f"Skipping '{section.name}' from '{section.src}' as it is a duplicate"
-                f" of a custom section from '{processed_sections[section.name].src}'"
-            )
-            continue
-
-        LOG.info(f"Processing '{section.name}' from '{section.src}'")
-        target_path: Path = CURRENT_DIR / section.get_out_filename()
-        if target_path in modified_files:
-            LOG.warning(
-                f"{target_path} has been already written to, its contents will be"
-                " OVERWRITTEN and notices will be duplicated"
-            )
-        contents: str = get_contents(section)
-
-        # processors goes here
-        if fix_headers in section.processors:
-            contents = fix_headers(contents)
-
-        with open(target_path, "w", encoding="utf-8") as f:
-            if section.src.suffix == ".md" and section.src != target_path:
-                rel = section.src.resolve().relative_to(CURRENT_DIR.parent)
-                f.write(f'[//]: # "NOTE: THIS FILE WAS AUTOGENERATED FROM {rel}"\n\n')
-            f.write(contents)
-        processed_sections[section.name] = section
-        modified_files.add(target_path)
-
-
 # -- Project information -----------------------------------------------------
 
 project = "Black"
-copyright = "2020, Łukasz Langa and contributors to Black"
+copyright = "2018-Present, Łukasz Langa and contributors to Black"
 author = "Łukasz Langa and contributors to Black"
 
 # Autopopulate version
@@ -213,33 +43,7 @@ def process_sections(
 for sp in "abcfr":
     version = version.split(sp)[0]
 
-custom_sections = [
-    DocSection("the_black_code_style", CURRENT_DIR / "the_black_code_style.md"),
-    DocSection("editor_integration", CURRENT_DIR / "editor_integration.md"),
-    DocSection("blackd", CURRENT_DIR / "blackd.md"),
-    DocSection("black_primer", CURRENT_DIR / "black_primer.md"),
-    DocSection("contributing_to_black", CURRENT_DIR / ".." / "CONTRIBUTING.md"),
-]
-
-# Sphinx complains when there is a source file that isn't referenced in any of the docs.
-# Since some sections autogenerated from the README are unused warnings will appear.
-#
-# Sections must be listed to what their name is when passed through make_filename().
-blocklisted_sections_from_readme = {
-    "license",
-    "pragmatism",
-    "testimonials",
-    "used_by",
-    "change_log",
-}
-
 make_pypi_svg(release)
-readme_sections = get_sections_from_readme()
-readme_sections = [
-    x for x in readme_sections if x.name not in blocklisted_sections_from_readme
-]
-
-process_sections(custom_sections, readme_sections)
 
 
 # -- General configuration ---------------------------------------------------
@@ -254,11 +58,11 @@ def process_sections(
     "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
-    "recommonmark",
+    "myst_parser",
 ]
 
 # If you need extensions of a certain version or higher, list them here.
-needs_extensions = {"recommonmark": "0.5"}
+needs_extensions = {"myst_parser": "0.13.7"}
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -286,6 +90,17 @@ def process_sections(
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = "sphinx"
 
+# We need headers to be linkable to so ask MyST-Parser to autogenerate anchor IDs for
+# headers up to and including level 3.
+myst_heading_anchors = 3
+
+# Prettier support formatting some MyST syntax but not all, so let's disable the
+# unsupported yet still enabled by default ones.
+myst_disable_syntax = [
+    "myst_block_break",
+    "myst_line_comment",
+    "math_block",
+]
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -299,7 +114,6 @@ def process_sections(
         "about.html",
         "navigation.html",
         "relations.html",
-        "sourcelink.html",
         "searchbox.html",
     ]
 }
@@ -341,21 +155,6 @@ def process_sections(
 
 # -- Options for LaTeX output ------------------------------------------------
 
-latex_elements = {
-    # The paper size ('letterpaper' or 'a4paper').
-    #
-    # 'papersize': 'letterpaper',
-    # The font size ('10pt', '11pt' or '12pt').
-    #
-    # 'pointsize': '10pt',
-    # Additional stuff for the LaTeX preamble.
-    #
-    # 'preamble': '',
-    # Latex figure (float) alignment
-    #
-    # 'figure_align': 'htbp',
-}
-
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
diff --git a/docs/contributing/gauging_changes.md b/docs/contributing/gauging_changes.md
new file mode 100644
index 00000000000..6b70e0bc9bc
--- /dev/null
+++ b/docs/contributing/gauging_changes.md
@@ -0,0 +1,61 @@
+# Gauging changes
+
+A lot of the time, your change will affect formatting and/or performance. Quantifying
+these changes is hard, so we have tooling to help make it easier.
+
+It's recommended you evaluate the quantifiable changes your _Black_ formatting
+modification causes before submitting a PR. Think about if the change seems disruptive
+enough to cause frustration to projects that are already "black formatted".
+
+## black-primer
+
+`black-primer` is a tool built for CI (and humans) to have _Black_ `--check` a number of
+Git accessible projects in parallel. (configured in `primer.json`) _(A PR will be
+accepted to add Mercurial support.)_
+
+### Run flow
+
+- Ensure we have a `black` + `git` in PATH
+- Load projects from `primer.json`
+- Run projects in parallel with `--worker` workers (defaults to CPU count / 2)
+  - Checkout projects
+  - Run black and record result
+  - Clean up repository checkout _(can optionally be disabled via `--keep`)_
+- Display results summary to screen
+- Default to cleaning up `--work-dir` (which defaults to tempfile schemantics)
+- Return
+  - 0 for successful run
+  - \< 0 for environment / internal error
+  - \> 0 for each project with an error
+
+### Speed up runs 🏎
+
+If you're running locally yourself to test black on lots of code try:
+
+- Using `-k` / `--keep` + `-w` / `--work-dir` so you don't have to re-checkout the repo
+  each run
+
+### CLI arguments
+
+```text
+Usage: black-primer [OPTIONS]
+
+  primer - prime projects for blackening... 🏴
+
+Options:
+  -c, --config PATH      JSON config file path  [default: /Users/cooper/repos/
+                         black/src/black_primer/primer.json]
+
+  --debug                Turn on debug logging  [default: False]
+  -k, --keep             Keep workdir + repos post run  [default: False]
+  -L, --long-checkouts   Pull big projects to test  [default: False]
+  -R, --rebase           Rebase project if already checked out  [default:
+                         False]
+
+  -w, --workdir PATH     Directory path for repo checkouts  [default: /var/fol
+                         ders/tc/hbwxh76j1hn6gqjd2n2sjn4j9k1glp/T/primer.20200
+                         517125229]
+
+  -W, --workers INTEGER  Number of parallel worker coroutines  [default: 2]
+  -h, --help             Show this message and exit.
+```
diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst
new file mode 100644
index 00000000000..68dfcd60c28
--- /dev/null
+++ b/docs/contributing/index.rst
@@ -0,0 +1,39 @@
+Contributing
+============
+
+.. toctree::
+  :hidden:
+
+  the_basics
+  gauging_changes
+  reference/reference_summary
+
+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?
+
+.. rubric:: Bird's eye view
+
+In terms of inspiration, *Black* is about as configurable as *gofmt*. This is
+deliberate.
+
+Bug reports and fixes are always welcome! Please follow the
+`issue template on GitHub <https://github.com/psf/black/issues/new>`_ 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
+up, and so on - go for it! On the other hand, if your answer is "because I don't like a
+particular formatting" then you're not ready to embrace *Black* yet. Such changes are
+unlikely to get accepted. You can still try but prepare to be disappointed.
+
+.. rubric:: Contents
+
+This section covers the following topics:
+
+- :doc:`the_basics`
+- :doc:`gauging_changes`
+- :doc:`reference/reference_summary`
+
+For an overview on contributing to the *Black*, please checkout :doc:`the_basics`.
+
+If you need a reference of the functions, classes, etc. available to you while
+developing *Black*, there's the :doc:`reference/reference_summary` docs.
diff --git a/docs/reference/reference_classes.rst b/docs/contributing/reference/reference_classes.rst
similarity index 100%
rename from docs/reference/reference_classes.rst
rename to docs/contributing/reference/reference_classes.rst
diff --git a/docs/reference/reference_exceptions.rst b/docs/contributing/reference/reference_exceptions.rst
similarity index 100%
rename from docs/reference/reference_exceptions.rst
rename to docs/contributing/reference/reference_exceptions.rst
diff --git a/docs/reference/reference_functions.rst b/docs/contributing/reference/reference_functions.rst
similarity index 100%
rename from docs/reference/reference_functions.rst
rename to docs/contributing/reference/reference_functions.rst
diff --git a/docs/reference/reference_summary.rst b/docs/contributing/reference/reference_summary.rst
similarity index 51%
rename from docs/reference/reference_summary.rst
rename to docs/contributing/reference/reference_summary.rst
index 780a4b46ed8..f6ff4681557 100644
--- a/docs/reference/reference_summary.rst
+++ b/docs/contributing/reference/reference_summary.rst
@@ -1,6 +1,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!
+
 *Contents are subject to change.*
 
 .. toctree::
diff --git a/docs/contributing_to_black.md b/docs/contributing/the_basics.md
similarity index 68%
rename from docs/contributing_to_black.md
rename to docs/contributing/the_basics.md
index b911b465afd..461bff96505 100644
--- a/docs/contributing_to_black.md
+++ b/docs/contributing/the_basics.md
@@ -1,28 +1,11 @@
-[//]: # "NOTE: THIS FILE WAS AUTOGENERATED FROM CONTRIBUTING.md"
+# The basics
 
-# 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?
-
-## Bird's eye view
-
-In terms of inspiration, _Black_ is about as configurable as _gofmt_. This is
-deliberate.
-
-Bug reports and fixes are always welcome! Please follow the
-[issue template on GitHub](https://github.com/psf/black/issues/new) 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
-up, and so on - go for it! On the other hand, if your answer is "because I don't like a
-particular formatting" then you're not ready to embrace _Black_ yet. Such changes are
-unlikely to get accepted. You can still try but prepare to be disappointed.
+An overview on contributing to the _Black_ project.
 
 ## Technicalities
 
 Development on the latest version of Python is preferred. As of this writing it's 3.9.
-You can use any operating system. I am using macOS myself and CentOS at work.
+You can use any operating system.
 
 Install all development dependencies using:
 
@@ -63,7 +46,7 @@ $ black-primer [-k -w /tmp/black_test_repos]
 ### News / Changelog Requirement
 
 `Black` has CI that will check for an entry corresponding to your PR in `CHANGES.md`. If
-you feel this PR not require a changelog entry please state that in a comment and a
+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:
 
@@ -71,11 +54,17 @@ have a line in the following format:
 - `Black` is now more awesome (#X)
 ```
 
-To workout X, please use
+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.
 
+### 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.
+
 ### Docs Testing
 
 If you make changes to docs, you can test they still build locally too.
@@ -96,7 +85,7 @@ your PR. You may need to change
 configuration for it to pass.
 
 For more `black-primer` information visit the
-[documentation](https://github.com/psf/black/blob/master/docs/black_primer.md).
+[documentation](./gauging_changes.md#black-primer).
 
 ## Hygiene
 
diff --git a/docs/getting_started.md b/docs/getting_started.md
new file mode 100644
index 00000000000..a509d34e903
--- /dev/null
+++ b/docs/getting_started.md
@@ -0,0 +1,49 @@
+# Getting Started
+
+New to _Black_? Don't worry, you've found the perfect place to get started!
+
+## Do you like the _Black_ code style?
+
+Before using _Black_ on some of your code, it might be a good idea to first understand
+how _Black_ will format your code. _Black_ isn't for everyone and you may find something
+that is a dealbreaker for you personally, which is okay! The current _Black_ code style
+[is described here](./the_black_code_style/current_style.md).
+
+## Try it out online
+
+Also, you can try out _Black_ online for minimal fuss on the
+[Black Playground](https://black.vercel.app) generously created by José Padilla.
+
+## Installation
+
+_Black_ can be installed by running `pip install black`. It requires Python 3.6.2+ to
+run, but can format Python 2 code too. Python 2 support needs the `typed_ast`
+dependency, which be installed with `pip install black[python2]`.
+
+If you can't wait for the latest _hotness_ and want to install from GitHub, use:
+
+`pip install git+git://github.com/psf/black`
+
+## Basic usage
+
+To get started right away with sensible defaults:
+
+```sh
+black {source_file_or_directory}...
+```
+
+You can run _Black_ as a package if running it as a script doesn't work:
+
+```sh
+python -m black {source_file_or_directory}...
+```
+
+## Next steps
+
+Took a look at [the _Black_ code style](./the_black_code_style/current_style.md) and
+tried out _Black_? Fantastic, you're ready for more. Why not explore some more on using
+_Black_ by reading
+[Usage and Configuration: The basics](./usage_and_configuration/the_basics.md).
+Alternatively, you can check out the
+[Introducing _Black_ to your project](./guides/introducing_black_to_your_project.md)
+guide.
diff --git a/docs/github_actions.md b/docs/github_actions.md
deleted file mode 100644
index bd4680998d9..00000000000
--- a/docs/github_actions.md
+++ /dev/null
@@ -1,27 +0,0 @@
-[//]: # "NOTE: THIS FILE WAS AUTOGENERATED FROM README.md"
-
-# GitHub Actions
-
-Create a file named `.github/workflows/black.yml` inside your repository with:
-
-```yaml
-name: Lint
-
-on: [push, pull_request]
-
-jobs:
-  lint:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
-      - uses: psf/black@stable
-        with:
-          black_args: ". --check"
-```
-
-## Inputs
-
-### `black_args`
-
-**optional**: Black input arguments. Defaults to `. --check --diff`.
diff --git a/docs/guides/index.rst b/docs/guides/index.rst
new file mode 100644
index 00000000000..717c5c4d066
--- /dev/null
+++ b/docs/guides/index.rst
@@ -0,0 +1,14 @@
+Guides
+======
+
+.. toctree::
+  :hidden:
+
+  introducing_black_to_your_project
+  using_black_with_other_tools
+
+Wondering how to do something specific? You've found the right place! Listed below
+are topic specific guides available:
+
+- :doc:`introducing_black_to_your_project`
+- :doc:`using_black_with_other_tools`
diff --git a/docs/guides/introducing_black_to_your_project.md b/docs/guides/introducing_black_to_your_project.md
new file mode 100644
index 00000000000..71ccf7c114c
--- /dev/null
+++ b/docs/guides/introducing_black_to_your_project.md
@@ -0,0 +1,50 @@
+# Introducing _Black_ to your project
+
+```{note}
+This guide is incomplete. Contributions are welcomed and would be deeply
+appreciated!
+```
+
+## Avoiding ruining git blame
+
+A long-standing argument against moving to automated code formatters like _Black_ is
+that the migration will clutter up the output of `git blame`. This was a valid argument,
+but since Git version 2.23, Git natively supports
+[ignoring revisions in blame](https://git-scm.com/docs/git-blame#Documentation/git-blame.txt---ignore-revltrevgt)
+with the `--ignore-rev` option. You can also pass a file listing the revisions to ignore
+using the `--ignore-revs-file` option. The changes made by the revision will be ignored
+when assigning blame. Lines modified by an ignored revision will be blamed on the
+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.
+
+```text
+# Migrate code style to Black
+5b4ab991dede475d393e9d69ec388fd6bd949699
+```
+
+Afterwards, you can pass that file to `git blame` and see clean and meaningful blame
+information.
+
+```console
+$ git blame important.py --ignore-revs-file .git-blame-ignore-revs
+7a1ae265 (John Smith 2019-04-15 15:55:13 -0400 1) def very_important_function(text, file):
+abdfd8b0 (Alice Doe  2019-09-23 11:39:32 -0400 2)     text = text.lstrip()
+7a1ae265 (John Smith 2019-04-15 15:55:13 -0400 3)     with open(file, "r+") as f:
+7a1ae265 (John Smith 2019-04-15 15:55:13 -0400 4)         f.write(formatted)
+```
+
+You can even configure `git` to automatically ignore revisions listed in a file on every
+call to `git blame`.
+
+```console
+$ git config blame.ignoreRevsFile .git-blame-ignore-revs
+```
+
+**The one caveat is that GitHub and GitLab do not yet support ignoring revisions using
+their native UI of blame.** 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) and please let GitHub
+know!)
diff --git a/docs/compatible_configs.md b/docs/guides/using_black_with_other_tools.md
similarity index 92%
rename from docs/compatible_configs.md
rename to docs/guides/using_black_with_other_tools.md
index de81769f72d..4b22f670fe1 100644
--- a/docs/compatible_configs.md
+++ b/docs/guides/using_black_with_other_tools.md
@@ -1,4 +1,6 @@
-# _Black_ compatible configurations
+# Using _Black_ with other tools
+
+## Black compatible configurations
 
 All of Black's changes are harmless (or at least, they should be), but a few do conflict
 against other tools. It is not uncommon to be using other tools alongside _Black_ like
@@ -13,13 +15,13 @@ tools, using **their** supported file formats.
 Compatible configuration files can be
 [found here](https://github.com/psf/black/blob/master/docs/compatible_configs/).
 
-## isort
+### isort
 
 [isort](https://pypi.org/p/isort/) helps to sort and format imports in your Python code.
 _Black_ also formats imports, but in a different way from isort's defaults which leads
 to conflicting changes.
 
-### Profile
+#### Profile
 
 Since version 5.0.0, isort supports
 [profiles](https://pycqa.github.io/isort/docs/configuration/profiles/) to allow easy
@@ -32,7 +34,7 @@ by isort. Below, an example for `pyproject.toml`:
 profile = "black"
 ```
 
-### Custom Configuration
+#### Custom Configuration
 
 If you're using an isort version that is older than 5.0.0 or you have some custom
 configuration for _Black_, you can tweak your isort configuration to make it compatible
@@ -47,12 +49,12 @@ ensure_newline_before_comments = True
 line_length = 88
 ```
 
-### Why those options above?
+#### Why those options above?
 
 _Black_ wraps imports that surpass `line-length` by moving identifiers into their own
 indented line. If that still doesn't fit the bill, it will put all of them in separate
 lines and put a trailing comma. A more detailed explanation of this behaviour can be
-[found here](https://github.com/psf/black/blob/master/docs/the_black_code_style.md#how-black-wraps-lines).
+[found here](../the_black_code_style/current_style.md#how-black-wraps-lines).
 
 isort's default mode of wrapping imports that extend past the `line_length` limit is
 "Grid".
@@ -90,7 +92,7 @@ works the same as with _Black_.
 **Please note** `ensure_newline_before_comments = True` only works since isort >= 5 but
 does not break older versions so you can keep it if you are running previous versions.
 
-### Formats
+#### Formats
 
 <details>
 <summary>.isort.cfg</summary>
@@ -132,21 +134,21 @@ profile = black
 
 </details>
 
-## Flake8
+### Flake8
 
 [Flake8](https://pypi.org/p/flake8/) is a code linter. It warns you of syntax errors,
 possible bugs, stylistic errors, etc. For the most part, Flake8 follows
 [PEP 8](https://www.python.org/dev/peps/pep-0008/) when warning about stylistic errors.
 There are a few deviations that cause incompatibilities with _Black_.
 
-### Configuration
+#### Configuration
 
 ```
 max-line-length = 88
 extend-ignore = E203
 ```
 
-### Why those options above?
+#### Why those options above?
 
 In some cases, as determined by PEP 8, _Black_ will enforce an equal amount of
 whitespace around slice operators. Due to this, Flake8 will raise
@@ -163,7 +165,7 @@ in your configuration.
 Also, as like with isort, flake8 should be configured to allow lines up to the length
 limit of `88`, _Black_'s default. This explains `max-line-length = 88`.
 
-### Formats
+#### Formats
 
 <details>
 <summary>.flake8</summary>
@@ -198,24 +200,24 @@ extend-ignore = E203
 
 </details>
 
-## Pylint
+### Pylint
 
 [Pylint](https://pypi.org/p/pylint/) is also a code linter like Flake8. It has the same
 checks as flake8 and more. In particular, it has more formatting checks regarding style
 conventions like variable naming. With so many checks, Pylint is bound to have some
 mixed feelings about _Black_'s formatting style.
 
-### Configuration
+#### Configuration
 
 ```
 disable = C0330, C0326
 max-line-length = 88
 ```
 
-### Why those options above?
+#### Why those options above?
 
 When _Black_ is folding very long expressions, the closing brackets will
-[be dedented](https://github.com/psf/black/blob/master/docs/the_black_code_style.md#how-black-wraps-lines).
+[be dedented](../the_black_code_style/current_style.md#how-black-wraps-lines).
 
 ```py3
 ImportantClass.important_method(
@@ -223,7 +225,7 @@ ImportantClass.important_method(
 )
 ```
 
-Although, this style is PEP 8 compliant, Pylint will raise
+Although this style is PEP 8 compliant, Pylint will raise
 `C0330: Wrong hanging indentation before block (add 4 spaces)` warnings. Since _Black_
 isn't configurable on this style, Pylint should be told to ignore these warnings via
 `disable = C0330`.
@@ -234,7 +236,7 @@ warning `C0326: Bad whitespace` should be disabled using `disable = C0326`.
 And as usual, Pylint should be configured to only complain about lines that surpass `88`
 characters via `max-line-length = 88`.
 
-### Formats
+#### Formats
 
 <details>
 <summary>pylintrc</summary>
diff --git a/docs/index.rst b/docs/index.rst
index f03d247d949..a7a7160f71f 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -14,12 +14,27 @@ possible. Blackened code looks the same regardless of the project
 you're reading. Formatting becomes transparent after a while and you
 can focus on the content instead.
 
-Try it out now using the `Black Playground <https://black.now.sh>`_.
+Try it out now using the `Black Playground <https://black.vercel.app>`_.
 
-.. note::
+.. admonition:: Note - this is a beta product
+
+   *Black* is already `successfully used <https://github.com/psf/black#used-by>`_ by
+   many projects, small and big. *Black* has a comprehensive test suite, with efficient
+   parallel tests, our own auto  formatting and parallel Continuous Integration runner.
+   However, *Black* is still beta. Things will probably be wonky for a while. This is
+   made explicit by the "Beta" trove classifier, as well as by the "b" in the versio
+   number. What this means for you is that **until the formatter becomes stable, you
+   should expect some formatting to change in the future**. That being said, no drastic
+   stylistic changes are planned, mostly responses to bug reports.
 
-   `Black is beta <installation_and_usage.html#note-this-is-a-beta-product>`_.
+   Also, as a safety measure which slows down processing, *Black* will check that the
+   reformatted code still produces a valid AST that is effectively equivalent to the
+   original (see the
+   `Pragmatism <./the_black_code_style/current_style.html#pragmatism>`_
+   section for details). If you're feeling confident, use ``--fast``.
 
+.. note::
+   :doc:`Black is licensed under the MIT license <license>`.
 
 Testimonials
 ------------
@@ -42,28 +57,62 @@ and `pipenv <https://docs.pipenv.org/>`_:
 
    *This vastly improves the formatting of our code. Thanks a ton!*
 
+
+Show your style
+---------------
+
+Use the badge in your project's README.md:
+
+.. code-block:: md
+
+   [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+
+Using the badge in README.rst:
+
+.. code-block:: rst
+
+   .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
+      :target: https://github.com/psf/black
+
+Looks like this:
+
+.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
+   :target: https://github.com/psf/black
+
 Contents
 --------
 
 .. toctree::
-   :maxdepth: 2
-
-   installation_and_usage
-   the_black_code_style
-   pyproject_toml
-   compatible_configs
-   editor_integration
-   blackd
-   black_primer
-   version_control_integration
-   github_actions
-   ignoring_unmodified_files
-   contributing_to_black
-   show_your_style
+   :maxdepth: 3
+   :includehidden:
+
+   the_black_code_style/index
+
+.. toctree::
+   :maxdepth: 3
+   :includehidden:
+
+   getting_started
+   usage_and_configuration/index
+   integrations/index
+   guides/index
+
+.. toctree::
+   :maxdepth: 3
+   :includehidden:
+
+   contributing/index
    change_log
-   reference/reference_summary
    authors
 
+.. toctree::
+   :hidden:
+
+   GitHub ↪ <https://github.com/psf/black>
+   PyPI ↪ <https://pypi.org/project/black>
+   IRC ↪ <https://webchat.freenode.net/?channels=%23blackformatter>
+
 Indices and tables
 ==================
 
diff --git a/docs/installation_and_usage.md b/docs/installation_and_usage.md
deleted file mode 100644
index fcde49f4e3a..00000000000
--- a/docs/installation_and_usage.md
+++ /dev/null
@@ -1,195 +0,0 @@
-[//]: # "NOTE: THIS FILE WAS AUTOGENERATED FROM README.md"
-
-# Installation and usage
-
-## Installation
-
-_Black_ can be installed by running `pip install black`. It requires Python 3.6.0+ to
-run but you can reformat Python 2 code with it, too.
-
-### Install from GitHub
-
-If you can't wait for the latest _hotness_ and want to install from GitHub, use:
-
-`pip install git+git://github.com/psf/black`
-
-## Usage
-
-To get started right away with sensible defaults:
-
-```sh
-black {source_file_or_directory}
-```
-
-You can run _Black_ as a package if running it as a script doesn't work:
-
-```sh
-python -m black {source_file_or_directory}
-```
-
-## Command line options
-
-_Black_ doesn't provide many options. You can list them by running `black --help`:
-
-```text
-Usage: black [OPTIONS] [SRC]...
-
-  The uncompromising code formatter.
-
-Options:
-  -c, --code TEXT                 Format the code passed in as a string.
-  -l, --line-length INTEGER       How many characters per line to allow.
-                                  [default: 88]
-
-  -t, --target-version [py27|py33|py34|py35|py36|py37|py38|py39]
-                                  Python versions that should be supported by
-                                  Black's output. [default: per-file auto-
-                                  detection]
-
-  --pyi                           Format all input files like typing stubs
-                                  regardless of file extension (useful when
-                                  piping source on standard input).
-
-  -S, --skip-string-normalization
-                                  Don't normalize string quotes or prefixes.
-  -C, --skip-magic-trailing-comma
-                                  Don't use trailing commas as a reason to
-                                  split lines.
-
-  --check                         Don't write the files back, just return the
-                                  status.  Return code 0 means nothing would
-                                  change.  Return code 1 means some files
-                                  would be reformatted. Return code 123 means
-                                  there was an internal error.
-
-  --diff                          Don't write the files back, just output a
-                                  diff for each file on stdout.
-
-  --color / --no-color            Show colored diff. Only applies when
-                                  `--diff` is given.
-
-  --fast / --safe                 If --fast given, skip temporary sanity
-                                  checks. [default: --safe]
-
-  --include TEXT                  A regular expression that matches files and
-                                  directories that should be included on
-                                  recursive searches.  An empty value means
-                                  all files are included regardless of the
-                                  name.  Use forward slashes for directories
-                                  on all platforms (Windows, too).  Exclusions
-                                  are calculated first, inclusions later.
-                                  [default: \.pyi?$]
-
-  --exclude TEXT                  A regular expression that matches files and
-                                  directories that should be excluded on
-                                  recursive searches.  An empty value means no
-                                  paths are excluded. Use forward slashes for
-                                  directories on all platforms (Windows, too).
-                                  Exclusions are calculated first, inclusions
-                                  later.  [default: /(\.direnv|\.eggs|\.git|\.
-                                  hg|\.mypy_cache|\.nox|\.tox|\.venv|venv|\.sv
-                                  n|_build|buck-out|build|dist)/]
-
-  --force-exclude TEXT            Like --exclude, but files and directories
-                                  matching this regex will be excluded even
-                                  when they are passed explicitly as
-                                  arguments.
-
-  --extend-exclude TEXT           Like --exclude, but adds additional files
-                                  and directories on top of the excluded
-                                  ones. (useful if you simply want to add to
-                                  the default)
-
-  --stdin-filename TEXT           The name of the file when passing it through
-                                  stdin. Useful to make sure Black will
-                                  respect --force-exclude option on some
-                                  editors that rely on using stdin.
-
-  -q, --quiet                     Don't emit non-error messages to stderr.
-                                  Errors are still emitted; silence those with
-                                  2>/dev/null.
-
-  -v, --verbose                   Also emit messages to stderr about files
-                                  that were not changed or were ignored due to
-                                  exclusion patterns.
-
-  --version                       Show the version and exit.
-  --config FILE                   Read configuration from FILE path.
-  -h, --help                      Show this message and exit.
-```
-
-_Black_ is a well-behaved Unix-style command-line tool:
-
-- it does nothing if no sources are passed to it;
-- it will read from standard input and write to standard output if `-` is used as the
-  filename;
-- it only outputs messages to users on standard error;
-- exits with code 0 unless an internal error occurred (or `--check` was used).
-
-## Using _Black_ with other tools
-
-While _Black_ enforces formatting that conforms to PEP 8, other tools may raise warnings
-about _Black_'s changes or will overwrite _Black_'s changes. A good example of this is
-[isort](https://pypi.org/p/isort). Since _Black_ is barely configurable, these tools
-should be configured to neither warn about nor overwrite _Black_'s changes.
-
-Actual details on _Black_ compatible configurations for various tools can be found in
-[compatible_configs](https://github.com/psf/black/blob/master/docs/compatible_configs.md#black-compatible-configurations).
-
-## Migrating your code style without ruining git blame
-
-A long-standing argument against moving to automated code formatters like _Black_ is
-that the migration will clutter up the output of `git blame`. This was a valid argument,
-but since Git version 2.23, Git natively supports
-[ignoring revisions in blame](https://git-scm.com/docs/git-blame#Documentation/git-blame.txt---ignore-revltrevgt)
-with the `--ignore-rev` option. You can also pass a file listing the revisions to ignore
-using the `--ignore-revs-file` option. The changes made by the revision will be ignored
-when assigning blame. Lines modified by an ignored revision will be blamed on the
-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.
-
-```
-# Migrate code style to Black
-5b4ab991dede475d393e9d69ec388fd6bd949699
-```
-
-Afterwards, you can pass that file to `git blame` and see clean and meaningful blame
-information.
-
-```console
-$ git blame important.py --ignore-revs-file .git-blame-ignore-revs
-7a1ae265 (John Smith 2019-04-15 15:55:13 -0400 1) def very_important_function(text, file):
-abdfd8b0 (Alice Doe  2019-09-23 11:39:32 -0400 2)     text = text.lstrip()
-7a1ae265 (John Smith 2019-04-15 15:55:13 -0400 3)     with open(file, "r+") as f:
-7a1ae265 (John Smith 2019-04-15 15:55:13 -0400 4)         f.write(formatted)
-```
-
-You can even configure `git` to automatically ignore revisions listed in a file on every
-call to `git blame`.
-
-```console
-$ git config blame.ignoreRevsFile .git-blame-ignore-revs
-```
-
-**The one caveat is that GitHub and GitLab do not yet support ignoring revisions using
-their native UI of blame.** 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) and please let GitHub
-know!)
-
-## NOTE: This is a beta product
-
-_Black_ is already [successfully used](https://github.com/psf/black#used-by) by many
-projects, small and big. It also sports a decent test suite. However, it is still very
-new. Things will probably be wonky for a while. This is made explicit by the "Beta"
-trove classifier, as well as by the "b" in the version number. What this means for you
-is that **until the formatter becomes stable, you should expect some formatting to
-change in the future**. That being said, no drastic stylistic changes are planned,
-mostly responses to bug reports.
-
-Also, as a temporary safety measure, _Black_ will check that the reformatted code still
-produces a valid AST that is equivalent to the original. This slows it down. If you're
-feeling confident, use `--fast`.
diff --git a/docs/editor_integration.md b/docs/integrations/editors.md
similarity index 85%
rename from docs/editor_integration.md
rename to docs/integrations/editors.md
index f2d21f21113..6a69e9e33fd 100644
--- a/docs/editor_integration.md
+++ b/docs/integrations/editors.md
@@ -4,7 +4,7 @@
 
 Options include the following:
 
-- [purcell/reformatter.el](https://github.com/purcell/reformatter.el)
+- [wbolster/emacs-python-black](https://github.com/wbolster/emacs-python-black)
 - [proofit404/blacken](https://github.com/pythonic-emacs/blacken)
 - [Elpy](https://github.com/jorgenschaefer/elpy).
 
@@ -16,7 +16,7 @@ Options include the following:
    $ pip install black
    ```
 
-2. Locate your `black` installation folder.
+1. Locate your `black` installation folder.
 
    On macOS / Linux / BSD:
 
@@ -35,7 +35,7 @@ Options include the following:
    Note that if you are using a virtual environment detected by PyCharm, this is an
    unneeded step. In this case the path to `black` is `$PyInterpreterDirectory$/black`.
 
-3. Open External tools in PyCharm/IntelliJ IDEA
+1. Open External tools in PyCharm/IntelliJ IDEA
 
    On macOS:
 
@@ -45,29 +45,29 @@ Options include the following:
 
    `File -> Settings -> Tools -> External Tools`
 
-4. Click the + icon to add a new external tool with the following values:
+1. Click the + icon to add a new external tool with the following values:
 
    - Name: Black
    - Description: Black is the uncompromising Python code formatter.
-   - Program: <install_location_from_step_2>
+   - Program: \<install_location_from_step_2>
    - Arguments: `"$FilePath$"`
 
-5. Format the currently opened file by selecting `Tools -> External Tools -> black`.
+1. Format the currently opened file by selecting `Tools -> External Tools -> black`.
 
    - Alternatively, you can set a keyboard shortcut by navigating to
      `Preferences or Settings -> Keymap -> External Tools -> External Tools - Black`.
 
-6. Optionally, run _Black_ on every file save:
+1. Optionally, run _Black_ on every file save:
 
    1. Make sure you have the
       [File Watchers](https://plugins.jetbrains.com/plugin/7177-file-watchers) plugin
       installed.
-   2. Go to `Preferences or Settings -> Tools -> File Watchers` and click `+` to add a
+   1. Go to `Preferences or Settings -> Tools -> File Watchers` and click `+` to add a
       new watcher:
       - Name: Black
       - File type: Python
       - Scope: Project Files
-      - Program: <install_location_from_step_2>
+      - Program: \<install_location_from_step_2>
       - Arguments: `$FilePath$`
       - Output paths to refresh: `$FilePath$`
       - Working directory: `$ProjectFileDir$`
@@ -87,13 +87,13 @@ Wing supports black via the OS Commands tool, as explained in the Wing documenta
    $ pip install black
    ```
 
-2. Make sure it runs from the command line, e.g.
+1. Make sure it runs from the command line, e.g.
 
    ```console
    $ black --help
    ```
 
-3. In Wing IDE, activate the **OS Commands** panel and define the command **black** to
+1. In Wing IDE, activate the **OS Commands** panel and define the command **black** to
    execute black on the currently selected file:
 
    - Use the Tools -> OS Commands menu selection
@@ -106,7 +106,7 @@ Wing supports black via the OS Commands tool, as explained in the Wing documenta
      - [x] Auto-save files before execution
      - [x] Line mode
 
-4. Select a file in the editor and press **F1** , or whatever key binding you selected
+1. Select a file in the editor and press **F1** , or whatever key binding you selected
    in step 3, to reformat the file.
 
 ## Vim
@@ -238,8 +238,10 @@ $ pip install -U black --no-binary regex,typed-ast
 ### With ALE
 
 1. Install [`ale`](https://github.com/dense-analysis/ale)
-2. Install `black`
-3. Add this to your vimrc:
+
+1. Install `black`
+
+1. Add this to your vimrc:
 
    ```vim
    let g:ale_fixers = {}
@@ -256,10 +258,10 @@ $ gedit <file_name>
 ```
 
 1. `Go to edit > preferences > plugins`
-2. Search for `external tools` and activate it.
-3. In `Tools menu -> Manage external tools`
-4. Add a new tool using `+` button.
-5. Copy the below content to the code window.
+1. Search for `external tools` and activate it.
+1. In `Tools menu -> Manage external tools`
+1. Add a new tool using `+` button.
+1. Copy the below content to the code window.
 
 ```console
 #!/bin/bash
@@ -319,17 +321,3 @@ hook global WinSetOption filetype=python %{
 ## Thonny
 
 Use [Thonny-black-code-format](https://github.com/Franccisco/thonny-black-code-format).
-
-## Other integrations
-
-Other editors and tools will require external contributions.
-
-Patches welcome! ✨ 🍰 ✨
-
-Any tool that can pipe code through _Black_ using its stdio mode (just
-[use `-` as the file name](https://www.tldp.org/LDP/abs/html/special-chars.html#DASHREF2)).
-The formatted code will be returned on stdout (unless `--check` was passed). _Black_
-will still emit messages on stderr but that shouldn't affect your use case.
-
-This can be used for example with PyCharm's or IntelliJ's
-[File Watchers](https://www.jetbrains.com/help/pycharm/file-watchers.html).
diff --git a/docs/integrations/github_actions.md b/docs/integrations/github_actions.md
new file mode 100644
index 00000000000..9e8cf436453
--- /dev/null
+++ b/docs/integrations/github_actions.md
@@ -0,0 +1,35 @@
+# GitHub Actions integration
+
+You can use _Black_ within a GitHub Actions workflow without setting your own Python
+environment. Great for enforcing that your code matches the _Black_ code style.
+
+## Usage
+
+Create a file named `.github/workflows/black.yml` inside your repository with:
+
+```yaml
+name: Lint
+
+on: [push, pull_request]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-python@v2
+      - uses: psf/black@stable
+```
+
+We recommend the use of the `@stable` tag, but per version tags also exist if you prefer
+that.
+
+You may use `options` (Default is `'--check --diff'`) and `src` (Default is `'.'`) as
+follows:
+
+```yaml
+- uses: psf/black@stable
+  with:
+    options: "--check --verbose"
+    src: "./src"
+```
diff --git a/docs/integrations/index.rst b/docs/integrations/index.rst
new file mode 100644
index 00000000000..ed62ebcf044
--- /dev/null
+++ b/docs/integrations/index.rst
@@ -0,0 +1,28 @@
+Integrations
+============
+
+.. toctree::
+    :hidden:
+
+    editors
+    github_actions
+    source_version_control
+
+*Black* can be integrated into many environments, providing a better and smoother experience. Documentation for integrating *Black* with a tool can be found for the
+following areas:
+
+- :doc:`Editor / IDE <./editors>`
+- :doc:`GitHub Actions <./github_actions>`
+- :doc:`Source version control <./source_version_control>`
+
+Editors and tools not listed will require external contributions.
+
+Patches welcome! ✨ 🍰 ✨
+
+Any tool can pipe code through *Black* using its stdio mode (just
+`use \`-\` as the file name <https://www.tldp.org/LDP/abs/html/special-chars.html#DASHREF2>`_).
+The formatted code will be returned on stdout (unless ``--check`` was passed). *Black*
+will still emit messages on stderr but that shouldn't affect your use case.
+
+This can be used for example with PyCharm's or IntelliJ's
+`File Watchers <https://www.jetbrains.com/help/pycharm/file-watchers.html>`_.
diff --git a/docs/integrations/source_version_control.md b/docs/integrations/source_version_control.md
new file mode 100644
index 00000000000..1ca6161bf0b
--- /dev/null
+++ b/docs/integrations/source_version_control.md
@@ -0,0 +1,14 @@
+# Version control integration
+
+Use [pre-commit](https://pre-commit.com/). Once you
+[have it installed](https://pre-commit.com/#install), add this to the
+`.pre-commit-config.yaml` in your repository:
+
+```yaml
+repos:
+  - repo: https://github.com/psf/black
+    rev: stable # Replace by any tag/version: https://github.com/psf/black/tags
+    hooks:
+      - id: black
+        language_version: python3 # Should be a command that runs python3.6+
+```
diff --git a/docs/license.rst b/docs/license.rst
new file mode 100644
index 00000000000..2dc20a24492
--- /dev/null
+++ b/docs/license.rst
@@ -0,0 +1,6 @@
+:orphan:
+
+License
+=======
+
+.. include:: ../LICENSE
diff --git a/docs/pyproject_toml.md b/docs/pyproject_toml.md
deleted file mode 100644
index ed88f37aa4a..00000000000
--- a/docs/pyproject_toml.md
+++ /dev/null
@@ -1,91 +0,0 @@
-[//]: # "NOTE: THIS FILE WAS AUTOGENERATED FROM README.md"
-
-# pyproject.toml
-
-_Black_ is able to read project-specific default values for its command line options
-from a `pyproject.toml` file. This is especially useful for specifying custom
-`--include` and `--exclude`/`--force-exclude`/`--extend-exclude` patterns for your
-project.
-
-**Pro-tip**: If you're asking yourself "Do I need to configure anything?" the answer is
-"No". _Black_ is all about sensible defaults.
-
-## What on Earth is a `pyproject.toml` file?
-
-[PEP 518](https://www.python.org/dev/peps/pep-0518/) defines `pyproject.toml` as a
-configuration file to store build system requirements for Python projects. With the help
-of tools like [Poetry](https://python-poetry.org/) or
-[Flit](https://flit.readthedocs.io/en/latest/) it can fully replace the need for
-`setup.py` and `setup.cfg` files.
-
-## Where _Black_ looks for the file
-
-By default _Black_ looks for `pyproject.toml` starting from the common base directory of
-all files and directories passed on the command line. If it's not there, it looks in
-parent directories. It stops looking when it finds the file, or a `.git` directory, or a
-`.hg` directory, or the root of the file system, whichever comes first.
-
-If you're formatting standard input, _Black_ will look for configuration starting from
-the current working directory.
-
-You can use a "global" configuration, stored in a specific location in your home
-directory. This will be used as a fallback configuration, that is, it will be used if
-and only if _Black_ doesn't find any configuration as mentioned above. Depending on your
-operating system, this configuration file should be stored as:
-
-- Windows: `~\.black`
-- Unix-like (Linux, MacOS, etc.): `$XDG_CONFIG_HOME/black` (`~/.config/black` if the
-  `XDG_CONFIG_HOME` environment variable is not set)
-
-Note that these are paths to the TOML file itself (meaning that they shouldn't be named
-as `pyproject.toml`), not directories where you store the configuration. Here, `~`
-refers to the path to your home directory. On Windows, this will be something like
-`C:\\Users\UserName`.
-
-You can also explicitly specify the path to a particular file that you want with
-`--config`. In this situation _Black_ will not look for any other file.
-
-If you're running with `--verbose`, you will see a blue message if a file was found and
-used.
-
-Files listed within a projects `.gitignore` file will not be formatted by _Black_.
-
-Please note `blackd` will not use `pyproject.toml` configuration.
-
-## Configuration format
-
-As the file extension suggests, `pyproject.toml` is a
-[TOML](https://github.com/toml-lang/toml) file. It contains separate sections for
-different tools. _Black_ is using the `[tool.black]` section. The option keys are the
-same as long names of options on the command line.
-
-Note that you have to use single-quoted strings in TOML for regular expressions. It's
-the equivalent of r-strings in Python. Multiline strings are treated as verbose regular
-expressions by Black. Use `[ ]` to denote a significant space character.
-
-<details>
-<summary>Example <code>pyproject.toml</code></summary>
-
-```toml
-[tool.black]
-line-length = 88
-target-version = ['py37']
-include = '\.pyi?$'
-extend-exclude = '''
-# A regex preceded with ^/ will apply only to files and directories
-# in the root of the project.
-^/foo.py  # exclude a file named foo.py in the root of the project (in addition to the defaults)
-'''
-```
-
-</details>
-
-## Lookup hierarchy
-
-Command-line options have defaults that you can see in `--help`. A `pyproject.toml` can
-override those defaults. Finally, options provided by the user on the command line
-override both.
-
-_Black_ will only ever use one `pyproject.toml` file during an entire run. It doesn't
-look for multiple files, and doesn't compose configuration from different levels of the
-file hierarchy.
diff --git a/docs/requirements.txt b/docs/requirements.txt
index fcb6809cadc..6c34e1fefab 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,3 +1,2 @@
-recommonmark==0.6.0
-Sphinx==3.2.1
-Pygments==2.7.4
\ No newline at end of file
+MyST-Parser==0.13.7
+Sphinx==3.5.4
diff --git a/docs/show_your_style.md b/docs/show_your_style.md
deleted file mode 100644
index 67b213c3965..00000000000
--- a/docs/show_your_style.md
+++ /dev/null
@@ -1,19 +0,0 @@
-[//]: # "NOTE: THIS FILE WAS AUTOGENERATED FROM README.md"
-
-# Show your style
-
-Use the badge in your project's README.md:
-
-```md
-[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
-```
-
-Using the badge in README.rst:
-
-```
-.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
-    :target: https://github.com/psf/black
-```
-
-Looks like this:
-[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
diff --git a/docs/the_black_code_style.md b/docs/the_black_code_style/current_style.md
similarity index 91%
rename from docs/the_black_code_style.md
rename to docs/the_black_code_style/current_style.md
index 39a452ff9a8..7d08bc9cad5 100644
--- a/docs/the_black_code_style.md
+++ b/docs/the_black_code_style/current_style.md
@@ -2,11 +2,13 @@
 
 ## Code style
 
-_Black_ reformats entire files in place. It is not configurable. It doesn't take
-previous formatting into account. It doesn't reformat blocks that start with
-`# fmt: off` and end with `# fmt: on`. `# fmt: on/off` have to be on the same level of
-indentation. It also recognizes [YAPF](https://github.com/google/yapf)'s block comments
-to the same effect, as a courtesy for straddling code.
+_Black_ reformats entire files in place. Style configuration options are deliberately
+limited and rarely added. It doesn't take previous formatting into account, except for
+the magic trailing comma and preserving newlines. It doesn't reformat blocks that start
+with `# fmt: off` and end with `# fmt: on`, or lines that ends with `# fmt: skip`.
+`# fmt: on/off` have to be on the same level of indentation. It also recognizes
+[YAPF](https://github.com/google/yapf)'s block comments to the same effect, as a
+courtesy for straddling code.
 
 ### How _Black_ wraps lines
 
@@ -75,6 +77,8 @@ def very_important_function(
         ...
 ```
 
+(labels/why-no-backslashes)=
+
 _Black_ prefers parentheses over backslashes, and will remove backslashes if found.
 
 ```py3
@@ -115,29 +119,6 @@ If you're reaching for backslashes, that's a clear signal that you can do better
 slightly refactor your code. I hope some of the examples above show you that there are
 many ways in which you can do it.
 
-However there is one exception: `with` statements using multiple context managers.
-Python's grammar does not allow organizing parentheses around the series of context
-managers.
-
-We don't want formatting like:
-
-```py3
-with make_context_manager1() as cm1, make_context_manager2() as cm2, make_context_manager3() as cm3, make_context_manager4() as cm4:
-    ...  # nothing to split on - line too long
-```
-
-So _Black_ will now format it like this:
-
-```py3
-with \
-     make_context_manager(1) as cm1, \
-     make_context_manager(2) as cm2, \
-     make_context_manager(3) as cm3, \
-     make_context_manager(4) as cm4 \
-:
-    ...  # backslashes and an ugly stranded colon
-```
-
 You might have noticed that closing brackets are always dedented and that a trailing
 comma is always added. Such formatting produces smaller diffs; when you add or remove an
 element, it's always just one line. Also, having the closing bracket dedented provides a
@@ -289,13 +270,13 @@ If you are adopting _Black_ in a large project with pre-existing string conventi
 you can pass `--skip-string-normalization` on the command line. This is meant as an
 adoption helper, avoid using this for new projects.
 
-As an experimental option, _Black_ splits long strings (using parentheses where
-appropriate) and merges short ones. When split, parts of f-strings that don't need
-formatting are converted to plain strings. User-made splits are respected when they do
-not exceed the line length limit. Line continuation backslashes are converted into
-parenthesized strings. Unnecessary parentheses are stripped. To enable experimental
-string processing, pass `--experimental-string-processing` on the command line. Because
-the functionality is experimental, feedback and issue reports are highly encouraged!
+As an experimental option (can be enabled by `--experimental-string-processing`),
+_Black_ splits long strings (using parentheses where appropriate) and merges short ones.
+When split, parts of f-strings that don't need formatting are converted to plain
+strings. User-made splits are respected when they do not exceed the line length limit.
+Line continuation backslashes are converted into parenthesized strings. Unnecessary
+parentheses are stripped. Because the functionality is experimental, feedback and issue
+reports are highly encouraged!
 
 _Black_ also processes docstrings. Firstly the indentation of docstrings is corrected
 for both quotations and the text within, although relative indentation in the text is
@@ -354,7 +335,7 @@ pair of parentheses to form an atom. There are a few interesting cases:
 In those cases, parentheses are removed when the entire statement fits in one line, or
 if the inner expression doesn't have any delimiters to further split on. If there is
 only a single delimiter and the expression starts or ends with a bracket, the
-parenthesis can also be successfully omitted since the existing bracket pair will
+parentheses can also be successfully omitted since the existing bracket pair will
 organize the expression neatly anyway. Otherwise, the parentheses are added.
 
 Please note that _Black_ does not add or remove any additional nested parentheses that
@@ -453,7 +434,7 @@ into one item per line.
 How do you make it stop? Just delete that trailing comma and _Black_ will collapse your
 collection into one line if it fits.
 
-If you must, you can recover the behaviour of early versions of Black with the option
+If you must, you can recover the behaviour of early versions of _Black_ with the option
 `--skip-magic-trailing-comma` / `-C`.
 
 ### r"strings" and R"strings"
@@ -478,11 +459,11 @@ target. There are three limited cases in which the AST does differ:
    of docstrings that we're aware of sanitizes indentation and leading/trailing
    whitespace anyway.
 
-2. _Black_ manages optional parentheses for some statements. In the case of the `del`
+1. _Black_ manages optional parentheses for some statements. In the case of the `del`
    statement, presence of wrapping parentheses or lack of thereof changes the resulting
    AST but is semantically equivalent in the interpreter.
 
-3. _Black_ might move comments around, which includes type comments. Those are part of
+1. _Black_ might move comments around, which includes type comments. Those are part of
    the AST as of Python 3.8. While the tool implements a number of special cases for
    those comments, there is no guarantee they will remain where they were in the source.
    Note that this doesn't change runtime behavior of the source code.
diff --git a/docs/the_black_code_style/future_style.md b/docs/the_black_code_style/future_style.md
new file mode 100644
index 00000000000..aca9fe04017
--- /dev/null
+++ b/docs/the_black_code_style/future_style.md
@@ -0,0 +1,35 @@
+# The (future of the) Black code style
+
+```{warning}
+Changes to this document often aren't tied and don't relate to releases of
+_Black_. It's recommended that you read the latest version available.
+```
+
+## Using backslashes for with statements
+
+[Backslashes are bad and should be never be used](labels/why-no-backslashes) however
+there is one exception: `with` statements using multiple context managers. Before Python
+3.9 Python's grammar does not allow organizing parentheses around the series of context
+managers.
+
+We don't want formatting like:
+
+```py3
+with make_context_manager1() as cm1, make_context_manager2() as cm2, make_context_manager3() as cm3, make_context_manager4() as cm4:
+    ...  # nothing to split on - line too long
+```
+
+So _Black_ will eventually format it like this:
+
+```py3
+with \
+     make_context_manager(1) as cm1, \
+     make_context_manager(2) as cm2, \
+     make_context_manager(3) as cm3, \
+     make_context_manager(4) as cm4 \
+:
+    ...  # backslashes and an ugly stranded colon
+```
+
+Although when the target version is Python 3.9 or higher, _Black_ will use parentheses
+instead since they're allowed in Python 3.9 and higher.
diff --git a/docs/the_black_code_style/index.rst b/docs/the_black_code_style/index.rst
new file mode 100644
index 00000000000..4693437be8b
--- /dev/null
+++ b/docs/the_black_code_style/index.rst
@@ -0,0 +1,19 @@
+The Black Code Style
+====================
+
+.. toctree::
+    :hidden:
+
+    Current style <current_style>
+    Future style <future_style>
+
+*Black* is a PEP 8 compliant opinionated formatter with its own style.
+
+It should be noted that while keeping the style unchanged throughout releases is a
+goal, the *Black* code style isn't set in stone. Sometimes it's modified in response to
+user feedback or even changes to the Python language!
+
+Documentation for both the current and future styles can be found:
+
+- :doc:`current_style`
+- :doc:`future_style`
diff --git a/docs/blackd.md b/docs/usage_and_configuration/black_as_a_server.md
similarity index 98%
rename from docs/blackd.md
rename to docs/usage_and_configuration/black_as_a_server.md
index c8058ee7c63..0c0382b3e50 100644
--- a/docs/blackd.md
+++ b/docs/usage_and_configuration/black_as_a_server.md
@@ -1,10 +1,10 @@
-## blackd
+# Black as a server (blackd)
 
 `blackd` is a small HTTP server that exposes _Black_'s functionality over a simple
 protocol. The main benefit of using it is to avoid the cost of starting up a new _Black_
 process every time you want to blacken a file.
 
-### Usage
+## Usage
 
 `blackd` is not packaged alongside _Black_ by default because it has additional
 dependencies. You will need to execute `pip install black[d]` to install it.
@@ -36,7 +36,7 @@ blackd --bind-port 9090 &  # or let blackd choose a port
 curl -s -XPOST "localhost:9090" -d "print('valid')"
 ```
 
-### Protocol
+## Protocol
 
 `blackd` only accepts `POST` requests at the `/` path. The body of the request should
 contain the python source code to be formatted, encoded according to the `charset` field
diff --git a/docs/ignoring_unmodified_files.md b/docs/usage_and_configuration/file_collection_and_discovery.md
similarity index 61%
rename from docs/ignoring_unmodified_files.md
rename to docs/usage_and_configuration/file_collection_and_discovery.md
index a915f4e8678..54c76cd9a0f 100644
--- a/docs/ignoring_unmodified_files.md
+++ b/docs/usage_and_configuration/file_collection_and_discovery.md
@@ -1,6 +1,11 @@
-[//]: # "NOTE: THIS FILE WAS AUTOGENERATED FROM README.md"
+# File collection and discovery
 
-# Ignoring unmodified files
+You can directly pass _Black_ files, but you can also pass directories and _Black_ will
+walk them, collecting files to format. It determines what files to format or skip
+automatically using the inclusion and exclusion regexes and as well their modification
+time.
+
+## Ignoring unmodified files
 
 _Black_ remembers files it has already formatted, unless the `--diff` flag is used or
 code is passed via standard input. This information is stored per-user. The exact
@@ -21,3 +26,12 @@ To override the location of these files on macOS or Linux, set the environment v
 `XDG_CACHE_HOME` to your preferred location. For example, if you want to put the cache
 in the directory you're running _Black_ from, set `XDG_CACHE_HOME=.cache`. _Black_ will
 then write the above files to `.cache/black/<version>/`.
+
+## .gitignore
+
+If `--exclude` is not set, _Black_ will automatically ignore files and directories in
+`.gitignore` file, if present. The `.gitignore` file must be in the project root to be
+used and nested `.gitignore` aren't supported.
+
+If you want _Black_ to continue using `.gitignore` while also configuring the exclusion
+rules, please use `--extend-exclude`.
diff --git a/docs/usage_and_configuration/index.rst b/docs/usage_and_configuration/index.rst
new file mode 100644
index 00000000000..84a9c0cb99b
--- /dev/null
+++ b/docs/usage_and_configuration/index.rst
@@ -0,0 +1,24 @@
+Usage and Configuration
+=======================
+
+.. toctree::
+  :hidden:
+
+  the_basics
+  file_collection_and_discovery
+  black_as_a_server
+
+Sometimes, running *Black* with its defaults and passing filepaths to it just won't cut
+it. Passing each file using paths will become burdensome, and maybe you would like
+*Black* to not touch your files and just output diffs. And yes, you *can* tweak certain
+parts of *Black*'s style, but please know that configurability in this area is
+purposefully limited.
+
+Using many of these more advanced features of *Black* will require some configuration.
+Configuration that will either live on the command line or in a TOML configuration file.
+
+This section covers features of *Black* and configuring *Black* in detail:
+
+- :doc:`The basics <./the_basics>`
+- :doc:`File collection and discovery <file_collection_and_discovery>`
+- :doc:`Black as a server (blackd) <./black_as_a_server>`
diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
new file mode 100644
index 00000000000..6fd8769b591
--- /dev/null
+++ b/docs/usage_and_configuration/the_basics.md
@@ -0,0 +1,227 @@
+# The basics
+
+Foundational knowledge on using and configuring Black.
+
+_Black_ is a well-behaved Unix-style command-line tool:
+
+- it does nothing if no sources are passed to it;
+- it will read from standard input and write to standard output if `-` is used as the
+  filename;
+- it only outputs messages to users on standard error;
+- exits with code 0 unless an internal error occurred (or `--check` was used).
+
+## Usage
+
+To get started right away with sensible defaults:
+
+```sh
+black {source_file_or_directory}
+```
+
+You can run _Black_ as a package if running it as a script doesn't work:
+
+```sh
+python -m black {source_file_or_directory}
+```
+
+### Command line options
+
+_Black_ has quite a few knobs these days, although _Black_ is opinionated so style
+configuration options are deliberately limited and rarely added. You can list them by
+running `black --help`.
+
+<details>
+
+<summary>Help output</summary>
+
+```
+  Usage: black [OPTIONS] [SRC]...
+
+    The uncompromising code formatter.
+
+  Options:
+    -c, --code TEXT                 Format the code passed in as a string.
+    -l, --line-length INTEGER       How many characters per line to allow.
+                                    [default: 88]
+
+    -t, --target-version [py27|py33|py34|py35|py36|py37|py38|py39]
+                                    Python versions that should be supported by
+                                    Black's output. [default: per-file auto-
+                                    detection]
+
+    --pyi                           Format all input files like typing stubs
+                                    regardless of file extension (useful when
+                                    piping source on standard input).
+
+    -S, --skip-string-normalization
+                                    Don't normalize string quotes or prefixes.
+    -C, --skip-magic-trailing-comma
+                                    Don't use trailing commas as a reason to
+                                    split lines.
+
+    --check                         Don't write the files back, just return the
+                                    status. Return code 0 means nothing would
+                                    change. Return code 1 means some files
+                                    would be reformatted. Return code 123 means
+                                    there was an internal error.
+
+    --diff                          Don't write the files back, just output a
+                                    diff for each file on stdout.
+
+    --color / --no-color            Show colored diff. Only applies when
+                                    `--diff` is given.
+
+    --fast / --safe                 If --fast given, skip temporary sanity
+                                    checks. [default: --safe]
+
+    --include TEXT                  A regular expression that matches files and
+                                    directories that should be included on
+                                    recursive searches. An empty value means
+                                    all files are included regardless of the
+                                    name. Use forward slashes for directories
+                                    on all platforms (Windows, too). Exclusions
+                                    are calculated first, inclusions later.
+                                    [default: \.pyi?$]
+
+    --exclude TEXT                  A regular expression that matches files and
+                                    directories that should be excluded on
+                                    recursive searches. An empty value means no
+                                    paths are excluded. Use forward slashes for
+                                    directories on all platforms (Windows, too).
+                                    Exclusions are calculated first, inclusions
+                                    later.  [default: /(\.direnv|\.eggs|\.git|\.
+                                    hg|\.mypy_cache|\.nox|\.tox|\.venv|venv|\.svn|_bu
+                                    ild|buck-out|build|dist)/]
+
+    --extend-exclude TEXT           Like --exclude, but adds additional files
+                                    and directories on top of the excluded
+                                    ones (useful if you simply want to add to
+                                    the default).
+
+    --force-exclude TEXT            Like --exclude, but files and directories
+                                    matching this regex will be excluded even
+                                    when they are passed explicitly as
+                                    arguments.
+
+
+    --stdin-filename TEXT           The name of the file when passing it through
+                                    stdin. Useful to make sure Black will
+                                    respect --force-exclude option on some
+                                    editors that rely on using stdin.
+
+    -q, --quiet                     Don't emit non-error messages to stderr.
+                                    Errors are still emitted; silence those with
+                                    2>/dev/null.
+
+    -v, --verbose                   Also emit messages to stderr about files
+                                    that were not changed or were ignored due to
+                                    exclusion patterns.
+
+    --version                       Show the version and exit.
+    --config FILE                   Read configuration from FILE path.
+    -h, --help                      Show this message and exit.
+```
+
+</details>
+
+## Configuration via a file
+
+_Black_ is able to read project-specific default values for its command line options
+from a `pyproject.toml` file. This is especially useful for specifying custom
+`--include` and `--exclude`/`--force-exclude`/`--extend-exclude` patterns for your
+project.
+
+**Pro-tip**: If you're asking yourself "Do I need to configure anything?" the answer is
+"No". _Black_ is all about sensible defaults. Applying those defaults will have your
+code in compliance with many other _Black_ formatted projects.
+
+### What on Earth is a `pyproject.toml` file?
+
+[PEP 518](https://www.python.org/dev/peps/pep-0518/) defines `pyproject.toml` as a
+configuration file to store build system requirements for Python projects. With the help
+of tools like [Poetry](https://python-poetry.org/) or
+[Flit](https://flit.readthedocs.io/en/latest/) it can fully replace the need for
+`setup.py` and `setup.cfg` files.
+
+### Where _Black_ looks for the file
+
+By default _Black_ looks for `pyproject.toml` starting from the common base directory of
+all files and directories passed on the command line. If it's not there, it looks in
+parent directories. It stops looking when it finds the file, or a `.git` directory, or a
+`.hg` directory, or the root of the file system, whichever comes first.
+
+If you're formatting standard input, _Black_ will look for configuration starting from
+the current working directory.
+
+You can use a "global" configuration, stored in a specific location in your home
+directory. This will be used as a fallback configuration, that is, it will be used if
+and only if _Black_ doesn't find any configuration as mentioned above. Depending on your
+operating system, this configuration file should be stored as:
+
+- Windows: `~\.black`
+- Unix-like (Linux, MacOS, etc.): `$XDG_CONFIG_HOME/black` (`~/.config/black` if the
+  `XDG_CONFIG_HOME` environment variable is not set)
+
+Note that these are paths to the TOML file itself (meaning that they shouldn't be named
+as `pyproject.toml`), not directories where you store the configuration. Here, `~`
+refers to the path to your home directory. On Windows, this will be something like
+`C:\\Users\UserName`.
+
+You can also explicitly specify the path to a particular file that you want with
+`--config`. In this situation _Black_ will not look for any other file.
+
+If you're running with `--verbose`, you will see a blue message if a file was found and
+used.
+
+Please note `blackd` will not use `pyproject.toml` configuration.
+
+### Configuration format
+
+As the file extension suggests, `pyproject.toml` is a
+[TOML](https://github.com/toml-lang/toml) file. It contains separate sections for
+different tools. _Black_ is using the `[tool.black]` section. The option keys are the
+same as long names of options on the command line.
+
+Note that you have to use single-quoted strings in TOML for regular expressions. It's
+the equivalent of r-strings in Python. Multiline strings are treated as verbose regular
+expressions by Black. Use `[ ]` to denote a significant space character.
+
+<details>
+<summary>Example <code>pyproject.toml</code></summary>
+
+```toml
+[tool.black]
+line-length = 88
+target-version = ['py37']
+include = '\.pyi?$'
+extend-exclude = '''
+# A regex preceded with ^/ will apply only to files and directories
+# in the root of the project.
+^/foo.py  # exclude a file named foo.py in the root of the project (in addition to the defaults)
+'''
+```
+
+</details>
+
+### Lookup hierarchy
+
+Command-line options have defaults that you can see in `--help`. A `pyproject.toml` can
+override those defaults. Finally, options provided by the user on the command line
+override both.
+
+_Black_ will only ever use one `pyproject.toml` file during an entire run. It doesn't
+look for multiple files, and doesn't compose configuration from different levels of the
+file hierarchy.
+
+## Next steps
+
+You've probably noted that not all of the options you can pass to _Black_ have been
+covered. Don't worry, the rest will be covered in a later section.
+
+A good next step would be configuring auto-discovery so `black .` is all you need
+instead of laborously listing every file or directory. You can get started by heading
+over to [File collection and discovery](./file_collection_and_discovery.md).
+
+Another good choice would be setting up an
+[integration with your editor](../integrations/editors.md) of choice or with
+[pre-commit for source version control](../integrations/source_version_control.md).
diff --git a/docs/version_control_integration.md b/docs/version_control_integration.md
deleted file mode 100644
index 2d8bc172eba..00000000000
--- a/docs/version_control_integration.md
+++ /dev/null
@@ -1,28 +0,0 @@
-[//]: # "NOTE: THIS FILE WAS AUTOGENERATED FROM README.md"
-
-# Version control integration
-
-Use [pre-commit](https://pre-commit.com/). Once you
-[have it installed](https://pre-commit.com/#install), add this to the
-`.pre-commit-config.yaml` in your repository:
-
-```yaml
-repos:
-  - repo: https://github.com/psf/black
-    rev: 20.8b1 # Replace by any tag/version: https://github.com/psf/black/tags
-    hooks:
-      - id: black
-        language_version: python3 # Should be a command that runs python3.6+
-```
-
-Then run `pre-commit install` and you're ready to go.
-
-Avoid using `args` in the hook. Instead, store necessary configuration in
-`pyproject.toml` so that editors and command-line usage of Black all behave consistently
-for your project. See _Black_'s own
-[pyproject.toml](https://github.com/psf/black/blob/master/pyproject.toml) for an
-example.
-
-If you're already using Python 3.7, switch the `language_version` accordingly. Finally,
-`stable` is a branch that tracks the latest release on PyPI. If you'd rather run on
-master, this is also an option.

From 1bedc176d19f0e71c24149c696c5a2a71f21e941 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Sat, 8 May 2021 15:53:01 -0400
Subject: [PATCH 0187/1034] Fix autodoc refs broken by refactor (#2207)

---
 .../reference/reference_classes.rst           |   6 +-
 .../reference/reference_exceptions.rst        |   2 +-
 .../reference/reference_functions.rst         | 112 +++++++++---------
 3 files changed, 59 insertions(+), 61 deletions(-)

diff --git a/docs/contributing/reference/reference_classes.rst b/docs/contributing/reference/reference_classes.rst
index 8a2ded9dfec..fa765961e69 100644
--- a/docs/contributing/reference/reference_classes.rst
+++ b/docs/contributing/reference/reference_classes.rst
@@ -8,7 +8,7 @@
 :class:`BracketTracker`
 -----------------------
 
-.. autoclass:: black.BracketTracker
+.. autoclass:: black.brackets.BracketTracker
     :members:
 
 :class:`EmptyLineTracker`
@@ -34,7 +34,7 @@
 :class:`ProtoComment`
 ---------------------
 
-.. autoclass:: black.ProtoComment
+.. autoclass:: black.comments.ProtoComment
     :members:
 
 :class:`Report`
@@ -47,7 +47,7 @@
 :class:`Visitor`
 ----------------
 
-.. autoclass:: black.Visitor
+.. autoclass:: black.nodes.Visitor
     :show-inheritance:
     :members:
 
diff --git a/docs/contributing/reference/reference_exceptions.rst b/docs/contributing/reference/reference_exceptions.rst
index 517249fa4ce..aafe61e5017 100644
--- a/docs/contributing/reference/reference_exceptions.rst
+++ b/docs/contributing/reference/reference_exceptions.rst
@@ -5,7 +5,7 @@
 
 .. currentmodule:: black
 
-.. autoexception:: black.CannotSplit
+.. autoexception:: black.linegen.CannotSplit
 
 .. autoexception:: black.NothingChanged
 
diff --git a/docs/contributing/reference/reference_functions.rst b/docs/contributing/reference/reference_functions.rst
index bffce7e9e32..4353d1bf9a9 100644
--- a/docs/contributing/reference/reference_functions.rst
+++ b/docs/contributing/reference/reference_functions.rst
@@ -12,31 +12,31 @@ Assertions and checks
 
 .. autofunction:: black.assert_stable
 
-.. autofunction:: black.can_be_split
+.. autofunction:: black.lines.can_be_split
 
-.. autofunction:: black.can_omit_invisible_parens
+.. autofunction:: black.lines.can_omit_invisible_parens
 
-.. autofunction:: black.is_empty_tuple
+.. autofunction:: black.nodes.is_empty_tuple
 
-.. autofunction:: black.is_import
+.. autofunction:: black.nodes.is_import
 
-.. autofunction:: black.is_line_short_enough
+.. autofunction:: black.lines.is_line_short_enough
 
-.. autofunction:: black.is_multiline_string
+.. autofunction:: black.nodes.is_multiline_string
 
-.. autofunction:: black.is_one_tuple
+.. autofunction:: black.nodes.is_one_tuple
 
-.. autofunction:: black.is_split_after_delimiter
+.. autofunction:: black.brackets.is_split_after_delimiter
 
-.. autofunction:: black.is_split_before_delimiter
+.. autofunction:: black.brackets.is_split_before_delimiter
 
-.. autofunction:: black.is_stub_body
+.. autofunction:: black.nodes.is_stub_body
 
-.. autofunction:: black.is_stub_suite
+.. autofunction:: black.nodes.is_stub_suite
 
-.. autofunction:: black.is_vararg
+.. autofunction:: black.nodes.is_vararg
 
-.. autofunction:: black.is_yield
+.. autofunction:: black.nodes.is_yield
 
 
 Formatting
@@ -70,111 +70,109 @@ Parsing
 
 .. autofunction:: black.decode_bytes
 
-.. autofunction:: black.lib2to3_parse
+.. autofunction:: black.parsing.lib2to3_parse
 
-.. autofunction:: black.lib2to3_unparse
+.. autofunction:: black.parsing.lib2to3_unparse
 
 Split functions
 ---------------
 
-.. autofunction:: black.bracket_split_build_line
+.. autofunction:: black.linegen.bracket_split_build_line
 
-.. autofunction:: black.bracket_split_succeeded_or_raise
+.. autofunction:: black.linegen.bracket_split_succeeded_or_raise
 
-.. autofunction:: black.delimiter_split
+.. autofunction:: black.linegen.delimiter_split
 
-.. autofunction:: black.left_hand_split
+.. autofunction:: black.linegen.left_hand_split
 
-.. autofunction:: black.right_hand_split
+.. autofunction:: black.linegen.right_hand_split
 
-.. autofunction:: black.standalone_comment_split
+.. autofunction:: black.linegen.standalone_comment_split
 
-.. autofunction:: black.transform_line
+.. autofunction:: black.linegen.transform_line
 
 Caching
 -------
 
-.. autofunction:: black.filter_cached
+.. autofunction:: black.cache.filter_cached
 
-.. autofunction:: black.get_cache_file
+.. autofunction:: black.cache.get_cache_file
 
-.. autofunction:: black.get_cache_info
+.. autofunction:: black.cache.get_cache_info
 
-.. autofunction:: black.read_cache
+.. autofunction:: black.cache.read_cache
 
-.. autofunction:: black.write_cache
+.. autofunction:: black.cache.write_cache
 
 Utilities
 ---------
 
-.. py:function:: black.DebugVisitor.show(code: str) -> None
+.. py:function:: black.debug.DebugVisitor.show(code: str) -> None
 
     Pretty-print the lib2to3 AST of a given string of `code`.
 
-.. autofunction:: black.cancel
+.. autofunction:: black.concurrency.cancel
 
-.. autofunction:: black.child_towards
+.. autofunction:: black.nodes.child_towards
 
-.. autofunction:: black.container_of
+.. autofunction:: black.nodes.container_of
 
-.. autofunction:: black.convert_one_fmt_off_pair
+.. autofunction:: black.comments.convert_one_fmt_off_pair
 
 .. autofunction:: black.diff
 
-.. autofunction:: black.dont_increase_indentation
+.. autofunction:: black.linegen.dont_increase_indentation
 
-.. autofunction:: black.format_float_or_int_string
+.. autofunction:: black.numerics.format_float_or_int_string
 
-.. autofunction:: black.ensure_visible
+.. autofunction:: black.nodes.ensure_visible
 
-.. autofunction:: black.enumerate_reversed
+.. autofunction:: black.lines.enumerate_reversed
 
-.. autofunction:: black.enumerate_with_length
+.. autofunction:: black.comments.generate_comments
 
-.. autofunction:: black.generate_comments
+.. autofunction:: black.comments.generate_ignored_nodes
 
-.. autofunction:: black.generate_ignored_nodes
+.. autofunction:: black.comments.is_fmt_on
 
-.. autofunction:: black.is_fmt_on
+.. autofunction:: black.comments.contains_fmt_on_at_column
 
-.. autofunction:: black.contains_fmt_on_at_column
+.. autofunction:: black.nodes.first_leaf_column
 
-.. autofunction:: black.first_leaf_column
-
-.. autofunction:: black.generate_trailers_to_omit
+.. autofunction:: black.linegen.generate_trailers_to_omit
 
 .. autofunction:: black.get_future_imports
 
-.. autofunction:: black.list_comments
+.. autofunction:: black.comments.list_comments
 
-.. autofunction:: black.make_comment
+.. autofunction:: black.comments.make_comment
 
-.. autofunction:: black.maybe_make_parens_invisible_in_atom
+.. autofunction:: black.linegen.maybe_make_parens_invisible_in_atom
 
-.. autofunction:: black.max_delimiter_priority_in_atom
+.. autofunction:: black.brackets.max_delimiter_priority_in_atom
 
 .. autofunction:: black.normalize_fmt_off
 
-.. autofunction:: black.normalize_numeric_literal
+.. autofunction:: black.numerics.normalize_numeric_literal
 
-.. autofunction:: black.normalize_prefix
+.. autofunction:: black.linegen.normalize_prefix
 
-.. autofunction:: black.normalize_string_prefix
+.. autofunction:: black.strings.normalize_string_prefix
 
-.. autofunction:: black.normalize_string_quotes
+.. autofunction:: black.strings.normalize_string_quotes
 
-.. autofunction:: black.normalize_invisible_parens
+.. autofunction:: black.linegen.normalize_invisible_parens
 
 .. autofunction:: black.patch_click
 
-.. autofunction:: black.preceding_leaf
+.. autofunction:: black.nodes.preceding_leaf
 
 .. autofunction:: black.re_compile_maybe_verbose
 
-.. autofunction:: black.should_split_line
+.. autofunction:: black.linegen.should_split_line
 
 .. autofunction:: black.shutdown
 
-.. autofunction:: black.sub_twice
+.. autofunction:: black.strings.sub_twice
 
-.. autofunction:: black.whitespace
+.. autofunction:: black.nodes.whitespace

From 5020577788eeab758a2c33d1d563e4ea82617ed4 Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Sun, 9 May 2021 00:08:03 -0700
Subject: [PATCH 0188/1034] Remove docker CI from look at 'master' branch
 (#2209)

---
 .github/workflows/docker.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
index 7eaf233ab9c..788c505ee4a 100644
--- a/.github/workflows/docker.yml
+++ b/.github/workflows/docker.yml
@@ -3,7 +3,7 @@ name: docker
 on:
   push:
     branches:
-      - "master"
+      - "main"
   release:
     types: created
 

From 06ccb88bf2bd35a4dc5d591bb296b5b299d07323 Mon Sep 17 00:00:00 2001
From: Panagiotis Vasilopoulos <hello@alwayslivid.com>
Date: Sun, 9 May 2021 21:50:17 +0000
Subject: [PATCH 0189/1034] Replace references to master branch (#2210)

Commit history before merge:

* Replace references to master branch
* Update .flake8 to reference docs on RTD

  We're moving away from GitHub as a documentation host to only RTD because
  it's makes our lives easier creating good docs. I know this link is dead right now,
  but it won't be once we release a new version with the documentation reorganization
  changes (which should be soon!).

  Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 .flake8                                     | 2 +-
 .github/ISSUE_TEMPLATE/bug_report.md        | 8 ++++----
 CHANGES.md                                  | 4 ++++
 README.md                                   | 6 +++---
 docs/contributing/the_basics.md             | 2 +-
 docs/guides/using_black_with_other_tools.md | 2 +-
 docs/integrations/editors.md                | 2 +-
 gallery/gallery.py                          | 8 ++++----
 setup.py                                    | 2 +-
 9 files changed, 20 insertions(+), 16 deletions(-)

diff --git a/.flake8 b/.flake8
index 656c0df24ee..68d15015a37 100644
--- a/.flake8
+++ b/.flake8
@@ -1,7 +1,7 @@
 [flake8]
 extend-ignore = E203, E266, E501
 # line length is intentionally set to 80 here because black uses Bugbear
-# See https://github.com/psf/black/blob/master/docs/the_black_code_style.md#line-length for more details
+# See https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#line-length for more details
 max-line-length = 80
 max-complexity = 18
 select = B,C,E,F,W,T4,B9
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
index 3b59906594a..c6c80be5345 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -18,13 +18,13 @@ assignees: ""
 
 **Environment (please complete the following information):**
 
-- Version: \[e.g. master\]
+- Version: \[e.g. main\]
 - OS and Python version: \[e.g. Linux/Python 3.7.4rc1\]
 
-**Does this bug also happen on master?** To answer this, you have two options:
+**Does this bug also happen on main?** To answer this, you have two options:
 
-1. Use the online formatter at <https://black.vercel.app/?version=master>, which will
-   use the latest master branch.
+1. Use the online formatter at <https://black.vercel.app/?version=main>, which will use
+   the latest main branch.
 1. Or run _Black_ on your machine:
    - create a new virtualenv (make sure it's the same Python version);
    - clone this repository;
diff --git a/CHANGES.md b/CHANGES.md
index 9b155924b7d..32c2d8d7237 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -8,6 +8,10 @@
 
 ### Documentation
 
+- Replaced all remaining references to the
+  [`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
   heading over to [the stable docs on RTD](https://black.readthedocs.io/en/stable/).
   (#2174)
diff --git a/README.md b/README.md
index ceccbb79962..beb8069c32b 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-![Black Logo](https://raw.githubusercontent.com/psf/black/master/docs/_static/logo2-readme.png)
+![Black Logo](https://raw.githubusercontent.com/psf/black/main/docs/_static/logo2-readme.png)
 
 <h2 align="center">The Uncompromising Code Formatter</h2>
 
@@ -6,8 +6,8 @@
 <a href="/psf/black/actions"><img alt="Actions Status" src="https://github.com/psf/black/workflows/Test/badge.svg"></a>
 <a href="/psf/black/actions"><img alt="Actions Status" src="https://github.com/psf/black/workflows/Primer/badge.svg"></a>
 <a href="https://black.readthedocs.io/en/stable/?badge=stable"><img alt="Documentation Status" src="https://readthedocs.org/projects/black/badge/?version=stable"></a>
-<a href="https://coveralls.io/github/psf/black?branch=master"><img alt="Coverage Status" src="https://coveralls.io/repos/github/psf/black/badge.svg?branch=master"></a>
-<a href="/psf/black/blob/master/LICENSE"><img alt="License: MIT" src="https://black.readthedocs.io/en/stable/_static/license.svg"></a>
+<a href="https://coveralls.io/github/psf/black?branch=main"><img alt="Coverage Status" src="https://coveralls.io/repos/github/psf/black/badge.svg?branch=main"></a>
+<a href="/psf/black/blob/main/LICENSE"><img alt="License: MIT" src="https://black.readthedocs.io/en/stable/_static/license.svg"></a>
 <a href="https://pypi.org/project/black/"><img alt="PyPI" src="https://img.shields.io/pypi/v/black"></a>
 <a href="https://pepy.tech/project/black"><img alt="Downloads" src="https://pepy.tech/badge/black"></a>
 <a href="https://anaconda.org/conda-forge/black/"><img alt="conda-forge" src="https://img.shields.io/conda/dn/conda-forge/black.svg?label=conda-forge"></a>
diff --git a/docs/contributing/the_basics.md b/docs/contributing/the_basics.md
index 461bff96505..d36b17eff31 100644
--- a/docs/contributing/the_basics.md
+++ b/docs/contributing/the_basics.md
@@ -81,7 +81,7 @@ $ sphinx-build -a -b html -W docs/ docs/_build/
 if we get source code changes. It will error on formatting changes or errors. Please run
 before pushing your PR to see if you get the actions you would expect from _Black_ with
 your PR. You may need to change
-[primer.json](https://github.com/psf/black/blob/master/src/black_primer/primer.json)
+[primer.json](https://github.com/psf/black/blob/main/src/black_primer/primer.json)
 configuration for it to pass.
 
 For more `black-primer` information visit the
diff --git a/docs/guides/using_black_with_other_tools.md b/docs/guides/using_black_with_other_tools.md
index 4b22f670fe1..2b3855f7ef0 100644
--- a/docs/guides/using_black_with_other_tools.md
+++ b/docs/guides/using_black_with_other_tools.md
@@ -13,7 +13,7 @@ tools out there.
 tools, using **their** supported file formats.
 
 Compatible configuration files can be
-[found here](https://github.com/psf/black/blob/master/docs/compatible_configs/).
+[found here](https://github.com/psf/black/blob/main/docs/compatible_configs/).
 
 ### isort
 
diff --git a/docs/integrations/editors.md b/docs/integrations/editors.md
index 6a69e9e33fd..88176e1aecb 100644
--- a/docs/integrations/editors.md
+++ b/docs/integrations/editors.md
@@ -166,7 +166,7 @@ automatically installs _Black_. You can upgrade it later by calling `:BlackUpgra
 restarting Vim.
 
 If you need to do anything special to make your virtualenv work and install _Black_ (for
-example you want to run a version from master), create a virtualenv manually and point
+example you want to run a version from main), create a virtualenv manually and point
 `g:black_virtualenv` to it. The plugin will use it.
 
 To run _Black_ on save, add the following line to `.vimrc` or `init.vim`:
diff --git a/gallery/gallery.py b/gallery/gallery.py
index 6b42ec3a6d4..3df05c1a722 100755
--- a/gallery/gallery.py
+++ b/gallery/gallery.py
@@ -74,7 +74,7 @@ def get_top_packages(days: Days) -> List[str]:
 def get_package_source(package: str, version: Optional[str]) -> str:
     if package == "cpython":
         if version is None:
-            version = "master"
+            version = "main"
         return f"https://github.com/python/cpython/archive/{version}.zip"
     elif package == "pypy":
         if version is None:
@@ -248,9 +248,9 @@ def format_repos(repos: Tuple[Path, ...], options: Namespace) -> None:
                 black_version=black_version,
                 input_directory=options.input,
             )
-        git_switch_branch("master", repo=repo)
+        git_switch_branch("main", repo=repo)
 
-    git_switch_branch("master", repo=options.black_repo)
+    git_switch_branch("main", repo=options.black_repo)
 
 
 def main() -> None:
@@ -296,7 +296,7 @@ def main() -> None:
         type=Path,
         help="Output directory to download and put result artifacts.",
     )
-    parser.add_argument("versions", nargs="*", default=("master",), help="")
+    parser.add_argument("versions", nargs="*", default=("main",), help="")
 
     options = parser.parse_args()
     repos = init_repos(options)
diff --git a/setup.py b/setup.py
index af93d0f453a..3dc52b26e81 100644
--- a/setup.py
+++ b/setup.py
@@ -58,7 +58,7 @@ def get_long_description() -> str:
     author="Łukasz Langa",
     author_email="lukasz@langa.pl",
     url="https://github.com/psf/black",
-    project_urls={"Changelog": "https://github.com/psf/black/blob/master/CHANGES.md"},
+    project_urls={"Changelog": "https://github.com/psf/black/blob/main/CHANGES.md"},
     license="MIT",
     py_modules=["_black_version"],
     ext_modules=ext_modules,

From 3d96b7f10a56fcf826693e98f08b673dad8ac256 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Sun, 9 May 2021 22:35:56 -0400
Subject: [PATCH 0190/1034] Autogenerate black(d|-primer)? help in usage docs
 (#2212)

So these won't go out of date. This does mean the environment has be
setup a bit more carefully so the right version of the tool is used,
but thankfully the build environment is rebuilt on change on RTD anyway.

Also since the HTML docs are known to build fine, let's provide
downloadable HTMLzips of our docs.

This change needs RTD and GH to install Black with the [d] extra so
blackd's help can generated. While editing RTD's config file, let's
migrate the file to a non-deprecated filename.

Also I missed adding AUTHORS.md to the files key in the doc GHA config.
---
 .github/workflows/doc.yml                     |  6 +-
 readthedocs.yml => .readthedocs.yaml          |  9 +-
 Pipfile                                       |  1 +
 Pipfile.lock                                  | 90 ++++++++++---------
 docs/conf.py                                  |  1 +
 docs/contributing/gauging_changes.md          | 21 +----
 docs/requirements.txt                         |  3 +-
 .../black_as_a_server.md                      | 10 +--
 docs/usage_and_configuration/the_basics.md    | 88 +-----------------
 9 files changed, 70 insertions(+), 159 deletions(-)
 rename readthedocs.yml => .readthedocs.yaml (55%)

diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml
index 930b6d440ff..74ec316a7cf 100644
--- a/.github/workflows/doc.yml
+++ b/.github/workflows/doc.yml
@@ -7,12 +7,14 @@ on:
       - "README.md"
       - "CHANGES.md"
       - "CONTRIBUTING.md"
+      - "AUTHORS.md"
   pull_request:
     paths:
       - "docs/**"
       - "README.md"
       - "CHANGES.md"
       - "CONTRIBUTING.md"
+      - "AUTHORS.md"
 
 jobs:
   build:
@@ -35,8 +37,8 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip setuptools wheel
-          python -m pip install -e "."
+          python -m pip install -e ".[d]"
           python -m pip install -r "docs/requirements.txt"
 
       - name: Build documentation
-        run: sphinx-build -a -b html -W docs/ docs/_build/
+        run: sphinx-build -a -b html -W --keep-going docs/ docs/_build
diff --git a/readthedocs.yml b/.readthedocs.yaml
similarity index 55%
rename from readthedocs.yml
rename to .readthedocs.yaml
index 15065033d0f..24eb3eaf6d9 100644
--- a/readthedocs.yml
+++ b/.readthedocs.yaml
@@ -1,7 +1,14 @@
 version: 2
+
+formats:
+  - htmlzip
+
 python:
   version: 3.8
   install:
     - requirements: docs/requirements.txt
-    - method: setuptools
+
+    - method: pip
       path: .
+      extra_requirements:
+        - d
diff --git a/Pipfile b/Pipfile
index d1842ff749b..b3859571137 100644
--- a/Pipfile
+++ b/Pipfile
@@ -13,6 +13,7 @@ mypy = ">=0.812"
 pre-commit = "*"
 readme_renderer = "*"
 MyST-Parser = ">=0.13.7"
+sphinxcontrib-programoutput = ">=0.17"
 setuptools = ">=39.2.0"
 setuptools-scm = "*"
 twine = ">=1.11.0"
diff --git a/Pipfile.lock b/Pipfile.lock
index f973c8423e8..0b9e529e73b 100644
--- a/Pipfile.lock
+++ b/Pipfile.lock
@@ -1,7 +1,7 @@
 {
     "_meta": {
         "hash": {
-            "sha256": "62bc4bdb0117234d1f374b2dc0685369f6df7c7192d16409cc9c42a429770166"
+            "sha256": "fdfbacb362e4514e588736a7e8783837cb5e3aa2fbab98ea17894fdb50d51a8e"
         },
         "pipfile-spec": 6,
         "requires": {},
@@ -83,11 +83,11 @@
         },
         "attrs": {
             "hashes": [
-                "sha256:31b2eced602aa8423c2aea9c76a724617ed67cf9513173fd3a4f03e3a929c7e6",
-                "sha256:832aa3cde19744e49938b91fea06d69ecb9e649c93ba974535d08ad92164f700"
+                "sha256:149e90d6d8ac20db7a955ad60cf0e6881a3f20d37096140088356da6c716b0b1",
+                "sha256:ef6aaac3ca6cd92904cdd0d83f629a15f18053ec84e6432106f7a4d04ae4f5fb"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==20.3.0"
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
+            "version": "==21.2.0"
         },
         "black": {
             "editable": true,
@@ -290,13 +290,13 @@
         },
         "typing-extensions": {
             "hashes": [
-                "sha256:7cb407020f00f7bfc3cb3e7881628838e69d8f3fcab2f64742a5e76b2f841918",
-                "sha256:99d4073b617d30288f569d3f13d2bd7548c3a7e4c8de87db09a9d29bb3a4a60c",
-                "sha256:dafc7639cde7f1b6e1acc0f457842a83e722ccca8eef5270af2d74792619a89f"
+                "sha256:0ac0f89795dd19de6b97debb0c6af1c70987fd80a2d62d1958f7e56fcc31b497",
+                "sha256:50b6f157849174217d0656f99dc82fe932884fb250826c18350e159ec6cdf342",
+                "sha256:779383f6086d90c99ae41cf0ff39aac8a7937a9283ce0a414e5dd782f4c94a84"
             ],
             "index": "pypi",
             "python_version <": "3.8",
-            "version": "==3.7.4.3",
+            "version": "==3.10.0.0",
             "version >=": "3.7.4"
         },
         "yarl": {
@@ -420,11 +420,11 @@
         },
         "attrs": {
             "hashes": [
-                "sha256:31b2eced602aa8423c2aea9c76a724617ed67cf9513173fd3a4f03e3a929c7e6",
-                "sha256:832aa3cde19744e49938b91fea06d69ecb9e649c93ba974535d08ad92164f700"
+                "sha256:149e90d6d8ac20db7a955ad60cf0e6881a3f20d37096140088356da6c716b0b1",
+                "sha256:ef6aaac3ca6cd92904cdd0d83f629a15f18053ec84e6432106f7a4d04ae4f5fb"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==20.3.0"
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
+            "version": "==21.2.0"
         },
         "babel": {
             "hashes": [
@@ -631,11 +631,11 @@
         },
         "flake8": {
             "hashes": [
-                "sha256:1aa8990be1e689d96c745c5682b687ea49f2e05a443aff1f8251092b0014e378",
-                "sha256:3b9f848952dddccf635be78098ca75010f073bfe14d2c6bda867154bea728d2a"
+                "sha256:07528381786f2a6237b061f6e96610a4167b226cb926e2aa2b6b1d78057c576b",
+                "sha256:bf8fd333346d844f616e8d47905ef3a3384edae6b4e9beb0c5101e25e3110907"
             ],
             "index": "pypi",
-            "version": "==3.9.1"
+            "version": "==3.9.2"
         },
         "flake8-bugbear": {
             "hashes": [
@@ -703,11 +703,11 @@
         },
         "markdown-it-py": {
             "hashes": [
-                "sha256:30b3e9f8198dc82a5df0dcb73fd31d56cd9a43bf8a747feb10b2ba74f962bcb1",
-                "sha256:c3b9f995be0792cbbc8ab2f53d74072eb7ff8a8b622be8d61d38ab879709eca3"
+                "sha256:36be6bb3ad987bfdb839f5ba78ddf094552ca38ccbd784ae4f74a4e1419fc6e3",
+                "sha256:98080fc0bc34c4f2bcf0846a096a9429acbd9d5d8e67ed34026c03c61c464389"
             ],
             "markers": "python_version ~= '3.6'",
-            "version": "==0.6.2"
+            "version": "==1.1.0"
         },
         "markupsafe": {
             "hashes": [
@@ -776,11 +776,11 @@
         },
         "mdit-py-plugins": {
             "hashes": [
-                "sha256:1e467ca2ea056e8065cbd5d6c61e5052bb50826bde84c40f6a5ed77e82125710",
-                "sha256:77fd75dad81109ee91f30eb49146196f79afbbae041f298ae4886c8c2b5e23d7"
+                "sha256:1833bf738e038e35d89cb3a07eb0d227ed647ce7dd357579b65343740c6d249c",
+                "sha256:5991cef645502e80a5388ec4fc20885d2313d4871e8b8e320ca2de14ac0c015f"
             ],
             "markers": "python_version ~= '3.6'",
-            "version": "==0.2.6"
+            "version": "==0.2.8"
         },
         "multidict": {
             "hashes": [
@@ -863,11 +863,11 @@
         },
         "myst-parser": {
             "hashes": [
-                "sha256:260355b4da8e8865fe080b0638d7f1ab1791dc4bed02a7a48630b6bad4249219",
-                "sha256:e4bc99e43e19f70d22e528de8e7cce59f7e8e7c4c34dcba203de92de7a7c7c85"
+                "sha256:8d7db76e2f33cd1dc1fe0c76af9f09e5cf19ce2c2e85074bc82f272c0f7c08ce",
+                "sha256:fc262959a74cdc799d7fa9b30c320c17187485b9a1e8c39e988fc12f3adff63c"
             ],
             "index": "pypi",
-            "version": "==0.13.7"
+            "version": "==0.14.0"
         },
         "nodeenv": {
             "hashes": [
@@ -933,11 +933,11 @@
         },
         "pygments": {
             "hashes": [
-                "sha256:2656e1a6edcdabf4275f9a3640db59fd5de107d88e8663c5d4e9a0fa62f77f94",
-                "sha256:534ef71d539ae97d4c3a4cf7d6f110f214b0e687e92f9cb9d2a3b0d3101289c8"
+                "sha256:a18f47b506a429f6f4b9df81bb02beab9ca21d0a5fee38ed15aef65f0545519f",
+                "sha256:d66e804411278594d764fc69ec36ec13d9ae9147193a1740cd34d272ca383b8e"
             ],
             "markers": "python_version >= '3.5'",
-            "version": "==2.8.1"
+            "version": "==2.9.0"
         },
         "pyparsing": {
             "hashes": [
@@ -1061,10 +1061,10 @@
         },
         "rfc3986": {
             "hashes": [
-                "sha256:112398da31a3344dc25dbf477d8df6cb34f9278a94fee2625d89e4514be8bb9d",
-                "sha256:af9147e9aceda37c91a05f4deb128d4b4b49d6b199775fd2d2927768abdc8f50"
+                "sha256:270aaf10d87d0d4e095063c65bf3ddbc6ee3d0b226328ce21e036f946e421835",
+                "sha256:a86d6e1f5b1dc238b218b012df0aa79409667bb209e58da56d0b94704e712a97"
             ],
-            "version": "==1.4.0"
+            "version": "==1.5.0"
         },
         "secretstorage": {
             "hashes": [
@@ -1084,11 +1084,11 @@
         },
         "six": {
             "hashes": [
-                "sha256:30639c035cdb23534cd4aa2dd52c3bf48f06e5f4a941509c8bafd8ce11080259",
-                "sha256:8b74bedcbbbaca38ff6d7491d76f2b06b3592611af620f8426e82dddb04a5ced"
+                "sha256:1e61c37477a1626458e36f7b1d82aa5c9b094fa4802892072e49de9c60c4c926",
+                "sha256:8abb2f1d86890a2dfb989f9a77cfcfd3e47c2a354b01111771326f8aa26e0254"
             ],
             "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==1.15.0"
+            "version": "==1.16.0"
         },
         "snowballstemmer": {
             "hashes": [
@@ -1137,6 +1137,14 @@
             "markers": "python_version >= '3.5'",
             "version": "==1.0.1"
         },
+        "sphinxcontrib-programoutput": {
+            "hashes": [
+                "sha256:0ef1c1d9159dbe7103077748214305eb4e0138e861feb71c0c346afc5fe97f84",
+                "sha256:300ee9b8caee8355d25cc74b4d1c7efd12e608d2ad165e3141d31e6fbc152b7f"
+            ],
+            "index": "pypi",
+            "version": "==0.17"
+        },
         "sphinxcontrib-qthelp": {
             "hashes": [
                 "sha256:4c33767ee058b70dba89a6fc5c1892c0d57a54be67ddd3e7875a18d14cba5a72",
@@ -1215,13 +1223,13 @@
         },
         "typing-extensions": {
             "hashes": [
-                "sha256:7cb407020f00f7bfc3cb3e7881628838e69d8f3fcab2f64742a5e76b2f841918",
-                "sha256:99d4073b617d30288f569d3f13d2bd7548c3a7e4c8de87db09a9d29bb3a4a60c",
-                "sha256:dafc7639cde7f1b6e1acc0f457842a83e722ccca8eef5270af2d74792619a89f"
+                "sha256:0ac0f89795dd19de6b97debb0c6af1c70987fd80a2d62d1958f7e56fcc31b497",
+                "sha256:50b6f157849174217d0656f99dc82fe932884fb250826c18350e159ec6cdf342",
+                "sha256:779383f6086d90c99ae41cf0ff39aac8a7937a9283ce0a414e5dd782f4c94a84"
             ],
             "index": "pypi",
             "python_version <": "3.8",
-            "version": "==3.7.4.3",
+            "version": "==3.10.0.0",
             "version >=": "3.7.4"
         },
         "urllib3": {
@@ -1234,11 +1242,11 @@
         },
         "virtualenv": {
             "hashes": [
-                "sha256:09c61377ef072f43568207dc8e46ddeac6bcdcaf288d49011bda0e7f4d38c4a2",
-                "sha256:a935126db63128861987a7d5d30e23e8ec045a73840eeccb467c148514e29535"
+                "sha256:307a555cf21e1550885c82120eccaf5acedf42978fd362d32ba8410f9593f543",
+                "sha256:72cf267afc04bf9c86ec932329b7e94db6a0331ae9847576daaa7ca3c86b29a4"
             ],
             "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==20.4.4"
+            "version": "==20.4.6"
         },
         "webencodings": {
             "hashes": [
diff --git a/docs/conf.py b/docs/conf.py
index d5673738452..7162f13dd41 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -59,6 +59,7 @@ def make_pypi_svg(version: str) -> None:
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
     "myst_parser",
+    "sphinxcontrib.programoutput",
 ]
 
 # If you need extensions of a certain version or higher, list them here.
diff --git a/docs/contributing/gauging_changes.md b/docs/contributing/gauging_changes.md
index 6b70e0bc9bc..b41c7a35dda 100644
--- a/docs/contributing/gauging_changes.md
+++ b/docs/contributing/gauging_changes.md
@@ -37,25 +37,6 @@ If you're running locally yourself to test black on lots of code try:
 
 ### CLI arguments
 
-```text
-Usage: black-primer [OPTIONS]
+```{program-output} black-primer --help
 
-  primer - prime projects for blackening... 🏴
-
-Options:
-  -c, --config PATH      JSON config file path  [default: /Users/cooper/repos/
-                         black/src/black_primer/primer.json]
-
-  --debug                Turn on debug logging  [default: False]
-  -k, --keep             Keep workdir + repos post run  [default: False]
-  -L, --long-checkouts   Pull big projects to test  [default: False]
-  -R, --rebase           Rebase project if already checked out  [default:
-                         False]
-
-  -w, --workdir PATH     Directory path for repo checkouts  [default: /var/fol
-                         ders/tc/hbwxh76j1hn6gqjd2n2sjn4j9k1glp/T/primer.20200
-                         517125229]
-
-  -W, --workers INTEGER  Number of parallel worker coroutines  [default: 2]
-  -h, --help             Show this message and exit.
 ```
diff --git a/docs/requirements.txt b/docs/requirements.txt
index 6c34e1fefab..c65cbe3c476 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,2 +1,3 @@
-MyST-Parser==0.13.7
+MyST-Parser==0.14.0
 Sphinx==3.5.4
+sphinxcontrib-programoutput==0.17
diff --git a/docs/usage_and_configuration/black_as_a_server.md b/docs/usage_and_configuration/black_as_a_server.md
index 0c0382b3e50..75a4d925a54 100644
--- a/docs/usage_and_configuration/black_as_a_server.md
+++ b/docs/usage_and_configuration/black_as_a_server.md
@@ -18,14 +18,8 @@ formatting requests.
 `blackd` provides even less options than _Black_. You can see them by running
 `blackd --help`:
 
-```text
-Usage: blackd [OPTIONS]
-
-Options:
-  --bind-host TEXT                Address to bind the server to.
-  --bind-port INTEGER             Port to listen on
-  --version                       Show the version and exit.
-  -h, --help                      Show this message and exit.
+```{program-output} blackd --help
+
 ```
 
 There is no official `blackd` client tool (yet!). You can test that blackd is working
diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index 6fd8769b591..4ac1693ea8b 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -34,92 +34,8 @@ running `black --help`.
 
 <summary>Help output</summary>
 
-```
-  Usage: black [OPTIONS] [SRC]...
-
-    The uncompromising code formatter.
-
-  Options:
-    -c, --code TEXT                 Format the code passed in as a string.
-    -l, --line-length INTEGER       How many characters per line to allow.
-                                    [default: 88]
-
-    -t, --target-version [py27|py33|py34|py35|py36|py37|py38|py39]
-                                    Python versions that should be supported by
-                                    Black's output. [default: per-file auto-
-                                    detection]
-
-    --pyi                           Format all input files like typing stubs
-                                    regardless of file extension (useful when
-                                    piping source on standard input).
-
-    -S, --skip-string-normalization
-                                    Don't normalize string quotes or prefixes.
-    -C, --skip-magic-trailing-comma
-                                    Don't use trailing commas as a reason to
-                                    split lines.
-
-    --check                         Don't write the files back, just return the
-                                    status. Return code 0 means nothing would
-                                    change. Return code 1 means some files
-                                    would be reformatted. Return code 123 means
-                                    there was an internal error.
-
-    --diff                          Don't write the files back, just output a
-                                    diff for each file on stdout.
-
-    --color / --no-color            Show colored diff. Only applies when
-                                    `--diff` is given.
-
-    --fast / --safe                 If --fast given, skip temporary sanity
-                                    checks. [default: --safe]
-
-    --include TEXT                  A regular expression that matches files and
-                                    directories that should be included on
-                                    recursive searches. An empty value means
-                                    all files are included regardless of the
-                                    name. Use forward slashes for directories
-                                    on all platforms (Windows, too). Exclusions
-                                    are calculated first, inclusions later.
-                                    [default: \.pyi?$]
-
-    --exclude TEXT                  A regular expression that matches files and
-                                    directories that should be excluded on
-                                    recursive searches. An empty value means no
-                                    paths are excluded. Use forward slashes for
-                                    directories on all platforms (Windows, too).
-                                    Exclusions are calculated first, inclusions
-                                    later.  [default: /(\.direnv|\.eggs|\.git|\.
-                                    hg|\.mypy_cache|\.nox|\.tox|\.venv|venv|\.svn|_bu
-                                    ild|buck-out|build|dist)/]
-
-    --extend-exclude TEXT           Like --exclude, but adds additional files
-                                    and directories on top of the excluded
-                                    ones (useful if you simply want to add to
-                                    the default).
-
-    --force-exclude TEXT            Like --exclude, but files and directories
-                                    matching this regex will be excluded even
-                                    when they are passed explicitly as
-                                    arguments.
-
-
-    --stdin-filename TEXT           The name of the file when passing it through
-                                    stdin. Useful to make sure Black will
-                                    respect --force-exclude option on some
-                                    editors that rely on using stdin.
-
-    -q, --quiet                     Don't emit non-error messages to stderr.
-                                    Errors are still emitted; silence those with
-                                    2>/dev/null.
-
-    -v, --verbose                   Also emit messages to stderr about files
-                                    that were not changed or were ignored due to
-                                    exclusion patterns.
-
-    --version                       Show the version and exit.
-    --config FILE                   Read configuration from FILE path.
-    -h, --help                      Show this message and exit.
+```{program-output} black --help
+
 ```
 
 </details>

From 7c851dfa2c2a8f0bf4c529d7f6faa43798d04325 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Mon, 10 May 2021 10:57:22 -0400
Subject: [PATCH 0191/1034] Cover more in the usage docs (#2208)

Commit history before merge:

* Cover more in the usage docs
* Minor fixes
* Even more corrections by Jelle
* Update docs/usage_and_configuration/the_basics.md

  Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 docs/usage_and_configuration/the_basics.md | 143 +++++++++++++++++++++
 1 file changed, 143 insertions(+)

diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index 4ac1693ea8b..0b2cd3b3544 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -40,6 +40,149 @@ running `black --help`.
 
 </details>
 
+### Code input alternatives
+
+#### Standard Input
+
+_Black_ supports formatting code via stdin, with the result being printed to stdout.
+Just let _Black_ know with `-` as the path.
+
+```console
+$ echo "print ( 'hello, world' )" | black -
+print("hello, world")
+reformatted -
+All done! ✨ 🍰 ✨
+1 file reformatted.
+```
+
+**Tip:** if you need _Black_ to treat stdin input as a file passed directly via the CLI,
+use `--stdin-filename`. Useful to make sure _Black_ will respect the `--force-exclude`
+option on some editors that rely on using stdin.
+
+#### As a string
+
+You can also pass code as a string using the `-c` / `--code` option.
+
+```console
+$ black --code "print ( 'hello, world' )"
+print("hello, world")
+```
+
+```{warning}
+--check, --diff, and --safe / --fast have no effect when using -c / --code. Safety
+checks normally turned on by default that verify _Black_'s output are disabled as well.
+This is a bug which we intend to fix eventually. More details can be found in this [bug
+report](https://github.com/psf/black/issues/2104).
+```
+
+### Writeback and reporting
+
+By default _Black_ reformats the files given and/or found in place. Sometimes you need
+_Black_ to just tell you what it _would_ do without actually rewriting the Python files.
+
+There's two variations to this mode that are independently enabled by their respective
+flags. Both variations can be enabled at once.
+
+#### Exit code
+
+Passing `--check` will make _Black_ exit with:
+
+- code 0 if nothing would change;
+- code 1 if some files would be reformatted; or
+- code 123 if there was an internal error
+
+```console
+$ black test.py --check
+All done! ✨ 🍰 ✨
+1 file would be left unchanged.
+$ echo $?
+0
+
+$ black test.py --check
+would reformat test.py
+Oh no! 💥 💔 💥
+1 file would be reformatted.
+$ echo $?
+1
+
+$ black test.py --check
+error: cannot format test.py: INTERNAL ERROR: Black produced code that is not equivalent to the source.  Please report a bug on https://github.com/psf/black/issues.  This diff might be helpful: /tmp/blk_kjdr1oog.log
+Oh no! 💥 💔 💥
+1 file would fail to reformat.
+$ echo $?
+123
+```
+
+#### Diffs
+
+Passing `--diff` will make _Black_ print out diffs that indicate what changes _Black_
+would've made. They are printed to stdout so capturing them is simple.
+
+If you'd like colored diffs, you can enable them with the `--color`.
+
+```console
+$ black test.py --diff
+--- test.py     2021-03-08 22:23:40.848954 +0000
++++ test.py     2021-03-08 22:23:47.126319 +0000
+@@ -1 +1 @@
+-print ( 'hello, world' )
++print("hello, world")
+would reformat test.py
+All done! ✨ 🍰 ✨
+1 file would be reformatted.
+```
+
+### Output verbosity
+
+_Black_ in general tries to produce the right amount of output, balancing between
+usefulness and conciseness. By default, _Black_ emits files modified and error messages,
+plus a short summary.
+
+```console
+$ black src/
+error: cannot format src/black_primer/cli.py: Cannot parse: 5:6: mport asyncio
+reformatted src/black_primer/lib.py
+reformatted src/blackd/__init__.py
+reformatted src/black/__init__.py
+Oh no! 💥 💔 💥
+3 files reformatted, 2 files left unchanged, 1 file failed to reformat.
+```
+
+Passing `-v` / `--verbose` will cause _Black_ to also emit messages about files that
+were not changed or were ignored due to exclusion patterns. If _Black_ is using a
+configuration file, a blue message detailing which one it is using will be emitted.
+
+```console
+$ black src/ -v
+Using configuration from /tmp/pyproject.toml.
+src/blib2to3 ignored: matches the --extend-exclude regular expression
+src/_black_version.py wasn't modified on disk since last run.
+src/black/__main__.py wasn't modified on disk since last run.
+error: cannot format src/black_primer/cli.py: Cannot parse: 5:6: mport asyncio
+reformatted src/black_primer/lib.py
+reformatted src/blackd/__init__.py
+reformatted src/black/__init__.py
+Oh no! 💥 💔 💥
+3 files reformatted, 2 files left unchanged, 1 file failed to reformat
+```
+
+Passing `-q` / `--quiet` will cause _Black_ to stop emitting all non-critial output.
+Error messages will still be emitted (which can silenced by `2>/dev/null`).
+
+```console
+$ black src/ -q
+error: cannot format src/black_primer/cli.py: Cannot parse: 5:6: mport asyncio
+```
+
+### Getting the version
+
+You can check the version of _Black_ you have installed using the `--version` flag.
+
+```console
+$ black --version
+black, version 21.5b0
+```
+
 ## Configuration via a file
 
 _Black_ is able to read project-specific default values for its command line options

From f1ce47bd2b0150d2b7c78beaafd3b60c469345d0 Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Mon, 10 May 2021 07:58:36 -0700
Subject: [PATCH 0192/1034] Release process docs (#2214)

* Setup groundwork for release process docs

I'm using MyST for the index page since I like it more and it's easier
to work with.

* Fill in Release Process for black

* Apply suggestions from code review

Apply Jelle's grammar + typo fixes. I am a terrible only English speaker.

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>

* Update release_process.md

Make lint happy via web UI.

* Move to contribution section and fix prettier

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 docs/contributing/index.rst          |  2 +
 docs/contributing/release_process.md | 72 ++++++++++++++++++++++++++++
 2 files changed, 74 insertions(+)
 create mode 100644 docs/contributing/release_process.md

diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst
index 68dfcd60c28..e7a7f9fb231 100644
--- a/docs/contributing/index.rst
+++ b/docs/contributing/index.rst
@@ -6,6 +6,7 @@ Contributing
 
   the_basics
   gauging_changes
+  release_process
   reference/reference_summary
 
 Welcome! Happy to see you willing to make the project better. Have you read the entire
@@ -31,6 +32,7 @@ This section covers the following topics:
 
 - :doc:`the_basics`
 - :doc:`gauging_changes`
+- :doc:`release_process`
 - :doc:`reference/reference_summary`
 
 For an overview on contributing to the *Black*, please checkout :doc:`the_basics`.
diff --git a/docs/contributing/release_process.md b/docs/contributing/release_process.md
new file mode 100644
index 00000000000..fadef4bbe3d
--- /dev/null
+++ b/docs/contributing/release_process.md
@@ -0,0 +1,72 @@
+# Release process
+
+_Black_ has had a lot of work automating its release process. This document sets out to
+explain what everything does and how to release _Black_ using said automation.
+
+## Cutting a Relase
+
+To cut a realease, you must be a _Black_ maintainer with `GitHub Release` creation
+access. Using this access, the release process is:
+
+1. Cut a new PR editing `CHANGES.md` to version the latest changes
+   1. Example PR: https://github.com/psf/black/pull/2192
+   2. Example title: `Update CHANGES.md for XX.X release`
+2. Once the release PR is merged ensure all CI passes
+   1. If not, ensure there is an Issue open for the cause of failing CI (generally we'd
+      want this fixed before cutting a release)
+3. Open `CHANGES.md` and copy the _raw markdown_ of the latest changes to use in the
+   description of the GitHub Release.
+4. Go and [cut a release](https://github.com/psf/black/releases) using the GitHub UI so
+   that all workflows noted below are triggered.
+   1. The release version and tag should be the [CalVer](https://calver.org) version
+      _Black_ used for the current release e.g. `21.6` / `21.5b1`
+   2. _Black_ uses [setuptools scm](https://pypi.org/project/setuptools-scm/) to pull
+      the current version for the package builds and release.
+5. Once the release is cut, you're basically done. It's a good practice to go and watch
+   to make sure all the [GitHub Actions](https://github.com/psf/black/actions) pass,
+   although you should receive an email to your registered GitHub email address should
+   one fail.
+   1. You should see all the release workflows and lint/unittests workflows running on
+      the new tag in the Actions UI
+
+If anything fails, please go read the respective action's log output and configuration
+file to reverse engineer your way to a fix/soluton.
+
+## Release workflows
+
+All _Blacks_'s automation workflows use GitHub Actions. All workflows are therefore
+configured using `.yml` files in the `.github/workflows` directory of the _Black_
+repository.
+
+Below are descriptions of our release workflows.
+
+### Docker
+
+This workflow uses the QEMU powered `buildx` feature of docker to upload a `arm64` and
+`amd64`/`x86_64` build of the official _Black_ docker image™.
+
+- Currently this workflow uses an API Token associated with @cooperlees account
+
+### pypi_upload
+
+This workflow builds a Python
+[sdist](https://docs.python.org/3/distutils/sourcedist.html) and
+[wheel](https://pythonwheels.com) using the latest
+[setuptools](https://pypi.org/project/setuptools/) and
+[wheel](https://pypi.org/project/wheel/) modules.
+
+It will then use [twine](https://pypi.org/project/twine/) to upload both release formats
+to PyPI for general downloading of the _Black_ Python package. This is where
+[pip](https://pypi.org/project/pip/) looks by default.
+
+- Currently this workflow uses an API token associated with @ambv's PyPI account
+
+### Upload self-contained binaries
+
+This workflow builds self-contained binaries for multiple platforms. This allows people
+to download the executable for their platform and run _Black_ without a
+[Python Runtime](https://wiki.python.org/moin/PythonImplementations) installed.
+
+The created binaries are attached/stored on the associated
+[GitHub Release](https://github.com/psf/black/releases) for download over _IPv4 only_
+(GitHub still does not have IPv6 access 😢).

From f933e8a8382e6945bf950356f6ecc4ded5617617 Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Mon, 10 May 2021 07:59:32 -0700
Subject: [PATCH 0193/1034] Update CHANGES.md for 21.5b1 release (#2215)

---
 CHANGES.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index 32c2d8d7237..38eef524b7c 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,6 +1,6 @@
 # Change Log
 
-## Unreleased
+## 21.5b1
 
 ### _Black_
 

From 2f52e4b4929370ec503ee272bcc10d3176db8e89 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Mon, 10 May 2021 08:01:53 -0700
Subject: [PATCH 0194/1034] fix typo (#2217)

---
 docs/contributing/release_process.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/contributing/release_process.md b/docs/contributing/release_process.md
index fadef4bbe3d..ae95cd703c9 100644
--- a/docs/contributing/release_process.md
+++ b/docs/contributing/release_process.md
@@ -5,7 +5,7 @@ explain what everything does and how to release _Black_ using said automation.
 
 ## Cutting a Relase
 
-To cut a realease, you must be a _Black_ maintainer with `GitHub Release` creation
+To cut a release, you must be a _Black_ maintainer with `GitHub Release` creation
 access. Using this access, the release process is:
 
 1. Cut a new PR editing `CHANGES.md` to version the latest changes

From 53d9bace12b3aa230820c869a079020b4608c945 Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Tue, 11 May 2021 10:01:03 -0700
Subject: [PATCH 0195/1034] Add stable tag process to release process
 documentation (#2224)

* Add stable tag process to release process documentation
- Add reasoning + step commands

* Bah - I ran the linter but forgot to commit

* Update docs/contributing/release_process.md

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 docs/contributing/release_process.md | 19 ++++++++++++++++++-
 1 file changed, 18 insertions(+), 1 deletion(-)

diff --git a/docs/contributing/release_process.md b/docs/contributing/release_process.md
index ae95cd703c9..718ea3dc9a2 100644
--- a/docs/contributing/release_process.md
+++ b/docs/contributing/release_process.md
@@ -3,7 +3,7 @@
 _Black_ has had a lot of work automating its release process. This document sets out to
 explain what everything does and how to release _Black_ using said automation.
 
-## Cutting a Relase
+## Cutting a Release
 
 To cut a release, you must be a _Black_ maintainer with `GitHub Release` creation
 access. Using this access, the release process is:
@@ -70,3 +70,20 @@ to download the executable for their platform and run _Black_ without a
 The created binaries are attached/stored on the associated
 [GitHub Release](https://github.com/psf/black/releases) for download over _IPv4 only_
 (GitHub still does not have IPv6 access 😢).
+
+## Moving the `stable` tag
+
+_Black_ provides a stable tag for people who want to move along as _Black_ developers
+deem the newest version reliable. Here the _Black_ developers will move once the release
+has been problem free for at least ~24 hours from release. Given the large _Black_
+userbase we hear about bad bugs quickly. We do strive to continually improve our CI too.
+
+### Tag moving process
+
+#### stable
+
+From a rebased `main` checkout:
+
+1. `git tag -f stable VERSION_TAG`
+   1. e.g. `git tag -f stable 21.5b1`
+1. `git push --tags -f`

From 94a0b07dbebabe344991dc27f9eb0b11597bb3b5 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Tue, 11 May 2021 14:09:33 -0400
Subject: [PATCH 0196/1034] Remove useless flake8 config + test support code
 (#2221)

We've depended on Click 7.x ever since we broke CI systems across the
world (oops lol) and flake8-mypy was purged a fair bit back: #1867

Also remove the primer tests import in tests/test_black.py because it's
annoying when just trying to actually target tests/test_black.py tests.
`pytest -k test_black.py` doesn't do what you expect due to that import.
---
 .flake8             |  4 ----
 tests/test_black.py | 35 +++++++----------------------------
 2 files changed, 7 insertions(+), 32 deletions(-)

diff --git a/.flake8 b/.flake8
index 68d15015a37..4866133a6a8 100644
--- a/.flake8
+++ b/.flake8
@@ -5,7 +5,3 @@ extend-ignore = E203, E266, E501
 max-line-length = 80
 max-complexity = 18
 select = B,C,E,F,W,T4,B9
-# We need to configure the mypy.ini because the flake8-mypy's default
-# options don't properly override it, so if we don't specify it we get
-# half of the config from mypy.ini and half from flake8-mypy.
-mypy_config = mypy.ini
diff --git a/tests/test_black.py b/tests/test_black.py
index 347eaf621fe..4cbb022954f 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -6,7 +6,7 @@
 from contextlib import contextmanager
 from dataclasses import replace
 import inspect
-from io import BytesIO, TextIOWrapper
+from io import BytesIO
 import os
 from pathlib import Path
 from platform import system
@@ -16,10 +16,8 @@
 import types
 from typing import (
     Any,
-    BinaryIO,
     Callable,
     Dict,
-    Generator,
     List,
     Iterator,
     TypeVar,
@@ -52,7 +50,6 @@
     ff,
     dump_to_stderr,
 )
-from .test_primer import PrimerCLITests  # noqa: F401
 
 
 THIS_FILE = Path(__file__)
@@ -104,28 +101,10 @@ def __init__(self) -> None:
 
 
 class BlackRunner(CliRunner):
-    """Modify CliRunner so that stderr is not merged with stdout.
-
-    This is a hack that can be removed once we depend on Click 7.x"""
+    """Make sure STDOUT and STDERR are kept seperate when testing Black via its CLI."""
 
     def __init__(self) -> None:
-        self.stderrbuf = BytesIO()
-        self.stdoutbuf = BytesIO()
-        self.stdout_bytes = b""
-        self.stderr_bytes = b""
-        super().__init__()
-
-    @contextmanager
-    def isolation(self, *args: Any, **kwargs: Any) -> Generator[BinaryIO, None, None]:
-        with super().isolation(*args, **kwargs) as output:
-            try:
-                hold_stderr = sys.stderr
-                sys.stderr = TextIOWrapper(self.stderrbuf, encoding=self.charset)
-                yield output
-            finally:
-                self.stdout_bytes = sys.stdout.buffer.getvalue()  # type: ignore
-                self.stderr_bytes = sys.stderr.buffer.getvalue()  # type: ignore
-                sys.stderr = hold_stderr
+        super().__init__(mix_stderr=False)
 
 
 class BlackTestCase(BlackBaseTestCase):
@@ -141,8 +120,8 @@ def invokeBlack(
             exit_code,
             msg=(
                 f"Failed with args: {args}\n"
-                f"stdout: {runner.stdout_bytes.decode()!r}\n"
-                f"stderr: {runner.stderr_bytes.decode()!r}\n"
+                f"stdout: {result.stdout_bytes.decode()!r}\n"
+                f"stderr: {result.stderr_bytes.decode()!r}\n"
                 f"exception: {result.exception}"
             ),
         )
@@ -483,7 +462,7 @@ def test_python2_should_fail_without_optional_install(self) -> None:
         finally:
             os.unlink(tmp_file)
         actual = (
-            runner.stderr_bytes.decode()
+            result.stderr_bytes.decode()
             .replace("\n", "")
             .replace("\\n", "")
             .replace("\\r", "")
@@ -1806,7 +1785,7 @@ def test_preserves_line_endings_via_stdin(self) -> None:
                 black.main, ["-", "--fast"], input=BytesIO(contents.encode("utf8"))
             )
             self.assertEqual(result.exit_code, 0)
-            output = runner.stdout_bytes
+            output = result.stdout_bytes
             self.assertIn(nl.encode("utf8"), output)
             if nl == "\n":
                 self.assertNotIn(b"\r\n", output)

From b2ee211b5ad84b62738ac0997b73bf6ee9a74d06 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C5=81ukasz=20Langa?= <lukasz@langa.pl>
Date: Wed, 12 May 2021 21:47:32 +0200
Subject: [PATCH 0197/1034] Click 8.0 renamed its "die on LANG=C" function so
 we need to look for that one too (#2227)

---
 CHANGES.md            | 6 ++++++
 mypy.ini              | 6 ++++--
 src/black/__init__.py | 6 ++++--
 3 files changed, 14 insertions(+), 4 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 38eef524b7c..becd621dbf2 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,5 +1,11 @@
 # Change Log
 
+## Unreleased
+
+### _Black_
+
+- Restored compatibility with Click 8.0 on Python 3.6 when LANG=C used (#2227)
+
 ## 21.5b1
 
 ### _Black_
diff --git a/mypy.ini b/mypy.ini
index 589fbf65139..ae7be5e5106 100644
--- a/mypy.ini
+++ b/mypy.ini
@@ -33,5 +33,7 @@ cache_dir=/dev/null
 
 [mypy-aiohttp.*]
 follow_imports=skip
-[mypy-_version]
-follow_imports=skip
+[mypy-black]
+# The following is because of `patch_click()`. Remove when
+# we drop Python 3.6 support.
+warn_unused_ignores=False
diff --git a/src/black/__init__.py b/src/black/__init__.py
index c61bc8c1d60..f46b866c1bd 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -1029,7 +1029,7 @@ def nullcontext() -> Iterator[None]:
 
 
 def patch_click() -> None:
-    """Make Click not crash.
+    """Make Click not crash on Python 3.6 with LANG=C.
 
     On certain misconfigured environments, Python 3 selects the ASCII encoding as the
     default which restricts paths that it can access during the lifetime of the
@@ -1047,7 +1047,9 @@ def patch_click() -> None:
 
     for module in (core, _unicodefun):
         if hasattr(module, "_verify_python3_env"):
-            module._verify_python3_env = lambda: None
+            module._verify_python3_env = lambda: None  # type: ignore
+        if hasattr(module, "_verify_python_env"):
+            module._verify_python_env = lambda: None  # type: ignore
 
 
 def patched_main() -> None:

From 3ef339b2e75468a09d617e6aa74bc920c317bce6 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Wed, 12 May 2021 21:28:41 -0400
Subject: [PATCH 0198/1034] Modify when Test, Primer, and Documentation Build
 run (#2226)

- Test and Primer don't run for documentation only changes since it's
  unnecessary, eating unnecessary cycles and slowing down CI since these
  workflows eat up the 20 max workers limit quite easily!

- Documentation Build runs all of the time now since quite a bit of the
  content depends on Black's code so even a simple 1-file change in
  src/black/__init__.py may break the docs build. It's not like this is
  a costly workflow anyway.

Fuzz is still running on all changes because with fuzzing, the more the
better in general. 6 or 7 jobs on a documentation only commit is much
better than 27/28 jobs anyway :p

I also found an error in our bug report issue template :)
---
 .github/ISSUE_TEMPLATE/bug_report.md |  2 +-
 .github/workflows/doc.yml            | 16 +---------------
 .github/workflows/primer.yml         | 11 ++++++++++-
 .github/workflows/test.yml           | 11 ++++++++++-
 4 files changed, 22 insertions(+), 18 deletions(-)

diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
index c6c80be5345..069795f7776 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -30,7 +30,7 @@ assignees: ""
    - clone this repository;
    - run `pip install -e .[d,python2]`;
    - run `pip install -r test_requirements.txt`
-   - make sure it's sane by running `python -m unittest`; and
+   - make sure it's sane by running `python -m pytest`; and
    - run `black` like you did last time.
 
 **Additional context** Add any other context about the problem here.
diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml
index 74ec316a7cf..04b25cf2a16 100644
--- a/.github/workflows/doc.yml
+++ b/.github/workflows/doc.yml
@@ -1,20 +1,6 @@
 name: Documentation Build
 
-on:
-  push:
-    paths:
-      - "docs/**"
-      - "README.md"
-      - "CHANGES.md"
-      - "CONTRIBUTING.md"
-      - "AUTHORS.md"
-  pull_request:
-    paths:
-      - "docs/**"
-      - "README.md"
-      - "CHANGES.md"
-      - "CONTRIBUTING.md"
-      - "AUTHORS.md"
+on: [push, pull_request]
 
 jobs:
   build:
diff --git a/.github/workflows/primer.yml b/.github/workflows/primer.yml
index 4c5751ae996..5f41c301737 100644
--- a/.github/workflows/primer.yml
+++ b/.github/workflows/primer.yml
@@ -1,6 +1,15 @@
 name: Primer
 
-on: [push, pull_request]
+on:
+  push:
+    paths-ignore:
+      - "docs/**"
+      - "*.md"
+
+  pull_request:
+    paths-ignore:
+      - "docs/**"
+      - "*.md"
 
 jobs:
   build:
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 2cfbab67ce1..ef8debb3fb7 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -1,6 +1,15 @@
 name: Test
 
-on: [push, pull_request]
+on:
+  push:
+    paths-ignore:
+      - "docs/**"
+      - "*.md"
+
+  pull_request:
+    paths-ignore:
+      - "docs/**"
+      - "*.md"
 
 jobs:
   build:

From 445f094f1fa2d998bf0cc0007ea48d62953fa876 Mon Sep 17 00:00:00 2001
From: Christian Clauss <cclauss@me.com>
Date: Thu, 13 May 2021 19:28:41 +0200
Subject: [PATCH 0199/1034] Use codespell to find typos (#2228)

---
 CHANGES.md              | 1 +
 docs/index.rst          | 2 +-
 src/black/trans.py      | 2 +-
 src/black_primer/lib.py | 2 +-
 tests/test_black.py     | 4 ++--
 5 files changed, 6 insertions(+), 5 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index becd621dbf2..3639d8ebaf9 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -4,6 +4,7 @@
 
 ### _Black_
 
+- Fix typos discovered by codespell (#2228)
 - Restored compatibility with Click 8.0 on Python 3.6 when LANG=C used (#2227)
 
 ## 21.5b1
diff --git a/docs/index.rst b/docs/index.rst
index a7a7160f71f..2b85cddd3c0 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -22,7 +22,7 @@ Try it out now using the `Black Playground <https://black.vercel.app>`_.
    many projects, small and big. *Black* has a comprehensive test suite, with efficient
    parallel tests, our own auto  formatting and parallel Continuous Integration runner.
    However, *Black* is still beta. Things will probably be wonky for a while. This is
-   made explicit by the "Beta" trove classifier, as well as by the "b" in the versio
+   made explicit by the "Beta" trove classifier, as well as by the "b" in the version
    number. What this means for you is that **until the formatter becomes stable, you
    should expect some formatting to change in the future**. That being said, no drastic
    stylistic changes are planned, mostly responses to bug reports.
diff --git a/src/black/trans.py b/src/black/trans.py
index 055f33c0ee2..7ecc31d6d31 100644
--- a/src/black/trans.py
+++ b/src/black/trans.py
@@ -576,7 +576,7 @@ class StringParenStripper(StringTransformer):
             - The target string is NOT the only argument to a function call.
             - The target string is NOT a "pointless" string.
             - If the target string contains a PERCENT, the brackets are not
-              preceeded or followed by an operator with higher precedence than
+              preceded or followed by an operator with higher precedence than
               PERCENT.
 
     Transformations:
diff --git a/src/black_primer/lib.py b/src/black_primer/lib.py
index 3ce383f17ce..384c0ad6cea 100644
--- a/src/black_primer/lib.py
+++ b/src/black_primer/lib.py
@@ -128,7 +128,7 @@ async def black_run(
         cmd.extend(["--diff", "."])
 
     with TemporaryDirectory() as tmp_path:
-        # Prevent reading top-level user configs by manipulating envionment variables
+        # Prevent reading top-level user configs by manipulating environment variables
         env = {
             **os.environ,
             "XDG_CONFIG_HOME": tmp_path,  # Unix-like
diff --git a/tests/test_black.py b/tests/test_black.py
index 4cbb022954f..5ab25cd1601 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -101,7 +101,7 @@ def __init__(self) -> None:
 
 
 class BlackRunner(CliRunner):
-    """Make sure STDOUT and STDERR are kept seperate when testing Black via its CLI."""
+    """Make sure STDOUT and STDERR are kept separate when testing Black via its CLI."""
 
     def __init__(self) -> None:
         super().__init__(mix_stderr=False)
@@ -1508,7 +1508,7 @@ def test_get_sources_with_stdin_filename(self) -> None:
 
     @patch("black.find_project_root", lambda *args: THIS_DIR.resolve())
     def test_get_sources_with_stdin_filename_and_exclude(self) -> None:
-        # Exclude shouldn't exclude stdin_filename since it is mimicing the
+        # Exclude shouldn't exclude stdin_filename since it is mimicking the
         # file being passed directly. This is the same as
         # test_exclude_for_issue_1572
         path = THIS_DIR / "data" / "include_exclude_tests"

From 904fe94ceba29f3f0c5b8772c4faf699de57338f Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Thu, 13 May 2021 15:30:34 -0400
Subject: [PATCH 0200/1034] Add lower bound for aiohttp-cors + fix primer
 (#2231)

It appears sqlalchemy has recently reformatted their project with
Black 21.5b1.

Most of our dependencies have a lower bound and creating a test
environment with the oldest acceptable dependencies runs the full
Black test suite just fine. The only exception to this is aiohttp-cors.
It's unbounded and the oldest version 0.1.0 until 0.4.0 breaks the
test suite in such an old environment.

Failure with 0.1.0:

```
tests/test_blackd.py:10: in <module>
    import blackd
testenv/lib/python3.8/site-packages/blackd/__init__.py:12: in <module>
    import aiohttp_cors
testenv/lib/python3.8/site-packages/aiohttp_cors/__init__.py:29: in <module>
    from .urldispatcher_router_adapter import UrlDistatcherRouterAdapter
testenv/lib/python3.8/site-packages/aiohttp_cors/urldispatcher_router_adapter.py:27: in <module>
    class UrlDistatcherRouterAdapter(RouterAdapter):
testenv/lib/python3.8/site-packages/aiohttp_cors/urldispatcher_router_adapter.py:32: in UrlDistatcherRouterAdapter
    def route_methods(self, route: web.Route):
E   AttributeError: module 'aiohttp.web' has no attribute 'Route'
```

For 0.2.0:

```
tests/test_blackd.py:10: in <module>
    import blackd
testenv/lib/python3.8/site-packages/blackd/__init__.py:12: in <module>
    import aiohttp_cors
testenv/lib/python3.8/site-packages/aiohttp_cors/__init__.py:27: in <module>
    from .cors_config import CorsConfig
testenv/lib/python3.8/site-packages/aiohttp_cors/cors_config.py:24: in <module>
    from .urldispatcher_router_adapter import UrlDistatcherRouterAdapter
testenv/lib/python3.8/site-packages/aiohttp_cors/urldispatcher_router_adapter.py:27: in <module>
    class UrlDistatcherRouterAdapter(AbstractRouterAdapter):
testenv/lib/python3.8/site-packages/aiohttp_cors/urldispatcher_router_adapter.py:32: in UrlDistatcherRouterAdapter
    def route_methods(self, route: web.Route):
E   AttributeError: module 'aiohttp.web' has no attribute 'Route'
```

For 0.3.0:

```
ERROR: Cannot install aiohttp-cors==0.3.0 and aiohttp==3.6.0 because these package versions have conflicting dependencies.

The conflict is caused by:
    The user requested aiohttp==3.6.0
    aiohttp-cors 0.3.0 depends on aiohttp<=0.20.2 and >=0.18.0

To fix this you could try to:
1. loosen the range of package versions you've specified
2. remove package versions to allow pip attempt to solve the dependency conflict

ERROR: ResolutionImpossible: for help visit https://pip.pypa.io/en/latest/user_guide/#fixing-conflicting-dependencies
```
---
 CHANGES.md                   | 5 +++++
 setup.py                     | 2 +-
 src/black_primer/primer.json | 2 +-
 3 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 3639d8ebaf9..85936e870b1 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -7,6 +7,11 @@
 - Fix typos discovered by codespell (#2228)
 - Restored compatibility with Click 8.0 on Python 3.6 when LANG=C used (#2227)
 
+### _Blackd_
+
+- Add a lower bound for the `aiohttp-cors` dependency. Only 0.4.0 or higher is
+  supported. (#2231)
+
 ## 21.5b1
 
 ### _Black_
diff --git a/setup.py b/setup.py
index 3dc52b26e81..2b5f71f56dd 100644
--- a/setup.py
+++ b/setup.py
@@ -83,7 +83,7 @@ def get_long_description() -> str:
         "mypy_extensions>=0.4.3",
     ],
     extras_require={
-        "d": ["aiohttp>=3.6.0", "aiohttp-cors"],
+        "d": ["aiohttp>=3.6.0", "aiohttp-cors>=0.4.0"],
         "colorama": ["colorama>=0.4.3"],
         "python2": ["typed-ast>=1.4.2"],
     },
diff --git a/src/black_primer/primer.json b/src/black_primer/primer.json
index 76ed4820487..0bbac85ca2e 100644
--- a/src/black_primer/primer.json
+++ b/src/black_primer/primer.json
@@ -106,7 +106,7 @@
     "sqlalchemy": {
       "no_cli_args_reason": "breaks black with new string parsing - #2188",
       "cli_arguments": [],
-      "expect_formatting_changes": true,
+      "expect_formatting_changes": false,
       "git_clone_url": "https://github.com/sqlalchemy/sqlalchemy.git",
       "long_checkout": false,
       "py_versions": ["all"]

From 403ce1a18a8a1600ab8249d828e7eaaca442cad7 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Sun, 16 May 2021 12:07:27 -0400
Subject: [PATCH 0201/1034] Add issue triage documentation (#2236)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Add issue triage documentation

Co-authored-by: Łukasz Langa <lukasz@langa.pl>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 Pipfile                           |   3 +-
 Pipfile.lock                      | 120 ++++++++++-----------
 docs/conf.py                      |   1 +
 docs/contributing/index.rst       |   1 +
 docs/contributing/issue_triage.md | 167 ++++++++++++++++++++++++++++++
 docs/requirements.txt             |   3 +
 6 files changed, 229 insertions(+), 66 deletions(-)
 create mode 100644 docs/contributing/issue_triage.md

diff --git a/Pipfile b/Pipfile
index b3859571137..789d97c3cbc 100644
--- a/Pipfile
+++ b/Pipfile
@@ -14,6 +14,7 @@ pre-commit = "*"
 readme_renderer = "*"
 MyST-Parser = ">=0.13.7"
 sphinxcontrib-programoutput = ">=0.17"
+sphinx-copybutton = ">=0.3.0"
 setuptools = ">=39.2.0"
 setuptools-scm = "*"
 twine = ">=1.11.0"
@@ -22,7 +23,7 @@ black = {editable = true, extras = ["d"], path = "."}
 
 [packages]
 aiohttp = ">=3.6.0"
-aiohttp-cors = "*"
+aiohttp-cors = ">=0.4.0"
 appdirs = "*"
 click = ">=7.1.2"
 mypy_extensions = ">=0.4.3"
diff --git a/Pipfile.lock b/Pipfile.lock
index 0b9e529e73b..b6dfe438e9e 100644
--- a/Pipfile.lock
+++ b/Pipfile.lock
@@ -1,7 +1,7 @@
 {
     "_meta": {
         "hash": {
-            "sha256": "fdfbacb362e4514e588736a7e8783837cb5e3aa2fbab98ea17894fdb50d51a8e"
+            "sha256": "b450e698cfe4d856397cb9d0695dcd74eb97b1d234de273179d78c0d0efccd0f"
         },
         "pipfile-spec": 6,
         "requires": {},
@@ -106,11 +106,11 @@
         },
         "click": {
             "hashes": [
-                "sha256:d2b5255c7c6349bc1bd1e59e08cd12acbbd63ce649f2588755783aa94dfb6b1a",
-                "sha256:dacca89f4bfadd5de3d7489b7c8a566eee0d3676333fbb50030263894c38c0dc"
+                "sha256:7d8c289ee437bcb0316820ccee14aefcb056e58d31830ecab8e47eda6540e136",
+                "sha256:e90e62ced43dc8105fb9a26d62f0d9340b5c8db053a814e25d95c19873ae87db"
             ],
             "index": "pypi",
-            "version": "==7.1.2"
+            "version": "==8.0.0"
         },
         "dataclasses": {
             "hashes": [
@@ -516,11 +516,11 @@
         },
         "click": {
             "hashes": [
-                "sha256:d2b5255c7c6349bc1bd1e59e08cd12acbbd63ce649f2588755783aa94dfb6b1a",
-                "sha256:dacca89f4bfadd5de3d7489b7c8a566eee0d3676333fbb50030263894c38c0dc"
+                "sha256:7d8c289ee437bcb0316820ccee14aefcb056e58d31830ecab8e47eda6540e136",
+                "sha256:e90e62ced43dc8105fb9a26d62f0d9340b5c8db053a814e25d95c19873ae87db"
             ],
             "index": "pypi",
-            "version": "==7.1.2"
+            "version": "==8.0.0"
         },
         "colorama": {
             "hashes": [
@@ -687,11 +687,11 @@
         },
         "jinja2": {
             "hashes": [
-                "sha256:03e47ad063331dd6a3f04a43eddca8a966a26ba0c5b7207a9a9e4e08f1b29419",
-                "sha256:a6d58433de0ae800347cab1fa3043cebbabe8baa9d29e668f1c768cb87a333c6"
+                "sha256:2f2de5285cf37f33d33ecd4a9080b75c87cd0c1994d5a9c6df17131ea1f049c6",
+                "sha256:ea8d7dd814ce9df6de6a761ec7f1cac98afe305b8cdc4aaae4e114b8d8ce24c5"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
-            "version": "==2.11.3"
+            "markers": "python_version >= '3.6'",
+            "version": "==3.0.0"
         },
         "keyring": {
             "hashes": [
@@ -711,61 +711,43 @@
         },
         "markupsafe": {
             "hashes": [
-                "sha256:00bc623926325b26bb9605ae9eae8a215691f33cae5df11ca5424f06f2d1f473",
-                "sha256:09027a7803a62ca78792ad89403b1b7a73a01c8cb65909cd876f7fcebd79b161",
-                "sha256:09c4b7f37d6c648cb13f9230d847adf22f8171b1ccc4d5682398e77f40309235",
-                "sha256:1027c282dad077d0bae18be6794e6b6b8c91d58ed8a8d89a89d59693b9131db5",
-                "sha256:13d3144e1e340870b25e7b10b98d779608c02016d5184cfb9927a9f10c689f42",
-                "sha256:195d7d2c4fbb0ee8139a6cf67194f3973a6b3042d742ebe0a9ed36d8b6f0c07f",
-                "sha256:22c178a091fc6630d0d045bdb5992d2dfe14e3259760e713c490da5323866c39",
-                "sha256:24982cc2533820871eba85ba648cd53d8623687ff11cbb805be4ff7b4c971aff",
-                "sha256:29872e92839765e546828bb7754a68c418d927cd064fd4708fab9fe9c8bb116b",
-                "sha256:2beec1e0de6924ea551859edb9e7679da6e4870d32cb766240ce17e0a0ba2014",
-                "sha256:3b8a6499709d29c2e2399569d96719a1b21dcd94410a586a18526b143ec8470f",
-                "sha256:43a55c2930bbc139570ac2452adf3d70cdbb3cfe5912c71cdce1c2c6bbd9c5d1",
-                "sha256:46c99d2de99945ec5cb54f23c8cd5689f6d7177305ebff350a58ce5f8de1669e",
-                "sha256:500d4957e52ddc3351cabf489e79c91c17f6e0899158447047588650b5e69183",
-                "sha256:535f6fc4d397c1563d08b88e485c3496cf5784e927af890fb3c3aac7f933ec66",
-                "sha256:596510de112c685489095da617b5bcbbac7dd6384aeebeda4df6025d0256a81b",
-                "sha256:62fe6c95e3ec8a7fad637b7f3d372c15ec1caa01ab47926cfdf7a75b40e0eac1",
-                "sha256:6788b695d50a51edb699cb55e35487e430fa21f1ed838122d722e0ff0ac5ba15",
-                "sha256:6dd73240d2af64df90aa7c4e7481e23825ea70af4b4922f8ede5b9e35f78a3b1",
-                "sha256:6f1e273a344928347c1290119b493a1f0303c52f5a5eae5f16d74f48c15d4a85",
-                "sha256:6fffc775d90dcc9aed1b89219549b329a9250d918fd0b8fa8d93d154918422e1",
-                "sha256:717ba8fe3ae9cc0006d7c451f0bb265ee07739daf76355d06366154ee68d221e",
-                "sha256:79855e1c5b8da654cf486b830bd42c06e8780cea587384cf6545b7d9ac013a0b",
-                "sha256:7c1699dfe0cf8ff607dbdcc1e9b9af1755371f92a68f706051cc8c37d447c905",
-                "sha256:7fed13866cf14bba33e7176717346713881f56d9d2bcebab207f7a036f41b850",
-                "sha256:84dee80c15f1b560d55bcfe6d47b27d070b4681c699c572af2e3c7cc90a3b8e0",
-                "sha256:88e5fcfb52ee7b911e8bb6d6aa2fd21fbecc674eadd44118a9cc3863f938e735",
-                "sha256:8defac2f2ccd6805ebf65f5eeb132adcf2ab57aa11fdf4c0dd5169a004710e7d",
-                "sha256:98bae9582248d6cf62321dcb52aaf5d9adf0bad3b40582925ef7c7f0ed85fceb",
-                "sha256:98c7086708b163d425c67c7a91bad6e466bb99d797aa64f965e9d25c12111a5e",
-                "sha256:9add70b36c5666a2ed02b43b335fe19002ee5235efd4b8a89bfcf9005bebac0d",
-                "sha256:9bf40443012702a1d2070043cb6291650a0841ece432556f784f004937f0f32c",
-                "sha256:a6a744282b7718a2a62d2ed9d993cad6f5f585605ad352c11de459f4108df0a1",
-                "sha256:acf08ac40292838b3cbbb06cfe9b2cb9ec78fce8baca31ddb87aaac2e2dc3bc2",
-                "sha256:ade5e387d2ad0d7ebf59146cc00c8044acbd863725f887353a10df825fc8ae21",
-                "sha256:b00c1de48212e4cc9603895652c5c410df699856a2853135b3967591e4beebc2",
-                "sha256:b1282f8c00509d99fef04d8ba936b156d419be841854fe901d8ae224c59f0be5",
-                "sha256:b1dba4527182c95a0db8b6060cc98ac49b9e2f5e64320e2b56e47cb2831978c7",
-                "sha256:b2051432115498d3562c084a49bba65d97cf251f5a331c64a12ee7e04dacc51b",
-                "sha256:b7d644ddb4dbd407d31ffb699f1d140bc35478da613b441c582aeb7c43838dd8",
-                "sha256:ba59edeaa2fc6114428f1637ffff42da1e311e29382d81b339c1817d37ec93c6",
-                "sha256:bf5aa3cbcfdf57fa2ee9cd1822c862ef23037f5c832ad09cfea57fa846dec193",
-                "sha256:c8716a48d94b06bb3b2524c2b77e055fb313aeb4ea620c8dd03a105574ba704f",
-                "sha256:caabedc8323f1e93231b52fc32bdcde6db817623d33e100708d9a68e1f53b26b",
-                "sha256:cd5df75523866410809ca100dc9681e301e3c27567cf498077e8551b6d20e42f",
-                "sha256:cdb132fc825c38e1aeec2c8aa9338310d29d337bebbd7baa06889d09a60a1fa2",
-                "sha256:d53bc011414228441014aa71dbec320c66468c1030aae3a6e29778a3382d96e5",
-                "sha256:d73a845f227b0bfe8a7455ee623525ee656a9e2e749e4742706d80a6065d5e2c",
-                "sha256:d9be0ba6c527163cbed5e0857c451fcd092ce83947944d6c14bc95441203f032",
-                "sha256:e249096428b3ae81b08327a63a485ad0878de3fb939049038579ac0ef61e17e7",
-                "sha256:e8313f01ba26fbbe36c7be1966a7b7424942f670f38e666995b88d012765b9be",
-                "sha256:feb7b34d6325451ef96bc0e36e1a6c0c1c64bc1fbec4b854f4529e51887b1621"
+                "sha256:007dc055dbce5b1104876acee177dbfd18757e19d562cd440182e1f492e96b95",
+                "sha256:031bf79a27d1c42f69c276d6221172417b47cb4b31cdc73d362a9bf5a1889b9f",
+                "sha256:161d575fa49395860b75da5135162481768b11208490d5a2143ae6785123e77d",
+                "sha256:24bbc3507fb6dfff663af7900a631f2aca90d5a445f272db5fc84999fa5718bc",
+                "sha256:2efaeb1baff547063bad2b2893a8f5e9c459c4624e1a96644bbba08910ae34e0",
+                "sha256:32200f562daaab472921a11cbb63780f1654552ae49518196fc361ed8e12e901",
+                "sha256:3261fae28155e5c8634dd7710635fe540a05b58f160cef7713c7700cb9980e66",
+                "sha256:3b54a9c68995ef4164567e2cd1a5e16db5dac30b2a50c39c82db8d4afaf14f63",
+                "sha256:3c352ff634e289061711608f5e474ec38dbaa21e3e168820d53d5f4015e5b91b",
+                "sha256:3fb47f97f1d338b943126e90b79cad50d4fcfa0b80637b5a9f468941dbbd9ce5",
+                "sha256:441ce2a8c17683d97e06447fcbccbdb057cbf587c78eb75ae43ea7858042fe2c",
+                "sha256:45535241baa0fc0ba2a43961a1ac7562ca3257f46c4c3e9c0de38b722be41bd1",
+                "sha256:4aca81a687975b35e3e80bcf9aa93fe10cd57fac37bf18b2314c186095f57e05",
+                "sha256:4cc563836f13c57f1473bc02d1e01fc37bab70ad4ee6be297d58c1d66bc819bf",
+                "sha256:4fae0677f712ee090721d8b17f412f1cbceefbf0dc180fe91bab3232f38b4527",
+                "sha256:58bc9fce3e1557d463ef5cee05391a05745fd95ed660f23c1742c711712c0abb",
+                "sha256:664832fb88b8162268928df233f4b12a144a0c78b01d38b81bdcf0fc96668ecb",
+                "sha256:70820a1c96311e02449591cbdf5cd1c6a34d5194d5b55094ab725364375c9eb2",
+                "sha256:79b2ae94fa991be023832e6bcc00f41dbc8e5fe9d997a02db965831402551730",
+                "sha256:83cf0228b2f694dcdba1374d5312f2277269d798e65f40344964f642935feac1",
+                "sha256:87de598edfa2230ff274c4de7fcf24c73ffd96208c8e1912d5d0fee459767d75",
+                "sha256:8f806bfd0f218477d7c46a11d3e52dc7f5fdfaa981b18202b7dc84bbc287463b",
+                "sha256:90053234a6479738fd40d155268af631c7fca33365f964f2208867da1349294b",
+                "sha256:a00dce2d96587651ef4fa192c17e039e8cfab63087c67e7d263a5533c7dad715",
+                "sha256:a08cd07d3c3c17cd33d9e66ea9dee8f8fc1c48e2d11bd88fd2dc515a602c709b",
+                "sha256:a19d39b02a24d3082856a5b06490b714a9d4179321225bbf22809ff1e1887cc8",
+                "sha256:d00a669e4a5bec3ee6dbeeeedd82a405ced19f8aeefb109a012ea88a45afff96",
+                "sha256:dab0c685f21f4a6c95bfc2afd1e7eae0033b403dd3d8c1b6d13a652ada75b348",
+                "sha256:df561f65049ed3556e5b52541669310e88713fdae2934845ec3606f283337958",
+                "sha256:e4570d16f88c7f3032ed909dc9e905a17da14a1c4cfd92608e3fda4cb1208bbd",
+                "sha256:e77e4b983e2441aff0c0d07ee711110c106b625f440292dfe02a2f60c8218bd6",
+                "sha256:e79212d09fc0e224d20b43ad44bb0a0a3416d1e04cf6b45fed265114a5d43d20",
+                "sha256:f58b5ba13a5689ca8317b98439fccfbcc673acaaf8241c1869ceea40f5d585bf",
+                "sha256:fef86115fdad7ae774720d7103aa776144cf9b66673b4afa9bcaa7af990ed07b"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==1.1.1"
+            "markers": "python_version >= '3.6'",
+            "version": "==2.0.0"
         },
         "mccabe": {
             "hashes": [
@@ -1105,6 +1087,14 @@
             "index": "pypi",
             "version": "==3.5.4"
         },
+        "sphinx-copybutton": {
+            "hashes": [
+                "sha256:0e0461df394515284e3907e3f418a0c60ef6ab6c9a27a800c8552772d0a402a2",
+                "sha256:5125c718e763596e6e52d92e15ee0d6f4800ad3817939be6dee51218870b3e3d"
+            ],
+            "index": "pypi",
+            "version": "==0.3.1"
+        },
         "sphinxcontrib-applehelp": {
             "hashes": [
                 "sha256:806111e5e962be97c29ec4c1e7fe277bfd19e9652fb1a4392105b43e01af885a",
diff --git a/docs/conf.py b/docs/conf.py
index 7162f13dd41..15adb5df7a1 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -60,6 +60,7 @@ def make_pypi_svg(version: str) -> None:
     "sphinx.ext.napoleon",
     "myst_parser",
     "sphinxcontrib.programoutput",
+    "sphinx_copybutton",
 ]
 
 # If you need extensions of a certain version or higher, list them here.
diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst
index e7a7f9fb231..7e3a90905cd 100644
--- a/docs/contributing/index.rst
+++ b/docs/contributing/index.rst
@@ -6,6 +6,7 @@ Contributing
 
   the_basics
   gauging_changes
+  issue_triage
   release_process
   reference/reference_summary
 
diff --git a/docs/contributing/issue_triage.md b/docs/contributing/issue_triage.md
new file mode 100644
index 00000000000..780b2b5e959
--- /dev/null
+++ b/docs/contributing/issue_triage.md
@@ -0,0 +1,167 @@
+# Issue triage
+
+Currently, _Black_ uses the issue tracker for bugs, feature requests, proposed design
+modifications, and general user support. Each of these issues have to be triaged so they
+can be eventually be resolved somehow. This document outlines the triaging process and
+also the current guidelines and recommendations.
+
+```{tip}
+If you're looking for a way to contribute without submitting patches, this might be
+the area for you. Since _Black_ is a popular project, its issue tracker is quite busy
+and always needs more attention than is available. While triage isn't the most
+glamorous or technically challenging form of contribution, it's still important.
+For example, we would love to know whether that old bug report is still reproducible!
+
+You can get easily started by reading over this document and then responding to issues.
+
+If you contribute enough and have stayed for a long enough time, you may even be
+given Triage permissions!
+```
+
+## The basics
+
+_Black_ gets a whole bunch of different issues, they range from bug reports to user
+support issues. To triage is to identify, organize, and kickstart the issue's journey
+through its lifecycle to resolution.
+
+More specifically, to triage an issue means to:
+
+- identify what type and categories the issue falls under
+- confirm bugs
+- ask questions / for further information if necessary
+- link related issues
+- provide the first initial feedback / support
+
+Note that triage is typically the first response to an issue, so don't fret if the issue
+doesn't make much progress after initial triage. The main goal of triaging to prepare
+the issue for future more specific development or discussion, so _eventually_ it will be
+resolved.
+
+The lifecycle of a bug report or user support issue typically goes something like this:
+
+1. _the issue is waiting for triage_
+2. **identified** - has been marked with a type label and other relevant labels, more
+   details or a functional reproduction may be still needed (and therefore should be
+   marked with `S: needs repro` or `S: awaiting reponse`)
+3. **confirmed** - the issue can reproduced and necessary details have been provided
+4. **discussion** - initial triage has been done and now the general details on how the
+   issue should be best resolved are being hashed out
+5. **awaiting fix** - no further discussion on the issue is necessary and a resolving PR
+   is the next step
+6. **closed** - the issue has been resolved, reasons include:
+   - the issue couldn't be reproduced
+   - the issue has been fixed
+   - duplicate of another pre-existing issue or is invalid
+
+For enhancement, documentation, and design issues, the lifecycle looks very similar but
+the details are different:
+
+1. _the issue is waiting for triage_
+2. **identified** - has been marked with a type label and other relevant labels
+3. **discussion** - the merits of the suggested changes are currently being discussed, a
+   PR would be acceptable but would be at sigificant risk of being rejected
+4. **accepted & awaiting PR** - it's been determined the suggested changes are OK and a
+   PR would be welcomed (`S: accepted`)
+5. **closed**: - the issue has been resolved, reasons include:
+   - the suggested changes were implemented
+   - it was rejected (due to technical concerns, ethos conflicts, etc.)
+   - duplicate of a pre-existing issue or is invalid
+
+**Note**: documentation issues don't use the `S: accepted` label currently since they're
+less likely to be rejected.
+
+## Labelling
+
+We use labels to organize, track progress, and help effectively divvy up work.
+
+Our labels are divided up into several groups identified by their prefix:
+
+- **T - Type**: the general flavor of issue / PR
+- **C - Category**: areas of concerns, ranges from bug types to project maintenance
+- **F - Formatting Area**: like C but for formatting specifically
+- **S - Status**: what stage of resolution is this issue currently in?
+- **R - Resolution**: how / why was the issue / PR resolved?
+
+We also have a few standalone labels:
+
+- **`good first issue`**: issues that are beginner-friendly (and will show up in GitHub
+  banners for first-time visitors to the repository)
+- **`help wanted`**: complex issues that need and are looking for a fair bit of work as
+  to progress (will also show up in various GitHub pages)
+- **`skip news`**: for PRs that are trivial and don't need a CHANGELOG entry (and skips
+  the CHANGELOG entry check)
+
+```{note}
+We do use labels for PRs, in particular the `skip news` label, but we aren't that
+rigorous about it. Just follow your judgement on what labels make sense for the
+specific PR (if any even make sense).
+```
+
+## Projects
+
+For more general and broad goals we use projects to track work. Some may be longterm
+projects with no true end (e.g. the "Amazing documentation" project) while others may be
+more focused and have a definite end (like the "Getting to beta" project).
+
+```{note}
+To modify GitHub Projects you need the [Write repository permission level or higher](https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/repository-permission-levels-for-an-organization#repository-access-for-each-permission-level).
+```
+
+## Closing issues
+
+Closing an issue signifies the issue has reached the end of its life, so closing issues
+should be taken with care. The following is the general recommendation for each type of
+issue. Note that these are only guidelines and if your judgement says something else
+it's totally cool to go with it instead.
+
+For most issues, closing the issue manually or automatically after a resolving PR is
+ideal. For bug reports specifically, if the bug has already been fixed, try to check in
+with the issue opener that their specific case has been resolved before closing.
+
+Design and enhancement issues should be also closed when it's clear the proposed change
+won't be implemented, whether that has been determined after a lot of discussion or just
+simply goes against _Black_'s ethos. If such an issue turns heated, closing and locking
+is acceptable if it's severe enough (although checking in with the core team is probably
+a good idea).
+
+User support issues are best closed by the author or when it's clear the issue has been
+resolved in some sort of manner.
+
+Duplicates and invalid issues should always be closed since they serve no purpose and
+add noise to an already busy issue tracker. Although be careful to make sure it's truly
+a duplicate and not just very similar before labelling and closing an issue as
+duplicate.
+
+## Common reports
+
+Some issues are frequently opened, like issues about _Black_ formatted code causing E203
+messages. Even though these issues are probably heavily duplicated, they still require
+triage sucking up valuable time from other things (although they usually skip most of
+their lifecycle since they're closed on triage).
+
+Here's some of the most common issues and also pre-made responses you can use:
+
+### "The trailing comma isn't being removed by Black!"
+
+```text
+Black used to remove the trailing comma if the expression fits in a single line, but this was changed by #826 and #1288. Now a trailing comma tells Black to always explode the expression. This change was made mostly for the cases where you _know_ a collection or whatever will grow in the future. Having it always exploded as one element per line reduces diff noise when adding elements. Before the "magic trailing comma" feature, you couldn't anticipate a collection's growth reliably since collections that fitted in one line were ruthlessly collapsed regardless of your intentions. One of Black's goals is reducing diff noise, so this was a good pragmatic change.
+
+So no, this is not a bug, but an intended feature. Anyway, [here's the documentation](https://github.com/psf/black/blob/master/docs/the_black_code_style.md#the-magic-trailing-comma) on the "magic trailing comma". Hopefully that helps and sorry for the possible confusion.
+```
+
+### "Black formatted code is violating Flake8's E203!"
+
+```text
+Hi,
+
+This is expected behaviour, please see the documentation regarding this case (emphasis
+mine):
+
+> PEP 8 recommends to treat : in slices as a binary operator with the lowest priority, and to leave an equal amount of space on either side, **except if a parameter is omitted (e.g. ham[1 + 1 :])**. It recommends no spaces around : operators for “simple expressions” (ham[lower:upper]), and **extra space for “complex expressions” (ham[lower : upper + offset])**. **Black treats anything more than variable names as “complex” (ham[lower : upper + 1]).** It also states that for extended slices, both : operators have to have the same amount of spacing, except if a parameter is omitted (ham[1 + 1 ::]). Black enforces these rules consistently.
+
+> This behaviour may raise E203 whitespace before ':' warnings in style guide enforcement tools like Flake8. **Since E203 is not PEP 8 compliant, you should tell Flake8 to ignore these warnings**.
+
+https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#slices
+
+Have a good day!
+```
diff --git a/docs/requirements.txt b/docs/requirements.txt
index c65cbe3c476..56dbf3ffe13 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,3 +1,6 @@
+# Used by ReadTheDocs; pinned requirements for stability.
+
 MyST-Parser==0.14.0
 Sphinx==3.5.4
 sphinxcontrib-programoutput==0.17
+sphinx_copybutton==0.3.1

From 9704922cf92c8f4b26a5efc6ddfdbd42064eae5f Mon Sep 17 00:00:00 2001
From: Matthew Clapp <itsayellow+dev@gmail.com>
Date: Sun, 16 May 2021 09:10:59 -0700
Subject: [PATCH 0202/1034] Update vim plugin manual installation instructions.
 (#2235)

---
 CHANGES.md                   | 1 +
 docs/integrations/editors.md | 7 +++++--
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 85936e870b1..1a38bf6649b 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -6,6 +6,7 @@
 
 - Fix typos discovered by codespell (#2228)
 - Restored compatibility with Click 8.0 on Python 3.6 when LANG=C used (#2227)
+- Fix vim plugin installation instructions. (#2235)
 
 ### _Blackd_
 
diff --git a/docs/integrations/editors.md b/docs/integrations/editors.md
index 88176e1aecb..dd09b4df6d1 100644
--- a/docs/integrations/editors.md
+++ b/docs/integrations/editors.md
@@ -146,12 +146,15 @@ $ cd ~/.vim/bundle/black
 $ git checkout origin/stable -b stable
 ```
 
-or you can copy the plugin from
-[plugin/black.vim](https://github.com/psf/black/blob/stable/plugin/black.vim).
+or you can copy the plugin files from
+[plugin/black.vim](https://github.com/psf/black/blob/stable/plugin/black.vim) and
+[autoload/black.vim](https://github.com/psf/black/blob/stable/autoload/black.vim).
 
 ```
 mkdir -p ~/.vim/pack/python/start/black/plugin
+mkdir -p ~/.vim/pack/python/start/black/autoload
 curl https://raw.githubusercontent.com/psf/black/stable/plugin/black.vim -o ~/.vim/pack/python/start/black/plugin/black.vim
+curl https://raw.githubusercontent.com/psf/black/stable/autoload/black.vim -o ~/.vim/pack/python/start/black/autoload/black.vim
 ```
 
 Let me know if this requires any changes to work with Vim 8's builtin `packadd`, or

From 60f8bd2c89fbb370e6816fd6d6e5eca64d5b9f13 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C5=81ukasz=20Langa?= <lukasz@langa.pl>
Date: Sun, 16 May 2021 18:24:28 +0200
Subject: [PATCH 0203/1034] Include Jelle's review suggestions

---
 CHANGES.md                        | 7 +++++--
 docs/contributing/issue_triage.md | 6 ++++--
 2 files changed, 9 insertions(+), 4 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 1a38bf6649b..f2c795440f8 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -4,15 +4,18 @@
 
 ### _Black_
 
-- Fix typos discovered by codespell (#2228)
 - Restored compatibility with Click 8.0 on Python 3.6 when LANG=C used (#2227)
-- Fix vim plugin installation instructions. (#2235)
 
 ### _Blackd_
 
 - Add a lower bound for the `aiohttp-cors` dependency. Only 0.4.0 or higher is
   supported. (#2231)
 
+### Documentation
+
+- Fix typos discovered by codespell (#2228)
+- Fix Vim plugin installation instructions. (#2235)
+
 ## 21.5b1
 
 ### _Black_
diff --git a/docs/contributing/issue_triage.md b/docs/contributing/issue_triage.md
index 780b2b5e959..9b987fb2425 100644
--- a/docs/contributing/issue_triage.md
+++ b/docs/contributing/issue_triage.md
@@ -116,7 +116,9 @@ it's totally cool to go with it instead.
 
 For most issues, closing the issue manually or automatically after a resolving PR is
 ideal. For bug reports specifically, if the bug has already been fixed, try to check in
-with the issue opener that their specific case has been resolved before closing.
+with the issue opener that their specific case has been resolved before closing. Note
+that we close issues as soon as they're fixed in the `main` branch. This doesn't
+necessarily mean they've been released yet.
 
 Design and enhancement issues should be also closed when it's clear the proposed change
 won't be implemented, whether that has been determined after a lot of discussion or just
@@ -146,7 +148,7 @@ Here's some of the most common issues and also pre-made responses you can use:
 ```text
 Black used to remove the trailing comma if the expression fits in a single line, but this was changed by #826 and #1288. Now a trailing comma tells Black to always explode the expression. This change was made mostly for the cases where you _know_ a collection or whatever will grow in the future. Having it always exploded as one element per line reduces diff noise when adding elements. Before the "magic trailing comma" feature, you couldn't anticipate a collection's growth reliably since collections that fitted in one line were ruthlessly collapsed regardless of your intentions. One of Black's goals is reducing diff noise, so this was a good pragmatic change.
 
-So no, this is not a bug, but an intended feature. Anyway, [here's the documentation](https://github.com/psf/black/blob/master/docs/the_black_code_style.md#the-magic-trailing-comma) on the "magic trailing comma". Hopefully that helps and sorry for the possible confusion.
+So no, this is not a bug, but an intended feature. Anyway, [here's the documentation](https://github.com/psf/black/blob/master/docs/the_black_code_style.md#the-magic-trailing-comma) on the "magic trailing comma", including the ability to skip this functionality with the `--skip-magic-trailing-comma` option. Hopefully that helps solve the possible confusion.
 ```
 
 ### "Black formatted code is violating Flake8's E203!"

From b8450b9faee10f3a0a63378b58adde60a27964e0 Mon Sep 17 00:00:00 2001
From: Hadi Alqattan <alqattanhadizaki@gmail.com>
Date: Sun, 16 May 2021 20:51:27 +0300
Subject: [PATCH 0204/1034] Fix: black only respects the root gitignore.
 (#2225)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Commit history before merge:

Black now respects .gitignore files in all levels, not only root/.gitignore file
(apply .gitignore rules like git does).

* Fix: typo
* Fix: respect .gitignore files in all levels.
* Add: CHANGELOG note.
* Fix: TypeError: unsupported operand type(s) for +: 'NoneType' and 'PathSpec'
* Update docs.
* Fix: no parent .gitignore
* Add a comment since the if expression is a bit hard to understand
* Update tests - conver no parent .gitignore case.
* Use main's Pipfile.lock instead

  The original changes in Pipfile.lock are whitespace only. The changes
  turned the JSON's file indentation from 4 to 2. Effectively this
  happened: `json.dumps(json.loads(old_pipfile_lock), indent=2) + "\n"`.

  Just using main's Pipfile.lock instead of undoing the changes because
  1) I don't know how to do that easily and quickly, and 2) there's a
  merge conflict.

  Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>

* Merge remote-tracking branch 'upstream/main' into i1730 …

  conflicts for days ay?
---
 CHANGES.md                                    |  2 ++
 .../file_collection_and_discovery.md          |  3 +-
 src/black/files.py                            |  4 ++-
 .../nested_gitignore_tests/pyproject.toml     |  3 ++
 .../nested_gitignore_tests/root/.gitignore    |  1 +
 tests/data/nested_gitignore_tests/root/a.py   |  1 +
 tests/data/nested_gitignore_tests/root/b.py   |  1 +
 tests/data/nested_gitignore_tests/root/c.py   |  1 +
 .../root/child/.gitignore                     |  1 +
 .../nested_gitignore_tests/root/child/a.py    |  1 +
 .../nested_gitignore_tests/root/child/b.py    |  1 +
 .../nested_gitignore_tests/root/child/c.py    |  1 +
 tests/data/nested_gitignore_tests/x.py        |  0
 tests/test_black.py                           | 29 ++++++++++++++++++-
 14 files changed, 45 insertions(+), 4 deletions(-)
 create mode 100644 tests/data/nested_gitignore_tests/pyproject.toml
 create mode 100644 tests/data/nested_gitignore_tests/root/.gitignore
 create mode 100644 tests/data/nested_gitignore_tests/root/a.py
 create mode 100644 tests/data/nested_gitignore_tests/root/b.py
 create mode 100644 tests/data/nested_gitignore_tests/root/c.py
 create mode 100644 tests/data/nested_gitignore_tests/root/child/.gitignore
 create mode 100644 tests/data/nested_gitignore_tests/root/child/a.py
 create mode 100644 tests/data/nested_gitignore_tests/root/child/b.py
 create mode 100644 tests/data/nested_gitignore_tests/root/child/c.py
 create mode 100644 tests/data/nested_gitignore_tests/x.py

diff --git a/CHANGES.md b/CHANGES.md
index f2c795440f8..603554cd8b7 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -4,6 +4,8 @@
 
 ### _Black_
 
+- Respect `.gitignore` files in all levels, not only `root/.gitignore` file (apply
+  `.gitignore` rules like `git` does) (#2225)
 - Restored compatibility with Click 8.0 on Python 3.6 when LANG=C used (#2227)
 
 ### _Blackd_
diff --git a/docs/usage_and_configuration/file_collection_and_discovery.md b/docs/usage_and_configuration/file_collection_and_discovery.md
index 54c76cd9a0f..1f436182dda 100644
--- a/docs/usage_and_configuration/file_collection_and_discovery.md
+++ b/docs/usage_and_configuration/file_collection_and_discovery.md
@@ -30,8 +30,7 @@ then write the above files to `.cache/black/<version>/`.
 ## .gitignore
 
 If `--exclude` is not set, _Black_ will automatically ignore files and directories in
-`.gitignore` file, if present. The `.gitignore` file must be in the project root to be
-used and nested `.gitignore` aren't supported.
+`.gitignore` file(s), if present.
 
 If you want _Black_ to continue using `.gitignore` while also configuring the exclusion
 rules, please use `--extend-exclude`.
diff --git a/src/black/files.py b/src/black/files.py
index 1be560643a1..a0c92e8c415 100644
--- a/src/black/files.py
+++ b/src/black/files.py
@@ -204,6 +204,8 @@ def gen_python_files(
             continue
 
         if child.is_dir():
+            # If gitignore is None, gitignore usage is disabled, while a Falsey
+            # gitignore is when the directory doesn't have a .gitignore file.
             yield from gen_python_files(
                 child.iterdir(),
                 root,
@@ -212,7 +214,7 @@ def gen_python_files(
                 extend_exclude,
                 force_exclude,
                 report,
-                gitignore,
+                gitignore + get_gitignore(child) if gitignore is not None else None,
             )
 
         elif child.is_file():
diff --git a/tests/data/nested_gitignore_tests/pyproject.toml b/tests/data/nested_gitignore_tests/pyproject.toml
new file mode 100644
index 00000000000..9ba7ec26980
--- /dev/null
+++ b/tests/data/nested_gitignore_tests/pyproject.toml
@@ -0,0 +1,3 @@
+[build-system]
+requires = ["setuptools>=41.0", "setuptools-scm", "wheel"]
+build-backend = "setuptools.build_meta"
diff --git a/tests/data/nested_gitignore_tests/root/.gitignore b/tests/data/nested_gitignore_tests/root/.gitignore
new file mode 100644
index 00000000000..2987e7bb646
--- /dev/null
+++ b/tests/data/nested_gitignore_tests/root/.gitignore
@@ -0,0 +1 @@
+a.py
diff --git a/tests/data/nested_gitignore_tests/root/a.py b/tests/data/nested_gitignore_tests/root/a.py
new file mode 100644
index 00000000000..7135cfd187c
--- /dev/null
+++ b/tests/data/nested_gitignore_tests/root/a.py
@@ -0,0 +1 @@
+# should be excluded (root/.gitignore)
diff --git a/tests/data/nested_gitignore_tests/root/b.py b/tests/data/nested_gitignore_tests/root/b.py
new file mode 100644
index 00000000000..bdeeca3c602
--- /dev/null
+++ b/tests/data/nested_gitignore_tests/root/b.py
@@ -0,0 +1 @@
+# should be included
diff --git a/tests/data/nested_gitignore_tests/root/c.py b/tests/data/nested_gitignore_tests/root/c.py
new file mode 100644
index 00000000000..bdeeca3c602
--- /dev/null
+++ b/tests/data/nested_gitignore_tests/root/c.py
@@ -0,0 +1 @@
+# should be included
diff --git a/tests/data/nested_gitignore_tests/root/child/.gitignore b/tests/data/nested_gitignore_tests/root/child/.gitignore
new file mode 100644
index 00000000000..6df81dd798e
--- /dev/null
+++ b/tests/data/nested_gitignore_tests/root/child/.gitignore
@@ -0,0 +1 @@
+b.py
diff --git a/tests/data/nested_gitignore_tests/root/child/a.py b/tests/data/nested_gitignore_tests/root/child/a.py
new file mode 100644
index 00000000000..7135cfd187c
--- /dev/null
+++ b/tests/data/nested_gitignore_tests/root/child/a.py
@@ -0,0 +1 @@
+# should be excluded (root/.gitignore)
diff --git a/tests/data/nested_gitignore_tests/root/child/b.py b/tests/data/nested_gitignore_tests/root/child/b.py
new file mode 100644
index 00000000000..c91d47946e6
--- /dev/null
+++ b/tests/data/nested_gitignore_tests/root/child/b.py
@@ -0,0 +1 @@
+# should be excluded (child/.gitignore)
diff --git a/tests/data/nested_gitignore_tests/root/child/c.py b/tests/data/nested_gitignore_tests/root/child/c.py
new file mode 100644
index 00000000000..bdeeca3c602
--- /dev/null
+++ b/tests/data/nested_gitignore_tests/root/child/c.py
@@ -0,0 +1 @@
+# should be included
diff --git a/tests/data/nested_gitignore_tests/x.py b/tests/data/nested_gitignore_tests/x.py
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/tests/test_black.py b/tests/test_black.py
index 5ab25cd1601..098a9ec9157 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -1406,7 +1406,7 @@ def test_include_exclude(self) -> None:
         )
         self.assertEqual(sorted(expected), sorted(sources))
 
-    def test_gitingore_used_as_default(self) -> None:
+    def test_gitignore_used_as_default(self) -> None:
         path = Path(THIS_DIR / "data" / "include_exclude_tests")
         include = re.compile(r"\.pyi?$")
         extend_exclude = re.compile(r"/exclude/")
@@ -1703,6 +1703,33 @@ def test_gitignore_exclude(self) -> None:
         )
         self.assertEqual(sorted(expected), sorted(sources))
 
+    def test_nested_gitignore(self) -> None:
+        path = Path(THIS_DIR / "data" / "nested_gitignore_tests")
+        include = re.compile(r"\.pyi?$")
+        exclude = re.compile(r"")
+        root_gitignore = black.files.get_gitignore(path)
+        report = black.Report()
+        expected: List[Path] = [
+            Path(path / "x.py"),
+            Path(path / "root/b.py"),
+            Path(path / "root/c.py"),
+            Path(path / "root/child/c.py"),
+        ]
+        this_abs = THIS_DIR.resolve()
+        sources = list(
+            black.gen_python_files(
+                path.iterdir(),
+                this_abs,
+                include,
+                exclude,
+                None,
+                None,
+                report,
+                root_gitignore,
+            )
+        )
+        self.assertEqual(sorted(expected), sorted(sources))
+
     def test_empty_include(self) -> None:
         path = THIS_DIR / "data" / "include_exclude_tests"
         report = black.Report()

From 921c24af8032416101f532e148e6a382d28e28c9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Felix=20Hild=C3=A9n?= <felix.hilden@gmail.com>
Date: Mon, 17 May 2021 21:38:43 +0300
Subject: [PATCH 0205/1034] Make Prettier preserve line ending type (#2244)

Why? The default in Prettier 2.0 was
[changed](https://prettier.io/docs/en/options.html#end-of-line) from
`auto` to `LF`. This makes development on Windows awkward, because
every file is marked with changes both by Prettier and then by Git
regardless of repository line ending settings, making committing harder
than it should be.

---

Aside from that: I noticed that runnin pre-commit manually seems to add
line endings to symlink files, but they disappear when actually committing.
Don't know if that's a known.. quirk..(?) or not.

---

Commit history before merge:

* Make Prettier preserve line ending type
* Move options to .prettierrc
---
 .pre-commit-config.yaml | 1 -
 .prettierrc.yaml        | 3 +++
 2 files changed, 3 insertions(+), 1 deletion(-)
 create mode 100644 .prettierrc.yaml

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index e461aa39c9d..2527c4d42ab 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -28,4 +28,3 @@ repos:
     rev: v2.2.1
     hooks:
       - id: prettier
-        args: [--prose-wrap=always, --print-width=88]
diff --git a/.prettierrc.yaml b/.prettierrc.yaml
new file mode 100644
index 00000000000..beda5ba4da8
--- /dev/null
+++ b/.prettierrc.yaml
@@ -0,0 +1,3 @@
+proseWrap: always
+printWidth: 88
+endOfLine: auto

From 7190d4f6c0dfcc7fce9adfffc1afc7254a01eae6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Felix=20Hild=C3=A9n?= <felix.hilden@gmail.com>
Date: Mon, 17 May 2021 21:47:34 +0300
Subject: [PATCH 0206/1034] Fix test requirements file name (#2245)

---
 docs/contributing/the_basics.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/contributing/the_basics.md b/docs/contributing/the_basics.md
index d36b17eff31..d61f3ec45b6 100644
--- a/docs/contributing/the_basics.md
+++ b/docs/contributing/the_basics.md
@@ -22,7 +22,7 @@ from the cloned _Black_ repo. It will do the correct thing.
 Non pipenv install works too:
 
 ```console
-$ pip install -r test_requirements
+$ pip install -r test_requirements.txt
 $ pip install -e .[d]
 ```
 

From 3bba8081735925ccd95d8e0ccd26c92e08e0b7a9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Felix=20Hild=C3=A9n?= <felix.hilden@gmail.com>
Date: Wed, 19 May 2021 22:11:37 +0300
Subject: [PATCH 0207/1034] Link isort profile to Black code style isort
 mention (#2246)

The isort configuration currently in the Black code style document is
duplicated in Using Black with other tools document. I think it would
be better to consolidate information and simply link to the tool guide,
mentioning the easy profile in the original document.

I changed the link from isort PyPI page to Black's docs on isort
because for users it could be better to see the Black docs on why that
configuration is necessary and what isort is from Black's perspective.
---
 docs/the_black_code_style/current_style.md | 26 +++-------------------
 1 file changed, 3 insertions(+), 23 deletions(-)

diff --git a/docs/the_black_code_style/current_style.md b/docs/the_black_code_style/current_style.md
index 7d08bc9cad5..00001dbc461 100644
--- a/docs/the_black_code_style/current_style.md
+++ b/docs/the_black_code_style/current_style.md
@@ -128,29 +128,9 @@ indentation level (like the arguments list and the docstring in the example abov
 If a data structure literal (tuple, list, set, dict) or a line of "from" imports cannot
 fit in the allotted length, it's always split into one element per line. This minimizes
 diffs as well as enables readers of code to find which commit introduced a particular
-entry. This also makes _Black_ compatible with [isort](https://pypi.org/p/isort/) with
-the following configuration.
-
-<details>
-<summary>A compatible `.isort.cfg`</summary>
-
-```cfg
-[settings]
-multi_line_output = 3
-include_trailing_comma = True
-force_grid_wrap = 0
-use_parentheses = True
-ensure_newline_before_comments = True
-line_length = 88
-```
-
-The equivalent command line is:
-
-```
-$ isort --multi-line=3 --trailing-comma --force-grid-wrap=0 --use-parentheses --line-width=88 [ file.py ]
-```
-
-</details>
+entry. This also makes _Black_ compatible with
+[isort](../guides/using_black_with_other_tools.md#isort) with the ready-made `black`
+profile or manual configuration.
 
 ### Line length
 

From 0b9b7dbdab8c14bb8c33165583e3b540046944e7 Mon Sep 17 00:00:00 2001
From: Salomon Popp <hi@salomonpopp.me>
Date: Mon, 24 May 2021 03:59:03 +0200
Subject: [PATCH 0208/1034] Build macOS releases (#2198)

* Add macOS release target
* Update ubuntu runner

Ubuntu 16.04 runner environment is deprecated
https://github.blog/changelog/2021-04-29-github-actions-ubuntu-16-04-lts-virtual-environment-will-be-removed-on-september-20-2021/
---
 .github/workflows/upload_binary.yml | 18 +++++++++++-------
 CHANGES.md                          |  4 ++++
 2 files changed, 15 insertions(+), 7 deletions(-)

diff --git a/.github/workflows/upload_binary.yml b/.github/workflows/upload_binary.yml
index 46d92ab2149..39a988752ec 100644
--- a/.github/workflows/upload_binary.yml
+++ b/.github/workflows/upload_binary.yml
@@ -11,16 +11,20 @@ jobs:
       fail-fast: false
       matrix:
         python-version: [3.7]
-        os: [ubuntu-16.04, windows-2019]
+        os: [windows-2019, ubuntu-20.04, macos-latest]
         include:
           - os: windows-2019
             pathsep: ";"
-            executable_suffix: ".exe"
+            asset_name: black_windows.exe
             executable_mime: "application/vnd.microsoft.portable-executable"
-          - os: ubuntu-16.04
+          - os: ubuntu-20.04
             pathsep: ":"
-            executable_suffix: ".elf"
+            asset_name: black_linux
             executable_mime: "application/x-executable"
+          - os: macos-latest
+            pathsep: ":"
+            asset_name: black_macos
+            executable_mime: "application/x-mach-binary"
 
     steps:
       - uses: actions/checkout@v2
@@ -38,7 +42,7 @@ jobs:
 
       - name: Build binary
         run: |
-          python -m PyInstaller -F --name black${{ matrix.executable_suffix }} --add-data 'src/blib2to3${{ matrix.pathsep }}blib2to3' src/black/__main__.py
+          python -m PyInstaller -F --name ${{ matrix.asset_name }} --add-data 'src/blib2to3${{ matrix.pathsep }}blib2to3' src/black/__main__.py
 
       - name: Upload binary as release asset
         uses: actions/upload-release-asset@v1
@@ -46,6 +50,6 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         with:
           upload_url: ${{ github.event.release.upload_url }}
-          asset_path: dist/black${{ matrix.executable_suffix }}
-          asset_name: black${{ matrix.executable_suffix }}
+          asset_path: dist/${{ matrix.asset_name }}
+          asset_name: ${{ matrix.asset_name }}
           asset_content_type: ${{ matrix.executable_mime }}
diff --git a/CHANGES.md b/CHANGES.md
index 603554cd8b7..f795c797bf5 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -13,6 +13,10 @@
 - Add a lower bound for the `aiohttp-cors` dependency. Only 0.4.0 or higher is
   supported. (#2231)
 
+### _Packaging_
+
+- Release self-contained macOS binaries as part of the GitHub release pipeline (#2198)
+
 ### Documentation
 
 - Fix typos discovered by codespell (#2228)

From 3759b856af3434e96ff48ac635928079a4a48ae7 Mon Sep 17 00:00:00 2001
From: temeddix <66480156+temeddix@users.noreply.github.com>
Date: Mon, 24 May 2021 11:19:03 +0900
Subject: [PATCH 0209/1034] Solved Problem with Non-ASCII .gitignore Files
 (#2229)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Solved Problem with non-alphabetical .gitignore files

When .gitignore file in the user's project directory contained non-alphabetical
characters(Japanese, Korean, Chinese, etc), Nothing works and printed this
weird message in the console('cp949' is the encoding for Korean characters
in this case). It even blocks VSCode's formatting from working. This commit
solves the problem.

Traceback (most recent call last):
  File "c:\users\username\anaconda3\envs\project-name\lib\runpy.py", line 193, in _run_module_as_main
    "__main__", mod_spec)
  File "c:\users\username\anaconda3\envs\project-name\lib\runpy.py", line 85, in _run_code
    exec(code, run_globals)
  File "C:\Users\username\anaconda3\envs\project-name\Scripts\black.exe\__main__.py", line 7, in <module>
  File "c:\users\username\anaconda3\envs\project-name\lib\site-packages\black\__init__.py", line 1056, in patched_main
    main()
  File "c:\users\username\anaconda3\envs\project-name\lib\site-packages\click\core.py", line 829, in __call__
    return self.main(*args, **kwargs)
  File "c:\users\username\anaconda3\envs\project-name\lib\site-packages\click\core.py", line 782, in main
    rv = self.invoke(ctx)
  File "c:\users\username\anaconda3\envs\project-name\lib\site-packages\click\core.py", line 1066, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "c:\users\username\anaconda3\envs\project-name\lib\site-packages\click\core.py", line 610, in invoke
    return callback(*args, **kwargs)
  File "c:\users\username\anaconda3\envs\project-name\lib\site-packages\click\decorators.py", line 21, in new_func
    return f(get_current_context(), *args, **kwargs)
  File "c:\users\username\anaconda3\envs\project-name\lib\site-packages\black\__init__.py", line 394, in main
    stdin_filename=stdin_filename,
  File "c:\users\username\anaconda3\envs\project-name\lib\site-packages\black\__init__.py", line 445, in get_sources
    gitignore = get_gitignore(root)
  File "c:\users\username\anaconda3\envs\project-name\lib\site-packages\black\files.py", line 122, in get_gitignore
    lines = gf.readlines()
UnicodeDecodeError: 'cp949' codec can't decode byte 0xb0 in position 13: illegal multibyte sequence

* Made .gitignore File Reader Detect Its Encoding
* Revert "Made .gitignore File Reader Detect Its Encoding"

  This reverts commit 6c3a7ea42b5b1e441cc0026c8205d1cee68c1bba.

* Revert "Solved Problem with non-alphabetical .gitignore files"

  This reverts commit b0100b5d91c2f5db544a60f34aafab120f0aa458.

* Made .gitignore Reader Open the File with Auto Encoding Detecting

  https://docs.python.org/3.8/library/tokenize.html#tokenize.open

* Revert "Made .gitignore Reader Open the File with Auto Encoding Detecting"

  This reverts commit 50dd80422938649ccc8c7f43aac752f9f6481779.

* Made .gitignore Reader Use UTF-8
* Updated CHANGES.md for #2229
* Updated CHANGES.md for #2229
* Update CHANGES.md
* Update CHANGES.md

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Co-authored-by: Łukasz Langa <lukasz@langa.pl>
Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 CHANGES.md         | 1 +
 src/black/files.py | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index f795c797bf5..34fa1a2092a 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -4,6 +4,7 @@
 
 ### _Black_
 
+- Fix handling of .gitignore files containing non-ASCII characters on Windows (#2229)
 - Respect `.gitignore` files in all levels, not only `root/.gitignore` file (apply
   `.gitignore` rules like `git` does) (#2225)
 - Restored compatibility with Click 8.0 on Python 3.6 when LANG=C used (#2227)
diff --git a/src/black/files.py b/src/black/files.py
index a0c92e8c415..de516156605 100644
--- a/src/black/files.py
+++ b/src/black/files.py
@@ -118,7 +118,7 @@ def get_gitignore(root: Path) -> PathSpec:
     gitignore = root / ".gitignore"
     lines: List[str] = []
     if gitignore.is_file():
-        with gitignore.open() as gf:
+        with gitignore.open(encoding="utf-8") as gf:
             lines = gf.readlines()
     return PathSpec.from_lines("gitwildmatch", lines)
 

From 04518c38c945ecf3c15765b71642112495cade8d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Felix=20Hild=C3=A9n?= <felix.hilden@gmail.com>
Date: Tue, 25 May 2021 23:07:05 +0300
Subject: [PATCH 0210/1034] Create FAQ documentation (GH-2247)

This commit creates a Frequently Asked Questions document for our users
to read. Hopefully they actually read it too. Items included are:
Black's non-API, AST safety, style stability, file discovery, Flake8
disagreements and Python 2 support. Hopefully I've got the answers
down in general.

Commit history before merge:

* Create FAQ
* Address feedback
* Move to single markdown file
* Minor wording improvements
* Add changelog entry
---
 CHANGES.md              |  1 +
 docs/_static/custom.css |  6 +++++
 docs/faq.md             | 52 +++++++++++++++++++++++++++++++++++++++++
 docs/index.rst          |  1 +
 4 files changed, 60 insertions(+)
 create mode 100644 docs/faq.md

diff --git a/CHANGES.md b/CHANGES.md
index 34fa1a2092a..22939e38c12 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -22,6 +22,7 @@
 
 - Fix typos discovered by codespell (#2228)
 - Fix Vim plugin installation instructions. (#2235)
+- Add new Frequently Asked Questions page (#2247)
 
 ## 21.5b1
 
diff --git a/docs/_static/custom.css b/docs/_static/custom.css
index c06c40a2dfc..eacd69c15a0 100644
--- a/docs/_static/custom.css
+++ b/docs/_static/custom.css
@@ -36,3 +36,9 @@ _:-ms-fullscreen,
     -ms-overflow-style: none;
   }
 }
+
+/* Nicer style for local document toc */
+.contents.topic {
+  background: none;
+  border: none;
+}
diff --git a/docs/faq.md b/docs/faq.md
new file mode 100644
index 00000000000..46e459883ed
--- /dev/null
+++ b/docs/faq.md
@@ -0,0 +1,52 @@
+# Frequently Asked Questions
+
+The most common questions and issues users face are aggregated to this FAQ.
+
+```{contents}
+:local:
+:backlinks: none
+```
+
+## Does Black have an API?
+
+Not yet. _Black_ is fundamentally a command line tool. Many
+[integrations](integrations/index.rst) are provided, but a Python interface is not one
+of them. A simple API is being [planned](https://github.com/psf/black/issues/779)
+though.
+
+## Is Black safe to use?
+
+Yes, for the most part. _Black_ is strictly about formatting, nothing else. But because
+_Black_ is still in [beta](index.rst), some edges are still a bit rough. To combat
+issues, the equivalence of code after formatting is
+[checked](the_black_code_style/current_style.md#ast-before-and-after-formatting) with
+limited special cases where the code is allowed to differ. If issues are found, an error
+is raised and the file is left untouched.
+
+## How stable is Black's style?
+
+Quite stable. _Black_ aims to enforce one style and one style only, with some room for
+pragmatism. However, _Black_ is still in beta so style changes are both planned and
+still proposed on the issue tracker. See
+[The Black Code Style](the_black_code_style/index.rst) for more details.
+
+## Why is my file not formatted?
+
+Most likely because it is ignored in `.gitignore` or excluded with configuration. See
+[file collection and discovery](usage_and_configuration/file_collection_and_discovery.md)
+for details.
+
+## Why are Flake8's E203 and W503 violated?
+
+Because they go against PEP 8. E203 falsely triggers on list
+[slices](the_black_code_style/current_style.md#slices), and adhering to W503 hinders
+readability because operators are misaligned. Disable W503 and enable the
+disabled-by-default counterpart W504. E203 should be disabled while changes are still
+[discussed](https://github.com/PyCQA/pycodestyle/issues/373).
+
+## Does Black support Python 2?
+
+For formatting, yes! [Install](getting_started.md#installation) with the `python2` extra
+to format Python 2 files too! There are no current plans to drop support, but most
+likely it is bound to happen. Sometime. Eventually. In terms of running _Black_ though,
+Python 3.6 or newer is required.
diff --git a/docs/index.rst b/docs/index.rst
index 2b85cddd3c0..53857995ec6 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -97,6 +97,7 @@ Contents
    usage_and_configuration/index
    integrations/index
    guides/index
+   faq
 
 .. toctree::
    :maxdepth: 3

From 92f20d7f8493f9d0f27531f68b776fb435d53d2e Mon Sep 17 00:00:00 2001
From: Mark Bell <MarkCBell@users.noreply.github.com>
Date: Tue, 25 May 2021 23:43:28 +0100
Subject: [PATCH 0211/1034] Removed adding a space into empty docstrings.
 (#2249)

Resolves #2168 by disabling the insertion of a " " when the docstring is entirely empty.

Note that this PR is focussed only on the case of empty docstrings. In particular this does not make any changes to the behaviour that a " " is inserted if a non-empty docstring begins with the quoting character. That is, black still prefers:

    """ "something" """

to:

    """"something" """

and that:

    """"Something""""

is not a legal docstring.
---
 CHANGES.md              |  1 +
 src/black/linegen.py    |  4 ++--
 tests/data/docstring.py | 16 ++++++++--------
 3 files changed, 11 insertions(+), 10 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 22939e38c12..1b7a54a516d 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -4,6 +4,7 @@
 
 ### _Black_
 
+- A space is no longer inserted into empty docstrings (#2249)
 - Fix handling of .gitignore files containing non-ASCII characters on Windows (#2229)
 - Respect `.gitignore` files in all levels, not only `root/.gitignore` file (apply
   `.gitignore` rules like `git` does) (#2225)
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 2e16b6fde44..7949654b40e 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -236,6 +236,7 @@ def visit_STRING(self, leaf: Leaf) -> Iterator[Line]:
             # characters but only if they are the same as the first.
             quote_len = 1 if docstring[1] != quote_char else 3
             docstring = docstring[quote_len:-quote_len]
+            docstring_started_empty = not docstring
 
             if is_multiline_string(leaf):
                 indent = " " * 4 * self.current_line.depth
@@ -255,8 +256,7 @@ def visit_STRING(self, leaf: Leaf) -> Iterator[Line]:
                         # Odd number of tailing backslashes, add some padding to
                         # avoid escaping the closing string quote.
                         docstring += " "
-            else:
-                # Add some padding if the docstring is empty.
+            elif not docstring_started_empty:
                 docstring = " "
 
             # We could enforce triple quotes at this point.
diff --git a/tests/data/docstring.py b/tests/data/docstring.py
index e977619e482..96bcf525b16 100644
--- a/tests/data/docstring.py
+++ b/tests/data/docstring.py
@@ -102,7 +102,7 @@ def and_this():
   "hey yah"'''
 
 
-def empty():
+def multiline_whitespace():
     '''
     
     
@@ -111,11 +111,11 @@ def empty():
     '''
 
 
-def oneline_empty():
+def oneline_whitespace():
     '''      '''
 
 
-def oneline_nothing():
+def empty():
     """"""
 
 
@@ -293,16 +293,16 @@ def and_this():
     "hey yah"'''
 
 
-def empty():
+def multiline_whitespace():
     """ """
 
 
-def oneline_empty():
+def oneline_whitespace():
     """ """
 
 
-def oneline_nothing():
-    """ """
+def empty():
+    """"""
 
 
 def single_quotes():
@@ -374,4 +374,4 @@ def my_god_its_full_of_stars_1():
 
 # the space below is actually a \u2001, removed in output
 def my_god_its_full_of_stars_2():
-    "I'm sorry Dave"
\ No newline at end of file
+    "I'm sorry Dave"

From 754eecf69eed0bdc75fe224c19a702a4f0676807 Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Wed, 26 May 2021 05:52:09 -0700
Subject: [PATCH 0212/1034] Add optional uvloop import (#2258)

* Add optional uvloop import

- If we find `uvloop` in the env for black, blackd or black-primer lets try and use it
- Add a uvloop extra install

Fixes #2257

Test:
- Add ci job to install black[uvloop] and run a primer run with uvloop
  - Only with latest python (3.9)
  - Will be handy to compare runtimes as a very unoffical benchmark

* Remove tox install

* Add to CHANGES/news
---
 .github/workflows/uvloop_test.yml | 45 +++++++++++++++++++++++++++++++
 CHANGES.md                        |  1 +
 setup.py                          |  1 +
 src/black/__init__.py             |  7 +++++
 src/black_primer/cli.py           |  8 ++++++
 src/blackd/__init__.py            |  8 ++++++
 6 files changed, 70 insertions(+)
 create mode 100644 .github/workflows/uvloop_test.yml

diff --git a/.github/workflows/uvloop_test.yml b/.github/workflows/uvloop_test.yml
new file mode 100644
index 00000000000..5d23ec64299
--- /dev/null
+++ b/.github/workflows/uvloop_test.yml
@@ -0,0 +1,45 @@
+name: test uvloop
+
+on:
+  push:
+    paths-ignore:
+      - "docs/**"
+      - "*.md"
+
+  pull_request:
+    paths-ignore:
+      - "docs/**"
+      - "*.md"
+
+jobs:
+  build:
+    # We want to run on external PRs, but not on our own internal PRs as they'll be run
+    # by the push to the branch. Without this if check, checks are duplicated since
+    # internal PRs match both the push and pull_request events.
+    if:
+      github.event_name == 'push' || github.event.pull_request.head.repo.full_name !=
+      github.repository
+
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macOS-latest]
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v2
+
+      - name: Install latest pip
+        run: |
+          python -m pip install --upgrade pip
+
+      - name: Test uvloop Extra Install
+        run: |
+          python -m pip install -e ".[uvloop]"
+
+      - name: Primer uvloop run
+        run: |
+          black-primer
diff --git a/CHANGES.md b/CHANGES.md
index 1b7a54a516d..de326e4ee7b 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -9,6 +9,7 @@
 - Respect `.gitignore` files in all levels, not only `root/.gitignore` file (apply
   `.gitignore` rules like `git` does) (#2225)
 - Restored compatibility with Click 8.0 on Python 3.6 when LANG=C used (#2227)
+- Add extra uvloop install + import support if in python env (#2258)
 
 ### _Blackd_
 
diff --git a/setup.py b/setup.py
index 2b5f71f56dd..5549ae35342 100644
--- a/setup.py
+++ b/setup.py
@@ -86,6 +86,7 @@ def get_long_description() -> str:
         "d": ["aiohttp>=3.6.0", "aiohttp-cors>=0.4.0"],
         "colorama": ["colorama>=0.4.3"],
         "python2": ["typed-ast>=1.4.2"],
+        "uvloop": ["uvloop>=0.15.2"],
     },
     test_suite="tests.test_black",
     classifiers=[
diff --git a/src/black/__init__.py b/src/black/__init__.py
index f46b866c1bd..90aad220a9c 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -54,6 +54,13 @@
 
 from _black_version import version as __version__
 
+# If our environment has uvloop installed lets use it
+try:
+    import uvloop
+
+    uvloop.install()
+except ImportError:
+    pass
 
 # types
 FileContent = str
diff --git a/src/black_primer/cli.py b/src/black_primer/cli.py
index 00b54d6511f..f0997049d21 100644
--- a/src/black_primer/cli.py
+++ b/src/black_primer/cli.py
@@ -13,6 +13,14 @@
 
 from black_primer import lib
 
+# If our environment has uvloop installed lets use it
+try:
+    import uvloop
+
+    uvloop.install()
+except ImportError:
+    pass
+
 
 DEFAULT_CONFIG = Path(__file__).parent / "primer.json"
 _timestamp = datetime.now().strftime("%Y%m%d%H%M%S")
diff --git a/src/blackd/__init__.py b/src/blackd/__init__.py
index fc684730e4b..10b616894da 100644
--- a/src/blackd/__init__.py
+++ b/src/blackd/__init__.py
@@ -22,6 +22,14 @@
 import black
 import click
 
+# If our environment has uvloop installed lets use it
+try:
+    import uvloop
+
+    uvloop.install()
+except ImportError:
+    pass
+
 from _black_version import version as __version__
 
 # This is used internally by tests to shut down the server prematurely

From 6613e76658143bcbbe363da76461e0202d589400 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Wed, 26 May 2021 22:04:10 -0400
Subject: [PATCH 0213/1034] Fix and test docs on Windows (#2262)

There's some weird interaction between Click and
sphinxcontrib-programoutput on Windows that leads to an encoding error
during the printing of black-primer's help text.

Also symlinks aren't well supported on Windows so let's just use
includes which actually work because we now use MyST :D
---
 .github/workflows/doc.yml | 11 +++++++----
 CHANGES.md                |  1 +
 docs/authors.md           |  4 +++-
 docs/change_log.md        |  4 +++-
 docs/conf.py              |  8 +++++++-
 5 files changed, 21 insertions(+), 7 deletions(-)
 mode change 120000 => 100644 docs/authors.md
 mode change 120000 => 100644 docs/change_log.md

diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml
index 04b25cf2a16..5689d2887c4 100644
--- a/.github/workflows/doc.yml
+++ b/.github/workflows/doc.yml
@@ -11,14 +11,17 @@ jobs:
       github.event_name == 'push' || github.event.pull_request.head.repo.full_name !=
       github.repository
 
-    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+
+    runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v2
 
-      - name: Set up Python 3.9
+      - name: Set up latest Python
         uses: actions/setup-python@v2
-        with:
-          python-version: 3.9
 
       - name: Install dependencies
         run: |
diff --git a/CHANGES.md b/CHANGES.md
index de326e4ee7b..0a87fd1dbf4 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -25,6 +25,7 @@
 - Fix typos discovered by codespell (#2228)
 - Fix Vim plugin installation instructions. (#2235)
 - Add new Frequently Asked Questions page (#2247)
+- Fix encoding + symlink issues preventing proper build on Windows (#2262)
 
 ## 21.5b1
 
diff --git a/docs/authors.md b/docs/authors.md
deleted file mode 120000
index 3234d6e0792..00000000000
--- a/docs/authors.md
+++ /dev/null
@@ -1 +0,0 @@
-../AUTHORS.md
\ No newline at end of file
diff --git a/docs/authors.md b/docs/authors.md
new file mode 100644
index 00000000000..21b0e1a1f5b
--- /dev/null
+++ b/docs/authors.md
@@ -0,0 +1,3 @@
+```{include} ../AUTHORS.md
+
+```
diff --git a/docs/change_log.md b/docs/change_log.md
deleted file mode 120000
index cf547089dc1..00000000000
--- a/docs/change_log.md
+++ /dev/null
@@ -1 +0,0 @@
-../CHANGES.md
\ No newline at end of file
diff --git a/docs/change_log.md b/docs/change_log.md
new file mode 100644
index 00000000000..e5f67e755d3
--- /dev/null
+++ b/docs/change_log.md
@@ -0,0 +1,3 @@
+```{include} ../CHANGES.md
+
+```
diff --git a/docs/conf.py b/docs/conf.py
index 15adb5df7a1..55d0fa99dc6 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -12,8 +12,10 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-from pathlib import Path
+
+import os
 import string
+from pathlib import Path
 
 from pkg_resources import get_distribution
 
@@ -29,6 +31,10 @@ def make_pypi_svg(version: str) -> None:
         f.write(svg)
 
 
+# Necessary so Click doesn't hit an encode error when called by
+# sphinxcontrib-programoutput on Windows.
+os.putenv("pythonioencoding", "utf-8")
+
 # -- Project information -----------------------------------------------------
 
 project = "Black"

From d3670d9c6568aef270ccda3006252ee3388cf587 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Felix=20Hild=C3=A9n?= <felix.hilden@gmail.com>
Date: Thu, 27 May 2021 16:58:06 +0300
Subject: [PATCH 0214/1034] Use latest Python in uploading binaries (#2260)

* Use latest Python in uploading binaries

* Don't pin version at all

* Add changelog entry
---
 .github/workflows/upload_binary.yml | 5 ++---
 CHANGES.md                          | 1 +
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/upload_binary.yml b/.github/workflows/upload_binary.yml
index 39a988752ec..766f37cc321 100644
--- a/.github/workflows/upload_binary.yml
+++ b/.github/workflows/upload_binary.yml
@@ -10,7 +10,6 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: [3.7]
         os: [windows-2019, ubuntu-20.04, macos-latest]
         include:
           - os: windows-2019
@@ -29,10 +28,10 @@ jobs:
     steps:
       - uses: actions/checkout@v2
 
-      - name: Set up Python ${{ matrix.python-version }}
+      - name: Set up latest Python
         uses: actions/setup-python@v2
         with:
-          python-version: ${{ matrix.python-version }}
+          python-version: "*"
 
       - name: Install dependencies
         run: |
diff --git a/CHANGES.md b/CHANGES.md
index 0a87fd1dbf4..5f570e2b8c7 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -19,6 +19,7 @@
 ### _Packaging_
 
 - Release self-contained macOS binaries as part of the GitHub release pipeline (#2198)
+- Always build binaries with the latest available Python (#2260)
 
 ### Documentation
 

From 7f138c11306cdf4be360d018528c33a3e024dd6b Mon Sep 17 00:00:00 2001
From: Matteo Bertucci <matteobertucci2004@gmail.com>
Date: Sat, 29 May 2021 15:56:46 +0200
Subject: [PATCH 0215/1034] Issue templates: use HTML comments (#2269)

This commit makes use of HTML comments inside GitHub issue templates
to make sure that even if they aren't removed by the issue author they won't be shown
in the rendered output.

The goal is to simply make the issues less noisy by removing template messages.
---
 .github/ISSUE_TEMPLATE/bug_report.md      | 31 +++++++++++++++--------
 .github/ISSUE_TEMPLATE/feature_request.md | 24 ++++++++++++------
 .github/ISSUE_TEMPLATE/style_issue.md     | 20 ++++++++++-----
 3 files changed, 51 insertions(+), 24 deletions(-)

diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
index 069795f7776..9924408b823 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -6,22 +6,31 @@ labels: bug
 assignees: ""
 ---
 
-**Describe the bug** A clear and concise description of what the bug is.
+**Describe the bug**
 
-**To Reproduce** Steps to reproduce the behavior:
+<!-- A clear and concise description of what the bug is. -->
 
+**To Reproduce**
+
+<!-- Steps to reproduce the behavior:
+
+For example:
 1. Take this file '...'
-1. Run _Black_ on it with these arguments '....'
-1. See error
+1. Run _Black_ on it with these arguments '...'
+1. See error -->
+
+**Expected behavior**
 
-**Expected behavior** A clear and concise description of what you expected to happen.
+<!-- A clear and concise description of what you expected to happen. -->
 
 **Environment (please complete the following information):**
 
-- Version: \[e.g. main\]
-- OS and Python version: \[e.g. Linux/Python 3.7.4rc1\]
+- Version: <!-- e.g. [main] -->
+- OS and Python version: <!-- e.g. [Linux/Python 3.7.4rc1] -->
 
-**Does this bug also happen on main?** To answer this, you have two options:
+**Does this bug also happen on main?**
+
+<!-- To answer this, you have two options:
 
 1. Use the online formatter at <https://black.vercel.app/?version=main>, which will use
    the latest main branch.
@@ -31,6 +40,8 @@ assignees: ""
    - run `pip install -e .[d,python2]`;
    - run `pip install -r test_requirements.txt`
    - make sure it's sane by running `python -m pytest`; and
-   - run `black` like you did last time.
+   - run `black` like you did last time. -->
+
+**Additional context**
 
-**Additional context** Add any other context about the problem here.
+<!-- Add any other context about the problem here. -->
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
index 56c2f0d0185..7c8cd1c1a07 100644
--- a/.github/ISSUE_TEMPLATE/feature_request.md
+++ b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -6,14 +6,22 @@ labels: enhancement
 assignees: ""
 ---
 
-**Is your feature request related to a problem? Please describe.** A clear and concise
-description of what the problem is. Ex. I'm always frustrated when \[...\]
+**Is your feature request related to a problem? Please describe.**
 
-**Describe the solution you'd like** A clear and concise description of what you want to
-happen.
+<!-- A clear and concise description of what the problem is.
+e.g. I'm always frustrated when [...] -->
 
-**Describe alternatives you've considered** A clear and concise description of any
-alternative solutions or features you've considered.
+**Describe the solution you'd like**
 
-**Additional context** Add any other context or screenshots about the feature request
-here.
+<!-- A clear and concise description of what you want to
+happen. -->
+
+**Describe alternatives you've considered**
+
+<!-- A clear and concise description of any
+alternative solutions or features you've considered. -->
+
+**Additional context**
+
+<!-- Add any other context or screenshots about the feature request
+here. -->
diff --git a/.github/ISSUE_TEMPLATE/style_issue.md b/.github/ISSUE_TEMPLATE/style_issue.md
index 6d1f246ed86..2ffd102712d 100644
--- a/.github/ISSUE_TEMPLATE/style_issue.md
+++ b/.github/ISSUE_TEMPLATE/style_issue.md
@@ -6,11 +6,15 @@ labels: design
 assignees: ""
 ---
 
-**Describe the style change** A clear and concise description of how the style can be
-improved.
+**Describe the style change**
 
-**Examples in the current _Black_ style** Think of some short code snippets that show
-how the current _Black_ style is not great:
+<!-- A clear and concise description of how the style can be
+improved. -->
+
+**Examples in the current _Black_ style**
+
+<!-- Think of some short code snippets that show
+how the current _Black_ style is not great: -->
 
 ```python
 def f():
@@ -18,7 +22,9 @@ def f():
     pass
 ```
 
-**Desired style** How do you think _Black_ should format the above snippets:
+**Desired style**
+
+<!-- How do you think _Black_ should format the above snippets: -->
 
 ```python
 def f(
@@ -26,4 +32,6 @@ def f(
     pass
 ```
 
-**Additional context** Add any other context about the problem here.
+**Additional context**
+
+<!-- Add any other context about the problem here. -->

From 33e2b4401439f2015065704c08d22f008f016235 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Sat, 29 May 2021 07:27:54 -0700
Subject: [PATCH 0216/1034] Add --experimental-string-processing to future
 changes (#2273)

* add esp to future style

* changelog

* fix label
---
 CHANGES.md                                 | 1 +
 docs/the_black_code_style/current_style.md | 2 ++
 docs/the_black_code_style/future_style.md  | 7 +++++++
 3 files changed, 10 insertions(+)

diff --git a/CHANGES.md b/CHANGES.md
index 5f570e2b8c7..0d595bb0d50 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -23,6 +23,7 @@
 
 ### Documentation
 
+- `--experimental-string-processing` will be enabled by default in the future (#2273)
 - Fix typos discovered by codespell (#2228)
 - Fix Vim plugin installation instructions. (#2235)
 - Add new Frequently Asked Questions page (#2247)
diff --git a/docs/the_black_code_style/current_style.md b/docs/the_black_code_style/current_style.md
index 00001dbc461..8c3a30270d1 100644
--- a/docs/the_black_code_style/current_style.md
+++ b/docs/the_black_code_style/current_style.md
@@ -250,6 +250,8 @@ If you are adopting _Black_ in a large project with pre-existing string conventi
 you can pass `--skip-string-normalization` on the command line. This is meant as an
 adoption helper, avoid using this for new projects.
 
+(labels/experimental-string)=
+
 As an experimental option (can be enabled by `--experimental-string-processing`),
 _Black_ splits long strings (using parentheses where appropriate) and merges short ones.
 When split, parts of f-strings that don't need formatting are converted to plain
diff --git a/docs/the_black_code_style/future_style.md b/docs/the_black_code_style/future_style.md
index aca9fe04017..a7676090553 100644
--- a/docs/the_black_code_style/future_style.md
+++ b/docs/the_black_code_style/future_style.md
@@ -33,3 +33,10 @@ with \
 
 Although when the target version is Python 3.9 or higher, _Black_ will use parentheses
 instead since they're allowed in Python 3.9 and higher.
+
+## Improved string processing
+
+Currently, _Black_ does not split long strings to fit the line length limit. Currently,
+there is [an experimental option](labels/experimental-string) to enable splitting
+strings. We plan to enable this option by default once it is fully stable. This is
+tracked in [this issue](https://github.com/psf/black/issues/2188).

From ab9baf0d65dedb87a853f87afc63d40276e10b3b Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Sat, 29 May 2021 09:03:08 -0700
Subject: [PATCH 0217/1034] Fix path_empty() (#2275)

Behavior other than output shouldn't depend on the verbose/quiet option. As far as I can tell this currently has no visible effect, since code after this function is called handles an empty list gracefully.
---
 src/black/__init__.py | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index 90aad220a9c..d83f0e54a72 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -506,8 +506,9 @@ def path_empty(
     """
     Exit if there is no `src` provided for formatting
     """
-    if not src and (verbose or not quiet):
-        out(msg)
+    if not src:
+        if verbose or not quiet:
+            out(msg)
         ctx.exit(0)
 
 

From 898815bc833779bd6c6f3e67710644f715b07316 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C5=81ukasz=20Langa?= <lukasz@langa.pl>
Date: Sat, 29 May 2021 18:04:45 +0200
Subject: [PATCH 0218/1034] Add @zzzeek testimonial to README and docs

---
 README.md      | 7 +++++++
 docs/index.rst | 7 +++++++
 2 files changed, 14 insertions(+)

diff --git a/README.md b/README.md
index beb8069c32b..7b4aeee8baa 100644
--- a/README.md
+++ b/README.md
@@ -141,6 +141,13 @@ Are we missing anyone? Let us know.
 
 ## Testimonials
 
+**Mike Bayer**, [author of `SQLAlchemy`](https://www.sqlalchemy.org/):
+
+> I can't think of any single tool in my entire programming career that has given me a
+> bigger productivity increase by its introduction. I can now do refactorings in about
+> 1% of the keystrokes that it would have taken me previously when we had no way for
+> code to format itself.
+
 **Dusty Phillips**,
 [writer](https://smile.amazon.com/s/ref=nb_sb_noss?url=search-alias%3Daps&field-keywords=dusty+phillips):
 
diff --git a/docs/index.rst b/docs/index.rst
index 53857995ec6..44b800cadf8 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -39,6 +39,13 @@ Try it out now using the `Black Playground <https://black.vercel.app>`_.
 Testimonials
 ------------
 
+**Mike Bayer**, author of `SQLAlchemy <https://www.sqlalchemy.org/>`_:
+
+   *I can't think of any single tool in my entire programming career that has given me a
+   bigger productivity increase by its introduction. I can now do refactorings in about
+   1% of the keystrokes that it would have taken me previously when we had no way for
+   code to format itself.*
+
 **Dusty Phillips**, `writer <https://smile.amazon.com/s/ref=nb_sb_noss?url=search-alias%3Daps&field-keywords=dusty+phillips>`_:
 
    *Black is opinionated so you don't have to be.*

From 009a17739d64b86e10cc6aac35477cadf51cdcfb Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Sat, 29 May 2021 10:15:22 -0700
Subject: [PATCH 0219/1034] ptr nolong requires changes (#2276)

- I worked on this project yesterday and must have fixed the formatting
---
 src/black_primer/primer.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/black_primer/primer.json b/src/black_primer/primer.json
index 0bbac85ca2e..034372609a1 100644
--- a/src/black_primer/primer.json
+++ b/src/black_primer/primer.json
@@ -91,7 +91,7 @@
     },
     "ptr": {
       "cli_arguments": ["--experimental-string-processing"],
-      "expect_formatting_changes": true,
+      "expect_formatting_changes": false,
       "git_clone_url": "https://github.com/facebookincubator/ptr.git",
       "long_checkout": false,
       "py_versions": ["all"]

From 519f807f879350704449e424c5c5b7e049e582b3 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Sat, 29 May 2021 10:16:33 -0700
Subject: [PATCH 0220/1034] add discussion of magic comments to FAQ (#2272)

Co-authored-by: Cooper Lees <me@cooperlees.com>
---
 CHANGES.md  |  1 +
 docs/faq.md | 11 ++++++++++-
 2 files changed, 11 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index 0d595bb0d50..d9800a6979c 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -23,6 +23,7 @@
 
 ### Documentation
 
+- Add discussion of magic comments to FAQ page (#2272)
 - `--experimental-string-processing` will be enabled by default in the future (#2273)
 - Fix typos discovered by codespell (#2228)
 - Fix Vim plugin installation instructions. (#2235)
diff --git a/docs/faq.md b/docs/faq.md
index 46e459883ed..ac5ba937c1c 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -21,7 +21,8 @@ _Black_ is still in [beta](index.rst), some edges are still a bit rough. To comb
 issues, the equivalence of code after formatting is
 [checked](the_black_code_style/current_style.md#ast-before-and-after-formatting) with
 limited special cases where the code is allowed to differ. If issues are found, an error
-is raised and the file is left untouched.
+is raised and the file is left untouched. Magical comments that influence linters and
+other tools, such as `# noqa`, may be moved by _Black_. See below for more details.
 
 ## How stable is Black's style?
 
@@ -50,3 +51,11 @@ For formatting, yes! [Install](getting_started.md#installation) with the `python
 to format Python 2 files too! There are no current plans to drop support, but most
 likely it is bound to happen. Sometime. Eventually. In terms of running _Black_ though,
 Python 3.6 or newer is required.
+
+## Why does my linter or typechecker complain after I format my code?
+
+Some linters and other tools use magical comments (e.g., `# noqa`, `# type: ignore`) to
+influence their behavior. While Black does its best to recognize such comments and leave
+them in the right place, this detection is not and cannot be perfect. Therefore, you'll
+sometimes have to manually move these comments to the right place after you format your
+codebase with _Black_.

From eec44f5977f195a10b81676525f463d0b634bd80 Mon Sep 17 00:00:00 2001
From: Bryan Bugyi <bryanbugyi34@gmail.com>
Date: Sun, 30 May 2021 15:32:28 -0400
Subject: [PATCH 0221/1034] Fix --experiemental-string-processing crash when
 matching parens not found (#2283)

Fixes #2271
---
 CHANGES.md                             |  1 +
 src/black/trans.py                     | 14 ++++++++++----
 tests/data/long_strings__regression.py | 20 ++++++++++++++++++++
 3 files changed, 31 insertions(+), 4 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index d9800a6979c..63c7a2cf30d 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -10,6 +10,7 @@
   `.gitignore` rules like `git` does) (#2225)
 - Restored compatibility with Click 8.0 on Python 3.6 when LANG=C used (#2227)
 - Add extra uvloop install + import support if in python env (#2258)
+- Fix --experimental-string-processing crash when matching parens are not found (#2283)
 
 ### _Blackd_
 
diff --git a/src/black/trans.py b/src/black/trans.py
index 7ecc31d6d31..169b675be3d 100644
--- a/src/black/trans.py
+++ b/src/black/trans.py
@@ -25,7 +25,7 @@
 from black.mode import Feature
 from black.nodes import syms, replace_child, parent_type
 from black.nodes import is_empty_par, is_empty_lpar, is_empty_rpar
-from black.nodes import CLOSING_BRACKETS, STANDALONE_COMMENT
+from black.nodes import OPENING_BRACKETS, CLOSING_BRACKETS, STANDALONE_COMMENT
 from black.lines import Line, append_leaves
 from black.brackets import BracketMatchError
 from black.comments import contains_pragma_comment
@@ -1398,6 +1398,11 @@ class StringParenWrapper(CustomSplitMapMixin, BaseStringSplitter):
     def do_splitter_match(self, line: Line) -> TMatchResult:
         LL = line.leaves
 
+        if line.leaves[-1].type in OPENING_BRACKETS:
+            return TErr(
+                "Cannot wrap parens around a line that ends in an opening bracket."
+            )
+
         string_idx = (
             self._return_match(LL)
             or self._else_match(LL)
@@ -1665,9 +1670,10 @@ def do_transform(self, line: Line, string_idx: int) -> Iterator[TResult[Line]]:
                 right_leaves.pop()
 
             if old_parens_exist:
-                assert (
-                    right_leaves and right_leaves[-1].type == token.RPAR
-                ), "Apparently, old parentheses do NOT exist?!"
+                assert right_leaves and right_leaves[-1].type == token.RPAR, (
+                    "Apparently, old parentheses do NOT exist?!"
+                    f" (left_leaves={left_leaves}, right_leaves={right_leaves})"
+                )
                 old_rpar_leaf = right_leaves.pop()
 
             append_leaves(string_line, line, right_leaves)
diff --git a/tests/data/long_strings__regression.py b/tests/data/long_strings__regression.py
index 2e7f2483b63..231d88651b6 100644
--- a/tests/data/long_strings__regression.py
+++ b/tests/data/long_strings__regression.py
@@ -396,6 +396,16 @@ def xxxxxxx_xxxxxx(xxxx):
     " it has now"
 )
 
+
+def _legacy_listen_examples():
+    text += (
+        "    \"listen for the '%(event_name)s' event\"\n"
+        "\n    # ... (event logic logic logic) ...\n"
+        % {
+            "since": since,
+        }
+    )
+
 # output
 
 
@@ -886,3 +896,13 @@ def xxxxxxx_xxxxxx(xxxx):
     " it goes over 88 characters which"
     " it has now"
 )
+
+
+def _legacy_listen_examples():
+    text += (
+        "    \"listen for the '%(event_name)s' event\"\n"
+        "\n    # ... (event logic logic logic) ...\n"
+        % {
+            "since": since,
+        }
+    )

From 4ca4407b4adc49b96c9536b16ed7d0a1e0b2deca Mon Sep 17 00:00:00 2001
From: Bryan Bugyi <bryanbugyi34@gmail.com>
Date: Sun, 30 May 2021 17:41:03 -0400
Subject: [PATCH 0222/1034] Make sure to split lines that start with a string
 operator (#2286)

Fixes #2284
---
 CHANGES.md                             |  1 +
 src/black/trans.py                     | 78 +++++++++++++++++-------
 tests/data/long_strings__regression.py | 84 ++++++++++++++++++++++++++
 3 files changed, 142 insertions(+), 21 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 63c7a2cf30d..c761d14624a 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -11,6 +11,7 @@
 - Restored compatibility with Click 8.0 on Python 3.6 when LANG=C used (#2227)
 - Add extra uvloop install + import support if in python env (#2258)
 - Fix --experimental-string-processing crash when matching parens are not found (#2283)
+- Make sure to split lines that start with a string operator (#2286)
 
 ### _Blackd_
 
diff --git a/src/black/trans.py b/src/black/trans.py
index 169b675be3d..80e88a2d2fb 100644
--- a/src/black/trans.py
+++ b/src/black/trans.py
@@ -920,9 +920,9 @@ class StringSplitter(CustomSplitMapMixin, BaseStringSplitter):
     lines by themselves).
 
     Requirements:
-        * The line consists ONLY of a single string (with the exception of a
-        '+' symbol which MAY exist at the start of the line), MAYBE a string
-        trailer, and MAYBE a trailing comma.
+        * The line consists ONLY of a single string (possibly prefixed by a
+        string operator [e.g. '+' or '==']), MAYBE a string trailer, and MAYBE
+        a trailing comma.
             AND
         * All of the requirements listed in BaseStringSplitter's docstring.
 
@@ -952,6 +952,16 @@ class StringSplitter(CustomSplitMapMixin, BaseStringSplitter):
         CustomSplit objects and add them to the custom split map.
     """
 
+    STRING_OPERATORS = [
+        token.PLUS,
+        token.STAR,
+        token.EQEQUAL,
+        token.NOTEQUAL,
+        token.LESS,
+        token.LESSEQUAL,
+        token.GREATER,
+        token.GREATEREQUAL,
+    ]
     MIN_SUBSTR_SIZE = 6
     # Matches an "f-expression" (e.g. {var}) that might be found in an f-string.
     RE_FEXPR = r"""
@@ -972,8 +982,20 @@ def do_splitter_match(self, line: Line) -> TMatchResult:
 
         idx = 0
 
-        # The first leaf MAY be a '+' symbol...
-        if is_valid_index(idx) and LL[idx].type == token.PLUS:
+        # The first two leaves MAY be the 'not in' keywords...
+        if (
+            is_valid_index(idx)
+            and is_valid_index(idx + 1)
+            and [LL[idx].type, LL[idx + 1].type] == [token.NAME, token.NAME]
+            and str(LL[idx]) + str(LL[idx + 1]) == "not in"
+        ):
+            idx += 2
+        # Else the first leaf MAY be a string operator symbol or the 'in' keyword...
+        elif is_valid_index(idx) and (
+            LL[idx].type in self.STRING_OPERATORS
+            or LL[idx].type == token.NAME
+            and str(LL[idx]) == "in"
+        ):
             idx += 1
 
         # The next/first leaf MAY be an empty LPAR...
@@ -1023,23 +1045,26 @@ def do_transform(self, line: Line, string_idx: int) -> Iterator[TResult[Line]]:
         )
 
         first_string_line = True
-        starts_with_plus = LL[0].type == token.PLUS
 
-        def line_needs_plus() -> bool:
-            return first_string_line and starts_with_plus
+        string_op_leaves = self._get_string_operator_leaves(LL)
+        string_op_leaves_length = (
+            sum([len(str(prefix_leaf)) for prefix_leaf in string_op_leaves]) + 1
+            if string_op_leaves
+            else 0
+        )
 
-        def maybe_append_plus(new_line: Line) -> None:
+        def maybe_append_string_operators(new_line: Line) -> None:
             """
             Side Effects:
-                If @line starts with a plus and this is the first line we are
-                constructing, this function appends a PLUS leaf to @new_line
-                and replaces the old PLUS leaf in the node structure. Otherwise
-                this function does nothing.
+                If @line starts with a string operator and this is the first
+                line we are constructing, this function appends the string
+                operator to @new_line and replaces the old string operator leaf
+                in the node structure. Otherwise this function does nothing.
             """
-            if line_needs_plus():
-                plus_leaf = Leaf(token.PLUS, "+")
-                replace_child(LL[0], plus_leaf)
-                new_line.append(plus_leaf)
+            maybe_prefix_leaves = string_op_leaves if first_string_line else []
+            for i, prefix_leaf in enumerate(maybe_prefix_leaves):
+                replace_child(LL[i], prefix_leaf)
+                new_line.append(prefix_leaf)
 
         ends_with_comma = (
             is_valid_index(string_idx + 1) and LL[string_idx + 1].type == token.COMMA
@@ -1054,7 +1079,7 @@ def max_last_string() -> int:
             result = self.line_length
             result -= line.depth * 4
             result -= 1 if ends_with_comma else 0
-            result -= 2 if line_needs_plus() else 0
+            result -= string_op_leaves_length
             return result
 
         # --- Calculate Max Break Index (for string value)
@@ -1103,7 +1128,7 @@ def more_splits_should_be_made() -> bool:
                 break_idx = csplit.break_idx
             else:
                 # Algorithmic Split (automatic)
-                max_bidx = max_break_idx - 2 if line_needs_plus() else max_break_idx
+                max_bidx = max_break_idx - string_op_leaves_length
                 maybe_break_idx = self._get_break_idx(rest_value, max_bidx)
                 if maybe_break_idx is None:
                     # If we are unable to algorithmically determine a good split
@@ -1148,7 +1173,7 @@ def more_splits_should_be_made() -> bool:
 
             # --- Construct `next_line`
             next_line = line.clone()
-            maybe_append_plus(next_line)
+            maybe_append_string_operators(next_line)
             next_line.append(next_leaf)
             string_line_results.append(Ok(next_line))
 
@@ -1169,7 +1194,7 @@ def more_splits_should_be_made() -> bool:
         self._maybe_normalize_string_quotes(rest_leaf)
 
         last_line = line.clone()
-        maybe_append_plus(last_line)
+        maybe_append_string_operators(last_line)
 
         # If there are any leaves to the right of the target string...
         if is_valid_index(string_idx + 1):
@@ -1345,6 +1370,17 @@ def _normalize_f_string(self, string: str, prefix: str) -> str:
         else:
             return string
 
+    def _get_string_operator_leaves(self, leaves: Iterable[Leaf]) -> List[Leaf]:
+        LL = list(leaves)
+
+        string_op_leaves = []
+        i = 0
+        while LL[i].type in self.STRING_OPERATORS + [token.NAME]:
+            prefix_leaf = Leaf(LL[i].type, str(LL[i]).strip())
+            string_op_leaves.append(prefix_leaf)
+            i += 1
+        return string_op_leaves
+
 
 class StringParenWrapper(CustomSplitMapMixin, BaseStringSplitter):
     """
diff --git a/tests/data/long_strings__regression.py b/tests/data/long_strings__regression.py
index 231d88651b6..bd7b6351321 100644
--- a/tests/data/long_strings__regression.py
+++ b/tests/data/long_strings__regression.py
@@ -406,6 +406,40 @@ def _legacy_listen_examples():
         }
     )
 
+
+assert str(suffix_arr) == (
+    "['$', 'angaroo$', 'angrykangaroo$', 'aroo$', 'garoo$', "
+    "'grykangaroo$', 'kangaroo$', 'ngaroo$', 'ngrykangaroo$', "
+    "'o$', 'oo$', 'roo$', 'rykangaroo$', 'ykangaroo$']"
+)
+assert str(suffix_arr) != (
+    "['$', 'angaroo$', 'angrykangaroo$', 'aroo$', 'garoo$', "
+    "'grykangaroo$', 'kangaroo$', 'ngaroo$', 'ngrykangaroo$', "
+    "'o$', 'oo$', 'roo$', 'rykangaroo$', 'ykangaroo$']"
+)
+assert str(suffix_arr) <= (
+    "['$', 'angaroo$', 'angrykangaroo$', 'aroo$', 'garoo$', "
+    "'grykangaroo$', 'kangaroo$', 'ngaroo$', 'ngrykangaroo$', "
+    "'o$', 'oo$', 'roo$', 'rykangaroo$', 'ykangaroo$']"
+)
+assert str(suffix_arr) >= (
+    "['$', 'angaroo$', 'angrykangaroo$', 'aroo$', 'garoo$', "
+    "'grykangaroo$', 'kangaroo$', 'ngaroo$', 'ngrykangaroo$', "
+    "'o$', 'oo$', 'roo$', 'rykangaroo$', 'ykangaroo$']"
+)
+assert str(suffix_arr) < (
+    "['$', 'angaroo$', 'angrykangaroo$', 'aroo$', 'garoo$', "
+    "'grykangaroo$', 'kangaroo$', 'ngaroo$', 'ngrykangaroo$', "
+    "'o$', 'oo$', 'roo$', 'rykangaroo$', 'ykangaroo$']"
+)
+assert str(suffix_arr) > (
+    "['$', 'angaroo$', 'angrykangaroo$', 'aroo$', 'garoo$', "
+    "'grykangaroo$', 'kangaroo$', 'ngaroo$', 'ngrykangaroo$', "
+    "'o$', 'oo$', 'roo$', 'rykangaroo$', 'ykangaroo$']"
+)
+assert str(suffix_arr) in "['$', 'angaroo$', 'angrykangaroo$', 'aroo$', 'garoo$', 'grykangaroo$', 'kangaroo$', 'ngaroo$', 'ngrykangaroo$', 'o$', 'oo$', 'roo$', 'rykangaroo$', 'ykangaroo$']"
+assert str(suffix_arr) not in "['$', 'angaroo$', 'angrykangaroo$', 'aroo$', 'garoo$', 'grykangaroo$', 'kangaroo$', 'ngaroo$', 'ngrykangaroo$', 'o$', 'oo$', 'roo$', 'rykangaroo$', 'ykangaroo$']"
+
 # output
 
 
@@ -906,3 +940,53 @@ def _legacy_listen_examples():
             "since": since,
         }
     )
+
+
+assert (
+    str(suffix_arr)
+    == "['$', 'angaroo$', 'angrykangaroo$', 'aroo$', 'garoo$', "
+    "'grykangaroo$', 'kangaroo$', 'ngaroo$', 'ngrykangaroo$', "
+    "'o$', 'oo$', 'roo$', 'rykangaroo$', 'ykangaroo$']"
+)
+assert (
+    str(suffix_arr)
+    != "['$', 'angaroo$', 'angrykangaroo$', 'aroo$', 'garoo$', "
+    "'grykangaroo$', 'kangaroo$', 'ngaroo$', 'ngrykangaroo$', "
+    "'o$', 'oo$', 'roo$', 'rykangaroo$', 'ykangaroo$']"
+)
+assert (
+    str(suffix_arr)
+    <= "['$', 'angaroo$', 'angrykangaroo$', 'aroo$', 'garoo$', "
+    "'grykangaroo$', 'kangaroo$', 'ngaroo$', 'ngrykangaroo$', "
+    "'o$', 'oo$', 'roo$', 'rykangaroo$', 'ykangaroo$']"
+)
+assert (
+    str(suffix_arr)
+    >= "['$', 'angaroo$', 'angrykangaroo$', 'aroo$', 'garoo$', "
+    "'grykangaroo$', 'kangaroo$', 'ngaroo$', 'ngrykangaroo$', "
+    "'o$', 'oo$', 'roo$', 'rykangaroo$', 'ykangaroo$']"
+)
+assert (
+    str(suffix_arr)
+    < "['$', 'angaroo$', 'angrykangaroo$', 'aroo$', 'garoo$', "
+    "'grykangaroo$', 'kangaroo$', 'ngaroo$', 'ngrykangaroo$', "
+    "'o$', 'oo$', 'roo$', 'rykangaroo$', 'ykangaroo$']"
+)
+assert (
+    str(suffix_arr)
+    > "['$', 'angaroo$', 'angrykangaroo$', 'aroo$', 'garoo$', "
+    "'grykangaroo$', 'kangaroo$', 'ngaroo$', 'ngrykangaroo$', "
+    "'o$', 'oo$', 'roo$', 'rykangaroo$', 'ykangaroo$']"
+)
+assert (
+    str(suffix_arr)
+    in "['$', 'angaroo$', 'angrykangaroo$', 'aroo$', 'garoo$', 'grykangaroo$',"
+    " 'kangaroo$', 'ngaroo$', 'ngrykangaroo$', 'o$', 'oo$', 'roo$', 'rykangaroo$',"
+    " 'ykangaroo$']"
+)
+assert (
+    str(suffix_arr)
+    not in "['$', 'angaroo$', 'angrykangaroo$', 'aroo$', 'garoo$', 'grykangaroo$',"
+    " 'kangaroo$', 'ngaroo$', 'ngrykangaroo$', 'o$', 'oo$', 'roo$',"
+    " 'rykangaroo$', 'ykangaroo$']"
+)

From 199e3eb76b74d9d2cada527403a3989287c4e8b3 Mon Sep 17 00:00:00 2001
From: Bryan Bugyi <bryanbugyi34@gmail.com>
Date: Sun, 30 May 2021 18:34:33 -0400
Subject: [PATCH 0223/1034] Fix regular expression that black uses to identify
 f-expressions (#2287)

Fixes #1469
---
 CHANGES.md                             |  1 +
 src/black/trans.py                     |  4 ++--
 tests/data/long_strings__regression.py | 12 ++++++++++++
 3 files changed, 15 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index c761d14624a..39256982215 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -12,6 +12,7 @@
 - Add extra uvloop install + import support if in python env (#2258)
 - Fix --experimental-string-processing crash when matching parens are not found (#2283)
 - Make sure to split lines that start with a string operator (#2286)
+- Fix regular expression that black uses to identify f-expressions (#2287)
 
 ### _Blackd_
 
diff --git a/src/black/trans.py b/src/black/trans.py
index 80e88a2d2fb..fd0de727620 100644
--- a/src/black/trans.py
+++ b/src/black/trans.py
@@ -971,8 +971,8 @@ class StringSplitter(CustomSplitMapMixin, BaseStringSplitter):
             | \{\{
             | \}\}
             | (?R)
-        )+?
-    (?<!\}) \} (?:\}\})* (?!\})
+        )+
+    \}
     """
 
     def do_splitter_match(self, line: Line) -> TMatchResult:
diff --git a/tests/data/long_strings__regression.py b/tests/data/long_strings__regression.py
index bd7b6351321..cd8053f9eb5 100644
--- a/tests/data/long_strings__regression.py
+++ b/tests/data/long_strings__regression.py
@@ -407,6 +407,12 @@ def _legacy_listen_examples():
     )
 
 
+temp_msg = (
+    f"{f'{humanize_number(pos)}.': <{pound_len+2}} "
+    f"{balance: <{bal_len + 5}} "
+    f"<<{author.display_name}>>\n"
+)
+
 assert str(suffix_arr) == (
     "['$', 'angaroo$', 'angrykangaroo$', 'aroo$', 'garoo$', "
     "'grykangaroo$', 'kangaroo$', 'ngaroo$', 'ngrykangaroo$', "
@@ -942,6 +948,12 @@ def _legacy_listen_examples():
     )
 
 
+temp_msg = (
+    f"{f'{humanize_number(pos)}.': <{pound_len+2}} "
+    f"{balance: <{bal_len + 5}} "
+    f"<<{author.display_name}>>\n"
+)
+
 assert (
     str(suffix_arr)
     == "['$', 'angaroo$', 'angrykangaroo$', 'aroo$', 'garoo$', "

From cf75673e1a2c993025a2113ce194d5c65f311c85 Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Mon, 31 May 2021 07:25:54 -0700
Subject: [PATCH 0224/1034] Update CHANGES.md for 21.5b2 release (#2290)

* Update CHANGES.md for 21.5b2 release
---
 CHANGES.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 39256982215..4bf08275cf8 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,6 +1,6 @@
 # Change Log
 
-## Unreleased
+## 21.5b2
 
 ### _Black_
 
@@ -21,7 +21,8 @@
 
 ### _Packaging_
 
-- Release self-contained macOS binaries as part of the GitHub release pipeline (#2198)
+- Release self-contained x86_64 MacOS binaries as part of the GitHub release pipeline
+  (#2198)
 - Always build binaries with the latest available Python (#2260)
 
 ### Documentation

From a4e35b314977baae2e930abd24fa1013c7235e39 Mon Sep 17 00:00:00 2001
From: Bryan Bugyi <bryanbugyi34@gmail.com>
Date: Mon, 31 May 2021 20:57:23 -0400
Subject: [PATCH 0225/1034] Correct max string length calculation when there
 are string operators (#2292)

PR #2286 did not fix the edge-cases (e.g. when the string is just long
enough to cause a line to be 89 characters long). This PR corrects that
mistake.
---
 CHANGES.md                            |  6 ++++++
 src/black/trans.py                    | 28 ++++++++++++++-------------
 tests/data/long_strings__edge_case.py | 19 ++++++++++++++++++
 3 files changed, 40 insertions(+), 13 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 4bf08275cf8..de67943d29f 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,5 +1,11 @@
 # Change Log
 
+## Unreleased
+
+### _Black_
+
+- Correct max string length calculation when there are string operators (#2292)
+
 ## 21.5b2
 
 ### _Black_
diff --git a/src/black/trans.py b/src/black/trans.py
index fd0de727620..bc6e93b01b4 100644
--- a/src/black/trans.py
+++ b/src/black/trans.py
@@ -738,6 +738,18 @@ class BaseStringSplitter(StringTransformer):
         * The target string is not a multiline (i.e. triple-quote) string.
     """
 
+    STRING_OPERATORS = [
+        token.EQEQUAL,
+        token.GREATER,
+        token.GREATEREQUAL,
+        token.LESS,
+        token.LESSEQUAL,
+        token.NOTEQUAL,
+        token.PERCENT,
+        token.PLUS,
+        token.STAR,
+    ]
+
     @abstractmethod
     def do_splitter_match(self, line: Line) -> TMatchResult:
         """
@@ -847,9 +859,9 @@ def _get_max_string_length(self, line: Line, string_idx: int) -> int:
                 p_idx -= 1
 
             P = LL[p_idx]
-            if P.type == token.PLUS:
-                # WMA4 a space and a '+' character (e.g. `+ STRING`).
-                offset += 2
+            if P.type in self.STRING_OPERATORS:
+                # WMA4 a space and a string operator (e.g. `+ STRING` or `== STRING`).
+                offset += len(str(P)) + 1
 
             if P.type == token.COMMA:
                 # WMA4 a space, a comma, and a closing bracket [e.g. `), STRING`].
@@ -952,16 +964,6 @@ class StringSplitter(CustomSplitMapMixin, BaseStringSplitter):
         CustomSplit objects and add them to the custom split map.
     """
 
-    STRING_OPERATORS = [
-        token.PLUS,
-        token.STAR,
-        token.EQEQUAL,
-        token.NOTEQUAL,
-        token.LESS,
-        token.LESSEQUAL,
-        token.GREATER,
-        token.GREATEREQUAL,
-    ]
     MIN_SUBSTR_SIZE = 6
     # Matches an "f-expression" (e.g. {var}) that might be found in an f-string.
     RE_FEXPR = r"""
diff --git a/tests/data/long_strings__edge_case.py b/tests/data/long_strings__edge_case.py
index 6919db5a80b..07c27537191 100644
--- a/tests/data/long_strings__edge_case.py
+++ b/tests/data/long_strings__edge_case.py
@@ -29,6 +29,9 @@
 )
 return f'{x}/b/c/d/d/d/dadfjsadjsaidoaisjdsfjaofjdfijaidfjaodfjaoifjodjafojdoajaaaaaaaaaaa'
 return f'{x}/b/c/d/d/d/dadfjsadjsaidoaisjdsfjaofjdfijaidfjaodfjaoifjodjafojdoajaaaaaaaaaaaa'
+assert str(result) == "This long string should be split at some point right close to or around hereeeeeee"
+assert str(result) < "This long string should be split at some point right close to or around hereeeeee"
+assert "A format string: %s" % "This long string should be split at some point right close to or around hereeeeeee" != result
 
 
 # output
@@ -108,3 +111,19 @@
     f"{x}/b/c/d/d/d/dadfjsadjsaidoaisjdsfjaofjdfijaidfjaodfjaoifjodjafojdoajaaaaaaaaaaa"
 )
 return f"{x}/b/c/d/d/d/dadfjsadjsaidoaisjdsfjaofjdfijaidfjaodfjaoifjodjafojdoajaaaaaaaaaaaa"
+assert (
+    str(result)
+    == "This long string should be split at some point right close to or around"
+    " hereeeeeee"
+)
+assert (
+    str(result)
+    < "This long string should be split at some point right close to or around"
+    " hereeeeee"
+)
+assert (
+    "A format string: %s"
+    % "This long string should be split at some point right close to or around"
+    " hereeeeeee"
+    != result
+)

From 4005246f86d1459e1123ac399721054182e9fef6 Mon Sep 17 00:00:00 2001
From: Stefan Foulis <stefan@foulis.ch>
Date: Tue, 1 Jun 2021 03:45:50 +0200
Subject: [PATCH 0226/1034] Add `version` to github action (and rewrite the
 whole thing while at it) (#1940)

Commit history before merge:

* Add black_version to github action
* Merge upstream/main into this branch
* Add version support for the Black action pt.2

  Since we're moving to a composite based action, quite a few changes
  were made. 1) Support was added for all OSes (Windows was painful).
  2) Isolation from the rest of the workflow had to be done manually
  with a virtual environment.

  Other noteworthy changes:

  - Rewrote basically all of the logic and put it in a Python script
    for easy testing (not doing it here tho cause I'm lazy and I can't
    think of a reasonable way of testing it).
  - Renamed `black_version` to `version` to better fit the existing
    input naming scheme.
  - Added support for log groups, this makes our action's output a
    bit more fancy (I may or may have not added some debug output too).

* Add more to and sorta rewrite the Action's docs

  Reflect compatability and gotchas.

* Add CHANGELOG entry
* Merge main into this branch
* Remove debug; address typos; clean up action.yml

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 CHANGES.md                          |  7 ++++-
 action.yml                          | 43 ++++++++++++++++++++++++++---
 action/Dockerfile                   | 10 -------
 action/entrypoint.sh                |  9 ------
 action/main.py                      | 39 ++++++++++++++++++++++++++
 docs/integrations/github_actions.md | 23 ++++++++++++---
 6 files changed, 103 insertions(+), 28 deletions(-)
 delete mode 100644 action/Dockerfile
 delete mode 100755 action/entrypoint.sh
 create mode 100644 action/main.py

diff --git a/CHANGES.md b/CHANGES.md
index de67943d29f..81a6d9f6668 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -25,7 +25,12 @@
 - Add a lower bound for the `aiohttp-cors` dependency. Only 0.4.0 or higher is
   supported. (#2231)
 
-### _Packaging_
+### Integrations
+
+- The official Black action now supports choosing what version to use, and supports the
+  major 3 OSes. (#1940)
+
+### Packaging
 
 - Release self-contained x86_64 MacOS binaries as part of the GitHub release pipeline
   (#2198)
diff --git a/action.yml b/action.yml
index 827e971801b..ddf07933a3e 100644
--- a/action.yml
+++ b/action.yml
@@ -4,21 +4,56 @@ author: "Łukasz Langa and contributors to Black"
 inputs:
   options:
     description:
-      "Options passed to black. Use `black --help` to see available options. Default:
+      "Options passed to Black. Use `black --help` to see available options. Default:
       '--check'"
     required: false
     default: "--check --diff"
   src:
-    description: "Source to run black. Default: '.'"
+    description: "Source to run Black. Default: '.'"
     required: false
     default: "."
   black_args:
     description: "[DEPRECATED] Black input arguments."
     required: false
     default: ""
+    deprecationMessage:
+      "Input `with.black_args` is deprecated. Use `with.options` and `with.src` instead."
+  version:
+    description: 'Python Version specifier (PEP440) - e.g. "21.5b1"'
+    required: false
+    default: ""
 branding:
   color: "black"
   icon: "check-circle"
 runs:
-  using: "docker"
-  image: "action/Dockerfile"
+  using: composite
+  steps:
+    - run: |
+        # Exists since using github.action_path + path to main script doesn't work because bash
+        # interprets the backslashes in github.action_path (which are used when the runner OS
+        # is Windows) destroying the path to the target file.
+        #
+        # Also semicolons are necessary because I can't get the newlines to work
+        entrypoint="import sys;
+        import subprocess;
+        from pathlib import Path;
+
+        MAIN_SCRIPT = Path(r'${{ github.action_path }}') / 'action' / 'main.py';
+
+        proc = subprocess.run([sys.executable, str(MAIN_SCRIPT)]);
+        sys.exit(proc.returncode)
+        "
+
+        if [ "$RUNNER_OS" == "Windows" ]; then
+          echo $entrypoint | python
+        else
+          echo $entrypoint | python3
+        fi
+      env:
+        # TODO: Remove once https://github.com/actions/runner/issues/665 is fixed.
+        INPUT_OPTIONS: ${{ inputs.options }}
+        INPUT_SRC: ${{ inputs.src }}
+        INPUT_BLACK_ARGS: ${{ inputs.black_args }}
+        INPUT_VERSION: ${{ inputs.version }}
+        pythonioencoding: utf-8
+      shell: bash
diff --git a/action/Dockerfile b/action/Dockerfile
deleted file mode 100644
index eb2209940db..00000000000
--- a/action/Dockerfile
+++ /dev/null
@@ -1,10 +0,0 @@
-FROM python:3
-
-ENV PYTHONDONTWRITEBYTECODE 1
-ENV PYTHONUNBUFFERED 1
-
-RUN pip install --upgrade --no-cache-dir black
-
-COPY entrypoint.sh /entrypoint.sh
-
-ENTRYPOINT ["/entrypoint.sh"]
diff --git a/action/entrypoint.sh b/action/entrypoint.sh
deleted file mode 100755
index 30bf4eb688f..00000000000
--- a/action/entrypoint.sh
+++ /dev/null
@@ -1,9 +0,0 @@
-#!/bin/bash -e
-
-if [ -n "$INPUT_BLACK_ARGS" ]; then
-  echo '::warning::Input `with.black_args` is deprecated. Use `with.options` and `with.src` instead.'
-  black $INPUT_BLACK_ARGS
-  exit $?
-fi
-
-black $INPUT_OPTIONS $INPUT_SRC
diff --git a/action/main.py b/action/main.py
new file mode 100644
index 00000000000..fde312553bf
--- /dev/null
+++ b/action/main.py
@@ -0,0 +1,39 @@
+import os
+import shlex
+import sys
+from pathlib import Path
+from subprocess import run, PIPE, STDOUT
+
+ACTION_PATH = Path(os.environ["GITHUB_ACTION_PATH"])
+ENV_PATH = ACTION_PATH / ".black-env"
+ENV_BIN = ENV_PATH / ("Scripts" if sys.platform == "win32" else "bin")
+OPTIONS = os.getenv("INPUT_OPTIONS", default="")
+SRC = os.getenv("INPUT_SRC", default="")
+BLACK_ARGS = os.getenv("INPUT_BLACK_ARGS", default="")
+VERSION = os.getenv("INPUT_VERSION", default="")
+
+run([sys.executable, "-m", "venv", str(ENV_PATH)], check=True)
+
+req = "black[colorama,python2]"
+if VERSION:
+    req += f"=={VERSION}"
+pip_proc = run(
+    [str(ENV_BIN / "python"), "-m", "pip", "install", req],
+    stdout=PIPE,
+    stderr=STDOUT,
+    encoding="utf-8",
+)
+if pip_proc.returncode:
+    print(pip_proc.stdout)
+    print("::error::Failed to install Black.", flush=True)
+    sys.exit(pip_proc.returncode)
+
+
+base_cmd = [str(ENV_BIN / "black")]
+if BLACK_ARGS:
+    # TODO: remove after a while since this is deprecated in favour of SRC + OPTIONS.
+    proc = run([*base_cmd, *shlex.split(BLACK_ARGS)])
+else:
+    proc = run([*base_cmd, *shlex.split(OPTIONS), *shlex.split(SRC)])
+
+sys.exit(proc.returncode)
diff --git a/docs/integrations/github_actions.md b/docs/integrations/github_actions.md
index 9e8cf436453..d293c40dadf 100644
--- a/docs/integrations/github_actions.md
+++ b/docs/integrations/github_actions.md
@@ -3,6 +3,14 @@
 You can use _Black_ within a GitHub Actions workflow without setting your own Python
 environment. Great for enforcing that your code matches the _Black_ code style.
 
+## Compatiblity
+
+This action is known to support all GitHub-hosted runner OSes. In addition, only
+published versions of _Black_ are supported (i.e. whatever is available on PyPI).
+
+Finally, this action installs _Black_ with both the `colorama` and `python2` extras so
+the `--color` flag and formatting Python 2 code are supported.
+
 ## Usage
 
 Create a file named `.github/workflows/black.yml` inside your repository with:
@@ -17,19 +25,26 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
       - uses: psf/black@stable
 ```
 
 We recommend the use of the `@stable` tag, but per version tags also exist if you prefer
-that.
+that. Note that the action's version you select is independent of the version of _Black_
+the action will use.
+
+The version of _Black_ the action will use can be configured via `version`. The action
+defaults to the latest release available on PyPI. Only versions available from PyPI are
+supported, so no commit SHAs or branch names.
+
+You can also configure the arguments passed to _Black_ via `options` (defaults to
+`'--check --diff'`) and `src` (default is `'.'`)
 
-You may use `options` (Default is `'--check --diff'`) and `src` (Default is `'.'`) as
-follows:
+Here's an example configuration:
 
 ```yaml
 - uses: psf/black@stable
   with:
     options: "--check --verbose"
     src: "./src"
+    version: "21.5b1"
 ```

From fdc4b67433906c2b8beeb349366a69befc37aafe Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Tue, 1 Jun 2021 15:08:17 -0700
Subject: [PATCH 0227/1034] Bump urllib3 from 1.26.4 to 1.26.5 (#2298)

Bumps [urllib3](https://github.com/urllib3/urllib3) from 1.26.4 to 1.26.5.
- [Release notes](https://github.com/urllib3/urllib3/releases)
- [Changelog](https://github.com/urllib3/urllib3/blob/main/CHANGES.rst)
- [Commits](https://github.com/urllib3/urllib3/compare/1.26.4...1.26.5)

---
updated-dependencies:
- dependency-name: urllib3
  dependency-type: indirect
...

Signed-off-by: dependabot[bot] <support@github.com>

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 Pipfile.lock | 230 +++++++++++++++++++++------------------------------
 1 file changed, 92 insertions(+), 138 deletions(-)

diff --git a/Pipfile.lock b/Pipfile.lock
index b6dfe438e9e..4f0b51e7d18 100644
--- a/Pipfile.lock
+++ b/Pipfile.lock
@@ -78,7 +78,6 @@
                 "sha256:0c3c816a028d47f659d6ff5c745cb2acf1f966da1fe5c19c77a70282b25f4c5f",
                 "sha256:4291ca197d287d274d0b6cb5d6f8f8f82d434ed288f962539ff18cc9012f9ea3"
             ],
-            "markers": "python_full_version >= '3.5.3'",
             "version": "==3.0.1"
         },
         "attrs": {
@@ -86,7 +85,6 @@
                 "sha256:149e90d6d8ac20db7a955ad60cf0e6881a3f20d37096140088356da6c716b0b1",
                 "sha256:ef6aaac3ca6cd92904cdd0d83f629a15f18053ec84e6432106f7a4d04ae4f5fb"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
             "version": "==21.2.0"
         },
         "black": {
@@ -101,7 +99,6 @@
                 "sha256:0d6f53a15db4120f2b08c94f11e7d93d2c911ee118b6b30a04ec3ee8310179fa",
                 "sha256:f864054d66fd9118f2e67044ac8981a54775ec5b67aed0441892edb553d21da5"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
             "version": "==4.0.0"
         },
         "click": {
@@ -118,17 +115,14 @@
                 "sha256:6988bd2b895eef432d562370bb707d540f32f7360ab13da45340101bc2307d84"
             ],
             "index": "pypi",
-            "python_version <": "3.7",
-            "version": "==0.6",
-            "version >": "0.6"
+            "version": "==0.6"
         },
         "idna": {
             "hashes": [
-                "sha256:5205d03e7bcbb919cc9c19885f9920d622ca52448306f2377daede5cf3faac16",
-                "sha256:c5b02147e01ea9920e6b0a3f1f7bb833612d507592c837a6c49552768f4054e1"
+                "sha256:14475042e284991034cb48e06f6851428fb14c4dc953acd9be9a5e95c7b6dd7a",
+                "sha256:467fbad99067910785144ce333826c71fb0e63a425657295239737f7ecd125f3"
             ],
-            "markers": "python_version >= '3.4'",
-            "version": "==3.1"
+            "version": "==3.2"
         },
         "multidict": {
             "hashes": [
@@ -170,7 +164,6 @@
                 "sha256:f21756997ad8ef815d8ef3d34edd98804ab5ea337feedcd62fb52d22bf531281",
                 "sha256:fc13a9524bc18b6fb6e0dbec3533ba0496bbed167c56d0aabefd965584557d80"
             ],
-            "markers": "python_version >= '3.6'",
             "version": "==5.1.0"
         },
         "mypy-extensions": {
@@ -236,14 +229,6 @@
             "index": "pypi",
             "version": "==2021.4.4"
         },
-        "setuptools-scm": {
-            "hashes": [
-                "sha256:c3bd5f701c8def44a5c0bfe8d407bef3f80342217ef3492b951f3777bd2d915c",
-                "sha256:d1925a69cb07e9b29416a275b9fadb009a23c148ace905b2fb220649a6c18e92"
-            ],
-            "markers": "python_version >= '3.6'",
-            "version": "==6.0.1"
-        },
         "toml": {
             "hashes": [
                 "sha256:806143ae5bfb6a3c6e736a764057db0e6a0e05e338b5630894a5f779cabb4f9b",
@@ -295,9 +280,7 @@
                 "sha256:779383f6086d90c99ae41cf0ff39aac8a7937a9283ce0a414e5dd782f4c94a84"
             ],
             "index": "pypi",
-            "python_version <": "3.8",
-            "version": "==3.10.0.0",
-            "version >=": "3.7.4"
+            "version": "==3.10.0.0"
         },
         "yarl": {
             "hashes": [
@@ -339,7 +322,6 @@
                 "sha256:f0b059678fd549c66b89bed03efcabb009075bd131c248ecdf087bdb6faba24a",
                 "sha256:fcbb48a93e8699eae920f8d92f7160c03567b421bc17362a9ffbbd706a816f71"
             ],
-            "markers": "python_version >= '3.6'",
             "version": "==1.6.3"
         }
     },
@@ -415,7 +397,6 @@
                 "sha256:0c3c816a028d47f659d6ff5c745cb2acf1f966da1fe5c19c77a70282b25f4c5f",
                 "sha256:4291ca197d287d274d0b6cb5d6f8f8f82d434ed288f962539ff18cc9012f9ea3"
             ],
-            "markers": "python_full_version >= '3.5.3'",
             "version": "==3.0.1"
         },
         "attrs": {
@@ -423,7 +404,6 @@
                 "sha256:149e90d6d8ac20db7a955ad60cf0e6881a3f20d37096140088356da6c716b0b1",
                 "sha256:ef6aaac3ca6cd92904cdd0d83f629a15f18053ec84e6432106f7a4d04ae4f5fb"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
             "version": "==21.2.0"
         },
         "babel": {
@@ -431,7 +411,6 @@
                 "sha256:ab49e12b91d937cd11f0b67cb259a57ab4ad2b59ac7a3b41d6c06c0ac5b0def9",
                 "sha256:bc0c176f9f6a994582230df350aa6e05ba2ebe4b3ac317eab29d9be5d2768da0"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==2.9.1"
         },
         "black": {
@@ -446,27 +425,35 @@
                 "sha256:6123ddc1052673e52bab52cdc955bcb57a015264a1c57d37bea2f6b817af0125",
                 "sha256:98b3170739e5e83dd9dc19633f074727ad848cbedb6026708c8ac2d3b697a433"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
             "version": "==3.3.0"
         },
         "certifi": {
             "hashes": [
-                "sha256:1a4995114262bffbc2413b159f2a1a480c969de6e6eb13ee966d470af86af59c",
-                "sha256:719a74fb9e33b9bd44cc7f3a8d94bc35e4049deebe19ba7d8e108280cfd59830"
+                "sha256:2bbf76fd432960138b3ef6dda3dde0544f27cbf8546c458e60baf371917ba9ee",
+                "sha256:50b1e4f8446b06f41be7dd6338db18e0990601dce795c2b1686458aa7e8fa7d8"
             ],
-            "version": "==2020.12.5"
+            "version": "==2021.5.30"
         },
         "cffi": {
             "hashes": [
                 "sha256:005a36f41773e148deac64b08f233873a4d0c18b053d37da83f6af4d9087b813",
+                "sha256:04c468b622ed31d408fea2346bec5bbffba2cc44226302a0de1ade9f5ea3d373",
+                "sha256:06d7cd1abac2ffd92e65c0609661866709b4b2d82dd15f611e602b9b188b0b69",
+                "sha256:06db6321b7a68b2bd6df96d08a5adadc1fa0e8f419226e25b2a5fbf6ccc7350f",
                 "sha256:0857f0ae312d855239a55c81ef453ee8fd24136eaba8e87a2eceba644c0d4c06",
+                "sha256:0f861a89e0043afec2a51fd177a567005847973be86f709bbb044d7f42fc4e05",
                 "sha256:1071534bbbf8cbb31b498d5d9db0f274f2f7a865adca4ae429e147ba40f73dea",
                 "sha256:158d0d15119b4b7ff6b926536763dc0714313aa59e320ddf787502c70c4d4bee",
+                "sha256:1bf1ac1984eaa7675ca8d5745a8cb87ef7abecb5592178406e55858d411eadc0",
                 "sha256:1f436816fc868b098b0d63b8920de7d208c90a67212546d02f84fe78a9c26396",
+                "sha256:24a570cd11895b60829e941f2613a4f79df1a27344cbbb82164ef2e0116f09c7",
+                "sha256:24ec4ff2c5c0c8f9c6b87d5bb53555bf267e1e6f70e52e5a9740d32861d36b6f",
                 "sha256:2894f2df484ff56d717bead0a5c2abb6b9d2bf26d6960c4604d5c48bbc30ee73",
                 "sha256:29314480e958fd8aab22e4a58b355b629c59bf5f2ac2492b61e3dc06d8c7a315",
+                "sha256:293e7ea41280cb28c6fcaaa0b1aa1f533b8ce060b9e701d78511e1e6c4a1de76",
                 "sha256:34eff4b97f3d982fb93e2831e6750127d1355a923ebaeeb565407b3d2f8d41a1",
                 "sha256:35f27e6eb43380fa080dccf676dece30bef72e4a67617ffda586641cd4508d49",
+                "sha256:3c3f39fa737542161d8b0d680df2ec249334cd70a8f420f71c9304bd83c3cbed",
                 "sha256:3d3dd4c9e559eb172ecf00a2a7517e97d1e96de2a5e610bd9b68cea3925b4892",
                 "sha256:43e0b9d9e2c9e5d152946b9c5fe062c151614b262fda2e7b201204de0b99e482",
                 "sha256:48e1c69bbacfc3d932221851b39d49e81567a4d4aac3b21258d9c24578280058",
@@ -474,6 +461,7 @@
                 "sha256:58e3f59d583d413809d60779492342801d6e82fefb89c86a38e040c16883be53",
                 "sha256:5de7970188bb46b7bf9858eb6890aad302577a5f6f75091fd7cdd3ef13ef3045",
                 "sha256:65fa59693c62cf06e45ddbb822165394a288edce9e276647f0046e1ec26920f3",
+                "sha256:681d07b0d1e3c462dd15585ef5e33cb021321588bebd910124ef4f4fb71aef55",
                 "sha256:69e395c24fc60aad6bb4fa7e583698ea6cc684648e1ffb7fe85e3c1ca131a7d5",
                 "sha256:6c97d7350133666fbb5cf4abdc1178c812cb205dc6f41d174a7b0f18fb93337e",
                 "sha256:6e4714cc64f474e4d6e37cfff31a814b509a35cb17de4fb1999907575684479c",
@@ -491,8 +479,10 @@
                 "sha256:b85eb46a81787c50650f2392b9b4ef23e1f126313b9e0e9013b35c15e4288e2e",
                 "sha256:bb89f306e5da99f4d922728ddcd6f7fcebb3241fc40edebcb7284d7514741991",
                 "sha256:cbde590d4faaa07c72bf979734738f328d239913ba3e043b1e98fe9a39f8b2b6",
+                "sha256:cc5a8e069b9ebfa22e26d0e6b97d6f9781302fe7f4f2b8776c3e1daea35f1adc",
                 "sha256:cd2868886d547469123fadc46eac7ea5253ea7fcb139f12e1dfc2bbd406427d1",
                 "sha256:d42b11d692e11b6634f7613ad8df5d6d5f8875f5d48939520d351007b3c13406",
+                "sha256:df5052c5d867c1ea0b311fb7c3cd28b19df469c056f7fdcfe88c7473aa63e333",
                 "sha256:f2d45f97ab6bb54753eab54fffe75aaf3de4ff2341c9daee1987ee1837636f1d",
                 "sha256:fd78e5fee591709f32ef6edb9a015b4aa1a5022598e36227500c8f4e02328d9c"
             ],
@@ -500,18 +490,16 @@
         },
         "cfgv": {
             "hashes": [
-                "sha256:32e43d604bbe7896fe7c248a9c2276447dbef840feb28fe20494f62af110211d",
-                "sha256:cf22deb93d4bcf92f345a5c3cd39d3d41d6340adc60c78bbbd6588c384fda6a1"
+                "sha256:9e600479b3b99e8af981ecdfc80a0296104ee610cab48a5ae4ffd0b668650eb1",
+                "sha256:b449c9c6118fe8cca7fa5e00b9ec60ba08145d281d52164230a69211c5d597a1"
             ],
-            "markers": "python_full_version >= '3.6.1'",
-            "version": "==3.2.0"
+            "version": "==3.3.0"
         },
         "chardet": {
             "hashes": [
                 "sha256:0d6f53a15db4120f2b08c94f11e7d93d2c911ee118b6b30a04ec3ee8310179fa",
                 "sha256:f864054d66fd9118f2e67044ac8981a54775ec5b67aed0441892edb553d21da5"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
             "version": "==4.0.0"
         },
         "click": {
@@ -527,7 +515,6 @@
                 "sha256:5941b2b48a20143d2267e95b1c2a7603ce057ee39fd88e7329b0c292aa16869b",
                 "sha256:9f47eda37229f68eee03b24b9748937c7dc3868f906e8ba69fbcbdd3bc5dc3e2"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
             "version": "==0.4.4"
         },
         "coverage": {
@@ -603,20 +590,18 @@
                 "sha256:eb8cc2afe8b05acbd84a43905832ec78e7b3873fb124ca190f574dca7389a87d",
                 "sha256:ee77aa129f481be46f8d92a1a7db57269a2f23052d5f2433b4621bb457081cc9"
             ],
-            "markers": "python_version >= '3.6'",
             "version": "==3.4.7"
         },
         "distlib": {
             "hashes": [
-                "sha256:8c09de2c67b3e7deef7184574fc060ab8a793e7adbb183d942c389c8b13c52fb",
-                "sha256:edf6116872c863e1aa9d5bb7cb5e05a022c519a4594dc703843343a9ddd9bff1"
+                "sha256:106fef6dc37dd8c0e2c0a60d3fca3e77460a48907f335fa28420463a6f799736",
+                "sha256:23e223426b28491b1ced97dc3bbe183027419dfc7982b4fa2f05d5f3ff10711c"
             ],
-            "version": "==0.3.1"
+            "version": "==0.3.2"
         },
         "docutils": {
             "hashes": [
                 "sha256:54a349c622ff31c91cbec43b0b512f113b5b24daf00e2ea530bb1bd9aac14849",
-                "sha256:ba4584f9107571ced0d2c7f56a5499c696215ba90797849c92d395979da68521",
                 "sha256:d2ddba74835cb090a1b627d3de4e7835c628d07ee461f7b4480f51af2fe4d448"
             ],
             "index": "pypi",
@@ -647,35 +632,31 @@
         },
         "identify": {
             "hashes": [
-                "sha256:9bcc312d4e2fa96c7abebcdfb1119563b511b5e3985ac52f60d9116277865b2e",
-                "sha256:ad9f3fa0c2316618dc4d840f627d474ab6de106392a4f00221820200f490f5a8"
+                "sha256:92d6ad08eca19ceb17576733759944b94c0761277ddc3acf65e75e57ef190e32",
+                "sha256:c29e74c3671fe9537715cb695148231d777170ca1498e1c30c675d4ea782afe9"
             ],
-            "markers": "python_full_version >= '3.6.1'",
-            "version": "==2.2.4"
+            "version": "==2.2.7"
         },
         "idna": {
             "hashes": [
-                "sha256:5205d03e7bcbb919cc9c19885f9920d622ca52448306f2377daede5cf3faac16",
-                "sha256:c5b02147e01ea9920e6b0a3f1f7bb833612d507592c837a6c49552768f4054e1"
+                "sha256:14475042e284991034cb48e06f6851428fb14c4dc953acd9be9a5e95c7b6dd7a",
+                "sha256:467fbad99067910785144ce333826c71fb0e63a425657295239737f7ecd125f3"
             ],
-            "markers": "python_version >= '3.4'",
-            "version": "==3.1"
+            "version": "==3.2"
         },
         "imagesize": {
             "hashes": [
                 "sha256:6965f19a6a2039c7d48bca7dba2473069ff854c36ae6f19d2cde309d998228a1",
                 "sha256:b1f6b5a4eab1f73479a50fb79fcf729514a900c341d8503d62a62dbc4127a2b1"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==1.2.0"
         },
         "importlib-metadata": {
             "hashes": [
-                "sha256:8c501196e49fb9df5df43833bdb1e4328f64847763ec8a50703148b73784d581",
-                "sha256:d7eb1dea6d6a6086f8be21784cc9e3bcfa55872b52309bc5fad53a8ea444465d"
+                "sha256:960d52ba7c21377c990412aca380bf3642d734c2eaab78a2c39319f67c6a5786",
+                "sha256:e592faad8de1bda9fe920cf41e15261e7131bcf266c30306eec00e8e225c1dd5"
             ],
-            "markers": "python_version >= '3.6'",
-            "version": "==4.0.1"
+            "version": "==4.4.0"
         },
         "jeepney": {
             "hashes": [
@@ -687,18 +668,16 @@
         },
         "jinja2": {
             "hashes": [
-                "sha256:2f2de5285cf37f33d33ecd4a9080b75c87cd0c1994d5a9c6df17131ea1f049c6",
-                "sha256:ea8d7dd814ce9df6de6a761ec7f1cac98afe305b8cdc4aaae4e114b8d8ce24c5"
+                "sha256:1f06f2da51e7b56b8f238affdd6b4e2c61e39598a378cc49345bc1bd42a978a4",
+                "sha256:703f484b47a6af502e743c9122595cc812b0271f661722403114f71a79d0f5a4"
             ],
-            "markers": "python_version >= '3.6'",
-            "version": "==3.0.0"
+            "version": "==3.0.1"
         },
         "keyring": {
             "hashes": [
                 "sha256:045703609dd3fccfcdb27da201684278823b72af515aedec1a8515719a038cb8",
                 "sha256:8f607d7d1cc502c43a932a275a56fe47db50271904513a379d39df1af277ac48"
             ],
-            "markers": "python_version >= '3.6'",
             "version": "==23.0.1"
         },
         "markdown-it-py": {
@@ -706,48 +685,46 @@
                 "sha256:36be6bb3ad987bfdb839f5ba78ddf094552ca38ccbd784ae4f74a4e1419fc6e3",
                 "sha256:98080fc0bc34c4f2bcf0846a096a9429acbd9d5d8e67ed34026c03c61c464389"
             ],
-            "markers": "python_version ~= '3.6'",
             "version": "==1.1.0"
         },
         "markupsafe": {
             "hashes": [
-                "sha256:007dc055dbce5b1104876acee177dbfd18757e19d562cd440182e1f492e96b95",
-                "sha256:031bf79a27d1c42f69c276d6221172417b47cb4b31cdc73d362a9bf5a1889b9f",
-                "sha256:161d575fa49395860b75da5135162481768b11208490d5a2143ae6785123e77d",
-                "sha256:24bbc3507fb6dfff663af7900a631f2aca90d5a445f272db5fc84999fa5718bc",
-                "sha256:2efaeb1baff547063bad2b2893a8f5e9c459c4624e1a96644bbba08910ae34e0",
-                "sha256:32200f562daaab472921a11cbb63780f1654552ae49518196fc361ed8e12e901",
-                "sha256:3261fae28155e5c8634dd7710635fe540a05b58f160cef7713c7700cb9980e66",
-                "sha256:3b54a9c68995ef4164567e2cd1a5e16db5dac30b2a50c39c82db8d4afaf14f63",
-                "sha256:3c352ff634e289061711608f5e474ec38dbaa21e3e168820d53d5f4015e5b91b",
-                "sha256:3fb47f97f1d338b943126e90b79cad50d4fcfa0b80637b5a9f468941dbbd9ce5",
-                "sha256:441ce2a8c17683d97e06447fcbccbdb057cbf587c78eb75ae43ea7858042fe2c",
-                "sha256:45535241baa0fc0ba2a43961a1ac7562ca3257f46c4c3e9c0de38b722be41bd1",
-                "sha256:4aca81a687975b35e3e80bcf9aa93fe10cd57fac37bf18b2314c186095f57e05",
-                "sha256:4cc563836f13c57f1473bc02d1e01fc37bab70ad4ee6be297d58c1d66bc819bf",
-                "sha256:4fae0677f712ee090721d8b17f412f1cbceefbf0dc180fe91bab3232f38b4527",
-                "sha256:58bc9fce3e1557d463ef5cee05391a05745fd95ed660f23c1742c711712c0abb",
-                "sha256:664832fb88b8162268928df233f4b12a144a0c78b01d38b81bdcf0fc96668ecb",
-                "sha256:70820a1c96311e02449591cbdf5cd1c6a34d5194d5b55094ab725364375c9eb2",
-                "sha256:79b2ae94fa991be023832e6bcc00f41dbc8e5fe9d997a02db965831402551730",
-                "sha256:83cf0228b2f694dcdba1374d5312f2277269d798e65f40344964f642935feac1",
-                "sha256:87de598edfa2230ff274c4de7fcf24c73ffd96208c8e1912d5d0fee459767d75",
-                "sha256:8f806bfd0f218477d7c46a11d3e52dc7f5fdfaa981b18202b7dc84bbc287463b",
-                "sha256:90053234a6479738fd40d155268af631c7fca33365f964f2208867da1349294b",
-                "sha256:a00dce2d96587651ef4fa192c17e039e8cfab63087c67e7d263a5533c7dad715",
-                "sha256:a08cd07d3c3c17cd33d9e66ea9dee8f8fc1c48e2d11bd88fd2dc515a602c709b",
-                "sha256:a19d39b02a24d3082856a5b06490b714a9d4179321225bbf22809ff1e1887cc8",
-                "sha256:d00a669e4a5bec3ee6dbeeeedd82a405ced19f8aeefb109a012ea88a45afff96",
-                "sha256:dab0c685f21f4a6c95bfc2afd1e7eae0033b403dd3d8c1b6d13a652ada75b348",
-                "sha256:df561f65049ed3556e5b52541669310e88713fdae2934845ec3606f283337958",
-                "sha256:e4570d16f88c7f3032ed909dc9e905a17da14a1c4cfd92608e3fda4cb1208bbd",
-                "sha256:e77e4b983e2441aff0c0d07ee711110c106b625f440292dfe02a2f60c8218bd6",
-                "sha256:e79212d09fc0e224d20b43ad44bb0a0a3416d1e04cf6b45fed265114a5d43d20",
-                "sha256:f58b5ba13a5689ca8317b98439fccfbcc673acaaf8241c1869ceea40f5d585bf",
-                "sha256:fef86115fdad7ae774720d7103aa776144cf9b66673b4afa9bcaa7af990ed07b"
-            ],
-            "markers": "python_version >= '3.6'",
-            "version": "==2.0.0"
+                "sha256:01a9b8ea66f1658938f65b93a85ebe8bc016e6769611be228d797c9d998dd298",
+                "sha256:023cb26ec21ece8dc3907c0e8320058b2e0cb3c55cf9564da612bc325bed5e64",
+                "sha256:0446679737af14f45767963a1a9ef7620189912317d095f2d9ffa183a4d25d2b",
+                "sha256:0717a7390a68be14b8c793ba258e075c6f4ca819f15edfc2a3a027c823718567",
+                "sha256:0955295dd5eec6cb6cc2fe1698f4c6d84af2e92de33fbcac4111913cd100a6ff",
+                "sha256:10f82115e21dc0dfec9ab5c0223652f7197feb168c940f3ef61563fc2d6beb74",
+                "sha256:1d609f577dc6e1aa17d746f8bd3c31aa4d258f4070d61b2aa5c4166c1539de35",
+                "sha256:2ef54abee730b502252bcdf31b10dacb0a416229b72c18b19e24a4509f273d26",
+                "sha256:3c112550557578c26af18a1ccc9e090bfe03832ae994343cfdacd287db6a6ae7",
+                "sha256:47ab1e7b91c098ab893b828deafa1203de86d0bc6ab587b160f78fe6c4011f75",
+                "sha256:49e3ceeabbfb9d66c3aef5af3a60cc43b85c33df25ce03d0031a608b0a8b2e3f",
+                "sha256:4efca8f86c54b22348a5467704e3fec767b2db12fc39c6d963168ab1d3fc9135",
+                "sha256:53edb4da6925ad13c07b6d26c2a852bd81e364f95301c66e930ab2aef5b5ddd8",
+                "sha256:594c67807fb16238b30c44bdf74f36c02cdf22d1c8cda91ef8a0ed8dabf5620a",
+                "sha256:611d1ad9a4288cf3e3c16014564df047fe08410e628f89805e475368bd304914",
+                "sha256:6557b31b5e2c9ddf0de32a691f2312a32f77cd7681d8af66c2692efdbef84c18",
+                "sha256:693ce3f9e70a6cf7d2fb9e6c9d8b204b6b39897a2c4a1aa65728d5ac97dcc1d8",
+                "sha256:6a7fae0dd14cf60ad5ff42baa2e95727c3d81ded453457771d02b7d2b3f9c0c2",
+                "sha256:6c4ca60fa24e85fe25b912b01e62cb969d69a23a5d5867682dd3e80b5b02581d",
+                "sha256:7d91275b0245b1da4d4cfa07e0faedd5b0812efc15b702576d103293e252af1b",
+                "sha256:905fec760bd2fa1388bb5b489ee8ee5f7291d692638ea5f67982d968366bef9f",
+                "sha256:97383d78eb34da7e1fa37dd273c20ad4320929af65d156e35a5e2d89566d9dfb",
+                "sha256:984d76483eb32f1bcb536dc27e4ad56bba4baa70be32fa87152832cdd9db0833",
+                "sha256:a30e67a65b53ea0a5e62fe23682cfe22712e01f453b95233b25502f7c61cb415",
+                "sha256:ab3ef638ace319fa26553db0624c4699e31a28bb2a835c5faca8f8acf6a5a902",
+                "sha256:b2f4bf27480f5e5e8ce285a8c8fd176c0b03e93dcc6646477d4630e83440c6a9",
+                "sha256:b7f2d075102dc8c794cbde1947378051c4e5180d52d276987b8d28a3bd58c17d",
+                "sha256:be98f628055368795d818ebf93da628541e10b75b41c559fdf36d104c5787066",
+                "sha256:d7f9850398e85aba693bb640262d3611788b1f29a79f0c93c565694658f4071f",
+                "sha256:f5653a225f31e113b152e56f154ccbe59eeb1c7487b39b9d9f9cdb58e6c79dc5",
+                "sha256:f826e31d18b516f653fe296d967d700fddad5901ae07c622bb3705955e1faa94",
+                "sha256:f8ba0e8349a38d3001fae7eadded3f6606f0da5d748ee53cc1dab1d6527b9509",
+                "sha256:f9081981fe268bd86831e5c75f7de206ef275defcb82bc70740ae6dc507aee51",
+                "sha256:fa130dd50c57d53368c9d59395cb5526eda596d3ffe36666cd81a44d56e48872"
+            ],
+            "version": "==2.0.1"
         },
         "mccabe": {
             "hashes": [
@@ -761,7 +738,6 @@
                 "sha256:1833bf738e038e35d89cb3a07eb0d227ed647ce7dd357579b65343740c6d249c",
                 "sha256:5991cef645502e80a5388ec4fc20885d2313d4871e8b8e320ca2de14ac0c015f"
             ],
-            "markers": "python_version ~= '3.6'",
             "version": "==0.2.8"
         },
         "multidict": {
@@ -804,7 +780,6 @@
                 "sha256:f21756997ad8ef815d8ef3d34edd98804ab5ea337feedcd62fb52d22bf531281",
                 "sha256:fc13a9524bc18b6fb6e0dbec3533ba0496bbed167c56d0aabefd965584557d80"
             ],
-            "markers": "python_version >= '3.6'",
             "version": "==5.1.0"
         },
         "mypy": {
@@ -863,7 +838,6 @@
                 "sha256:5b327ac1320dc863dca72f4514ecc086f31186744b84a230374cc1fd776feae5",
                 "sha256:67714da7f7bc052e064859c05c595155bd1ee9f69f76557e21f051443c20947a"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==20.9"
         },
         "pathspec": {
@@ -894,7 +868,6 @@
                 "sha256:514f76d918fcc0b55c6680472f0a37970994e07bbb80725808c17089be302068",
                 "sha256:c389c1d06bf7904078ca03399a4816f974a1d590090fecea0c63ec26ebaf1cef"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==2.7.0"
         },
         "pycparser": {
@@ -902,7 +875,6 @@
                 "sha256:2d475327684562c3a96cc71adf7dc8c4f0565175cf86b6d7a404ff4c771f15f0",
                 "sha256:7582ad22678f0fcd81102833f60ef8d0e57288b6b5fb00323d101be910e35705"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==2.20"
         },
         "pyflakes": {
@@ -910,7 +882,6 @@
                 "sha256:7893783d01b8a89811dd72d7dfd4d84ff098e5eed95cfa8905b22bbffe52efc3",
                 "sha256:f5bc8ecabc05bb9d291eb5203d6810b49040f6ff446a756326104746cc00c1db"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==2.3.1"
         },
         "pygments": {
@@ -918,7 +889,6 @@
                 "sha256:a18f47b506a429f6f4b9df81bb02beab9ca21d0a5fee38ed15aef65f0545519f",
                 "sha256:d66e804411278594d764fc69ec36ec13d9ae9147193a1740cd34d272ca383b8e"
             ],
-            "markers": "python_version >= '3.5'",
             "version": "==2.9.0"
         },
         "pyparsing": {
@@ -926,7 +896,6 @@
                 "sha256:c203ec8783bf771a155b207279b9bccb8dea02d8f0c9e5f8ead507bc3246ecc1",
                 "sha256:ef9d7589ef3c200abe66653d3f1ab1033c3c419ae9b9bdb1240a85b024efc88b"
             ],
-            "markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==2.4.7"
         },
         "pytz": {
@@ -968,7 +937,6 @@
                 "sha256:fdc842473cd33f45ff6bce46aea678a54e3d21f1b61a7750ce3c498eedfe25d6",
                 "sha256:fe69978f3f768926cfa37b867e3843918e012cf83f680806599ddce33c2c68b0"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4, 3.5'",
             "version": "==5.4.1"
         },
         "readme-renderer": {
@@ -1031,7 +999,6 @@
                 "sha256:27973dd4a904a4f13b263a19c866c13b92a39ed1c964655f025f3f8d3d75b804",
                 "sha256:c210084e36a42ae6b9219e00e48287def368a26d03a048ddad7bfee44f75871e"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
             "version": "==2.25.1"
         },
         "requests-toolbelt": {
@@ -1061,7 +1028,7 @@
                 "sha256:c3bd5f701c8def44a5c0bfe8d407bef3f80342217ef3492b951f3777bd2d915c",
                 "sha256:d1925a69cb07e9b29416a275b9fadb009a23c148ace905b2fb220649a6c18e92"
             ],
-            "markers": "python_version >= '3.6'",
+            "index": "pypi",
             "version": "==6.0.1"
         },
         "six": {
@@ -1069,7 +1036,6 @@
                 "sha256:1e61c37477a1626458e36f7b1d82aa5c9b094fa4802892072e49de9c60c4c926",
                 "sha256:8abb2f1d86890a2dfb989f9a77cfcfd3e47c2a354b01111771326f8aa26e0254"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==1.16.0"
         },
         "snowballstemmer": {
@@ -1100,7 +1066,6 @@
                 "sha256:806111e5e962be97c29ec4c1e7fe277bfd19e9652fb1a4392105b43e01af885a",
                 "sha256:a072735ec80e7675e3f432fcae8610ecf509c5f1869d17e2eecff44389cdbc58"
             ],
-            "markers": "python_version >= '3.5'",
             "version": "==1.0.2"
         },
         "sphinxcontrib-devhelp": {
@@ -1108,23 +1073,20 @@
                 "sha256:8165223f9a335cc1af7ffe1ed31d2871f325254c0423bc0c4c7cd1c1e4734a2e",
                 "sha256:ff7f1afa7b9642e7060379360a67e9c41e8f3121f2ce9164266f61b9f4b338e4"
             ],
-            "markers": "python_version >= '3.5'",
             "version": "==1.0.2"
         },
         "sphinxcontrib-htmlhelp": {
             "hashes": [
-                "sha256:3c0bc24a2c41e340ac37c85ced6dafc879ab485c095b1d65d2461ac2f7cca86f",
-                "sha256:e8f5bb7e31b2dbb25b9cc435c8ab7a79787ebf7f906155729338f3156d93659b"
+                "sha256:d412243dfb797ae3ec2b59eca0e52dac12e75a241bf0e4eb861e450d06c6ed07",
+                "sha256:f5f8bb2d0d629f398bf47d0d69c07bc13b65f75a81ad9e2f71a63d4b7a2f6db2"
             ],
-            "markers": "python_version >= '3.5'",
-            "version": "==1.0.3"
+            "version": "==2.0.0"
         },
         "sphinxcontrib-jsmath": {
             "hashes": [
                 "sha256:2ec2eaebfb78f3f2078e73666b1415417a116cc848b72e5172e596c871103178",
                 "sha256:a9925e4a4587247ed2191a22df5f6970656cb8ca2bd6284309578f2153e0c4b8"
             ],
-            "markers": "python_version >= '3.5'",
             "version": "==1.0.1"
         },
         "sphinxcontrib-programoutput": {
@@ -1140,16 +1102,14 @@
                 "sha256:4c33767ee058b70dba89a6fc5c1892c0d57a54be67ddd3e7875a18d14cba5a72",
                 "sha256:bd9fc24bcb748a8d51fd4ecaade681350aa63009a347a8c14e637895444dfab6"
             ],
-            "markers": "python_version >= '3.5'",
             "version": "==1.0.3"
         },
         "sphinxcontrib-serializinghtml": {
             "hashes": [
-                "sha256:eaa0eccc86e982a9b939b2b82d12cc5d013385ba5eadcc7e4fed23f4405f77bc",
-                "sha256:f242a81d423f59617a8e5cf16f5d4d74e28ee9a66f9e5b637a18082991db5a9a"
+                "sha256:352a9a00ae864471d3a7ead8d7d79f5fc0b57e8b3f95e9867eb9eb28999b92fd",
+                "sha256:aa5f6de5dfdf809ef505c4895e51ef5c9eac17d0f287933eb49ec495280b6952"
             ],
-            "markers": "python_version >= '3.5'",
-            "version": "==1.1.4"
+            "version": "==1.1.5"
         },
         "toml": {
             "hashes": [
@@ -1161,11 +1121,10 @@
         },
         "tqdm": {
             "hashes": [
-                "sha256:daec693491c52e9498632dfbe9ccfc4882a557f5fa08982db1b4d3adbe0887c3",
-                "sha256:ebdebdb95e3477ceea267decfc0784859aa3df3e27e22d23b83e9b272bf157ae"
+                "sha256:736524215c690621b06fc89d0310a49822d75e599fcd0feb7cc742b98d692493",
+                "sha256:cd5791b5d7c3f2f1819efc81d36eb719a38e0906a7380365c556779f585ea042"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==4.60.0"
+            "version": "==4.61.0"
         },
         "twine": {
             "hashes": [
@@ -1218,25 +1177,22 @@
                 "sha256:779383f6086d90c99ae41cf0ff39aac8a7937a9283ce0a414e5dd782f4c94a84"
             ],
             "index": "pypi",
-            "python_version <": "3.8",
-            "version": "==3.10.0.0",
-            "version >=": "3.7.4"
+            "version": "==3.10.0.0"
         },
         "urllib3": {
             "hashes": [
-                "sha256:2f4da4594db7e1e110a944bb1b551fdf4e6c136ad42e4234131391e21eb5b0df",
-                "sha256:e7b021f7241115872f92f43c6508082facffbd1c048e3c6e2bb9c2a157e28937"
+                "sha256:753a0374df26658f99d826cfe40394a686d05985786d946fbe4165b5148f5a7c",
+                "sha256:a7acd0977125325f516bda9735fa7142b909a8d01e8b2e4c8108d0984e6e0098"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4' and python_version < '4'",
-            "version": "==1.26.4"
+            "index": "pypi",
+            "version": "==1.26.5"
         },
         "virtualenv": {
             "hashes": [
-                "sha256:307a555cf21e1550885c82120eccaf5acedf42978fd362d32ba8410f9593f543",
-                "sha256:72cf267afc04bf9c86ec932329b7e94db6a0331ae9847576daaa7ca3c86b29a4"
+                "sha256:14fdf849f80dbb29a4eb6caa9875d476ee2a5cf76a5f5415fa2f1606010ab467",
+                "sha256:2b0126166ea7c9c3661f5b8e06773d28f83322de7a3ff7d06f0aed18c9de6a76"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==20.4.6"
+            "version": "==20.4.7"
         },
         "webencodings": {
             "hashes": [
@@ -1293,7 +1249,6 @@
                 "sha256:f0b059678fd549c66b89bed03efcabb009075bd131c248ecdf087bdb6faba24a",
                 "sha256:fcbb48a93e8699eae920f8d92f7160c03567b421bc17362a9ffbbd706a816f71"
             ],
-            "markers": "python_version >= '3.6'",
             "version": "==1.6.3"
         },
         "zipp": {
@@ -1301,7 +1256,6 @@
                 "sha256:3607921face881ba3e026887d8150cca609d517579abe052ac81fc5aeffdbd76",
                 "sha256:51cb66cc54621609dd593d1787f286ee42a5c0adbb4b29abea5a63edc3e03098"
             ],
-            "markers": "python_version >= '3.6'",
             "version": "==3.4.1"
         }
     }

From 7567cdf3b4f32d4fb12bd5ca0da838f7ff252cfc Mon Sep 17 00:00:00 2001
From: Hassan Abouelela <abouelelahassan@gmail.com>
Date: Wed, 2 Jun 2021 04:55:21 +0300
Subject: [PATCH 0228/1034] Code Flag Options (#2259)

Properly handles the diff, color, and fast option when black is run with
 the `--code` option.

Closes #2104, closes #1801.
---
 AUTHORS.md                                 |   1 +
 CHANGES.md                                 |   2 +
 docs/usage_and_configuration/the_basics.md |   7 -
 src/black/__init__.py                      | 119 ++++++++++++-----
 src/black/files.py                         |   2 +-
 tests/test_black.py                        | 144 +++++++++++++++++++++
 6 files changed, 233 insertions(+), 42 deletions(-)

diff --git a/AUTHORS.md b/AUTHORS.md
index cb79dec3de3..8d112ea6795 100644
--- a/AUTHORS.md
+++ b/AUTHORS.md
@@ -68,6 +68,7 @@ Multiple contributions by:
 - Gustavo Camargo
 - hauntsaninja
 - [Hadi Alqattan](mailto:alqattanhadizaki@gmail.com)
+- [Hassan Abouelela](mailto:hassan@hassanamr.com)
 - [Heaford](mailto:dan@heaford.com)
 - [Hugo Barrera](mailto::hugo@barrera.io)
 - Hugo van Kemenade
diff --git a/CHANGES.md b/CHANGES.md
index 81a6d9f6668..e7851637836 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -15,6 +15,7 @@
 - Respect `.gitignore` files in all levels, not only `root/.gitignore` file (apply
   `.gitignore` rules like `git` does) (#2225)
 - Restored compatibility with Click 8.0 on Python 3.6 when LANG=C used (#2227)
+- Fixed option usage when using the `--code` flag (#2259)
 - Add extra uvloop install + import support if in python env (#2258)
 - Fix --experimental-string-processing crash when matching parens are not found (#2283)
 - Make sure to split lines that start with a string operator (#2286)
@@ -43,6 +44,7 @@
 - Fix typos discovered by codespell (#2228)
 - Fix Vim plugin installation instructions. (#2235)
 - Add new Frequently Asked Questions page (#2247)
+- Removed safety checks warning for the `--code` option (#2259)
 - Fix encoding + symlink issues preventing proper build on Windows (#2262)
 
 ## 21.5b1
diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index 0b2cd3b3544..c5e17e5a521 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -68,13 +68,6 @@ $ black --code "print ( 'hello, world' )"
 print("hello, world")
 ```
 
-```{warning}
---check, --diff, and --safe / --fast have no effect when using -c / --code. Safety
-checks normally turned on by default that verify _Black_'s output are disabled as well.
-This is a bug which we intend to fix eventually. More details can be found in this [bug
-report](https://github.com/psf/black/issues/2104).
-```
-
 ### Writeback and reporting
 
 By default _Black_ reformats the files given and/or found in place. Sometimes you need
diff --git a/src/black/__init__.py b/src/black/__init__.py
index d83f0e54a72..1d0ad7d5ddd 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -384,47 +384,61 @@ def main(
     )
     if config and verbose:
         out(f"Using configuration from {config}.", bold=False, fg="blue")
+
     if code is not None:
-        print(format_str(code, mode=mode))
-        ctx.exit(0)
-    report = Report(check=check, diff=diff, quiet=quiet, verbose=verbose)
-    sources = get_sources(
-        ctx=ctx,
-        src=src,
-        quiet=quiet,
-        verbose=verbose,
-        include=include,
-        exclude=exclude,
-        extend_exclude=extend_exclude,
-        force_exclude=force_exclude,
-        report=report,
-        stdin_filename=stdin_filename,
-    )
+        # Run in quiet mode by default with -c; the extra output isn't useful.
+        # You can still pass -v to get verbose output.
+        quiet = True
 
-    path_empty(
-        sources,
-        "No Python files are present to be formatted. Nothing to do 😴",
-        quiet,
-        verbose,
-        ctx,
-    )
+    report = Report(check=check, diff=diff, quiet=quiet, verbose=verbose)
 
-    if len(sources) == 1:
-        reformat_one(
-            src=sources.pop(),
-            fast=fast,
-            write_back=write_back,
-            mode=mode,
-            report=report,
+    if code is not None:
+        reformat_code(
+            content=code, fast=fast, write_back=write_back, mode=mode, report=report
         )
     else:
-        reformat_many(
-            sources=sources, fast=fast, write_back=write_back, mode=mode, report=report
+        sources = get_sources(
+            ctx=ctx,
+            src=src,
+            quiet=quiet,
+            verbose=verbose,
+            include=include,
+            exclude=exclude,
+            extend_exclude=extend_exclude,
+            force_exclude=force_exclude,
+            report=report,
+            stdin_filename=stdin_filename,
         )
 
+        path_empty(
+            sources,
+            "No Python files are present to be formatted. Nothing to do 😴",
+            quiet,
+            verbose,
+            ctx,
+        )
+
+        if len(sources) == 1:
+            reformat_one(
+                src=sources.pop(),
+                fast=fast,
+                write_back=write_back,
+                mode=mode,
+                report=report,
+            )
+        else:
+            reformat_many(
+                sources=sources,
+                fast=fast,
+                write_back=write_back,
+                mode=mode,
+                report=report,
+            )
+
     if verbose or not quiet:
         out("Oh no! 💥 💔 💥" if report.return_code else "All done! ✨ 🍰 ✨")
-        click.secho(str(report), err=True)
+        if code is None:
+            click.secho(str(report), err=True)
     ctx.exit(report.return_code)
 
 
@@ -512,6 +526,30 @@ def path_empty(
         ctx.exit(0)
 
 
+def reformat_code(
+    content: str, fast: bool, write_back: WriteBack, mode: Mode, report: Report
+) -> None:
+    """
+    Reformat and print out `content` without spawning child processes.
+    Similar to `reformat_one`, but for string content.
+
+    `fast`, `write_back`, and `mode` options are passed to
+    :func:`format_file_in_place` or :func:`format_stdin_to_stdout`.
+    """
+    path = Path("<string>")
+    try:
+        changed = Changed.NO
+        if format_stdin_to_stdout(
+            content=content, fast=fast, write_back=write_back, mode=mode
+        ):
+            changed = Changed.YES
+        report.done(path, changed)
+    except Exception as exc:
+        if report.verbose:
+            traceback.print_exc()
+        report.failed(path, str(exc))
+
+
 def reformat_one(
     src: Path, fast: bool, write_back: WriteBack, mode: Mode, report: "Report"
 ) -> None:
@@ -720,16 +758,27 @@ def format_file_in_place(
 
 
 def format_stdin_to_stdout(
-    fast: bool, *, write_back: WriteBack = WriteBack.NO, mode: Mode
+    fast: bool,
+    *,
+    content: Optional[str] = None,
+    write_back: WriteBack = WriteBack.NO,
+    mode: Mode,
 ) -> bool:
     """Format file on stdin. Return True if changed.
 
+    If content is None, it's read from sys.stdin.
+
     If `write_back` is YES, write reformatted code back to stdout. If it is DIFF,
     write a diff to stdout. The `mode` argument is passed to
     :func:`format_file_contents`.
     """
     then = datetime.utcnow()
-    src, encoding, newline = decode_bytes(sys.stdin.buffer.read())
+
+    if content is None:
+        src, encoding, newline = decode_bytes(sys.stdin.buffer.read())
+    else:
+        src, encoding, newline = content, "utf-8", ""
+
     dst = src
     try:
         dst = format_file_contents(src, fast=fast, mode=mode)
@@ -743,6 +792,8 @@ def format_stdin_to_stdout(
             sys.stdout.buffer, encoding=encoding, newline=newline, write_through=True
         )
         if write_back == WriteBack.YES:
+            # Make sure there's a newline after the content
+            dst += "" if dst[-1] == "\n" else "\n"
             f.write(dst)
         elif write_back in (WriteBack.DIFF, WriteBack.COLOR_DIFF):
             now = datetime.utcnow()
diff --git a/src/black/files.py b/src/black/files.py
index de516156605..b9cefd317e0 100644
--- a/src/black/files.py
+++ b/src/black/files.py
@@ -38,7 +38,7 @@ def find_project_root(srcs: Sequence[str]) -> Path:
     project root, the root of the file system is returned.
     """
     if not srcs:
-        return Path("/").resolve()
+        srcs = [str(Path.cwd().resolve())]
 
     path_srcs = [Path(Path.cwd(), src).resolve() for src in srcs]
 
diff --git a/tests/test_black.py b/tests/test_black.py
index 098a9ec9157..f0a14aa2da4 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -34,6 +34,7 @@
 from black import Feature, TargetVersion
 from black.cache import get_cache_file
 from black.debug import DebugVisitor
+from black.output import diff, color_diff
 from black.report import Report
 import black.files
 
@@ -63,6 +64,9 @@
 T = TypeVar("T")
 R = TypeVar("R")
 
+# Match the time output in a diff, but nothing else
+DIFF_TIME = re.compile(r"\t[\d-:+\. ]+")
+
 
 @contextmanager
 def cache_dir(exists: bool = True) -> Iterator[Path]:
@@ -2069,6 +2073,146 @@ def test_docstring_reformat_for_py27(self) -> None:
         actual = result.output
         self.assertFormatEqual(actual, expected)
 
+    @staticmethod
+    def compare_results(
+        result: click.testing.Result, expected_value: str, expected_exit_code: int
+    ) -> None:
+        """Helper method to test the value and exit code of a click Result."""
+        assert (
+            result.output == expected_value
+        ), "The output did not match the expected value."
+        assert result.exit_code == expected_exit_code, "The exit code is incorrect."
+
+    def test_code_option(self) -> None:
+        """Test the code option with no changes."""
+        code = 'print("Hello world")\n'
+        args = ["--code", code]
+        result = CliRunner().invoke(black.main, args)
+
+        self.compare_results(result, code, 0)
+
+    def test_code_option_changed(self) -> None:
+        """Test the code option when changes are required."""
+        code = "print('hello world')"
+        formatted = black.format_str(code, mode=DEFAULT_MODE)
+
+        args = ["--code", code]
+        result = CliRunner().invoke(black.main, args)
+
+        self.compare_results(result, formatted, 0)
+
+    def test_code_option_check(self) -> None:
+        """Test the code option when check is passed."""
+        args = ["--check", "--code", 'print("Hello world")\n']
+        result = CliRunner().invoke(black.main, args)
+        self.compare_results(result, "", 0)
+
+    def test_code_option_check_changed(self) -> None:
+        """Test the code option when changes are required, and check is passed."""
+        args = ["--check", "--code", "print('hello world')"]
+        result = CliRunner().invoke(black.main, args)
+        self.compare_results(result, "", 1)
+
+    def test_code_option_diff(self) -> None:
+        """Test the code option when diff is passed."""
+        code = "print('hello world')"
+        formatted = black.format_str(code, mode=DEFAULT_MODE)
+        result_diff = diff(code, formatted, "STDIN", "STDOUT")
+
+        args = ["--diff", "--code", code]
+        result = CliRunner().invoke(black.main, args)
+
+        # Remove time from diff
+        output = DIFF_TIME.sub("", result.output)
+
+        assert output == result_diff, "The output did not match the expected value."
+        assert result.exit_code == 0, "The exit code is incorrect."
+
+    def test_code_option_color_diff(self) -> None:
+        """Test the code option when color and diff are passed."""
+        code = "print('hello world')"
+        formatted = black.format_str(code, mode=DEFAULT_MODE)
+
+        result_diff = diff(code, formatted, "STDIN", "STDOUT")
+        result_diff = color_diff(result_diff)
+
+        args = ["--diff", "--color", "--code", code]
+        result = CliRunner().invoke(black.main, args)
+
+        # Remove time from diff
+        output = DIFF_TIME.sub("", result.output)
+
+        assert output == result_diff, "The output did not match the expected value."
+        assert result.exit_code == 0, "The exit code is incorrect."
+
+    def test_code_option_safe(self) -> None:
+        """Test that the code option throws an error when the sanity checks fail."""
+        # Patch black.assert_equivalent to ensure the sanity checks fail
+        with patch.object(black, "assert_equivalent", side_effect=AssertionError):
+            code = 'print("Hello world")'
+            error_msg = f"{code}\nerror: cannot format <string>: \n"
+
+            args = ["--safe", "--code", code]
+            result = CliRunner().invoke(black.main, args)
+
+            self.compare_results(result, error_msg, 123)
+
+    def test_code_option_fast(self) -> None:
+        """Test that the code option ignores errors when the sanity checks fail."""
+        # Patch black.assert_equivalent to ensure the sanity checks fail
+        with patch.object(black, "assert_equivalent", side_effect=AssertionError):
+            code = 'print("Hello world")'
+            formatted = black.format_str(code, mode=DEFAULT_MODE)
+
+            args = ["--fast", "--code", code]
+            result = CliRunner().invoke(black.main, args)
+
+            self.compare_results(result, formatted, 0)
+
+    def test_code_option_config(self) -> None:
+        """
+        Test that the code option finds the pyproject.toml in the current directory.
+        """
+        with patch.object(black, "parse_pyproject_toml", return_value={}) as parse:
+            # Make sure we are in the project root with the pyproject file
+            if not Path("tests").exists():
+                os.chdir("..")
+
+            args = ["--code", "print"]
+            CliRunner().invoke(black.main, args)
+
+            pyproject_path = Path(Path().cwd(), "pyproject.toml").resolve()
+            assert (
+                len(parse.mock_calls) >= 1
+            ), "Expected config parse to be called with the current directory."
+
+            _, call_args, _ = parse.mock_calls[0]
+            assert (
+                call_args[0].lower() == str(pyproject_path).lower()
+            ), "Incorrect config loaded."
+
+    def test_code_option_parent_config(self) -> None:
+        """
+        Test that the code option finds the pyproject.toml in the parent directory.
+        """
+        with patch.object(black, "parse_pyproject_toml", return_value={}) as parse:
+            # Make sure we are in the tests directory
+            if Path("tests").exists():
+                os.chdir("tests")
+
+            args = ["--code", "print"]
+            CliRunner().invoke(black.main, args)
+
+            pyproject_path = Path(Path().cwd().parent, "pyproject.toml").resolve()
+            assert (
+                len(parse.mock_calls) >= 1
+            ), "Expected config parse to be called with the current directory."
+
+            _, call_args, _ = parse.mock_calls[0]
+            assert (
+                call_args[0].lower() == str(pyproject_path).lower()
+            ), "Incorrect config loaded."
+
 
 with open(black.__file__, "r", encoding="utf-8") as _bf:
     black_source_lines = _bf.readlines()

From 5de8c5f2f798d97133de3a1b391c04813c314c48 Mon Sep 17 00:00:00 2001
From: Cooper Ry Lees <me@cooperlees.com>
Date: Tue, 1 Jun 2021 19:45:03 -0700
Subject: [PATCH 0229/1034] Move `--code` #2259 change log to correct unlreased
 section of CHANGES.md

---
 CHANGES.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index e7851637836..e9775e0ac42 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -5,6 +5,7 @@
 ### _Black_
 
 - Correct max string length calculation when there are string operators (#2292)
+- Fixed option usage when using the `--code` flag (#2259)
 
 ## 21.5b2
 
@@ -15,7 +16,6 @@
 - Respect `.gitignore` files in all levels, not only `root/.gitignore` file (apply
   `.gitignore` rules like `git` does) (#2225)
 - Restored compatibility with Click 8.0 on Python 3.6 when LANG=C used (#2227)
-- Fixed option usage when using the `--code` flag (#2259)
 - Add extra uvloop install + import support if in python env (#2258)
 - Fix --experimental-string-processing crash when matching parens are not found (#2283)
 - Make sure to split lines that start with a string operator (#2286)

From f2a3fee15c3bc0f4068b2b2fb64f255b417cb4ef Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Tue, 1 Jun 2021 20:01:02 -0700
Subject: [PATCH 0230/1034] remove unnecessary docs changelog

---
 CHANGES.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index e9775e0ac42..3427fe8e391 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -44,7 +44,6 @@
 - Fix typos discovered by codespell (#2228)
 - Fix Vim plugin installation instructions. (#2235)
 - Add new Frequently Asked Questions page (#2247)
-- Removed safety checks warning for the `--code` option (#2259)
 - Fix encoding + symlink issues preventing proper build on Windows (#2262)
 
 ## 21.5b1

From df1c86cbe7cf0727d81e526e904b0752d7371da0 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Thu, 3 Jun 2021 10:13:55 -0700
Subject: [PATCH 0231/1034] don't uvloop.install on import (#2303)

---
 CHANGES.md               |  1 +
 src/black/__init__.py    | 11 ++---------
 src/black/concurrency.py | 15 +++++++++++++++
 src/blackd/__init__.py   | 10 ++--------
 4 files changed, 20 insertions(+), 17 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 3427fe8e391..e4fa25c90f4 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -6,6 +6,7 @@
 
 - Correct max string length calculation when there are string operators (#2292)
 - Fixed option usage when using the `--code` flag (#2259)
+- Do not call `uvloop.install()` when _Black_ is used as a library (#2303)
 
 ## 21.5b2
 
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 1d0ad7d5ddd..d95e9b13bb9 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -38,7 +38,7 @@
 from black.mode import Mode, TargetVersion
 from black.mode import Feature, supports_feature, VERSION_TO_FEATURES
 from black.cache import read_cache, write_cache, get_cache_info, filter_cached, Cache
-from black.concurrency import cancel, shutdown
+from black.concurrency import cancel, shutdown, maybe_install_uvloop
 from black.output import dump_to_file, diff, color_diff, out, err
 from black.report import Report, Changed
 from black.files import find_project_root, find_pyproject_toml, parse_pyproject_toml
@@ -54,14 +54,6 @@
 
 from _black_version import version as __version__
 
-# If our environment has uvloop installed lets use it
-try:
-    import uvloop
-
-    uvloop.install()
-except ImportError:
-    pass
-
 # types
 FileContent = str
 Encoding = str
@@ -1112,6 +1104,7 @@ def patch_click() -> None:
 
 
 def patched_main() -> None:
+    maybe_install_uvloop()
     freeze_support()
     patch_click()
     main()
diff --git a/src/black/concurrency.py b/src/black/concurrency.py
index 119a9a71faf..69d79f534e8 100644
--- a/src/black/concurrency.py
+++ b/src/black/concurrency.py
@@ -6,6 +6,21 @@
 from black.output import err
 
 
+def maybe_install_uvloop() -> None:
+    """If our environment has uvloop installed we use it.
+
+    This is called only from command-line entry points to avoid
+    interfering with the parent process if Black is used as a library.
+
+    """
+    try:
+        import uvloop
+
+        uvloop.install()
+    except ImportError:
+        pass
+
+
 def cancel(tasks: Iterable["asyncio.Task[Any]"]) -> None:
     """asyncio signal handler that cancels all `tasks` and reports to stderr."""
     err("Aborted!")
diff --git a/src/blackd/__init__.py b/src/blackd/__init__.py
index 10b616894da..3e2a7e7c30f 100644
--- a/src/blackd/__init__.py
+++ b/src/blackd/__init__.py
@@ -20,16 +20,9 @@
     sys.exit(-1)
 
 import black
+from black.concurrency import maybe_install_uvloop
 import click
 
-# If our environment has uvloop installed lets use it
-try:
-    import uvloop
-
-    uvloop.install()
-except ImportError:
-    pass
-
 from _black_version import version as __version__
 
 # This is used internally by tests to shut down the server prematurely
@@ -210,6 +203,7 @@ def parse_python_variant_header(value: str) -> Tuple[bool, Set[black.TargetVersi
 
 
 def patched_main() -> None:
+    maybe_install_uvloop()
     freeze_support()
     black.patch_click()
     main()

From a2b5ba2a3a97eb3a0b5130a5b317bb750c1624cf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Felix=20Hild=C3=A9n?= <felix.hilden@gmail.com>
Date: Thu, 3 Jun 2021 23:09:41 +0300
Subject: [PATCH 0232/1034] Add option to require a specific version to be
 running (#2300)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Closes #1246: This PR adds a new option (and automatically a toml entry, hooray for existing configuration management 🎉) to require a specific version of Black to be running.

For example: `black --required-version 20.8b -c "format = 'this'"`

Execution fails straight away if it doesn't match `__version__`.
---
 CHANGES.md                                 |  1 +
 docs/usage_and_configuration/the_basics.md | 15 ++++++++++++-
 src/black/__init__.py                      | 26 ++++++++++++++++++----
 tests/test_black.py                        | 10 +++++++++
 4 files changed, 47 insertions(+), 5 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index e4fa25c90f4..16d9ebc3fe5 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -7,6 +7,7 @@
 - Correct max string length calculation when there are string operators (#2292)
 - Fixed option usage when using the `--code` flag (#2259)
 - Do not call `uvloop.install()` when _Black_ is used as a library (#2303)
+- Added `--required-version` option to require a specific version to be running (#2300)
 
 ## 21.5b2
 
diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index c5e17e5a521..474ad669cd1 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -167,7 +167,7 @@ $ black src/ -q
 error: cannot format src/black_primer/cli.py: Cannot parse: 5:6: mport asyncio
 ```
 
-### Getting the version
+### Versions
 
 You can check the version of _Black_ you have installed using the `--version` flag.
 
@@ -176,6 +176,19 @@ $ black --version
 black, version 21.5b0
 ```
 
+An option to require a specific version to be running is also provided.
+
+```console
+$ black --required-version 21.5b2 -c "format = 'this'"
+format = "this"
+$ black --required-version 31.5b2 -c "still = 'beta?!'"
+Oh no! 💥 💔 💥 The required version does not match the running version!
+```
+
+This is useful for example when running _Black_ in multiple environments that haven't
+necessarily installed the correct version. This option can be set in a configuration
+file for consistent results across environments.
+
 ## Configuration via a file
 
 _Black_ is able to read project-specific default values for its command line options
diff --git a/src/black/__init__.py b/src/black/__init__.py
index d95e9b13bb9..a985926afa5 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -241,6 +241,14 @@ def validate_regex(
     is_flag=True,
     help="If --fast given, skip temporary sanity checks. [default: --safe]",
 )
+@click.option(
+    "--required-version",
+    type=str,
+    help=(
+        "Require a specific version of Black to be running (useful for unifying results"
+        " across many environments e.g. with a pyproject.toml file)."
+    ),
+)
 @click.option(
     "--include",
     type=str,
@@ -351,6 +359,7 @@ def main(
     experimental_string_processing: bool,
     quiet: bool,
     verbose: bool,
+    required_version: str,
     include: Pattern,
     exclude: Optional[Pattern],
     extend_exclude: Optional[Pattern],
@@ -360,6 +369,17 @@ def main(
     config: Optional[str],
 ) -> None:
     """The uncompromising code formatter."""
+    if config and verbose:
+        out(f"Using configuration from {config}.", bold=False, fg="blue")
+
+    error_msg = "Oh no! 💥 💔 💥"
+    if required_version and required_version != __version__:
+        err(
+            f"{error_msg} The required version `{required_version}` does not match"
+            f" the running version `{__version__}`!"
+        )
+        ctx.exit(1)
+
     write_back = WriteBack.from_configuration(check=check, diff=diff, color=color)
     if target_version:
         versions = set(target_version)
@@ -374,8 +394,6 @@ def main(
         magic_trailing_comma=not skip_magic_trailing_comma,
         experimental_string_processing=experimental_string_processing,
     )
-    if config and verbose:
-        out(f"Using configuration from {config}.", bold=False, fg="blue")
 
     if code is not None:
         # Run in quiet mode by default with -c; the extra output isn't useful.
@@ -428,9 +446,9 @@ def main(
             )
 
     if verbose or not quiet:
-        out("Oh no! 💥 💔 💥" if report.return_code else "All done! ✨ 🍰 ✨")
+        out(error_msg if report.return_code else "All done! ✨ 🍰 ✨")
         if code is None:
-            click.secho(str(report), err=True)
+            click.echo(str(report), err=True)
     ctx.exit(report.return_code)
 
 
diff --git a/tests/test_black.py b/tests/test_black.py
index f0a14aa2da4..455cb33e827 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -1796,6 +1796,16 @@ def test_invalid_cli_regex(self) -> None:
         for option in ["--include", "--exclude", "--extend-exclude", "--force-exclude"]:
             self.invokeBlack(["-", option, "**()(!!*)"], exit_code=2)
 
+    def test_required_version_matches_version(self) -> None:
+        self.invokeBlack(
+            ["--required-version", black.__version__], exit_code=0, ignore_config=True
+        )
+
+    def test_required_version_does_not_match_version(self) -> None:
+        self.invokeBlack(
+            ["--required-version", "20.99b"], exit_code=1, ignore_config=True
+        )
+
     def test_preserves_line_endings(self) -> None:
         with TemporaryDirectory() as workspace:
             test_file = Path(workspace) / "test.py"

From c53b3ad8fa62eb124d017a23bdff5a2bfa9890af Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Thu, 3 Jun 2021 21:26:21 -0400
Subject: [PATCH 0233/1034] Go back to single core for test suite on CI (#2305)

The random asyncio bug is just too frequent and annoying to be
worth the speed improvements. Our test suite is already quite fast.
Random test failures hurt for 3 reasons, 1) they are discouraging for
new contributors who won't understand it's out of their control, 2)
it's annoying and time consuming to rerun the workflow, and 3) it
makes single job failures feel less important (even they should be
treated as important!).
---
 .github/workflows/test.yml |  2 +-
 tox.ini                    | 12 +++++++++---
 2 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index ef8debb3fb7..1db9f5d6d93 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -42,7 +42,7 @@ jobs:
 
       - name: Unit tests
         run: |
-          tox -e py -- -v --color=yes
+          tox -e ci-py -- -v --color=yes
 
       - name: Publish coverage to Coveralls
         # If pushed / is a pull request against main repo AND
diff --git a/tox.ini b/tox.ini
index 2379500f55a..3ea4da8eac2 100644
--- a/tox.ini
+++ b/tox.ini
@@ -1,17 +1,23 @@
 [tox]
-envlist = py{36,37,38,39},fuzz
+envlist = {,ci-}py{36,37,38,39},fuzz
 
 [testenv]
 setenv = PYTHONPATH = {toxinidir}/src
 skip_install = True
 deps =
     -r{toxinidir}/test_requirements.txt
+; parallelization is disabled on CI because pytest-dev/pytest-xdist#620 occurs too frequently
+; local runs can stay parallelized since they aren't rolling the dice so many times as like on CI
 commands =
     pip install -e .[d]
     coverage erase
-    pytest tests --run-optional no_python2 --numprocesses auto --cov {posargs}
+    pytest tests --run-optional no_python2 \
+        !ci: --numprocesses auto \
+        --cov {posargs}
     pip install -e .[d,python2]
-    pytest tests --run-optional python2 --numprocesses auto --cov --cov-append {posargs}
+    pytest tests --run-optional python2 \
+        !ci: --numprocesses auto \
+        --cov --cov-append {posargs}
     coverage report
 
 [testenv:fuzz]

From 6380b9f2f6e53748360a120ed9acb874a35885e0 Mon Sep 17 00:00:00 2001
From: Bryan Bugyi <bryanbugyi34@gmail.com>
Date: Mon, 7 Jun 2021 10:01:57 -0400
Subject: [PATCH 0234/1034] Account for += assignment when deciding whether to
 split string (#2312)

Fixes #2294
---
 CHANGES.md                             |  1 +
 src/black/trans.py                     |  2 +-
 tests/data/long_strings__edge_case.py  | 11 +++++++++++
 tests/data/long_strings__regression.py | 20 ++++++++++++++++++++
 4 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index 16d9ebc3fe5..84f156d903d 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -4,6 +4,7 @@
 
 ### _Black_
 
+- Account for += assignment when deciding whether to split string (#2312)
 - Correct max string length calculation when there are string operators (#2292)
 - Fixed option usage when using the `--code` flag (#2259)
 - Do not call `uvloop.install()` when _Black_ is used as a library (#2303)
diff --git a/src/black/trans.py b/src/black/trans.py
index bc6e93b01b4..d56205d4598 100644
--- a/src/black/trans.py
+++ b/src/black/trans.py
@@ -867,7 +867,7 @@ def _get_max_string_length(self, line: Line, string_idx: int) -> int:
                 # WMA4 a space, a comma, and a closing bracket [e.g. `), STRING`].
                 offset += 3
 
-            if P.type in [token.COLON, token.EQUAL, token.NAME]:
+            if P.type in [token.COLON, token.EQUAL, token.PLUSEQUAL, token.NAME]:
                 # This conditional branch is meant to handle dictionary keys,
                 # variable assignments, 'return STRING' statement lines, and
                 # 'else STRING' ternary expression lines.
diff --git a/tests/data/long_strings__edge_case.py b/tests/data/long_strings__edge_case.py
index 07c27537191..2bc0b6ed328 100644
--- a/tests/data/long_strings__edge_case.py
+++ b/tests/data/long_strings__edge_case.py
@@ -32,6 +32,9 @@
 assert str(result) == "This long string should be split at some point right close to or around hereeeeeee"
 assert str(result) < "This long string should be split at some point right close to or around hereeeeee"
 assert "A format string: %s" % "This long string should be split at some point right close to or around hereeeeeee" != result
+msg += "This long string should be wrapped in parens at some point right around hereeeee"
+msg += "This long string should be split at some point right close to or around hereeeeeeee"
+msg += "This long string should not be split at any point ever since it is just righttt"
 
 
 # output
@@ -127,3 +130,11 @@
     " hereeeeeee"
     != result
 )
+msg += (
+    "This long string should be wrapped in parens at some point right around hereeeee"
+)
+msg += (
+    "This long string should be split at some point right close to or around"
+    " hereeeeeeee"
+)
+msg += "This long string should not be split at any point ever since it is just righttt"
diff --git a/tests/data/long_strings__regression.py b/tests/data/long_strings__regression.py
index cd8053f9eb5..d46f96a82d0 100644
--- a/tests/data/long_strings__regression.py
+++ b/tests/data/long_strings__regression.py
@@ -407,6 +407,16 @@ def _legacy_listen_examples():
     )
 
 
+class X:
+    async def foo(self):
+        msg = ""
+        for candidate in CANDIDATES:
+            msg += (
+                "**{candidate.object_type} {candidate.rev}**"
+                " - {candidate.description}\n"
+            )
+
+
 temp_msg = (
     f"{f'{humanize_number(pos)}.': <{pound_len+2}} "
     f"{balance: <{bal_len + 5}} "
@@ -948,6 +958,16 @@ def _legacy_listen_examples():
     )
 
 
+class X:
+    async def foo(self):
+        msg = ""
+        for candidate in CANDIDATES:
+            msg += (
+                "**{candidate.object_type} {candidate.rev}**"
+                " - {candidate.description}\n"
+            )
+
+
 temp_msg = (
     f"{f'{humanize_number(pos)}.': <{pound_len+2}} "
     f"{balance: <{bal_len + 5}} "

From 99b68e59ce0424a86215cc9ca0cb46e481d2a6fe Mon Sep 17 00:00:00 2001
From: Bryan Bugyi <bryanbugyi34@gmail.com>
Date: Mon, 7 Jun 2021 10:03:39 -0400
Subject: [PATCH 0235/1034] Fix incorrect custom breakpoint indices when string
 group contains fake f-strings (#2311)

Fixes #2293
---
 CHANGES.md                             |  2 +
 src/black/trans.py                     | 33 +++++++----
 tests/data/long_strings__regression.py | 78 ++++++++++++++++++++++++++
 3 files changed, 102 insertions(+), 11 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 84f156d903d..02b3fdf75d5 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -9,6 +9,8 @@
 - Fixed option usage when using the `--code` flag (#2259)
 - Do not call `uvloop.install()` when _Black_ is used as a library (#2303)
 - Added `--required-version` option to require a specific version to be running (#2300)
+- Fix incorrect custom breakpoint indices when string group contains fake f-strings
+  (#2311)
 
 ## 21.5b2
 
diff --git a/src/black/trans.py b/src/black/trans.py
index d56205d4598..4fb2c4d0144 100644
--- a/src/black/trans.py
+++ b/src/black/trans.py
@@ -1151,21 +1151,32 @@ def more_splits_should_be_made() -> bool:
 
             # --- Construct `next_value`
             next_value = rest_value[:break_idx] + QUOTE
+
+            # HACK: The following 'if' statement is a hack to fix the custom
+            # breakpoint index in the case of either: (a) substrings that were
+            # f-strings but will have the 'f' prefix removed OR (b) substrings
+            # that were not f-strings but will now become f-strings because of
+            # redundant use of the 'f' prefix (i.e. none of the substrings
+            # contain f-expressions but one or more of them had the 'f' prefix
+            # anyway; in which case, we will prepend 'f' to _all_ substrings).
+            #
+            # There is probably a better way to accomplish what is being done
+            # here...
+            #
+            # If this substring is an f-string, we _could_ remove the 'f'
+            # prefix, and the current custom split did NOT originally use a
+            # prefix...
             if (
-                # Are we allowed to try to drop a pointless 'f' prefix?
-                drop_pointless_f_prefix
-                # If we are, will we be successful?
-                and next_value != self._normalize_f_string(next_value, prefix)
+                next_value != self._normalize_f_string(next_value, prefix)
+                and use_custom_breakpoints
+                and not csplit.has_prefix
             ):
-                # If the current custom split did NOT originally use a prefix,
-                # then `csplit.break_idx` will be off by one after removing
+                # Then `csplit.break_idx` will be off by one after removing
                 # the 'f' prefix.
-                break_idx = (
-                    break_idx + 1
-                    if use_custom_breakpoints and not csplit.has_prefix
-                    else break_idx
-                )
+                break_idx += 1
                 next_value = rest_value[:break_idx] + QUOTE
+
+            if drop_pointless_f_prefix:
                 next_value = self._normalize_f_string(next_value, prefix)
 
             # --- Construct `next_leaf`
diff --git a/tests/data/long_strings__regression.py b/tests/data/long_strings__regression.py
index d46f96a82d0..83cae614e69 100644
--- a/tests/data/long_strings__regression.py
+++ b/tests/data/long_strings__regression.py
@@ -455,6 +455,45 @@ async def foo(self):
 )
 assert str(suffix_arr) in "['$', 'angaroo$', 'angrykangaroo$', 'aroo$', 'garoo$', 'grykangaroo$', 'kangaroo$', 'ngaroo$', 'ngrykangaroo$', 'o$', 'oo$', 'roo$', 'rykangaroo$', 'ykangaroo$']"
 assert str(suffix_arr) not in "['$', 'angaroo$', 'angrykangaroo$', 'aroo$', 'garoo$', 'grykangaroo$', 'kangaroo$', 'ngaroo$', 'ngrykangaroo$', 'o$', 'oo$', 'roo$', 'rykangaroo$', 'ykangaroo$']"
+message = (
+    f"1. Go to Google Developers Console and log in with your Google account."
+    "(https://console.developers.google.com/)"
+    "2. You should be prompted to create a new project (name does not matter)."
+    "3. Click on Enable APIs and Services at the top."
+    "4. In the list of APIs choose or search for YouTube Data API v3 and "
+    "click on it. Choose Enable."
+    "5. Click on Credentials on the left navigation bar."
+    "6. Click on Create Credential at the top."
+    '7. At the top click the link for "API key".'
+    "8. No application restrictions are needed. Click Create at the bottom."
+    "9. You now have a key to add to `{prefix}set api youtube api_key`"
+)
+message = (
+    f"1. Go to Google Developers Console and log in with your Google account."
+    "(https://console.developers.google.com/)"
+    "2. You should be prompted to create a new project (name does not matter)."
+    f"3. Click on Enable APIs and Services at the top."
+    "4. In the list of APIs choose or search for YouTube Data API v3 and "
+    "click on it. Choose Enable."
+    f"5. Click on Credentials on the left navigation bar."
+    "6. Click on Create Credential at the top."
+    '7. At the top click the link for "API key".'
+    "8. No application restrictions are needed. Click Create at the bottom."
+    "9. You now have a key to add to `{prefix}set api youtube api_key`"
+)
+message = (
+    f"1. Go to Google Developers Console and log in with your Google account."
+    "(https://console.developers.google.com/)"
+    "2. You should be prompted to create a new project (name does not matter)."
+    f"3. Click on Enable APIs and Services at the top."
+    "4. In the list of APIs choose or search for YouTube Data API v3 and "
+    "click on it. Choose Enable."
+    f"5. Click on Credentials on the left navigation bar."
+    "6. Click on Create Credential at the top."
+    '7. At the top click the link for "API key".'
+    "8. No application restrictions are needed. Click Create at the bottom."
+    f"9. You now have a key to add to `{prefix}set api youtube api_key`"
+)
 
 # output
 
@@ -1022,3 +1061,42 @@ async def foo(self):
     " 'kangaroo$', 'ngaroo$', 'ngrykangaroo$', 'o$', 'oo$', 'roo$',"
     " 'rykangaroo$', 'ykangaroo$']"
 )
+message = (
+    f"1. Go to Google Developers Console and log in with your Google account."
+    f"(https://console.developers.google.com/)"
+    f"2. You should be prompted to create a new project (name does not matter)."
+    f"3. Click on Enable APIs and Services at the top."
+    f"4. In the list of APIs choose or search for YouTube Data API v3 and "
+    f"click on it. Choose Enable."
+    f"5. Click on Credentials on the left navigation bar."
+    f"6. Click on Create Credential at the top."
+    f'7. At the top click the link for "API key".'
+    f"8. No application restrictions are needed. Click Create at the bottom."
+    f"9. You now have a key to add to `{{prefix}}set api youtube api_key`"
+)
+message = (
+    f"1. Go to Google Developers Console and log in with your Google account."
+    f"(https://console.developers.google.com/)"
+    f"2. You should be prompted to create a new project (name does not matter)."
+    f"3. Click on Enable APIs and Services at the top."
+    f"4. In the list of APIs choose or search for YouTube Data API v3 and "
+    f"click on it. Choose Enable."
+    f"5. Click on Credentials on the left navigation bar."
+    f"6. Click on Create Credential at the top."
+    f'7. At the top click the link for "API key".'
+    f"8. No application restrictions are needed. Click Create at the bottom."
+    f"9. You now have a key to add to `{{prefix}}set api youtube api_key`"
+)
+message = (
+    "1. Go to Google Developers Console and log in with your Google account."
+    "(https://console.developers.google.com/)"
+    "2. You should be prompted to create a new project (name does not matter)."
+    "3. Click on Enable APIs and Services at the top."
+    "4. In the list of APIs choose or search for YouTube Data API v3 and "
+    "click on it. Choose Enable."
+    "5. Click on Credentials on the left navigation bar."
+    "6. Click on Create Credential at the top."
+    '7. At the top click the link for "API key".'
+    "8. No application restrictions are needed. Click Create at the bottom."
+    f"9. You now have a key to add to `{prefix}set api youtube api_key`"
+)

From c1c2418368cfcaa4f49edd7ec599fa45cce2d47d Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Mon, 7 Jun 2021 08:05:08 -0700
Subject: [PATCH 0236/1034] [primer] Enable everything (#2288)

See if we pass all our repos with experimental string processing enabled.
Django probably needed:
- Ignores >= 3.8 only

We could support PEP440 version specifiers, but that would introduce the packaging module as a dependency that I'd like to avoid ... Or I could implement a poor persons version or vendor

Commit history before merge:
 * [primer] Enable everything
 * Add exclude extend to django CLI args for primer
 * Change default timeout to from 5 to 10 mins for a primer project
 * Skip string normalization for Django
 * Limit Django to >= 3.8 due to := operator
---
 src/black_primer/lib.py      |  2 +-
 src/black_primer/primer.json | 13 +++++++------
 2 files changed, 8 insertions(+), 7 deletions(-)

diff --git a/src/black_primer/lib.py b/src/black_primer/lib.py
index 384c0ad6cea..df67602b6a5 100644
--- a/src/black_primer/lib.py
+++ b/src/black_primer/lib.py
@@ -39,7 +39,7 @@ class Results(NamedTuple):
 
 async def _gen_check_output(
     cmd: Sequence[str],
-    timeout: float = 300,
+    timeout: float = 600,
     env: Optional[Dict[str, str]] = None,
     cwd: Optional[Path] = None,
 ) -> Tuple[bytes, bytes]:
diff --git a/src/black_primer/primer.json b/src/black_primer/primer.json
index 034372609a1..f1035a819ce 100644
--- a/src/black_primer/primer.json
+++ b/src/black_primer/primer.json
@@ -30,13 +30,16 @@
       "py_versions": ["all"]
     },
     "django": {
-      "disabled_reason": "black --check --diff returned 123 on tests_syntax_error.py",
-      "disabled": true,
-      "cli_arguments": ["--experimental-string-processing"],
+      "cli_arguments": [
+        "--experimental-string-processing",
+        "--skip-string-normalization",
+        "--extend-exclude",
+        "/((docs|scripts)/|django/forms/models.py|tests/gis_tests/test_spatialrefsys.py|tests/test_runner_apps/tagged/tests_syntax_error.py)"
+      ],
       "expect_formatting_changes": true,
       "git_clone_url": "https://github.com/django/django.git",
       "long_checkout": false,
-      "py_versions": ["all"]
+      "py_versions": ["3.8", "3.9"]
     },
     "flake8-bugbear": {
       "cli_arguments": ["--experimental-string-processing"],
@@ -53,8 +56,6 @@
       "py_versions": ["all"]
     },
     "pandas": {
-      "disabled_reason": "black-primer runs failing on Pandas - #2193",
-      "disabled": true,
       "cli_arguments": ["--experimental-string-processing"],
       "expect_formatting_changes": true,
       "git_clone_url": "https://github.com/pandas-dev/pandas.git",

From 40fae18134916b8499bd992d8bef4ae23bcd2986 Mon Sep 17 00:00:00 2001
From: Sergey Vartanov <me@enzet.ru>
Date: Wed, 9 Jun 2021 00:37:34 +0300
Subject: [PATCH 0237/1034] Possible fix for issue with indentation and fmt:
 skip (#2281)

Not sure the fix is right.  Here is what I found: issue is connected
with line

    first.prefix = prefix[comment.consumed :]

in `comments.py`.  `first.prefix` is a prefix of the line, that ends
with `# fmt: skip`, but `comment.consumed` is the length of the
`"  # fmt: skip"` string.  If prefix length is greater than 14,
`first.prefix` will grow every time we apply formatting.

Fixes #2254
---
 CHANGES.md             |  1 +
 src/black/comments.py  |  5 ++++-
 tests/data/fmtskip6.py | 13 +++++++++++++
 tests/test_format.py   |  1 +
 4 files changed, 19 insertions(+), 1 deletion(-)
 create mode 100644 tests/data/fmtskip6.py

diff --git a/CHANGES.md b/CHANGES.md
index 02b3fdf75d5..2d2b3b4cf49 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -4,6 +4,7 @@
 
 ### _Black_
 
+- Fix failure caused by `fmt: skip` and indentation (#2281)
 - Account for += assignment when deciding whether to split string (#2312)
 - Correct max string length calculation when there are string operators (#2292)
 - Fixed option usage when using the `--code` flag (#2259)
diff --git a/src/black/comments.py b/src/black/comments.py
index 415e391b2a7..c7513c21ef5 100644
--- a/src/black/comments.py
+++ b/src/black/comments.py
@@ -159,7 +159,10 @@ def convert_one_fmt_off_pair(node: Node) -> bool:
             first = ignored_nodes[0]  # Can be a container node with the `leaf`.
             parent = first.parent
             prefix = first.prefix
-            first.prefix = prefix[comment.consumed :]
+            if comment.value in FMT_OFF:
+                first.prefix = prefix[comment.consumed :]
+            if comment.value in FMT_SKIP:
+                first.prefix = ""
             hidden_value = "".join(str(n) for n in ignored_nodes)
             if comment.value in FMT_OFF:
                 hidden_value = comment.value + "\n" + hidden_value
diff --git a/tests/data/fmtskip6.py b/tests/data/fmtskip6.py
new file mode 100644
index 00000000000..0a779fcee00
--- /dev/null
+++ b/tests/data/fmtskip6.py
@@ -0,0 +1,13 @@
+class A:
+    def f(self):
+        for line in range(10):
+            if True:
+                pass  # fmt: skip
+
+# output
+
+class A:
+    def f(self):
+        for line in range(10):
+            if True:
+                pass  # fmt: skip
diff --git a/tests/test_format.py b/tests/test_format.py
index 5c78afe0ba6..fc9678ad27c 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -41,6 +41,7 @@
     "fmtskip3",
     "fmtskip4",
     "fmtskip5",
+    "fmtskip6",
     "fstring",
     "function",
     "function2",

From a9eab85f226df3b3070aca122d089dbd62b42b9c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Felix=20Hild=C3=A9n?= <felix.hilden@gmail.com>
Date: Wed, 9 Jun 2021 00:57:23 +0300
Subject: [PATCH 0238/1034] Mention comment non-processing in documentation
 (#2306)

This commit adds a short section discussing the non-processing of docstrings
besides spacing improvements, mentions comment moving and links to the
AST equivalence discussion. I also added a simple spacing test for good
measure.

Commit history before merge:

* Mention comment non-processing in documentation, add spacing test
* Mention special cases for comment spacing
* Add all special cases, improve wording
---
 docs/the_black_code_style/current_style.md | 10 ++++++++++
 tests/data/comments2.py                    |  4 ++--
 2 files changed, 12 insertions(+), 2 deletions(-)

diff --git a/docs/the_black_code_style/current_style.md b/docs/the_black_code_style/current_style.md
index 8c3a30270d1..aa2dd881a9e 100644
--- a/docs/the_black_code_style/current_style.md
+++ b/docs/the_black_code_style/current_style.md
@@ -200,6 +200,16 @@ following field or method. This conforms to
 _Black_ won't insert empty lines after function docstrings unless that empty line is
 required due to an inner function starting immediately after.
 
+### Comments
+
+_Black_ does not format comment contents, but it enforces two spaces between code and a
+comment on the same line, and a space before the comment text begins. Some types of
+comments that require specific spacing rules are respected: doc comments (`#: comment`),
+section comments with long runs of hashes, and Spyder cells. Non-breaking spaces after
+hashes are also preserved. Comments may sometimes be moved because of formatting
+changes, which can break tools that assign special meaning to them. See
+[AST before and after formatting](#ast-before-and-after-formatting) for more discussion.
+
 ### Trailing commas
 
 _Black_ will add trailing commas to expressions that are split by comma where each
diff --git a/tests/data/comments2.py b/tests/data/comments2.py
index 221cb3fe143..4eea013151a 100644
--- a/tests/data/comments2.py
+++ b/tests/data/comments2.py
@@ -159,7 +159,7 @@ def _init_host(self, parsed) -> None:
 #######################
 
 
-instruction()
+instruction()#comment with bad spacing
 
 # END COMMENTS
 # MORE END COMMENTS
@@ -336,7 +336,7 @@ def _init_host(self, parsed) -> None:
 #######################
 
 
-instruction()
+instruction()  # comment with bad spacing
 
 # END COMMENTS
 # MORE END COMMENTS

From 00e7e12a3a412ea386806d5d4eeaed345e912940 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Tue, 8 Jun 2021 20:46:09 -0400
Subject: [PATCH 0239/1034] Regression fix: leave R prefixes capitalization
 alone (#2285)

`black.strings.get_string_prefix` used to lowercase the extracted
prefix before returning it. This is wrong because 1) it ignores the
fact we should leave R prefixes alone because of MagicPython, and 2)
there is dedicated prefix casing handling code that fixes issue 1.
`.lower` is too naive.

This was originally fixed in 20.8b0, but was reintroduced since 21.4b0.

I also added proper prefix normalization for docstrings by using the
`black.strings.normalize_string_prefix` helper.

Some more test strings were added to make sure strings with capitalized
prefixes aren't treated differently (actually happened with my original
patch, Jelle had to point it out to me).
---
 CHANGES.md                             |  1 +
 src/black/linegen.py                   |  5 +--
 src/black/strings.py                   |  2 +-
 src/black/trans.py                     | 10 +++---
 tests/data/long_strings__regression.py | 42 ++++++++++++++++++++++++++
 tests/data/string_prefixes.py          | 21 +++++++++++++
 6 files changed, 73 insertions(+), 8 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 2d2b3b4cf49..9c2939e1b1b 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -12,6 +12,7 @@
 - Added `--required-version` option to require a specific version to be running (#2300)
 - Fix incorrect custom breakpoint indices when string group contains fake f-strings
   (#2311)
+- Fix regression where `R` prefixes would be lowercased for docstrings (#2285)
 
 ## 21.5b2
 
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 7949654b40e..3b811f02b7c 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -226,8 +226,9 @@ def visit_STRING(self, leaf: Leaf) -> Iterator[Line]:
         if is_docstring(leaf) and "\\\n" not in leaf.value:
             # We're ignoring docstrings with backslash newline escapes because changing
             # indentation of those changes the AST representation of the code.
-            prefix = get_string_prefix(leaf.value)
-            docstring = leaf.value[len(prefix) :]  # Remove the prefix
+            docstring = normalize_string_prefix(leaf.value, self.remove_u_prefix)
+            prefix = get_string_prefix(docstring)
+            docstring = docstring[len(prefix) :]  # Remove the prefix
             quote_char = docstring[0]
             # A natural way to remove the outer quotes is to do:
             #   docstring = docstring.strip(quote_char)
diff --git a/src/black/strings.py b/src/black/strings.py
index 5b443ddebc9..80f588f5119 100644
--- a/src/black/strings.py
+++ b/src/black/strings.py
@@ -87,7 +87,7 @@ def get_string_prefix(string: str) -> str:
     prefix = ""
     prefix_idx = 0
     while string[prefix_idx] in STRING_PREFIX_CHARS:
-        prefix += string[prefix_idx].lower()
+        prefix += string[prefix_idx]
         prefix_idx += 1
 
     return prefix
diff --git a/src/black/trans.py b/src/black/trans.py
index 4fb2c4d0144..ca620f6b2a5 100644
--- a/src/black/trans.py
+++ b/src/black/trans.py
@@ -411,7 +411,7 @@ def make_naked(string: str, string_prefix: str) -> str:
             and is_valid_index(next_str_idx)
             and LL[next_str_idx].type == token.STRING
         ):
-            prefix = get_string_prefix(LL[next_str_idx].value)
+            prefix = get_string_prefix(LL[next_str_idx].value).lower()
             next_str_idx += 1
 
         # The next loop merges the string group. The final string will be
@@ -431,7 +431,7 @@ def make_naked(string: str, string_prefix: str) -> str:
             num_of_strings += 1
 
             SS = LL[next_str_idx].value
-            next_prefix = get_string_prefix(SS)
+            next_prefix = get_string_prefix(SS).lower()
 
             # If this is an f-string group but this substring is not prefixed
             # with 'f'...
@@ -541,7 +541,7 @@ def _validate_msg(line: Line, string_idx: int) -> TResult[None]:
                 return TErr("StringMerger does NOT merge multiline strings.")
 
             num_of_strings += 1
-            prefix = get_string_prefix(leaf.value)
+            prefix = get_string_prefix(leaf.value).lower()
             if "r" in prefix:
                 return TErr("StringMerger does NOT merge raw strings.")
 
@@ -1036,7 +1036,7 @@ def do_transform(self, line: Line, string_idx: int) -> Iterator[TResult[Line]]:
         is_valid_index = is_valid_index_factory(LL)
         insert_str_child = insert_str_child_factory(LL[string_idx])
 
-        prefix = get_string_prefix(LL[string_idx].value)
+        prefix = get_string_prefix(LL[string_idx].value).lower()
 
         # We MAY choose to drop the 'f' prefix from substrings that don't
         # contain any f-expressions, but ONLY if the original f-string
@@ -1290,7 +1290,7 @@ def fexpr_slices() -> Iterator[Tuple[Index, Index]]:
 
             yield from _fexpr_slices
 
-        is_fstring = "f" in get_string_prefix(string)
+        is_fstring = "f" in get_string_prefix(string).lower()
 
         def breaks_fstring_expression(i: Index) -> bool:
             """
diff --git a/tests/data/long_strings__regression.py b/tests/data/long_strings__regression.py
index 83cae614e69..e4234b2f97c 100644
--- a/tests/data/long_strings__regression.py
+++ b/tests/data/long_strings__regression.py
@@ -495,6 +495,26 @@ async def foo(self):
     f"9. You now have a key to add to `{prefix}set api youtube api_key`"
 )
 
+# It shouldn't matter if the string prefixes are capitalized.
+temp_msg = (
+    F"{F'{humanize_number(pos)}.': <{pound_len+2}} "
+    F"{balance: <{bal_len + 5}} "
+    F"<<{author.display_name}>>\n"
+)
+
+fstring = (
+    F"We have to remember to escape {braces}."
+    " Like {these}."
+    F" But not {this}."
+)
+
+welcome_to_programming = R"hello," R" world!"
+
+fstring = F"f-strings definitely make things more {difficult} than they need to be for {{black}}. But boy they sure are handy. The problem is that some lines will need to have the 'f' whereas others do not. This {line}, for example, needs one."
+
+x = F"This is a long string which contains an f-expr that should not split {{{[i for i in range(5)]}}}."
+
+
 # output
 
 
@@ -1100,3 +1120,25 @@ async def foo(self):
     "8. No application restrictions are needed. Click Create at the bottom."
     f"9. You now have a key to add to `{prefix}set api youtube api_key`"
 )
+
+# It shouldn't matter if the string prefixes are capitalized.
+temp_msg = (
+    f"{F'{humanize_number(pos)}.': <{pound_len+2}} "
+    f"{balance: <{bal_len + 5}} "
+    f"<<{author.display_name}>>\n"
+)
+
+fstring = f"We have to remember to escape {braces}. Like {{these}}. But not {this}."
+
+welcome_to_programming = R"hello," R" world!"
+
+fstring = (
+    f"f-strings definitely make things more {difficult} than they need to be for"
+    " {black}. But boy they sure are handy. The problem is that some lines will need"
+    f" to have the 'f' whereas others do not. This {line}, for example, needs one."
+)
+
+x = (
+    "This is a long string which contains an f-expr that should not split"
+    f" {{{[i for i in range(5)]}}}."
+)
diff --git a/tests/data/string_prefixes.py b/tests/data/string_prefixes.py
index 0ca3686a2b6..9ddc2b540fc 100644
--- a/tests/data/string_prefixes.py
+++ b/tests/data/string_prefixes.py
@@ -6,6 +6,17 @@
 r"hello"
 fR"hello"
 
+
+def docstring_singleline():
+    R"""2020 was one hell of a year. The good news is that we were able to"""
+
+
+def docstring_multiline():
+    R"""
+    clear out all of the issues opened in that time :p
+    """
+
+
 # output
 
 
@@ -16,3 +27,13 @@
 b"hello"
 r"hello"
 fR"hello"
+
+
+def docstring_singleline():
+    R"""2020 was one hell of a year. The good news is that we were able to"""
+
+
+def docstring_multiline():
+    R"""
+    clear out all of the issues opened in that time :p
+    """

From 229498e531b26f93c482115b1ccdb16b70bad620 Mon Sep 17 00:00:00 2001
From: jack1142 <6032823+jack1142@users.noreply.github.com>
Date: Wed, 9 Jun 2021 16:01:07 +0200
Subject: [PATCH 0240/1034] Fix flake8 configuration by switching from
 extend-ignore to ignore (#2320)

---
 .flake8             | 2 +-
 src/black/output.py | 3 ++-
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/.flake8 b/.flake8
index 4866133a6a8..ae11a13347c 100644
--- a/.flake8
+++ b/.flake8
@@ -1,5 +1,5 @@
 [flake8]
-extend-ignore = E203, E266, E501
+ignore = E203, E266, E501, W503
 # line length is intentionally set to 80 here because black uses Bugbear
 # See https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#line-length for more details
 max-line-length = 80
diff --git a/src/black/output.py b/src/black/output.py
index 6831524090d..c253c85e90e 100644
--- a/src/black/output.py
+++ b/src/black/output.py
@@ -45,7 +45,8 @@ def diff(a: str, b: str, a_name: str, b_name: str) -> str:
         a_lines, b_lines, fromfile=a_name, tofile=b_name, n=5
     ):
         # Work around https://bugs.python.org/issue2142
-        # See https://www.gnu.org/software/diffutils/manual/html_node/Incomplete-Lines.html
+        # See:
+        # https://www.gnu.org/software/diffutils/manual/html_node/Incomplete-Lines.html
         if line[-1] == "\n":
             diff_lines.append(line)
         else:

From 62402a32618bc62ae90cfcdc3d47c7ad20e60e10 Mon Sep 17 00:00:00 2001
From: jack1142 <6032823+jack1142@users.noreply.github.com>
Date: Wed, 9 Jun 2021 21:29:32 +0200
Subject: [PATCH 0241/1034] Support named escapes (`\N{...}`) in string
 processing (#2319)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Felix Hildén <felix.hilden@gmail.com>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 CHANGES.md                             |  2 +
 src/black/trans.py                     | 91 +++++++++++++++++---------
 tests/data/long_strings.py             | 72 ++++++++++++++++++++
 tests/data/long_strings__regression.py |  8 +++
 4 files changed, 143 insertions(+), 30 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 9c2939e1b1b..01c02fe2b70 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -13,6 +13,8 @@
 - Fix incorrect custom breakpoint indices when string group contains fake f-strings
   (#2311)
 - Fix regression where `R` prefixes would be lowercased for docstrings (#2285)
+- Fix handling of named escapes (`\N{...}`) when `--experimental-string-processing` is
+  used (#2319)
 
 ## 21.5b2
 
diff --git a/src/black/trans.py b/src/black/trans.py
index ca620f6b2a5..023dcd3618a 100644
--- a/src/black/trans.py
+++ b/src/black/trans.py
@@ -15,6 +15,7 @@
     List,
     Optional,
     Sequence,
+    Set,
     Tuple,
     TypeVar,
     Union,
@@ -1243,6 +1244,61 @@ def more_splits_should_be_made() -> bool:
             last_line.comments = line.comments.copy()
             yield Ok(last_line)
 
+    def _iter_nameescape_slices(self, string: str) -> Iterator[Tuple[Index, Index]]:
+        """
+        Yields:
+            All ranges of @string which, if @string were to be split there,
+            would result in the splitting of an \\N{...} expression (which is NOT
+            allowed).
+        """
+        # True - the previous backslash was unescaped
+        # False - the previous backslash was escaped *or* there was no backslash
+        previous_was_unescaped_backslash = False
+        it = iter(enumerate(string))
+        for idx, c in it:
+            if c == "\\":
+                previous_was_unescaped_backslash = not previous_was_unescaped_backslash
+                continue
+            if not previous_was_unescaped_backslash or c != "N":
+                previous_was_unescaped_backslash = False
+                continue
+            previous_was_unescaped_backslash = False
+
+            begin = idx - 1  # the position of backslash before \N{...}
+            for idx, c in it:
+                if c == "}":
+                    end = idx
+                    break
+            else:
+                # malformed nameescape expression?
+                # should have been detected by AST parsing earlier...
+                raise RuntimeError(f"{self.__class__.__name__} LOGIC ERROR!")
+            yield begin, end
+
+    def _iter_fexpr_slices(self, string: str) -> Iterator[Tuple[Index, Index]]:
+        """
+        Yields:
+            All ranges of @string which, if @string were to be split there,
+            would result in the splitting of an f-expression (which is NOT
+            allowed).
+        """
+        if "f" not in get_string_prefix(string).lower():
+            return
+
+        for match in re.finditer(self.RE_FEXPR, string, re.VERBOSE):
+            yield match.span()
+
+    def _get_illegal_split_indices(self, string: str) -> Set[Index]:
+        illegal_indices: Set[Index] = set()
+        iterators = [
+            self._iter_fexpr_slices(string),
+            self._iter_nameescape_slices(string),
+        ]
+        for it in iterators:
+            for begin, end in it:
+                illegal_indices.update(range(begin, end + 1))
+        return illegal_indices
+
     def _get_break_idx(self, string: str, max_break_idx: int) -> Optional[int]:
         """
         This method contains the algorithm that StringSplitter uses to
@@ -1272,40 +1328,15 @@ def _get_break_idx(self, string: str, max_break_idx: int) -> Optional[int]:
         assert is_valid_index(max_break_idx)
         assert_is_leaf_string(string)
 
-        _fexpr_slices: Optional[List[Tuple[Index, Index]]] = None
-
-        def fexpr_slices() -> Iterator[Tuple[Index, Index]]:
-            """
-            Yields:
-                All ranges of @string which, if @string were to be split there,
-                would result in the splitting of an f-expression (which is NOT
-                allowed).
-            """
-            nonlocal _fexpr_slices
-
-            if _fexpr_slices is None:
-                _fexpr_slices = []
-                for match in re.finditer(self.RE_FEXPR, string, re.VERBOSE):
-                    _fexpr_slices.append(match.span())
-
-            yield from _fexpr_slices
-
-        is_fstring = "f" in get_string_prefix(string).lower()
+        _illegal_split_indices = self._get_illegal_split_indices(string)
 
-        def breaks_fstring_expression(i: Index) -> bool:
+        def breaks_unsplittable_expression(i: Index) -> bool:
             """
             Returns:
                 True iff returning @i would result in the splitting of an
-                f-expression (which is NOT allowed).
+                unsplittable expression (which is NOT allowed).
             """
-            if not is_fstring:
-                return False
-
-            for (start, end) in fexpr_slices():
-                if start <= i < end:
-                    return True
-
-            return False
+            return i in _illegal_split_indices
 
         def passes_all_checks(i: Index) -> bool:
             """
@@ -1329,7 +1360,7 @@ def passes_all_checks(i: Index) -> bool:
                 is_space
                 and is_not_escaped
                 and is_big_enough
-                and not breaks_fstring_expression(i)
+                and not breaks_unsplittable_expression(i)
             )
 
         # First, we check all indices BELOW @max_break_idx.
diff --git a/tests/data/long_strings.py b/tests/data/long_strings.py
index 151396b5239..430f760cf0b 100644
--- a/tests/data/long_strings.py
+++ b/tests/data/long_strings.py
@@ -207,6 +207,38 @@ def foo():
     " of it."
 )
 
+string_with_nameescape = (
+    "........................................................................ \N{LAO KO LA}"
+)
+
+string_with_nameescape = (
+    "........................................................................... \N{LAO KO LA}"
+)
+
+string_with_nameescape = (
+    "............................................................................ \N{LAO KO LA}"
+)
+
+string_with_nameescape_and_escaped_backslash = (
+    "...................................................................... \\\N{LAO KO LA}"
+)
+
+string_with_nameescape_and_escaped_backslash = (
+    "......................................................................... \\\N{LAO KO LA}"
+)
+
+string_with_nameescape_and_escaped_backslash = (
+    ".......................................................................... \\\N{LAO KO LA}"
+)
+
+string_with_escaped_nameescape = (
+    "........................................................................ \\N{LAO KO LA}"
+)
+
+string_with_escaped_nameescape = (
+    "........................................................................... \\N{LAO KO LA}"
+)
+
 
 # output
 
@@ -587,3 +619,43 @@ def foo():
     "This is a really long string that can't be merged because it has a likely pragma at the end"  # pylint: disable=some-pylint-check
     " of it."
 )
+
+string_with_nameescape = (
+    "........................................................................"
+    " \N{LAO KO LA}"
+)
+
+string_with_nameescape = (
+    "..........................................................................."
+    " \N{LAO KO LA}"
+)
+
+string_with_nameescape = (
+    "............................................................................"
+    " \N{LAO KO LA}"
+)
+
+string_with_nameescape_and_escaped_backslash = (
+    "......................................................................"
+    " \\\N{LAO KO LA}"
+)
+
+string_with_nameescape_and_escaped_backslash = (
+    "........................................................................."
+    " \\\N{LAO KO LA}"
+)
+
+string_with_nameescape_and_escaped_backslash = (
+    ".........................................................................."
+    " \\\N{LAO KO LA}"
+)
+
+string_with_escaped_nameescape = (
+    "........................................................................ \\N{LAO"
+    " KO LA}"
+)
+
+string_with_escaped_nameescape = (
+    "..........................................................................."
+    " \\N{LAO KO LA}"
+)
diff --git a/tests/data/long_strings__regression.py b/tests/data/long_strings__regression.py
index e4234b2f97c..61c28d376ef 100644
--- a/tests/data/long_strings__regression.py
+++ b/tests/data/long_strings__regression.py
@@ -514,6 +514,10 @@ async def foo(self):
 
 x = F"This is a long string which contains an f-expr that should not split {{{[i for i in range(5)]}}}."
 
+x = (
+    "\N{BLACK RIGHT-POINTING TRIANGLE WITH DOUBLE VERTICAL BAR}\N{VARIATION SELECTOR-16}"
+)
+
 
 # output
 
@@ -1142,3 +1146,7 @@ async def foo(self):
     "This is a long string which contains an f-expr that should not split"
     f" {{{[i for i in range(5)]}}}."
 )
+
+x = (
+    "\N{BLACK RIGHT-POINTING TRIANGLE WITH DOUBLE VERTICAL BAR}\N{VARIATION SELECTOR-16}"
+)

From 2c5150c7c679b939ba05de1050a2b839cd4f8c96 Mon Sep 17 00:00:00 2001
From: jack1142 <6032823+jack1142@users.noreply.github.com>
Date: Wed, 9 Jun 2021 22:33:53 +0200
Subject: [PATCH 0242/1034] Don't run Docker workflow on push to forks (#2324)

---
 .github/workflows/docker.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
index 788c505ee4a..419ec74ba3c 100644
--- a/.github/workflows/docker.yml
+++ b/.github/workflows/docker.yml
@@ -9,6 +9,7 @@ on:
 
 jobs:
   docker:
+    if: github.repository == 'psf/black'
     runs-on: ubuntu-latest
     steps:
       - name: Checkout

From 77021f0fb203969d0c2437f1f9dc38f08a1b69fb Mon Sep 17 00:00:00 2001
From: jack1142 <6032823+jack1142@users.noreply.github.com>
Date: Wed, 9 Jun 2021 22:33:59 +0200
Subject: [PATCH 0243/1034] Add coverage files to gitignore (#2323)

---
 .gitignore | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.gitignore b/.gitignore
index f487d96cb3d..da7328c2865 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,6 @@
 .venv
 .coverage
+.coverage.*
 _build
 .DS_Store
 .vscode

From 93c10bf9ebccf8d7cc686b0b9579f2e5e41c5328 Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Thu, 10 Jun 2021 15:25:47 -0700
Subject: [PATCH 0244/1034] Update CHANGES.md for 21.6b0 release (#2325)

---
 CHANGES.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index 01c02fe2b70..caaf1c3d7ad 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,6 +1,6 @@
 # Change Log
 
-## Unreleased
+## 21.6b0
 
 ### _Black_
 

From 05b54b84327cfd1089cc4d630c7c65880252bcb4 Mon Sep 17 00:00:00 2001
From: Ryan McPartlan <ryanmcp45@gmail.com>
Date: Thu, 10 Jun 2021 20:45:43 -0400
Subject: [PATCH 0245/1034] Fix incorrect document referance (#2326)

---
 .pre-commit-config.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 2527c4d42ab..207766b0b3a 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -1,5 +1,5 @@
 # Note: don't use this config for your own repositories. Instead, see
-# "Version control integration" in README.md.
+# "Version control integration" in docs/integrations/source_version_control.md
 exclude: ^(src/blib2to3/|profiling/|tests/data/)
 repos:
   - repo: local

From aa31a117b16ed849710cf13cea5c064839beb29e Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Thu, 10 Jun 2021 21:06:50 -0700
Subject: [PATCH 0246/1034] Add STDIN test to primer (#2315)

* Add STDIN test to primer

- Check that out STDIN black support stays working
- Add asyncio.subprocess STDIN pip via communicate
- We just check we format python code from primer's `lib.py`

Fixes #2310
---
 CHANGES.md                   |  6 +++++
 src/black_primer/lib.py      | 45 +++++++++++++++++++++++++++---------
 src/black_primer/primer.json |  7 ++++++
 tests/test_primer.py         | 17 ++++++++++----
 4 files changed, 60 insertions(+), 15 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index caaf1c3d7ad..d22062ad542 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,5 +1,11 @@
 # Change Log
 
+## Unreleased
+
+### _Black_
+
+- Add primer support and test for code piped into black via STDIN (#2315)
+
 ## 21.6b0
 
 ### _Black_
diff --git a/src/black_primer/lib.py b/src/black_primer/lib.py
index df67602b6a5..784134bf652 100644
--- a/src/black_primer/lib.py
+++ b/src/black_primer/lib.py
@@ -42,16 +42,18 @@ async def _gen_check_output(
     timeout: float = 600,
     env: Optional[Dict[str, str]] = None,
     cwd: Optional[Path] = None,
+    stdin: Optional[bytes] = None,
 ) -> Tuple[bytes, bytes]:
     process = await asyncio.create_subprocess_exec(
         *cmd,
+        stdin=asyncio.subprocess.PIPE,
         stdout=asyncio.subprocess.PIPE,
         stderr=asyncio.subprocess.STDOUT,
         env=env,
         cwd=cwd,
     )
     try:
-        (stdout, stderr) = await asyncio.wait_for(process.communicate(), timeout)
+        (stdout, stderr) = await asyncio.wait_for(process.communicate(stdin), timeout)
     except asyncio.TimeoutError:
         process.kill()
         await process.wait()
@@ -112,20 +114,35 @@ def analyze_results(project_count: int, results: Results) -> int:
 
 
 async def black_run(
-    repo_path: Path,
+    project_name: str,
+    repo_path: Optional[Path],
     project_config: Dict[str, Any],
     results: Results,
     no_diff: bool = False,
 ) -> None:
     """Run Black and record failures"""
+    if not repo_path:
+        results.stats["failed"] += 1
+        results.failed_projects[project_name] = CalledProcessError(
+            69, [], f"{project_name} has no repo_path: {repo_path}".encode(), b""
+        )
+        return
+
+    stdin_test = project_name.upper() == "STDIN"
     cmd = [str(which(BLACK_BINARY))]
     if "cli_arguments" in project_config and project_config["cli_arguments"]:
         cmd.extend(project_config["cli_arguments"])
     cmd.append("--check")
-    if no_diff:
-        cmd.append(".")
+    if not no_diff:
+        cmd.append("--diff")
+
+    # Workout if we should read in a python file or search from cwd
+    stdin = None
+    if stdin_test:
+        cmd.append("-")
+        stdin = repo_path.read_bytes()
     else:
-        cmd.extend(["--diff", "."])
+        cmd.append(".")
 
     with TemporaryDirectory() as tmp_path:
         # Prevent reading top-level user configs by manipulating environment variables
@@ -135,8 +152,11 @@ async def black_run(
             "USERPROFILE": tmp_path,  # Windows (changes `Path.home()` output)
         }
 
+        cwd_path = repo_path.parent if stdin_test else repo_path
         try:
-            _stdout, _stderr = await _gen_check_output(cmd, cwd=repo_path, env=env)
+            _stdout, _stderr = await _gen_check_output(
+                cmd, cwd=cwd_path, env=env, stdin=stdin
+            )
         except asyncio.TimeoutError:
             results.stats["failed"] += 1
             LOG.error(f"Running black for {repo_path} timed out ({cmd})")
@@ -289,12 +309,15 @@ async def project_runner(
             LOG.debug(f"Skipping {project_name} as it's configured as a long checkout")
             continue
 
-        repo_path = await git_checkout_or_rebase(work_path, project_config, rebase)
-        if not repo_path:
-            continue
-        await black_run(repo_path, project_config, results, no_diff)
+        repo_path: Optional[Path] = Path(__file__)
+        stdin_project = project_name.upper() == "STDIN"
+        if not stdin_project:
+            repo_path = await git_checkout_or_rebase(work_path, project_config, rebase)
+            if not repo_path:
+                continue
+        await black_run(project_name, repo_path, project_config, results, no_diff)
 
-        if not keep:
+        if not keep and not stdin_project:
             LOG.debug(f"Removing {repo_path}")
             rmtree_partial = partial(
                 rmtree, path=repo_path, onerror=handle_PermissionError
diff --git a/src/black_primer/primer.json b/src/black_primer/primer.json
index f1035a819ce..90643987942 100644
--- a/src/black_primer/primer.json
+++ b/src/black_primer/primer.json
@@ -1,6 +1,13 @@
 {
   "configuration_format_version": 20200509,
   "projects": {
+    "STDIN": {
+      "cli_arguments": ["--experimental-string-processing"],
+      "expect_formatting_changes": false,
+      "git_clone_url": "",
+      "long_checkout": false,
+      "py_versions": ["all"]
+    },
     "aioexabgp": {
       "cli_arguments": ["--experimental-string-processing"],
       "expect_formatting_changes": false,
diff --git a/tests/test_primer.py b/tests/test_primer.py
index 8bfecd61a57..3c1ec2f929f 100644
--- a/tests/test_primer.py
+++ b/tests/test_primer.py
@@ -106,13 +106,16 @@ def test_analyze_results(self) -> None:
     def test_black_run(self) -> None:
         """Pretend to run Black to ensure we cater for all scenarios"""
         loop = asyncio.get_event_loop()
+        project_name = "unittest"
         repo_path = Path(gettempdir())
         project_config = deepcopy(FAKE_PROJECT_CONFIG)
         results = lib.Results({"failed": 0, "success": 0}, {})
 
         # Test a successful Black run
         with patch("black_primer.lib._gen_check_output", return_subproccess_output):
-            loop.run_until_complete(lib.black_run(repo_path, project_config, results))
+            loop.run_until_complete(
+                lib.black_run(project_name, repo_path, project_config, results)
+            )
         self.assertEqual(1, results.stats["success"])
         self.assertFalse(results.failed_projects)
 
@@ -120,7 +123,9 @@ def test_black_run(self) -> None:
         project_config["expect_formatting_changes"] = True
         results = lib.Results({"failed": 0, "success": 0}, {})
         with patch("black_primer.lib._gen_check_output", return_subproccess_output):
-            loop.run_until_complete(lib.black_run(repo_path, project_config, results))
+            loop.run_until_complete(
+                lib.black_run(project_name, repo_path, project_config, results)
+            )
         self.assertEqual(1, results.stats["failed"])
         self.assertTrue(results.failed_projects)
 
@@ -128,13 +133,17 @@ def test_black_run(self) -> None:
         project_config["expect_formatting_changes"] = False
         results = lib.Results({"failed": 0, "success": 0}, {})
         with patch("black_primer.lib._gen_check_output", raise_subprocess_error_1):
-            loop.run_until_complete(lib.black_run(repo_path, project_config, results))
+            loop.run_until_complete(
+                lib.black_run(project_name, repo_path, project_config, results)
+            )
         self.assertEqual(1, results.stats["failed"])
         self.assertTrue(results.failed_projects)
 
         # Test a formatting error based on returning 123
         with patch("black_primer.lib._gen_check_output", raise_subprocess_error_123):
-            loop.run_until_complete(lib.black_run(repo_path, project_config, results))
+            loop.run_until_complete(
+                lib.black_run(project_name, repo_path, project_config, results)
+            )
         self.assertEqual(2, results.stats["failed"])
 
     @event_loop()

From 4a007a881fa9d7757820657056aa376c05e49e9e Mon Sep 17 00:00:00 2001
From: Austin Glaser <austin.glaser@gmail.com>
Date: Sat, 12 Jun 2021 12:52:49 -0700
Subject: [PATCH 0247/1034] Find pyproject from vim relative to current file
 (#1871)

Commit history before merge:

* Find pyproject from vim relative to current file
* Merge remote-tracking branch 'upstream/main' into find-pyproject-vim
* Finish and fix this patch (thanks Matt Wozniski!)

Both the existing code and the proposed code are broken.
The vim.eval() call (whether it's vim.eval("@%") or
vim.eval("fnamemodify(getcwd(), ':t')) returns a string, and it passes
that string to find_pyproject_toml, which expects a sequence of strings,
not a single string, and - since a string is a sequence of single
character strings - it gets turned into a list of ridiculous paths. I
tested with a file called foo.py, and added a print(path_srcs) into
find_project_root, which printed out:

[
  PosixPath('/home/matt/f'),
  PosixPath('/home/matt/o'),
  PosixPath('/home/matt/o'),
  PosixPath('/home/matt'),
  PosixPath('/home/matt/p'),
  PosixPath('/home/matt/y')
]

This does work for an unnamed buffer, too - we wind up calling
black.find_pyproject_toml(("",)), and that winds up prepending the
working directory to any relative paths, so "" just gets turned into
the current working directory.

Note that find_pyproject_toml needs to be passed a 1-tuple, not a
list, because it requires something hashable (thanks to
functools.lru_cache being used)

Co-authored-by: Matt Wozniski <mwozniski@bloomberg.net>

* I forgot the CHANGELOG entry ... again
* I'm really bad at dealing with merge conflicts sometimes
* Be more correct describing search behaviour

Co-authored-by: Austin Glaser <austin.glaser@spacex.com>
Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
Co-authored-by: Matt Wozniski <mwozniski@bloomberg.net>
---
 CHANGES.md         | 5 +++++
 autoload/black.vim | 3 ++-
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index d22062ad542..a5205ba7a06 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -22,6 +22,11 @@
 - Fix handling of named escapes (`\N{...}`) when `--experimental-string-processing` is
   used (#2319)
 
+### Integrations
+
+- The vim plugin now searches upwards from the directory containing the current buffer
+  instead of the current working directory for pyproject.toml. (#1871)
+
 ## 21.5b2
 
 ### _Black_
diff --git a/autoload/black.vim b/autoload/black.vim
index f0357b07123..0d93aa899d0 100644
--- a/autoload/black.vim
+++ b/autoload/black.vim
@@ -139,7 +139,8 @@ def Black():
       print(f'Reformatted in {time.time() - start:.4f}s.')
 
 def get_configs():
-  path_pyproject_toml = black.find_pyproject_toml(vim.eval("fnamemodify(getcwd(), ':t')"))
+  filename = vim.eval("@%")
+  path_pyproject_toml = black.find_pyproject_toml((filename,))
   if path_pyproject_toml:
     toml_config = black.parse_pyproject_toml(path_pyproject_toml)
   else:

From 52384bf0a3fe4b0d0a11daad6ef90b8cd948a773 Mon Sep 17 00:00:00 2001
From: Bartosz Telenczuk <bartosz@telenczuk.pl>
Date: Sat, 12 Jun 2021 21:55:10 +0200
Subject: [PATCH 0248/1034] Vim plugin fix string normalization option (#1869)

This commit fixes parsing of the skip-string-normalization option in vim
plugin. Originally, the plugin read the string-normalization option,
which does not exist in help (--help) and it's not respected by black
on command line.

Commit history before merge:

* fix string normalization option in vim plugin
* fix string normalization option in vim plugin
* Finish and fix patch (thanks Matt Wozniski!)

FYI: this is totally the work and the comments below of Matt (AKA godlygeek)

This fixes two entirely different problems related to how pyproject.toml
files are handled by the vim plugin.

=== Problem #1 ===

The plugin fails to properly read boolean values from pyproject.toml.
For instance, if you create this pyproject.toml:

```
[tool.black]
quiet = true
```

the Black CLI is happy with it and runs without any messages, but the
:Black command provided by this plugin fails with:

```
Traceback (most recent call last):
  File "<string>", line 1, in <module>
  File "<string>", line 102, in Black
  File "<string>", line 150, in get_configs
  File "<string>", line 150, in <dictcomp>
  File "/usr/lib/python3.6/distutils/util.py", line 311, in strtobool
    val = val.lower()
AttributeError: 'bool' object has no attribute 'lower'
```

That's because the value returned by the toml.load() is already a
bool, but the vim plugin incorrectly tries to convert it from a str to a bool.

The value returned by toml_config.get() was always being passed to
flag.cast(), which is a function that either converts a string to an
int or a string to a bool, depending on the flag. vim.eval()
returns integers and strings all as str, which is why we need the cast,
but that's the wrong thing to do for values that came from toml.load().
We should be applying the cast only to the return from vim.eval()
(since we know it always gives us a string), rather than casting the
value that toml.load() found - which is already the right type.

=== Problem #2 ===

The vim plugin fails to take the value for skip_string_normalization
from pyproject.toml. That's because it looks for a string_normalization
key instead of a skip_string_normalization key, thanks to this line
saying the name of the flag is string_normalization:

black/autoload/black.vim (line 25 in 05b54b8)
```
 Flag(name="string_normalization", cast=strtobool),
```

and this dictcomp looking up each flag's name in the config dict:

black/autoload/black.vim (lines 148 to 151 in 05b54b8)
```
 return {
   flag.var_name: flag.cast(toml_config.get(flag.name, vim.eval(flag.vim_rc_name)))
   for flag in FLAGS
 }
```

For the second issue, I think I'd do a slightly different patch. I'd
keep the change to invert this flag's meaning and change its name that
this PR proposes, but I'd also change the handling of the
g:black_skip_string_normalization and g:black_string_normalization
variables to make it clear that g:black_skip_string_normalization is
the expected name, and g:black_string_normalization is only checked
when the expected name is unset, for backwards compatibility.

My proposed behavior is to check if g:black_skip_string_normalization
is defined and to define it if not, using the inverse of
g:black_string_normalization if that is set, and otherwise to the
default of 0. The Python code in autoload/black.vim runs later, and
will use the value of g:black_skip_string_normalization (and ignore
g:black_string_normalization; it will only be used to set
g:black_skip_string_normalization if it wasn't already set).

---

Co-authored-by: Matt Wozniski <mwozniski@bloomberg.net>

* Fix plugin/black.vim (need to up my vim game)

Co-authored-by: Matt Wozniski <godlygeek@gmail.com>

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
Co-authored-by: Matt Wozniski <mwozniski@bloomberg.net>
Co-authored-by: Matt Wozniski <godlygeek@gmail.com>
---
 CHANGES.md         | 7 +++++++
 autoload/black.vim | 6 +++---
 plugin/black.vim   | 8 ++++----
 3 files changed, 14 insertions(+), 7 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index a5205ba7a06..403723b70cc 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -27,6 +27,13 @@
 - The vim plugin now searches upwards from the directory containing the current buffer
   instead of the current working directory for pyproject.toml. (#1871)
 
+### Integrations
+
+- The vim plugin now reads the correct string normalization option in pyproject.toml
+  (#1869)
+- The vim plugin no longer crashes Black when there's boolean values in pyproject.toml
+  (#1869)
+
 ## 21.5b2
 
 ### _Black_
diff --git a/autoload/black.vim b/autoload/black.vim
index 0d93aa899d0..29d8f2b88e4 100644
--- a/autoload/black.vim
+++ b/autoload/black.vim
@@ -22,7 +22,7 @@ class Flag(collections.namedtuple("FlagBase", "name, cast")):
 FLAGS = [
   Flag(name="line_length", cast=int),
   Flag(name="fast", cast=strtobool),
-  Flag(name="string_normalization", cast=strtobool),
+  Flag(name="skip_string_normalization", cast=strtobool),
   Flag(name="quiet", cast=strtobool),
 ]
 
@@ -103,7 +103,7 @@ def Black():
   configs = get_configs()
   mode = black.FileMode(
     line_length=configs["line_length"],
-    string_normalization=configs["string_normalization"],
+    string_normalization=not configs["skip_string_normalization"],
     is_pyi=vim.current.buffer.name.endswith('.pyi'),
   )
   quiet = configs["quiet"]
@@ -147,7 +147,7 @@ def get_configs():
     toml_config = {}
 
   return {
-    flag.var_name: flag.cast(toml_config.get(flag.name, vim.eval(flag.vim_rc_name)))
+    flag.var_name: toml_config.get(flag.name, flag.cast(vim.eval(flag.vim_rc_name)))
     for flag in FLAGS
   }
 
diff --git a/plugin/black.vim b/plugin/black.vim
index b5edb2a6ade..3bdca62e6ad 100644
--- a/plugin/black.vim
+++ b/plugin/black.vim
@@ -43,11 +43,11 @@ endif
 if !exists("g:black_linelength")
   let g:black_linelength = 88
 endif
-if !exists("g:black_string_normalization")
-  if exists("g:black_skip_string_normalization")
-    let g:black_string_normalization = !g:black_skip_string_normalization
+if !exists("g:black_skip_string_normalization")
+  if exists("g:black_string_normalization")
+    let g:black_skip_string_normalization = !g:black_string_normalization
   else
-    let g:black_string_normalization = 1
+    let g:black_skip_string_normalization = 0
   endif
 endif
 if !exists("g:black_quiet")

From e2fd914dc172a13c0e6395d2d08efa5a25380381 Mon Sep 17 00:00:00 2001
From: Bryan Bugyi <bryanbugyi34@gmail.com>
Date: Sun, 13 Jun 2021 13:20:50 -0400
Subject: [PATCH 0249/1034] Fix internal error when FORCE_OPTIONAL_PARENTHESES
 feature is enabled (#2332)

Fixes #2313.
---
 CHANGES.md                             |  1 +
 src/black/linegen.py                   | 21 +++++++++++++--------
 tests/data/long_strings__regression.py | 14 ++++++++++++++
 3 files changed, 28 insertions(+), 8 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 403723b70cc..12e8fccbe4e 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -5,6 +5,7 @@
 ### _Black_
 
 - Add primer support and test for code piped into black via STDIN (#2315)
+- Fix internal error when `FORCE_OPTIONAL_PARENTHESES` feature is enabled (#2332)
 
 ## 21.6b0
 
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 3b811f02b7c..76b553a959a 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -961,14 +961,19 @@ def run_transformer(
 
         result.extend(transform_line(transformed_line, mode=mode, features=features))
 
-    if not (
-        transform.__name__ == "rhs"
-        and line.bracket_tracker.invisible
-        and not any(bracket.value for bracket in line.bracket_tracker.invisible)
-        and not line.contains_multiline_strings()
-        and not result[0].contains_uncollapsable_type_comments()
-        and not result[0].contains_unsplittable_type_ignore()
-        and not is_line_short_enough(result[0], line_length=mode.line_length)
+    if (
+        transform.__name__ != "rhs"
+        or not line.bracket_tracker.invisible
+        or any(bracket.value for bracket in line.bracket_tracker.invisible)
+        or line.contains_multiline_strings()
+        or result[0].contains_uncollapsable_type_comments()
+        or result[0].contains_unsplittable_type_ignore()
+        or is_line_short_enough(result[0], line_length=mode.line_length)
+        # If any leaves have no parents (which _can_ occur since
+        # `transform(line)` potentially destroys the line's underlying node
+        # structure), then we can't proceed. Doing so would cause the below
+        # call to `append_leaves()` to fail.
+        or any(leaf.parent is None for leaf in line.leaves)
     ):
         return result
 
diff --git a/tests/data/long_strings__regression.py b/tests/data/long_strings__regression.py
index 61c28d376ef..36f323e04d6 100644
--- a/tests/data/long_strings__regression.py
+++ b/tests/data/long_strings__regression.py
@@ -518,6 +518,12 @@ async def foo(self):
     "\N{BLACK RIGHT-POINTING TRIANGLE WITH DOUBLE VERTICAL BAR}\N{VARIATION SELECTOR-16}"
 )
 
+xxxxxx_xxx_xxxx_xx_xxxxx_xxxxxxxx_xxxxxxxx_xxxxxxxxxx_xxxx_xxxx_xxxxx = xxxx.xxxxxx.xxxxxxxxx.xxxxxxxxxxxxxxxxxxxx(
+    xx_xxxxxx={
+        "x3_xxxxxxxx": "xxx3_xxxxx_xxxxxxxx_xxxxxxxx_xxxxxxxxxx_xxxxxxxx_xxxxxx_xxxxxxx",
+    },
+)
+
 
 # output
 
@@ -1150,3 +1156,11 @@ async def foo(self):
 x = (
     "\N{BLACK RIGHT-POINTING TRIANGLE WITH DOUBLE VERTICAL BAR}\N{VARIATION SELECTOR-16}"
 )
+
+xxxxxx_xxx_xxxx_xx_xxxxx_xxxxxxxx_xxxxxxxx_xxxxxxxxxx_xxxx_xxxx_xxxxx = xxxx.xxxxxx.xxxxxxxxx.xxxxxxxxxxxxxxxxxxxx(
+    xx_xxxxxx={
+        "x3_xxxxxxxx": (
+            "xxx3_xxxxx_xxxxxxxx_xxxxxxxx_xxxxxxxxxx_xxxxxxxx_xxxxxx_xxxxxxx"
+        ),
+    },
+)

From 52f402dcfbeb49d4710b2c8d2b15563b08369fc5 Mon Sep 17 00:00:00 2001
From: jack1142 <6032823+jack1142@users.noreply.github.com>
Date: Sun, 13 Jun 2021 19:22:46 +0200
Subject: [PATCH 0250/1034] Add EOF and trailing whitespace fixer to pre-commit
 config (#2330)

---
 .gitignore               | 2 +-
 .pre-commit-config.yaml  | 6 ++++++
 docs/Makefile            | 2 +-
 docs/_static/license.svg | 2 +-
 pyproject.toml           | 2 +-
 src/black/py.typed       | 1 -
 tests/test.toml          | 1 -
 7 files changed, 10 insertions(+), 6 deletions(-)

diff --git a/.gitignore b/.gitignore
index da7328c2865..ab796ce4cd0 100644
--- a/.gitignore
+++ b/.gitignore
@@ -17,4 +17,4 @@ src/_black_version.py
 .dmypy.json
 *.swp
 .hypothesis/
-venv/
\ No newline at end of file
+venv/
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 207766b0b3a..be60ff2e635 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -28,3 +28,9 @@ repos:
     rev: v2.2.1
     hooks:
       - id: prettier
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.0.1
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
diff --git a/docs/Makefile b/docs/Makefile
index 2e0e5eeaf9d..cb0463c842b 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -17,4 +17,4 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
\ No newline at end of file
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/_static/license.svg b/docs/_static/license.svg
index 36bea29f654..25aa18b91af 100644
--- a/docs/_static/license.svg
+++ b/docs/_static/license.svg
@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="78" height="20"><linearGradient id="b" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="a"><rect width="78" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#a)"><path fill="#555" d="M0 0h47v20H0z"/><path fill="#7900CA" d="M47 0h31v20H47z"/><path fill="url(#b)" d="M0 0h78v20H0z"/></g><g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="110"><text x="245" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="370">license</text><text x="245" y="140" transform="scale(.1)" textLength="370">license</text><text x="615" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="210">MIT</text><text x="615" y="140" transform="scale(.1)" textLength="210">MIT</text></g> </svg>
\ No newline at end of file
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="78" height="20"><linearGradient id="b" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="a"><rect width="78" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#a)"><path fill="#555" d="M0 0h47v20H0z"/><path fill="#7900CA" d="M47 0h31v20H47z"/><path fill="url(#b)" d="M0 0h78v20H0z"/></g><g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="110"><text x="245" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="370">license</text><text x="245" y="140" transform="scale(.1)" textLength="370">license</text><text x="615" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="210">MIT</text><text x="615" y="140" transform="scale(.1)" textLength="210">MIT</text></g> </svg>
diff --git a/pyproject.toml b/pyproject.toml
index 4d6777ef6ec..79060fc422d 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -31,4 +31,4 @@ build-backend = "setuptools.build_meta"
 optional-tests = [
   "no_python2: run when `python2` extra NOT installed",
   "no_blackd: run when `d` extra NOT installed",
-]
\ No newline at end of file
+]
diff --git a/src/black/py.typed b/src/black/py.typed
index 8b137891791..e69de29bb2d 100644
--- a/src/black/py.typed
+++ b/src/black/py.typed
@@ -1 +0,0 @@
-
diff --git a/tests/test.toml b/tests/test.toml
index 405c00ce2c3..570c2f26b15 100644
--- a/tests/test.toml
+++ b/tests/test.toml
@@ -7,4 +7,3 @@ line-length = 79
 target-version = ["py36", "py37", "py38"]
 exclude='\.pyi?$'
 include='\.py?$'
-

From bd7f49df3e16b52f0b287c28427c306e6c1064c8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Felix=20Hild=C3=A9n?= <felix.hilden@gmail.com>
Date: Sun, 13 Jun 2021 22:27:57 +0300
Subject: [PATCH 0251/1034] Docs: no space is inserted to empty docstrings
 (#2249) (#2333)

---
 docs/the_black_code_style/current_style.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/the_black_code_style/current_style.md b/docs/the_black_code_style/current_style.md
index aa2dd881a9e..b9ab350cd12 100644
--- a/docs/the_black_code_style/current_style.md
+++ b/docs/the_black_code_style/current_style.md
@@ -275,7 +275,7 @@ for both quotations and the text within, although relative indentation in the te
 preserved. Superfluous trailing whitespace on each line and unnecessary new lines at the
 end of the docstring are removed. All leading tabs are converted to spaces, but tabs
 inside text are preserved. Whitespace leading and trailing one-line docstrings is
-removed. The quotations of an empty docstring are separated with one space.
+removed.
 
 ### Numeric literals
 

From 742ddd156121ea593349dcf864c8aaafeb08b809 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Felix=20Hild=C3=A9n?= <felix.hilden@gmail.com>
Date: Tue, 15 Jun 2021 17:37:59 +0300
Subject: [PATCH 0252/1034] Chat on Discord instead of Freenode (#2336)

Now that we've moved, let's direct our users to Discord in the
documentation and readme.
---
 README.md      | 2 +-
 docs/index.rst | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 7b4aeee8baa..0b5c7ee39c3 100644
--- a/README.md
+++ b/README.md
@@ -200,7 +200,7 @@ You can also take a look at the rest of the contributing docs or talk with the
 developers:
 
 - [Contributing documentation](https://black.readthedocs.io/en/latest/contributing/index.html)
-- [IRC channel on Freenode](https://webchat.freenode.net/?channels=%23blackformatter)
+- [Chat on Discord](https://discord.gg/RtVdv86PrH)
 
 ## Change log
 
diff --git a/docs/index.rst b/docs/index.rst
index 44b800cadf8..1515697f556 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -119,7 +119,7 @@ Contents
 
    GitHub ↪ <https://github.com/psf/black>
    PyPI ↪ <https://pypi.org/project/black>
-   IRC ↪ <https://webchat.freenode.net/?channels=%23blackformatter>
+   Chat ↪ <https://discord.gg/RtVdv86PrH>
 
 Indices and tables
 ==================

From 8d8b3d18059b7f11871eaa376c288f14549dd342 Mon Sep 17 00:00:00 2001
From: Art Chaidarun <art@duolingo.com>
Date: Thu, 17 Jun 2021 12:32:03 -0400
Subject: [PATCH 0253/1034] Add Duolingo to list of users (#2341)

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 0b5c7ee39c3..0f1953df341 100644
--- a/README.md
+++ b/README.md
@@ -135,7 +135,7 @@ code style: pytest, tox, Pyramid, Django Channels, Hypothesis, attrs, SQLAlchemy
 Poetry, PyPA applications (Warehouse, Bandersnatch, Pipenv, virtualenv), pandas, Pillow,
 every Datadog Agent Integration, Home Assistant, Zulip.
 
-The following organizations use _Black_: Facebook, Dropbox, Mozilla, Quora.
+The following organizations use _Black_: Facebook, Dropbox, Mozilla, Quora, Duolingo.
 
 Are we missing anyone? Let us know.
 

From 3980b4b1767a35c6d99f9231f14d4690d0a270c2 Mon Sep 17 00:00:00 2001
From: SADIK KUZU <sadikkuzu@hotmail.com>
Date: Tue, 22 Jun 2021 04:28:25 +0300
Subject: [PATCH 0254/1034] Update pre-commit config (#2331)

via `pre-commit autoupdate`

```
Updating https://gitlab.com/pycqa/flake8
... updating 3.9.0 -> 3.9.2.
Updating https://github.com/pre-commit/mirrors-mypy
... updating v0.812 -> v0.902.
Updating https://github.com/pre-commit/mirrors-prettier
... updating v2.2.1 -> v2.3.1.
```

Signed-off-by: SADIK KUZU <sadikkuzu@hotmail.com>

* Add necessary typeshed packages to requirements

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 .pre-commit-config.yaml |  12 ++-
 Pipfile                 |   6 +-
 Pipfile.lock            | 229 +++++++++++++++++++++++++---------------
 3 files changed, 156 insertions(+), 91 deletions(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index be60ff2e635..920ae669d71 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -13,21 +13,27 @@ repos:
         types_or: [python, pyi]
 
   - repo: https://gitlab.com/pycqa/flake8
-    rev: 3.9.0
+    rev: 3.9.2
     hooks:
       - id: flake8
         additional_dependencies: [flake8-bugbear]
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v0.812
+    rev: v0.902
     hooks:
       - id: mypy
         exclude: ^docs/conf.py
+        additional_dependencies:
+          - types-dataclasses >= 0.1.3
+          - types-toml >= 0.1.1
+          - types-typed-ast >= 1.4.1
+          - types-click >= 7.1.2
 
   - repo: https://github.com/pre-commit/mirrors-prettier
-    rev: v2.2.1
+    rev: v2.3.1
     hooks:
       - id: prettier
+        exclude: ^Pipfile\.lock
 
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.0.1
diff --git a/Pipfile b/Pipfile
index 789d97c3cbc..f617fdc0a67 100644
--- a/Pipfile
+++ b/Pipfile
@@ -10,6 +10,10 @@ docutils = "==0.15"  # not a direct dependency, see https://github.com/pypa/pipe
 flake8 = "*"
 flake8-bugbear = "*"
 mypy = ">=0.812"
+types-click = ">=7.1.2"
+types-dataclasses = ">=0.1.3"
+types-toml = ">=0.1.1"
+types-typed-ast = ">=1.4.1"
 pre-commit = "*"
 readme_renderer = "*"
 MyST-Parser = ">=0.13.7"
@@ -33,4 +37,4 @@ toml = ">=0.10.1"
 typed-ast = "==1.4.2"
 typing_extensions = {"python_version <" = "3.8","version >=" = "3.7.4"}
 black = {editable = true,extras = ["d"],path = "."}
-dataclasses = {"python_version <" = "3.7","version >" = "0.6"}
+dataclasses = {"python_version <" = "3.7","version >" = "0.1.3"}
diff --git a/Pipfile.lock b/Pipfile.lock
index 4f0b51e7d18..17140de2983 100644
--- a/Pipfile.lock
+++ b/Pipfile.lock
@@ -1,7 +1,7 @@
 {
     "_meta": {
         "hash": {
-            "sha256": "b450e698cfe4d856397cb9d0695dcd74eb97b1d234de273179d78c0d0efccd0f"
+            "sha256": "18ff16725509d6d14f44e3a96fe620730c9adfdaa87cbeee74aa397913dedaab"
         },
         "pipfile-spec": 6,
         "requires": {},
@@ -78,6 +78,7 @@
                 "sha256:0c3c816a028d47f659d6ff5c745cb2acf1f966da1fe5c19c77a70282b25f4c5f",
                 "sha256:4291ca197d287d274d0b6cb5d6f8f8f82d434ed288f962539ff18cc9012f9ea3"
             ],
+            "markers": "python_full_version >= '3.5.3'",
             "version": "==3.0.1"
         },
         "attrs": {
@@ -85,6 +86,7 @@
                 "sha256:149e90d6d8ac20db7a955ad60cf0e6881a3f20d37096140088356da6c716b0b1",
                 "sha256:ef6aaac3ca6cd92904cdd0d83f629a15f18053ec84e6432106f7a4d04ae4f5fb"
             ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
             "version": "==21.2.0"
         },
         "black": {
@@ -99,15 +101,16 @@
                 "sha256:0d6f53a15db4120f2b08c94f11e7d93d2c911ee118b6b30a04ec3ee8310179fa",
                 "sha256:f864054d66fd9118f2e67044ac8981a54775ec5b67aed0441892edb553d21da5"
             ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
             "version": "==4.0.0"
         },
         "click": {
             "hashes": [
-                "sha256:7d8c289ee437bcb0316820ccee14aefcb056e58d31830ecab8e47eda6540e136",
-                "sha256:e90e62ced43dc8105fb9a26d62f0d9340b5c8db053a814e25d95c19873ae87db"
+                "sha256:8c04c11192119b1ef78ea049e0a6f0463e4c48ef00a30160c704337586f3ad7a",
+                "sha256:fba402a4a47334742d782209a7c79bc448911afe1149d07bdabdf480b3e2f4b6"
             ],
             "index": "pypi",
-            "version": "==8.0.0"
+            "version": "==8.0.1"
         },
         "dataclasses": {
             "hashes": [
@@ -115,13 +118,16 @@
                 "sha256:6988bd2b895eef432d562370bb707d540f32f7360ab13da45340101bc2307d84"
             ],
             "index": "pypi",
-            "version": "==0.6"
+            "python_version <": "3.7",
+            "version": "==0.6",
+            "version >": "0.1.3"
         },
         "idna": {
             "hashes": [
                 "sha256:14475042e284991034cb48e06f6851428fb14c4dc953acd9be9a5e95c7b6dd7a",
                 "sha256:467fbad99067910785144ce333826c71fb0e63a425657295239737f7ecd125f3"
             ],
+            "markers": "python_version >= '3.5'",
             "version": "==3.2"
         },
         "multidict": {
@@ -164,6 +170,7 @@
                 "sha256:f21756997ad8ef815d8ef3d34edd98804ab5ea337feedcd62fb52d22bf531281",
                 "sha256:fc13a9524bc18b6fb6e0dbec3533ba0496bbed167c56d0aabefd965584557d80"
             ],
+            "markers": "python_version >= '3.6'",
             "version": "==5.1.0"
         },
         "mypy-extensions": {
@@ -229,6 +236,14 @@
             "index": "pypi",
             "version": "==2021.4.4"
         },
+        "setuptools-scm": {
+            "hashes": [
+                "sha256:c3bd5f701c8def44a5c0bfe8d407bef3f80342217ef3492b951f3777bd2d915c",
+                "sha256:d1925a69cb07e9b29416a275b9fadb009a23c148ace905b2fb220649a6c18e92"
+            ],
+            "markers": "python_version >= '3.6'",
+            "version": "==6.0.1"
+        },
         "toml": {
             "hashes": [
                 "sha256:806143ae5bfb6a3c6e736a764057db0e6a0e05e338b5630894a5f779cabb4f9b",
@@ -280,7 +295,9 @@
                 "sha256:779383f6086d90c99ae41cf0ff39aac8a7937a9283ce0a414e5dd782f4c94a84"
             ],
             "index": "pypi",
-            "version": "==3.10.0.0"
+            "python_version <": "3.8",
+            "version": "==3.10.0.0",
+            "version >=": "3.7.4"
         },
         "yarl": {
             "hashes": [
@@ -322,6 +339,7 @@
                 "sha256:f0b059678fd549c66b89bed03efcabb009075bd131c248ecdf087bdb6faba24a",
                 "sha256:fcbb48a93e8699eae920f8d92f7160c03567b421bc17362a9ffbbd706a816f71"
             ],
+            "markers": "python_version >= '3.6'",
             "version": "==1.6.3"
         }
     },
@@ -397,6 +415,7 @@
                 "sha256:0c3c816a028d47f659d6ff5c745cb2acf1f966da1fe5c19c77a70282b25f4c5f",
                 "sha256:4291ca197d287d274d0b6cb5d6f8f8f82d434ed288f962539ff18cc9012f9ea3"
             ],
+            "markers": "python_full_version >= '3.5.3'",
             "version": "==3.0.1"
         },
         "attrs": {
@@ -404,6 +423,7 @@
                 "sha256:149e90d6d8ac20db7a955ad60cf0e6881a3f20d37096140088356da6c716b0b1",
                 "sha256:ef6aaac3ca6cd92904cdd0d83f629a15f18053ec84e6432106f7a4d04ae4f5fb"
             ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
             "version": "==21.2.0"
         },
         "babel": {
@@ -411,6 +431,7 @@
                 "sha256:ab49e12b91d937cd11f0b67cb259a57ab4ad2b59ac7a3b41d6c06c0ac5b0def9",
                 "sha256:bc0c176f9f6a994582230df350aa6e05ba2ebe4b3ac317eab29d9be5d2768da0"
             ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==2.9.1"
         },
         "black": {
@@ -425,6 +446,7 @@
                 "sha256:6123ddc1052673e52bab52cdc955bcb57a015264a1c57d37bea2f6b817af0125",
                 "sha256:98b3170739e5e83dd9dc19633f074727ad848cbedb6026708c8ac2d3b697a433"
             ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
             "version": "==3.3.0"
         },
         "certifi": {
@@ -493,6 +515,7 @@
                 "sha256:9e600479b3b99e8af981ecdfc80a0296104ee610cab48a5ae4ffd0b668650eb1",
                 "sha256:b449c9c6118fe8cca7fa5e00b9ec60ba08145d281d52164230a69211c5d597a1"
             ],
+            "markers": "python_full_version >= '3.6.1'",
             "version": "==3.3.0"
         },
         "chardet": {
@@ -500,21 +523,23 @@
                 "sha256:0d6f53a15db4120f2b08c94f11e7d93d2c911ee118b6b30a04ec3ee8310179fa",
                 "sha256:f864054d66fd9118f2e67044ac8981a54775ec5b67aed0441892edb553d21da5"
             ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
             "version": "==4.0.0"
         },
         "click": {
             "hashes": [
-                "sha256:7d8c289ee437bcb0316820ccee14aefcb056e58d31830ecab8e47eda6540e136",
-                "sha256:e90e62ced43dc8105fb9a26d62f0d9340b5c8db053a814e25d95c19873ae87db"
+                "sha256:8c04c11192119b1ef78ea049e0a6f0463e4c48ef00a30160c704337586f3ad7a",
+                "sha256:fba402a4a47334742d782209a7c79bc448911afe1149d07bdabdf480b3e2f4b6"
             ],
             "index": "pypi",
-            "version": "==8.0.0"
+            "version": "==8.0.1"
         },
         "colorama": {
             "hashes": [
                 "sha256:5941b2b48a20143d2267e95b1c2a7603ce057ee39fd88e7329b0c292aa16869b",
                 "sha256:9f47eda37229f68eee03b24b9748937c7dc3868f906e8ba69fbcbdd3bc5dc3e2"
             ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
             "version": "==0.4.4"
         },
         "coverage": {
@@ -590,6 +615,7 @@
                 "sha256:eb8cc2afe8b05acbd84a43905832ec78e7b3873fb124ca190f574dca7389a87d",
                 "sha256:ee77aa129f481be46f8d92a1a7db57269a2f23052d5f2433b4621bb457081cc9"
             ],
+            "markers": "python_version >= '3.6'",
             "version": "==3.4.7"
         },
         "distlib": {
@@ -602,6 +628,7 @@
         "docutils": {
             "hashes": [
                 "sha256:54a349c622ff31c91cbec43b0b512f113b5b24daf00e2ea530bb1bd9aac14849",
+                "sha256:ba4584f9107571ced0d2c7f56a5499c696215ba90797849c92d395979da68521",
                 "sha256:d2ddba74835cb090a1b627d3de4e7835c628d07ee461f7b4480f51af2fe4d448"
             ],
             "index": "pypi",
@@ -632,16 +659,18 @@
         },
         "identify": {
             "hashes": [
-                "sha256:92d6ad08eca19ceb17576733759944b94c0761277ddc3acf65e75e57ef190e32",
-                "sha256:c29e74c3671fe9537715cb695148231d777170ca1498e1c30c675d4ea782afe9"
+                "sha256:18d0c531ee3dbc112fa6181f34faa179de3f57ea57ae2899754f16a7e0ff6421",
+                "sha256:5b41f71471bc738e7b586308c3fca172f78940195cb3bf6734c1e66fdac49306"
             ],
-            "version": "==2.2.7"
+            "markers": "python_full_version >= '3.6.1'",
+            "version": "==2.2.10"
         },
         "idna": {
             "hashes": [
                 "sha256:14475042e284991034cb48e06f6851428fb14c4dc953acd9be9a5e95c7b6dd7a",
                 "sha256:467fbad99067910785144ce333826c71fb0e63a425657295239737f7ecd125f3"
             ],
+            "markers": "python_version >= '3.5'",
             "version": "==3.2"
         },
         "imagesize": {
@@ -649,14 +678,16 @@
                 "sha256:6965f19a6a2039c7d48bca7dba2473069ff854c36ae6f19d2cde309d998228a1",
                 "sha256:b1f6b5a4eab1f73479a50fb79fcf729514a900c341d8503d62a62dbc4127a2b1"
             ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==1.2.0"
         },
         "importlib-metadata": {
             "hashes": [
-                "sha256:960d52ba7c21377c990412aca380bf3642d734c2eaab78a2c39319f67c6a5786",
-                "sha256:e592faad8de1bda9fe920cf41e15261e7131bcf266c30306eec00e8e225c1dd5"
+                "sha256:833b26fb89d5de469b24a390e9df088d4e52e4ba33b01dc5e0e4f41b81a16c00",
+                "sha256:b142cc1dd1342f31ff04bb7d022492b09920cb64fed867cd3ea6f80fe3ebd139"
             ],
-            "version": "==4.4.0"
+            "markers": "python_version >= '3.6'",
+            "version": "==4.5.0"
         },
         "jeepney": {
             "hashes": [
@@ -671,6 +702,7 @@
                 "sha256:1f06f2da51e7b56b8f238affdd6b4e2c61e39598a378cc49345bc1bd42a978a4",
                 "sha256:703f484b47a6af502e743c9122595cc812b0271f661722403114f71a79d0f5a4"
             ],
+            "markers": "python_version >= '3.6'",
             "version": "==3.0.1"
         },
         "keyring": {
@@ -678,6 +710,7 @@
                 "sha256:045703609dd3fccfcdb27da201684278823b72af515aedec1a8515719a038cb8",
                 "sha256:8f607d7d1cc502c43a932a275a56fe47db50271904513a379d39df1af277ac48"
             ],
+            "markers": "python_version >= '3.6'",
             "version": "==23.0.1"
         },
         "markdown-it-py": {
@@ -685,6 +718,7 @@
                 "sha256:36be6bb3ad987bfdb839f5ba78ddf094552ca38ccbd784ae4f74a4e1419fc6e3",
                 "sha256:98080fc0bc34c4f2bcf0846a096a9429acbd9d5d8e67ed34026c03c61c464389"
             ],
+            "markers": "python_version ~= '3.6'",
             "version": "==1.1.0"
         },
         "markupsafe": {
@@ -724,6 +758,7 @@
                 "sha256:f9081981fe268bd86831e5c75f7de206ef275defcb82bc70740ae6dc507aee51",
                 "sha256:fa130dd50c57d53368c9d59395cb5526eda596d3ffe36666cd81a44d56e48872"
             ],
+            "markers": "python_version >= '3.6'",
             "version": "==2.0.1"
         },
         "mccabe": {
@@ -738,6 +773,7 @@
                 "sha256:1833bf738e038e35d89cb3a07eb0d227ed647ce7dd357579b65343740c6d249c",
                 "sha256:5991cef645502e80a5388ec4fc20885d2313d4871e8b8e320ca2de14ac0c015f"
             ],
+            "markers": "python_version ~= '3.6'",
             "version": "==0.2.8"
         },
         "multidict": {
@@ -780,35 +816,37 @@
                 "sha256:f21756997ad8ef815d8ef3d34edd98804ab5ea337feedcd62fb52d22bf531281",
                 "sha256:fc13a9524bc18b6fb6e0dbec3533ba0496bbed167c56d0aabefd965584557d80"
             ],
+            "markers": "python_version >= '3.6'",
             "version": "==5.1.0"
         },
         "mypy": {
             "hashes": [
-                "sha256:0d0a87c0e7e3a9becdfbe936c981d32e5ee0ccda3e0f07e1ef2c3d1a817cf73e",
-                "sha256:25adde9b862f8f9aac9d2d11971f226bd4c8fbaa89fb76bdadb267ef22d10064",
-                "sha256:28fb5479c494b1bab244620685e2eb3c3f988d71fd5d64cc753195e8ed53df7c",
-                "sha256:2f9b3407c58347a452fc0736861593e105139b905cca7d097e413453a1d650b4",
-                "sha256:33f159443db0829d16f0a8d83d94df3109bb6dd801975fe86bacb9bf71628e97",
-                "sha256:3f2aca7f68580dc2508289c729bd49ee929a436208d2b2b6aab15745a70a57df",
-                "sha256:499c798053cdebcaa916eef8cd733e5584b5909f789de856b482cd7d069bdad8",
-                "sha256:4eec37370483331d13514c3f55f446fc5248d6373e7029a29ecb7b7494851e7a",
-                "sha256:552a815579aa1e995f39fd05dde6cd378e191b063f031f2acfe73ce9fb7f9e56",
-                "sha256:5873888fff1c7cf5b71efbe80e0e73153fe9212fafdf8e44adfe4c20ec9f82d7",
-                "sha256:61a3d5b97955422964be6b3baf05ff2ce7f26f52c85dd88db11d5e03e146a3a6",
-                "sha256:674e822aa665b9fd75130c6c5f5ed9564a38c6cea6a6432ce47eafb68ee578c5",
-                "sha256:7ce3175801d0ae5fdfa79b4f0cfed08807af4d075b402b7e294e6aa72af9aa2a",
-                "sha256:9743c91088d396c1a5a3c9978354b61b0382b4e3c440ce83cf77994a43e8c521",
-                "sha256:9f94aac67a2045ec719ffe6111df543bac7874cee01f41928f6969756e030564",
-                "sha256:a26f8ec704e5a7423c8824d425086705e381b4f1dfdef6e3a1edab7ba174ec49",
-                "sha256:abf7e0c3cf117c44d9285cc6128856106183938c68fd4944763003decdcfeb66",
-                "sha256:b09669bcda124e83708f34a94606e01b614fa71931d356c1f1a5297ba11f110a",
-                "sha256:cd07039aa5df222037005b08fbbfd69b3ab0b0bd7a07d7906de75ae52c4e3119",
-                "sha256:d23e0ea196702d918b60c8288561e722bf437d82cb7ef2edcd98cfa38905d506",
-                "sha256:d65cc1df038ef55a99e617431f0553cd77763869eebdf9042403e16089fe746c",
-                "sha256:d7da2e1d5f558c37d6e8c1246f1aec1e7349e4913d8fb3cb289a35de573fe2eb"
+                "sha256:0190fb77e93ce971954c9e54ea61de2802065174e5e990c9d4c1d0f54fbeeca2",
+                "sha256:0756529da2dd4d53d26096b7969ce0a47997123261a5432b48cc6848a2cb0bd4",
+                "sha256:2f9fedc1f186697fda191e634ac1d02f03d4c260212ccb018fabbb6d4b03eee8",
+                "sha256:353aac2ce41ddeaf7599f1c73fed2b75750bef3b44b6ad12985a991bc002a0da",
+                "sha256:3f12705eabdd274b98f676e3e5a89f247ea86dc1af48a2d5a2b080abac4e1243",
+                "sha256:4efc67b9b3e2fddbe395700f91d5b8deb5980bfaaccb77b306310bd0b9e002eb",
+                "sha256:517e7528d1be7e187a5db7f0a3e479747307c1b897d9706b1c662014faba3116",
+                "sha256:68a098c104ae2b75e946b107ef69dd8398d54cb52ad57580dfb9fc78f7f997f0",
+                "sha256:746e0b0101b8efec34902810047f26a8c80e1efbb4fc554956d848c05ef85d76",
+                "sha256:8be7bbd091886bde9fcafed8dd089a766fa76eb223135fe5c9e9798f78023a20",
+                "sha256:9236c21194fde5df1b4d8ebc2ef2c1f2a5dc7f18bcbea54274937cae2e20a01c",
+                "sha256:9ef5355eaaf7a23ab157c21a44c614365238a7bdb3552ec3b80c393697d974e1",
+                "sha256:9f1d74eeb3f58c7bd3f3f92b8f63cb1678466a55e2c4612bf36909105d0724ab",
+                "sha256:a26d0e53e90815c765f91966442775cf03b8a7514a4e960de7b5320208b07269",
+                "sha256:ae94c31bb556ddb2310e4f913b706696ccbd43c62d3331cd3511caef466871d2",
+                "sha256:b5ba1f0d5f9087e03bf5958c28d421a03a4c1ad260bf81556195dffeccd979c4",
+                "sha256:b5dfcd22c6bab08dfeded8d5b44bdcb68c6f1ab261861e35c470b89074f78a70",
+                "sha256:cd01c599cf9f897b6b6c6b5d8b182557fb7d99326bcdf5d449a0fbbb4ccee4b9",
+                "sha256:e89880168c67cf4fde4506b80ee42f1537ad66ad366c101d388b3fd7d7ce2afd",
+                "sha256:ebe2bc9cb638475f5d39068d2dbe8ae1d605bb8d8d3ff281c695df1670ab3987",
+                "sha256:f89bfda7f0f66b789792ab64ce0978e4a991a0e4dd6197349d0767b0f1095b21",
+                "sha256:fc4d63da57ef0e8cd4ab45131f3fe5c286ce7dd7f032650d0fbc239c6190e167",
+                "sha256:fd634bc17b1e2d6ce716f0e43446d0d61cdadb1efcad5c56ca211c22b246ebc8"
             ],
             "index": "pypi",
-            "version": "==0.812"
+            "version": "==0.902"
         },
         "mypy-extensions": {
             "hashes": [
@@ -820,11 +858,11 @@
         },
         "myst-parser": {
             "hashes": [
-                "sha256:8d7db76e2f33cd1dc1fe0c76af9f09e5cf19ce2c2e85074bc82f272c0f7c08ce",
-                "sha256:fc262959a74cdc799d7fa9b30c320c17187485b9a1e8c39e988fc12f3adff63c"
+                "sha256:7c3c78a36c4bc30ce6a67933ebd800a880c8d81f1688fad5c2ebd82cddbc1603",
+                "sha256:e8baa9959dac0bcf0f3ea5fc32a1a28792959471d8a8094e3ed5ee0de9733ade"
             ],
             "index": "pypi",
-            "version": "==0.14.0"
+            "version": "==0.15.1"
         },
         "nodeenv": {
             "hashes": [
@@ -838,6 +876,7 @@
                 "sha256:5b327ac1320dc863dca72f4514ecc086f31186744b84a230374cc1fd776feae5",
                 "sha256:67714da7f7bc052e064859c05c595155bd1ee9f69f76557e21f051443c20947a"
             ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==20.9"
         },
         "pathspec": {
@@ -857,17 +896,18 @@
         },
         "pre-commit": {
             "hashes": [
-                "sha256:70c5ec1f30406250b706eda35e868b87e3e4ba099af8787e3e8b4b01e84f4712",
-                "sha256:900d3c7e1bf4cf0374bb2893c24c23304952181405b4d88c9c40b72bda1bb8a9"
+                "sha256:764972c60693dc668ba8e86eb29654ec3144501310f7198742a767bec385a378",
+                "sha256:b679d0fddd5b9d6d98783ae5f10fd0c4c59954f375b70a58cbe1ce9bcf9809a4"
             ],
             "index": "pypi",
-            "version": "==2.12.1"
+            "version": "==2.13.0"
         },
         "pycodestyle": {
             "hashes": [
                 "sha256:514f76d918fcc0b55c6680472f0a37970994e07bbb80725808c17089be302068",
                 "sha256:c389c1d06bf7904078ca03399a4816f974a1d590090fecea0c63ec26ebaf1cef"
             ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==2.7.0"
         },
         "pycparser": {
@@ -875,6 +915,7 @@
                 "sha256:2d475327684562c3a96cc71adf7dc8c4f0565175cf86b6d7a404ff4c771f15f0",
                 "sha256:7582ad22678f0fcd81102833f60ef8d0e57288b6b5fb00323d101be910e35705"
             ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==2.20"
         },
         "pyflakes": {
@@ -882,6 +923,7 @@
                 "sha256:7893783d01b8a89811dd72d7dfd4d84ff098e5eed95cfa8905b22bbffe52efc3",
                 "sha256:f5bc8ecabc05bb9d291eb5203d6810b49040f6ff446a756326104746cc00c1db"
             ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==2.3.1"
         },
         "pygments": {
@@ -889,6 +931,7 @@
                 "sha256:a18f47b506a429f6f4b9df81bb02beab9ca21d0a5fee38ed15aef65f0545519f",
                 "sha256:d66e804411278594d764fc69ec36ec13d9ae9147193a1740cd34d272ca383b8e"
             ],
+            "markers": "python_version >= '3.5'",
             "version": "==2.9.0"
         },
         "pyparsing": {
@@ -896,6 +939,7 @@
                 "sha256:c203ec8783bf771a155b207279b9bccb8dea02d8f0c9e5f8ead507bc3246ecc1",
                 "sha256:ef9d7589ef3c200abe66653d3f1ab1033c3c419ae9b9bdb1240a85b024efc88b"
             ],
+            "markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==2.4.7"
         },
         "pytz": {
@@ -937,6 +981,7 @@
                 "sha256:fdc842473cd33f45ff6bce46aea678a54e3d21f1b61a7750ce3c498eedfe25d6",
                 "sha256:fe69978f3f768926cfa37b867e3843918e012cf83f680806599ddce33c2c68b0"
             ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4, 3.5'",
             "version": "==5.4.1"
         },
         "readme-renderer": {
@@ -999,6 +1044,7 @@
                 "sha256:27973dd4a904a4f13b263a19c866c13b92a39ed1c964655f025f3f8d3d75b804",
                 "sha256:c210084e36a42ae6b9219e00e48287def368a26d03a048ddad7bfee44f75871e"
             ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
             "version": "==2.25.1"
         },
         "requests-toolbelt": {
@@ -1028,7 +1074,7 @@
                 "sha256:c3bd5f701c8def44a5c0bfe8d407bef3f80342217ef3492b951f3777bd2d915c",
                 "sha256:d1925a69cb07e9b29416a275b9fadb009a23c148ace905b2fb220649a6c18e92"
             ],
-            "index": "pypi",
+            "markers": "python_version >= '3.6'",
             "version": "==6.0.1"
         },
         "six": {
@@ -1036,6 +1082,7 @@
                 "sha256:1e61c37477a1626458e36f7b1d82aa5c9b094fa4802892072e49de9c60c4c926",
                 "sha256:8abb2f1d86890a2dfb989f9a77cfcfd3e47c2a354b01111771326f8aa26e0254"
             ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==1.16.0"
         },
         "snowballstemmer": {
@@ -1047,25 +1094,26 @@
         },
         "sphinx": {
             "hashes": [
-                "sha256:19010b7b9fa0dc7756a6e105b2aacd3a80f798af3c25c273be64d7beeb482cb1",
-                "sha256:2320d4e994a191f4b4be27da514e46b3d6b420f2ff895d064f52415d342461e8"
+                "sha256:b5c2ae4120bf00c799ba9b3699bc895816d272d120080fbc967292f29b52b48c",
+                "sha256:d1cb10bee9c4231f1700ec2e24a91be3f3a3aba066ea4ca9f3bbe47e59d5a1d4"
             ],
             "index": "pypi",
-            "version": "==3.5.4"
+            "version": "==4.0.2"
         },
         "sphinx-copybutton": {
             "hashes": [
-                "sha256:0e0461df394515284e3907e3f418a0c60ef6ab6c9a27a800c8552772d0a402a2",
-                "sha256:5125c718e763596e6e52d92e15ee0d6f4800ad3817939be6dee51218870b3e3d"
+                "sha256:19850e9c1ed09c899f136ce3cfa304cb3b6d2f508528c19d8f512ccc8c66b0d4",
+                "sha256:3695987d5e98e3b223471aaed8aa7491e03e9bfc48ed655a91446fd5e30b6c25"
             ],
             "index": "pypi",
-            "version": "==0.3.1"
+            "version": "==0.3.3"
         },
         "sphinxcontrib-applehelp": {
             "hashes": [
                 "sha256:806111e5e962be97c29ec4c1e7fe277bfd19e9652fb1a4392105b43e01af885a",
                 "sha256:a072735ec80e7675e3f432fcae8610ecf509c5f1869d17e2eecff44389cdbc58"
             ],
+            "markers": "python_version >= '3.5'",
             "version": "==1.0.2"
         },
         "sphinxcontrib-devhelp": {
@@ -1073,6 +1121,7 @@
                 "sha256:8165223f9a335cc1af7ffe1ed31d2871f325254c0423bc0c4c7cd1c1e4734a2e",
                 "sha256:ff7f1afa7b9642e7060379360a67e9c41e8f3121f2ce9164266f61b9f4b338e4"
             ],
+            "markers": "python_version >= '3.5'",
             "version": "==1.0.2"
         },
         "sphinxcontrib-htmlhelp": {
@@ -1080,6 +1129,7 @@
                 "sha256:d412243dfb797ae3ec2b59eca0e52dac12e75a241bf0e4eb861e450d06c6ed07",
                 "sha256:f5f8bb2d0d629f398bf47d0d69c07bc13b65f75a81ad9e2f71a63d4b7a2f6db2"
             ],
+            "markers": "python_version >= '3.6'",
             "version": "==2.0.0"
         },
         "sphinxcontrib-jsmath": {
@@ -1087,6 +1137,7 @@
                 "sha256:2ec2eaebfb78f3f2078e73666b1415417a116cc848b72e5172e596c871103178",
                 "sha256:a9925e4a4587247ed2191a22df5f6970656cb8ca2bd6284309578f2153e0c4b8"
             ],
+            "markers": "python_version >= '3.5'",
             "version": "==1.0.1"
         },
         "sphinxcontrib-programoutput": {
@@ -1102,6 +1153,7 @@
                 "sha256:4c33767ee058b70dba89a6fc5c1892c0d57a54be67ddd3e7875a18d14cba5a72",
                 "sha256:bd9fc24bcb748a8d51fd4ecaade681350aa63009a347a8c14e637895444dfab6"
             ],
+            "markers": "python_version >= '3.5'",
             "version": "==1.0.3"
         },
         "sphinxcontrib-serializinghtml": {
@@ -1109,6 +1161,7 @@
                 "sha256:352a9a00ae864471d3a7ead8d7d79f5fc0b57e8b3f95e9867eb9eb28999b92fd",
                 "sha256:aa5f6de5dfdf809ef505c4895e51ef5c9eac17d0f287933eb49ec495280b6952"
             ],
+            "markers": "python_version >= '3.5'",
             "version": "==1.1.5"
         },
         "toml": {
@@ -1121,10 +1174,11 @@
         },
         "tqdm": {
             "hashes": [
-                "sha256:736524215c690621b06fc89d0310a49822d75e599fcd0feb7cc742b98d692493",
-                "sha256:cd5791b5d7c3f2f1819efc81d36eb719a38e0906a7380365c556779f585ea042"
+                "sha256:24be966933e942be5f074c29755a95b315c69a91f839a29139bf26ffffe2d3fd",
+                "sha256:aa0c29f03f298951ac6318f7c8ce584e48fa22ec26396e6411e43d038243bdb2"
             ],
-            "version": "==4.61.0"
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
+            "version": "==4.61.1"
         },
         "twine": {
             "hashes": [
@@ -1134,38 +1188,34 @@
             "index": "pypi",
             "version": "==3.4.1"
         },
-        "typed-ast": {
+        "types-click": {
             "hashes": [
-                "sha256:07d49388d5bf7e863f7fa2f124b1b1d89d8aa0e2f7812faff0a5658c01c59aa1",
-                "sha256:14bf1522cdee369e8f5581238edac09150c765ec1cb33615855889cf33dcb92d",
-                "sha256:240296b27397e4e37874abb1df2a608a92df85cf3e2a04d0d4d61055c8305ba6",
-                "sha256:36d829b31ab67d6fcb30e185ec996e1f72b892255a745d3a82138c97d21ed1cd",
-                "sha256:37f48d46d733d57cc70fd5f30572d11ab8ed92da6e6b28e024e4a3edfb456e37",
-                "sha256:4c790331247081ea7c632a76d5b2a265e6d325ecd3179d06e9cf8d46d90dd151",
-                "sha256:5dcfc2e264bd8a1db8b11a892bd1647154ce03eeba94b461effe68790d8b8e07",
-                "sha256:7147e2a76c75f0f64c4319886e7639e490fee87c9d25cb1d4faef1d8cf83a440",
-                "sha256:7703620125e4fb79b64aa52427ec192822e9f45d37d4b6625ab37ef403e1df70",
-                "sha256:8368f83e93c7156ccd40e49a783a6a6850ca25b556c0fa0240ed0f659d2fe496",
-                "sha256:84aa6223d71012c68d577c83f4e7db50d11d6b1399a9c779046d75e24bed74ea",
-                "sha256:85f95aa97a35bdb2f2f7d10ec5bbdac0aeb9dafdaf88e17492da0504de2e6400",
-                "sha256:8db0e856712f79c45956da0c9a40ca4246abc3485ae0d7ecc86a20f5e4c09abc",
-                "sha256:9044ef2df88d7f33692ae3f18d3be63dec69c4fb1b5a4a9ac950f9b4ba571606",
-                "sha256:963c80b583b0661918718b095e02303d8078950b26cc00b5e5ea9ababe0de1fc",
-                "sha256:987f15737aba2ab5f3928c617ccf1ce412e2e321c77ab16ca5a293e7bbffd581",
-                "sha256:9ec45db0c766f196ae629e509f059ff05fc3148f9ffd28f3cfe75d4afb485412",
-                "sha256:9fc0b3cb5d1720e7141d103cf4819aea239f7d136acf9ee4a69b047b7986175a",
-                "sha256:a2c927c49f2029291fbabd673d51a2180038f8cd5a5b2f290f78c4516be48be2",
-                "sha256:a38878a223bdd37c9709d07cd357bb79f4c760b29210e14ad0fb395294583787",
-                "sha256:b4fcdcfa302538f70929eb7b392f536a237cbe2ed9cba88e3bf5027b39f5f77f",
-                "sha256:c0c74e5579af4b977c8b932f40a5464764b2f86681327410aa028a22d2f54937",
-                "sha256:c1c876fd795b36126f773db9cbb393f19808edd2637e00fd6caba0e25f2c7b64",
-                "sha256:c9aadc4924d4b5799112837b226160428524a9a45f830e0d0f184b19e4090487",
-                "sha256:cc7b98bf58167b7f2db91a4327da24fb93368838eb84a44c472283778fc2446b",
-                "sha256:cf54cfa843f297991b7388c281cb3855d911137223c6b6d2dd82a47ae5125a41",
-                "sha256:d003156bb6a59cda9050e983441b7fa2487f7800d76bdc065566b7d728b4581a",
-                "sha256:d175297e9533d8d37437abc14e8a83cbc68af93cc9c1c59c2c292ec59a0697a3",
-                "sha256:d746a437cdbca200622385305aedd9aef68e8a645e385cc483bdc5e488f07166",
-                "sha256:e683e409e5c45d5c9082dc1daf13f6374300806240719f95dc783d1fc942af10"
+                "sha256:040897284e4f9466825c3865f708a985a8e7ba4d8e22cb9198ffb7b522160850",
+                "sha256:4722746f1ec9fd3fc8b1d7fb8c840604dc22f9e32bcc7a31a36d6d85cc2bce24"
+            ],
+            "index": "pypi",
+            "version": "==7.1.2"
+        },
+        "types-dataclasses": {
+            "hashes": [
+                "sha256:7b5f4099fb21c209f2df3a83c2b64308c29955769d610a457244dc0eebe1cafc",
+                "sha256:c19491cfb981bff9cafd9c113c291a7a54adccc6298ded8ca3de0d7abe211984"
+            ],
+            "index": "pypi",
+            "version": "==0.1.5"
+        },
+        "types-toml": {
+            "hashes": [
+                "sha256:33ebe67bebaec55a123ecbaa2bd98fe588335d8d8dda2c7ac53502ef5a81a79a",
+                "sha256:d4add39a90993173d49ff0b069edd122c66ad4cf5c01082b590e380ca670ee1a"
+            ],
+            "index": "pypi",
+            "version": "==0.1.3"
+        },
+        "types-typed-ast": {
+            "hashes": [
+                "sha256:014ab2742015d3eaab86ea061c27809c7e76beeb9e134102f2e2ddb34ab05c62",
+                "sha256:6a47165760321835d160da20a6ac5b9065f23d6dc246162508cad1ef1238afc3"
             ],
             "index": "pypi",
             "version": "==1.4.2"
@@ -1177,14 +1227,16 @@
                 "sha256:779383f6086d90c99ae41cf0ff39aac8a7937a9283ce0a414e5dd782f4c94a84"
             ],
             "index": "pypi",
-            "version": "==3.10.0.0"
+            "python_version <": "3.8",
+            "version": "==3.10.0.0",
+            "version >=": "3.7.4"
         },
         "urllib3": {
             "hashes": [
                 "sha256:753a0374df26658f99d826cfe40394a686d05985786d946fbe4165b5148f5a7c",
                 "sha256:a7acd0977125325f516bda9735fa7142b909a8d01e8b2e4c8108d0984e6e0098"
             ],
-            "index": "pypi",
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4' and python_version < '4'",
             "version": "==1.26.5"
         },
         "virtualenv": {
@@ -1192,6 +1244,7 @@
                 "sha256:14fdf849f80dbb29a4eb6caa9875d476ee2a5cf76a5f5415fa2f1606010ab467",
                 "sha256:2b0126166ea7c9c3661f5b8e06773d28f83322de7a3ff7d06f0aed18c9de6a76"
             ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==20.4.7"
         },
         "webencodings": {
@@ -1249,6 +1302,7 @@
                 "sha256:f0b059678fd549c66b89bed03efcabb009075bd131c248ecdf087bdb6faba24a",
                 "sha256:fcbb48a93e8699eae920f8d92f7160c03567b421bc17362a9ffbbd706a816f71"
             ],
+            "markers": "python_version >= '3.6'",
             "version": "==1.6.3"
         },
         "zipp": {
@@ -1256,6 +1310,7 @@
                 "sha256:3607921face881ba3e026887d8150cca609d517579abe052ac81fc5aeffdbd76",
                 "sha256:51cb66cc54621609dd593d1787f286ee42a5c0adbb4b29abea5a63edc3e03098"
             ],
+            "markers": "python_version >= '3.6'",
             "version": "==3.4.1"
         }
     }

From be16cfa0353f33adf0ee5f026d9b46f9ca6ac7ac Mon Sep 17 00:00:00 2001
From: Taneli Hukkinen <3275109+hukkin@users.noreply.github.com>
Date: Tue, 22 Jun 2021 18:58:49 +0300
Subject: [PATCH 0255/1034] Get `click` types from main repo (#2344)

Click types have been moved to click repo itself. See pallets/click#1856

I've had some issues with typeshed types being outdated in another project
so might be good to avoid that here.

Commit history before merge:

* Get `click` types from main repo
* Fix mypy errors
* Require click v8 for type annotations
* Update Pipfile
---
 .pre-commit-config.yaml |  2 +-
 Pipfile                 |  3 +--
 Pipfile.lock            | 10 +---------
 tests/test_black.py     |  9 ++++++---
 4 files changed, 9 insertions(+), 15 deletions(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 920ae669d71..79795d1085f 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -27,7 +27,7 @@ repos:
           - types-dataclasses >= 0.1.3
           - types-toml >= 0.1.1
           - types-typed-ast >= 1.4.1
-          - types-click >= 7.1.2
+          - click >= 8.0.0
 
   - repo: https://github.com/pre-commit/mirrors-prettier
     rev: v2.3.1
diff --git a/Pipfile b/Pipfile
index f617fdc0a67..a27614c94a9 100644
--- a/Pipfile
+++ b/Pipfile
@@ -10,7 +10,6 @@ docutils = "==0.15"  # not a direct dependency, see https://github.com/pypa/pipe
 flake8 = "*"
 flake8-bugbear = "*"
 mypy = ">=0.812"
-types-click = ">=7.1.2"
 types-dataclasses = ">=0.1.3"
 types-toml = ">=0.1.1"
 types-typed-ast = ">=1.4.1"
@@ -29,7 +28,7 @@ black = {editable = true, extras = ["d"], path = "."}
 aiohttp = ">=3.6.0"
 aiohttp-cors = ">=0.4.0"
 appdirs = "*"
-click = ">=7.1.2"
+click = ">=8.0.0"
 mypy_extensions = ">=0.4.3"
 pathspec = ">=0.8.1"
 regex = ">=2020.1.8"
diff --git a/Pipfile.lock b/Pipfile.lock
index 17140de2983..d22131ee859 100644
--- a/Pipfile.lock
+++ b/Pipfile.lock
@@ -1,7 +1,7 @@
 {
     "_meta": {
         "hash": {
-            "sha256": "18ff16725509d6d14f44e3a96fe620730c9adfdaa87cbeee74aa397913dedaab"
+            "sha256": "0c126694d1a1cd1c4dc875a99f330f6b9a5994e51a1f870a98dbacd0185dae53"
         },
         "pipfile-spec": 6,
         "requires": {},
@@ -1188,14 +1188,6 @@
             "index": "pypi",
             "version": "==3.4.1"
         },
-        "types-click": {
-            "hashes": [
-                "sha256:040897284e4f9466825c3865f708a985a8e7ba4d8e22cb9198ffb7b522160850",
-                "sha256:4722746f1ec9fd3fc8b1d7fb8c840604dc22f9e32bcc7a31a36d6d85cc2bce24"
-            ],
-            "index": "pypi",
-            "version": "==7.1.2"
-        },
         "types-dataclasses": {
             "hashes": [
                 "sha256:7b5f4099fb21c209f2df3a83c2b64308c29955769d610a457244dc0eebe1cafc",
diff --git a/tests/test_black.py b/tests/test_black.py
index 455cb33e827..5262c0ee44c 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -119,6 +119,8 @@ def invokeBlack(
         if ignore_config:
             args = ["--verbose", "--config", str(THIS_DIR / "empty.toml"), *args]
         result = runner.invoke(black.main, args)
+        assert result.stdout_bytes is not None
+        assert result.stderr_bytes is not None
         self.assertEqual(
             result.exit_code,
             exit_code,
@@ -465,6 +467,7 @@ def test_python2_should_fail_without_optional_install(self) -> None:
             self.assertEqual(result.exit_code, 123)
         finally:
             os.unlink(tmp_file)
+        assert result.stderr_bytes is not None
         actual = (
             result.stderr_bytes.decode()
             .replace("\n", "")
@@ -1892,7 +1895,7 @@ def test_symlink_out_of_root_directory(self) -> None:
 
     def test_shhh_click(self) -> None:
         try:
-            from click import _unicodefun  # type: ignore
+            from click import _unicodefun
         except ModuleNotFoundError:
             self.skipTest("Incompatible Click version")
         if not hasattr(_unicodefun, "_verify_python3_env"):
@@ -1901,14 +1904,14 @@ def test_shhh_click(self) -> None:
         with patch("locale.getpreferredencoding") as gpe:
             gpe.return_value = "ASCII"
             with self.assertRaises(RuntimeError):
-                _unicodefun._verify_python3_env()
+                _unicodefun._verify_python3_env()  # type: ignore
         # Now, let's silence Click...
         black.patch_click()
         # ...and confirm it's silent.
         with patch("locale.getpreferredencoding") as gpe:
             gpe.return_value = "ASCII"
             try:
-                _unicodefun._verify_python3_env()
+                _unicodefun._verify_python3_env()  # type: ignore
             except RuntimeError as re:
                 self.fail(f"`patch_click()` failed, exception still raised: {re}")
 

From 017aafea992ca1c6d7af45d3013af7ddb7fda12a Mon Sep 17 00:00:00 2001
From: simaki <shota.imaki.0801@gmail.com>
Date: Thu, 24 Jun 2021 04:11:23 +0900
Subject: [PATCH 0256/1034] Accept empty stdin (close #2337) (#2346)

Commit history before merge:

* Accept empty stdin (close #2337)
* Update tests/test_black.py
* Add changelog
* Assert Black reformats an empty string to an empty string (#2337) (#2346)
* fix
---
 CHANGES.md            |  1 +
 src/black/__init__.py |  3 ++-
 tests/test_black.py   | 15 +++++++++++++++
 3 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index 12e8fccbe4e..ea5196e07a0 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -6,6 +6,7 @@
 
 - Add primer support and test for code piped into black via STDIN (#2315)
 - Fix internal error when `FORCE_OPTIONAL_PARENTHESES` feature is enabled (#2332)
+- Accept empty stdin (#2346)
 
 ## 21.6b0
 
diff --git a/src/black/__init__.py b/src/black/__init__.py
index a985926afa5..8e2123d50cc 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -803,7 +803,8 @@ def format_stdin_to_stdout(
         )
         if write_back == WriteBack.YES:
             # Make sure there's a newline after the content
-            dst += "" if dst[-1] == "\n" else "\n"
+            if dst and dst[-1] != "\n":
+                dst += "\n"
             f.write(dst)
         elif write_back in (WriteBack.DIFF, WriteBack.COLOR_DIFF):
             now = datetime.utcnow()
diff --git a/tests/test_black.py b/tests/test_black.py
index 5262c0ee44c..42ac119324c 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -6,6 +6,7 @@
 from contextlib import contextmanager
 from dataclasses import replace
 import inspect
+import io
 from io import BytesIO
 import os
 from pathlib import Path
@@ -1682,6 +1683,20 @@ def test_reformat_one_with_stdin_and_existing_path(self) -> None:
             # __BLACK_STDIN_FILENAME__ should have been stripped
             report.done.assert_called_with(expected, black.Changed.YES)
 
+    def test_reformat_one_with_stdin_empty(self) -> None:
+        output = io.StringIO()
+        with patch("io.TextIOWrapper", lambda *args, **kwargs: output):
+            try:
+                black.format_stdin_to_stdout(
+                    fast=True,
+                    content="",
+                    write_back=black.WriteBack.YES,
+                    mode=DEFAULT_MODE,
+                )
+            except io.UnsupportedOperation:
+                pass  # StringIO does not support detach
+            assert output.getvalue() == ""
+
     def test_gitignore_exclude(self) -> None:
         path = THIS_DIR / "data" / "include_exclude_tests"
         include = re.compile(r"\.pyi?$")

From 14072be245b909d2340e13c571e76bf36080cc5a Mon Sep 17 00:00:00 2001
From: Marco Edward Gorelli <marcogorelli@protonmail.com>
Date: Sun, 4 Jul 2021 19:23:00 +0100
Subject: [PATCH 0257/1034] fix typo (#2358)

---
 docs/integrations/github_actions.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/integrations/github_actions.md b/docs/integrations/github_actions.md
index d293c40dadf..e866a3cc616 100644
--- a/docs/integrations/github_actions.md
+++ b/docs/integrations/github_actions.md
@@ -3,7 +3,7 @@
 You can use _Black_ within a GitHub Actions workflow without setting your own Python
 environment. Great for enforcing that your code matches the _Black_ code style.
 
-## Compatiblity
+## Compatibility
 
 This action is known to support all GitHub-hosted runner OSes. In addition, only
 published versions of _Black_ are supported (i.e. whatever is available on PyPI).

From ae56983a5f36d69e2a8cfa762f255a800039b0df Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Thu, 8 Jul 2021 21:46:32 -0400
Subject: [PATCH 0258/1034] Avoid src being marked as optional in help (#2356)

---
 src/black/__init__.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index 8e2123d50cc..51384fb08da 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -328,6 +328,7 @@ def validate_regex(
         exists=True, file_okay=True, dir_okay=True, readable=True, allow_dash=True
     ),
     is_eager=True,
+    metavar="SRC ...",
 )
 @click.option(
     "--config",

From dd6c674e3a33ac6d20faea751764aeafecdf34c2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Felix=20Hild=C3=A9n?= <felix.hilden@gmail.com>
Date: Sat, 10 Jul 2021 03:09:29 +0300
Subject: [PATCH 0259/1034] Use setuptools.find_packages in setup (#2363)

* Use setuptools.find_packages in setup

* Address mypy errors
---
 setup.py                     | 4 ++--
 src/black_primer/__init__.py | 0
 src/black_primer/cli.py      | 6 +++---
 tests/test_primer.py         | 4 ++--
 4 files changed, 7 insertions(+), 7 deletions(-)
 create mode 100644 src/black_primer/__init__.py

diff --git a/setup.py b/setup.py
index 5549ae35342..95252eab054 100644
--- a/setup.py
+++ b/setup.py
@@ -1,5 +1,5 @@
 # Copyright (C) 2020 Łukasz Langa
-from setuptools import setup
+from setuptools import setup, find_packages
 import sys
 import os
 
@@ -62,7 +62,7 @@ def get_long_description() -> str:
     license="MIT",
     py_modules=["_black_version"],
     ext_modules=ext_modules,
-    packages=["blackd", "black", "blib2to3", "blib2to3.pgen2", "black_primer"],
+    packages=find_packages(where="src"),
     package_dir={"": "src"},
     package_data={
         "blib2to3": ["*.txt"],
diff --git a/src/black_primer/__init__.py b/src/black_primer/__init__.py
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/src/black_primer/cli.py b/src/black_primer/cli.py
index f0997049d21..8360fc3c703 100644
--- a/src/black_primer/cli.py
+++ b/src/black_primer/cli.py
@@ -7,7 +7,7 @@
 from pathlib import Path
 from shutil import rmtree, which
 from tempfile import gettempdir
-from typing import Any, Union
+from typing import Any, Union, Optional
 
 import click
 
@@ -29,8 +29,8 @@
 
 
 def _handle_debug(
-    ctx: click.core.Context,
-    param: Union[click.core.Option, click.core.Parameter],
+    ctx: Optional[click.core.Context],
+    param: Optional[Union[click.core.Option, click.core.Parameter]],
     debug: Union[bool, int, str],
 ) -> Union[bool, int, str]:
     """Turn on debugging if asked otherwise INFO default"""
diff --git a/tests/test_primer.py b/tests/test_primer.py
index 3c1ec2f929f..8dd1212313e 100644
--- a/tests/test_primer.py
+++ b/tests/test_primer.py
@@ -189,7 +189,7 @@ def test_process_queue(self, mock_stdout: Mock) -> None:
         with patch("black_primer.lib.git_checkout_or_rebase", return_false):
             with TemporaryDirectory() as td:
                 return_val = loop.run_until_complete(
-                    lib.process_queue(str(config_path), td, 2)
+                    lib.process_queue(str(config_path), Path(td), 2)
                 )
                 self.assertEqual(0, return_val)
 
@@ -210,7 +210,7 @@ def test_async_main(self) -> None:
             "no_diff": False,
         }
         with patch("black_primer.cli.lib.process_queue", return_zero):
-            return_val = loop.run_until_complete(cli.async_main(**args))
+            return_val = loop.run_until_complete(cli.async_main(**args))  # type: ignore
             self.assertEqual(0, return_val)
 
     def test_handle_debug(self) -> None:

From 548d6991610ae547b34e6c3058fc8299c9b25658 Mon Sep 17 00:00:00 2001
From: Marco Edward Gorelli <marcogorelli@protonmail.com>
Date: Sun, 11 Jul 2021 21:03:36 +0100
Subject: [PATCH 0260/1034] Second run of tox -e py results in a test error for
 test marked with no_python2 (#2369)

Fixes #2367
---
 tox.ini | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/tox.ini b/tox.ini
index 3ea4da8eac2..a97d18946b3 100644
--- a/tox.ini
+++ b/tox.ini
@@ -4,6 +4,10 @@ envlist = {,ci-}py{36,37,38,39},fuzz
 [testenv]
 setenv = PYTHONPATH = {toxinidir}/src
 skip_install = True
+# We use `recreate=True` because otherwise, on the second run of `tox -e py`,
+# the `no_python2` tests would run with the Python2 extra dependencies installed.
+# See https://github.com/psf/black/issues/2367.
+recreate = True
 deps =
     -r{toxinidir}/test_requirements.txt
 ; parallelization is disabled on CI because pytest-dev/pytest-xdist#620 occurs too frequently

From c64fb8cbb121f33f3897b403adffef0ed4314fdc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C5=81ukasz=20Langa?= <lukasz@langa.pl>
Date: Mon, 12 Jul 2021 11:56:03 +0200
Subject: [PATCH 0261/1034] Add LocalStack and Twisted to projects using Black

---
 README.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 0f1953df341..7b87a03fc38 100644
--- a/README.md
+++ b/README.md
@@ -133,7 +133,8 @@ code in compliance with many other _Black_ formatted projects.
 The following notable open-source projects trust _Black_ with enforcing a consistent
 code style: pytest, tox, Pyramid, Django Channels, Hypothesis, attrs, SQLAlchemy,
 Poetry, PyPA applications (Warehouse, Bandersnatch, Pipenv, virtualenv), pandas, Pillow,
-every Datadog Agent Integration, Home Assistant, Zulip.
+Twisted, LocalStack, every Datadog Agent Integration, Home Assistant, Zulip, and many
+more.
 
 The following organizations use _Black_: Facebook, Dropbox, Mozilla, Quora, Duolingo.
 

From 2946d3b03d499475ed2276e590516df46d01d01a Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Mon, 12 Jul 2021 16:01:38 -0400
Subject: [PATCH 0262/1034] Switch `toml` TOML library for `tomli` (#2301)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

toml unfortunately has a lack of maintainership issue right now. It's
evident by the fact toml only supports TOML v0.5.0. TOML v1.0.0 has
been recently released and right now Black crashes hard on its usage.

tomli is a brand new parse only TOML library. It supports TOML
v1.0.0. Although TBH we're switching to this one mostly because
pip is doing the same.

*The upper bound was included at the library maintainer's request.

Co-authored-by: Łukasz Langa <lukasz@langa.pl>
Co-authored-by: Taneli Hukkinen <3275109+hukkin@users.noreply.github.com>
---
 CHANGES.md         |   2 +
 Pipfile            |   2 +-
 Pipfile.lock       | 391 ++++++++++++++++++++++-----------------------
 setup.py           |   2 +-
 src/black/files.py |   7 +-
 tests/test.toml    |   7 +
 6 files changed, 210 insertions(+), 201 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index ea5196e07a0..611094f71e9 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -4,6 +4,8 @@
 
 ### _Black_
 
+- Configuration files using TOML features higher than spec v0.5.0 are now supported
+  (#2301)
 - Add primer support and test for code piped into black via STDIN (#2315)
 - Fix internal error when `FORCE_OPTIONAL_PARENTHESES` feature is enabled (#2332)
 - Accept empty stdin (#2346)
diff --git a/Pipfile b/Pipfile
index a27614c94a9..e0d5d1a7969 100644
--- a/Pipfile
+++ b/Pipfile
@@ -32,7 +32,7 @@ click = ">=8.0.0"
 mypy_extensions = ">=0.4.3"
 pathspec = ">=0.8.1"
 regex = ">=2020.1.8"
-toml = ">=0.10.1"
+tomli = ">=0.2.6, <2.0.0"
 typed-ast = "==1.4.2"
 typing_extensions = {"python_version <" = "3.8","version >=" = "3.7.4"}
 black = {editable = true,extras = ["d"],path = "."}
diff --git a/Pipfile.lock b/Pipfile.lock
index d22131ee859..90923038adb 100644
--- a/Pipfile.lock
+++ b/Pipfile.lock
@@ -1,7 +1,7 @@
 {
     "_meta": {
         "hash": {
-            "sha256": "0c126694d1a1cd1c4dc875a99f330f6b9a5994e51a1f870a98dbacd0185dae53"
+            "sha256": "e6b7c19c10b5fba5ba20296b68049fab625b4c6d61db97b79d83a6dfa36d9f6d"
         },
         "pipfile-spec": 6,
         "requires": {},
@@ -191,50 +191,50 @@
         },
         "regex": {
             "hashes": [
-                "sha256:01afaf2ec48e196ba91b37451aa353cb7eda77efe518e481707e0515025f0cd5",
-                "sha256:11d773d75fa650cd36f68d7ca936e3c7afaae41b863b8c387a22aaa78d3c5c79",
-                "sha256:18c071c3eb09c30a264879f0d310d37fe5d3a3111662438889ae2eb6fc570c31",
-                "sha256:1e1c20e29358165242928c2de1482fb2cf4ea54a6a6dea2bd7a0e0d8ee321500",
-                "sha256:281d2fd05555079448537fe108d79eb031b403dac622621c78944c235f3fcf11",
-                "sha256:314d66636c494ed9c148a42731b3834496cc9a2c4251b1661e40936814542b14",
-                "sha256:32e65442138b7b76dd8173ffa2cf67356b7bc1768851dded39a7a13bf9223da3",
-                "sha256:339456e7d8c06dd36a22e451d58ef72cef293112b559010db3d054d5560ef439",
-                "sha256:3916d08be28a1149fb97f7728fca1f7c15d309a9f9682d89d79db75d5e52091c",
-                "sha256:3a9cd17e6e5c7eb328517969e0cb0c3d31fd329298dd0c04af99ebf42e904f82",
-                "sha256:47bf5bf60cf04d72bf6055ae5927a0bd9016096bf3d742fa50d9bf9f45aa0711",
-                "sha256:4c46e22a0933dd783467cf32b3516299fb98cfebd895817d685130cc50cd1093",
-                "sha256:4c557a7b470908b1712fe27fb1ef20772b78079808c87d20a90d051660b1d69a",
-                "sha256:52ba3d3f9b942c49d7e4bc105bb28551c44065f139a65062ab7912bef10c9afb",
-                "sha256:563085e55b0d4fb8f746f6a335893bda5c2cef43b2f0258fe1020ab1dd874df8",
-                "sha256:598585c9f0af8374c28edd609eb291b5726d7cbce16be6a8b95aa074d252ee17",
-                "sha256:619d71c59a78b84d7f18891fe914446d07edd48dc8328c8e149cbe0929b4e000",
-                "sha256:67bdb9702427ceddc6ef3dc382455e90f785af4c13d495f9626861763ee13f9d",
-                "sha256:6d1b01031dedf2503631d0903cb563743f397ccaf6607a5e3b19a3d76fc10480",
-                "sha256:741a9647fcf2e45f3a1cf0e24f5e17febf3efe8d4ba1281dcc3aa0459ef424dc",
-                "sha256:7c2a1af393fcc09e898beba5dd59196edaa3116191cc7257f9224beaed3e1aa0",
-                "sha256:7d9884d86dd4dd489e981d94a65cd30d6f07203d90e98f6f657f05170f6324c9",
-                "sha256:90f11ff637fe8798933fb29f5ae1148c978cccb0452005bf4c69e13db951e765",
-                "sha256:919859aa909429fb5aa9cf8807f6045592c85ef56fdd30a9a3747e513db2536e",
-                "sha256:96fcd1888ab4d03adfc9303a7b3c0bd78c5412b2bfbe76db5b56d9eae004907a",
-                "sha256:97f29f57d5b84e73fbaf99ab3e26134e6687348e95ef6b48cfd2c06807005a07",
-                "sha256:980d7be47c84979d9136328d882f67ec5e50008681d94ecc8afa8a65ed1f4a6f",
-                "sha256:a91aa8619b23b79bcbeb37abe286f2f408d2f2d6f29a17237afda55bb54e7aac",
-                "sha256:ade17eb5d643b7fead300a1641e9f45401c98eee23763e9ed66a43f92f20b4a7",
-                "sha256:b9c3db21af35e3b3c05764461b262d6f05bbca08a71a7849fd79d47ba7bc33ed",
-                "sha256:bd28bc2e3a772acbb07787c6308e00d9626ff89e3bfcdebe87fa5afbfdedf968",
-                "sha256:bf5824bfac591ddb2c1f0a5f4ab72da28994548c708d2191e3b87dd207eb3ad7",
-                "sha256:c0502c0fadef0d23b128605d69b58edb2c681c25d44574fc673b0e52dce71ee2",
-                "sha256:c38c71df845e2aabb7fb0b920d11a1b5ac8526005e533a8920aea97efb8ec6a4",
-                "sha256:ce15b6d103daff8e9fee13cf7f0add05245a05d866e73926c358e871221eae87",
-                "sha256:d3029c340cfbb3ac0a71798100ccc13b97dddf373a4ae56b6a72cf70dfd53bc8",
-                "sha256:e512d8ef5ad7b898cdb2d8ee1cb09a8339e4f8be706d27eaa180c2f177248a10",
-                "sha256:e8e5b509d5c2ff12f8418006d5a90e9436766133b564db0abaec92fd27fcee29",
-                "sha256:ee54ff27bf0afaf4c3b3a62bcd016c12c3fdb4ec4f413391a90bd38bc3624605",
-                "sha256:fa4537fb4a98fe8fde99626e4681cc644bdcf2a795038533f9f711513a862ae6",
-                "sha256:fd45ff9293d9274c5008a2054ecef86a9bfe819a67c7be1afb65e69b405b3042"
+                "sha256:0eb2c6e0fcec5e0f1d3bcc1133556563222a2ffd2211945d7b1480c1b1a42a6f",
+                "sha256:15dddb19823f5147e7517bb12635b3c82e6f2a3a6b696cc3e321522e8b9308ad",
+                "sha256:173bc44ff95bc1e96398c38f3629d86fa72e539c79900283afa895694229fe6a",
+                "sha256:1c78780bf46d620ff4fff40728f98b8afd8b8e35c3efd638c7df67be2d5cddbf",
+                "sha256:2366fe0479ca0e9afa534174faa2beae87847d208d457d200183f28c74eaea59",
+                "sha256:2bceeb491b38225b1fee4517107b8491ba54fba77cf22a12e996d96a3c55613d",
+                "sha256:2ddeabc7652024803666ea09f32dd1ed40a0579b6fbb2a213eba590683025895",
+                "sha256:2fe5e71e11a54e3355fa272137d521a40aace5d937d08b494bed4529964c19c4",
+                "sha256:319eb2a8d0888fa6f1d9177705f341bc9455a2c8aca130016e52c7fe8d6c37a3",
+                "sha256:3f5716923d3d0bfb27048242a6e0f14eecdb2e2a7fac47eda1d055288595f222",
+                "sha256:422dec1e7cbb2efbbe50e3f1de36b82906def93ed48da12d1714cabcd993d7f0",
+                "sha256:4c9c3155fe74269f61e27617529b7f09552fbb12e44b1189cebbdb24294e6e1c",
+                "sha256:4f64fc59fd5b10557f6cd0937e1597af022ad9b27d454e182485f1db3008f417",
+                "sha256:564a4c8a29435d1f2256ba247a0315325ea63335508ad8ed938a4f14c4116a5d",
+                "sha256:59506c6e8bd9306cd8a41511e32d16d5d1194110b8cfe5a11d102d8b63cf945d",
+                "sha256:598c0a79b4b851b922f504f9f39a863d83ebdfff787261a5ed061c21e67dd761",
+                "sha256:59c00bb8dd8775473cbfb967925ad2c3ecc8886b3b2d0c90a8e2707e06c743f0",
+                "sha256:6110bab7eab6566492618540c70edd4d2a18f40ca1d51d704f1d81c52d245026",
+                "sha256:6afe6a627888c9a6cfbb603d1d017ce204cebd589d66e0703309b8048c3b0854",
+                "sha256:791aa1b300e5b6e5d597c37c346fb4d66422178566bbb426dd87eaae475053fb",
+                "sha256:8394e266005f2d8c6f0bc6780001f7afa3ef81a7a2111fa35058ded6fce79e4d",
+                "sha256:875c355360d0f8d3d827e462b29ea7682bf52327d500a4f837e934e9e4656068",
+                "sha256:89e5528803566af4df368df2d6f503c84fbfb8249e6631c7b025fe23e6bd0cde",
+                "sha256:99d8ab206a5270c1002bfcf25c51bf329ca951e5a169f3b43214fdda1f0b5f0d",
+                "sha256:9a854b916806c7e3b40e6616ac9e85d3cdb7649d9e6590653deb5b341a736cec",
+                "sha256:b85ac458354165405c8a84725de7bbd07b00d9f72c31a60ffbf96bb38d3e25fa",
+                "sha256:bc84fb254a875a9f66616ed4538542fb7965db6356f3df571d783f7c8d256edd",
+                "sha256:c92831dac113a6e0ab28bc98f33781383fe294df1a2c3dfd1e850114da35fd5b",
+                "sha256:cbe23b323988a04c3e5b0c387fe3f8f363bf06c0680daf775875d979e376bd26",
+                "sha256:ccb3d2190476d00414aab36cca453e4596e8f70a206e2aa8db3d495a109153d2",
+                "sha256:d8bbce0c96462dbceaa7ac4a7dfbbee92745b801b24bce10a98d2f2b1ea9432f",
+                "sha256:db2b7df831c3187a37f3bb80ec095f249fa276dbe09abd3d35297fc250385694",
+                "sha256:e586f448df2bbc37dfadccdb7ccd125c62b4348cb90c10840d695592aa1b29e0",
+                "sha256:e5983c19d0beb6af88cb4d47afb92d96751fb3fa1784d8785b1cdf14c6519407",
+                "sha256:e6a1e5ca97d411a461041d057348e578dc344ecd2add3555aedba3b408c9f874",
+                "sha256:eaf58b9e30e0e546cdc3ac06cf9165a1ca5b3de8221e9df679416ca667972035",
+                "sha256:ed693137a9187052fc46eedfafdcb74e09917166362af4cc4fddc3b31560e93d",
+                "sha256:edd1a68f79b89b0c57339bce297ad5d5ffcc6ae7e1afdb10f1947706ed066c9c",
+                "sha256:f080248b3e029d052bf74a897b9d74cfb7643537fbde97fe8225a6467fb559b5",
+                "sha256:f9392a4555f3e4cb45310a65b403d86b589adc773898c25a39184b1ba4db8985",
+                "sha256:f98dc35ab9a749276f1a4a38ab3e0e2ba1662ce710f6530f5b0a6656f1c32b58"
             ],
             "index": "pypi",
-            "version": "==2021.4.4"
+            "version": "==2021.7.6"
         },
         "setuptools-scm": {
             "hashes": [
@@ -244,13 +244,13 @@
             "markers": "python_version >= '3.6'",
             "version": "==6.0.1"
         },
-        "toml": {
+        "tomli": {
             "hashes": [
-                "sha256:806143ae5bfb6a3c6e736a764057db0e6a0e05e338b5630894a5f779cabb4f9b",
-                "sha256:b3bda1d108d5dd99f4a20d24d9c348e91c4db7ab1b749200bded2f839ccbe68f"
+                "sha256:0713b16ff91df8638a6a694e295c8159ab35ba93e3424a626dd5226d386057be",
+                "sha256:be670d0d8d7570fd0ea0113bd7bb1ba3ac6706b4de062cc4c952769355c9c268"
             ],
             "index": "pypi",
-            "version": "==0.10.2"
+            "version": "==1.0.4"
         },
         "typed-ast": {
             "hashes": [
@@ -458,57 +458,48 @@
         },
         "cffi": {
             "hashes": [
-                "sha256:005a36f41773e148deac64b08f233873a4d0c18b053d37da83f6af4d9087b813",
-                "sha256:04c468b622ed31d408fea2346bec5bbffba2cc44226302a0de1ade9f5ea3d373",
-                "sha256:06d7cd1abac2ffd92e65c0609661866709b4b2d82dd15f611e602b9b188b0b69",
-                "sha256:06db6321b7a68b2bd6df96d08a5adadc1fa0e8f419226e25b2a5fbf6ccc7350f",
-                "sha256:0857f0ae312d855239a55c81ef453ee8fd24136eaba8e87a2eceba644c0d4c06",
-                "sha256:0f861a89e0043afec2a51fd177a567005847973be86f709bbb044d7f42fc4e05",
-                "sha256:1071534bbbf8cbb31b498d5d9db0f274f2f7a865adca4ae429e147ba40f73dea",
-                "sha256:158d0d15119b4b7ff6b926536763dc0714313aa59e320ddf787502c70c4d4bee",
-                "sha256:1bf1ac1984eaa7675ca8d5745a8cb87ef7abecb5592178406e55858d411eadc0",
-                "sha256:1f436816fc868b098b0d63b8920de7d208c90a67212546d02f84fe78a9c26396",
-                "sha256:24a570cd11895b60829e941f2613a4f79df1a27344cbbb82164ef2e0116f09c7",
-                "sha256:24ec4ff2c5c0c8f9c6b87d5bb53555bf267e1e6f70e52e5a9740d32861d36b6f",
-                "sha256:2894f2df484ff56d717bead0a5c2abb6b9d2bf26d6960c4604d5c48bbc30ee73",
-                "sha256:29314480e958fd8aab22e4a58b355b629c59bf5f2ac2492b61e3dc06d8c7a315",
-                "sha256:293e7ea41280cb28c6fcaaa0b1aa1f533b8ce060b9e701d78511e1e6c4a1de76",
-                "sha256:34eff4b97f3d982fb93e2831e6750127d1355a923ebaeeb565407b3d2f8d41a1",
-                "sha256:35f27e6eb43380fa080dccf676dece30bef72e4a67617ffda586641cd4508d49",
-                "sha256:3c3f39fa737542161d8b0d680df2ec249334cd70a8f420f71c9304bd83c3cbed",
-                "sha256:3d3dd4c9e559eb172ecf00a2a7517e97d1e96de2a5e610bd9b68cea3925b4892",
-                "sha256:43e0b9d9e2c9e5d152946b9c5fe062c151614b262fda2e7b201204de0b99e482",
-                "sha256:48e1c69bbacfc3d932221851b39d49e81567a4d4aac3b21258d9c24578280058",
-                "sha256:51182f8927c5af975fece87b1b369f722c570fe169f9880764b1ee3bca8347b5",
-                "sha256:58e3f59d583d413809d60779492342801d6e82fefb89c86a38e040c16883be53",
-                "sha256:5de7970188bb46b7bf9858eb6890aad302577a5f6f75091fd7cdd3ef13ef3045",
-                "sha256:65fa59693c62cf06e45ddbb822165394a288edce9e276647f0046e1ec26920f3",
-                "sha256:681d07b0d1e3c462dd15585ef5e33cb021321588bebd910124ef4f4fb71aef55",
-                "sha256:69e395c24fc60aad6bb4fa7e583698ea6cc684648e1ffb7fe85e3c1ca131a7d5",
-                "sha256:6c97d7350133666fbb5cf4abdc1178c812cb205dc6f41d174a7b0f18fb93337e",
-                "sha256:6e4714cc64f474e4d6e37cfff31a814b509a35cb17de4fb1999907575684479c",
-                "sha256:72d8d3ef52c208ee1c7b2e341f7d71c6fd3157138abf1a95166e6165dd5d4369",
-                "sha256:8ae6299f6c68de06f136f1f9e69458eae58f1dacf10af5c17353eae03aa0d827",
-                "sha256:8b198cec6c72df5289c05b05b8b0969819783f9418e0409865dac47288d2a053",
-                "sha256:99cd03ae7988a93dd00bcd9d0b75e1f6c426063d6f03d2f90b89e29b25b82dfa",
-                "sha256:9cf8022fb8d07a97c178b02327b284521c7708d7c71a9c9c355c178ac4bbd3d4",
-                "sha256:9de2e279153a443c656f2defd67769e6d1e4163952b3c622dcea5b08a6405322",
-                "sha256:9e93e79c2551ff263400e1e4be085a1210e12073a31c2011dbbda14bda0c6132",
-                "sha256:9ff227395193126d82e60319a673a037d5de84633f11279e336f9c0f189ecc62",
-                "sha256:a465da611f6fa124963b91bf432d960a555563efe4ed1cc403ba5077b15370aa",
-                "sha256:ad17025d226ee5beec591b52800c11680fca3df50b8b29fe51d882576e039ee0",
-                "sha256:afb29c1ba2e5a3736f1c301d9d0abe3ec8b86957d04ddfa9d7a6a42b9367e396",
-                "sha256:b85eb46a81787c50650f2392b9b4ef23e1f126313b9e0e9013b35c15e4288e2e",
-                "sha256:bb89f306e5da99f4d922728ddcd6f7fcebb3241fc40edebcb7284d7514741991",
-                "sha256:cbde590d4faaa07c72bf979734738f328d239913ba3e043b1e98fe9a39f8b2b6",
-                "sha256:cc5a8e069b9ebfa22e26d0e6b97d6f9781302fe7f4f2b8776c3e1daea35f1adc",
-                "sha256:cd2868886d547469123fadc46eac7ea5253ea7fcb139f12e1dfc2bbd406427d1",
-                "sha256:d42b11d692e11b6634f7613ad8df5d6d5f8875f5d48939520d351007b3c13406",
-                "sha256:df5052c5d867c1ea0b311fb7c3cd28b19df469c056f7fdcfe88c7473aa63e333",
-                "sha256:f2d45f97ab6bb54753eab54fffe75aaf3de4ff2341c9daee1987ee1837636f1d",
-                "sha256:fd78e5fee591709f32ef6edb9a015b4aa1a5022598e36227500c8f4e02328d9c"
-            ],
-            "version": "==1.14.5"
+                "sha256:06c54a68935738d206570b20da5ef2b6b6d92b38ef3ec45c5422c0ebaf338d4d",
+                "sha256:0c0591bee64e438883b0c92a7bed78f6290d40bf02e54c5bf0978eaf36061771",
+                "sha256:19ca0dbdeda3b2615421d54bef8985f72af6e0c47082a8d26122adac81a95872",
+                "sha256:22b9c3c320171c108e903d61a3723b51e37aaa8c81255b5e7ce102775bd01e2c",
+                "sha256:26bb2549b72708c833f5abe62b756176022a7b9a7f689b571e74c8478ead51dc",
+                "sha256:33791e8a2dc2953f28b8d8d300dde42dd929ac28f974c4b4c6272cb2955cb762",
+                "sha256:3c8d896becff2fa653dc4438b54a5a25a971d1f4110b32bd3068db3722c80202",
+                "sha256:4373612d59c404baeb7cbd788a18b2b2a8331abcc84c3ba40051fcd18b17a4d5",
+                "sha256:487d63e1454627c8e47dd230025780e91869cfba4c753a74fda196a1f6ad6548",
+                "sha256:4922cd707b25e623b902c86188aca466d3620892db76c0bdd7b99a3d5e61d35f",
+                "sha256:55af55e32ae468e9946f741a5d51f9896da6b9bf0bbdd326843fec05c730eb20",
+                "sha256:5d4b68e216fc65e9fe4f524c177b54964af043dde734807586cf5435af84045c",
+                "sha256:64fda793737bc4037521d4899be780534b9aea552eb673b9833b01f945904c2e",
+                "sha256:6d6169cb3c6c2ad50db5b868db6491a790300ade1ed5d1da29289d73bbe40b56",
+                "sha256:7bcac9a2b4fdbed2c16fa5681356d7121ecabf041f18d97ed5b8e0dd38a80224",
+                "sha256:80b06212075346b5546b0417b9f2bf467fea3bfe7352f781ffc05a8ab24ba14a",
+                "sha256:818014c754cd3dba7229c0f5884396264d51ffb87ec86e927ef0be140bfdb0d2",
+                "sha256:8eb687582ed7cd8c4bdbff3df6c0da443eb89c3c72e6e5dcdd9c81729712791a",
+                "sha256:99f27fefe34c37ba9875f224a8f36e31d744d8083e00f520f133cab79ad5e819",
+                "sha256:9f3e33c28cd39d1b655ed1ba7247133b6f7fc16fa16887b120c0c670e35ce346",
+                "sha256:a8661b2ce9694ca01c529bfa204dbb144b275a31685a075ce123f12331be790b",
+                "sha256:a9da7010cec5a12193d1af9872a00888f396aba3dc79186604a09ea3ee7c029e",
+                "sha256:b315d709717a99f4b27b59b021e6207c64620790ca3e0bde636a6c7f14618abb",
+                "sha256:ba6f2b3f452e150945d58f4badd92310449876c4c954836cfb1803bdd7b422f0",
+                "sha256:c33d18eb6e6bc36f09d793c0dc58b0211fccc6ae5149b808da4a62660678b156",
+                "sha256:c9a875ce9d7fe32887784274dd533c57909b7b1dcadcc128a2ac21331a9765dd",
+                "sha256:c9e005e9bd57bc987764c32a1bee4364c44fdc11a3cc20a40b93b444984f2b87",
+                "sha256:d2ad4d668a5c0645d281dcd17aff2be3212bc109b33814bbb15c4939f44181cc",
+                "sha256:d950695ae4381ecd856bcaf2b1e866720e4ab9a1498cba61c602e56630ca7195",
+                "sha256:e22dcb48709fc51a7b58a927391b23ab37eb3737a98ac4338e2448bef8559b33",
+                "sha256:e8c6a99be100371dbb046880e7a282152aa5d6127ae01783e37662ef73850d8f",
+                "sha256:e9dc245e3ac69c92ee4c167fbdd7428ec1956d4e754223124991ef29eb57a09d",
+                "sha256:eb687a11f0a7a1839719edd80f41e459cc5366857ecbed383ff376c4e3cc6afd",
+                "sha256:eb9e2a346c5238a30a746893f23a9535e700f8192a68c07c0258e7ece6ff3728",
+                "sha256:ed38b924ce794e505647f7c331b22a693bee1538fdf46b0222c4717b42f744e7",
+                "sha256:f0c5d1acbfca6ebdd6b1e3eded8d261affb6ddcf2186205518f1428b8569bb99",
+                "sha256:f10afb1004f102c7868ebfe91c28f4a712227fe4cb24974350ace1f90e1febbf",
+                "sha256:f174135f5609428cc6e1b9090f9268f5c8935fddb1b25ccb8255a2d50de6789e",
+                "sha256:f3ebe6e73c319340830a9b2825d32eb6d8475c1dac020b4f0aa774ee3b898d1c",
+                "sha256:fd4305f86f53dfd8cd3522269ed7fc34856a8ee3709a5e28b2836b2db9d4cd69"
+            ],
+            "version": "==1.14.6"
         },
         "cfgv": {
             "hashes": [
@@ -659,11 +650,11 @@
         },
         "identify": {
             "hashes": [
-                "sha256:18d0c531ee3dbc112fa6181f34faa179de3f57ea57ae2899754f16a7e0ff6421",
-                "sha256:5b41f71471bc738e7b586308c3fca172f78940195cb3bf6734c1e66fdac49306"
+                "sha256:7abaecbb414e385752e8ce02d8c494f4fbc780c975074b46172598a28f1ab839",
+                "sha256:a0e700637abcbd1caae58e0463861250095dfe330a8371733a471af706a4a29a"
             ],
             "markers": "python_full_version >= '3.6.1'",
-            "version": "==2.2.10"
+            "version": "==2.2.11"
         },
         "idna": {
             "hashes": [
@@ -683,19 +674,19 @@
         },
         "importlib-metadata": {
             "hashes": [
-                "sha256:833b26fb89d5de469b24a390e9df088d4e52e4ba33b01dc5e0e4f41b81a16c00",
-                "sha256:b142cc1dd1342f31ff04bb7d022492b09920cb64fed867cd3ea6f80fe3ebd139"
+                "sha256:079ada16b7fc30dfbb5d13399a5113110dab1aa7c2bc62f66af75f0b717c8cac",
+                "sha256:9f55f560e116f8643ecf2922d9cd3e1c7e8d52e683178fecd9d08f6aa357e11e"
             ],
             "markers": "python_version >= '3.6'",
-            "version": "==4.5.0"
+            "version": "==4.6.1"
         },
         "jeepney": {
             "hashes": [
-                "sha256:7d59b6622675ca9e993a6bd38de845051d315f8b0c72cca3aef733a20b648657",
-                "sha256:aec56c0eb1691a841795111e184e13cad504f7703b9a64f63020816afa79a8ae"
+                "sha256:1237cd64c8f7ac3aa4b3f332c4d0fb4a8216f39eaa662ec904302d4d77de5a54",
+                "sha256:71335e7a4e93817982f473f3507bffc2eff7a544119ab9b73e089c8ba1409ba3"
             ],
             "markers": "sys_platform == 'linux'",
-            "version": "==0.6.0"
+            "version": "==0.7.0"
         },
         "jinja2": {
             "hashes": [
@@ -821,32 +812,32 @@
         },
         "mypy": {
             "hashes": [
-                "sha256:0190fb77e93ce971954c9e54ea61de2802065174e5e990c9d4c1d0f54fbeeca2",
-                "sha256:0756529da2dd4d53d26096b7969ce0a47997123261a5432b48cc6848a2cb0bd4",
-                "sha256:2f9fedc1f186697fda191e634ac1d02f03d4c260212ccb018fabbb6d4b03eee8",
-                "sha256:353aac2ce41ddeaf7599f1c73fed2b75750bef3b44b6ad12985a991bc002a0da",
-                "sha256:3f12705eabdd274b98f676e3e5a89f247ea86dc1af48a2d5a2b080abac4e1243",
-                "sha256:4efc67b9b3e2fddbe395700f91d5b8deb5980bfaaccb77b306310bd0b9e002eb",
-                "sha256:517e7528d1be7e187a5db7f0a3e479747307c1b897d9706b1c662014faba3116",
-                "sha256:68a098c104ae2b75e946b107ef69dd8398d54cb52ad57580dfb9fc78f7f997f0",
-                "sha256:746e0b0101b8efec34902810047f26a8c80e1efbb4fc554956d848c05ef85d76",
-                "sha256:8be7bbd091886bde9fcafed8dd089a766fa76eb223135fe5c9e9798f78023a20",
-                "sha256:9236c21194fde5df1b4d8ebc2ef2c1f2a5dc7f18bcbea54274937cae2e20a01c",
-                "sha256:9ef5355eaaf7a23ab157c21a44c614365238a7bdb3552ec3b80c393697d974e1",
-                "sha256:9f1d74eeb3f58c7bd3f3f92b8f63cb1678466a55e2c4612bf36909105d0724ab",
-                "sha256:a26d0e53e90815c765f91966442775cf03b8a7514a4e960de7b5320208b07269",
-                "sha256:ae94c31bb556ddb2310e4f913b706696ccbd43c62d3331cd3511caef466871d2",
-                "sha256:b5ba1f0d5f9087e03bf5958c28d421a03a4c1ad260bf81556195dffeccd979c4",
-                "sha256:b5dfcd22c6bab08dfeded8d5b44bdcb68c6f1ab261861e35c470b89074f78a70",
-                "sha256:cd01c599cf9f897b6b6c6b5d8b182557fb7d99326bcdf5d449a0fbbb4ccee4b9",
-                "sha256:e89880168c67cf4fde4506b80ee42f1537ad66ad366c101d388b3fd7d7ce2afd",
-                "sha256:ebe2bc9cb638475f5d39068d2dbe8ae1d605bb8d8d3ff281c695df1670ab3987",
-                "sha256:f89bfda7f0f66b789792ab64ce0978e4a991a0e4dd6197349d0767b0f1095b21",
-                "sha256:fc4d63da57ef0e8cd4ab45131f3fe5c286ce7dd7f032650d0fbc239c6190e167",
-                "sha256:fd634bc17b1e2d6ce716f0e43446d0d61cdadb1efcad5c56ca211c22b246ebc8"
+                "sha256:088cd9c7904b4ad80bec811053272986611b84221835e079be5bcad029e79dd9",
+                "sha256:0aadfb2d3935988ec3815952e44058a3100499f5be5b28c34ac9d79f002a4a9a",
+                "sha256:119bed3832d961f3a880787bf621634ba042cb8dc850a7429f643508eeac97b9",
+                "sha256:1a85e280d4d217150ce8cb1a6dddffd14e753a4e0c3cf90baabb32cefa41b59e",
+                "sha256:3c4b8ca36877fc75339253721f69603a9c7fdb5d4d5a95a1a1b899d8b86a4de2",
+                "sha256:3e382b29f8e0ccf19a2df2b29a167591245df90c0b5a2542249873b5c1d78212",
+                "sha256:42c266ced41b65ed40a282c575705325fa7991af370036d3f134518336636f5b",
+                "sha256:53fd2eb27a8ee2892614370896956af2ff61254c275aaee4c230ae771cadd885",
+                "sha256:704098302473cb31a218f1775a873b376b30b4c18229421e9e9dc8916fd16150",
+                "sha256:7df1ead20c81371ccd6091fa3e2878559b5c4d4caadaf1a484cf88d93ca06703",
+                "sha256:866c41f28cee548475f146aa4d39a51cf3b6a84246969f3759cb3e9c742fc072",
+                "sha256:a155d80ea6cee511a3694b108c4494a39f42de11ee4e61e72bc424c490e46457",
+                "sha256:adaeee09bfde366d2c13fe6093a7df5df83c9a2ba98638c7d76b010694db760e",
+                "sha256:b6fb13123aeef4a3abbcfd7e71773ff3ff1526a7d3dc538f3929a49b42be03f0",
+                "sha256:b94e4b785e304a04ea0828759172a15add27088520dc7e49ceade7834275bedb",
+                "sha256:c0df2d30ed496a08de5daed2a9ea807d07c21ae0ab23acf541ab88c24b26ab97",
+                "sha256:c6c2602dffb74867498f86e6129fd52a2770c48b7cd3ece77ada4fa38f94eba8",
+                "sha256:ceb6e0a6e27fb364fb3853389607cf7eb3a126ad335790fa1e14ed02fba50811",
+                "sha256:d9dd839eb0dc1bbe866a288ba3c1afc33a202015d2ad83b31e875b5905a079b6",
+                "sha256:e4dab234478e3bd3ce83bac4193b2ecd9cf94e720ddd95ce69840273bf44f6de",
+                "sha256:ec4e0cd079db280b6bdabdc807047ff3e199f334050db5cbb91ba3e959a67504",
+                "sha256:ecd2c3fe726758037234c93df7e98deb257fd15c24c9180dacf1ef829da5f921",
+                "sha256:ef565033fa5a958e62796867b1df10c40263ea9ded87164d67572834e57a174d"
             ],
             "index": "pypi",
-            "version": "==0.902"
+            "version": "==0.910"
         },
         "mypy-extensions": {
             "hashes": [
@@ -873,11 +864,11 @@
         },
         "packaging": {
             "hashes": [
-                "sha256:5b327ac1320dc863dca72f4514ecc086f31186744b84a230374cc1fd776feae5",
-                "sha256:67714da7f7bc052e064859c05c595155bd1ee9f69f76557e21f051443c20947a"
+                "sha256:7dc96269f53a4ccec5c0670940a4281106dd0bb343f47b7471f779df49c2fbe7",
+                "sha256:c86254f9220d55e31cc94d69bade760f0847da8000def4dfe1c6b872fd14ff14"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==20.9"
+            "markers": "python_version >= '3.6'",
+            "version": "==21.0"
         },
         "pathspec": {
             "hashes": [
@@ -889,10 +880,10 @@
         },
         "pkginfo": {
             "hashes": [
-                "sha256:029a70cb45c6171c329dfc890cde0879f8c52d6f3922794796e06f577bb03db4",
-                "sha256:9fdbea6495622e022cc72c2e5e1b735218e4ffb2a2a69cde2694a6c1f16afb75"
+                "sha256:37ecd857b47e5f55949c41ed061eb51a0bee97a87c969219d144c0e023982779",
+                "sha256:e7432f81d08adec7297633191bbf0bd47faf13cd8724c3a13250e51d542635bd"
             ],
-            "version": "==1.7.0"
+            "version": "==1.7.1"
         },
         "pre-commit": {
             "hashes": [
@@ -994,50 +985,50 @@
         },
         "regex": {
             "hashes": [
-                "sha256:01afaf2ec48e196ba91b37451aa353cb7eda77efe518e481707e0515025f0cd5",
-                "sha256:11d773d75fa650cd36f68d7ca936e3c7afaae41b863b8c387a22aaa78d3c5c79",
-                "sha256:18c071c3eb09c30a264879f0d310d37fe5d3a3111662438889ae2eb6fc570c31",
-                "sha256:1e1c20e29358165242928c2de1482fb2cf4ea54a6a6dea2bd7a0e0d8ee321500",
-                "sha256:281d2fd05555079448537fe108d79eb031b403dac622621c78944c235f3fcf11",
-                "sha256:314d66636c494ed9c148a42731b3834496cc9a2c4251b1661e40936814542b14",
-                "sha256:32e65442138b7b76dd8173ffa2cf67356b7bc1768851dded39a7a13bf9223da3",
-                "sha256:339456e7d8c06dd36a22e451d58ef72cef293112b559010db3d054d5560ef439",
-                "sha256:3916d08be28a1149fb97f7728fca1f7c15d309a9f9682d89d79db75d5e52091c",
-                "sha256:3a9cd17e6e5c7eb328517969e0cb0c3d31fd329298dd0c04af99ebf42e904f82",
-                "sha256:47bf5bf60cf04d72bf6055ae5927a0bd9016096bf3d742fa50d9bf9f45aa0711",
-                "sha256:4c46e22a0933dd783467cf32b3516299fb98cfebd895817d685130cc50cd1093",
-                "sha256:4c557a7b470908b1712fe27fb1ef20772b78079808c87d20a90d051660b1d69a",
-                "sha256:52ba3d3f9b942c49d7e4bc105bb28551c44065f139a65062ab7912bef10c9afb",
-                "sha256:563085e55b0d4fb8f746f6a335893bda5c2cef43b2f0258fe1020ab1dd874df8",
-                "sha256:598585c9f0af8374c28edd609eb291b5726d7cbce16be6a8b95aa074d252ee17",
-                "sha256:619d71c59a78b84d7f18891fe914446d07edd48dc8328c8e149cbe0929b4e000",
-                "sha256:67bdb9702427ceddc6ef3dc382455e90f785af4c13d495f9626861763ee13f9d",
-                "sha256:6d1b01031dedf2503631d0903cb563743f397ccaf6607a5e3b19a3d76fc10480",
-                "sha256:741a9647fcf2e45f3a1cf0e24f5e17febf3efe8d4ba1281dcc3aa0459ef424dc",
-                "sha256:7c2a1af393fcc09e898beba5dd59196edaa3116191cc7257f9224beaed3e1aa0",
-                "sha256:7d9884d86dd4dd489e981d94a65cd30d6f07203d90e98f6f657f05170f6324c9",
-                "sha256:90f11ff637fe8798933fb29f5ae1148c978cccb0452005bf4c69e13db951e765",
-                "sha256:919859aa909429fb5aa9cf8807f6045592c85ef56fdd30a9a3747e513db2536e",
-                "sha256:96fcd1888ab4d03adfc9303a7b3c0bd78c5412b2bfbe76db5b56d9eae004907a",
-                "sha256:97f29f57d5b84e73fbaf99ab3e26134e6687348e95ef6b48cfd2c06807005a07",
-                "sha256:980d7be47c84979d9136328d882f67ec5e50008681d94ecc8afa8a65ed1f4a6f",
-                "sha256:a91aa8619b23b79bcbeb37abe286f2f408d2f2d6f29a17237afda55bb54e7aac",
-                "sha256:ade17eb5d643b7fead300a1641e9f45401c98eee23763e9ed66a43f92f20b4a7",
-                "sha256:b9c3db21af35e3b3c05764461b262d6f05bbca08a71a7849fd79d47ba7bc33ed",
-                "sha256:bd28bc2e3a772acbb07787c6308e00d9626ff89e3bfcdebe87fa5afbfdedf968",
-                "sha256:bf5824bfac591ddb2c1f0a5f4ab72da28994548c708d2191e3b87dd207eb3ad7",
-                "sha256:c0502c0fadef0d23b128605d69b58edb2c681c25d44574fc673b0e52dce71ee2",
-                "sha256:c38c71df845e2aabb7fb0b920d11a1b5ac8526005e533a8920aea97efb8ec6a4",
-                "sha256:ce15b6d103daff8e9fee13cf7f0add05245a05d866e73926c358e871221eae87",
-                "sha256:d3029c340cfbb3ac0a71798100ccc13b97dddf373a4ae56b6a72cf70dfd53bc8",
-                "sha256:e512d8ef5ad7b898cdb2d8ee1cb09a8339e4f8be706d27eaa180c2f177248a10",
-                "sha256:e8e5b509d5c2ff12f8418006d5a90e9436766133b564db0abaec92fd27fcee29",
-                "sha256:ee54ff27bf0afaf4c3b3a62bcd016c12c3fdb4ec4f413391a90bd38bc3624605",
-                "sha256:fa4537fb4a98fe8fde99626e4681cc644bdcf2a795038533f9f711513a862ae6",
-                "sha256:fd45ff9293d9274c5008a2054ecef86a9bfe819a67c7be1afb65e69b405b3042"
+                "sha256:0eb2c6e0fcec5e0f1d3bcc1133556563222a2ffd2211945d7b1480c1b1a42a6f",
+                "sha256:15dddb19823f5147e7517bb12635b3c82e6f2a3a6b696cc3e321522e8b9308ad",
+                "sha256:173bc44ff95bc1e96398c38f3629d86fa72e539c79900283afa895694229fe6a",
+                "sha256:1c78780bf46d620ff4fff40728f98b8afd8b8e35c3efd638c7df67be2d5cddbf",
+                "sha256:2366fe0479ca0e9afa534174faa2beae87847d208d457d200183f28c74eaea59",
+                "sha256:2bceeb491b38225b1fee4517107b8491ba54fba77cf22a12e996d96a3c55613d",
+                "sha256:2ddeabc7652024803666ea09f32dd1ed40a0579b6fbb2a213eba590683025895",
+                "sha256:2fe5e71e11a54e3355fa272137d521a40aace5d937d08b494bed4529964c19c4",
+                "sha256:319eb2a8d0888fa6f1d9177705f341bc9455a2c8aca130016e52c7fe8d6c37a3",
+                "sha256:3f5716923d3d0bfb27048242a6e0f14eecdb2e2a7fac47eda1d055288595f222",
+                "sha256:422dec1e7cbb2efbbe50e3f1de36b82906def93ed48da12d1714cabcd993d7f0",
+                "sha256:4c9c3155fe74269f61e27617529b7f09552fbb12e44b1189cebbdb24294e6e1c",
+                "sha256:4f64fc59fd5b10557f6cd0937e1597af022ad9b27d454e182485f1db3008f417",
+                "sha256:564a4c8a29435d1f2256ba247a0315325ea63335508ad8ed938a4f14c4116a5d",
+                "sha256:59506c6e8bd9306cd8a41511e32d16d5d1194110b8cfe5a11d102d8b63cf945d",
+                "sha256:598c0a79b4b851b922f504f9f39a863d83ebdfff787261a5ed061c21e67dd761",
+                "sha256:59c00bb8dd8775473cbfb967925ad2c3ecc8886b3b2d0c90a8e2707e06c743f0",
+                "sha256:6110bab7eab6566492618540c70edd4d2a18f40ca1d51d704f1d81c52d245026",
+                "sha256:6afe6a627888c9a6cfbb603d1d017ce204cebd589d66e0703309b8048c3b0854",
+                "sha256:791aa1b300e5b6e5d597c37c346fb4d66422178566bbb426dd87eaae475053fb",
+                "sha256:8394e266005f2d8c6f0bc6780001f7afa3ef81a7a2111fa35058ded6fce79e4d",
+                "sha256:875c355360d0f8d3d827e462b29ea7682bf52327d500a4f837e934e9e4656068",
+                "sha256:89e5528803566af4df368df2d6f503c84fbfb8249e6631c7b025fe23e6bd0cde",
+                "sha256:99d8ab206a5270c1002bfcf25c51bf329ca951e5a169f3b43214fdda1f0b5f0d",
+                "sha256:9a854b916806c7e3b40e6616ac9e85d3cdb7649d9e6590653deb5b341a736cec",
+                "sha256:b85ac458354165405c8a84725de7bbd07b00d9f72c31a60ffbf96bb38d3e25fa",
+                "sha256:bc84fb254a875a9f66616ed4538542fb7965db6356f3df571d783f7c8d256edd",
+                "sha256:c92831dac113a6e0ab28bc98f33781383fe294df1a2c3dfd1e850114da35fd5b",
+                "sha256:cbe23b323988a04c3e5b0c387fe3f8f363bf06c0680daf775875d979e376bd26",
+                "sha256:ccb3d2190476d00414aab36cca453e4596e8f70a206e2aa8db3d495a109153d2",
+                "sha256:d8bbce0c96462dbceaa7ac4a7dfbbee92745b801b24bce10a98d2f2b1ea9432f",
+                "sha256:db2b7df831c3187a37f3bb80ec095f249fa276dbe09abd3d35297fc250385694",
+                "sha256:e586f448df2bbc37dfadccdb7ccd125c62b4348cb90c10840d695592aa1b29e0",
+                "sha256:e5983c19d0beb6af88cb4d47afb92d96751fb3fa1784d8785b1cdf14c6519407",
+                "sha256:e6a1e5ca97d411a461041d057348e578dc344ecd2add3555aedba3b408c9f874",
+                "sha256:eaf58b9e30e0e546cdc3ac06cf9165a1ca5b3de8221e9df679416ca667972035",
+                "sha256:ed693137a9187052fc46eedfafdcb74e09917166362af4cc4fddc3b31560e93d",
+                "sha256:edd1a68f79b89b0c57339bce297ad5d5ffcc6ae7e1afdb10f1947706ed066c9c",
+                "sha256:f080248b3e029d052bf74a897b9d74cfb7643537fbde97fe8225a6467fb559b5",
+                "sha256:f9392a4555f3e4cb45310a65b403d86b589adc773898c25a39184b1ba4db8985",
+                "sha256:f98dc35ab9a749276f1a4a38ab3e0e2ba1662ce710f6530f5b0a6656f1c32b58"
             ],
             "index": "pypi",
-            "version": "==2021.4.4"
+            "version": "==2021.7.6"
         },
         "requests": {
             "hashes": [
@@ -1094,19 +1085,19 @@
         },
         "sphinx": {
             "hashes": [
-                "sha256:b5c2ae4120bf00c799ba9b3699bc895816d272d120080fbc967292f29b52b48c",
-                "sha256:d1cb10bee9c4231f1700ec2e24a91be3f3a3aba066ea4ca9f3bbe47e59d5a1d4"
+                "sha256:4219f14258ca5612a0c85ed9b7222d54da69724d7e9dd92d1819ad1bf65e1ad2",
+                "sha256:51028bb0d3340eb80bcc1a2d614e8308ac78d226e6b796943daf57920abc1aea"
             ],
             "index": "pypi",
-            "version": "==4.0.2"
+            "version": "==4.1.0"
         },
         "sphinx-copybutton": {
             "hashes": [
-                "sha256:19850e9c1ed09c899f136ce3cfa304cb3b6d2f508528c19d8f512ccc8c66b0d4",
-                "sha256:3695987d5e98e3b223471aaed8aa7491e03e9bfc48ed655a91446fd5e30b6c25"
+                "sha256:4340d33c169dac6dd82dce2c83333412aa786a42dd01a81a8decac3b130dc8b0",
+                "sha256:8daed13a87afd5013c3a9af3575cc4d5bec052075ccd3db243f895c07a689386"
             ],
             "index": "pypi",
-            "version": "==0.3.3"
+            "version": "==0.4.0"
         },
         "sphinxcontrib-applehelp": {
             "hashes": [
@@ -1169,16 +1160,24 @@
                 "sha256:806143ae5bfb6a3c6e736a764057db0e6a0e05e338b5630894a5f779cabb4f9b",
                 "sha256:b3bda1d108d5dd99f4a20d24d9c348e91c4db7ab1b749200bded2f839ccbe68f"
             ],
-            "index": "pypi",
+            "markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==0.10.2"
         },
+        "tomli": {
+            "hashes": [
+                "sha256:0713b16ff91df8638a6a694e295c8159ab35ba93e3424a626dd5226d386057be",
+                "sha256:be670d0d8d7570fd0ea0113bd7bb1ba3ac6706b4de062cc4c952769355c9c268"
+            ],
+            "index": "pypi",
+            "version": "==1.0.4"
+        },
         "tqdm": {
             "hashes": [
-                "sha256:24be966933e942be5f074c29755a95b315c69a91f839a29139bf26ffffe2d3fd",
-                "sha256:aa0c29f03f298951ac6318f7c8ce584e48fa22ec26396e6411e43d038243bdb2"
+                "sha256:5aa445ea0ad8b16d82b15ab342de6b195a722d75fc1ef9934a46bba6feafbc64",
+                "sha256:8bb94db0d4468fea27d004a0f1d1c02da3cdedc00fe491c0de986b76a04d6b0a"
             ],
             "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==4.61.1"
+            "version": "==4.61.2"
         },
         "twine": {
             "hashes": [
@@ -1225,11 +1224,11 @@
         },
         "urllib3": {
             "hashes": [
-                "sha256:753a0374df26658f99d826cfe40394a686d05985786d946fbe4165b5148f5a7c",
-                "sha256:a7acd0977125325f516bda9735fa7142b909a8d01e8b2e4c8108d0984e6e0098"
+                "sha256:39fb8672126159acb139a7718dd10806104dec1e2f0f6c88aab05d17df10c8d4",
+                "sha256:f57b4c16c62fa2760b7e3d97c35b255512fb6b59a259730f36ba32ce9f8e342f"
             ],
             "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4' and python_version < '4'",
-            "version": "==1.26.5"
+            "version": "==1.26.6"
         },
         "virtualenv": {
             "hashes": [
@@ -1299,11 +1298,11 @@
         },
         "zipp": {
             "hashes": [
-                "sha256:3607921face881ba3e026887d8150cca609d517579abe052ac81fc5aeffdbd76",
-                "sha256:51cb66cc54621609dd593d1787f286ee42a5c0adbb4b29abea5a63edc3e03098"
+                "sha256:957cfda87797e389580cb8b9e3870841ca991e2125350677b2ca83a0e99390a3",
+                "sha256:f5812b1e007e48cff63449a5e9f4e7ebea716b4111f9c4f9a645f91d579bf0c4"
             ],
             "markers": "python_version >= '3.6'",
-            "version": "==3.4.1"
+            "version": "==3.5.0"
         }
     }
 }
diff --git a/setup.py b/setup.py
index 95252eab054..da25deab512 100644
--- a/setup.py
+++ b/setup.py
@@ -74,7 +74,7 @@ def get_long_description() -> str:
     install_requires=[
         "click>=7.1.2",
         "appdirs",
-        "toml>=0.10.1",
+        "tomli>=0.2.6,<2.0.0",
         "typed-ast>=1.4.2; python_version < '3.8'",
         "regex>=2020.1.8",
         "pathspec>=0.8.1, <1",
diff --git a/src/black/files.py b/src/black/files.py
index b9cefd317e0..427ad668f48 100644
--- a/src/black/files.py
+++ b/src/black/files.py
@@ -18,7 +18,7 @@
 )
 
 from pathspec import PathSpec
-import toml
+import tomli
 
 from black.output import err
 from black.report import Report
@@ -89,9 +89,10 @@ def find_pyproject_toml(path_search_start: Tuple[str, ...]) -> Optional[str]:
 def parse_pyproject_toml(path_config: str) -> Dict[str, Any]:
     """Parse a pyproject toml file, pulling out relevant parts for Black
 
-    If parsing fails, will raise a toml.TomlDecodeError
+    If parsing fails, will raise a tomli.TOMLDecodeError
     """
-    pyproject_toml = toml.load(path_config)
+    with open(path_config, encoding="utf8") as f:
+        pyproject_toml = tomli.load(f)
     config = pyproject_toml.get("tool", {}).get("black", {})
     return {k.replace("--", "").replace("-", "_"): v for k, v in config.items()}
 
diff --git a/tests/test.toml b/tests/test.toml
index 570c2f26b15..d3ab1e61202 100644
--- a/tests/test.toml
+++ b/tests/test.toml
@@ -7,3 +7,10 @@ line-length = 79
 target-version = ["py36", "py37", "py38"]
 exclude='\.pyi?$'
 include='\.py?$'
+
+[v1.0.0-syntax]
+# This shouldn't break Black.
+contributors = [
+  "Foo Bar <foo@example.com>",
+  { name = "Baz Qux", email = "bazqux@example.com", url = "https://example.com/bazqux" }
+]

From 91773b89097927a2393bc5223295d37ed26e1632 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Felix=20Hild=C3=A9n?= <felix.hilden@gmail.com>
Date: Tue, 13 Jul 2021 20:24:55 +0300
Subject: [PATCH 0263/1034] Improve AST safety parsing error message (#2304)

Co-authored-by: Hasan Ramezani <hasan.r67@gmail.com>
---
 CHANGES.md           |  1 +
 src/black/parsing.py | 52 +++++++++++++++++++++++++-------------------
 tests/test_black.py  | 32 ---------------------------
 3 files changed, 31 insertions(+), 54 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 611094f71e9..b3224e1c5b3 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -20,6 +20,7 @@
 - Fixed option usage when using the `--code` flag (#2259)
 - Do not call `uvloop.install()` when _Black_ is used as a library (#2303)
 - Added `--required-version` option to require a specific version to be running (#2300)
+- Provide a more useful error when parsing fails during AST safety checks (#2304)
 - Fix incorrect custom breakpoint indices when string group contains fake f-strings
   (#2311)
 - Fix regression where `R` prefixes would be lowercased for docstrings (#2285)
diff --git a/src/black/parsing.py b/src/black/parsing.py
index 8e9feea9120..0b8d984cedd 100644
--- a/src/black/parsing.py
+++ b/src/black/parsing.py
@@ -3,7 +3,7 @@
 """
 import ast
 import sys
-from typing import Iterable, Iterator, List, Set, Union
+from typing import Iterable, Iterator, List, Set, Union, Tuple
 
 # lib2to3 fork
 from blib2to3.pytree import Node, Leaf
@@ -106,28 +106,36 @@ def lib2to3_unparse(node: Node) -> str:
     return code
 
 
-def parse_ast(src: str) -> Union[ast.AST, ast3.AST, ast27.AST]:
+def parse_single_version(
+    src: str, version: Tuple[int, int]
+) -> Union[ast.AST, ast3.AST, ast27.AST]:
     filename = "<unknown>"
-    if sys.version_info >= (3, 8):
-        # TODO: support Python 4+ ;)
-        for minor_version in range(sys.version_info[1], 4, -1):
-            try:
-                return ast.parse(src, filename, feature_version=(3, minor_version))
-            except SyntaxError:
-                continue
-    else:
-        for feature_version in (7, 6):
-            try:
-                return ast3.parse(src, filename, feature_version=feature_version)
-            except SyntaxError:
-                continue
-    if ast27.__name__ == "ast":
-        raise SyntaxError(
-            "The requested source code has invalid Python 3 syntax.\n"
-            "If you are trying to format Python 2 files please reinstall Black"
-            " with the 'python2' extra: `python3 -m pip install black[python2]`."
-        )
-    return ast27.parse(src)
+    # typed_ast is needed because of feature version limitations in the builtin ast
+    if sys.version_info >= (3, 8) and version >= (3,):
+        return ast.parse(src, filename, feature_version=version)
+    elif version >= (3,):
+        return ast3.parse(src, filename, feature_version=version[1])
+    elif version == (2, 7):
+        return ast27.parse(src)
+    raise AssertionError("INTERNAL ERROR: Tried parsing unsupported Python version!")
+
+
+def parse_ast(src: str) -> Union[ast.AST, ast3.AST, ast27.AST]:
+    # TODO: support Python 4+ ;)
+    versions = [(3, minor) for minor in range(3, sys.version_info[1] + 1)]
+
+    if ast27.__name__ != "ast":
+        versions.append((2, 7))
+
+    first_error = ""
+    for version in sorted(versions, reverse=True):
+        try:
+            return parse_single_version(src, version)
+        except SyntaxError as e:
+            if not first_error:
+                first_error = str(e)
+
+    raise SyntaxError(first_error)
 
 
 def stringify_ast(
diff --git a/tests/test_black.py b/tests/test_black.py
index 42ac119324c..e3be9c71fd4 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -451,38 +451,6 @@ def test_skip_magic_trailing_comma(self) -> None:
             )
             self.assertEqual(expected, actual, msg)
 
-    @pytest.mark.no_python2
-    def test_python2_should_fail_without_optional_install(self) -> None:
-        if sys.version_info < (3, 8):
-            self.skipTest(
-                "Python 3.6 and 3.7 will install typed-ast to work and as such will be"
-                " able to parse Python 2 syntax without explicitly specifying the"
-                " python2 extra"
-            )
-
-        source = "x = 1234l"
-        tmp_file = Path(black.dump_to_file(source))
-        try:
-            runner = BlackRunner()
-            result = runner.invoke(black.main, [str(tmp_file)])
-            self.assertEqual(result.exit_code, 123)
-        finally:
-            os.unlink(tmp_file)
-        assert result.stderr_bytes is not None
-        actual = (
-            result.stderr_bytes.decode()
-            .replace("\n", "")
-            .replace("\\n", "")
-            .replace("\\r", "")
-            .replace("\r", "")
-        )
-        msg = (
-            "The requested source code has invalid Python 3 syntax."
-            "If you are trying to format Python 2 files please reinstall Black"
-            " with the 'python2' extra: `python3 -m pip install black[python2]`."
-        )
-        self.assertIn(msg, actual)
-
     @pytest.mark.python2
     @patch("black.dump_to_file", dump_to_stderr)
     def test_python2_print_function(self) -> None:

From 756177a617b5d84e7a77c5b085d19980a5a9f1f9 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Thu, 15 Jul 2021 20:21:53 -0400
Subject: [PATCH 0264/1034] Don't include profiling/ to cut down sdist by ~2x
 (#2362)

They seem to be used as test cases for a specific region of formatting
that was slow. Now performance testing is probably something end users
won't be needing to do, so this is an easy way of reducing the sdist
size sigificantly.
---
 MANIFEST.in | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 MANIFEST.in

diff --git a/MANIFEST.in b/MANIFEST.in
new file mode 100644
index 00000000000..5e53af336e2
--- /dev/null
+++ b/MANIFEST.in
@@ -0,0 +1 @@
+prune profiling

From 4622e4cb821efdc22d855eac586cb58d55426943 Mon Sep 17 00:00:00 2001
From: pszlazak <pszlazak@users.noreply.github.com>
Date: Fri, 16 Jul 2021 16:26:29 +0200
Subject: [PATCH 0265/1034] Create Docker tag 'latest_release' (#2374)

Docker images created during release process will have extra tag 'latest_release'.

This closes #2373.
---
 .github/workflows/docker.yml | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
index 419ec74ba3c..4bb41a17906 100644
--- a/.github/workflows/docker.yml
+++ b/.github/workflows/docker.yml
@@ -40,5 +40,14 @@ jobs:
           push: true
           tags: pyfound/black:latest,pyfound/black:${{ env.GIT_TAG }}
 
+      - name: Build and push latest_release tag
+        if: ${{ github.event_name == 'release' && github.event.action == 'created' }}
+        uses: docker/build-push-action@v2
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: pyfound/black:latest_release
+
       - name: Image digest
         run: echo ${{ steps.docker_build.outputs.digest }}

From e3000ace2fd1fcb1c181bb7a8285f1f976bcbdc7 Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Fri, 16 Jul 2021 07:42:47 -0700
Subject: [PATCH 0266/1034] Update CHANGES.md for 21.7b0 release (#2376)

* Update CHANGES.md for 21.7b0 release

* move some changes to the right section

* another one

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 CHANGES.md | 34 ++++++++++++++++++----------------
 1 file changed, 18 insertions(+), 16 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index b3224e1c5b3..30f809d5057 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,6 +1,6 @@
 # Change Log
 
-## Unreleased
+## 21.7b0
 
 ### _Black_
 
@@ -9,6 +9,21 @@
 - Add primer support and test for code piped into black via STDIN (#2315)
 - Fix internal error when `FORCE_OPTIONAL_PARENTHESES` feature is enabled (#2332)
 - Accept empty stdin (#2346)
+- Provide a more useful error when parsing fails during AST safety checks (#2304)
+
+### Docker
+
+- Add new `latest_release` tag automation to follow latest black release on docker
+  images (#2374)
+
+### Integrations
+
+- The vim plugin now searches upwards from the directory containing the current buffer
+  instead of the current working directory for pyproject.toml. (#1871)
+- The vim plugin now reads the correct string normalization option in pyproject.toml
+  (#1869)
+- The vim plugin no longer crashes Black when there's boolean values in pyproject.toml
+  (#1869)
 
 ## 21.6b0
 
@@ -20,7 +35,6 @@
 - Fixed option usage when using the `--code` flag (#2259)
 - Do not call `uvloop.install()` when _Black_ is used as a library (#2303)
 - Added `--required-version` option to require a specific version to be running (#2300)
-- Provide a more useful error when parsing fails during AST safety checks (#2304)
 - Fix incorrect custom breakpoint indices when string group contains fake f-strings
   (#2311)
 - Fix regression where `R` prefixes would be lowercased for docstrings (#2285)
@@ -29,15 +43,8 @@
 
 ### Integrations
 
-- The vim plugin now searches upwards from the directory containing the current buffer
-  instead of the current working directory for pyproject.toml. (#1871)
-
-### Integrations
-
-- The vim plugin now reads the correct string normalization option in pyproject.toml
-  (#1869)
-- The vim plugin no longer crashes Black when there's boolean values in pyproject.toml
-  (#1869)
+- The official Black action now supports choosing what version to use, and supports the
+  major 3 OSes. (#1940)
 
 ## 21.5b2
 
@@ -58,11 +65,6 @@
 - Add a lower bound for the `aiohttp-cors` dependency. Only 0.4.0 or higher is
   supported. (#2231)
 
-### Integrations
-
-- The official Black action now supports choosing what version to use, and supports the
-  major 3 OSes. (#1940)
-
 ### Packaging
 
 - Release self-contained x86_64 MacOS binaries as part of the GitHub release pipeline

From 4dd100bff283b3c60ce67491dd53f47b45f68ac2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bern=C3=A1t=20G=C3=A1bor?= <gaborjbernat@gmail.com>
Date: Fri, 16 Jul 2021 18:45:47 +0100
Subject: [PATCH 0267/1034] Use platformdirs over appdirs (#2375)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Bernát Gábor <bgabor8@bloomberg.net>
Signed-off-by: Bernát Gábor <gaborjbernat@gmail.com>
---
 CHANGES.md         |  4 +++
 Pipfile            |  2 +-
 Pipfile.lock       | 83 +++++++++++++++++++++++++++++-----------------
 setup.py           |  2 +-
 src/black/cache.py |  2 +-
 5 files changed, 59 insertions(+), 34 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 30f809d5057..6714a9d9eb2 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,5 +1,9 @@
 # Change Log
 
+## Unreleased
+
+- Moved from `appdirs` dependency to `platformdirs` (#2375)
+
 ## 21.7b0
 
 ### _Black_
diff --git a/Pipfile b/Pipfile
index e0d5d1a7969..8d75f30885d 100644
--- a/Pipfile
+++ b/Pipfile
@@ -27,7 +27,7 @@ black = {editable = true, extras = ["d"], path = "."}
 [packages]
 aiohttp = ">=3.6.0"
 aiohttp-cors = ">=0.4.0"
-appdirs = "*"
+platformdirs= ">=2"
 click = ">=8.0.0"
 mypy_extensions = ">=0.4.3"
 pathspec = ">=0.8.1"
diff --git a/Pipfile.lock b/Pipfile.lock
index 90923038adb..b553de86e6a 100644
--- a/Pipfile.lock
+++ b/Pipfile.lock
@@ -1,7 +1,7 @@
 {
     "_meta": {
         "hash": {
-            "sha256": "e6b7c19c10b5fba5ba20296b68049fab625b4c6d61db97b79d83a6dfa36d9f6d"
+            "sha256": "22f8394c2efe89a85bc1886c46c11c63d00a8d5e7d445ff1cf387b98984581a5"
         },
         "pipfile-spec": 6,
         "requires": {},
@@ -65,14 +65,6 @@
             "index": "pypi",
             "version": "==0.7.0"
         },
-        "appdirs": {
-            "hashes": [
-                "sha256:7d5d0167b2b1ba821647616af46a749d1c653740dd0d2415100fe26e27afdf41",
-                "sha256:a841dacd6b99318a741b166adb07e19ee71a274450e68237b4650ca1055ab128"
-            ],
-            "index": "pypi",
-            "version": "==1.4.4"
-        },
         "async-timeout": {
             "hashes": [
                 "sha256:0c3c816a028d47f659d6ff5c745cb2acf1f966da1fe5c19c77a70282b25f4c5f",
@@ -189,6 +181,14 @@
             "index": "pypi",
             "version": "==0.8.1"
         },
+        "platformdirs": {
+            "hashes": [
+                "sha256:0b9547541f599d3d242078ae60b927b3e453f0ad52f58b4d4bc3be86aed3ec41",
+                "sha256:3b00d081227d9037bbbca521a5787796b5ef5000faea1e43fd76f1d44b06fcfa"
+            ],
+            "index": "pypi",
+            "version": "==2.0.2"
+        },
         "regex": {
             "hashes": [
                 "sha256:0eb2c6e0fcec5e0f1d3bcc1133556563222a2ffd2211945d7b1480c1b1a42a6f",
@@ -402,14 +402,6 @@
             ],
             "version": "==0.7.12"
         },
-        "appdirs": {
-            "hashes": [
-                "sha256:7d5d0167b2b1ba821647616af46a749d1c653740dd0d2415100fe26e27afdf41",
-                "sha256:a841dacd6b99318a741b166adb07e19ee71a274450e68237b4650ca1055ab128"
-            ],
-            "index": "pypi",
-            "version": "==1.4.4"
-        },
         "async-timeout": {
             "hashes": [
                 "sha256:0c3c816a028d47f659d6ff5c745cb2acf1f966da1fe5c19c77a70282b25f4c5f",
@@ -434,6 +426,14 @@
             "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==2.9.1"
         },
+        "backports.entry-points-selectable": {
+            "hashes": [
+                "sha256:988468260ec1c196dab6ae1149260e2f5472c9110334e5d51adcb77867361f6a",
+                "sha256:a6d9a871cde5e15b4c4a53e3d43ba890cc6861ec1332c9c2428c92f977192acc"
+            ],
+            "markers": "python_version >= '2.7'",
+            "version": "==1.1.0"
+        },
         "black": {
             "editable": true,
             "extras": [
@@ -443,11 +443,11 @@
         },
         "bleach": {
             "hashes": [
-                "sha256:6123ddc1052673e52bab52cdc955bcb57a015264a1c57d37bea2f6b817af0125",
-                "sha256:98b3170739e5e83dd9dc19633f074727ad848cbedb6026708c8ac2d3b697a433"
+                "sha256:306483a5a9795474160ad57fce3ddd1b50551e981eed8e15a582d34cef28aafa",
+                "sha256:ae976d7174bba988c0b632def82fdc94235756edfb14e6558a9c5be555c9fb78"
             ],
             "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
-            "version": "==3.3.0"
+            "version": "==3.3.1"
         },
         "certifi": {
             "hashes": [
@@ -467,8 +467,10 @@
                 "sha256:3c8d896becff2fa653dc4438b54a5a25a971d1f4110b32bd3068db3722c80202",
                 "sha256:4373612d59c404baeb7cbd788a18b2b2a8331abcc84c3ba40051fcd18b17a4d5",
                 "sha256:487d63e1454627c8e47dd230025780e91869cfba4c753a74fda196a1f6ad6548",
+                "sha256:48916e459c54c4a70e52745639f1db524542140433599e13911b2f329834276a",
                 "sha256:4922cd707b25e623b902c86188aca466d3620892db76c0bdd7b99a3d5e61d35f",
                 "sha256:55af55e32ae468e9946f741a5d51f9896da6b9bf0bbdd326843fec05c730eb20",
+                "sha256:57e555a9feb4a8460415f1aac331a2dc833b1115284f7ded7278b54afc5bd218",
                 "sha256:5d4b68e216fc65e9fe4f524c177b54964af043dde734807586cf5435af84045c",
                 "sha256:64fda793737bc4037521d4899be780534b9aea552eb673b9833b01f945904c2e",
                 "sha256:6d6169cb3c6c2ad50db5b868db6491a790300ade1ed5d1da29289d73bbe40b56",
@@ -480,6 +482,7 @@
                 "sha256:9f3e33c28cd39d1b655ed1ba7247133b6f7fc16fa16887b120c0c670e35ce346",
                 "sha256:a8661b2ce9694ca01c529bfa204dbb144b275a31685a075ce123f12331be790b",
                 "sha256:a9da7010cec5a12193d1af9872a00888f396aba3dc79186604a09ea3ee7c029e",
+                "sha256:aedb15f0a5a5949ecb129a82b72b19df97bbbca024081ed2ef88bd5c0a610534",
                 "sha256:b315d709717a99f4b27b59b021e6207c64620790ca3e0bde636a6c7f14618abb",
                 "sha256:ba6f2b3f452e150945d58f4badd92310449876c4c954836cfb1803bdd7b422f0",
                 "sha256:c33d18eb6e6bc36f09d793c0dc58b0211fccc6ae5149b808da4a62660678b156",
@@ -493,10 +496,12 @@
                 "sha256:eb687a11f0a7a1839719edd80f41e459cc5366857ecbed383ff376c4e3cc6afd",
                 "sha256:eb9e2a346c5238a30a746893f23a9535e700f8192a68c07c0258e7ece6ff3728",
                 "sha256:ed38b924ce794e505647f7c331b22a693bee1538fdf46b0222c4717b42f744e7",
+                "sha256:f0010c6f9d1a4011e429109fda55a225921e3206e7f62a0c22a35344bfd13cca",
                 "sha256:f0c5d1acbfca6ebdd6b1e3eded8d261affb6ddcf2186205518f1428b8569bb99",
                 "sha256:f10afb1004f102c7868ebfe91c28f4a712227fe4cb24974350ace1f90e1febbf",
                 "sha256:f174135f5609428cc6e1b9090f9268f5c8935fddb1b25ccb8255a2d50de6789e",
                 "sha256:f3ebe6e73c319340830a9b2825d32eb6d8475c1dac020b4f0aa774ee3b898d1c",
+                "sha256:f627688813d0a4140153ff532537fbe4afea5a3dffce1f9deb7f91f848a832b5",
                 "sha256:fd4305f86f53dfd8cd3522269ed7fc34856a8ee3709a5e28b2836b2db9d4cd69"
             ],
             "version": "==1.14.6"
@@ -517,6 +522,14 @@
             "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
             "version": "==4.0.0"
         },
+        "charset-normalizer": {
+            "hashes": [
+                "sha256:3c502a35807c9df35697b0f44b1d65008f83071ff29c69677c7c22573bc5a45a",
+                "sha256:951567c2f7433a70ab63f1be67e5ee05d3925d9423306ecb71a3b272757bcc95"
+            ],
+            "markers": "python_version >= '3'",
+            "version": "==2.0.2"
+        },
         "click": {
             "hashes": [
                 "sha256:8c04c11192119b1ef78ea049e0a6f0463e4c48ef00a30160c704337586f3ad7a",
@@ -885,6 +898,14 @@
             ],
             "version": "==1.7.1"
         },
+        "platformdirs": {
+            "hashes": [
+                "sha256:0b9547541f599d3d242078ae60b927b3e453f0ad52f58b4d4bc3be86aed3ec41",
+                "sha256:3b00d081227d9037bbbca521a5787796b5ef5000faea1e43fd76f1d44b06fcfa"
+            ],
+            "index": "pypi",
+            "version": "==2.0.2"
+        },
         "pre-commit": {
             "hashes": [
                 "sha256:764972c60693dc668ba8e86eb29654ec3144501310f7198742a767bec385a378",
@@ -1032,11 +1053,11 @@
         },
         "requests": {
             "hashes": [
-                "sha256:27973dd4a904a4f13b263a19c866c13b92a39ed1c964655f025f3f8d3d75b804",
-                "sha256:c210084e36a42ae6b9219e00e48287def368a26d03a048ddad7bfee44f75871e"
+                "sha256:6c1246513ecd5ecd4528a0906f910e8f0f9c6b8ec72030dc9fd154dc1a6efd24",
+                "sha256:b8aa58f8cf793ffd8782d3d8cb19e66ef36f7aba4353eec859e74678b01b07a7"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
-            "version": "==2.25.1"
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4, 3.5'",
+            "version": "==2.26.0"
         },
         "requests-toolbelt": {
             "hashes": [
@@ -1085,11 +1106,11 @@
         },
         "sphinx": {
             "hashes": [
-                "sha256:4219f14258ca5612a0c85ed9b7222d54da69724d7e9dd92d1819ad1bf65e1ad2",
-                "sha256:51028bb0d3340eb80bcc1a2d614e8308ac78d226e6b796943daf57920abc1aea"
+                "sha256:23c846a1841af998cb736218539bb86d16f5eb95f5760b1966abcd2d584e62b8",
+                "sha256:3d513088236eef51e5b0adb78b0492eb22cc3b8ccdb0b36dd021173b365d4454"
             ],
             "index": "pypi",
-            "version": "==4.1.0"
+            "version": "==4.1.1"
         },
         "sphinx-copybutton": {
             "hashes": [
@@ -1232,11 +1253,11 @@
         },
         "virtualenv": {
             "hashes": [
-                "sha256:14fdf849f80dbb29a4eb6caa9875d476ee2a5cf76a5f5415fa2f1606010ab467",
-                "sha256:2b0126166ea7c9c3661f5b8e06773d28f83322de7a3ff7d06f0aed18c9de6a76"
+                "sha256:51df5d8a2fad5d1b13e088ff38a433475768ff61f202356bb9812c454c20ae45",
+                "sha256:e4fc84337dce37ba34ef520bf2d4392b392999dbe47df992870dc23230f6b758"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==20.4.7"
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
+            "version": "==20.6.0"
         },
         "webencodings": {
             "hashes": [
diff --git a/setup.py b/setup.py
index da25deab512..0a00638108c 100644
--- a/setup.py
+++ b/setup.py
@@ -73,7 +73,7 @@ def get_long_description() -> str:
     zip_safe=False,
     install_requires=[
         "click>=7.1.2",
-        "appdirs",
+        "platformdirs>=2",
         "tomli>=0.2.6,<2.0.0",
         "typed-ast>=1.4.2; python_version < '3.8'",
         "regex>=2020.1.8",
diff --git a/src/black/cache.py b/src/black/cache.py
index 017a2a91362..3f165de2ed6 100644
--- a/src/black/cache.py
+++ b/src/black/cache.py
@@ -6,7 +6,7 @@
 import tempfile
 from typing import Dict, Iterable, Set, Tuple
 
-from appdirs import user_cache_dir
+from platformdirs import user_cache_dir
 
 from black.mode import Mode
 

From 65abd1006bca13aa5fc12b173bf206dc261bd592 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Fri, 16 Jul 2021 19:21:34 -0700
Subject: [PATCH 0268/1034] add context manager to temporarily change the cwd
 (#2377)

Commit history before merge:

* add context manager to temporarily change the cwd
* Iterator, not Iterable
---
 tests/test_black.py | 43 ++++++++++++++++---------------------------
 tests/util.py       | 14 +++++++++++++-
 2 files changed, 29 insertions(+), 28 deletions(-)

diff --git a/tests/test_black.py b/tests/test_black.py
index e3be9c71fd4..998ecfcbdeb 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -44,6 +44,7 @@
 # Import other test classes
 from tests.util import (
     THIS_DIR,
+    change_directory,
     read_data,
     DETERMINISTIC_HEADER,
     BlackBaseTestCase,
@@ -2009,17 +2010,12 @@ def test_bpo_33660_workaround(self) -> None:
             return
 
         # https://bugs.python.org/issue33660
-
-        old_cwd = Path.cwd()
-        try:
-            root = Path("/")
-            os.chdir(str(root))
+        root = Path("/")
+        with change_directory(root):
             path = Path("workspace") / "project"
             report = black.Report(verbose=True)
             normalized_path = black.normalize_path_maybe_ignore(path, root, report)
             self.assertEqual(normalized_path, "workspace/project")
-        finally:
-            os.chdir(str(old_cwd))
 
     def test_newline_comment_interaction(self) -> None:
         source = "class A:\\\r\n# type: ignore\n pass\n"
@@ -2170,10 +2166,6 @@ def test_code_option_config(self) -> None:
         Test that the code option finds the pyproject.toml in the current directory.
         """
         with patch.object(black, "parse_pyproject_toml", return_value={}) as parse:
-            # Make sure we are in the project root with the pyproject file
-            if not Path("tests").exists():
-                os.chdir("..")
-
             args = ["--code", "print"]
             CliRunner().invoke(black.main, args)
 
@@ -2192,22 +2184,19 @@ def test_code_option_parent_config(self) -> None:
         Test that the code option finds the pyproject.toml in the parent directory.
         """
         with patch.object(black, "parse_pyproject_toml", return_value={}) as parse:
-            # Make sure we are in the tests directory
-            if Path("tests").exists():
-                os.chdir("tests")
-
-            args = ["--code", "print"]
-            CliRunner().invoke(black.main, args)
-
-            pyproject_path = Path(Path().cwd().parent, "pyproject.toml").resolve()
-            assert (
-                len(parse.mock_calls) >= 1
-            ), "Expected config parse to be called with the current directory."
-
-            _, call_args, _ = parse.mock_calls[0]
-            assert (
-                call_args[0].lower() == str(pyproject_path).lower()
-            ), "Incorrect config loaded."
+            with change_directory(Path("tests")):
+                args = ["--code", "print"]
+                CliRunner().invoke(black.main, args)
+
+                pyproject_path = Path(Path().cwd().parent, "pyproject.toml").resolve()
+                assert (
+                    len(parse.mock_calls) >= 1
+                ), "Expected config parse to be called with the current directory."
+
+                _, call_args, _ = parse.mock_calls[0]
+                assert (
+                    call_args[0].lower() == str(pyproject_path).lower()
+                ), "Incorrect config loaded."
 
 
 with open(black.__file__, "r", encoding="utf-8") as _bf:
diff --git a/tests/util.py b/tests/util.py
index 1e86a3f3d78..e83017f5ad3 100644
--- a/tests/util.py
+++ b/tests/util.py
@@ -1,7 +1,8 @@
 import os
 import unittest
 from pathlib import Path
-from typing import List, Tuple, Any
+from typing import Iterator, List, Tuple, Any
+from contextlib import contextmanager
 from functools import partial
 
 import black
@@ -72,3 +73,14 @@ def read_data_from_file(file_name: Path) -> Tuple[str, str]:
         # If there's no output marker, treat the entire file as already pre-formatted.
         _output = _input[:]
     return "".join(_input).strip() + "\n", "".join(_output).strip() + "\n"
+
+
+@contextmanager
+def change_directory(path: Path) -> Iterator[None]:
+    """Context manager to temporarily chdir to a different directory."""
+    previous_dir = os.getcwd()
+    try:
+        os.chdir(path)
+        yield
+    finally:
+        os.chdir(previous_dir)

From 6559bdbd9dcf71ba0017d66bb133c744bd83b0e3 Mon Sep 17 00:00:00 2001
From: David Szotten <davidszotten@gmail.com>
Date: Thu, 22 Jul 2021 15:04:53 +0100
Subject: [PATCH 0269/1034] isort docs have changed urls (#2390)

---
 docs/guides/using_black_with_other_tools.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/guides/using_black_with_other_tools.md b/docs/guides/using_black_with_other_tools.md
index 2b3855f7ef0..09421819ec3 100644
--- a/docs/guides/using_black_with_other_tools.md
+++ b/docs/guides/using_black_with_other_tools.md
@@ -24,10 +24,10 @@ to conflicting changes.
 #### Profile
 
 Since version 5.0.0, isort supports
-[profiles](https://pycqa.github.io/isort/docs/configuration/profiles/) to allow easy
+[profiles](https://pycqa.github.io/isort/docs/configuration/profiles.html) to allow easy
 interoperability with common code styles. You can set the black profile in any of the
-[config files](https://pycqa.github.io/isort/docs/configuration/config_files/) supported
-by isort. Below, an example for `pyproject.toml`:
+[config files](https://pycqa.github.io/isort/docs/configuration/config_files.html)
+supported by isort. Below, an example for `pyproject.toml`:
 
 ```toml
 [tool.isort]

From 6665677495974cb56e12d717d4e796bbc211dc6a Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Sat, 24 Jul 2021 15:59:53 -0700
Subject: [PATCH 0270/1034] Clarify contributing docs (#2398)

"as configurable as gofmt" means little to people who haven't used gofmt.
---
 docs/contributing/index.rst | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst
index 7e3a90905cd..480dbd6cd0e 100644
--- a/docs/contributing/index.rst
+++ b/docs/contributing/index.rst
@@ -15,8 +15,9 @@ Welcome! Happy to see you willing to make the project better. Have you read the
 
 .. rubric:: Bird's eye view
 
-In terms of inspiration, *Black* is about as configurable as *gofmt*. This is
-deliberate.
+In terms of inspiration, *Black* is about as configurable as *gofmt* (which is to say,
+not very). This is deliberate. *Black* aims to provide a consistent style and take away
+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.

From 982e7fd9deae3f755a4d5bc1a7757057a98d6245 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Sat, 24 Jul 2021 20:04:01 -0400
Subject: [PATCH 0271/1034] Add ESP to sqlalchemy for black-primer (#2400)

The crash has been fixed for a little while now. Tentatively assuming
that this will lead to changes.
---
 src/black_primer/primer.json | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/src/black_primer/primer.json b/src/black_primer/primer.json
index 90643987942..9665b491a81 100644
--- a/src/black_primer/primer.json
+++ b/src/black_primer/primer.json
@@ -112,9 +112,8 @@
       "py_versions": ["all"]
     },
     "sqlalchemy": {
-      "no_cli_args_reason": "breaks black with new string parsing - #2188",
-      "cli_arguments": [],
-      "expect_formatting_changes": false,
+      "cli_arguments": ["--experimental-string-processing"],
+      "expect_formatting_changes": true,
       "git_clone_url": "https://github.com/sqlalchemy/sqlalchemy.git",
       "long_checkout": false,
       "py_versions": ["all"]

From 4760b6e71e73809f8197a111486fb692cbc19692 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Tue, 27 Jul 2021 20:38:04 -0400
Subject: [PATCH 0272/1034] Fix issue templates + add docs template (#2399)

The template weren't applying the default labels ever since I renamed
the labels.

There has been enough issues about documentation opened recently so it's
probably worth a template for it.
---
 .github/ISSUE_TEMPLATE/bug_report.md      |  4 ++--
 .github/ISSUE_TEMPLATE/config.yml         | 12 ++++++++++
 .github/ISSUE_TEMPLATE/docs-issue.md      | 27 +++++++++++++++++++++++
 .github/ISSUE_TEMPLATE/feature_request.md |  2 +-
 .github/ISSUE_TEMPLATE/style_issue.md     |  2 +-
 5 files changed, 43 insertions(+), 4 deletions(-)
 create mode 100644 .github/ISSUE_TEMPLATE/config.yml
 create mode 100644 .github/ISSUE_TEMPLATE/docs-issue.md

diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
index 9924408b823..e8d232c8b34 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -1,8 +1,8 @@
 ---
 name: Bug report
-about: Create a report to help us improve
+about: Create a report to help us improve Black's quality
 title: ""
-labels: bug
+labels: "T: bug"
 assignees: ""
 ---
 
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 00000000000..67c3ce825ea
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,12 @@
+# See also: https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository#configuring-the-template-chooser
+
+# This is the default and blank issues are useful so let's keep 'em.
+blank_issues_enabled: true
+
+contact_links:
+  - name: Chat on Python Discord
+    url: https://discord.gg/RtVdv86PrH
+    about: |
+      User support, questions, and other lightweight requests can be
+      handled via the \#black-formatter text channel we have on Python
+      Discord.
diff --git a/.github/ISSUE_TEMPLATE/docs-issue.md b/.github/ISSUE_TEMPLATE/docs-issue.md
new file mode 100644
index 00000000000..d362b867eab
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/docs-issue.md
@@ -0,0 +1,27 @@
+---
+name: Documentation
+about: Report a problem with or suggest something for the documentation
+title: ""
+labels: "T: documentation"
+assignees: ""
+---
+
+**Is this related to a problem? Please describe.**
+
+<!-- A clear and concise description of what the problem is.
+e.g. I'm always frustrated when [...] / I wished that [...] -->
+
+**Describe the solution you'd like**
+
+<!-- A clear and concise description of what you want to
+happen or see changed. -->
+
+**Describe alternatives you've considered**
+
+<!-- A clear and concise description of any
+alternative solutions or features you've considered. -->
+
+**Additional context**
+
+<!-- Add any other context or screenshots about the issue
+here. -->
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
index 7c8cd1c1a07..a34e4a0e214 100644
--- a/.github/ISSUE_TEMPLATE/feature_request.md
+++ b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -2,7 +2,7 @@
 name: Feature request
 about: Suggest an idea for this project
 title: ""
-labels: enhancement
+labels: "T: enhancement"
 assignees: ""
 ---
 
diff --git a/.github/ISSUE_TEMPLATE/style_issue.md b/.github/ISSUE_TEMPLATE/style_issue.md
index 2ffd102712d..2e4343a3527 100644
--- a/.github/ISSUE_TEMPLATE/style_issue.md
+++ b/.github/ISSUE_TEMPLATE/style_issue.md
@@ -2,7 +2,7 @@
 name: Style issue
 about: Help us improve the Black style
 title: ""
-labels: design
+labels: "T: design"
 assignees: ""
 ---
 

From 8ea641eed5b9540287a8e9a9afa1458b72b9b630 Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <hugovk@users.noreply.github.com>
Date: Wed, 28 Jul 2021 17:29:11 +0300
Subject: [PATCH 0273/1034] Test on Python 3.10-dev (#2406)

---
 .github/workflows/fuzz.yml   | 2 +-
 .github/workflows/primer.yml | 2 +-
 .github/workflows/test.yml   | 2 +-
 tox.ini                      | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/fuzz.yml b/.github/workflows/fuzz.yml
index f3b688f3ef6..6b3ca6bb068 100644
--- a/.github/workflows/fuzz.yml
+++ b/.github/workflows/fuzz.yml
@@ -15,7 +15,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: [3.6, 3.7, 3.8, 3.9]
+        python-version: ["3.6", "3.7", "3.8", "3.9", "3.10-dev"]
 
     steps:
       - uses: actions/checkout@v2
diff --git a/.github/workflows/primer.yml b/.github/workflows/primer.yml
index 5f41c301737..8f7c11c824e 100644
--- a/.github/workflows/primer.yml
+++ b/.github/workflows/primer.yml
@@ -24,7 +24,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: [3.6, 3.7, 3.8, 3.9]
+        python-version: ["3.6", "3.7", "3.8", "3.9", "3.10-dev"]
         os: [ubuntu-latest, windows-latest]
 
     steps:
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 1db9f5d6d93..8e6b4a7a72d 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -24,7 +24,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: [3.6, 3.7, 3.8, 3.9]
+        python-version: ["3.6", "3.7", "3.8", "3.9", "3.10-dev"]
         os: [ubuntu-latest, macOS-latest, windows-latest]
 
     steps:
diff --git a/tox.ini b/tox.ini
index a97d18946b3..3767f98a73b 100644
--- a/tox.ini
+++ b/tox.ini
@@ -1,5 +1,5 @@
 [tox]
-envlist = {,ci-}py{36,37,38,39},fuzz
+envlist = {,ci-}py{36,37,38,39,310},fuzz
 
 [testenv]
 setenv = PYTHONPATH = {toxinidir}/src

From e76adbecb8c3b62631868332c3b632363c7c16b4 Mon Sep 17 00:00:00 2001
From: Taneli Hukkinen <3275109+hukkin@users.noreply.github.com>
Date: Fri, 6 Aug 2021 21:53:24 +0300
Subject: [PATCH 0274/1034] Fix type dependencies of mypy invocation (#2411)

Commit history before merge:

* Fix type dependencies of mypy invocation
* Consistent version upper bound
---
 .pre-commit-config.yaml |   3 +-
 Pipfile                 |   1 -
 Pipfile.lock            | 254 ++++++++++++++++++----------------------
 src/black/files.py      |   2 +-
 4 files changed, 118 insertions(+), 142 deletions(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 79795d1085f..ff9589bb3ce 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -25,9 +25,10 @@ repos:
         exclude: ^docs/conf.py
         additional_dependencies:
           - types-dataclasses >= 0.1.3
-          - types-toml >= 0.1.1
+          - tomli >= 0.2.6, < 2.0.0
           - types-typed-ast >= 1.4.1
           - click >= 8.0.0
+          - platformdirs >= 2.1.0
 
   - repo: https://github.com/pre-commit/mirrors-prettier
     rev: v2.3.1
diff --git a/Pipfile b/Pipfile
index 8d75f30885d..6527958c425 100644
--- a/Pipfile
+++ b/Pipfile
@@ -11,7 +11,6 @@ flake8 = "*"
 flake8-bugbear = "*"
 mypy = ">=0.812"
 types-dataclasses = ">=0.1.3"
-types-toml = ">=0.1.1"
 types-typed-ast = ">=1.4.1"
 pre-commit = "*"
 readme_renderer = "*"
diff --git a/Pipfile.lock b/Pipfile.lock
index b553de86e6a..3047a487657 100644
--- a/Pipfile.lock
+++ b/Pipfile.lock
@@ -1,7 +1,7 @@
 {
     "_meta": {
         "hash": {
-            "sha256": "22f8394c2efe89a85bc1886c46c11c63d00a8d5e7d445ff1cf387b98984581a5"
+            "sha256": "a02de7783dc48a2466cf52fc639b76f39823ccc87cee228521905f5fdb830b1f"
         },
         "pipfile-spec": 6,
         "requires": {},
@@ -175,66 +175,58 @@
         },
         "pathspec": {
             "hashes": [
-                "sha256:86379d6b86d75816baba717e64b1a3a3469deb93bb76d613c9ce79edc5cb68fd",
-                "sha256:aa0cb481c4041bf52ffa7b0d8fa6cd3e88a2ca4879c533c9153882ee2556790d"
+                "sha256:7d15c4ddb0b5c802d161efc417ec1a2558ea2653c2e8ad9c19098201dc1c993a",
+                "sha256:e564499435a2673d586f6b2130bb5b95f04a3ba06f81b8f895b651a3c76aabb1"
             ],
             "index": "pypi",
-            "version": "==0.8.1"
+            "version": "==0.9.0"
         },
         "platformdirs": {
             "hashes": [
-                "sha256:0b9547541f599d3d242078ae60b927b3e453f0ad52f58b4d4bc3be86aed3ec41",
-                "sha256:3b00d081227d9037bbbca521a5787796b5ef5000faea1e43fd76f1d44b06fcfa"
+                "sha256:4666d822218db6a262bdfdc9c39d21f23b4cfdb08af331a81e92751daf6c866c",
+                "sha256:632daad3ab546bd8e6af0537d09805cec458dce201bccfe23012df73332e181e"
             ],
             "index": "pypi",
-            "version": "==2.0.2"
+            "version": "==2.2.0"
         },
         "regex": {
             "hashes": [
-                "sha256:0eb2c6e0fcec5e0f1d3bcc1133556563222a2ffd2211945d7b1480c1b1a42a6f",
-                "sha256:15dddb19823f5147e7517bb12635b3c82e6f2a3a6b696cc3e321522e8b9308ad",
-                "sha256:173bc44ff95bc1e96398c38f3629d86fa72e539c79900283afa895694229fe6a",
-                "sha256:1c78780bf46d620ff4fff40728f98b8afd8b8e35c3efd638c7df67be2d5cddbf",
-                "sha256:2366fe0479ca0e9afa534174faa2beae87847d208d457d200183f28c74eaea59",
-                "sha256:2bceeb491b38225b1fee4517107b8491ba54fba77cf22a12e996d96a3c55613d",
-                "sha256:2ddeabc7652024803666ea09f32dd1ed40a0579b6fbb2a213eba590683025895",
-                "sha256:2fe5e71e11a54e3355fa272137d521a40aace5d937d08b494bed4529964c19c4",
-                "sha256:319eb2a8d0888fa6f1d9177705f341bc9455a2c8aca130016e52c7fe8d6c37a3",
-                "sha256:3f5716923d3d0bfb27048242a6e0f14eecdb2e2a7fac47eda1d055288595f222",
-                "sha256:422dec1e7cbb2efbbe50e3f1de36b82906def93ed48da12d1714cabcd993d7f0",
-                "sha256:4c9c3155fe74269f61e27617529b7f09552fbb12e44b1189cebbdb24294e6e1c",
-                "sha256:4f64fc59fd5b10557f6cd0937e1597af022ad9b27d454e182485f1db3008f417",
-                "sha256:564a4c8a29435d1f2256ba247a0315325ea63335508ad8ed938a4f14c4116a5d",
-                "sha256:59506c6e8bd9306cd8a41511e32d16d5d1194110b8cfe5a11d102d8b63cf945d",
-                "sha256:598c0a79b4b851b922f504f9f39a863d83ebdfff787261a5ed061c21e67dd761",
-                "sha256:59c00bb8dd8775473cbfb967925ad2c3ecc8886b3b2d0c90a8e2707e06c743f0",
-                "sha256:6110bab7eab6566492618540c70edd4d2a18f40ca1d51d704f1d81c52d245026",
-                "sha256:6afe6a627888c9a6cfbb603d1d017ce204cebd589d66e0703309b8048c3b0854",
-                "sha256:791aa1b300e5b6e5d597c37c346fb4d66422178566bbb426dd87eaae475053fb",
-                "sha256:8394e266005f2d8c6f0bc6780001f7afa3ef81a7a2111fa35058ded6fce79e4d",
-                "sha256:875c355360d0f8d3d827e462b29ea7682bf52327d500a4f837e934e9e4656068",
-                "sha256:89e5528803566af4df368df2d6f503c84fbfb8249e6631c7b025fe23e6bd0cde",
-                "sha256:99d8ab206a5270c1002bfcf25c51bf329ca951e5a169f3b43214fdda1f0b5f0d",
-                "sha256:9a854b916806c7e3b40e6616ac9e85d3cdb7649d9e6590653deb5b341a736cec",
-                "sha256:b85ac458354165405c8a84725de7bbd07b00d9f72c31a60ffbf96bb38d3e25fa",
-                "sha256:bc84fb254a875a9f66616ed4538542fb7965db6356f3df571d783f7c8d256edd",
-                "sha256:c92831dac113a6e0ab28bc98f33781383fe294df1a2c3dfd1e850114da35fd5b",
-                "sha256:cbe23b323988a04c3e5b0c387fe3f8f363bf06c0680daf775875d979e376bd26",
-                "sha256:ccb3d2190476d00414aab36cca453e4596e8f70a206e2aa8db3d495a109153d2",
-                "sha256:d8bbce0c96462dbceaa7ac4a7dfbbee92745b801b24bce10a98d2f2b1ea9432f",
-                "sha256:db2b7df831c3187a37f3bb80ec095f249fa276dbe09abd3d35297fc250385694",
-                "sha256:e586f448df2bbc37dfadccdb7ccd125c62b4348cb90c10840d695592aa1b29e0",
-                "sha256:e5983c19d0beb6af88cb4d47afb92d96751fb3fa1784d8785b1cdf14c6519407",
-                "sha256:e6a1e5ca97d411a461041d057348e578dc344ecd2add3555aedba3b408c9f874",
-                "sha256:eaf58b9e30e0e546cdc3ac06cf9165a1ca5b3de8221e9df679416ca667972035",
-                "sha256:ed693137a9187052fc46eedfafdcb74e09917166362af4cc4fddc3b31560e93d",
-                "sha256:edd1a68f79b89b0c57339bce297ad5d5ffcc6ae7e1afdb10f1947706ed066c9c",
-                "sha256:f080248b3e029d052bf74a897b9d74cfb7643537fbde97fe8225a6467fb559b5",
-                "sha256:f9392a4555f3e4cb45310a65b403d86b589adc773898c25a39184b1ba4db8985",
-                "sha256:f98dc35ab9a749276f1a4a38ab3e0e2ba1662ce710f6530f5b0a6656f1c32b58"
+                "sha256:026beb631097a4a3def7299aa5825e05e057de3c6d72b139c37813bfa351274b",
+                "sha256:14caacd1853e40103f59571f169704367e79fb78fac3d6d09ac84d9197cadd16",
+                "sha256:16d9eaa8c7e91537516c20da37db975f09ac2e7772a0694b245076c6d68f85da",
+                "sha256:18fdc51458abc0a974822333bd3a932d4e06ba2a3243e9a1da305668bd62ec6d",
+                "sha256:28e8af338240b6f39713a34e337c3813047896ace09d51593d6907c66c0708ba",
+                "sha256:3835de96524a7b6869a6c710b26c90e94558c31006e96ca3cf6af6751b27dca1",
+                "sha256:3905c86cc4ab6d71635d6419a6f8d972cab7c634539bba6053c47354fd04452c",
+                "sha256:3c09d88a07483231119f5017904db8f60ad67906efac3f1baa31b9b7f7cca281",
+                "sha256:4551728b767f35f86b8e5ec19a363df87450c7376d7419c3cac5b9ceb4bce576",
+                "sha256:459bbe342c5b2dec5c5223e7c363f291558bc27982ef39ffd6569e8c082bdc83",
+                "sha256:4f421e3cdd3a273bace013751c345f4ebeef08f05e8c10757533ada360b51a39",
+                "sha256:577737ec3d4c195c4aef01b757905779a9e9aee608fa1cf0aec16b5576c893d3",
+                "sha256:57fece29f7cc55d882fe282d9de52f2f522bb85290555b49394102f3621751ee",
+                "sha256:7976d410e42be9ae7458c1816a416218364e06e162b82e42f7060737e711d9ce",
+                "sha256:85f568892422a0e96235eb8ea6c5a41c8ccbf55576a2260c0160800dbd7c4f20",
+                "sha256:8764a78c5464ac6bde91a8c87dd718c27c1cabb7ed2b4beaf36d3e8e390567f9",
+                "sha256:8935937dad2c9b369c3d932b0edbc52a62647c2afb2fafc0c280f14a8bf56a6a",
+                "sha256:8fe58d9f6e3d1abf690174fd75800fda9bdc23d2a287e77758dc0e8567e38ce6",
+                "sha256:937b20955806381e08e54bd9d71f83276d1f883264808521b70b33d98e4dec5d",
+                "sha256:9569da9e78f0947b249370cb8fadf1015a193c359e7e442ac9ecc585d937f08d",
+                "sha256:a3b73390511edd2db2d34ff09aa0b2c08be974c71b4c0505b4a048d5dc128c2b",
+                "sha256:a4eddbe2a715b2dd3849afbdeacf1cc283160b24e09baf64fa5675f51940419d",
+                "sha256:a5c6dbe09aff091adfa8c7cfc1a0e83fdb8021ddb2c183512775a14f1435fe16",
+                "sha256:b63e3571b24a7959017573b6455e05b675050bbbea69408f35f3cb984ec54363",
+                "sha256:bb350eb1060591d8e89d6bac4713d41006cd4d479f5e11db334a48ff8999512f",
+                "sha256:bf6d987edd4a44dd2fa2723fca2790f9442ae4de2c8438e53fcb1befdf5d823a",
+                "sha256:bfa6a679410b394600eafd16336b2ce8de43e9b13f7fb9247d84ef5ad2b45e91",
+                "sha256:c856ec9b42e5af4fe2d8e75970fcc3a2c15925cbcc6e7a9bcb44583b10b95e80",
+                "sha256:cea56288eeda8b7511d507bbe7790d89ae7049daa5f51ae31a35ae3c05408531",
+                "sha256:ea212df6e5d3f60341aef46401d32fcfded85593af1d82b8b4a7a68cd67fdd6b",
+                "sha256:f35567470ee6dbfb946f069ed5f5615b40edcbb5f1e6e1d3d2b114468d505fc6",
+                "sha256:fbc20975eee093efa2071de80df7f972b7b35e560b213aafabcec7c0bd00bd8c",
+                "sha256:ff4a8ad9638b7ca52313d8732f37ecd5fd3c8e3aff10a8ccb93176fd5b3812f6"
             ],
             "index": "pypi",
-            "version": "==2021.7.6"
+            "version": "==2021.8.3"
         },
         "setuptools-scm": {
             "hashes": [
@@ -246,11 +238,11 @@
         },
         "tomli": {
             "hashes": [
-                "sha256:0713b16ff91df8638a6a694e295c8159ab35ba93e3424a626dd5226d386057be",
-                "sha256:be670d0d8d7570fd0ea0113bd7bb1ba3ac6706b4de062cc4c952769355c9c268"
+                "sha256:8dd0e9524d6f386271a36b41dbf6c57d8e32fd96fd22b6584679dc569d20899f",
+                "sha256:a5b75cb6f3968abb47af1b40c1819dc519ea82bcc065776a866e8d74c5ca9442"
             ],
             "index": "pypi",
-            "version": "==1.0.4"
+            "version": "==1.2.1"
         },
         "typed-ast": {
             "hashes": [
@@ -443,11 +435,11 @@
         },
         "bleach": {
             "hashes": [
-                "sha256:306483a5a9795474160ad57fce3ddd1b50551e981eed8e15a582d34cef28aafa",
-                "sha256:ae976d7174bba988c0b632def82fdc94235756edfb14e6558a9c5be555c9fb78"
+                "sha256:c1685a132e6a9a38bf93752e5faab33a9517a6c0bb2f37b785e47bf253bdb51d",
+                "sha256:ffa9221c6ac29399cc50fcc33473366edd0cf8d5e2cbbbb63296dc327fb67cc8"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
-            "version": "==3.3.1"
+            "markers": "python_version >= '3.6'",
+            "version": "==4.0.0"
         },
         "certifi": {
             "hashes": [
@@ -524,11 +516,11 @@
         },
         "charset-normalizer": {
             "hashes": [
-                "sha256:3c502a35807c9df35697b0f44b1d65008f83071ff29c69677c7c22573bc5a45a",
-                "sha256:951567c2f7433a70ab63f1be67e5ee05d3925d9423306ecb71a3b272757bcc95"
+                "sha256:0c8911edd15d19223366a194a513099a302055a962bca2cec0f54b8b63175d8b",
+                "sha256:f23667ebe1084be45f6ae0538e4a5a865206544097e4e8bbcacf42cd02a348f3"
             ],
             "markers": "python_version >= '3'",
-            "version": "==2.0.2"
+            "version": "==2.0.4"
         },
         "click": {
             "hashes": [
@@ -663,11 +655,11 @@
         },
         "identify": {
             "hashes": [
-                "sha256:7abaecbb414e385752e8ce02d8c494f4fbc780c975074b46172598a28f1ab839",
-                "sha256:a0e700637abcbd1caae58e0463861250095dfe330a8371733a471af706a4a29a"
+                "sha256:242332b3bdd45a8af1752d5d5a3afb12bee26f8e67c4be06e394f82d05ef1a4d",
+                "sha256:a510cbe155f39665625c8a4c4b4f9360cbce539f51f23f47836ab7dd852db541"
             ],
             "markers": "python_full_version >= '3.6.1'",
-            "version": "==2.2.11"
+            "version": "==2.2.12"
         },
         "idna": {
             "hashes": [
@@ -687,19 +679,19 @@
         },
         "importlib-metadata": {
             "hashes": [
-                "sha256:079ada16b7fc30dfbb5d13399a5113110dab1aa7c2bc62f66af75f0b717c8cac",
-                "sha256:9f55f560e116f8643ecf2922d9cd3e1c7e8d52e683178fecd9d08f6aa357e11e"
+                "sha256:0645585859e9a6689c523927a5032f2ba5919f1f7d0e84bd4533312320de1ff9",
+                "sha256:51c6635429c77cf1ae634c997ff9e53ca3438b495f10a55ba28594dd69764a8b"
             ],
             "markers": "python_version >= '3.6'",
-            "version": "==4.6.1"
+            "version": "==4.6.3"
         },
         "jeepney": {
             "hashes": [
-                "sha256:1237cd64c8f7ac3aa4b3f332c4d0fb4a8216f39eaa662ec904302d4d77de5a54",
-                "sha256:71335e7a4e93817982f473f3507bffc2eff7a544119ab9b73e089c8ba1409ba3"
+                "sha256:1b5a0ea5c0e7b166b2f5895b91a08c14de8915afda4407fb5022a195224958ac",
+                "sha256:fa9e232dfa0c498bd0b8a3a73b8d8a31978304dcef0515adc859d4e096f96f4f"
             ],
             "markers": "sys_platform == 'linux'",
-            "version": "==0.7.0"
+            "version": "==0.7.1"
         },
         "jinja2": {
             "hashes": [
@@ -885,11 +877,11 @@
         },
         "pathspec": {
             "hashes": [
-                "sha256:86379d6b86d75816baba717e64b1a3a3469deb93bb76d613c9ce79edc5cb68fd",
-                "sha256:aa0cb481c4041bf52ffa7b0d8fa6cd3e88a2ca4879c533c9153882ee2556790d"
+                "sha256:7d15c4ddb0b5c802d161efc417ec1a2558ea2653c2e8ad9c19098201dc1c993a",
+                "sha256:e564499435a2673d586f6b2130bb5b95f04a3ba06f81b8f895b651a3c76aabb1"
             ],
             "index": "pypi",
-            "version": "==0.8.1"
+            "version": "==0.9.0"
         },
         "pkginfo": {
             "hashes": [
@@ -900,11 +892,11 @@
         },
         "platformdirs": {
             "hashes": [
-                "sha256:0b9547541f599d3d242078ae60b927b3e453f0ad52f58b4d4bc3be86aed3ec41",
-                "sha256:3b00d081227d9037bbbca521a5787796b5ef5000faea1e43fd76f1d44b06fcfa"
+                "sha256:4666d822218db6a262bdfdc9c39d21f23b4cfdb08af331a81e92751daf6c866c",
+                "sha256:632daad3ab546bd8e6af0537d09805cec458dce201bccfe23012df73332e181e"
             ],
             "index": "pypi",
-            "version": "==2.0.2"
+            "version": "==2.2.0"
         },
         "pre-commit": {
             "hashes": [
@@ -1006,50 +998,42 @@
         },
         "regex": {
             "hashes": [
-                "sha256:0eb2c6e0fcec5e0f1d3bcc1133556563222a2ffd2211945d7b1480c1b1a42a6f",
-                "sha256:15dddb19823f5147e7517bb12635b3c82e6f2a3a6b696cc3e321522e8b9308ad",
-                "sha256:173bc44ff95bc1e96398c38f3629d86fa72e539c79900283afa895694229fe6a",
-                "sha256:1c78780bf46d620ff4fff40728f98b8afd8b8e35c3efd638c7df67be2d5cddbf",
-                "sha256:2366fe0479ca0e9afa534174faa2beae87847d208d457d200183f28c74eaea59",
-                "sha256:2bceeb491b38225b1fee4517107b8491ba54fba77cf22a12e996d96a3c55613d",
-                "sha256:2ddeabc7652024803666ea09f32dd1ed40a0579b6fbb2a213eba590683025895",
-                "sha256:2fe5e71e11a54e3355fa272137d521a40aace5d937d08b494bed4529964c19c4",
-                "sha256:319eb2a8d0888fa6f1d9177705f341bc9455a2c8aca130016e52c7fe8d6c37a3",
-                "sha256:3f5716923d3d0bfb27048242a6e0f14eecdb2e2a7fac47eda1d055288595f222",
-                "sha256:422dec1e7cbb2efbbe50e3f1de36b82906def93ed48da12d1714cabcd993d7f0",
-                "sha256:4c9c3155fe74269f61e27617529b7f09552fbb12e44b1189cebbdb24294e6e1c",
-                "sha256:4f64fc59fd5b10557f6cd0937e1597af022ad9b27d454e182485f1db3008f417",
-                "sha256:564a4c8a29435d1f2256ba247a0315325ea63335508ad8ed938a4f14c4116a5d",
-                "sha256:59506c6e8bd9306cd8a41511e32d16d5d1194110b8cfe5a11d102d8b63cf945d",
-                "sha256:598c0a79b4b851b922f504f9f39a863d83ebdfff787261a5ed061c21e67dd761",
-                "sha256:59c00bb8dd8775473cbfb967925ad2c3ecc8886b3b2d0c90a8e2707e06c743f0",
-                "sha256:6110bab7eab6566492618540c70edd4d2a18f40ca1d51d704f1d81c52d245026",
-                "sha256:6afe6a627888c9a6cfbb603d1d017ce204cebd589d66e0703309b8048c3b0854",
-                "sha256:791aa1b300e5b6e5d597c37c346fb4d66422178566bbb426dd87eaae475053fb",
-                "sha256:8394e266005f2d8c6f0bc6780001f7afa3ef81a7a2111fa35058ded6fce79e4d",
-                "sha256:875c355360d0f8d3d827e462b29ea7682bf52327d500a4f837e934e9e4656068",
-                "sha256:89e5528803566af4df368df2d6f503c84fbfb8249e6631c7b025fe23e6bd0cde",
-                "sha256:99d8ab206a5270c1002bfcf25c51bf329ca951e5a169f3b43214fdda1f0b5f0d",
-                "sha256:9a854b916806c7e3b40e6616ac9e85d3cdb7649d9e6590653deb5b341a736cec",
-                "sha256:b85ac458354165405c8a84725de7bbd07b00d9f72c31a60ffbf96bb38d3e25fa",
-                "sha256:bc84fb254a875a9f66616ed4538542fb7965db6356f3df571d783f7c8d256edd",
-                "sha256:c92831dac113a6e0ab28bc98f33781383fe294df1a2c3dfd1e850114da35fd5b",
-                "sha256:cbe23b323988a04c3e5b0c387fe3f8f363bf06c0680daf775875d979e376bd26",
-                "sha256:ccb3d2190476d00414aab36cca453e4596e8f70a206e2aa8db3d495a109153d2",
-                "sha256:d8bbce0c96462dbceaa7ac4a7dfbbee92745b801b24bce10a98d2f2b1ea9432f",
-                "sha256:db2b7df831c3187a37f3bb80ec095f249fa276dbe09abd3d35297fc250385694",
-                "sha256:e586f448df2bbc37dfadccdb7ccd125c62b4348cb90c10840d695592aa1b29e0",
-                "sha256:e5983c19d0beb6af88cb4d47afb92d96751fb3fa1784d8785b1cdf14c6519407",
-                "sha256:e6a1e5ca97d411a461041d057348e578dc344ecd2add3555aedba3b408c9f874",
-                "sha256:eaf58b9e30e0e546cdc3ac06cf9165a1ca5b3de8221e9df679416ca667972035",
-                "sha256:ed693137a9187052fc46eedfafdcb74e09917166362af4cc4fddc3b31560e93d",
-                "sha256:edd1a68f79b89b0c57339bce297ad5d5ffcc6ae7e1afdb10f1947706ed066c9c",
-                "sha256:f080248b3e029d052bf74a897b9d74cfb7643537fbde97fe8225a6467fb559b5",
-                "sha256:f9392a4555f3e4cb45310a65b403d86b589adc773898c25a39184b1ba4db8985",
-                "sha256:f98dc35ab9a749276f1a4a38ab3e0e2ba1662ce710f6530f5b0a6656f1c32b58"
+                "sha256:026beb631097a4a3def7299aa5825e05e057de3c6d72b139c37813bfa351274b",
+                "sha256:14caacd1853e40103f59571f169704367e79fb78fac3d6d09ac84d9197cadd16",
+                "sha256:16d9eaa8c7e91537516c20da37db975f09ac2e7772a0694b245076c6d68f85da",
+                "sha256:18fdc51458abc0a974822333bd3a932d4e06ba2a3243e9a1da305668bd62ec6d",
+                "sha256:28e8af338240b6f39713a34e337c3813047896ace09d51593d6907c66c0708ba",
+                "sha256:3835de96524a7b6869a6c710b26c90e94558c31006e96ca3cf6af6751b27dca1",
+                "sha256:3905c86cc4ab6d71635d6419a6f8d972cab7c634539bba6053c47354fd04452c",
+                "sha256:3c09d88a07483231119f5017904db8f60ad67906efac3f1baa31b9b7f7cca281",
+                "sha256:4551728b767f35f86b8e5ec19a363df87450c7376d7419c3cac5b9ceb4bce576",
+                "sha256:459bbe342c5b2dec5c5223e7c363f291558bc27982ef39ffd6569e8c082bdc83",
+                "sha256:4f421e3cdd3a273bace013751c345f4ebeef08f05e8c10757533ada360b51a39",
+                "sha256:577737ec3d4c195c4aef01b757905779a9e9aee608fa1cf0aec16b5576c893d3",
+                "sha256:57fece29f7cc55d882fe282d9de52f2f522bb85290555b49394102f3621751ee",
+                "sha256:7976d410e42be9ae7458c1816a416218364e06e162b82e42f7060737e711d9ce",
+                "sha256:85f568892422a0e96235eb8ea6c5a41c8ccbf55576a2260c0160800dbd7c4f20",
+                "sha256:8764a78c5464ac6bde91a8c87dd718c27c1cabb7ed2b4beaf36d3e8e390567f9",
+                "sha256:8935937dad2c9b369c3d932b0edbc52a62647c2afb2fafc0c280f14a8bf56a6a",
+                "sha256:8fe58d9f6e3d1abf690174fd75800fda9bdc23d2a287e77758dc0e8567e38ce6",
+                "sha256:937b20955806381e08e54bd9d71f83276d1f883264808521b70b33d98e4dec5d",
+                "sha256:9569da9e78f0947b249370cb8fadf1015a193c359e7e442ac9ecc585d937f08d",
+                "sha256:a3b73390511edd2db2d34ff09aa0b2c08be974c71b4c0505b4a048d5dc128c2b",
+                "sha256:a4eddbe2a715b2dd3849afbdeacf1cc283160b24e09baf64fa5675f51940419d",
+                "sha256:a5c6dbe09aff091adfa8c7cfc1a0e83fdb8021ddb2c183512775a14f1435fe16",
+                "sha256:b63e3571b24a7959017573b6455e05b675050bbbea69408f35f3cb984ec54363",
+                "sha256:bb350eb1060591d8e89d6bac4713d41006cd4d479f5e11db334a48ff8999512f",
+                "sha256:bf6d987edd4a44dd2fa2723fca2790f9442ae4de2c8438e53fcb1befdf5d823a",
+                "sha256:bfa6a679410b394600eafd16336b2ce8de43e9b13f7fb9247d84ef5ad2b45e91",
+                "sha256:c856ec9b42e5af4fe2d8e75970fcc3a2c15925cbcc6e7a9bcb44583b10b95e80",
+                "sha256:cea56288eeda8b7511d507bbe7790d89ae7049daa5f51ae31a35ae3c05408531",
+                "sha256:ea212df6e5d3f60341aef46401d32fcfded85593af1d82b8b4a7a68cd67fdd6b",
+                "sha256:f35567470ee6dbfb946f069ed5f5615b40edcbb5f1e6e1d3d2b114468d505fc6",
+                "sha256:fbc20975eee093efa2071de80df7f972b7b35e560b213aafabcec7c0bd00bd8c",
+                "sha256:ff4a8ad9638b7ca52313d8732f37ecd5fd3c8e3aff10a8ccb93176fd5b3812f6"
             ],
             "index": "pypi",
-            "version": "==2021.7.6"
+            "version": "==2021.8.3"
         },
         "requests": {
             "hashes": [
@@ -1106,11 +1090,11 @@
         },
         "sphinx": {
             "hashes": [
-                "sha256:23c846a1841af998cb736218539bb86d16f5eb95f5760b1966abcd2d584e62b8",
-                "sha256:3d513088236eef51e5b0adb78b0492eb22cc3b8ccdb0b36dd021173b365d4454"
+                "sha256:3092d929cd807926d846018f2ace47ba2f3b671b309c7a89cd3306e80c826b13",
+                "sha256:46d52c6cee13fec44744b8c01ed692c18a640f6910a725cbb938bc36e8d64544"
             ],
             "index": "pypi",
-            "version": "==4.1.1"
+            "version": "==4.1.2"
         },
         "sphinx-copybutton": {
             "hashes": [
@@ -1186,27 +1170,27 @@
         },
         "tomli": {
             "hashes": [
-                "sha256:0713b16ff91df8638a6a694e295c8159ab35ba93e3424a626dd5226d386057be",
-                "sha256:be670d0d8d7570fd0ea0113bd7bb1ba3ac6706b4de062cc4c952769355c9c268"
+                "sha256:8dd0e9524d6f386271a36b41dbf6c57d8e32fd96fd22b6584679dc569d20899f",
+                "sha256:a5b75cb6f3968abb47af1b40c1819dc519ea82bcc065776a866e8d74c5ca9442"
             ],
             "index": "pypi",
-            "version": "==1.0.4"
+            "version": "==1.2.1"
         },
         "tqdm": {
             "hashes": [
-                "sha256:5aa445ea0ad8b16d82b15ab342de6b195a722d75fc1ef9934a46bba6feafbc64",
-                "sha256:8bb94db0d4468fea27d004a0f1d1c02da3cdedc00fe491c0de986b76a04d6b0a"
+                "sha256:3642d483b558eec80d3c831e23953582c34d7e4540db86d9e5ed9dad238dabc6",
+                "sha256:706dea48ee05ba16e936ee91cb3791cd2ea6da348a0e50b46863ff4363ff4340"
             ],
             "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==4.61.2"
+            "version": "==4.62.0"
         },
         "twine": {
             "hashes": [
-                "sha256:16f706f2f1687d7ce30e7effceee40ed0a09b7c33b9abb5ef6434e5551565d83",
-                "sha256:a56c985264b991dc8a8f4234eb80c5af87fa8080d0c224ad8f2cd05a2c22e83b"
+                "sha256:087328e9bb405e7ce18527a2dca4042a84c7918658f951110b38bc135acab218",
+                "sha256:4caec0f1ed78dc4c9b83ad537e453d03ce485725f2aea57f1bb3fdde78dae936"
             ],
             "index": "pypi",
-            "version": "==3.4.1"
+            "version": "==3.4.2"
         },
         "types-dataclasses": {
             "hashes": [
@@ -1216,14 +1200,6 @@
             "index": "pypi",
             "version": "==0.1.5"
         },
-        "types-toml": {
-            "hashes": [
-                "sha256:33ebe67bebaec55a123ecbaa2bd98fe588335d8d8dda2c7ac53502ef5a81a79a",
-                "sha256:d4add39a90993173d49ff0b069edd122c66ad4cf5c01082b590e380ca670ee1a"
-            ],
-            "index": "pypi",
-            "version": "==0.1.3"
-        },
         "types-typed-ast": {
             "hashes": [
                 "sha256:014ab2742015d3eaab86ea061c27809c7e76beeb9e134102f2e2ddb34ab05c62",
@@ -1253,11 +1229,11 @@
         },
         "virtualenv": {
             "hashes": [
-                "sha256:51df5d8a2fad5d1b13e088ff38a433475768ff61f202356bb9812c454c20ae45",
-                "sha256:e4fc84337dce37ba34ef520bf2d4392b392999dbe47df992870dc23230f6b758"
+                "sha256:97066a978431ec096d163e72771df5357c5c898ffdd587048f45e0aecc228094",
+                "sha256:fdfdaaf0979ac03ae7f76d5224a05b58165f3c804f8aa633f3dd6f22fbd435d5"
             ],
             "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
-            "version": "==20.6.0"
+            "version": "==20.7.0"
         },
         "webencodings": {
             "hashes": [
diff --git a/src/black/files.py b/src/black/files.py
index 427ad668f48..213bbf82a58 100644
--- a/src/black/files.py
+++ b/src/black/files.py
@@ -92,7 +92,7 @@ def parse_pyproject_toml(path_config: str) -> Dict[str, Any]:
     If parsing fails, will raise a tomli.TOMLDecodeError
     """
     with open(path_config, encoding="utf8") as f:
-        pyproject_toml = tomli.load(f)
+        pyproject_toml = tomli.load(f)  # type: ignore  # due to deprecated API usage
     config = pyproject_toml.get("tool", {}).get("black", {})
     return {k.replace("--", "").replace("-", "_"): v for k, v in config.items()}
 

From b1d060101626aa1c332f52e4bdf0ae5e4cc07990 Mon Sep 17 00:00:00 2001
From: Marco Edward Gorelli <marcogorelli@protonmail.com>
Date: Fri, 6 Aug 2021 21:57:46 +0100
Subject: [PATCH 0275/1034] Jupyter notebook support (#2357)

To summarise, based on what was discussed in that issue:

due to not being able to parse automagics (e.g. pip install black)
without a running IPython kernel, cells with syntax which is parseable
by neither ast.parse nor IPython will be skipped cells with multiline
magics will be skipped trailing semicolons will be preserved, as they
are often put there intentionally in Jupyter Notebooks to suppress
unnecessary output

Commit history before merge (excluding merge commits):

* wip
* fixup tests
* skip tests if no IPython
* install test requirements in ipynb tests
* if --ipynb format all as ipynb
* wip
* add some whole-notebook tests
* docstrings
* skip multiline magics
* add test for nested cell magic
* remove ipynb_test.yml, put ipynb tests in tox.ini
* add changelog entry
* typo
* make token same length as magic it replaces
* only include .ipynb by default if jupyter dependencies are found
* remove logic from const
* fixup
* fixup
* re.compile
* noop
* clear up
* new_src -> dst
* early exit for non-python notebooks
* add non-python test notebook
* add repo with many notebooks to black-primer
* install extra dependencies for black-primer
* fix planetary computer examples url
* dont run on ipynb files by default
* add scikit-lego (Expected to change) to black-primer
* add ipynb-specific diff
* fixup
* run on all (including ipynb) by default
* remove --include .ipynb from scikit-lego black-primer
* use tokenize so as to mirror the exact logic in IPython.core.displayhooks quiet
* fixup
* :art:
* clarify docstring
* add test for when comment is after trailing semicolon
* enumerate(reversed) instead of [::-1]
* clarify docstrings
* wip
* use jupyter and no_jupyter marks
* use THIS_DIR
* windows fixup
* perform safe check cell-by-cell for ipynb
* only perform safe check in ipynb if not fast
* remove redundant Optional
* :art:
* use typeguard
* dont process cell containing transformed magic
* require typing extensions before 3.10 so as to have TypeGuard
* use dataclasses
* mention black[jupyter] in docs as well as in README
* add faq
* add message to assertion error
* add test for indented quieted cell
* use tokenize_rt else we cant roundtrip
* fmake fronzet set for tokens to ignore when looking for trailing semicolon
* remove planetary code examples as recent commits result in changes
* use dataclasses which inherit from ast.NodeVisitor
* bump typing-extensions so that TypeGuard is available
* bump typing-extensions in Pipfile
* add test with notebook with empty metadata
* pipenv lock
* deprivative validate_cell
* Update README.md
* Update docs/getting_started.md
* dont cache notebooks if jupyter dependencies arent found
* dont write to cache if jupyter deps are not installed
* add notebook which cant be parsed
* use clirunner
* remove other subprocess calls
* add docstring
* make verbose and quiet keyword only
* :art:
* run second many test on directory, not on file
* test for warning message when running on directory
* early return from non-python cell magics
* move NothingChanged to report to avoid circular import
* remove circular import
* reinstate --ipynb flag

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 .github/workflows/primer.yml                  |   2 +-
 .gitignore                                    |   1 +
 .pre-commit-hooks.yaml                        |  11 +
 CHANGES.md                                    |   5 +-
 Pipfile                                       |   2 +-
 README.md                                     |   3 +-
 docs/faq.md                                   |  23 +
 docs/getting_started.md                       |   3 +-
 pyproject.toml                                |   1 +
 setup.py                                      |   3 +-
 src/black/__init__.py                         | 191 +++++++-
 src/black/const.py                            |   2 +-
 src/black/files.py                            |  10 +
 src/black/handle_ipynb_magics.py              | 457 ++++++++++++++++++
 src/black/mode.py                             |   2 +
 src/black/output.py                           |  18 +
 src/black/report.py                           |   4 +
 src/black_primer/primer.json                  |   7 +
 tests/data/non_python_notebook.ipynb          |   1 +
 tests/data/notebook_empty_metadata.ipynb      |  27 ++
 tests/data/notebook_no_trailing_newline.ipynb |  39 ++
 tests/data/notebook_trailing_newline.ipynb    |  39 ++
 .../data/notebook_which_cant_be_parsed.ipynb  |   1 +
 tests/data/notebook_without_changes.ipynb     |  46 ++
 tests/test_black.py                           |  14 +
 tests/test_ipynb.py                           | 455 +++++++++++++++++
 tests/test_no_ipynb.py                        |  37 ++
 tox.ini                                       |   7 +
 28 files changed, 1383 insertions(+), 28 deletions(-)
 create mode 100644 src/black/handle_ipynb_magics.py
 create mode 100644 tests/data/non_python_notebook.ipynb
 create mode 100644 tests/data/notebook_empty_metadata.ipynb
 create mode 100644 tests/data/notebook_no_trailing_newline.ipynb
 create mode 100644 tests/data/notebook_trailing_newline.ipynb
 create mode 100644 tests/data/notebook_which_cant_be_parsed.ipynb
 create mode 100644 tests/data/notebook_without_changes.ipynb
 create mode 100644 tests/test_ipynb.py
 create mode 100644 tests/test_no_ipynb.py

diff --git a/.github/workflows/primer.yml b/.github/workflows/primer.yml
index 8f7c11c824e..01eb4ef6187 100644
--- a/.github/workflows/primer.yml
+++ b/.github/workflows/primer.yml
@@ -38,7 +38,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          python -m pip install -e ".[d]"
+          python -m pip install -e ".[d,jupyter]"
 
       - name: Primer run
         env:
diff --git a/.gitignore b/.gitignore
index ab796ce4cd0..f81bce8fd4e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -18,3 +18,4 @@ src/_black_version.py
 *.swp
 .hypothesis/
 venv/
+.ipynb_checkpoints/
diff --git a/.pre-commit-hooks.yaml b/.pre-commit-hooks.yaml
index de2eb674e0d..81848d7dcf7 100644
--- a/.pre-commit-hooks.yaml
+++ b/.pre-commit-hooks.yaml
@@ -7,3 +7,14 @@
   minimum_pre_commit_version: 2.9.2
   require_serial: true
   types_or: [python, pyi]
+- id: black-jupyter
+  name: black-jupyter
+  description:
+    "Black: The uncompromising Python code formatter (with Jupyter Notebook support)"
+  entry: black
+  language: python
+  language_version: python3
+  minimum_pre_commit_version: 2.9.2
+  require_serial: true
+  types_or: [python, pyi, jupyter]
+  additional_dependencies: [".[jupyter]"]
diff --git a/CHANGES.md b/CHANGES.md
index 6714a9d9eb2..a678aaefc2a 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -2,7 +2,10 @@
 
 ## Unreleased
 
-- Moved from `appdirs` dependency to `platformdirs` (#2375)
+### _Black_
+
+- Add support for formatting Jupyter Notebook files (#2357)
+- Move from `appdirs` dependency to `platformdirs` (#2375)
 
 ## 21.7b0
 
diff --git a/Pipfile b/Pipfile
index 6527958c425..433a3b392f7 100644
--- a/Pipfile
+++ b/Pipfile
@@ -33,6 +33,6 @@ pathspec = ">=0.8.1"
 regex = ">=2020.1.8"
 tomli = ">=0.2.6, <2.0.0"
 typed-ast = "==1.4.2"
-typing_extensions = {"python_version <" = "3.8","version >=" = "3.7.4"}
+typing_extensions = {"python_version <" = "3.10","version >=" = "3.10.0.0"}
 black = {editable = true,extras = ["d"],path = "."}
 dataclasses = {"python_version <" = "3.7","version >" = "0.1.3"}
diff --git a/README.md b/README.md
index 7b87a03fc38..709478e1d58 100644
--- a/README.md
+++ b/README.md
@@ -41,7 +41,8 @@ Try it out now using the [Black Playground](https://black.vercel.app). Watch the
 
 _Black_ can be installed by running `pip install black`. It requires Python 3.6.2+ to
 run. If you want to format Python 2 code as well, install with
-`pip install black[python2]`.
+`pip install black[python2]`. 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:
 
diff --git a/docs/faq.md b/docs/faq.md
index ac5ba937c1c..d7e6a16351f 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -37,6 +37,29 @@ Most likely because it is ignored in `.gitignore` or excluded with configuration
 [file collection and discovery](usage_and_configuration/file_collection_and_discovery.md)
 for details.
 
+## Why is my Jupyter Notebook cell not formatted?
+
+_Black_ is timid about formatting Jupyter Notebooks. Cells containing any of the
+following will not be formatted:
+
+- automagics (e.g. `pip install black`)
+- multiline magics, e.g.:
+
+  ```python
+  %timeit f(1, \
+          2, \
+          3)
+  ```
+
+- code which `IPython`'s `TransformerManager` would transform magics into, e.g.:
+
+  ```python
+  get_ipython().system('ls')
+  ```
+
+- invalid syntax, as it can't be safely distinguished from automagics in the absense of
+  a running `IPython` kernel.
+
 ## Why are Flake8's E203 and W503 violated?
 
 Because they go against PEP 8. E203 falsely triggers on list
diff --git a/docs/getting_started.md b/docs/getting_started.md
index a509d34e903..c79dc607c4a 100644
--- a/docs/getting_started.md
+++ b/docs/getting_started.md
@@ -18,7 +18,8 @@ Also, you can try out _Black_ online for minimal fuss on the
 
 _Black_ can be installed by running `pip install black`. It requires Python 3.6.2+ to
 run, but can format Python 2 code too. Python 2 support needs the `typed_ast`
-dependency, which be installed with `pip install black[python2]`.
+dependency, which be installed with `pip install black[python2]`. 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:
 
diff --git a/pyproject.toml b/pyproject.toml
index 79060fc422d..d085c0ddc62 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -31,4 +31,5 @@ build-backend = "setuptools.build_meta"
 optional-tests = [
   "no_python2: run when `python2` extra NOT installed",
   "no_blackd: run when `d` extra NOT installed",
+  "no_jupyter: run when `jupyter` extra NOT installed",
 ]
diff --git a/setup.py b/setup.py
index 0a00638108c..92b78f1abe1 100644
--- a/setup.py
+++ b/setup.py
@@ -79,7 +79,7 @@ def get_long_description() -> str:
         "regex>=2020.1.8",
         "pathspec>=0.8.1, <1",
         "dataclasses>=0.6; python_version < '3.7'",
-        "typing_extensions>=3.7.4; python_version < '3.8'",
+        "typing_extensions>=3.10.0.0; python_version < '3.10'",
         "mypy_extensions>=0.4.3",
     ],
     extras_require={
@@ -87,6 +87,7 @@ def get_long_description() -> str:
         "colorama": ["colorama>=0.4.3"],
         "python2": ["typed-ast>=1.4.2"],
         "uvloop": ["uvloop>=0.15.2"],
+        "jupyter": ["ipython>=7.8.0", "tokenize-rt>=3.2.0"],
     },
     test_suite="tests.test_black",
     classifiers=[
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 51384fb08da..29fb244f8b7 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -1,4 +1,6 @@
 import asyncio
+from json.decoder import JSONDecodeError
+import json
 from concurrent.futures import Executor, ThreadPoolExecutor, ProcessPoolExecutor
 from contextlib import contextmanager
 from datetime import datetime
@@ -18,6 +20,7 @@
     Generator,
     Iterator,
     List,
+    MutableMapping,
     Optional,
     Pattern,
     Set,
@@ -39,13 +42,21 @@
 from black.mode import Feature, supports_feature, VERSION_TO_FEATURES
 from black.cache import read_cache, write_cache, get_cache_info, filter_cached, Cache
 from black.concurrency import cancel, shutdown, maybe_install_uvloop
-from black.output import dump_to_file, diff, color_diff, out, err
-from black.report import Report, Changed
+from black.output import dump_to_file, ipynb_diff, diff, color_diff, out, err
+from black.report import Report, Changed, NothingChanged
 from black.files import find_project_root, find_pyproject_toml, parse_pyproject_toml
 from black.files import gen_python_files, get_gitignore, normalize_path_maybe_ignore
 from black.files import wrap_stream_for_windows
 from black.parsing import InvalidInput  # noqa F401
 from black.parsing import lib2to3_parse, parse_ast, stringify_ast
+from black.handle_ipynb_magics import (
+    mask_cell,
+    unmask_cell,
+    remove_trailing_semicolon,
+    put_trailing_semicolon_back,
+    TRANSFORMED_MAGICS,
+    jupyter_dependencies_are_installed,
+)
 
 
 # lib2to3 fork
@@ -60,10 +71,6 @@
 NewLine = str
 
 
-class NothingChanged(UserWarning):
-    """Raised when reformatted code is the same as source."""
-
-
 class WriteBack(Enum):
     NO = 0
     YES = 1
@@ -196,6 +203,14 @@ def validate_regex(
         " when piping source on standard input)."
     ),
 )
+@click.option(
+    "--ipynb",
+    is_flag=True,
+    help=(
+        "Format all input files like Jupyter Notebooks regardless of file extension "
+        "(useful when piping source on standard input)."
+    ),
+)
 @click.option(
     "-S",
     "--skip-string-normalization",
@@ -355,6 +370,7 @@ def main(
     color: bool,
     fast: bool,
     pyi: bool,
+    ipynb: bool,
     skip_string_normalization: bool,
     skip_magic_trailing_comma: bool,
     experimental_string_processing: bool,
@@ -380,6 +396,9 @@ def main(
             f" the running version `{__version__}`!"
         )
         ctx.exit(1)
+    if ipynb and pyi:
+        err("Cannot pass both `pyi` and `ipynb` flags!")
+        ctx.exit(1)
 
     write_back = WriteBack.from_configuration(check=check, diff=diff, color=color)
     if target_version:
@@ -391,6 +410,7 @@ def main(
         target_versions=versions,
         line_length=line_length,
         is_pyi=pyi,
+        is_ipynb=ipynb,
         string_normalization=not skip_string_normalization,
         magic_trailing_comma=not skip_magic_trailing_comma,
         experimental_string_processing=experimental_string_processing,
@@ -504,6 +524,11 @@ def get_sources(
             if is_stdin:
                 p = Path(f"{STDIN_PLACEHOLDER}{str(p)}")
 
+            if p.suffix == ".ipynb" and not jupyter_dependencies_are_installed(
+                verbose=verbose, quiet=quiet
+            ):
+                continue
+
             sources.add(p)
         elif p.is_dir():
             sources.update(
@@ -516,6 +541,8 @@ def get_sources(
                     force_exclude,
                     report,
                     gitignore,
+                    verbose=verbose,
+                    quiet=quiet,
                 )
             )
         elif s == "-":
@@ -585,6 +612,8 @@ def reformat_one(
         if is_stdin:
             if src.suffix == ".pyi":
                 mode = replace(mode, is_pyi=True)
+            elif src.suffix == ".ipynb":
+                mode = replace(mode, is_ipynb=True)
             if format_stdin_to_stdout(fast=fast, write_back=write_back, mode=mode):
                 changed = Changed.YES
         else:
@@ -733,6 +762,8 @@ def format_file_in_place(
     """
     if src.suffix == ".pyi":
         mode = replace(mode, is_pyi=True)
+    elif src.suffix == ".ipynb":
+        mode = replace(mode, is_ipynb=True)
 
     then = datetime.utcfromtimestamp(src.stat().st_mtime)
     with open(src, "rb") as buf:
@@ -741,6 +772,8 @@ def format_file_in_place(
         dst_contents = format_file_contents(src_contents, fast=fast, mode=mode)
     except NothingChanged:
         return False
+    except JSONDecodeError:
+        raise ValueError(f"File '{src}' cannot be parsed as valid Jupyter notebook.")
 
     if write_back == WriteBack.YES:
         with open(src, "w", encoding=encoding, newline=newline) as f:
@@ -749,7 +782,10 @@ def format_file_in_place(
         now = datetime.utcnow()
         src_name = f"{src}\t{then} +0000"
         dst_name = f"{src}\t{now} +0000"
-        diff_contents = diff(src_contents, dst_contents, src_name, dst_name)
+        if mode.is_ipynb:
+            diff_contents = ipynb_diff(src_contents, dst_contents, src_name, dst_name)
+        else:
+            diff_contents = diff(src_contents, dst_contents, src_name, dst_name)
 
         if write_back == WriteBack.COLOR_DIFF:
             diff_contents = color_diff(diff_contents)
@@ -819,6 +855,29 @@ def format_stdin_to_stdout(
         f.detach()
 
 
+def check_stability_and_equivalence(
+    src_contents: str, dst_contents: str, *, mode: Mode
+) -> None:
+    """Perform stability and equivalence checks.
+
+    Raise AssertionError if source and destination contents are not
+    equivalent, or if a second pass of the formatter would format the
+    content differently.
+    """
+    assert_equivalent(src_contents, dst_contents)
+
+    # Forced second pass to work around optional trailing commas (becoming
+    # forced trailing commas on pass 2) interacting differently with optional
+    # parentheses.  Admittedly ugly.
+    dst_contents_pass2 = format_str(dst_contents, mode=mode)
+    if dst_contents != dst_contents_pass2:
+        dst_contents = dst_contents_pass2
+        assert_equivalent(src_contents, dst_contents, pass_num=2)
+        assert_stable(src_contents, dst_contents, mode=mode)
+    # Note: no need to explicitly call `assert_stable` if `dst_contents` was
+    # the same as `dst_contents_pass2`.
+
+
 def format_file_contents(src_contents: str, *, fast: bool, mode: Mode) -> FileContent:
     """Reformat contents of a file and return new contents.
 
@@ -829,26 +888,116 @@ def format_file_contents(src_contents: str, *, fast: bool, mode: Mode) -> FileCo
     if not src_contents.strip():
         raise NothingChanged
 
-    dst_contents = format_str(src_contents, mode=mode)
+    if mode.is_ipynb:
+        dst_contents = format_ipynb_string(src_contents, fast=fast, mode=mode)
+    else:
+        dst_contents = format_str(src_contents, mode=mode)
     if src_contents == dst_contents:
         raise NothingChanged
 
-    if not fast:
-        assert_equivalent(src_contents, dst_contents)
-
-        # Forced second pass to work around optional trailing commas (becoming
-        # forced trailing commas on pass 2) interacting differently with optional
-        # parentheses.  Admittedly ugly.
-        dst_contents_pass2 = format_str(dst_contents, mode=mode)
-        if dst_contents != dst_contents_pass2:
-            dst_contents = dst_contents_pass2
-            assert_equivalent(src_contents, dst_contents, pass_num=2)
-            assert_stable(src_contents, dst_contents, mode=mode)
-        # Note: no need to explicitly call `assert_stable` if `dst_contents` was
-        # the same as `dst_contents_pass2`.
+    if not fast and not mode.is_ipynb:
+        # Jupyter notebooks will already have been checked above.
+        check_stability_and_equivalence(src_contents, dst_contents, mode=mode)
     return dst_contents
 
 
+def validate_cell(src: str) -> None:
+    """Check that cell does not already contain TransformerManager transformations.
+
+    If a cell contains ``!ls``, then it'll be transformed to
+    ``get_ipython().system('ls')``. However, if the cell originally contained
+    ``get_ipython().system('ls')``, then it would get transformed in the same way:
+
+        >>> TransformerManager().transform_cell("get_ipython().system('ls')")
+        "get_ipython().system('ls')\n"
+        >>> TransformerManager().transform_cell("!ls")
+        "get_ipython().system('ls')\n"
+
+    Due to the impossibility of safely roundtripping in such situations, cells
+    containing transformed magics will be ignored.
+    """
+    if any(transformed_magic in src for transformed_magic in TRANSFORMED_MAGICS):
+        raise NothingChanged
+
+
+def format_cell(src: str, *, fast: bool, mode: Mode) -> str:
+    """Format code in given cell of Jupyter notebook.
+
+    General idea is:
+
+      - if cell has trailing semicolon, remove it;
+      - if cell has IPython magics, mask them;
+      - format cell;
+      - reinstate IPython magics;
+      - reinstate trailing semicolon (if originally present);
+      - strip trailing newlines.
+
+    Cells with syntax errors will not be processed, as they
+    could potentially be automagics or multi-line magics, which
+    are currently not supported.
+    """
+    validate_cell(src)
+    src_without_trailing_semicolon, has_trailing_semicolon = remove_trailing_semicolon(
+        src
+    )
+    try:
+        masked_src, replacements = mask_cell(src_without_trailing_semicolon)
+    except SyntaxError:
+        raise NothingChanged
+    masked_dst = format_str(masked_src, mode=mode)
+    if not fast:
+        check_stability_and_equivalence(masked_src, masked_dst, mode=mode)
+    dst_without_trailing_semicolon = unmask_cell(masked_dst, replacements)
+    dst = put_trailing_semicolon_back(
+        dst_without_trailing_semicolon, has_trailing_semicolon
+    )
+    dst = dst.rstrip("\n")
+    if dst == src:
+        raise NothingChanged
+    return dst
+
+
+def validate_metadata(nb: MutableMapping[str, Any]) -> None:
+    """If notebook is marked as non-Python, don't format it.
+
+    All notebook metadata fields are optional, see
+    https://nbformat.readthedocs.io/en/latest/format_description.html. So
+    if a notebook has empty metadata, we will try to parse it anyway.
+    """
+    language = nb.get("metadata", {}).get("language_info", {}).get("name", None)
+    if language is not None and language != "python":
+        raise NothingChanged
+
+
+def format_ipynb_string(src_contents: str, *, fast: bool, mode: Mode) -> FileContent:
+    """Format Jupyter notebook.
+
+    Operate cell-by-cell, only on code cells, only for Python notebooks.
+    If the ``.ipynb`` originally had a trailing newline, it'll be preseved.
+    """
+    trailing_newline = src_contents[-1] == "\n"
+    modified = False
+    nb = json.loads(src_contents)
+    validate_metadata(nb)
+    for cell in nb["cells"]:
+        if cell.get("cell_type", None) == "code":
+            try:
+                src = "".join(cell["source"])
+                dst = format_cell(src, fast=fast, mode=mode)
+            except NothingChanged:
+                pass
+            else:
+                cell["source"] = dst.splitlines(keepends=True)
+                modified = True
+    if modified:
+        dst_contents = json.dumps(nb, indent=1, ensure_ascii=False)
+        if trailing_newline:
+            dst_contents = dst_contents + "\n"
+        return dst_contents
+    else:
+        raise NothingChanged
+
+
 def format_str(src_contents: str, *, mode: Mode) -> FileContent:
     """Reformat a string and return new contents.
 
diff --git a/src/black/const.py b/src/black/const.py
index 821258588ab..dbb4826be0e 100644
--- a/src/black/const.py
+++ b/src/black/const.py
@@ -1,4 +1,4 @@
 DEFAULT_LINE_LENGTH = 88
 DEFAULT_EXCLUDES = r"/(\.direnv|\.eggs|\.git|\.hg|\.mypy_cache|\.nox|\.tox|\.venv|venv|\.svn|_build|buck-out|build|dist)/"  # noqa: B950
-DEFAULT_INCLUDES = r"\.pyi?$"
+DEFAULT_INCLUDES = r"(\.pyi?|\.ipynb)$"
 STDIN_PLACEHOLDER = "__BLACK_STDIN_FILENAME__"
diff --git a/src/black/files.py b/src/black/files.py
index 213bbf82a58..ba60c84a275 100644
--- a/src/black/files.py
+++ b/src/black/files.py
@@ -22,6 +22,7 @@
 
 from black.output import err
 from black.report import Report
+from black.handle_ipynb_magics import jupyter_dependencies_are_installed
 
 if TYPE_CHECKING:
     import colorama  # noqa: F401
@@ -165,6 +166,9 @@ def gen_python_files(
     force_exclude: Optional[Pattern[str]],
     report: Report,
     gitignore: Optional[PathSpec],
+    *,
+    verbose: bool,
+    quiet: bool,
 ) -> Iterator[Path]:
     """Generate all files under `path` whose paths are not excluded by the
     `exclude_regex`, `extend_exclude`, or `force_exclude` regexes,
@@ -216,9 +220,15 @@ def gen_python_files(
                 force_exclude,
                 report,
                 gitignore + get_gitignore(child) if gitignore is not None else None,
+                verbose=verbose,
+                quiet=quiet,
             )
 
         elif child.is_file():
+            if child.suffix == ".ipynb" and not jupyter_dependencies_are_installed(
+                verbose=verbose, quiet=quiet
+            ):
+                continue
             include_match = include.search(normalized_path) if include else True
             if include_match:
                 yield child
diff --git a/src/black/handle_ipynb_magics.py b/src/black/handle_ipynb_magics.py
new file mode 100644
index 00000000000..ad93c444efc
--- /dev/null
+++ b/src/black/handle_ipynb_magics.py
@@ -0,0 +1,457 @@
+"""Functions to process IPython magics with."""
+from functools import lru_cache
+import dataclasses
+import ast
+from typing import Dict
+
+import secrets
+from typing import List, Tuple
+import collections
+
+from typing import Optional
+from typing_extensions import TypeGuard
+from black.report import NothingChanged
+from black.output import out
+
+
+TRANSFORMED_MAGICS = frozenset(
+    (
+        "get_ipython().run_cell_magic",
+        "get_ipython().system",
+        "get_ipython().getoutput",
+        "get_ipython().run_line_magic",
+    )
+)
+TOKENS_TO_IGNORE = frozenset(
+    (
+        "ENDMARKER",
+        "NL",
+        "NEWLINE",
+        "COMMENT",
+        "DEDENT",
+        "UNIMPORTANT_WS",
+        "ESCAPED_NL",
+    )
+)
+NON_PYTHON_CELL_MAGICS = frozenset(
+    (
+        "%%bash",
+        "%%html",
+        "%%javascript",
+        "%%js",
+        "%%latex",
+        "%%markdown",
+        "%%perl",
+        "%%ruby",
+        "%%script",
+        "%%sh",
+        "%%svg",
+        "%%writefile",
+    )
+)
+
+
+@dataclasses.dataclass(frozen=True)
+class Replacement:
+    mask: str
+    src: str
+
+
+@lru_cache()
+def jupyter_dependencies_are_installed(*, verbose: bool, quiet: bool) -> bool:
+    try:
+        import IPython  # noqa:F401
+        import tokenize_rt  # noqa:F401
+    except ModuleNotFoundError:
+        if verbose or not quiet:
+            msg = (
+                "Skipping .ipynb files as Jupyter dependencies are not installed.\n"
+                "You can fix this by running ``pip install black[jupyter]``"
+            )
+            out(msg)
+        return False
+    else:
+        return True
+
+
+def remove_trailing_semicolon(src: str) -> Tuple[str, bool]:
+    """Remove trailing semicolon from Jupyter notebook cell.
+
+    For example,
+
+        fig, ax = plt.subplots()
+        ax.plot(x_data, y_data);  # plot data
+
+    would become
+
+        fig, ax = plt.subplots()
+        ax.plot(x_data, y_data)  # plot data
+
+    Mirrors the logic in `quiet` from `IPython.core.displayhook`, but uses
+    ``tokenize_rt`` so that round-tripping works fine.
+    """
+    from tokenize_rt import (
+        src_to_tokens,
+        tokens_to_src,
+        reversed_enumerate,
+    )
+
+    tokens = src_to_tokens(src)
+    trailing_semicolon = False
+    for idx, token in reversed_enumerate(tokens):
+        if token.name in TOKENS_TO_IGNORE:
+            continue
+        if token.name == "OP" and token.src == ";":
+            del tokens[idx]
+            trailing_semicolon = True
+        break
+    if not trailing_semicolon:
+        return src, False
+    return tokens_to_src(tokens), True
+
+
+def put_trailing_semicolon_back(src: str, has_trailing_semicolon: bool) -> str:
+    """Put trailing semicolon back if cell originally had it.
+
+    Mirrors the logic in `quiet` from `IPython.core.displayhook`, but uses
+    ``tokenize_rt`` so that round-tripping works fine.
+    """
+    if not has_trailing_semicolon:
+        return src
+    from tokenize_rt import src_to_tokens, tokens_to_src, reversed_enumerate
+
+    tokens = src_to_tokens(src)
+    for idx, token in reversed_enumerate(tokens):
+        if token.name in TOKENS_TO_IGNORE:
+            continue
+        tokens[idx] = token._replace(src=token.src + ";")
+        break
+    else:  # pragma: nocover
+        raise AssertionError(
+            "INTERNAL ERROR: Was not able to reinstate trailing semicolon. "
+            "Please report a bug on https://github.com/psf/black/issues.  "
+        ) from None
+    return str(tokens_to_src(tokens))
+
+
+def mask_cell(src: str) -> Tuple[str, List[Replacement]]:
+    """Mask IPython magics so content becomes parseable Python code.
+
+    For example,
+
+        %matplotlib inline
+        'foo'
+
+    becomes
+
+        "25716f358c32750e"
+        'foo'
+
+    The replacements are returned, along with the transformed code.
+    """
+    replacements: List[Replacement] = []
+    try:
+        ast.parse(src)
+    except SyntaxError:
+        # Might have IPython magics, will process below.
+        pass
+    else:
+        # Syntax is fine, nothing to mask, early return.
+        return src, replacements
+
+    from IPython.core.inputtransformer2 import TransformerManager
+
+    transformer_manager = TransformerManager()
+    transformed = transformer_manager.transform_cell(src)
+    transformed, cell_magic_replacements = replace_cell_magics(transformed)
+    replacements += cell_magic_replacements
+    transformed = transformer_manager.transform_cell(transformed)
+    transformed, magic_replacements = replace_magics(transformed)
+    if len(transformed.splitlines()) != len(src.splitlines()):
+        # Multi-line magic, not supported.
+        raise NothingChanged
+    replacements += magic_replacements
+    return transformed, replacements
+
+
+def get_token(src: str, magic: str) -> str:
+    """Return randomly generated token to mask IPython magic with.
+
+    For example, if 'magic' was `%matplotlib inline`, then a possible
+    token to mask it with would be `"43fdd17f7e5ddc83"`. The token
+    will be the same length as the magic, and we make sure that it was
+    not already present anywhere else in the cell.
+    """
+    assert magic
+    nbytes = max(len(magic) // 2 - 1, 1)
+    token = secrets.token_hex(nbytes)
+    counter = 0
+    while token in src:  # pragma: nocover
+        token = secrets.token_hex(nbytes)
+        counter += 1
+        if counter > 100:
+            raise AssertionError(
+                "INTERNAL ERROR: Black was not able to replace IPython magic. "
+                "Please report a bug on https://github.com/psf/black/issues.  "
+                f"The magic might be helpful: {magic}"
+            ) from None
+    if len(token) + 2 < len(magic):
+        token = f"{token}."
+    return f'"{token}"'
+
+
+def replace_cell_magics(src: str) -> Tuple[str, List[Replacement]]:
+    """Replace cell magic with token.
+
+    Note that 'src' will already have been processed by IPython's
+    TransformerManager().transform_cell.
+
+    Example,
+
+        get_ipython().run_cell_magic('t', '-n1', 'ls =!ls\\n')
+
+    becomes
+
+        "a794."
+        ls =!ls
+
+    The replacement, along with the transformed code, is returned.
+    """
+    replacements: List[Replacement] = []
+
+    tree = ast.parse(src)
+
+    cell_magic_finder = CellMagicFinder()
+    cell_magic_finder.visit(tree)
+    if cell_magic_finder.cell_magic is None:
+        return src, replacements
+    if cell_magic_finder.cell_magic.header.split()[0] in NON_PYTHON_CELL_MAGICS:
+        raise NothingChanged
+    mask = get_token(src, cell_magic_finder.cell_magic.header)
+    replacements.append(Replacement(mask=mask, src=cell_magic_finder.cell_magic.header))
+    return f"{mask}\n{cell_magic_finder.cell_magic.body}", replacements
+
+
+def replace_magics(src: str) -> Tuple[str, List[Replacement]]:
+    """Replace magics within body of cell.
+
+    Note that 'src' will already have been processed by IPython's
+    TransformerManager().transform_cell.
+
+    Example, this
+
+        get_ipython().run_line_magic('matplotlib', 'inline')
+        'foo'
+
+    becomes
+
+        "5e67db56d490fd39"
+        'foo'
+
+    The replacement, along with the transformed code, are returned.
+    """
+    replacements = []
+    magic_finder = MagicFinder()
+    magic_finder.visit(ast.parse(src))
+    new_srcs = []
+    for i, line in enumerate(src.splitlines(), start=1):
+        if i in magic_finder.magics:
+            offsets_and_magics = magic_finder.magics[i]
+            if len(offsets_and_magics) != 1:  # pragma: nocover
+                raise AssertionError(
+                    f"Expecting one magic per line, got: {offsets_and_magics}\n"
+                    "Please report a bug on https://github.com/psf/black/issues."
+                )
+            col_offset, magic = (
+                offsets_and_magics[0].col_offset,
+                offsets_and_magics[0].magic,
+            )
+            mask = get_token(src, magic)
+            replacements.append(Replacement(mask=mask, src=magic))
+            line = line[:col_offset] + mask
+        new_srcs.append(line)
+    return "\n".join(new_srcs), replacements
+
+
+def unmask_cell(src: str, replacements: List[Replacement]) -> str:
+    """Remove replacements from cell.
+
+    For example
+
+        "9b20"
+        foo = bar
+
+    becomes
+
+        %%time
+        foo = bar
+    """
+    for replacement in replacements:
+        src = src.replace(replacement.mask, replacement.src)
+    return src
+
+
+def _is_ipython_magic(node: ast.expr) -> TypeGuard[ast.Attribute]:
+    """Check if attribute is IPython magic.
+
+    Note that the source of the abstract syntax tree
+    will already have been processed by IPython's
+    TransformerManager().transform_cell.
+    """
+    return (
+        isinstance(node, ast.Attribute)
+        and isinstance(node.value, ast.Call)
+        and isinstance(node.value.func, ast.Name)
+        and node.value.func.id == "get_ipython"
+    )
+
+
+@dataclasses.dataclass(frozen=True)
+class CellMagic:
+    header: str
+    body: str
+
+
+@dataclasses.dataclass
+class CellMagicFinder(ast.NodeVisitor):
+    """Find cell magics.
+
+    Note that the source of the abstract syntax tree
+    will already have been processed by IPython's
+    TransformerManager().transform_cell.
+
+    For example,
+
+        %%time\nfoo()
+
+    would have been transformed to
+
+        get_ipython().run_cell_magic('time', '', 'foo()\\n')
+
+    and we look for instances of the latter.
+    """
+
+    cell_magic: Optional[CellMagic] = None
+
+    def visit_Expr(self, node: ast.Expr) -> None:
+        """Find cell magic, extract header and body."""
+        if (
+            isinstance(node.value, ast.Call)
+            and _is_ipython_magic(node.value.func)
+            and node.value.func.attr == "run_cell_magic"
+        ):
+            args = []
+            for arg in node.value.args:
+                assert isinstance(arg, ast.Str)
+                args.append(arg.s)
+            header = f"%%{args[0]}"
+            if args[1]:
+                header += f" {args[1]}"
+            self.cell_magic = CellMagic(header=header, body=args[2])
+        self.generic_visit(node)
+
+
+@dataclasses.dataclass(frozen=True)
+class OffsetAndMagic:
+    col_offset: int
+    magic: str
+
+
+@dataclasses.dataclass
+class MagicFinder(ast.NodeVisitor):
+    """Visit cell to look for get_ipython calls.
+
+    Note that the source of the abstract syntax tree
+    will already have been processed by IPython's
+    TransformerManager().transform_cell.
+
+    For example,
+
+        %matplotlib inline
+
+    would have been transformed to
+
+        get_ipython().run_line_magic('matplotlib', 'inline')
+
+    and we look for instances of the latter (and likewise for other
+    types of magics).
+    """
+
+    magics: Dict[int, List[OffsetAndMagic]] = dataclasses.field(
+        default_factory=lambda: collections.defaultdict(list)
+    )
+
+    def visit_Assign(self, node: ast.Assign) -> None:
+        """Look for system assign magics.
+
+        For example,
+
+            black_version = !black --version
+
+        would have been transformed to
+
+            black_version = get_ipython().getoutput('black --version')
+
+        and we look for instances of the latter.
+        """
+        if (
+            isinstance(node.value, ast.Call)
+            and _is_ipython_magic(node.value.func)
+            and node.value.func.attr == "getoutput"
+        ):
+            args = []
+            for arg in node.value.args:
+                assert isinstance(arg, ast.Str)
+                args.append(arg.s)
+            assert args
+            src = f"!{args[0]}"
+            self.magics[node.value.lineno].append(
+                OffsetAndMagic(node.value.col_offset, src)
+            )
+        self.generic_visit(node)
+
+    def visit_Expr(self, node: ast.Expr) -> None:
+        """Look for magics in body of cell.
+
+        For examples,
+
+            !ls
+            !!ls
+            ?ls
+            ??ls
+
+        would (respectively) get transformed to
+
+            get_ipython().system('ls')
+            get_ipython().getoutput('ls')
+            get_ipython().run_line_magic('pinfo', 'ls')
+            get_ipython().run_line_magic('pinfo2', 'ls')
+
+        and we look for instances of any of the latter.
+        """
+        if isinstance(node.value, ast.Call) and _is_ipython_magic(node.value.func):
+            args = []
+            for arg in node.value.args:
+                assert isinstance(arg, ast.Str)
+                args.append(arg.s)
+            assert args
+            if node.value.func.attr == "run_line_magic":
+                if args[0] == "pinfo":
+                    src = f"?{args[1]}"
+                elif args[0] == "pinfo2":
+                    src = f"??{args[1]}"
+                else:
+                    src = f"%{args[0]}"
+                    if args[1]:
+                        assert src is not None
+                        src += f" {args[1]}"
+            elif node.value.func.attr == "system":
+                src = f"!{args[0]}"
+            elif node.value.func.attr == "getoutput":
+                src = f"!!{args[0]}"
+            else:
+                raise NothingChanged  # unsupported magic.
+            self.magics[node.value.lineno].append(
+                OffsetAndMagic(node.value.col_offset, src)
+            )
+        self.generic_visit(node)
diff --git a/src/black/mode.py b/src/black/mode.py
index e2ce322da5c..0b7624eaf8a 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -101,6 +101,7 @@ class Mode:
     line_length: int = DEFAULT_LINE_LENGTH
     string_normalization: bool = True
     is_pyi: bool = False
+    is_ipynb: bool = False
     magic_trailing_comma: bool = True
     experimental_string_processing: bool = False
 
@@ -117,6 +118,7 @@ def get_cache_key(self) -> str:
             str(self.line_length),
             str(int(self.string_normalization)),
             str(int(self.is_pyi)),
+            str(int(self.is_ipynb)),
             str(int(self.magic_trailing_comma)),
             str(int(self.experimental_string_processing)),
         ]
diff --git a/src/black/output.py b/src/black/output.py
index c253c85e90e..fd3dbb37627 100644
--- a/src/black/output.py
+++ b/src/black/output.py
@@ -3,6 +3,7 @@
 The double calls are for patching purposes in tests.
 """
 
+import json
 from typing import Any, Optional
 from mypy_extensions import mypyc_attr
 import tempfile
@@ -34,6 +35,23 @@ def err(message: Optional[str] = None, nl: bool = True, **styles: Any) -> None:
     _err(message, nl=nl, **styles)
 
 
+def ipynb_diff(a: str, b: str, a_name: str, b_name: str) -> str:
+    """Return a unified diff string between each cell in notebooks `a` and `b`."""
+    a_nb = json.loads(a)
+    b_nb = json.loads(b)
+    diff_lines = [
+        diff(
+            "".join(a_nb["cells"][cell_number]["source"]) + "\n",
+            "".join(b_nb["cells"][cell_number]["source"]) + "\n",
+            f"{a_name}:cell_{cell_number}",
+            f"{b_name}:cell_{cell_number}",
+        )
+        for cell_number, cell in enumerate(a_nb["cells"])
+        if cell["cell_type"] == "code"
+    ]
+    return "".join(diff_lines)
+
+
 def diff(a: str, b: str, a_name: str, b_name: str) -> str:
     """Return a unified diff string between strings `a` and `b`."""
     import difflib
diff --git a/src/black/report.py b/src/black/report.py
index 8fc5da2e167..7e1c8b4b87f 100644
--- a/src/black/report.py
+++ b/src/black/report.py
@@ -16,6 +16,10 @@ class Changed(Enum):
     YES = 2
 
 
+class NothingChanged(UserWarning):
+    """Raised when reformatted code is the same as source."""
+
+
 @dataclass
 class Report:
     """Provides a reformatting counter. Can be rendered with `str(report)`."""
diff --git a/src/black_primer/primer.json b/src/black_primer/primer.json
index 9665b491a81..edbed3f33dd 100644
--- a/src/black_primer/primer.json
+++ b/src/black_primer/primer.json
@@ -111,6 +111,13 @@
       "long_checkout": false,
       "py_versions": ["all"]
     },
+    "scikit-lego": {
+      "cli_arguments": ["--experimental-string-processing"],
+      "expect_formatting_changes": true,
+      "git_clone_url": "https://github.com/koaning/scikit-lego",
+      "long_checkout": false,
+      "py_versions": ["all"]
+    },
     "sqlalchemy": {
       "cli_arguments": ["--experimental-string-processing"],
       "expect_formatting_changes": true,
diff --git a/tests/data/non_python_notebook.ipynb b/tests/data/non_python_notebook.ipynb
new file mode 100644
index 00000000000..da5cdd8e185
--- /dev/null
+++ b/tests/data/non_python_notebook.ipynb
@@ -0,0 +1 @@
+{"metadata":{"kernelspec":{"name":"ir","display_name":"R","language":"R"},"language_info":{"name":"R","codemirror_mode":"r","pygments_lexer":"r","mimetype":"text/x-r-source","file_extension":".r","version":"4.0.5"}},"nbformat_minor":4,"nbformat":4,"cells":[{"cell_type":"code","source":"library(tidyverse) ","metadata":{"_uuid":"051d70d956493feee0c6d64651c6a088724dca2a","_execution_state":"idle"},"execution_count":null,"outputs":[]}]}
\ No newline at end of file
diff --git a/tests/data/notebook_empty_metadata.ipynb b/tests/data/notebook_empty_metadata.ipynb
new file mode 100644
index 00000000000..7dc1f805cd6
--- /dev/null
+++ b/tests/data/notebook_empty_metadata.ipynb
@@ -0,0 +1,27 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "%%time\n",
+    "\n",
+    "print('foo')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {},
+ "nbformat": 4,
+ "nbformat_minor": 4
+}
diff --git a/tests/data/notebook_no_trailing_newline.ipynb b/tests/data/notebook_no_trailing_newline.ipynb
new file mode 100644
index 00000000000..79f95bea2f6
--- /dev/null
+++ b/tests/data/notebook_no_trailing_newline.ipynb
@@ -0,0 +1,39 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "%%time\n",
+    "\n",
+    "print('foo')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "interpreter": {
+   "hash": "e758f3098b5b55f4d87fe30bbdc1367f20f246b483f96267ee70e6c40cb185d8"
+  },
+  "kernelspec": {
+   "display_name": "Python 3.8.10 64-bit ('black': venv)",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": ""
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}
\ No newline at end of file
diff --git a/tests/data/notebook_trailing_newline.ipynb b/tests/data/notebook_trailing_newline.ipynb
new file mode 100644
index 00000000000..4f82869312d
--- /dev/null
+++ b/tests/data/notebook_trailing_newline.ipynb
@@ -0,0 +1,39 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "%%time\n",
+    "\n",
+    "print('foo')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "interpreter": {
+   "hash": "e758f3098b5b55f4d87fe30bbdc1367f20f246b483f96267ee70e6c40cb185d8"
+  },
+  "kernelspec": {
+   "display_name": "Python 3.8.10 64-bit ('black': venv)",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": ""
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}
diff --git a/tests/data/notebook_which_cant_be_parsed.ipynb b/tests/data/notebook_which_cant_be_parsed.ipynb
new file mode 100644
index 00000000000..257cc5642cb
--- /dev/null
+++ b/tests/data/notebook_which_cant_be_parsed.ipynb
@@ -0,0 +1 @@
+foo
diff --git a/tests/data/notebook_without_changes.ipynb b/tests/data/notebook_without_changes.ipynb
new file mode 100644
index 00000000000..ac6c7e63efa
--- /dev/null
+++ b/tests/data/notebook_without_changes.ipynb
@@ -0,0 +1,46 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "%%time\n",
+    "\n",
+    "print(\"foo\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "This notebook should not be reformatted"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "interpreter": {
+   "hash": "e758f3098b5b55f4d87fe30bbdc1367f20f246b483f96267ee70e6c40cb185d8"
+  },
+  "kernelspec": {
+   "display_name": "Python 3.8.10 64-bit ('black': venv)",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": ""
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}
\ No newline at end of file
diff --git a/tests/test_black.py b/tests/test_black.py
index 998ecfcbdeb..942446ec343 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -1379,6 +1379,8 @@ def test_include_exclude(self) -> None:
                 None,
                 report,
                 gitignore,
+                verbose=False,
+                quiet=False,
             )
         )
         self.assertEqual(sorted(expected), sorted(sources))
@@ -1690,6 +1692,8 @@ def test_gitignore_exclude(self) -> None:
                 None,
                 report,
                 gitignore,
+                verbose=False,
+                quiet=False,
             )
         )
         self.assertEqual(sorted(expected), sorted(sources))
@@ -1717,6 +1721,8 @@ def test_nested_gitignore(self) -> None:
                 None,
                 report,
                 root_gitignore,
+                verbose=False,
+                quiet=False,
             )
         )
         self.assertEqual(sorted(expected), sorted(sources))
@@ -1751,6 +1757,8 @@ def test_empty_include(self) -> None:
                 None,
                 report,
                 gitignore,
+                verbose=False,
+                quiet=False,
             )
         )
         self.assertEqual(sorted(expected), sorted(sources))
@@ -1775,6 +1783,8 @@ def test_extend_exclude(self) -> None:
                 None,
                 report,
                 gitignore,
+                verbose=False,
+                quiet=False,
             )
         )
         self.assertEqual(sorted(expected), sorted(sources))
@@ -1847,6 +1857,8 @@ def test_symlink_out_of_root_directory(self) -> None:
                     None,
                     report,
                     gitignore,
+                    verbose=False,
+                    quiet=False,
                 )
             )
         except ValueError as ve:
@@ -1868,6 +1880,8 @@ def test_symlink_out_of_root_directory(self) -> None:
                     None,
                     report,
                     gitignore,
+                    verbose=False,
+                    quiet=False,
                 )
             )
         path.iterdir.assert_called()
diff --git a/tests/test_ipynb.py b/tests/test_ipynb.py
new file mode 100644
index 00000000000..038155e9270
--- /dev/null
+++ b/tests/test_ipynb.py
@@ -0,0 +1,455 @@
+import pathlib
+from click.testing import CliRunner
+from black.handle_ipynb_magics import jupyter_dependencies_are_installed
+from black import (
+    main,
+    NothingChanged,
+    format_cell,
+    format_file_contents,
+    format_file_in_place,
+)
+import os
+import pytest
+from black import Mode
+from _pytest.monkeypatch import MonkeyPatch
+from py.path import local
+
+pytestmark = pytest.mark.jupyter
+pytest.importorskip("IPython", reason="IPython is an optional dependency")
+pytest.importorskip("tokenize_rt", reason="tokenize-rt is an optional dependency")
+
+JUPYTER_MODE = Mode(is_ipynb=True)
+
+runner = CliRunner()
+
+
+def test_noop() -> None:
+    src = 'foo = "a"'
+    with pytest.raises(NothingChanged):
+        format_cell(src, fast=True, mode=JUPYTER_MODE)
+
+
+@pytest.mark.parametrize("fast", [True, False])
+def test_trailing_semicolon(fast: bool) -> None:
+    src = 'foo = "a" ;'
+    result = format_cell(src, fast=fast, mode=JUPYTER_MODE)
+    expected = 'foo = "a";'
+    assert result == expected
+
+
+def test_trailing_semicolon_with_comment() -> None:
+    src = 'foo = "a" ;  # bar'
+    result = format_cell(src, fast=True, mode=JUPYTER_MODE)
+    expected = 'foo = "a";  # bar'
+    assert result == expected
+
+
+def test_trailing_semicolon_with_comment_on_next_line() -> None:
+    src = "import black;\n\n# this is a comment"
+    with pytest.raises(NothingChanged):
+        format_cell(src, fast=True, mode=JUPYTER_MODE)
+
+
+def test_trailing_semicolon_indented() -> None:
+    src = "with foo:\n    plot_bar();"
+    with pytest.raises(NothingChanged):
+        format_cell(src, fast=True, mode=JUPYTER_MODE)
+
+
+def test_trailing_semicolon_noop() -> None:
+    src = 'foo = "a";'
+    with pytest.raises(NothingChanged):
+        format_cell(src, fast=True, mode=JUPYTER_MODE)
+
+
+def test_cell_magic() -> None:
+    src = "%%time\nfoo =bar"
+    result = format_cell(src, fast=True, mode=JUPYTER_MODE)
+    expected = "%%time\nfoo = bar"
+    assert result == expected
+
+
+def test_cell_magic_noop() -> None:
+    src = "%%time\n2 + 2"
+    with pytest.raises(NothingChanged):
+        format_cell(src, fast=True, mode=JUPYTER_MODE)
+
+
+@pytest.mark.parametrize(
+    "src, expected",
+    (
+        pytest.param("ls =!ls", "ls = !ls", id="System assignment"),
+        pytest.param("!ls\n'foo'", '!ls\n"foo"', id="System call"),
+        pytest.param("!!ls\n'foo'", '!!ls\n"foo"', id="Other system call"),
+        pytest.param("?str\n'foo'", '?str\n"foo"', id="Help"),
+        pytest.param("??str\n'foo'", '??str\n"foo"', id="Other help"),
+        pytest.param(
+            "%matplotlib inline\n'foo'",
+            '%matplotlib inline\n"foo"',
+            id="Line magic with argument",
+        ),
+        pytest.param("%time\n'foo'", '%time\n"foo"', id="Line magic without argument"),
+    ),
+)
+def test_magic(src: str, expected: str) -> None:
+    result = format_cell(src, fast=True, mode=JUPYTER_MODE)
+    assert result == expected
+
+
+@pytest.mark.parametrize(
+    "src",
+    (
+        "%%bash\n2+2",
+        "%%html --isolated\n2+2",
+    ),
+)
+def test_non_python_magics(src: str) -> None:
+    with pytest.raises(NothingChanged):
+        format_cell(src, fast=True, mode=JUPYTER_MODE)
+
+
+def test_set_input() -> None:
+    src = "a = b??"
+    with pytest.raises(NothingChanged):
+        format_cell(src, fast=True, mode=JUPYTER_MODE)
+
+
+def test_input_already_contains_transformed_magic() -> None:
+    src = '%time foo()\nget_ipython().run_cell_magic("time", "", "foo()\\n")'
+    with pytest.raises(NothingChanged):
+        format_cell(src, fast=True, mode=JUPYTER_MODE)
+
+
+def test_magic_noop() -> None:
+    src = "ls = !ls"
+    with pytest.raises(NothingChanged):
+        format_cell(src, fast=True, mode=JUPYTER_MODE)
+
+
+def test_cell_magic_with_magic() -> None:
+    src = "%%t -n1\nls =!ls"
+    result = format_cell(src, fast=True, mode=JUPYTER_MODE)
+    expected = "%%t -n1\nls = !ls"
+    assert result == expected
+
+
+def test_cell_magic_nested() -> None:
+    src = "%%time\n%%time\n2+2"
+    result = format_cell(src, fast=True, mode=JUPYTER_MODE)
+    expected = "%%time\n%%time\n2 + 2"
+    assert result == expected
+
+
+def test_cell_magic_with_magic_noop() -> None:
+    src = "%%t -n1\nls = !ls"
+    with pytest.raises(NothingChanged):
+        format_cell(src, fast=True, mode=JUPYTER_MODE)
+
+
+def test_automagic() -> None:
+    src = "pip install black"
+    with pytest.raises(NothingChanged):
+        format_cell(src, fast=True, mode=JUPYTER_MODE)
+
+
+def test_multiline_magic() -> None:
+    src = "%time 1 + \\\n2"
+    with pytest.raises(NothingChanged):
+        format_cell(src, fast=True, mode=JUPYTER_MODE)
+
+
+def test_multiline_no_magic() -> None:
+    src = "1 + \\\n2"
+    result = format_cell(src, fast=True, mode=JUPYTER_MODE)
+    expected = "1 + 2"
+    assert result == expected
+
+
+def test_cell_magic_with_invalid_body() -> None:
+    src = "%%time\nif True"
+    with pytest.raises(NothingChanged):
+        format_cell(src, fast=True, mode=JUPYTER_MODE)
+
+
+def test_empty_cell() -> None:
+    src = ""
+    with pytest.raises(NothingChanged):
+        format_cell(src, fast=True, mode=JUPYTER_MODE)
+
+
+def test_entire_notebook_empty_metadata() -> None:
+    with open(
+        os.path.join("tests", "data", "notebook_empty_metadata.ipynb"), "rb"
+    ) as fd:
+        content_bytes = fd.read()
+    content = content_bytes.decode()
+    result = format_file_contents(content, fast=True, mode=JUPYTER_MODE)
+    expected = (
+        "{\n"
+        ' "cells": [\n'
+        "  {\n"
+        '   "cell_type": "code",\n'
+        '   "execution_count": null,\n'
+        '   "metadata": {\n'
+        '    "tags": []\n'
+        "   },\n"
+        '   "outputs": [],\n'
+        '   "source": [\n'
+        '    "%%time\\n",\n'
+        '    "\\n",\n'
+        '    "print(\\"foo\\")"\n'
+        "   ]\n"
+        "  },\n"
+        "  {\n"
+        '   "cell_type": "code",\n'
+        '   "execution_count": null,\n'
+        '   "metadata": {},\n'
+        '   "outputs": [],\n'
+        '   "source": []\n'
+        "  }\n"
+        " ],\n"
+        ' "metadata": {},\n'
+        ' "nbformat": 4,\n'
+        ' "nbformat_minor": 4\n'
+        "}\n"
+    )
+    assert result == expected
+
+
+def test_entire_notebook_trailing_newline() -> None:
+    with open(
+        os.path.join("tests", "data", "notebook_trailing_newline.ipynb"), "rb"
+    ) as fd:
+        content_bytes = fd.read()
+    content = content_bytes.decode()
+    result = format_file_contents(content, fast=True, mode=JUPYTER_MODE)
+    expected = (
+        "{\n"
+        ' "cells": [\n'
+        "  {\n"
+        '   "cell_type": "code",\n'
+        '   "execution_count": null,\n'
+        '   "metadata": {\n'
+        '    "tags": []\n'
+        "   },\n"
+        '   "outputs": [],\n'
+        '   "source": [\n'
+        '    "%%time\\n",\n'
+        '    "\\n",\n'
+        '    "print(\\"foo\\")"\n'
+        "   ]\n"
+        "  },\n"
+        "  {\n"
+        '   "cell_type": "code",\n'
+        '   "execution_count": null,\n'
+        '   "metadata": {},\n'
+        '   "outputs": [],\n'
+        '   "source": []\n'
+        "  }\n"
+        " ],\n"
+        ' "metadata": {\n'
+        '  "interpreter": {\n'
+        '   "hash": "e758f3098b5b55f4d87fe30bbdc1367f20f246b483f96267ee70e6c40cb185d8"\n'  # noqa:B950
+        "  },\n"
+        '  "kernelspec": {\n'
+        '   "display_name": "Python 3.8.10 64-bit (\'black\': venv)",\n'
+        '   "name": "python3"\n'
+        "  },\n"
+        '  "language_info": {\n'
+        '   "name": "python",\n'
+        '   "version": ""\n'
+        "  }\n"
+        " },\n"
+        ' "nbformat": 4,\n'
+        ' "nbformat_minor": 4\n'
+        "}\n"
+    )
+    assert result == expected
+
+
+def test_entire_notebook_no_trailing_newline() -> None:
+    with open(
+        os.path.join("tests", "data", "notebook_no_trailing_newline.ipynb"), "rb"
+    ) as fd:
+        content_bytes = fd.read()
+    content = content_bytes.decode()
+    result = format_file_contents(content, fast=True, mode=JUPYTER_MODE)
+    expected = (
+        "{\n"
+        ' "cells": [\n'
+        "  {\n"
+        '   "cell_type": "code",\n'
+        '   "execution_count": null,\n'
+        '   "metadata": {\n'
+        '    "tags": []\n'
+        "   },\n"
+        '   "outputs": [],\n'
+        '   "source": [\n'
+        '    "%%time\\n",\n'
+        '    "\\n",\n'
+        '    "print(\\"foo\\")"\n'
+        "   ]\n"
+        "  },\n"
+        "  {\n"
+        '   "cell_type": "code",\n'
+        '   "execution_count": null,\n'
+        '   "metadata": {},\n'
+        '   "outputs": [],\n'
+        '   "source": []\n'
+        "  }\n"
+        " ],\n"
+        ' "metadata": {\n'
+        '  "interpreter": {\n'
+        '   "hash": "e758f3098b5b55f4d87fe30bbdc1367f20f246b483f96267ee70e6c40cb185d8"\n'  # noqa: B950
+        "  },\n"
+        '  "kernelspec": {\n'
+        '   "display_name": "Python 3.8.10 64-bit (\'black\': venv)",\n'
+        '   "name": "python3"\n'
+        "  },\n"
+        '  "language_info": {\n'
+        '   "name": "python",\n'
+        '   "version": ""\n'
+        "  }\n"
+        " },\n"
+        ' "nbformat": 4,\n'
+        ' "nbformat_minor": 4\n'
+        "}"
+    )
+    assert result == expected
+
+
+def test_entire_notebook_without_changes() -> None:
+    with open(
+        os.path.join("tests", "data", "notebook_without_changes.ipynb"), "rb"
+    ) as fd:
+        content_bytes = fd.read()
+    content = content_bytes.decode()
+    with pytest.raises(NothingChanged):
+        format_file_contents(content, fast=True, mode=JUPYTER_MODE)
+
+
+def test_non_python_notebook() -> None:
+    with open(os.path.join("tests", "data", "non_python_notebook.ipynb"), "rb") as fd:
+        content_bytes = fd.read()
+    content = content_bytes.decode()
+    with pytest.raises(NothingChanged):
+        format_file_contents(content, fast=True, mode=JUPYTER_MODE)
+
+
+def test_empty_string() -> None:
+    with pytest.raises(NothingChanged):
+        format_file_contents("", fast=True, mode=JUPYTER_MODE)
+
+
+def test_unparseable_notebook() -> None:
+    msg = (
+        r"File 'tests[/\\]data[/\\]notebook_which_cant_be_parsed\.ipynb' "
+        r"cannot be parsed as valid Jupyter notebook\."
+    )
+    with pytest.raises(ValueError, match=msg):
+        format_file_in_place(
+            pathlib.Path("tests") / "data/notebook_which_cant_be_parsed.ipynb",
+            fast=True,
+            mode=JUPYTER_MODE,
+        )
+
+
+def test_ipynb_diff_with_change() -> None:
+    result = runner.invoke(
+        main,
+        [
+            os.path.join("tests", "data", "notebook_trailing_newline.ipynb"),
+            "--diff",
+        ],
+    )
+    expected = "@@ -1,3 +1,3 @@\n %%time\n \n-print('foo')\n" '+print("foo")\n'
+    assert expected in result.output
+
+
+def test_ipynb_diff_with_no_change() -> None:
+    result = runner.invoke(
+        main,
+        [
+            os.path.join("tests", "data", "notebook_without_changes.ipynb"),
+            "--diff",
+        ],
+    )
+    expected = "1 file would be left unchanged."
+    assert expected in result.output
+
+
+def test_cache_isnt_written_if_no_jupyter_deps_single(
+    monkeypatch: MonkeyPatch, tmpdir: local
+) -> None:
+    # Check that the cache isn't written to if Jupyter dependencies aren't installed.
+    jupyter_dependencies_are_installed.cache_clear()
+    nb = os.path.join("tests", "data", "notebook_trailing_newline.ipynb")
+    tmp_nb = tmpdir / "notebook.ipynb"
+    with open(nb) as src, open(tmp_nb, "w") as dst:
+        dst.write(src.read())
+    monkeypatch.setattr(
+        "black.jupyter_dependencies_are_installed", lambda verbose, quiet: False
+    )
+    result = runner.invoke(main, [str(tmpdir / "notebook.ipynb")])
+    assert "No Python files are present to be formatted. Nothing to do" in result.output
+    jupyter_dependencies_are_installed.cache_clear()
+    monkeypatch.setattr(
+        "black.jupyter_dependencies_are_installed", lambda verbose, quiet: True
+    )
+    result = runner.invoke(main, [str(tmpdir / "notebook.ipynb")])
+    assert "reformatted" in result.output
+
+
+def test_cache_isnt_written_if_no_jupyter_deps_dir(
+    monkeypatch: MonkeyPatch, tmpdir: local
+) -> None:
+    # Check that the cache isn't written to if Jupyter dependencies aren't installed.
+    jupyter_dependencies_are_installed.cache_clear()
+    nb = os.path.join("tests", "data", "notebook_trailing_newline.ipynb")
+    tmp_nb = tmpdir / "notebook.ipynb"
+    with open(nb) as src, open(tmp_nb, "w") as dst:
+        dst.write(src.read())
+    monkeypatch.setattr(
+        "black.files.jupyter_dependencies_are_installed", lambda verbose, quiet: False
+    )
+    result = runner.invoke(main, [str(tmpdir)])
+    assert "No Python files are present to be formatted. Nothing to do" in result.output
+    jupyter_dependencies_are_installed.cache_clear()
+    monkeypatch.setattr(
+        "black.files.jupyter_dependencies_are_installed", lambda verbose, quiet: True
+    )
+    result = runner.invoke(main, [str(tmpdir)])
+    assert "reformatted" in result.output
+
+
+def test_ipynb_flag(tmpdir: local) -> None:
+    nb = os.path.join("tests", "data", "notebook_trailing_newline.ipynb")
+    tmp_nb = tmpdir / "notebook.a_file_extension_which_is_definitely_not_ipynb"
+    with open(nb) as src, open(tmp_nb, "w") as dst:
+        dst.write(src.read())
+    result = runner.invoke(
+        main,
+        [
+            str(tmp_nb),
+            "--diff",
+            "--ipynb",
+        ],
+    )
+    expected = "@@ -1,3 +1,3 @@\n %%time\n \n-print('foo')\n" '+print("foo")\n'
+    assert expected in result.output
+
+
+def test_ipynb_and_pyi_flags() -> None:
+    nb = os.path.join("tests", "data", "notebook_trailing_newline.ipynb")
+    result = runner.invoke(
+        main,
+        [
+            nb,
+            "--pyi",
+            "--ipynb",
+            "--diff",
+        ],
+    )
+    assert isinstance(result.exception, SystemExit)
+    expected = "Cannot pass both `pyi` and `ipynb` flags!\n"
+    assert result.output == expected
diff --git a/tests/test_no_ipynb.py b/tests/test_no_ipynb.py
new file mode 100644
index 00000000000..bcda2d5369f
--- /dev/null
+++ b/tests/test_no_ipynb.py
@@ -0,0 +1,37 @@
+import pytest
+import os
+
+from tests.util import THIS_DIR
+from black import main, jupyter_dependencies_are_installed
+from click.testing import CliRunner
+from _pytest.tmpdir import tmpdir
+
+pytestmark = pytest.mark.no_jupyter
+
+runner = CliRunner()
+
+
+def test_ipynb_diff_with_no_change_single() -> None:
+    jupyter_dependencies_are_installed.cache_clear()
+    path = THIS_DIR / "data/notebook_trailing_newline.ipynb"
+    result = runner.invoke(main, [str(path)])
+    expected_output = (
+        "Skipping .ipynb files as Jupyter dependencies are not installed.\n"
+        "You can fix this by running ``pip install black[jupyter]``\n"
+    )
+    assert expected_output in result.output
+
+
+def test_ipynb_diff_with_no_change_dir(tmpdir: tmpdir) -> None:
+    jupyter_dependencies_are_installed.cache_clear()
+    runner = CliRunner()
+    nb = os.path.join("tests", "data", "notebook_trailing_newline.ipynb")
+    tmp_nb = tmpdir / "notebook.ipynb"
+    with open(nb) as src, open(tmp_nb, "w") as dst:
+        dst.write(src.read())
+    result = runner.invoke(main, [str(tmpdir)])
+    expected_output = (
+        "Skipping .ipynb files as Jupyter dependencies are not installed.\n"
+        "You can fix this by running ``pip install black[jupyter]``\n"
+    )
+    assert expected_output in result.output
diff --git a/tox.ini b/tox.ini
index 3767f98a73b..57f41acb3d1 100644
--- a/tox.ini
+++ b/tox.ini
@@ -16,10 +16,17 @@ commands =
     pip install -e .[d]
     coverage erase
     pytest tests --run-optional no_python2 \
+        --run-optional no_jupyter \
         !ci: --numprocesses auto \
         --cov {posargs}
     pip install -e .[d,python2]
     pytest tests --run-optional python2 \
+        --run-optional no_jupyter \
+        !ci: --numprocesses auto \
+        --cov --cov-append {posargs}
+    pip install -e .[jupyter]
+    pytest tests --run-optional jupyter \
+        -m jupyter \
         !ci: --numprocesses auto \
         --cov --cov-append {posargs}
     coverage report

From 355a6b34b3a61b6729e469115e1393d9779963c5 Mon Sep 17 00:00:00 2001
From: aru <genericusername414@gmail.com>
Date: Wed, 11 Aug 2021 21:50:46 -0400
Subject: [PATCH 0276/1034] fix: remove unneccessary escape character (#2423)

---
 .github/ISSUE_TEMPLATE/config.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
index 67c3ce825ea..3f6641c91a0 100644
--- a/.github/ISSUE_TEMPLATE/config.yml
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -8,5 +8,5 @@ contact_links:
     url: https://discord.gg/RtVdv86PrH
     about: |
       User support, questions, and other lightweight requests can be
-      handled via the \#black-formatter text channel we have on Python
+      handled via the #black-formatter text channel we have on Python
       Discord.

From e465acf6f8dc82152b0e9187ed6e934b97c678c8 Mon Sep 17 00:00:00 2001
From: Tom Fryers <61272761+TomFryers@users.noreply.github.com>
Date: Thu, 12 Aug 2021 23:45:33 +0100
Subject: [PATCH 0277/1034] Update language server links (#2425)

python-language-server is no longer maintained.
---
 docs/integrations/editors.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/integrations/editors.md b/docs/integrations/editors.md
index dd09b4df6d1..b1ca84e42fc 100644
--- a/docs/integrations/editors.md
+++ b/docs/integrations/editors.md
@@ -295,12 +295,12 @@ Use [sublack plugin](https://github.com/jgirardet/sublack).
 
 Use [blackcellmagic](https://github.com/csurfer/blackcellmagic).
 
-## Python Language Server
+## Python LSP Server
 
 If your editor supports the [Language Server Protocol](https://langserver.org/) (Atom,
 Sublime Text, Visual Studio Code and many more), you can use the
-[Python Language Server](https://github.com/palantir/python-language-server) with the
-[pyls-black](https://github.com/rupert/pyls-black) plugin.
+[Python LSP Server](https://github.com/python-lsp/python-lsp-server) with the
+[python-lsp-black](https://github.com/python-lsp/python-lsp-black) plugin.
 
 ## Atom/Nuclide
 

From b92ec348439edb8641204a102849bfab51f4dda0 Mon Sep 17 00:00:00 2001
From: Marco Edward Gorelli <marcogorelli@protonmail.com>
Date: Mon, 16 Aug 2021 03:54:42 +0100
Subject: [PATCH 0278/1034] Add jupyter deps to Pipfile.lock (#2419)

---
 Pipfile      |   2 +-
 Pipfile.lock | 243 ++++++++++++++++++++++++++++-----------------------
 2 files changed, 134 insertions(+), 111 deletions(-)

diff --git a/Pipfile b/Pipfile
index 433a3b392f7..c9238d3f69e 100644
--- a/Pipfile
+++ b/Pipfile
@@ -21,7 +21,7 @@ setuptools = ">=39.2.0"
 setuptools-scm = "*"
 twine = ">=1.11.0"
 wheel = ">=0.31.1"
-black = {editable = true, extras = ["d"], path = "."}
+black = {editable = true, extras = ["d", "jupyter"], path = "."}
 
 [packages]
 aiohttp = ">=3.6.0"
diff --git a/Pipfile.lock b/Pipfile.lock
index 3047a487657..0c9a42348c3 100644
--- a/Pipfile.lock
+++ b/Pipfile.lock
@@ -1,7 +1,7 @@
 {
     "_meta": {
         "hash": {
-            "sha256": "a02de7783dc48a2466cf52fc639b76f39823ccc87cee228521905f5fdb830b1f"
+            "sha256": "eca7ef453dc0d16ab3910fc8035a3b57e2c1512dea8d9a95958eeecfe71935c1"
         },
         "pipfile-spec": 6,
         "requires": {},
@@ -287,9 +287,9 @@
                 "sha256:779383f6086d90c99ae41cf0ff39aac8a7937a9283ce0a414e5dd782f4c94a84"
             ],
             "index": "pypi",
-            "python_version <": "3.8",
+            "python_version <": "3.10",
             "version": "==3.10.0.0",
-            "version >=": "3.7.4"
+            "version >=": "3.10.0.0"
         },
         "yarl": {
             "hashes": [
@@ -394,6 +394,14 @@
             ],
             "version": "==0.7.12"
         },
+        "appnope": {
+            "hashes": [
+                "sha256:93aa393e9d6c54c5cd570ccadd8edad61ea0c4b9ea7a01409020c9aa019eb442",
+                "sha256:dd83cd4b5b460958838f6eb3000c660b1f9caf2a5b1de4264e941512f603258a"
+            ],
+            "markers": "sys_platform == 'darwin'",
+            "version": "==0.1.2"
+        },
         "async-timeout": {
             "hashes": [
                 "sha256:0c3c816a028d47f659d6ff5c745cb2acf1f966da1fe5c19c77a70282b25f4c5f",
@@ -418,6 +426,13 @@
             "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==2.9.1"
         },
+        "backcall": {
+            "hashes": [
+                "sha256:5cbdbf27be5e7cfadb448baf0aa95508f91f2bbc6c6437cd9cd06e2a4c215e1e",
+                "sha256:fbbce6a29f263178a1f7915c1940bde0ec2b2a967566fe1c65c1dfb7422bd255"
+            ],
+            "version": "==0.2.0"
+        },
         "backports.entry-points-selectable": {
             "hashes": [
                 "sha256:988468260ec1c196dab6ae1149260e2f5472c9110334e5d51adcb77867361f6a",
@@ -448,56 +463,6 @@
             ],
             "version": "==2021.5.30"
         },
-        "cffi": {
-            "hashes": [
-                "sha256:06c54a68935738d206570b20da5ef2b6b6d92b38ef3ec45c5422c0ebaf338d4d",
-                "sha256:0c0591bee64e438883b0c92a7bed78f6290d40bf02e54c5bf0978eaf36061771",
-                "sha256:19ca0dbdeda3b2615421d54bef8985f72af6e0c47082a8d26122adac81a95872",
-                "sha256:22b9c3c320171c108e903d61a3723b51e37aaa8c81255b5e7ce102775bd01e2c",
-                "sha256:26bb2549b72708c833f5abe62b756176022a7b9a7f689b571e74c8478ead51dc",
-                "sha256:33791e8a2dc2953f28b8d8d300dde42dd929ac28f974c4b4c6272cb2955cb762",
-                "sha256:3c8d896becff2fa653dc4438b54a5a25a971d1f4110b32bd3068db3722c80202",
-                "sha256:4373612d59c404baeb7cbd788a18b2b2a8331abcc84c3ba40051fcd18b17a4d5",
-                "sha256:487d63e1454627c8e47dd230025780e91869cfba4c753a74fda196a1f6ad6548",
-                "sha256:48916e459c54c4a70e52745639f1db524542140433599e13911b2f329834276a",
-                "sha256:4922cd707b25e623b902c86188aca466d3620892db76c0bdd7b99a3d5e61d35f",
-                "sha256:55af55e32ae468e9946f741a5d51f9896da6b9bf0bbdd326843fec05c730eb20",
-                "sha256:57e555a9feb4a8460415f1aac331a2dc833b1115284f7ded7278b54afc5bd218",
-                "sha256:5d4b68e216fc65e9fe4f524c177b54964af043dde734807586cf5435af84045c",
-                "sha256:64fda793737bc4037521d4899be780534b9aea552eb673b9833b01f945904c2e",
-                "sha256:6d6169cb3c6c2ad50db5b868db6491a790300ade1ed5d1da29289d73bbe40b56",
-                "sha256:7bcac9a2b4fdbed2c16fa5681356d7121ecabf041f18d97ed5b8e0dd38a80224",
-                "sha256:80b06212075346b5546b0417b9f2bf467fea3bfe7352f781ffc05a8ab24ba14a",
-                "sha256:818014c754cd3dba7229c0f5884396264d51ffb87ec86e927ef0be140bfdb0d2",
-                "sha256:8eb687582ed7cd8c4bdbff3df6c0da443eb89c3c72e6e5dcdd9c81729712791a",
-                "sha256:99f27fefe34c37ba9875f224a8f36e31d744d8083e00f520f133cab79ad5e819",
-                "sha256:9f3e33c28cd39d1b655ed1ba7247133b6f7fc16fa16887b120c0c670e35ce346",
-                "sha256:a8661b2ce9694ca01c529bfa204dbb144b275a31685a075ce123f12331be790b",
-                "sha256:a9da7010cec5a12193d1af9872a00888f396aba3dc79186604a09ea3ee7c029e",
-                "sha256:aedb15f0a5a5949ecb129a82b72b19df97bbbca024081ed2ef88bd5c0a610534",
-                "sha256:b315d709717a99f4b27b59b021e6207c64620790ca3e0bde636a6c7f14618abb",
-                "sha256:ba6f2b3f452e150945d58f4badd92310449876c4c954836cfb1803bdd7b422f0",
-                "sha256:c33d18eb6e6bc36f09d793c0dc58b0211fccc6ae5149b808da4a62660678b156",
-                "sha256:c9a875ce9d7fe32887784274dd533c57909b7b1dcadcc128a2ac21331a9765dd",
-                "sha256:c9e005e9bd57bc987764c32a1bee4364c44fdc11a3cc20a40b93b444984f2b87",
-                "sha256:d2ad4d668a5c0645d281dcd17aff2be3212bc109b33814bbb15c4939f44181cc",
-                "sha256:d950695ae4381ecd856bcaf2b1e866720e4ab9a1498cba61c602e56630ca7195",
-                "sha256:e22dcb48709fc51a7b58a927391b23ab37eb3737a98ac4338e2448bef8559b33",
-                "sha256:e8c6a99be100371dbb046880e7a282152aa5d6127ae01783e37662ef73850d8f",
-                "sha256:e9dc245e3ac69c92ee4c167fbdd7428ec1956d4e754223124991ef29eb57a09d",
-                "sha256:eb687a11f0a7a1839719edd80f41e459cc5366857ecbed383ff376c4e3cc6afd",
-                "sha256:eb9e2a346c5238a30a746893f23a9535e700f8192a68c07c0258e7ece6ff3728",
-                "sha256:ed38b924ce794e505647f7c331b22a693bee1538fdf46b0222c4717b42f744e7",
-                "sha256:f0010c6f9d1a4011e429109fda55a225921e3206e7f62a0c22a35344bfd13cca",
-                "sha256:f0c5d1acbfca6ebdd6b1e3eded8d261affb6ddcf2186205518f1428b8569bb99",
-                "sha256:f10afb1004f102c7868ebfe91c28f4a712227fe4cb24974350ace1f90e1febbf",
-                "sha256:f174135f5609428cc6e1b9090f9268f5c8935fddb1b25ccb8255a2d50de6789e",
-                "sha256:f3ebe6e73c319340830a9b2825d32eb6d8475c1dac020b4f0aa774ee3b898d1c",
-                "sha256:f627688813d0a4140153ff532537fbe4afea5a3dffce1f9deb7f91f848a832b5",
-                "sha256:fd4305f86f53dfd8cd3522269ed7fc34856a8ee3709a5e28b2836b2db9d4cd69"
-            ],
-            "version": "==1.14.6"
-        },
         "cfgv": {
             "hashes": [
                 "sha256:9e600479b3b99e8af981ecdfc80a0296104ee610cab48a5ae4ffd0b668650eb1",
@@ -596,23 +561,13 @@
             "index": "pypi",
             "version": "==5.5"
         },
-        "cryptography": {
-            "hashes": [
-                "sha256:0f1212a66329c80d68aeeb39b8a16d54ef57071bf22ff4e521657b27372e327d",
-                "sha256:1e056c28420c072c5e3cb36e2b23ee55e260cb04eee08f702e0edfec3fb51959",
-                "sha256:240f5c21aef0b73f40bb9f78d2caff73186700bf1bc6b94285699aff98cc16c6",
-                "sha256:26965837447f9c82f1855e0bc8bc4fb910240b6e0d16a664bb722df3b5b06873",
-                "sha256:37340614f8a5d2fb9aeea67fd159bfe4f5f4ed535b1090ce8ec428b2f15a11f2",
-                "sha256:3d10de8116d25649631977cb37da6cbdd2d6fa0e0281d014a5b7d337255ca713",
-                "sha256:3d8427734c781ea5f1b41d6589c293089704d4759e34597dce91014ac125aad1",
-                "sha256:7ec5d3b029f5fa2b179325908b9cd93db28ab7b85bb6c1db56b10e0b54235177",
-                "sha256:8e56e16617872b0957d1c9742a3f94b43533447fd78321514abbe7db216aa250",
-                "sha256:de4e5f7f68220d92b7637fc99847475b59154b7a1b3868fb7385337af54ac9ca",
-                "sha256:eb8cc2afe8b05acbd84a43905832ec78e7b3873fb124ca190f574dca7389a87d",
-                "sha256:ee77aa129f481be46f8d92a1a7db57269a2f23052d5f2433b4621bb457081cc9"
+        "decorator": {
+            "hashes": [
+                "sha256:6e5c199c16f7a9f0e3a61a4a54b3d27e7dad0dbdde92b944426cb20914376323",
+                "sha256:72ecfba4320a893c53f9706bebb2d55c270c1e51a28789361aa93e4a21319ed5"
             ],
-            "markers": "python_version >= '3.6'",
-            "version": "==3.4.7"
+            "markers": "python_version >= '3.5'",
+            "version": "==5.0.9"
         },
         "distlib": {
             "hashes": [
@@ -655,11 +610,11 @@
         },
         "identify": {
             "hashes": [
-                "sha256:242332b3bdd45a8af1752d5d5a3afb12bee26f8e67c4be06e394f82d05ef1a4d",
-                "sha256:a510cbe155f39665625c8a4c4b4f9360cbce539f51f23f47836ab7dd852db541"
+                "sha256:7199679b5be13a6b40e6e19ea473e789b11b4e3b60986499b1f589ffb03c217c",
+                "sha256:7bc6e829392bd017236531963d2d937d66fc27cadc643ac0aba2ce9f26157c79"
             ],
             "markers": "python_full_version >= '3.6.1'",
-            "version": "==2.2.12"
+            "version": "==2.2.13"
         },
         "idna": {
             "hashes": [
@@ -685,13 +640,28 @@
             "markers": "python_version >= '3.6'",
             "version": "==4.6.3"
         },
-        "jeepney": {
+        "ipython": {
             "hashes": [
-                "sha256:1b5a0ea5c0e7b166b2f5895b91a08c14de8915afda4407fb5022a195224958ac",
-                "sha256:fa9e232dfa0c498bd0b8a3a73b8d8a31978304dcef0515adc859d4e096f96f4f"
+                "sha256:0cff04bb042800129348701f7bd68a430a844e8fb193979c08f6c99f28bb735e",
+                "sha256:892743b65c21ed72b806a3a602cca408520b3200b89d1924f4b3d2cdb3692362"
             ],
-            "markers": "sys_platform == 'linux'",
-            "version": "==0.7.1"
+            "markers": "python_version >= '3.7'",
+            "version": "==7.26.0"
+        },
+        "ipython-genutils": {
+            "hashes": [
+                "sha256:72dd37233799e619666c9f639a9da83c34013a73e8bbc79a7a6348d93c61fab8",
+                "sha256:eb2e116e75ecef9d4d228fdc66af54269afa26ab4463042e33785b887c628ba8"
+            ],
+            "version": "==0.2.0"
+        },
+        "jedi": {
+            "hashes": [
+                "sha256:18456d83f65f400ab0c2d3319e48520420ef43b23a086fdc05dff34132f0fb93",
+                "sha256:92550a404bad8afed881a137ec9a461fed49eca661414be45059329614ed0707"
+            ],
+            "markers": "python_version >= '3.6'",
+            "version": "==0.18.0"
         },
         "jinja2": {
             "hashes": [
@@ -757,6 +727,14 @@
             "markers": "python_version >= '3.6'",
             "version": "==2.0.1"
         },
+        "matplotlib-inline": {
+            "hashes": [
+                "sha256:5cf1176f554abb4fa98cb362aa2b55c500147e4bdbb07e3fda359143e1da0811",
+                "sha256:f41d5ff73c9f5385775d5c0bc13b424535c8402fe70ea8210f93e11f3683993e"
+            ],
+            "markers": "python_version >= '3.5'",
+            "version": "==0.1.2"
+        },
         "mccabe": {
             "hashes": [
                 "sha256:ab8a6258860da4b6677da4bd2fe5dc2c659cff31b3ee4f7f5d64e79735b80d42",
@@ -875,6 +853,14 @@
             "markers": "python_version >= '3.6'",
             "version": "==21.0"
         },
+        "parso": {
+            "hashes": [
+                "sha256:12b83492c6239ce32ff5eed6d3639d6a536170723c6f3f1506869f1ace413398",
+                "sha256:a8c4922db71e4fdb90e0d0bc6e50f9b273d3397925e5e60a717e719201778d22"
+            ],
+            "markers": "python_version >= '3.6'",
+            "version": "==0.8.2"
+        },
         "pathspec": {
             "hashes": [
                 "sha256:7d15c4ddb0b5c802d161efc417ec1a2558ea2653c2e8ad9c19098201dc1c993a",
@@ -883,6 +869,21 @@
             "index": "pypi",
             "version": "==0.9.0"
         },
+        "pexpect": {
+            "hashes": [
+                "sha256:0b48a55dcb3c05f3329815901ea4fc1537514d6ba867a152b581d69ae3710937",
+                "sha256:fc65a43959d153d0114afe13997d439c22823a27cefceb5ff35c2178c6784c0c"
+            ],
+            "markers": "sys_platform != 'win32'",
+            "version": "==4.8.0"
+        },
+        "pickleshare": {
+            "hashes": [
+                "sha256:87683d47965c1da65cdacaf31c8441d12b8044cdec9aca500cd78fc2c683afca",
+                "sha256:9649af414d74d4df115d5d718f82acb59c9d418196b7b4290ed47a12ce62df56"
+            ],
+            "version": "==0.7.5"
+        },
         "pkginfo": {
             "hashes": [
                 "sha256:37ecd857b47e5f55949c41ed061eb51a0bee97a87c969219d144c0e023982779",
@@ -900,11 +901,26 @@
         },
         "pre-commit": {
             "hashes": [
-                "sha256:764972c60693dc668ba8e86eb29654ec3144501310f7198742a767bec385a378",
-                "sha256:b679d0fddd5b9d6d98783ae5f10fd0c4c59954f375b70a58cbe1ce9bcf9809a4"
+                "sha256:2386eeb4cf6633712c7cc9ede83684d53c8cafca6b59f79c738098b51c6d206c",
+                "sha256:ec3045ae62e1aa2eecfb8e86fa3025c2e3698f77394ef8d2011ce0aedd85b2d4"
             ],
             "index": "pypi",
-            "version": "==2.13.0"
+            "version": "==2.14.0"
+        },
+        "prompt-toolkit": {
+            "hashes": [
+                "sha256:08360ee3a3148bdb5163621709ee322ec34fc4375099afa4bbf751e9b7b7fa4f",
+                "sha256:7089d8d2938043508aa9420ec18ce0922885304cddae87fb96eebca942299f88"
+            ],
+            "markers": "python_full_version >= '3.6.1'",
+            "version": "==3.0.19"
+        },
+        "ptyprocess": {
+            "hashes": [
+                "sha256:4b41f3967fce3af57cc7e94b888626c18bf37a083e3651ca8feeb66d492fef35",
+                "sha256:5c5d0a3b48ceee0b48485e0c26037c0acd7d29765ca3fbb5cb3831d347423220"
+            ],
+            "version": "==0.7.0"
         },
         "pycodestyle": {
             "hashes": [
@@ -914,14 +930,6 @@
             "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==2.7.0"
         },
-        "pycparser": {
-            "hashes": [
-                "sha256:2d475327684562c3a96cc71adf7dc8c4f0565175cf86b6d7a404ff4c771f15f0",
-                "sha256:7582ad22678f0fcd81102833f60ef8d0e57288b6b5fb00323d101be910e35705"
-            ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==2.20"
-        },
         "pyflakes": {
             "hashes": [
                 "sha256:7893783d01b8a89811dd72d7dfd4d84ff098e5eed95cfa8905b22bbffe52efc3",
@@ -1057,14 +1065,6 @@
             ],
             "version": "==1.5.0"
         },
-        "secretstorage": {
-            "hashes": [
-                "sha256:422d82c36172d88d6a0ed5afdec956514b189ddbfb72fefab0c8a1cee4eaf71f",
-                "sha256:fd666c51a6bf200643495a04abb261f83229dcb6fd8472ec393df7ffc8b6f195"
-            ],
-            "markers": "sys_platform == 'linux'",
-            "version": "==3.3.1"
-        },
         "setuptools-scm": {
             "hashes": [
                 "sha256:c3bd5f701c8def44a5c0bfe8d407bef3f80342217ef3492b951f3777bd2d915c",
@@ -1160,6 +1160,14 @@
             "markers": "python_version >= '3.5'",
             "version": "==1.1.5"
         },
+        "tokenize-rt": {
+            "hashes": [
+                "sha256:ab339b5ff829eb5e198590477f9c03c84e762b3e455e74c018956e7e326cbc70",
+                "sha256:b37251fa28c21e8cce2e42f7769a35fba2dd2ecafb297208f9a9a8add3ca7793"
+            ],
+            "markers": "python_full_version >= '3.6.1'",
+            "version": "==4.1.0"
+        },
         "toml": {
             "hashes": [
                 "sha256:806143ae5bfb6a3c6e736a764057db0e6a0e05e338b5630894a5f779cabb4f9b",
@@ -1184,6 +1192,14 @@
             "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==4.62.0"
         },
+        "traitlets": {
+            "hashes": [
+                "sha256:178f4ce988f69189f7e523337a3e11d91c786ded9360174a3d9ca83e79bc5396",
+                "sha256:69ff3f9d5351f31a7ad80443c2674b7099df13cc41fc5fa6e2f6d3b0330b0426"
+            ],
+            "markers": "python_version >= '3.7'",
+            "version": "==5.0.5"
+        },
         "twine": {
             "hashes": [
                 "sha256:087328e9bb405e7ce18527a2dca4042a84c7918658f951110b38bc135acab218",
@@ -1194,19 +1210,19 @@
         },
         "types-dataclasses": {
             "hashes": [
-                "sha256:7b5f4099fb21c209f2df3a83c2b64308c29955769d610a457244dc0eebe1cafc",
-                "sha256:c19491cfb981bff9cafd9c113c291a7a54adccc6298ded8ca3de0d7abe211984"
+                "sha256:248075d093d8f7c1541ce515594df7ae40233d1340afde11ce7125368c5209b8",
+                "sha256:fc372bb68b878ac7a68fd04230d923d4a6303a137ecb0b9700b90630bdfcbfc9"
             ],
             "index": "pypi",
-            "version": "==0.1.5"
+            "version": "==0.1.7"
         },
         "types-typed-ast": {
             "hashes": [
-                "sha256:014ab2742015d3eaab86ea061c27809c7e76beeb9e134102f2e2ddb34ab05c62",
-                "sha256:6a47165760321835d160da20a6ac5b9065f23d6dc246162508cad1ef1238afc3"
+                "sha256:b7f561796b4d002c7522b0020f58b18f715bd28a31429d424a78e2e2dbbd6785",
+                "sha256:ffa0471e0ba19c4ea0cba0436d660871b5f5215854ea9ead3cb5b60f525af75a"
             ],
             "index": "pypi",
-            "version": "==1.4.2"
+            "version": "==1.4.4"
         },
         "typing-extensions": {
             "hashes": [
@@ -1215,9 +1231,9 @@
                 "sha256:779383f6086d90c99ae41cf0ff39aac8a7937a9283ce0a414e5dd782f4c94a84"
             ],
             "index": "pypi",
-            "python_version <": "3.8",
+            "python_version <": "3.10",
             "version": "==3.10.0.0",
-            "version >=": "3.7.4"
+            "version >=": "3.10.0.0"
         },
         "urllib3": {
             "hashes": [
@@ -1229,11 +1245,18 @@
         },
         "virtualenv": {
             "hashes": [
-                "sha256:97066a978431ec096d163e72771df5357c5c898ffdd587048f45e0aecc228094",
-                "sha256:fdfdaaf0979ac03ae7f76d5224a05b58165f3c804f8aa633f3dd6f22fbd435d5"
+                "sha256:57bcb59c5898818bd555b1e0cfcf668bd6204bc2b53ad0e70a52413bd790f9e4",
+                "sha256:73863dc3be1efe6ee638e77495c0c195a6384ae7b15c561f3ceb2698ae7267c1"
             ],
             "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
-            "version": "==20.7.0"
+            "version": "==20.7.1"
+        },
+        "wcwidth": {
+            "hashes": [
+                "sha256:beb4802a9cebb9144e99086eff703a642a13d6a0052920003a230f3294bbe784",
+                "sha256:c4d647b99872929fdb7bdcaa4fbe7f01413ed3d98077df798530e5b04f116c83"
+            ],
+            "version": "==0.2.5"
         },
         "webencodings": {
             "hashes": [
@@ -1244,11 +1267,11 @@
         },
         "wheel": {
             "hashes": [
-                "sha256:78b5b185f0e5763c26ca1e324373aadd49182ca90e825f7853f4b2509215dc0e",
-                "sha256:e11eefd162658ea59a60a0f6c7d493a7190ea4b9a85e335b33489d9f17e0245e"
+                "sha256:21014b2bd93c6d0034b6ba5d35e4eb284340e09d63c59aef6fc14b0f346146fd",
+                "sha256:e2ef7239991699e3355d54f8e968a21bb940a1dbf34a4d226741e64462516fad"
             ],
             "index": "pypi",
-            "version": "==0.36.2"
+            "version": "==0.37.0"
         },
         "yarl": {
             "hashes": [

From ef7c45f28132a7704a4549072ce5b272034fa196 Mon Sep 17 00:00:00 2001
From: Aneesh Agrawal <aneeshusa@gmail.com>
Date: Wed, 18 Aug 2021 09:24:14 -0700
Subject: [PATCH 0279/1034] Remove `language_version` for pre-commit (#2430)

* Remove `language_version` for pre-commit

At my company, we set the Python version in `default_language_version`
in each repo's `.pre-commit-config.yaml`,
so that all hooks are running with the same Python version.

However, this currently doesn't work for black,
as the `language_version` specified here
in the upstream `.pre-commit-hooks.yaml` takes precedence.
Currently, this requires us to manually set `language_version`
specifically for black,
duplicating the value from `default_language_version`.
The failure mode otherwise is subtle -
black works most of the time,
but try to add a walrus operator and it suddenly breaks!

Given that black's `setup.py` already has `python_requires>=3.6.2`,
specifying that `python3` must be used here isn't needed
as folks inadvertently using Python 2 will get hook-install-time failures anyways.
Remove the `language_version` from these upstream hook configs
so that users of black are able to use `default_language_version`
and have it apply to all their hooks, black included.

Example `.pre-commit-config.yaml` before:
```
default_language_version:
  python: python3.8
repos:
-   repo: https://github.com/psf/black
    rev: 21.7b0
    hooks:
    -   id: black
        language_version: python3.8
```

After:
```
default_language_version:
  python: python3.8
repos:
-   repo: https://github.com/psf/black
    rev: 21.7b0
    hooks:
    -   id: black
```

* Add changelog entry
---
 .pre-commit-hooks.yaml | 2 --
 CHANGES.md             | 5 +++++
 2 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/.pre-commit-hooks.yaml b/.pre-commit-hooks.yaml
index 81848d7dcf7..137957045a6 100644
--- a/.pre-commit-hooks.yaml
+++ b/.pre-commit-hooks.yaml
@@ -3,7 +3,6 @@
   description: "Black: The uncompromising Python code formatter"
   entry: black
   language: python
-  language_version: python3
   minimum_pre_commit_version: 2.9.2
   require_serial: true
   types_or: [python, pyi]
@@ -13,7 +12,6 @@
     "Black: The uncompromising Python code formatter (with Jupyter Notebook support)"
   entry: black
   language: python
-  language_version: python3
   minimum_pre_commit_version: 2.9.2
   require_serial: true
   types_or: [python, pyi, jupyter]
diff --git a/CHANGES.md b/CHANGES.md
index a678aaefc2a..a4b8e01fb93 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -7,6 +7,11 @@
 - Add support for formatting Jupyter Notebook files (#2357)
 - Move from `appdirs` dependency to `platformdirs` (#2375)
 
+### Integrations
+
+- The provided pre-commit hooks no longer specify `language_version` to avoid overriding
+  `default_language_version` (#2430)
+
 ## 21.7b0
 
 ### _Black_

From 104aec555fae0883ef5b53709569bd9c4d420bc5 Mon Sep 17 00:00:00 2001
From: Nipunn Koorapati <nipunn1313@gmail.com>
Date: Fri, 20 Aug 2021 16:54:53 -0700
Subject: [PATCH 0280/1034] Present a more user-friendly error if .gitignore is
 invalid (#2414)

Fixes #2359.

This commit now makes Black exit with an user-friendly error message if a
.gitignore file couldn't be parsed -- a massive improvement over an opaque
traceback!
---
 CHANGES.md                                    |  1 +
 setup.py                                      |  2 +-
 src/black/__init__.py                         | 28 +++++++++++--------
 src/black/files.py                            |  7 ++++-
 tests/data/invalid_gitignore_tests/.gitignore |  1 +
 tests/data/invalid_gitignore_tests/a.py       |  0
 .../invalid_gitignore_tests/pyproject.toml    |  1 +
 .../data/invalid_nested_gitignore_tests/a.py  |  0
 .../a/.gitignore                              |  1 +
 .../invalid_nested_gitignore_tests/a/a.py     |  0
 .../pyproject.toml                            |  1 +
 tests/test_black.py                           | 24 ++++++++++++++++
 12 files changed, 52 insertions(+), 14 deletions(-)
 create mode 100644 tests/data/invalid_gitignore_tests/.gitignore
 create mode 100644 tests/data/invalid_gitignore_tests/a.py
 create mode 100644 tests/data/invalid_gitignore_tests/pyproject.toml
 create mode 100644 tests/data/invalid_nested_gitignore_tests/a.py
 create mode 100644 tests/data/invalid_nested_gitignore_tests/a/.gitignore
 create mode 100644 tests/data/invalid_nested_gitignore_tests/a/a.py
 create mode 100644 tests/data/invalid_nested_gitignore_tests/pyproject.toml

diff --git a/CHANGES.md b/CHANGES.md
index a4b8e01fb93..3a96029bf5c 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -6,6 +6,7 @@
 
 - Add support for formatting Jupyter Notebook files (#2357)
 - Move from `appdirs` dependency to `platformdirs` (#2375)
+- Present a more user-friendly error if .gitignore is invalid (#2414)
 
 ### Integrations
 
diff --git a/setup.py b/setup.py
index 92b78f1abe1..215fa6cff61 100644
--- a/setup.py
+++ b/setup.py
@@ -77,7 +77,7 @@ def get_long_description() -> str:
         "tomli>=0.2.6,<2.0.0",
         "typed-ast>=1.4.2; python_version < '3.8'",
         "regex>=2020.1.8",
-        "pathspec>=0.8.1, <1",
+        "pathspec>=0.9.0, <1",
         "dataclasses>=0.6; python_version < '3.7'",
         "typing_extensions>=3.10.0.0; python_version < '3.10'",
         "mypy_extensions>=0.4.3",
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 29fb244f8b7..60f4fa34e9d 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -9,6 +9,7 @@
 from multiprocessing import Manager, freeze_support
 import os
 from pathlib import Path
+from pathspec.patterns.gitwildmatch import GitWildMatchPatternError
 import regex as re
 import signal
 import sys
@@ -428,18 +429,21 @@ def main(
             content=code, fast=fast, write_back=write_back, mode=mode, report=report
         )
     else:
-        sources = get_sources(
-            ctx=ctx,
-            src=src,
-            quiet=quiet,
-            verbose=verbose,
-            include=include,
-            exclude=exclude,
-            extend_exclude=extend_exclude,
-            force_exclude=force_exclude,
-            report=report,
-            stdin_filename=stdin_filename,
-        )
+        try:
+            sources = get_sources(
+                ctx=ctx,
+                src=src,
+                quiet=quiet,
+                verbose=verbose,
+                include=include,
+                exclude=exclude,
+                extend_exclude=extend_exclude,
+                force_exclude=force_exclude,
+                report=report,
+                stdin_filename=stdin_filename,
+            )
+        except GitWildMatchPatternError:
+            ctx.exit(1)
 
         path_empty(
             sources,
diff --git a/src/black/files.py b/src/black/files.py
index ba60c84a275..4d7b47aaa9f 100644
--- a/src/black/files.py
+++ b/src/black/files.py
@@ -18,6 +18,7 @@
 )
 
 from pathspec import PathSpec
+from pathspec.patterns.gitwildmatch import GitWildMatchPatternError
 import tomli
 
 from black.output import err
@@ -122,7 +123,11 @@ def get_gitignore(root: Path) -> PathSpec:
     if gitignore.is_file():
         with gitignore.open(encoding="utf-8") as gf:
             lines = gf.readlines()
-    return PathSpec.from_lines("gitwildmatch", lines)
+    try:
+        return PathSpec.from_lines("gitwildmatch", lines)
+    except GitWildMatchPatternError as e:
+        err(f"Could not parse {gitignore}: {e}")
+        raise
 
 
 def normalize_path_maybe_ignore(
diff --git a/tests/data/invalid_gitignore_tests/.gitignore b/tests/data/invalid_gitignore_tests/.gitignore
new file mode 100644
index 00000000000..cdf4cb4feba
--- /dev/null
+++ b/tests/data/invalid_gitignore_tests/.gitignore
@@ -0,0 +1 @@
+!
diff --git a/tests/data/invalid_gitignore_tests/a.py b/tests/data/invalid_gitignore_tests/a.py
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/tests/data/invalid_gitignore_tests/pyproject.toml b/tests/data/invalid_gitignore_tests/pyproject.toml
new file mode 100644
index 00000000000..3908e457a9e
--- /dev/null
+++ b/tests/data/invalid_gitignore_tests/pyproject.toml
@@ -0,0 +1 @@
+# Empty configuration file; used in tests to avoid interference from Black's own config.
diff --git a/tests/data/invalid_nested_gitignore_tests/a.py b/tests/data/invalid_nested_gitignore_tests/a.py
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/tests/data/invalid_nested_gitignore_tests/a/.gitignore b/tests/data/invalid_nested_gitignore_tests/a/.gitignore
new file mode 100644
index 00000000000..cdf4cb4feba
--- /dev/null
+++ b/tests/data/invalid_nested_gitignore_tests/a/.gitignore
@@ -0,0 +1 @@
+!
diff --git a/tests/data/invalid_nested_gitignore_tests/a/a.py b/tests/data/invalid_nested_gitignore_tests/a/a.py
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/tests/data/invalid_nested_gitignore_tests/pyproject.toml b/tests/data/invalid_nested_gitignore_tests/pyproject.toml
new file mode 100644
index 00000000000..3908e457a9e
--- /dev/null
+++ b/tests/data/invalid_nested_gitignore_tests/pyproject.toml
@@ -0,0 +1 @@
+# Empty configuration file; used in tests to avoid interference from Black's own config.
diff --git a/tests/test_black.py b/tests/test_black.py
index 942446ec343..5c720507216 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -1727,6 +1727,30 @@ def test_nested_gitignore(self) -> None:
         )
         self.assertEqual(sorted(expected), sorted(sources))
 
+    def test_invalid_gitignore(self) -> None:
+        path = THIS_DIR / "data" / "invalid_gitignore_tests"
+        empty_config = path / "pyproject.toml"
+        result = BlackRunner().invoke(
+            black.main, ["--verbose", "--config", str(empty_config), str(path)]
+        )
+        assert result.exit_code == 1
+        assert result.stderr_bytes is not None
+
+        gitignore = path / ".gitignore"
+        assert f"Could not parse {gitignore}" in result.stderr_bytes.decode()
+
+    def test_invalid_nested_gitignore(self) -> None:
+        path = THIS_DIR / "data" / "invalid_nested_gitignore_tests"
+        empty_config = path / "pyproject.toml"
+        result = BlackRunner().invoke(
+            black.main, ["--verbose", "--config", str(empty_config), str(path)]
+        )
+        assert result.exit_code == 1
+        assert result.stderr_bytes is not None
+
+        gitignore = path / "a" / ".gitignore"
+        assert f"Could not parse {gitignore}" in result.stderr_bytes.decode()
+
     def test_empty_include(self) -> None:
         path = THIS_DIR / "data" / "include_exclude_tests"
         report = black.Report()

From 8c04847aa22d14f01bb206cfc1b1e1cebd2ae538 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Sun, 22 Aug 2021 22:52:19 -0400
Subject: [PATCH 0281/1034] Improve f-string expression detection regex so ...
 (#2437)

we don't accidentally add backslashes to them when normalizing quotes
because that's invalid syntax!

The problem this commit fixes is that matches would eat too much
blocking important matches to occur. For example, here's one f-string
body:

    {a}{b}{c}

I know there's no risk of introducing backslashes here, but the regex
already goes sideways with this. Throwing this example at regex101
I get:

    {a}{b}{c}   # The As and Bs are the two matches, and the upper
    ---- ----   # case letters are the groups with those matches.
    aAaa bbBb

... we've missed the middle expression (so if any backslashes in a
more complex example were introduced there we wouldn't bail out
even though we should -- hence the bug). As it stands the regex
needs somesort of extra character (or the start/end of the body)
around the expressions but that isn't always the case as shown
above.

The fix implemented here is to turn the "eat a surrounding non-curly
bracket character" groups ie. `(?:[^{]|^)` and `(?:[^}]|$)` into
negative lookaheads and lookbehinds. This still guarantees the
already specified rules but without problematically eating extra
characters ^^
---
 CHANGES.md                  |  2 ++
 src/black/strings.py        |  4 ++--
 tests/data/string_quotes.py | 10 ++++++++++
 3 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 3a96029bf5c..22ddc423e55 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -7,6 +7,8 @@
 - Add support for formatting Jupyter Notebook files (#2357)
 - Move from `appdirs` dependency to `platformdirs` (#2375)
 - Present a more user-friendly error if .gitignore is invalid (#2414)
+- The failsafe for accidentally added backslashes in f-string expressions has been
+  hardened to handle more edge cases during quote normalization (#2437)
 
 ### Integrations
 
diff --git a/src/black/strings.py b/src/black/strings.py
index 80f588f5119..d7b6c240e80 100644
--- a/src/black/strings.py
+++ b/src/black/strings.py
@@ -190,9 +190,9 @@ def normalize_string_quotes(s: str) -> str:
     if "f" in prefix.casefold():
         matches = re.findall(
             r"""
-            (?:[^{]|^)\{  # start of the string or a non-{ followed by a single {
+            (?:(?<!\{)|^)\{  # start of the string or a non-{ followed by a single {
                 ([^{].*?)  # contents of the brackets except if begins with {{
-            \}(?:[^}]|$)  # A } followed by end of the string or a non-}
+            \}(?:(?!\})|$)  # A } followed by end of the string or a non-}
             """,
             new_body,
             re.VERBOSE,
diff --git a/tests/data/string_quotes.py b/tests/data/string_quotes.py
index 5a4bc5d0b11..3384241f4ad 100644
--- a/tests/data/string_quotes.py
+++ b/tests/data/string_quotes.py
@@ -51,6 +51,11 @@
 '\'{z}\' {y * " "}'
 '{y * x} \'{z}\''
 
+# We must bail out if changing the quotes would introduce backslashes in f-string
+# expressions. xref: https://github.com/psf/black/issues/2348
+f"\"{b}\"{' ' * (long-len(b)+1)}: \"{sts}\",\n"
+f"\"{a}\"{'hello' * b}\"{c}\""
+
 # output
 
 """"""
@@ -100,3 +105,8 @@
 f"{y * x} '{z}'"
 "'{z}' {y * \" \"}"
 "{y * x} '{z}'"
+
+# We must bail out if changing the quotes would introduce backslashes in f-string
+# expressions. xref: https://github.com/psf/black/issues/2348
+f"\"{b}\"{' ' * (long-len(b)+1)}: \"{sts}\",\n"
+f"\"{a}\"{'hello' * b}\"{c}\""

From b97a4ac449c6f0fd987e9ad2d0228fa756870086 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Sun, 22 Aug 2021 23:20:06 -0400
Subject: [PATCH 0282/1034] Add test requirements to Pipfile[.lock] & bump deps
 (#2436)

While this development environment / requirements situation is a mess,
let's at least make it consistent. We're effectively supporting two
modes of development in this project, 1) tox based dev commands
(e.g. `tox -e fuzz`) that are dead simple to use, and 2) manual dev
commands (e.g. `pytest -n auto`) that give more control and are usually
faster.

Right now the Pipfile.lock based development environment is incomplete
missing the test requirements specified in ./test_requirements.txt.
This is annoying since manual test commands (e.g. `pytest -k fmtonoff`)
fail. Let's fix this by making Pipfile.lock basically a
"everything you need" requirements file (fuzzing not included since
running it locally is not something common).

Oh and let's bump some documentation deps (and bring some requirements
across .pre-commit-config.yaml, Pipfile, and docs/requirement.txt in
alignment again). Don't worry, I tested these changes so they should
be fine (hopefully!).
---
 .pre-commit-config.yaml |   4 +-
 Pipfile                 |  33 ++-
 Pipfile.lock            | 551 +++++++++++++++++++++++++++++++---------
 docs/requirements.txt   |   6 +-
 4 files changed, 457 insertions(+), 137 deletions(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index ff9589bb3ce..5ae418d9bdd 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -19,7 +19,7 @@ repos:
         additional_dependencies: [flake8-bugbear]
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v0.902
+    rev: v0.910
     hooks:
       - id: mypy
         exclude: ^docs/conf.py
@@ -31,7 +31,7 @@ repos:
           - platformdirs >= 2.1.0
 
   - repo: https://github.com/pre-commit/mirrors-prettier
-    rev: v2.3.1
+    rev: v2.3.2
     hooks:
       - id: prettier
         exclude: ^Pipfile\.lock
diff --git a/Pipfile b/Pipfile
index c9238d3f69e..7f386c5381f 100644
--- a/Pipfile
+++ b/Pipfile
@@ -4,23 +4,38 @@ url = "https://pypi.python.org/simple"
 verify_ssl = true
 
 [dev-packages]
-Sphinx = ">=3.1.2"
-coverage = "*"
-docutils = "==0.15"  # not a direct dependency, see https://github.com/pypa/pipenv/issues/3865
-flake8 = "*"
+# Testing related requirements.
+coverage = ">= 5.3"
+pytest = " >= 6.1.1"
+pytest-mock = ">= 3.3.1"
+pytest-cases = ">= 2.3.0"
+pytest-xdist = ">= 2.2.1"
+pytest-cov = ">= 2.11.1"
+parameterized = ">= 0.7.4"
+tox = "*"
+
+# Linting related requirements.
+pre-commit = ">=2.9.2"
+flake8 = ">=3.9.2"
 flake8-bugbear = "*"
-mypy = ">=0.812"
+mypy = ">=0.910"
 types-dataclasses = ">=0.1.3"
 types-typed-ast = ">=1.4.1"
-pre-commit = "*"
-readme_renderer = "*"
-MyST-Parser = ">=0.13.7"
+
+# Documentation related requirements.
+Sphinx = ">=4.1.2"
+MyST-Parser = ">=0.15.1"
 sphinxcontrib-programoutput = ">=0.17"
-sphinx-copybutton = ">=0.3.0"
+sphinx-copybutton = ">=0.4.0"
+docutils = "==0.17.1"  # not a direct dependency, see https://github.com/pypa/pipenv/issues/3865
+
+# Packaging related requirements.
 setuptools = ">=39.2.0"
 setuptools-scm = "*"
 twine = ">=1.11.0"
 wheel = ">=0.31.1"
+readme_renderer = "*"
+
 black = {editable = true, extras = ["d", "jupyter"], path = "."}
 
 [packages]
diff --git a/Pipfile.lock b/Pipfile.lock
index 0c9a42348c3..6d62ec76680 100644
--- a/Pipfile.lock
+++ b/Pipfile.lock
@@ -1,7 +1,7 @@
 {
     "_meta": {
         "hash": {
-            "sha256": "eca7ef453dc0d16ab3910fc8035a3b57e2c1512dea8d9a95958eeecfe71935c1"
+            "sha256": "ac07cc9a5cb19ea72381baf4ba0db1689f475538d37e4be3119fc958a722b062"
         },
         "pipfile-spec": 6,
         "requires": {},
@@ -106,12 +106,12 @@
         },
         "dataclasses": {
             "hashes": [
-                "sha256:454a69d788c7fda44efd71e259be79577822f5e3f53f029a22d08004e951dc9f",
-                "sha256:6988bd2b895eef432d562370bb707d540f32f7360ab13da45340101bc2307d84"
+                "sha256:0201d89fa866f68c8ebd9d08ee6ff50c0b255f8ec63a71c16fda7af82bb887bf",
+                "sha256:8479067f342acf957dc82ec415d355ab5edb7e7646b90dc6e2fd1d96ad084c97"
             ],
             "index": "pypi",
             "python_version <": "3.7",
-            "version": "==0.6",
+            "version": "==0.8",
             "version >": "0.1.3"
         },
         "idna": {
@@ -122,6 +122,21 @@
             "markers": "python_version >= '3.5'",
             "version": "==3.2"
         },
+        "idna-ssl": {
+            "hashes": [
+                "sha256:a933e3bb13da54383f9e8f35dc4f9cb9eb9b3b78c6b36f311254d6d0d92c6c7c"
+            ],
+            "markers": "python_version < '3.7'",
+            "version": "==1.1.0"
+        },
+        "importlib-metadata": {
+            "hashes": [
+                "sha256:7b30a78db2922d78a6f47fb30683156a14f3c6aa5cc23f77cc8967e9ab2d002f",
+                "sha256:ed5157fef23a4bc4594615a0dd8eba94b2bb36bf2a343fa3d8bb2fa0a62a99d5"
+            ],
+            "markers": "python_version < '3.8'",
+            "version": "==4.6.4"
+        },
         "multidict": {
             "hashes": [
                 "sha256:018132dbd8688c7a69ad89c4a3f39ea2f9f33302ebe567a879da8f4ca73f0d0a",
@@ -191,42 +206,50 @@
         },
         "regex": {
             "hashes": [
-                "sha256:026beb631097a4a3def7299aa5825e05e057de3c6d72b139c37813bfa351274b",
-                "sha256:14caacd1853e40103f59571f169704367e79fb78fac3d6d09ac84d9197cadd16",
-                "sha256:16d9eaa8c7e91537516c20da37db975f09ac2e7772a0694b245076c6d68f85da",
-                "sha256:18fdc51458abc0a974822333bd3a932d4e06ba2a3243e9a1da305668bd62ec6d",
-                "sha256:28e8af338240b6f39713a34e337c3813047896ace09d51593d6907c66c0708ba",
-                "sha256:3835de96524a7b6869a6c710b26c90e94558c31006e96ca3cf6af6751b27dca1",
-                "sha256:3905c86cc4ab6d71635d6419a6f8d972cab7c634539bba6053c47354fd04452c",
-                "sha256:3c09d88a07483231119f5017904db8f60ad67906efac3f1baa31b9b7f7cca281",
-                "sha256:4551728b767f35f86b8e5ec19a363df87450c7376d7419c3cac5b9ceb4bce576",
-                "sha256:459bbe342c5b2dec5c5223e7c363f291558bc27982ef39ffd6569e8c082bdc83",
-                "sha256:4f421e3cdd3a273bace013751c345f4ebeef08f05e8c10757533ada360b51a39",
-                "sha256:577737ec3d4c195c4aef01b757905779a9e9aee608fa1cf0aec16b5576c893d3",
-                "sha256:57fece29f7cc55d882fe282d9de52f2f522bb85290555b49394102f3621751ee",
-                "sha256:7976d410e42be9ae7458c1816a416218364e06e162b82e42f7060737e711d9ce",
-                "sha256:85f568892422a0e96235eb8ea6c5a41c8ccbf55576a2260c0160800dbd7c4f20",
-                "sha256:8764a78c5464ac6bde91a8c87dd718c27c1cabb7ed2b4beaf36d3e8e390567f9",
-                "sha256:8935937dad2c9b369c3d932b0edbc52a62647c2afb2fafc0c280f14a8bf56a6a",
-                "sha256:8fe58d9f6e3d1abf690174fd75800fda9bdc23d2a287e77758dc0e8567e38ce6",
-                "sha256:937b20955806381e08e54bd9d71f83276d1f883264808521b70b33d98e4dec5d",
-                "sha256:9569da9e78f0947b249370cb8fadf1015a193c359e7e442ac9ecc585d937f08d",
-                "sha256:a3b73390511edd2db2d34ff09aa0b2c08be974c71b4c0505b4a048d5dc128c2b",
-                "sha256:a4eddbe2a715b2dd3849afbdeacf1cc283160b24e09baf64fa5675f51940419d",
-                "sha256:a5c6dbe09aff091adfa8c7cfc1a0e83fdb8021ddb2c183512775a14f1435fe16",
-                "sha256:b63e3571b24a7959017573b6455e05b675050bbbea69408f35f3cb984ec54363",
-                "sha256:bb350eb1060591d8e89d6bac4713d41006cd4d479f5e11db334a48ff8999512f",
-                "sha256:bf6d987edd4a44dd2fa2723fca2790f9442ae4de2c8438e53fcb1befdf5d823a",
-                "sha256:bfa6a679410b394600eafd16336b2ce8de43e9b13f7fb9247d84ef5ad2b45e91",
-                "sha256:c856ec9b42e5af4fe2d8e75970fcc3a2c15925cbcc6e7a9bcb44583b10b95e80",
-                "sha256:cea56288eeda8b7511d507bbe7790d89ae7049daa5f51ae31a35ae3c05408531",
-                "sha256:ea212df6e5d3f60341aef46401d32fcfded85593af1d82b8b4a7a68cd67fdd6b",
-                "sha256:f35567470ee6dbfb946f069ed5f5615b40edcbb5f1e6e1d3d2b114468d505fc6",
-                "sha256:fbc20975eee093efa2071de80df7f972b7b35e560b213aafabcec7c0bd00bd8c",
-                "sha256:ff4a8ad9638b7ca52313d8732f37ecd5fd3c8e3aff10a8ccb93176fd5b3812f6"
+                "sha256:03840a07a402576b8e3a6261f17eb88abd653ad4e18ec46ef10c9a63f8c99ebd",
+                "sha256:06ba444bbf7ede3890a912bd4904bb65bf0da8f0d8808b90545481362c978642",
+                "sha256:1f9974826aeeda32a76648fc677e3125ade379869a84aa964b683984a2dea9f1",
+                "sha256:330836ad89ff0be756b58758878409f591d4737b6a8cef26a162e2a4961c3321",
+                "sha256:38600fd58c2996829480de7d034fb2d3a0307110e44dae80b6b4f9b3d2eea529",
+                "sha256:3a195e26df1fbb40ebee75865f9b64ba692a5824ecb91c078cc665b01f7a9a36",
+                "sha256:41acdd6d64cd56f857e271009966c2ffcbd07ec9149ca91f71088574eaa4278a",
+                "sha256:45f97ade892ace20252e5ccecdd7515c7df5feeb42c3d2a8b8c55920c3551c30",
+                "sha256:4b0c211c55d4aac4309c3209833c803fada3fc21cdf7b74abedda42a0c9dc3ce",
+                "sha256:5d5209c3ba25864b1a57461526ebde31483db295fc6195fdfc4f8355e10f7376",
+                "sha256:615fb5a524cffc91ab4490b69e10ae76c1ccbfa3383ea2fad72e54a85c7d47dd",
+                "sha256:61e734c2bcb3742c3f454dfa930ea60ea08f56fd1a0eb52d8cb189a2f6be9586",
+                "sha256:640ccca4d0a6fcc6590f005ecd7b16c3d8f5d52174e4854f96b16f34c39d6cb7",
+                "sha256:6dbd51c3db300ce9d3171f4106da18fe49e7045232630fe3d4c6e37cb2b39ab9",
+                "sha256:71a904da8c9c02aee581f4452a5a988c3003207cb8033db426f29e5b2c0b7aea",
+                "sha256:8021dee64899f993f4b5cca323aae65aabc01a546ed44356a0965e29d7893c94",
+                "sha256:8b8d551f1bd60b3e1c59ff55b9e8d74607a5308f66e2916948cafd13480b44a3",
+                "sha256:93f9f720081d97acee38a411e861d4ce84cbc8ea5319bc1f8e38c972c47af49f",
+                "sha256:96f0c79a70642dfdf7e6a018ebcbea7ea5205e27d8e019cad442d2acfc9af267",
+                "sha256:9966337353e436e6ba652814b0a957a517feb492a98b8f9d3b6ba76d22301dcc",
+                "sha256:a34ba9e39f8269fd66ab4f7a802794ffea6d6ac500568ec05b327a862c21ce23",
+                "sha256:a49f85f0a099a5755d0a2cc6fc337e3cb945ad6390ec892332c691ab0a045882",
+                "sha256:a795829dc522227265d72b25d6ee6f6d41eb2105c15912c230097c8f5bfdbcdc",
+                "sha256:a89ca4105f8099de349d139d1090bad387fe2b208b717b288699ca26f179acbe",
+                "sha256:ac95101736239260189f426b1e361dc1b704513963357dc474beb0f39f5b7759",
+                "sha256:ae87ab669431f611c56e581679db33b9a467f87d7bf197ac384e71e4956b4456",
+                "sha256:b091dcfee169ad8de21b61eb2c3a75f9f0f859f851f64fdaf9320759a3244239",
+                "sha256:b511c6009d50d5c0dd0bab85ed25bc8ad6b6f5611de3a63a59786207e82824bb",
+                "sha256:b79dc2b2e313565416c1e62807c7c25c67a6ff0a0f8d83a318df464555b65948",
+                "sha256:bca14dfcfd9aae06d7d8d7e105539bd77d39d06caaae57a1ce945670bae744e0",
+                "sha256:c835c30f3af5c63a80917b72115e1defb83de99c73bc727bddd979a3b449e183",
+                "sha256:ccd721f1d4fc42b541b633d6e339018a08dd0290dc67269df79552843a06ca92",
+                "sha256:d6c2b1d78ceceb6741d703508cd0e9197b34f6bf6864dab30f940f8886e04ade",
+                "sha256:d6ec4ae13760ceda023b2e5ef1f9bc0b21e4b0830458db143794a117fdbdc044",
+                "sha256:d8b623fc429a38a881ab2d9a56ef30e8ea20c72a891c193f5ebbddc016e083ee",
+                "sha256:ea9753d64cba6f226947c318a923dadaf1e21cd8db02f71652405263daa1f033",
+                "sha256:ebbceefbffae118ab954d3cd6bf718f5790db66152f95202ebc231d58ad4e2c2",
+                "sha256:ecb6e7c45f9cd199c10ec35262b53b2247fb9a408803ed00ee5bb2b54aa626f5",
+                "sha256:ef9326c64349e2d718373415814e754183057ebc092261387a2c2f732d9172b2",
+                "sha256:f93a9d8804f4cec9da6c26c8cfae2c777028b4fdd9f49de0302e26e00bb86504",
+                "sha256:faf08b0341828f6a29b8f7dd94d5cf8cc7c39bfc3e67b78514c54b494b66915a"
             ],
             "index": "pypi",
-            "version": "==2021.8.3"
+            "version": "==2021.8.21"
         },
         "setuptools-scm": {
             "hashes": [
@@ -333,6 +356,14 @@
             ],
             "markers": "python_version >= '3.6'",
             "version": "==1.6.3"
+        },
+        "zipp": {
+            "hashes": [
+                "sha256:957cfda87797e389580cb8b9e3870841ca991e2125350677b2ca83a0e99390a3",
+                "sha256:f5812b1e007e48cff63449a5e9f4e7ebea716b4111f9c4f9a645f91d579bf0c4"
+            ],
+            "markers": "python_version >= '3.6'",
+            "version": "==3.5.0"
         }
     },
     "develop": {
@@ -394,14 +425,6 @@
             ],
             "version": "==0.7.12"
         },
-        "appnope": {
-            "hashes": [
-                "sha256:93aa393e9d6c54c5cd570ccadd8edad61ea0c4b9ea7a01409020c9aa019eb442",
-                "sha256:dd83cd4b5b460958838f6eb3000c660b1f9caf2a5b1de4264e941512f603258a"
-            ],
-            "markers": "sys_platform == 'darwin'",
-            "version": "==0.1.2"
-        },
         "async-timeout": {
             "hashes": [
                 "sha256:0c3c816a028d47f659d6ff5c745cb2acf1f966da1fe5c19c77a70282b25f4c5f",
@@ -463,6 +486,56 @@
             ],
             "version": "==2021.5.30"
         },
+        "cffi": {
+            "hashes": [
+                "sha256:06c54a68935738d206570b20da5ef2b6b6d92b38ef3ec45c5422c0ebaf338d4d",
+                "sha256:0c0591bee64e438883b0c92a7bed78f6290d40bf02e54c5bf0978eaf36061771",
+                "sha256:19ca0dbdeda3b2615421d54bef8985f72af6e0c47082a8d26122adac81a95872",
+                "sha256:22b9c3c320171c108e903d61a3723b51e37aaa8c81255b5e7ce102775bd01e2c",
+                "sha256:26bb2549b72708c833f5abe62b756176022a7b9a7f689b571e74c8478ead51dc",
+                "sha256:33791e8a2dc2953f28b8d8d300dde42dd929ac28f974c4b4c6272cb2955cb762",
+                "sha256:3c8d896becff2fa653dc4438b54a5a25a971d1f4110b32bd3068db3722c80202",
+                "sha256:4373612d59c404baeb7cbd788a18b2b2a8331abcc84c3ba40051fcd18b17a4d5",
+                "sha256:487d63e1454627c8e47dd230025780e91869cfba4c753a74fda196a1f6ad6548",
+                "sha256:48916e459c54c4a70e52745639f1db524542140433599e13911b2f329834276a",
+                "sha256:4922cd707b25e623b902c86188aca466d3620892db76c0bdd7b99a3d5e61d35f",
+                "sha256:55af55e32ae468e9946f741a5d51f9896da6b9bf0bbdd326843fec05c730eb20",
+                "sha256:57e555a9feb4a8460415f1aac331a2dc833b1115284f7ded7278b54afc5bd218",
+                "sha256:5d4b68e216fc65e9fe4f524c177b54964af043dde734807586cf5435af84045c",
+                "sha256:64fda793737bc4037521d4899be780534b9aea552eb673b9833b01f945904c2e",
+                "sha256:6d6169cb3c6c2ad50db5b868db6491a790300ade1ed5d1da29289d73bbe40b56",
+                "sha256:7bcac9a2b4fdbed2c16fa5681356d7121ecabf041f18d97ed5b8e0dd38a80224",
+                "sha256:80b06212075346b5546b0417b9f2bf467fea3bfe7352f781ffc05a8ab24ba14a",
+                "sha256:818014c754cd3dba7229c0f5884396264d51ffb87ec86e927ef0be140bfdb0d2",
+                "sha256:8eb687582ed7cd8c4bdbff3df6c0da443eb89c3c72e6e5dcdd9c81729712791a",
+                "sha256:99f27fefe34c37ba9875f224a8f36e31d744d8083e00f520f133cab79ad5e819",
+                "sha256:9f3e33c28cd39d1b655ed1ba7247133b6f7fc16fa16887b120c0c670e35ce346",
+                "sha256:a8661b2ce9694ca01c529bfa204dbb144b275a31685a075ce123f12331be790b",
+                "sha256:a9da7010cec5a12193d1af9872a00888f396aba3dc79186604a09ea3ee7c029e",
+                "sha256:aedb15f0a5a5949ecb129a82b72b19df97bbbca024081ed2ef88bd5c0a610534",
+                "sha256:b315d709717a99f4b27b59b021e6207c64620790ca3e0bde636a6c7f14618abb",
+                "sha256:ba6f2b3f452e150945d58f4badd92310449876c4c954836cfb1803bdd7b422f0",
+                "sha256:c33d18eb6e6bc36f09d793c0dc58b0211fccc6ae5149b808da4a62660678b156",
+                "sha256:c9a875ce9d7fe32887784274dd533c57909b7b1dcadcc128a2ac21331a9765dd",
+                "sha256:c9e005e9bd57bc987764c32a1bee4364c44fdc11a3cc20a40b93b444984f2b87",
+                "sha256:d2ad4d668a5c0645d281dcd17aff2be3212bc109b33814bbb15c4939f44181cc",
+                "sha256:d950695ae4381ecd856bcaf2b1e866720e4ab9a1498cba61c602e56630ca7195",
+                "sha256:e22dcb48709fc51a7b58a927391b23ab37eb3737a98ac4338e2448bef8559b33",
+                "sha256:e8c6a99be100371dbb046880e7a282152aa5d6127ae01783e37662ef73850d8f",
+                "sha256:e9dc245e3ac69c92ee4c167fbdd7428ec1956d4e754223124991ef29eb57a09d",
+                "sha256:eb687a11f0a7a1839719edd80f41e459cc5366857ecbed383ff376c4e3cc6afd",
+                "sha256:eb9e2a346c5238a30a746893f23a9535e700f8192a68c07c0258e7ece6ff3728",
+                "sha256:ed38b924ce794e505647f7c331b22a693bee1538fdf46b0222c4717b42f744e7",
+                "sha256:f0010c6f9d1a4011e429109fda55a225921e3206e7f62a0c22a35344bfd13cca",
+                "sha256:f0c5d1acbfca6ebdd6b1e3eded8d261affb6ddcf2186205518f1428b8569bb99",
+                "sha256:f10afb1004f102c7868ebfe91c28f4a712227fe4cb24974350ace1f90e1febbf",
+                "sha256:f174135f5609428cc6e1b9090f9268f5c8935fddb1b25ccb8255a2d50de6789e",
+                "sha256:f3ebe6e73c319340830a9b2825d32eb6d8475c1dac020b4f0aa774ee3b898d1c",
+                "sha256:f627688813d0a4140153ff532537fbe4afea5a3dffce1f9deb7f91f848a832b5",
+                "sha256:fd4305f86f53dfd8cd3522269ed7fc34856a8ee3709a5e28b2836b2db9d4cd69"
+            ],
+            "version": "==1.14.6"
+        },
         "cfgv": {
             "hashes": [
                 "sha256:9e600479b3b99e8af981ecdfc80a0296104ee610cab48a5ae4ffd0b668650eb1",
@@ -561,6 +634,43 @@
             "index": "pypi",
             "version": "==5.5"
         },
+        "cryptography": {
+            "hashes": [
+                "sha256:0f1212a66329c80d68aeeb39b8a16d54ef57071bf22ff4e521657b27372e327d",
+                "sha256:1e056c28420c072c5e3cb36e2b23ee55e260cb04eee08f702e0edfec3fb51959",
+                "sha256:240f5c21aef0b73f40bb9f78d2caff73186700bf1bc6b94285699aff98cc16c6",
+                "sha256:26965837447f9c82f1855e0bc8bc4fb910240b6e0d16a664bb722df3b5b06873",
+                "sha256:37340614f8a5d2fb9aeea67fd159bfe4f5f4ed535b1090ce8ec428b2f15a11f2",
+                "sha256:3d10de8116d25649631977cb37da6cbdd2d6fa0e0281d014a5b7d337255ca713",
+                "sha256:3d8427734c781ea5f1b41d6589c293089704d4759e34597dce91014ac125aad1",
+                "sha256:7ec5d3b029f5fa2b179325908b9cd93db28ab7b85bb6c1db56b10e0b54235177",
+                "sha256:8e56e16617872b0957d1c9742a3f94b43533447fd78321514abbe7db216aa250",
+                "sha256:b01fd6f2737816cb1e08ed4807ae194404790eac7ad030b34f2ce72b332f5586",
+                "sha256:bf40af59ca2465b24e54f671b2de2c59257ddc4f7e5706dbd6930e26823668d3",
+                "sha256:de4e5f7f68220d92b7637fc99847475b59154b7a1b3868fb7385337af54ac9ca",
+                "sha256:eb8cc2afe8b05acbd84a43905832ec78e7b3873fb124ca190f574dca7389a87d",
+                "sha256:ee77aa129f481be46f8d92a1a7db57269a2f23052d5f2433b4621bb457081cc9"
+            ],
+            "markers": "python_version >= '3.6'",
+            "version": "==3.4.7"
+        },
+        "dataclasses": {
+            "hashes": [
+                "sha256:0201d89fa866f68c8ebd9d08ee6ff50c0b255f8ec63a71c16fda7af82bb887bf",
+                "sha256:8479067f342acf957dc82ec415d355ab5edb7e7646b90dc6e2fd1d96ad084c97"
+            ],
+            "index": "pypi",
+            "python_version <": "3.7",
+            "version": "==0.8",
+            "version >": "0.1.3"
+        },
+        "decopatch": {
+            "hashes": [
+                "sha256:29a74d5d753423b188d5b537532da4f4b88e33ddccb95a8a20a5eff5b13265d4",
+                "sha256:c66b0815f15db04de7bb52b0b276432b76b7346fe7046f28033f48a14340d144"
+            ],
+            "version": "==1.4.8"
+        },
         "decorator": {
             "hashes": [
                 "sha256:6e5c199c16f7a9f0e3a61a4a54b3d27e7dad0dbdde92b944426cb20914376323",
@@ -578,12 +688,19 @@
         },
         "docutils": {
             "hashes": [
-                "sha256:54a349c622ff31c91cbec43b0b512f113b5b24daf00e2ea530bb1bd9aac14849",
-                "sha256:ba4584f9107571ced0d2c7f56a5499c696215ba90797849c92d395979da68521",
-                "sha256:d2ddba74835cb090a1b627d3de4e7835c628d07ee461f7b4480f51af2fe4d448"
+                "sha256:686577d2e4c32380bb50cbb22f575ed742d58168cee37e99117a854bcd88f125",
+                "sha256:cf316c8370a737a022b72b56874f6602acf974a37a9fba42ec2876387549fc61"
             ],
             "index": "pypi",
-            "version": "==0.15"
+            "version": "==0.17.1"
+        },
+        "execnet": {
+            "hashes": [
+                "sha256:8f694f3ba9cc92cab508b152dcfe322153975c29bda272e2fd7f3f00f36e47c5",
+                "sha256:a295f7cc774947aac58dde7fdc85f4aa00c42adf5d8f5468fc630c1acf30a142"
+            ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
+            "version": "==1.9.0"
         },
         "filelock": {
             "hashes": [
@@ -624,6 +741,13 @@
             "markers": "python_version >= '3.5'",
             "version": "==3.2"
         },
+        "idna-ssl": {
+            "hashes": [
+                "sha256:a933e3bb13da54383f9e8f35dc4f9cb9eb9b3b78c6b36f311254d6d0d92c6c7c"
+            ],
+            "markers": "python_version < '3.7'",
+            "version": "==1.1.0"
+        },
         "imagesize": {
             "hashes": [
                 "sha256:6965f19a6a2039c7d48bca7dba2473069ff854c36ae6f19d2cde309d998228a1",
@@ -634,19 +758,34 @@
         },
         "importlib-metadata": {
             "hashes": [
-                "sha256:0645585859e9a6689c523927a5032f2ba5919f1f7d0e84bd4533312320de1ff9",
-                "sha256:51c6635429c77cf1ae634c997ff9e53ca3438b495f10a55ba28594dd69764a8b"
+                "sha256:7b30a78db2922d78a6f47fb30683156a14f3c6aa5cc23f77cc8967e9ab2d002f",
+                "sha256:ed5157fef23a4bc4594615a0dd8eba94b2bb36bf2a343fa3d8bb2fa0a62a99d5"
             ],
-            "markers": "python_version >= '3.6'",
-            "version": "==4.6.3"
+            "markers": "python_version < '3.8'",
+            "version": "==4.6.4"
+        },
+        "importlib-resources": {
+            "hashes": [
+                "sha256:2480d8e07d1890056cb53c96e3de44fead9c62f2ba949b0f2e4c4345f4afa977",
+                "sha256:a65882a4d0fe5fbf702273456ba2ce74fe44892c25e42e057aca526b702a6d4b"
+            ],
+            "markers": "python_version < '3.7' and python_version < '3.7'",
+            "version": "==5.2.2"
+        },
+        "iniconfig": {
+            "hashes": [
+                "sha256:011e24c64b7f47f6ebd835bb12a743f2fbe9a26d4cecaa7f53bc4f35ee9da8b3",
+                "sha256:bc3af051d7d14b2ee5ef9969666def0cd1a000e121eaea580d4a313df4b37f32"
+            ],
+            "version": "==1.1.1"
         },
         "ipython": {
             "hashes": [
-                "sha256:0cff04bb042800129348701f7bd68a430a844e8fb193979c08f6c99f28bb735e",
-                "sha256:892743b65c21ed72b806a3a602cca408520b3200b89d1924f4b3d2cdb3692362"
+                "sha256:2dbcc8c27ca7d3cfe4fcdff7f45b27f9a8d3edfa70ff8024a71c7a8eb5f09d64",
+                "sha256:9f4fcb31d3b2c533333893b9172264e4821c1ac91839500f31bd43f2c59b3ccf"
             ],
-            "markers": "python_version >= '3.7'",
-            "version": "==7.26.0"
+            "markers": "python_version >= '3.6'",
+            "version": "==7.16.1"
         },
         "ipython-genutils": {
             "hashes": [
@@ -663,6 +802,14 @@
             "markers": "python_version >= '3.6'",
             "version": "==0.18.0"
         },
+        "jeepney": {
+            "hashes": [
+                "sha256:1b5a0ea5c0e7b166b2f5895b91a08c14de8915afda4407fb5022a195224958ac",
+                "sha256:fa9e232dfa0c498bd0b8a3a73b8d8a31978304dcef0515adc859d4e096f96f4f"
+            ],
+            "markers": "sys_platform == 'linux'",
+            "version": "==0.7.1"
+        },
         "jinja2": {
             "hashes": [
                 "sha256:1f06f2da51e7b56b8f238affdd6b4e2c61e39598a378cc49345bc1bd42a978a4",
@@ -673,11 +820,18 @@
         },
         "keyring": {
             "hashes": [
-                "sha256:045703609dd3fccfcdb27da201684278823b72af515aedec1a8515719a038cb8",
-                "sha256:8f607d7d1cc502c43a932a275a56fe47db50271904513a379d39df1af277ac48"
+                "sha256:b32397fd7e7063f8dd74a26db910c9862fc2109285fa16e3b5208bcb42a3e579",
+                "sha256:b7e0156667f5dcc73c1f63a518005cd18a4eb23fe77321194fefcc03748b21a4"
             ],
             "markers": "python_version >= '3.6'",
-            "version": "==23.0.1"
+            "version": "==23.1.0"
+        },
+        "makefun": {
+            "hashes": [
+                "sha256:033eed65e2c1804fca84161a38d1fc8bb8650d32a89ac1c5dc7e54b2b2c2e88c",
+                "sha256:a19bddf07efb6bf92e3ccde5d593e49bc59001fd6c17cf7301d7a73a2647ae83"
+            ],
+            "version": "==1.11.3"
         },
         "markdown-it-py": {
             "hashes": [
@@ -694,30 +848,50 @@
                 "sha256:0446679737af14f45767963a1a9ef7620189912317d095f2d9ffa183a4d25d2b",
                 "sha256:0717a7390a68be14b8c793ba258e075c6f4ca819f15edfc2a3a027c823718567",
                 "sha256:0955295dd5eec6cb6cc2fe1698f4c6d84af2e92de33fbcac4111913cd100a6ff",
+                "sha256:0d4b31cc67ab36e3392bbf3862cfbadac3db12bdd8b02a2731f509ed5b829724",
                 "sha256:10f82115e21dc0dfec9ab5c0223652f7197feb168c940f3ef61563fc2d6beb74",
+                "sha256:168cd0a3642de83558a5153c8bd34f175a9a6e7f6dc6384b9655d2697312a646",
                 "sha256:1d609f577dc6e1aa17d746f8bd3c31aa4d258f4070d61b2aa5c4166c1539de35",
+                "sha256:1f2ade76b9903f39aa442b4aadd2177decb66525062db244b35d71d0ee8599b6",
+                "sha256:2a7d351cbd8cfeb19ca00de495e224dea7e7d919659c2841bbb7f420ad03e2d6",
+                "sha256:2d7d807855b419fc2ed3e631034685db6079889a1f01d5d9dac950f764da3dad",
                 "sha256:2ef54abee730b502252bcdf31b10dacb0a416229b72c18b19e24a4509f273d26",
+                "sha256:36bc903cbb393720fad60fc28c10de6acf10dc6cc883f3e24ee4012371399a38",
+                "sha256:37205cac2a79194e3750b0af2a5720d95f786a55ce7df90c3af697bfa100eaac",
                 "sha256:3c112550557578c26af18a1ccc9e090bfe03832ae994343cfdacd287db6a6ae7",
+                "sha256:3dd007d54ee88b46be476e293f48c85048603f5f516008bee124ddd891398ed6",
                 "sha256:47ab1e7b91c098ab893b828deafa1203de86d0bc6ab587b160f78fe6c4011f75",
                 "sha256:49e3ceeabbfb9d66c3aef5af3a60cc43b85c33df25ce03d0031a608b0a8b2e3f",
                 "sha256:4efca8f86c54b22348a5467704e3fec767b2db12fc39c6d963168ab1d3fc9135",
                 "sha256:53edb4da6925ad13c07b6d26c2a852bd81e364f95301c66e930ab2aef5b5ddd8",
+                "sha256:5855f8438a7d1d458206a2466bf82b0f104a3724bf96a1c781ab731e4201731a",
                 "sha256:594c67807fb16238b30c44bdf74f36c02cdf22d1c8cda91ef8a0ed8dabf5620a",
+                "sha256:5bb28c636d87e840583ee3adeb78172efc47c8b26127267f54a9c0ec251d41a9",
+                "sha256:60bf42e36abfaf9aff1f50f52644b336d4f0a3fd6d8a60ca0d054ac9f713a864",
                 "sha256:611d1ad9a4288cf3e3c16014564df047fe08410e628f89805e475368bd304914",
                 "sha256:6557b31b5e2c9ddf0de32a691f2312a32f77cd7681d8af66c2692efdbef84c18",
                 "sha256:693ce3f9e70a6cf7d2fb9e6c9d8b204b6b39897a2c4a1aa65728d5ac97dcc1d8",
                 "sha256:6a7fae0dd14cf60ad5ff42baa2e95727c3d81ded453457771d02b7d2b3f9c0c2",
                 "sha256:6c4ca60fa24e85fe25b912b01e62cb969d69a23a5d5867682dd3e80b5b02581d",
+                "sha256:6fcf051089389abe060c9cd7caa212c707e58153afa2c649f00346ce6d260f1b",
                 "sha256:7d91275b0245b1da4d4cfa07e0faedd5b0812efc15b702576d103293e252af1b",
                 "sha256:905fec760bd2fa1388bb5b489ee8ee5f7291d692638ea5f67982d968366bef9f",
                 "sha256:97383d78eb34da7e1fa37dd273c20ad4320929af65d156e35a5e2d89566d9dfb",
                 "sha256:984d76483eb32f1bcb536dc27e4ad56bba4baa70be32fa87152832cdd9db0833",
+                "sha256:99df47edb6bda1249d3e80fdabb1dab8c08ef3975f69aed437cb69d0a5de1e28",
                 "sha256:a30e67a65b53ea0a5e62fe23682cfe22712e01f453b95233b25502f7c61cb415",
                 "sha256:ab3ef638ace319fa26553db0624c4699e31a28bb2a835c5faca8f8acf6a5a902",
+                "sha256:add36cb2dbb8b736611303cd3bfcee00afd96471b09cda130da3581cbdc56a6d",
                 "sha256:b2f4bf27480f5e5e8ce285a8c8fd176c0b03e93dcc6646477d4630e83440c6a9",
                 "sha256:b7f2d075102dc8c794cbde1947378051c4e5180d52d276987b8d28a3bd58c17d",
+                "sha256:baa1a4e8f868845af802979fcdbf0bb11f94f1cb7ced4c4b8a351bb60d108145",
                 "sha256:be98f628055368795d818ebf93da628541e10b75b41c559fdf36d104c5787066",
+                "sha256:bf5d821ffabf0ef3533c39c518f3357b171a1651c1ff6827325e4489b0e46c3c",
+                "sha256:c47adbc92fc1bb2b3274c4b3a43ae0e4573d9fbff4f54cd484555edbf030baf1",
                 "sha256:d7f9850398e85aba693bb640262d3611788b1f29a79f0c93c565694658f4071f",
+                "sha256:d8446c54dc28c01e5a2dbac5a25f071f6653e6e40f3a8818e8b45d790fe6ef53",
+                "sha256:e0f138900af21926a02425cf736db95be9f4af72ba1bb21453432a07f6082134",
+                "sha256:e9936f0b261d4df76ad22f8fee3ae83b60d7c3e871292cd42f40b81b70afae85",
                 "sha256:f5653a225f31e113b152e56f154ccbe59eeb1c7487b39b9d9f9cdb58e6c79dc5",
                 "sha256:f826e31d18b516f653fe296d967d700fddad5901ae07c622bb3705955e1faa94",
                 "sha256:f8ba0e8349a38d3001fae7eadded3f6606f0da5d748ee53cc1dab1d6527b9509",
@@ -727,14 +901,6 @@
             "markers": "python_version >= '3.6'",
             "version": "==2.0.1"
         },
-        "matplotlib-inline": {
-            "hashes": [
-                "sha256:5cf1176f554abb4fa98cb362aa2b55c500147e4bdbb07e3fda359143e1da0811",
-                "sha256:f41d5ff73c9f5385775d5c0bc13b424535c8402fe70ea8210f93e11f3683993e"
-            ],
-            "markers": "python_version >= '3.5'",
-            "version": "==0.1.2"
-        },
         "mccabe": {
             "hashes": [
                 "sha256:ab8a6258860da4b6677da4bd2fe5dc2c659cff31b3ee4f7f5d64e79735b80d42",
@@ -853,6 +1019,14 @@
             "markers": "python_version >= '3.6'",
             "version": "==21.0"
         },
+        "parameterized": {
+            "hashes": [
+                "sha256:41bbff37d6186430f77f900d777e5bb6a24928a1c46fb1de692f8b52b8833b5c",
+                "sha256:9cbb0b69a03e8695d68b3399a8a5825200976536fe1cb79db60ed6a4c8c9efe9"
+            ],
+            "index": "pypi",
+            "version": "==0.8.1"
+        },
         "parso": {
             "hashes": [
                 "sha256:12b83492c6239ce32ff5eed6d3639d6a536170723c6f3f1506869f1ace413398",
@@ -899,6 +1073,14 @@
             "index": "pypi",
             "version": "==2.2.0"
         },
+        "pluggy": {
+            "hashes": [
+                "sha256:15b2acde666561e1298d71b523007ed7364de07029219b604cf808bfa1c765b0",
+                "sha256:966c145cd83c96502c3c3868f50408687b38434af77734af1e9ca461a4081d2d"
+            ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
+            "version": "==0.13.1"
+        },
         "pre-commit": {
             "hashes": [
                 "sha256:2386eeb4cf6633712c7cc9ede83684d53c8cafca6b59f79c738098b51c6d206c",
@@ -909,11 +1091,11 @@
         },
         "prompt-toolkit": {
             "hashes": [
-                "sha256:08360ee3a3148bdb5163621709ee322ec34fc4375099afa4bbf751e9b7b7fa4f",
-                "sha256:7089d8d2938043508aa9420ec18ce0922885304cddae87fb96eebca942299f88"
+                "sha256:6076e46efae19b1e0ca1ec003ed37a933dc94b4d20f486235d436e64771dcd5c",
+                "sha256:eb71d5a6b72ce6db177af4a7d4d7085b99756bf656d98ffcc4fecd36850eea6c"
             ],
-            "markers": "python_full_version >= '3.6.1'",
-            "version": "==3.0.19"
+            "markers": "python_full_version >= '3.6.2'",
+            "version": "==3.0.20"
         },
         "ptyprocess": {
             "hashes": [
@@ -922,6 +1104,14 @@
             ],
             "version": "==0.7.0"
         },
+        "py": {
+            "hashes": [
+                "sha256:21b81bda15b66ef5e1a777a21c4dcd9c20ad3efd0b3f817e7a809035269e1bd3",
+                "sha256:3b80836aa6d1feeaa108e046da6423ab8f6ceda6468545ae8d02d9d58d18818a"
+            ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
+            "version": "==1.10.0"
+        },
         "pycodestyle": {
             "hashes": [
                 "sha256:514f76d918fcc0b55c6680472f0a37970994e07bbb80725808c17089be302068",
@@ -930,6 +1120,14 @@
             "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==2.7.0"
         },
+        "pycparser": {
+            "hashes": [
+                "sha256:2d475327684562c3a96cc71adf7dc8c4f0565175cf86b6d7a404ff4c771f15f0",
+                "sha256:7582ad22678f0fcd81102833f60ef8d0e57288b6b5fb00323d101be910e35705"
+            ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
+            "version": "==2.20"
+        },
         "pyflakes": {
             "hashes": [
                 "sha256:7893783d01b8a89811dd72d7dfd4d84ff098e5eed95cfa8905b22bbffe52efc3",
@@ -940,20 +1138,68 @@
         },
         "pygments": {
             "hashes": [
-                "sha256:a18f47b506a429f6f4b9df81bb02beab9ca21d0a5fee38ed15aef65f0545519f",
-                "sha256:d66e804411278594d764fc69ec36ec13d9ae9147193a1740cd34d272ca383b8e"
+                "sha256:b8e67fe6af78f492b3c4b3e2970c0624cbf08beb1e493b2c99b9fa1b67a20380",
+                "sha256:f398865f7eb6874156579fdf36bc840a03cab64d1cde9e93d68f46a425ec52c6"
             ],
             "markers": "python_version >= '3.5'",
-            "version": "==2.9.0"
+            "version": "==2.10.0"
         },
         "pyparsing": {
             "hashes": [
                 "sha256:c203ec8783bf771a155b207279b9bccb8dea02d8f0c9e5f8ead507bc3246ecc1",
                 "sha256:ef9d7589ef3c200abe66653d3f1ab1033c3c419ae9b9bdb1240a85b024efc88b"
             ],
-            "markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2, 3.3'",
+            "markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2'",
             "version": "==2.4.7"
         },
+        "pytest": {
+            "hashes": [
+                "sha256:50bcad0a0b9c5a72c8e4e7c9855a3ad496ca6a881a3641b4260605450772c54b",
+                "sha256:91ef2131a9bd6be8f76f1f08eac5c5317221d6ad1e143ae03894b862e8976890"
+            ],
+            "index": "pypi",
+            "version": "==6.2.4"
+        },
+        "pytest-cases": {
+            "hashes": [
+                "sha256:13136269240615bc79041f8af8fc96e0e3e085da72dd22b18625451fda2443b8",
+                "sha256:a4abe0ec2b8acf8f8b5ab73060de72eac745c6ed9cfa317d59ae71b4a0bbbdf5"
+            ],
+            "index": "pypi",
+            "version": "==3.6.3"
+        },
+        "pytest-cov": {
+            "hashes": [
+                "sha256:261bb9e47e65bd099c89c3edf92972865210c36813f80ede5277dceb77a4a62a",
+                "sha256:261ceeb8c227b726249b376b8526b600f38667ee314f910353fa318caa01f4d7"
+            ],
+            "index": "pypi",
+            "version": "==2.12.1"
+        },
+        "pytest-forked": {
+            "hashes": [
+                "sha256:6aa9ac7e00ad1a539c41bec6d21011332de671e938c7637378ec9710204e37ca",
+                "sha256:dc4147784048e70ef5d437951728825a131b81714b398d5d52f17c7c144d8815"
+            ],
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
+            "version": "==1.3.0"
+        },
+        "pytest-mock": {
+            "hashes": [
+                "sha256:30c2f2cc9759e76eee674b81ea28c9f0b94f8f0445a1b87762cadf774f0df7e3",
+                "sha256:40217a058c52a63f1042f0784f62009e976ba824c418cced42e88d5f40ab0e62"
+            ],
+            "index": "pypi",
+            "version": "==3.6.1"
+        },
+        "pytest-xdist": {
+            "hashes": [
+                "sha256:e8ecde2f85d88fbcadb7d28cb33da0fa29bca5cf7d5967fa89fc0e97e5299ea5",
+                "sha256:ed3d7da961070fce2a01818b51f6888327fb88df4379edeb6b9d990e789d9c8d"
+            ],
+            "index": "pypi",
+            "version": "==2.3.0"
+        },
         "pytz": {
             "hashes": [
                 "sha256:83a4a90894bf38e243cf052c8b58f381bfe9a7a483f6a9cab140bc7f702ac4da",
@@ -1006,42 +1252,50 @@
         },
         "regex": {
             "hashes": [
-                "sha256:026beb631097a4a3def7299aa5825e05e057de3c6d72b139c37813bfa351274b",
-                "sha256:14caacd1853e40103f59571f169704367e79fb78fac3d6d09ac84d9197cadd16",
-                "sha256:16d9eaa8c7e91537516c20da37db975f09ac2e7772a0694b245076c6d68f85da",
-                "sha256:18fdc51458abc0a974822333bd3a932d4e06ba2a3243e9a1da305668bd62ec6d",
-                "sha256:28e8af338240b6f39713a34e337c3813047896ace09d51593d6907c66c0708ba",
-                "sha256:3835de96524a7b6869a6c710b26c90e94558c31006e96ca3cf6af6751b27dca1",
-                "sha256:3905c86cc4ab6d71635d6419a6f8d972cab7c634539bba6053c47354fd04452c",
-                "sha256:3c09d88a07483231119f5017904db8f60ad67906efac3f1baa31b9b7f7cca281",
-                "sha256:4551728b767f35f86b8e5ec19a363df87450c7376d7419c3cac5b9ceb4bce576",
-                "sha256:459bbe342c5b2dec5c5223e7c363f291558bc27982ef39ffd6569e8c082bdc83",
-                "sha256:4f421e3cdd3a273bace013751c345f4ebeef08f05e8c10757533ada360b51a39",
-                "sha256:577737ec3d4c195c4aef01b757905779a9e9aee608fa1cf0aec16b5576c893d3",
-                "sha256:57fece29f7cc55d882fe282d9de52f2f522bb85290555b49394102f3621751ee",
-                "sha256:7976d410e42be9ae7458c1816a416218364e06e162b82e42f7060737e711d9ce",
-                "sha256:85f568892422a0e96235eb8ea6c5a41c8ccbf55576a2260c0160800dbd7c4f20",
-                "sha256:8764a78c5464ac6bde91a8c87dd718c27c1cabb7ed2b4beaf36d3e8e390567f9",
-                "sha256:8935937dad2c9b369c3d932b0edbc52a62647c2afb2fafc0c280f14a8bf56a6a",
-                "sha256:8fe58d9f6e3d1abf690174fd75800fda9bdc23d2a287e77758dc0e8567e38ce6",
-                "sha256:937b20955806381e08e54bd9d71f83276d1f883264808521b70b33d98e4dec5d",
-                "sha256:9569da9e78f0947b249370cb8fadf1015a193c359e7e442ac9ecc585d937f08d",
-                "sha256:a3b73390511edd2db2d34ff09aa0b2c08be974c71b4c0505b4a048d5dc128c2b",
-                "sha256:a4eddbe2a715b2dd3849afbdeacf1cc283160b24e09baf64fa5675f51940419d",
-                "sha256:a5c6dbe09aff091adfa8c7cfc1a0e83fdb8021ddb2c183512775a14f1435fe16",
-                "sha256:b63e3571b24a7959017573b6455e05b675050bbbea69408f35f3cb984ec54363",
-                "sha256:bb350eb1060591d8e89d6bac4713d41006cd4d479f5e11db334a48ff8999512f",
-                "sha256:bf6d987edd4a44dd2fa2723fca2790f9442ae4de2c8438e53fcb1befdf5d823a",
-                "sha256:bfa6a679410b394600eafd16336b2ce8de43e9b13f7fb9247d84ef5ad2b45e91",
-                "sha256:c856ec9b42e5af4fe2d8e75970fcc3a2c15925cbcc6e7a9bcb44583b10b95e80",
-                "sha256:cea56288eeda8b7511d507bbe7790d89ae7049daa5f51ae31a35ae3c05408531",
-                "sha256:ea212df6e5d3f60341aef46401d32fcfded85593af1d82b8b4a7a68cd67fdd6b",
-                "sha256:f35567470ee6dbfb946f069ed5f5615b40edcbb5f1e6e1d3d2b114468d505fc6",
-                "sha256:fbc20975eee093efa2071de80df7f972b7b35e560b213aafabcec7c0bd00bd8c",
-                "sha256:ff4a8ad9638b7ca52313d8732f37ecd5fd3c8e3aff10a8ccb93176fd5b3812f6"
+                "sha256:03840a07a402576b8e3a6261f17eb88abd653ad4e18ec46ef10c9a63f8c99ebd",
+                "sha256:06ba444bbf7ede3890a912bd4904bb65bf0da8f0d8808b90545481362c978642",
+                "sha256:1f9974826aeeda32a76648fc677e3125ade379869a84aa964b683984a2dea9f1",
+                "sha256:330836ad89ff0be756b58758878409f591d4737b6a8cef26a162e2a4961c3321",
+                "sha256:38600fd58c2996829480de7d034fb2d3a0307110e44dae80b6b4f9b3d2eea529",
+                "sha256:3a195e26df1fbb40ebee75865f9b64ba692a5824ecb91c078cc665b01f7a9a36",
+                "sha256:41acdd6d64cd56f857e271009966c2ffcbd07ec9149ca91f71088574eaa4278a",
+                "sha256:45f97ade892ace20252e5ccecdd7515c7df5feeb42c3d2a8b8c55920c3551c30",
+                "sha256:4b0c211c55d4aac4309c3209833c803fada3fc21cdf7b74abedda42a0c9dc3ce",
+                "sha256:5d5209c3ba25864b1a57461526ebde31483db295fc6195fdfc4f8355e10f7376",
+                "sha256:615fb5a524cffc91ab4490b69e10ae76c1ccbfa3383ea2fad72e54a85c7d47dd",
+                "sha256:61e734c2bcb3742c3f454dfa930ea60ea08f56fd1a0eb52d8cb189a2f6be9586",
+                "sha256:640ccca4d0a6fcc6590f005ecd7b16c3d8f5d52174e4854f96b16f34c39d6cb7",
+                "sha256:6dbd51c3db300ce9d3171f4106da18fe49e7045232630fe3d4c6e37cb2b39ab9",
+                "sha256:71a904da8c9c02aee581f4452a5a988c3003207cb8033db426f29e5b2c0b7aea",
+                "sha256:8021dee64899f993f4b5cca323aae65aabc01a546ed44356a0965e29d7893c94",
+                "sha256:8b8d551f1bd60b3e1c59ff55b9e8d74607a5308f66e2916948cafd13480b44a3",
+                "sha256:93f9f720081d97acee38a411e861d4ce84cbc8ea5319bc1f8e38c972c47af49f",
+                "sha256:96f0c79a70642dfdf7e6a018ebcbea7ea5205e27d8e019cad442d2acfc9af267",
+                "sha256:9966337353e436e6ba652814b0a957a517feb492a98b8f9d3b6ba76d22301dcc",
+                "sha256:a34ba9e39f8269fd66ab4f7a802794ffea6d6ac500568ec05b327a862c21ce23",
+                "sha256:a49f85f0a099a5755d0a2cc6fc337e3cb945ad6390ec892332c691ab0a045882",
+                "sha256:a795829dc522227265d72b25d6ee6f6d41eb2105c15912c230097c8f5bfdbcdc",
+                "sha256:a89ca4105f8099de349d139d1090bad387fe2b208b717b288699ca26f179acbe",
+                "sha256:ac95101736239260189f426b1e361dc1b704513963357dc474beb0f39f5b7759",
+                "sha256:ae87ab669431f611c56e581679db33b9a467f87d7bf197ac384e71e4956b4456",
+                "sha256:b091dcfee169ad8de21b61eb2c3a75f9f0f859f851f64fdaf9320759a3244239",
+                "sha256:b511c6009d50d5c0dd0bab85ed25bc8ad6b6f5611de3a63a59786207e82824bb",
+                "sha256:b79dc2b2e313565416c1e62807c7c25c67a6ff0a0f8d83a318df464555b65948",
+                "sha256:bca14dfcfd9aae06d7d8d7e105539bd77d39d06caaae57a1ce945670bae744e0",
+                "sha256:c835c30f3af5c63a80917b72115e1defb83de99c73bc727bddd979a3b449e183",
+                "sha256:ccd721f1d4fc42b541b633d6e339018a08dd0290dc67269df79552843a06ca92",
+                "sha256:d6c2b1d78ceceb6741d703508cd0e9197b34f6bf6864dab30f940f8886e04ade",
+                "sha256:d6ec4ae13760ceda023b2e5ef1f9bc0b21e4b0830458db143794a117fdbdc044",
+                "sha256:d8b623fc429a38a881ab2d9a56ef30e8ea20c72a891c193f5ebbddc016e083ee",
+                "sha256:ea9753d64cba6f226947c318a923dadaf1e21cd8db02f71652405263daa1f033",
+                "sha256:ebbceefbffae118ab954d3cd6bf718f5790db66152f95202ebc231d58ad4e2c2",
+                "sha256:ecb6e7c45f9cd199c10ec35262b53b2247fb9a408803ed00ee5bb2b54aa626f5",
+                "sha256:ef9326c64349e2d718373415814e754183057ebc092261387a2c2f732d9172b2",
+                "sha256:f93a9d8804f4cec9da6c26c8cfae2c777028b4fdd9f49de0302e26e00bb86504",
+                "sha256:faf08b0341828f6a29b8f7dd94d5cf8cc7c39bfc3e67b78514c54b494b66915a"
             ],
             "index": "pypi",
-            "version": "==2021.8.3"
+            "version": "==2021.8.21"
         },
         "requests": {
             "hashes": [
@@ -1065,6 +1319,14 @@
             ],
             "version": "==1.5.0"
         },
+        "secretstorage": {
+            "hashes": [
+                "sha256:422d82c36172d88d6a0ed5afdec956514b189ddbfb72fefab0c8a1cee4eaf71f",
+                "sha256:fd666c51a6bf200643495a04abb261f83229dcb6fd8472ec393df7ffc8b6f195"
+            ],
+            "markers": "sys_platform == 'linux'",
+            "version": "==3.3.1"
+        },
         "setuptools-scm": {
             "hashes": [
                 "sha256:c3bd5f701c8def44a5c0bfe8d407bef3f80342217ef3492b951f3777bd2d915c",
@@ -1078,7 +1340,7 @@
                 "sha256:1e61c37477a1626458e36f7b1d82aa5c9b094fa4802892072e49de9c60c4c926",
                 "sha256:8abb2f1d86890a2dfb989f9a77cfcfd3e47c2a354b01111771326f8aa26e0254"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2'",
             "version": "==1.16.0"
         },
         "snowballstemmer": {
@@ -1173,7 +1435,7 @@
                 "sha256:806143ae5bfb6a3c6e736a764057db0e6a0e05e338b5630894a5f779cabb4f9b",
                 "sha256:b3bda1d108d5dd99f4a20d24d9c348e91c4db7ab1b749200bded2f839ccbe68f"
             ],
-            "markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2, 3.3'",
+            "markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2'",
             "version": "==0.10.2"
         },
         "tomli": {
@@ -1184,21 +1446,28 @@
             "index": "pypi",
             "version": "==1.2.1"
         },
+        "tox": {
+            "hashes": [
+                "sha256:9fbf8e2ab758b2a5e7cb2c72945e4728089934853076f67ef18d7575c8ab6b88",
+                "sha256:c6c4e77705ada004283610fd6d9ba4f77bc85d235447f875df9f0ba1bc23b634"
+            ],
+            "index": "pypi",
+            "version": "==3.24.3"
+        },
         "tqdm": {
             "hashes": [
-                "sha256:3642d483b558eec80d3c831e23953582c34d7e4540db86d9e5ed9dad238dabc6",
-                "sha256:706dea48ee05ba16e936ee91cb3791cd2ea6da348a0e50b46863ff4363ff4340"
+                "sha256:07856e19a1fe4d2d9621b539d3f072fa88c9c1ef1f3b7dd4d4953383134c3164",
+                "sha256:35540feeaca9ac40c304e916729e6b78045cbbeccd3e941b2868f09306798ac9"
             ],
             "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==4.62.0"
+            "version": "==4.62.1"
         },
         "traitlets": {
             "hashes": [
-                "sha256:178f4ce988f69189f7e523337a3e11d91c786ded9360174a3d9ca83e79bc5396",
-                "sha256:69ff3f9d5351f31a7ad80443c2674b7099df13cc41fc5fa6e2f6d3b0330b0426"
+                "sha256:70b4c6a1d9019d7b4f6846832288f86998aa3b9207c6821f3578a6a6a467fe44",
+                "sha256:d023ee369ddd2763310e4c3eae1ff649689440d4ae59d7485eb4cfbbe3e359f7"
             ],
-            "markers": "python_version >= '3.7'",
-            "version": "==5.0.5"
+            "version": "==4.3.3"
         },
         "twine": {
             "hashes": [
@@ -1208,6 +1477,42 @@
             "index": "pypi",
             "version": "==3.4.2"
         },
+        "typed-ast": {
+            "hashes": [
+                "sha256:07d49388d5bf7e863f7fa2f124b1b1d89d8aa0e2f7812faff0a5658c01c59aa1",
+                "sha256:14bf1522cdee369e8f5581238edac09150c765ec1cb33615855889cf33dcb92d",
+                "sha256:240296b27397e4e37874abb1df2a608a92df85cf3e2a04d0d4d61055c8305ba6",
+                "sha256:36d829b31ab67d6fcb30e185ec996e1f72b892255a745d3a82138c97d21ed1cd",
+                "sha256:37f48d46d733d57cc70fd5f30572d11ab8ed92da6e6b28e024e4a3edfb456e37",
+                "sha256:4c790331247081ea7c632a76d5b2a265e6d325ecd3179d06e9cf8d46d90dd151",
+                "sha256:5dcfc2e264bd8a1db8b11a892bd1647154ce03eeba94b461effe68790d8b8e07",
+                "sha256:7147e2a76c75f0f64c4319886e7639e490fee87c9d25cb1d4faef1d8cf83a440",
+                "sha256:7703620125e4fb79b64aa52427ec192822e9f45d37d4b6625ab37ef403e1df70",
+                "sha256:8368f83e93c7156ccd40e49a783a6a6850ca25b556c0fa0240ed0f659d2fe496",
+                "sha256:84aa6223d71012c68d577c83f4e7db50d11d6b1399a9c779046d75e24bed74ea",
+                "sha256:85f95aa97a35bdb2f2f7d10ec5bbdac0aeb9dafdaf88e17492da0504de2e6400",
+                "sha256:8db0e856712f79c45956da0c9a40ca4246abc3485ae0d7ecc86a20f5e4c09abc",
+                "sha256:9044ef2df88d7f33692ae3f18d3be63dec69c4fb1b5a4a9ac950f9b4ba571606",
+                "sha256:963c80b583b0661918718b095e02303d8078950b26cc00b5e5ea9ababe0de1fc",
+                "sha256:987f15737aba2ab5f3928c617ccf1ce412e2e321c77ab16ca5a293e7bbffd581",
+                "sha256:9ec45db0c766f196ae629e509f059ff05fc3148f9ffd28f3cfe75d4afb485412",
+                "sha256:9fc0b3cb5d1720e7141d103cf4819aea239f7d136acf9ee4a69b047b7986175a",
+                "sha256:a2c927c49f2029291fbabd673d51a2180038f8cd5a5b2f290f78c4516be48be2",
+                "sha256:a38878a223bdd37c9709d07cd357bb79f4c760b29210e14ad0fb395294583787",
+                "sha256:b4fcdcfa302538f70929eb7b392f536a237cbe2ed9cba88e3bf5027b39f5f77f",
+                "sha256:c0c74e5579af4b977c8b932f40a5464764b2f86681327410aa028a22d2f54937",
+                "sha256:c1c876fd795b36126f773db9cbb393f19808edd2637e00fd6caba0e25f2c7b64",
+                "sha256:c9aadc4924d4b5799112837b226160428524a9a45f830e0d0f184b19e4090487",
+                "sha256:cc7b98bf58167b7f2db91a4327da24fb93368838eb84a44c472283778fc2446b",
+                "sha256:cf54cfa843f297991b7388c281cb3855d911137223c6b6d2dd82a47ae5125a41",
+                "sha256:d003156bb6a59cda9050e983441b7fa2487f7800d76bdc065566b7d728b4581a",
+                "sha256:d175297e9533d8d37437abc14e8a83cbc68af93cc9c1c59c2c292ec59a0697a3",
+                "sha256:d746a437cdbca200622385305aedd9aef68e8a645e385cc483bdc5e488f07166",
+                "sha256:e683e409e5c45d5c9082dc1daf13f6374300806240719f95dc783d1fc942af10"
+            ],
+            "index": "pypi",
+            "version": "==1.4.2"
+        },
         "types-dataclasses": {
             "hashes": [
                 "sha256:248075d093d8f7c1541ce515594df7ae40233d1340afde11ce7125368c5209b8",
@@ -1245,11 +1550,11 @@
         },
         "virtualenv": {
             "hashes": [
-                "sha256:57bcb59c5898818bd555b1e0cfcf668bd6204bc2b53ad0e70a52413bd790f9e4",
-                "sha256:73863dc3be1efe6ee638e77495c0c195a6384ae7b15c561f3ceb2698ae7267c1"
+                "sha256:9ef4e8ee4710826e98ff3075c9a4739e2cb1040de6a2a8d35db0055840dc96a0",
+                "sha256:e4670891b3a03eb071748c569a87cceaefbf643c5bac46d996c5a45c34aa0f06"
             ],
             "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
-            "version": "==20.7.1"
+            "version": "==20.7.2"
         },
         "wcwidth": {
             "hashes": [
diff --git a/docs/requirements.txt b/docs/requirements.txt
index 56dbf3ffe13..4c5b700412a 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,6 +1,6 @@
 # Used by ReadTheDocs; pinned requirements for stability.
 
-MyST-Parser==0.14.0
-Sphinx==3.5.4
+myst-parser==0.15.1
+Sphinx==4.1.2
 sphinxcontrib-programoutput==0.17
-sphinx_copybutton==0.3.1
+sphinx_copybutton==0.4.0

From 0969ca4a46c4a2081be38f7e96a81a74b308c75f Mon Sep 17 00:00:00 2001
From: erykoff <erykoff@stanford.edu>
Date: Tue, 24 Aug 2021 13:59:24 -0700
Subject: [PATCH 0283/1034] Change sys.exit to raise ImportError (#2440)

The fix for #1688 in #1761 breaks help("modules") introspection and also leads
to unhappy results when inadvertently importing blackd from Python. Basically
the sys.exit(-1) causes the whole Python REPL to exit -- not great to suffice.

Commit history before merge:

* Change sys.exit to Raise.
* Add #2440 to changelog.
* Fix lint error from prettier
* Remove exception chain for more helpful user message.

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 CHANGES.md             | 4 ++++
 src/blackd/__init__.py | 9 +++------
 2 files changed, 7 insertions(+), 6 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 22ddc423e55..ed08ab3b9ad 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -10,6 +10,10 @@
 - The failsafe for accidentally added backslashes in f-string expressions has been
   hardened to handle more edge cases during quote normalization (#2437)
 
+### _Blackd_
+
+- Replace sys.exit(-1) with raise ImportError (#2440)
+
 ### Integrations
 
 - The provided pre-commit hooks no longer specify `language_version` to avoid overriding
diff --git a/src/blackd/__init__.py b/src/blackd/__init__.py
index 3e2a7e7c30f..5fdec152226 100644
--- a/src/blackd/__init__.py
+++ b/src/blackd/__init__.py
@@ -1,6 +1,5 @@
 import asyncio
 import logging
-import sys
 from concurrent.futures import Executor, ProcessPoolExecutor
 from datetime import datetime
 from functools import partial
@@ -11,13 +10,11 @@
     from aiohttp import web
     import aiohttp_cors
 except ImportError as ie:
-    print(
+    raise ImportError(
         f"aiohttp dependency is not installed: {ie}. "
         + "Please re-install black with the '[d]' extra install "
-        + "to obtain aiohttp_cors: `pip install black[d]`",
-        file=sys.stderr,
-    )
-    sys.exit(-1)
+        + "to obtain aiohttp_cors: `pip install black[d]`"
+    ) from None
 
 import black
 from black.concurrency import maybe_install_uvloop

From 5bb4da02c2c8c92d017e8b6be57eb442cc8f04ff Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Tue, 24 Aug 2021 14:29:49 -0700
Subject: [PATCH 0284/1034] Add cpython Lib/ repository config into primer
 config - Disabled (#2429)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Add CPython repository into primer runs

- CPython tests is probably the best repo for black to test on as the stdlib's unittests should use all syntax
  - Limit to running in recent versions of the python runtime - e.g. today >= 3.9
    - This allows us to parse more syntax
- Exclude all failing files for now
  - Definitely have bugs to explore there - Refer to #2407 for more details there
  - Some test files on purpose have syntax errors, so we will never be able to parse them
- Add new black command arguments logging in debug mode; very handy for seeing how CLI arguments are formatted

CPython now succeeds ignoring 16 files:
```
Oh no! 💥 💔 💥
1859 files would be reformatted, 148 files would be left unchanged.
```

Testing
- Ran locally with and without string processing - Very little runtime difference BUT 3 more failed files
```
time /tmp/tb/bin/black --experimental-string-processing --check . 2>&1 | tee /tmp/black_cpython_esp
...
Oh no! 💥 💔 💥
1859 files would be reformatted, 148 files would be left unchanged, 16 files would fail to reformat.

real	4m8.563s
user	16m21.735s
sys	0m6.000s
```
- Add unittest for new covienence config file flattening that allows long arguments to be broke up into an array/list of strings

Addresses #2407

---

Commit history before merge:

* Add new `timeout_seconds` support into primer.json
- If present, will set forked process limit to that value in seconds
- Otherwise, stay with default 10 minutes (600 seconds)

* Add new "base_path" concept to black-primer
- Rather than start at the repo root start at a configured path within the repository
  - e.g. for cpython only run black on `Lib`

* Disable by default - It's too much for GitHub Actions. But let's leave config for others to use
* Minor tweak to _flatten_cli_args

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 src/black_primer/lib.py      | 42 ++++++++++++++++++++++++++++++++----
 src/black_primer/primer.json | 33 +++++++++++++++++++++++++++-
 tests/test_primer.py         |  7 ++++++
 3 files changed, 77 insertions(+), 5 deletions(-)

diff --git a/src/black_primer/lib.py b/src/black_primer/lib.py
index 784134bf652..7494ae6dc7d 100644
--- a/src/black_primer/lib.py
+++ b/src/black_primer/lib.py
@@ -12,12 +12,23 @@
 from subprocess import CalledProcessError
 from sys import version_info
 from tempfile import TemporaryDirectory
-from typing import Any, Callable, Dict, NamedTuple, Optional, Sequence, Tuple
+from typing import (
+    Any,
+    Callable,
+    Dict,
+    List,
+    NamedTuple,
+    Optional,
+    Sequence,
+    Tuple,
+    Union,
+)
 from urllib.parse import urlparse
 
 import click
 
 
+TEN_MINUTES_SECONDS = 600
 WINDOWS = system() == "Windows"
 BLACK_BINARY = "black.exe" if WINDOWS else "black"
 GIT_BINARY = "git.exe" if WINDOWS else "git"
@@ -39,7 +50,7 @@ class Results(NamedTuple):
 
 async def _gen_check_output(
     cmd: Sequence[str],
-    timeout: float = 600,
+    timeout: float = TEN_MINUTES_SECONDS,
     env: Optional[Dict[str, str]] = None,
     cwd: Optional[Path] = None,
     stdin: Optional[bytes] = None,
@@ -113,6 +124,21 @@ def analyze_results(project_count: int, results: Results) -> int:
     return results.stats["failed"]
 
 
+def _flatten_cli_args(cli_args: List[Union[Sequence[str], str]]) -> List[str]:
+    """Allow a user to put long arguments into a list of strs
+    to make the JSON human readable"""
+    flat_args = []
+    for arg in cli_args:
+        if isinstance(arg, str):
+            flat_args.append(arg)
+            continue
+
+        args_as_str = "".join(arg)
+        flat_args.append(args_as_str)
+
+    return flat_args
+
+
 async def black_run(
     project_name: str,
     repo_path: Optional[Path],
@@ -131,7 +157,7 @@ async def black_run(
     stdin_test = project_name.upper() == "STDIN"
     cmd = [str(which(BLACK_BINARY))]
     if "cli_arguments" in project_config and project_config["cli_arguments"]:
-        cmd.extend(project_config["cli_arguments"])
+        cmd.extend(_flatten_cli_args(project_config["cli_arguments"]))
     cmd.append("--check")
     if not no_diff:
         cmd.append("--diff")
@@ -141,9 +167,16 @@ async def black_run(
     if stdin_test:
         cmd.append("-")
         stdin = repo_path.read_bytes()
+    elif "base_path" in project_config:
+        cmd.append(project_config["base_path"])
     else:
         cmd.append(".")
 
+    timeout = (
+        project_config["timeout_seconds"]
+        if "timeout_seconds" in project_config
+        else TEN_MINUTES_SECONDS
+    )
     with TemporaryDirectory() as tmp_path:
         # Prevent reading top-level user configs by manipulating environment variables
         env = {
@@ -154,8 +187,9 @@ async def black_run(
 
         cwd_path = repo_path.parent if stdin_test else repo_path
         try:
+            LOG.debug(f"Running black for {project_name}: {' '.join(cmd)}")
             _stdout, _stderr = await _gen_check_output(
-                cmd, cwd=cwd_path, env=env, stdin=stdin
+                cmd, cwd=cwd_path, env=env, stdin=stdin, timeout=timeout
             )
         except asyncio.TimeoutError:
             results.stats["failed"] += 1
diff --git a/src/black_primer/primer.json b/src/black_primer/primer.json
index edbed3f33dd..0d1018fc50e 100644
--- a/src/black_primer/primer.json
+++ b/src/black_primer/primer.json
@@ -1,5 +1,5 @@
 {
-  "configuration_format_version": 20200509,
+  "configuration_format_version": 20210815,
   "projects": {
     "STDIN": {
       "cli_arguments": ["--experimental-string-processing"],
@@ -36,6 +36,37 @@
       "long_checkout": false,
       "py_versions": ["all"]
     },
+    "cpython": {
+      "disabled": true,
+      "disabled_reason": "To big / slow for GitHub Actions but handy to keep config to use manually or in some other CI in the future",
+      "base_path": "Lib",
+      "cli_arguments": [
+        "--experimental-string-processing",
+        "--extend-exclude",
+        [
+          "Lib/lib2to3/tests/data/different_encoding.py",
+          "|Lib/lib2to3/tests/data/false_encoding.py",
+          "|Lib/lib2to3/tests/data/py2_test_grammar.py",
+          "|Lib/test/bad_coding.py",
+          "|Lib/test/bad_coding2.py",
+          "|Lib/test/badsyntax_3131.py",
+          "|Lib/test/badsyntax_pep3120.py",
+          "|Lib/test/test_base64.py",
+          "|Lib/test/test_exceptions.py",
+          "|Lib/test/test_grammar.py",
+          "|Lib/test/test_named_expressions.py",
+          "|Lib/test/test_patma.py",
+          "|Lib/test/test_tokenize.py",
+          "|Lib/test/test_xml_etree.py",
+          "|Lib/traceback.py"
+        ]
+      ],
+      "expect_formatting_changes": true,
+      "git_clone_url": "https://github.com/python/cpython.git",
+      "long_checkout": false,
+      "py_versions": ["3.9", "3.10"],
+      "timeout_seconds": 900
+    },
     "django": {
       "cli_arguments": [
         "--experimental-string-processing",
diff --git a/tests/test_primer.py b/tests/test_primer.py
index 8dd1212313e..e7f99fdb0c2 100644
--- a/tests/test_primer.py
+++ b/tests/test_primer.py
@@ -146,6 +146,11 @@ def test_black_run(self) -> None:
             )
         self.assertEqual(2, results.stats["failed"])
 
+    def test_flatten_cli_args(self) -> None:
+        fake_long_args = ["--arg", ["really/", "|long", "|regex", "|splitup"], "--done"]
+        expected = ["--arg", "really/|long|regex|splitup", "--done"]
+        self.assertEqual(expected, lib._flatten_cli_args(fake_long_args))
+
     @event_loop()
     def test_gen_check_output(self) -> None:
         loop = asyncio.get_event_loop()
@@ -184,6 +189,8 @@ def test_git_checkout_or_rebase(self) -> None:
     @patch("sys.stdout", new_callable=StringIO)
     @event_loop()
     def test_process_queue(self, mock_stdout: Mock) -> None:
+        """Test the process queue on primer itself
+        - If you have non black conforming formatting in primer itself this can fail"""
         loop = asyncio.get_event_loop()
         config_path = Path(lib.__file__).parent / "primer.json"
         with patch("black_primer.lib.git_checkout_or_rebase", return_false):

From d249f2d8380893f051b63140e3768cef599f49f3 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Wed, 25 Aug 2021 21:25:44 -0400
Subject: [PATCH 0285/1034] MNT: add pull request template (#2443)

So we don't have to request changes on these basic requirements as
often - hopefully :)
---
 .github/PULL_REQUEST_TEMPLATE.md | 36 ++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)
 create mode 100644 .github/PULL_REQUEST_TEMPLATE.md

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 00000000000..36f98c527f4
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,36 @@
+<!-- Hello! Thanks for submitting a PR. To help make things go a bit more
+     smoothly we would appreciate that you go through this template. -->
+
+### Description
+
+<!-- Good things to put here include: reasoning for the change (please link
+     any relevant issues!), any noteworthy (or hacky) choices to be aware of,
+     or what the problem resolved here looked like ... we won't mind a ranty
+     story :) -->
+
+### Checklist - did you ...
+
+<!-- If any of the following items aren't relevant for your contribution
+     please still tick them so we know you've gone through the checklist.
+
+    All user-facing changes should get an entry. Otherwise, signal to us
+    this should get the magical label to silence the CHANGELOG entry check.
+    Tests are required for bugfixes and new features. Documentation changes
+    are necessary for formatting and most enhancement changes. -->
+
+- [] Add a CHANGELOG entry if necessary?
+- [] Add / update tests if necessary?
+- [] Add new / update outdated documentation?
+
+<!-- Just as a reminder, everyone in all psf/black spaces including PRs
+     must follow the PSF Code of Conduct (link below).
+
+     Finally, once again thanks for your time and effort. If you have any
+     feedback in regards to your experience contributing here, please
+     let us know!
+
+     Helpful links:
+
+      PSF COC: https://www.python.org/psf/conduct/
+      Contributing docs: https://black.readthedocs.io/en/latest/contributing/index.html
+      Chat on Python Discord: https://discord.gg/RtVdv86PrH -->

From 8a59528c2d8ae1ef5f366039c728614aaf1a470b Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Wed, 25 Aug 2021 21:32:27 -0400
Subject: [PATCH 0286/1034] Stop changing return type annotations to tuples
 (#2384)

This fixes a bug where a trailing comma would be added to a
parenthesized return annotation changing its type to a tuple.
Here's one case where this bug shows up:

```
def spam() -> (
    this_is_a_long_type_annotation_which_should_NOT_get_a_trailing_comma
):
    pass
```

The root problem was that the type annotation was treated as if it was
a parameter & import list (is_body=True to linegen::bracket_split_build_line)
where a trailing comma is usually fine. Now there's another check in the
aforementioned function to make sure the body it's operating on isn't
a return annotation before truly adding a trailing comma.
---
 CHANGES.md                            |  2 +
 src/black/linegen.py                  | 16 ++++++-
 src/black/nodes.py                    |  2 +
 tests/data/function_trailing_comma.py | 64 ++++++++++++++++++++++++++-
 4 files changed, 82 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index ed08ab3b9ad..47e64cfa274 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -9,6 +9,8 @@
 - Present a more user-friendly error if .gitignore is invalid (#2414)
 - The failsafe for accidentally added backslashes in f-string expressions has been
   hardened to handle more edge cases during quote normalization (#2437)
+- Avoid changing a function return type annotation's type to a tuple by adding a
+  trailing comma (#2384)
 
 ### _Blackd_
 
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 76b553a959a..fafaf1032ca 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -7,7 +7,7 @@
 
 from dataclasses import dataclass, field
 
-from black.nodes import WHITESPACE, STATEMENT, STANDALONE_COMMENT
+from black.nodes import WHITESPACE, RARROW, STATEMENT, STANDALONE_COMMENT
 from black.nodes import ASSIGNMENTS, OPENING_BRACKETS, CLOSING_BRACKETS
 from black.nodes import Visitor, syms, first_child_is_arith, ensure_visible
 from black.nodes import is_docstring, is_empty_tuple, is_one_tuple, is_one_tuple_between
@@ -574,6 +574,20 @@ def bracket_split_build_line(
                 original.is_def
                 and opening_bracket.value == "("
                 and not any(leaf.type == token.COMMA for leaf in leaves)
+                # In particular, don't add one within a parenthesized return annotation.
+                # Unfortunately the indicator we're in a return annotation (RARROW) may
+                # be defined directly in the parent node, the parent of the parent ...
+                # and so on depending on how complex the return annotation is.
+                # This isn't perfect and there's some false negatives but they are in
+                # contexts were a comma is actually fine.
+                and not any(
+                    node.prev_sibling.type == RARROW
+                    for node in (
+                        leaves[0].parent,
+                        getattr(leaves[0].parent, "parent", None),
+                    )
+                    if isinstance(node, Node) and isinstance(node.prev_sibling, Leaf)
+                )
             )
 
             if original.is_import or no_commas:
diff --git a/src/black/nodes.py b/src/black/nodes.py
index e0db9a42426..8f2e15b2cc3 100644
--- a/src/black/nodes.py
+++ b/src/black/nodes.py
@@ -135,6 +135,8 @@
 BRACKETS = OPENING_BRACKETS | CLOSING_BRACKETS
 ALWAYS_NO_SPACE = CLOSING_BRACKETS | {token.COMMA, STANDALONE_COMMENT}
 
+RARROW = 55
+
 
 class Visitor(Generic[T]):
     """Basic lib2to3 visitor that yields things of type `T` on `visit()`."""
diff --git a/tests/data/function_trailing_comma.py b/tests/data/function_trailing_comma.py
index d15459cbeb5..02078219e82 100644
--- a/tests/data/function_trailing_comma.py
+++ b/tests/data/function_trailing_comma.py
@@ -21,6 +21,34 @@ def xxxxxxxxxxxxxxxxxxxxxxxxxxxx() -> Set[
 ]:
     json = {"k": {"k2": {"k3": [1,]}}}
 
+
+
+# The type annotation shouldn't get a trailing comma since that would change its type.
+# Relevant bug report: https://github.com/psf/black/issues/2381.
+def some_function_with_a_really_long_name() -> (
+    returning_a_deeply_nested_import_of_a_type_i_suppose
+):
+    pass
+
+
+def some_method_with_a_really_long_name(very_long_parameter_so_yeah: str, another_long_parameter: int) -> (
+    another_case_of_returning_a_deeply_nested_import_of_a_type_i_suppose_cause_why_not
+):
+    pass
+
+
+def func() -> (
+    also_super_long_type_annotation_that_may_cause_an_AST_related_crash_in_black(this_shouldn_t_get_a_trailing_comma_too)
+):
+    pass
+
+
+def func() -> ((also_super_long_type_annotation_that_may_cause_an_AST_related_crash_in_black(
+        this_shouldn_t_get_a_trailing_comma_too
+    ))
+):
+    pass
+
 # output
 
 def f(
@@ -85,4 +113,38 @@ def xxxxxxxxxxxxxxxxxxxxxxxxxxxx() -> Set[
                 ]
             }
         }
-    }
\ No newline at end of file
+    }
+
+
+# The type annotation shouldn't get a trailing comma since that would change its type.
+# Relevant bug report: https://github.com/psf/black/issues/2381.
+def some_function_with_a_really_long_name() -> (
+    returning_a_deeply_nested_import_of_a_type_i_suppose
+):
+    pass
+
+
+def some_method_with_a_really_long_name(
+    very_long_parameter_so_yeah: str, another_long_parameter: int
+) -> (
+    another_case_of_returning_a_deeply_nested_import_of_a_type_i_suppose_cause_why_not
+):
+    pass
+
+
+def func() -> (
+    also_super_long_type_annotation_that_may_cause_an_AST_related_crash_in_black(
+        this_shouldn_t_get_a_trailing_comma_too
+    )
+):
+    pass
+
+
+def func() -> (
+    (
+        also_super_long_type_annotation_that_may_cause_an_AST_related_crash_in_black(
+            this_shouldn_t_get_a_trailing_comma_too
+        )
+    )
+):
+    pass

From 366a0806eb4edd94d4d20cc6912333586bdc9fa7 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Thu, 26 Aug 2021 16:59:01 -0400
Subject: [PATCH 0287/1034] blib2to3: support unparenthesized wulruses in more
 places (#2447)

Implementation stolen from PR davidhalter/parso#162. Thanks parso!

I could add support for these newer syntactical constructs in the
target version detection logic, but until I get diff-shades up
and running I don't feel very comfortable adding the code.
---
 CHANGES.md                  | 2 ++
 src/blib2to3/Grammar.txt    | 6 +++---
 src/blib2to3/README         | 7 ++++++-
 tests/data/pep_572_py310.py | 4 ++++
 tests/data/pep_572_py39.py  | 7 +++++++
 tests/test_black.py         | 9 +++++++++
 6 files changed, 31 insertions(+), 4 deletions(-)
 create mode 100644 tests/data/pep_572_py310.py
 create mode 100644 tests/data/pep_572_py39.py

diff --git a/CHANGES.md b/CHANGES.md
index 47e64cfa274..d28d766f4c0 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -11,6 +11,8 @@
   hardened to handle more edge cases during quote normalization (#2437)
 - Avoid changing a function return type annotation's type to a tuple by adding a
   trailing comma (#2384)
+- Parsing support has been added for unparenthesized walruses in set literals, set
+  comprehensions, and indices (#2447).
 
 ### _Blackd_
 
diff --git a/src/blib2to3/Grammar.txt b/src/blib2to3/Grammar.txt
index 69b9af96608..ac8a067378d 100644
--- a/src/blib2to3/Grammar.txt
+++ b/src/blib2to3/Grammar.txt
@@ -157,14 +157,14 @@ testlist_gexp: (namedexpr_test|star_expr) ( old_comp_for | (',' (namedexpr_test|
 lambdef: 'lambda' [varargslist] ':' test
 trailer: '(' [arglist] ')' | '[' subscriptlist ']' | '.' NAME
 subscriptlist: subscript (',' subscript)* [',']
-subscript: test | [test] ':' [test] [sliceop]
+subscript: test [':=' test] | [test] ':' [test] [sliceop]
 sliceop: ':' [test]
 exprlist: (expr|star_expr) (',' (expr|star_expr))* [',']
 testlist: test (',' test)* [',']
 dictsetmaker: ( ((test ':' test | '**' expr)
                  (comp_for | (',' (test ':' test | '**' expr))* [','])) |
-                ((test | star_expr)
-		 (comp_for | (',' (test | star_expr))* [','])) )
+                ((test [':=' test] | star_expr)
+		 (comp_for | (',' (test [':=' test] | star_expr))* [','])) )
 
 classdef: 'class' NAME ['(' [arglist] ')'] ':' suite
 
diff --git a/src/blib2to3/README b/src/blib2to3/README
index a43f15cb37d..ccad28337b6 100644
--- a/src/blib2to3/README
+++ b/src/blib2to3/README
@@ -13,4 +13,9 @@ Reasons for forking:
 - ability to Cythonize
 
 Change Log:
-- Changes default logger used by Driver
\ No newline at end of file
+- Changes default logger used by Driver
+- Backported the following upstream parser changes:
+  - "bpo-42381: Allow walrus in set literals and set comprehensions (GH-23332)"
+    https://github.com/python/cpython/commit/cae60187cf7a7b26281d012e1952fafe4e2e97e9
+  - "bpo-42316: Allow unparenthesized walrus operator in indexes (GH-23317)"
+    https://github.com/python/cpython/commit/b0aba1fcdc3da952698d99aec2334faa79a8b68c
diff --git a/tests/data/pep_572_py310.py b/tests/data/pep_572_py310.py
new file mode 100644
index 00000000000..2aef589ce8d
--- /dev/null
+++ b/tests/data/pep_572_py310.py
@@ -0,0 +1,4 @@
+# Unparenthesized walruses are now allowed in indices since Python 3.10.
+x[a:=0]
+x[a:=0, b:=1]
+x[5, b:=0]
diff --git a/tests/data/pep_572_py39.py b/tests/data/pep_572_py39.py
new file mode 100644
index 00000000000..7bbd5091197
--- /dev/null
+++ b/tests/data/pep_572_py39.py
@@ -0,0 +1,7 @@
+# Unparenthesized walruses are now allowed in set literals & set comprehensions
+# since Python 3.9
+{x := 1, 2, 3}
+{x4 := x ** 5 for x in range(7)}
+# We better not remove the parentheses here (since it's a 3.10 feature)
+x[(a := 1)]
+x[(a := 1), (b := 3)]
diff --git a/tests/test_black.py b/tests/test_black.py
index 5c720507216..8a37f7c65b4 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -26,6 +26,7 @@
 import pytest
 import unittest
 from unittest.mock import patch, MagicMock
+from parameterized import parameterized
 
 import click
 from click import unstyle
@@ -299,6 +300,14 @@ def test_pep_572_version_detection(self) -> None:
         versions = black.detect_target_versions(root)
         self.assertIn(black.TargetVersion.PY38, versions)
 
+    @parameterized.expand([(3, 9), (3, 10)])
+    def test_pep_572_newer_syntax(self, major: int, minor: int) -> None:
+        source, expected = read_data(f"pep_572_py{major}{minor}")
+        actual = fs(source, mode=DEFAULT_MODE)
+        self.assertFormatEqual(expected, actual)
+        if sys.version_info >= (major, minor):
+            black.assert_equivalent(source, actual)
+
     def test_expression_ff(self) -> None:
         source, expected = read_data("expression")
         tmp_file = Path(black.dump_to_file(source))

From 8b0680533420c2ea367860fcbb08df99317a6b44 Mon Sep 17 00:00:00 2001
From: Marco Edward Gorelli <marcogorelli@protonmail.com>
Date: Fri, 27 Aug 2021 21:21:08 +0100
Subject: [PATCH 0288/1034] Document jupyter hook (#2416)

This also introduces a script so we can reference the latest version in
the example pre-commit configuration in the docs without forgetting to
update it when doing a release!

Commit history before merge:

* document jupyter hook
* note minimum version
* add check for pre-commit version
* use git tag
* curl api during ci
* parse version from changes file
* fixup script
* rename variables
* Tweak the docs & magical script
* fix couple of typos
* pin additional dependencies in hook
* Add types-PyYAML to lockfile

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 .pre-commit-config.yaml                     |  9 ++++
 Pipfile                                     |  1 +
 Pipfile.lock                                | 24 +++++++--
 docs/faq.md                                 |  2 +-
 docs/integrations/source_version_control.md | 15 +++++-
 scripts/__init__.py                         |  0
 scripts/check_pre_commit_rev_in_example.py  | 54 +++++++++++++++++++++
 src/black/__init__.py                       |  2 +-
 8 files changed, 100 insertions(+), 7 deletions(-)
 create mode 100644 scripts/__init__.py
 create mode 100644 scripts/check_pre_commit_rev_in_example.py

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 5ae418d9bdd..b3cbe352e38 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -12,6 +12,14 @@ repos:
         require_serial: true
         types_or: [python, pyi]
 
+      - id: check-pre-commit-rev-in-example
+        name: Check pre-commit rev in example
+        language: python
+        entry: python -m scripts.check_pre_commit_rev_in_example
+        files: '(CHANGES\.md|source_version_control\.md)$'
+        additional_dependencies:
+          ["commonmark==0.9.1", "pyyaml==5.4.1", "beautifulsoup4==4.9.3"]
+
   - repo: https://gitlab.com/pycqa/flake8
     rev: 3.9.2
     hooks:
@@ -25,6 +33,7 @@ repos:
         exclude: ^docs/conf.py
         additional_dependencies:
           - types-dataclasses >= 0.1.3
+          - types-PyYAML
           - tomli >= 0.2.6, < 2.0.0
           - types-typed-ast >= 1.4.1
           - click >= 8.0.0
diff --git a/Pipfile b/Pipfile
index 7f386c5381f..824beda16cc 100644
--- a/Pipfile
+++ b/Pipfile
@@ -21,6 +21,7 @@ flake8-bugbear = "*"
 mypy = ">=0.910"
 types-dataclasses = ">=0.1.3"
 types-typed-ast = ">=1.4.1"
+types-PyYAML = ">=5.4.1"
 
 # Documentation related requirements.
 Sphinx = ">=4.1.2"
diff --git a/Pipfile.lock b/Pipfile.lock
index 6d62ec76680..30a4defcca3 100644
--- a/Pipfile.lock
+++ b/Pipfile.lock
@@ -1,7 +1,7 @@
 {
     "_meta": {
         "hash": {
-            "sha256": "ac07cc9a5cb19ea72381baf4ba0db1689f475538d37e4be3119fc958a722b062"
+            "sha256": "ebf216584cfb2c962a1792d0682f3c08b44c7ae27305a03a54eacd6f42df27db"
         },
         "pipfile-spec": 6,
         "requires": {},
@@ -901,6 +901,14 @@
             "markers": "python_version >= '3.6'",
             "version": "==2.0.1"
         },
+        "matplotlib-inline": {
+            "hashes": [
+                "sha256:5cf1176f554abb4fa98cb362aa2b55c500147e4bdbb07e3fda359143e1da0811",
+                "sha256:f41d5ff73c9f5385775d5c0bc13b424535c8402fe70ea8210f93e11f3683993e"
+            ],
+            "markers": "python_version >= '3.5'",
+            "version": "==0.1.2"
+        },
         "mccabe": {
             "hashes": [
                 "sha256:ab8a6258860da4b6677da4bd2fe5dc2c659cff31b3ee4f7f5d64e79735b80d42",
@@ -1149,7 +1157,7 @@
                 "sha256:c203ec8783bf771a155b207279b9bccb8dea02d8f0c9e5f8ead507bc3246ecc1",
                 "sha256:ef9d7589ef3c200abe66653d3f1ab1033c3c419ae9b9bdb1240a85b024efc88b"
             ],
-            "markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2'",
+            "markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==2.4.7"
         },
         "pytest": {
@@ -1340,7 +1348,7 @@
                 "sha256:1e61c37477a1626458e36f7b1d82aa5c9b094fa4802892072e49de9c60c4c926",
                 "sha256:8abb2f1d86890a2dfb989f9a77cfcfd3e47c2a354b01111771326f8aa26e0254"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2'",
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==1.16.0"
         },
         "snowballstemmer": {
@@ -1435,7 +1443,7 @@
                 "sha256:806143ae5bfb6a3c6e736a764057db0e6a0e05e338b5630894a5f779cabb4f9b",
                 "sha256:b3bda1d108d5dd99f4a20d24d9c348e91c4db7ab1b749200bded2f839ccbe68f"
             ],
-            "markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2'",
+            "markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==0.10.2"
         },
         "tomli": {
@@ -1521,6 +1529,14 @@
             "index": "pypi",
             "version": "==0.1.7"
         },
+        "types-pyyaml": {
+            "hashes": [
+                "sha256:745dcb4b1522423026bcc83abb9925fba747f1e8602d902f71a4058f9e7fb662",
+                "sha256:96f8d3d96aa1a18a465e8f6a220e02cff2f52632314845a364ecbacb0aea6e30"
+            ],
+            "index": "pypi",
+            "version": "==5.4.6"
+        },
         "types-typed-ast": {
             "hashes": [
                 "sha256:b7f561796b4d002c7522b0020f58b18f715bd28a31429d424a78e2e2dbbd6785",
diff --git a/docs/faq.md b/docs/faq.md
index d7e6a16351f..c361addf7ae 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -57,7 +57,7 @@ following will not be formatted:
   get_ipython().system('ls')
   ```
 
-- invalid syntax, as it can't be safely distinguished from automagics in the absense of
+- invalid syntax, as it can't be safely distinguished from automagics in the absence of
   a running `IPython` kernel.
 
 ## Why are Flake8's E203 and W503 violated?
diff --git a/docs/integrations/source_version_control.md b/docs/integrations/source_version_control.md
index 1ca6161bf0b..e1482487aa4 100644
--- a/docs/integrations/source_version_control.md
+++ b/docs/integrations/source_version_control.md
@@ -7,8 +7,21 @@ Use [pre-commit](https://pre-commit.com/). Once you
 ```yaml
 repos:
   - repo: https://github.com/psf/black
-    rev: stable # Replace by any tag/version: https://github.com/psf/black/tags
+    rev: 21.7b0
     hooks:
       - id: black
         language_version: python3 # Should be a command that runs python3.6+
 ```
+
+Feel free to switch out the `rev` value to something else, like another
+[tag/version][black-tags] or even a specific commit. Although we discourage the use of
+branches or other mutable refs since the hook [won't auto update as you may
+expect][pre-commit-mutable-rev].
+
+If you want support for Jupyter Notebooks as well, then replace `id: black` with
+`id: black-jupyter` (though note that it's only available from version `21.8b0`
+onwards).
+
+[black-tags]: https://github.com/psf/black/tags
+[pre-commit-mutable-rev]:
+  https://pre-commit.com/#using-the-latest-version-for-a-repository
diff --git a/scripts/__init__.py b/scripts/__init__.py
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/scripts/check_pre_commit_rev_in_example.py b/scripts/check_pre_commit_rev_in_example.py
new file mode 100644
index 00000000000..9560b3b8401
--- /dev/null
+++ b/scripts/check_pre_commit_rev_in_example.py
@@ -0,0 +1,54 @@
+"""
+Check that the rev value in the example pre-commit configuration matches
+the latest version of Black. This saves us from forgetting to update that
+during the release process.
+
+Why can't we just use `rev: stable` and call it a day? Well pre-commit
+won't auto update the hook as you may expect (and for good reasons, some
+technical and some pragmatic). Encouraging bad practice is also just
+not ideal. xref: https://github.com/psf/black/issues/420
+"""
+
+import os
+import sys
+
+import commonmark
+import yaml
+from bs4 import BeautifulSoup
+
+
+def main(changes: str, source_version_control: str) -> None:
+    changes_html = commonmark.commonmark(changes)
+    changes_soup = BeautifulSoup(changes_html, "html.parser")
+    headers = changes_soup.find_all("h2")
+    latest_tag, *_ = [
+        header.string for header in headers if header.string != "Unreleased"
+    ]
+
+    source_version_control_html = commonmark.commonmark(source_version_control)
+    source_version_control_soup = BeautifulSoup(
+        source_version_control_html, "html.parser"
+    )
+    pre_commit_repos = yaml.safe_load(
+        source_version_control_soup.find(class_="language-yaml").string
+    )["repos"]
+
+    for repo in pre_commit_repos:
+        pre_commit_rev = repo["rev"]
+        if not pre_commit_rev == latest_tag:
+            print(
+                "Please set the rev in ``source_version_control.md`` to be the latest "
+                f"one.\nExpected {latest_tag}, got {pre_commit_rev}.\n"
+            )
+            sys.exit(1)
+
+
+if __name__ == "__main__":
+    with open("CHANGES.md", encoding="utf-8") as fd:
+        changes = fd.read()
+    with open(
+        os.path.join("docs", "integrations", "source_version_control.md"),
+        encoding="utf-8",
+    ) as fd:
+        source_version_control = fd.read()
+    main(changes, source_version_control)
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 60f4fa34e9d..d033e01141a 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -977,7 +977,7 @@ def format_ipynb_string(src_contents: str, *, fast: bool, mode: Mode) -> FileCon
     """Format Jupyter notebook.
 
     Operate cell-by-cell, only on code cells, only for Python notebooks.
-    If the ``.ipynb`` originally had a trailing newline, it'll be preseved.
+    If the ``.ipynb`` originally had a trailing newline, it'll be preserved.
     """
     trailing_newline = src_contents[-1] == "\n"
     modified = False

From fcfead919b352e9530de4c198ae03f424c80e3ca Mon Sep 17 00:00:00 2001
From: Marco Edward Gorelli <marcogorelli@protonmail.com>
Date: Sat, 28 Aug 2021 14:55:34 +0100
Subject: [PATCH 0289/1034] set mypy_path in mypy.ini (#2455)

---
 mypy.ini | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/mypy.ini b/mypy.ini
index ae7be5e5106..7e563e6f696 100644
--- a/mypy.ini
+++ b/mypy.ini
@@ -5,6 +5,8 @@
 python_version=3.6
 platform=linux
 
+mypy_path=src
+
 show_column_numbers=True
 
 # show error messages from unrelated files

From 7a093f0303c3fa7fee0b6742b7c6a3ff03438ace Mon Sep 17 00:00:00 2001
From: Marco Edward Gorelli <marcogorelli@protonmail.com>
Date: Sat, 28 Aug 2021 16:27:55 +0100
Subject: [PATCH 0290/1034] add test which covers stdin filename ipynb (#2454)

---
 tests/test_black.py | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/tests/test_black.py b/tests/test_black.py
index 8a37f7c65b4..398a528bee9 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -1639,6 +1639,30 @@ def test_reformat_one_with_stdin_filename_pyi(self) -> None:
             # __BLACK_STDIN_FILENAME__ should have been stripped
             report.done.assert_called_with(expected, black.Changed.YES)
 
+    def test_reformat_one_with_stdin_filename_ipynb(self) -> None:
+        with patch(
+            "black.format_stdin_to_stdout",
+            return_value=lambda *args, **kwargs: black.Changed.YES,
+        ) as fsts:
+            report = MagicMock()
+            p = "foo.ipynb"
+            path = Path(f"__BLACK_STDIN_FILENAME__{p}")
+            expected = Path(p)
+            black.reformat_one(
+                path,
+                fast=True,
+                write_back=black.WriteBack.YES,
+                mode=DEFAULT_MODE,
+                report=report,
+            )
+            fsts.assert_called_once_with(
+                fast=True,
+                write_back=black.WriteBack.YES,
+                mode=replace(DEFAULT_MODE, is_ipynb=True),
+            )
+            # __BLACK_STDIN_FILENAME__ should have been stripped
+            report.done.assert_called_with(expected, black.Changed.YES)
+
     def test_reformat_one_with_stdin_and_existing_path(self) -> None:
         with patch(
             "black.format_stdin_to_stdout",

From a5bb6e0a320bf42f1b219ee2e55ea1c1917961dc Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Sat, 28 Aug 2021 15:37:53 -0400
Subject: [PATCH 0291/1034] Pin setuptools-scm build time dependency (#2457)

The setuptools-scm dependency in setup.cfg did not have a version
specified, leading to the issues described in #2449 after a faulty release
of setuptools-scm was published. To avoid this issue in the future, the
last version before that faulty update is now pinned.

Commit history before merge:

* Pin setuptools-scm dependency version (#2449)
* Update CHANGES.md
* Let's pin in pyproject.toml too

Mostly since it's non-build-backend specific configuration and more
widely standardized file. Not sure what benefits pinning in setup.cfg
gives us on top of pyproject.toml but I'd rather not find out during
the release that is supposed to happen today :wink:

Co-authored-by: FiNs <24248249+FabianNiehaus@users.noreply.github.com>
---
 CHANGES.md     | 1 +
 pyproject.toml | 5 ++++-
 setup.cfg      | 3 ++-
 3 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index d28d766f4c0..6c542f446e7 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -13,6 +13,7 @@
   trailing comma (#2384)
 - Parsing support has been added for unparenthesized walruses in set literals, set
   comprehensions, and indices (#2447).
+- Pin `setuptools-scm` build-time dependency version (#2457)
 
 ### _Blackd_
 
diff --git a/pyproject.toml b/pyproject.toml
index d085c0ddc62..30e62974475 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -23,7 +23,10 @@ extend-exclude = '''
 # NOTE: You don't need this in your own Black configuration.
 
 [build-system]
-requires = ["setuptools>=41.0", "setuptools-scm", "wheel"]
+# We're pinning setuptools-scm to bugfix versions only because for build-time
+# deps having them work on install by default is really important. Especially
+# since it's hard for users to work-around the specified build requirements.
+requires = ["setuptools>=41.0", "setuptools_scm~=6.0.1", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [tool.pytest.ini_options]
diff --git a/setup.cfg b/setup.cfg
index 55c66add7fb..dbd667e8f19 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -1,2 +1,3 @@
 [options]
-setup_requires = setuptools_scm
+setup_requires =
+  setuptools_scm~=6.0.1

From 16275d24e3c2ad88d953d67e7d8795fd7f73f7cb Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Sun, 29 Aug 2021 14:56:22 -0400
Subject: [PATCH 0292/1034] Prepare CHANGES.md for release 21.8b0 (#2458)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Hopefully my first release doesn't end up in flames 🔥

Commit history before merge:

* Prepare CHANGES.md for release 21.8b0
* I need to add a check for this too.
---
 CHANGES.md                                  | 5 +++--
 docs/integrations/source_version_control.md | 2 +-
 docs/usage_and_configuration/the_basics.md  | 4 ++--
 3 files changed, 6 insertions(+), 5 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 6c542f446e7..6e2721ba19c 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,6 +1,6 @@
 # Change Log
 
-## Unreleased
+## 21.8b0
 
 ### _Black_
 
@@ -17,7 +17,8 @@
 
 ### _Blackd_
 
-- Replace sys.exit(-1) with raise ImportError (#2440)
+- Replace sys.exit(-1) with raise ImportError as it plays more nicely with tools that
+  scan installed packages (#2440)
 
 ### Integrations
 
diff --git a/docs/integrations/source_version_control.md b/docs/integrations/source_version_control.md
index e1482487aa4..220f429eb20 100644
--- a/docs/integrations/source_version_control.md
+++ b/docs/integrations/source_version_control.md
@@ -7,7 +7,7 @@ Use [pre-commit](https://pre-commit.com/). Once you
 ```yaml
 repos:
   - repo: https://github.com/psf/black
-    rev: 21.7b0
+    rev: 21.8b0
     hooks:
       - id: black
         language_version: python3 # Should be a command that runs python3.6+
diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index 474ad669cd1..4b68ad7b76b 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -173,13 +173,13 @@ You can check the version of _Black_ you have installed using the `--version` fl
 
 ```console
 $ black --version
-black, version 21.5b0
+black, version 21.8b0
 ```
 
 An option to require a specific version to be running is also provided.
 
 ```console
-$ black --required-version 21.5b2 -c "format = 'this'"
+$ black --required-version 21.8b0 -c "format = 'this'"
 format = "this"
 $ black --required-version 31.5b2 -c "still = 'beta?!'"
 Oh no! 💥 💔 💥 The required version does not match the running version!

From a8b4665e7d6eb945c47820adb1a3f8b006adce0c Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Sun, 29 Aug 2021 17:04:49 -0400
Subject: [PATCH 0293/1034] Exclude broken typing-extensions version + fix
 import (#2460)

re. import, the ipynb code was assuming that typing-extensions would
always be available, but that's not the case! There's an environment
marker on the requirement meaning it won't get installed on 3.10 or
higher. The test suite didn't catch this issue since aiohttp pulls in
typing-extensions unconditionally.
---
 CHANGES.md                       |  2 ++
 setup.py                         |  5 ++++-
 src/black/handle_ipynb_magics.py | 12 ++++++++----
 3 files changed, 14 insertions(+), 5 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 6e2721ba19c..576e3c84882 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -14,6 +14,8 @@
 - Parsing support has been added for unparenthesized walruses in set literals, set
   comprehensions, and indices (#2447).
 - Pin `setuptools-scm` build-time dependency version (#2457)
+- Exclude typing-extensions version 3.10.0.1 due to it being broken on Python 3.10
+  (#2460)
 
 ### _Blackd_
 
diff --git a/setup.py b/setup.py
index 215fa6cff61..929096a2098 100644
--- a/setup.py
+++ b/setup.py
@@ -79,7 +79,10 @@ def get_long_description() -> str:
         "regex>=2020.1.8",
         "pathspec>=0.9.0, <1",
         "dataclasses>=0.6; python_version < '3.7'",
-        "typing_extensions>=3.10.0.0; python_version < '3.10'",
+        "typing_extensions>=3.10.0.0",
+        # 3.10.0.1 is broken on at least Python 3.10,
+        # https://github.com/python/typing/issues/865
+        "typing_extensions!=3.10.0.1; python_version >= '3.10'",
         "mypy_extensions>=0.4.3",
     ],
     extras_require={
diff --git a/src/black/handle_ipynb_magics.py b/src/black/handle_ipynb_magics.py
index ad93c444efc..b18f8629136 100644
--- a/src/black/handle_ipynb_magics.py
+++ b/src/black/handle_ipynb_magics.py
@@ -1,15 +1,19 @@
 """Functions to process IPython magics with."""
+
 from functools import lru_cache
 import dataclasses
 import ast
-from typing import Dict
+from typing import Dict, List, Tuple, Optional
 
 import secrets
-from typing import List, Tuple
+import sys
 import collections
 
-from typing import Optional
-from typing_extensions import TypeGuard
+if sys.version_info >= (3, 10):
+    from typing import TypeGuard
+else:
+    from typing_extensions import TypeGuard
+
 from black.report import NothingChanged
 from black.output import out
 

From 79575f3376f043186d8b8c4885ef51c6b3c36246 Mon Sep 17 00:00:00 2001
From: aru <genericusername414@gmail.com>
Date: Mon, 30 Aug 2021 13:26:21 -0400
Subject: [PATCH 0294/1034] fix: run pypi / docker upload from published draft
 releases (#2461)

Draft releases don't trigger the workflows (that's good!) but since they only

Commit history before merge:

* fix: run pypi upload from published draft releases
* Fix broken task list markup in PR template
* change docker workflow to build on release publish

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 .github/PULL_REQUEST_TEMPLATE.md  | 6 +++---
 .github/workflows/docker.yml      | 2 +-
 .github/workflows/pypi_upload.yml | 2 +-
 3 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 36f98c527f4..833cd164134 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -18,9 +18,9 @@
     Tests are required for bugfixes and new features. Documentation changes
     are necessary for formatting and most enhancement changes. -->
 
-- [] Add a CHANGELOG entry if necessary?
-- [] Add / update tests if necessary?
-- [] Add new / update outdated documentation?
+- [ ] Add a CHANGELOG entry if necessary?
+- [ ] Add / update tests if necessary?
+- [ ] Add new / update outdated documentation?
 
 <!-- Just as a reminder, everyone in all psf/black spaces including PRs
      must follow the PSF Code of Conduct (link below).
diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
index 4bb41a17906..1686c561f50 100644
--- a/.github/workflows/docker.yml
+++ b/.github/workflows/docker.yml
@@ -5,7 +5,7 @@ on:
     branches:
       - "main"
   release:
-    types: created
+    types: [published]
 
 jobs:
   docker:
diff --git a/.github/workflows/pypi_upload.yml b/.github/workflows/pypi_upload.yml
index 5df91d92165..201d94fd85e 100644
--- a/.github/workflows/pypi_upload.yml
+++ b/.github/workflows/pypi_upload.yml
@@ -2,7 +2,7 @@ name: pypi_upload
 
 on:
   release:
-    types: created
+    types: [published]
 
 jobs:
   build:

From 77d11bb4b4911c91ea97dd43047cf6021d173c65 Mon Sep 17 00:00:00 2001
From: pszlazak <pszlazak@users.noreply.github.com>
Date: Tue, 31 Aug 2021 20:26:31 +0200
Subject: [PATCH 0295/1034] Change docker workflow for latest_release tag
 (#2468)

---
 .github/workflows/docker.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
index 1686c561f50..0825385c6c0 100644
--- a/.github/workflows/docker.yml
+++ b/.github/workflows/docker.yml
@@ -41,7 +41,7 @@ jobs:
           tags: pyfound/black:latest,pyfound/black:${{ env.GIT_TAG }}
 
       - name: Build and push latest_release tag
-        if: ${{ github.event_name == 'release' && github.event.action == 'created' }}
+        if: ${{ github.event_name == 'release' && github.event.action == 'published' }}
         uses: docker/build-push-action@v2
         with:
           context: .

From 72de89f54e744a8b3bbc9d3ea71f78a67d8ba82e Mon Sep 17 00:00:00 2001
From: Jameel Al-Aziz <247849+jalaziz@users.noreply.github.com>
Date: Wed, 1 Sep 2021 15:05:11 -0700
Subject: [PATCH 0296/1034] Add hidden import to PyInstaller build (GH-2466)

Add new platformdirs dependencies as hidden imports when creating
PyInstaller-based binaries.

platformdirs imports the module for each platform dynamically, which
PyInstaller is unable to correctly detect for packing. By adding the
modules as hidden imports, we are telling PyInstaller to include the
modules in the packaged binary.

This issue seems to have been introduce when switching to platformdirs
in #2375. fixes #2464

Commit history before merge:

* Add hidden import to PyInstaller build

Add new platformdirs dependency as a hidden import when creating
PyInstaller based binaries.

* Only include the platformdirs for the relevant os
---
 .github/workflows/upload_binary.yml | 9 +++++++--
 CHANGES.md                          | 6 ++++++
 2 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/upload_binary.yml b/.github/workflows/upload_binary.yml
index 766f37cc321..8f44d4ec27b 100644
--- a/.github/workflows/upload_binary.yml
+++ b/.github/workflows/upload_binary.yml
@@ -16,14 +16,17 @@ jobs:
             pathsep: ";"
             asset_name: black_windows.exe
             executable_mime: "application/vnd.microsoft.portable-executable"
+            platform: windows
           - os: ubuntu-20.04
             pathsep: ":"
             asset_name: black_linux
             executable_mime: "application/x-executable"
+            platform: unix
           - os: macos-latest
             pathsep: ":"
             asset_name: black_macos
             executable_mime: "application/x-mach-binary"
+            platform: macos
 
     steps:
       - uses: actions/checkout@v2
@@ -40,8 +43,10 @@ jobs:
           python -m pip install pyinstaller
 
       - name: Build binary
-        run: |
-          python -m PyInstaller -F --name ${{ matrix.asset_name }} --add-data 'src/blib2to3${{ matrix.pathsep }}blib2to3' src/black/__main__.py
+        run: >
+          python -m PyInstaller -F --name ${{ matrix.asset_name }} --add-data
+          'src/blib2to3${{ matrix.pathsep }}blib2to3' --hidden-import platformdirs.${{
+          matrix.platform }} src/black/__main__.py
 
       - name: Upload binary as release asset
         uses: actions/upload-release-asset@v1
diff --git a/CHANGES.md b/CHANGES.md
index 576e3c84882..ef0a57d6142 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,5 +1,11 @@
 # Change Log
 
+## Unreleased
+
+### Packaging
+
+- Fix missing modules in self-contained binaries (#2466)
+
 ## 21.8b0
 
 ### _Black_

From 8b0c7bcfda60e2200ce1335b5b371593548ab9f8 Mon Sep 17 00:00:00 2001
From: Marco Edward Gorelli <marcogorelli@protonmail.com>
Date: Sun, 5 Sep 2021 15:52:16 +0100
Subject: [PATCH 0297/1034] Remove `blackcellmagic` reference (#2477)

This package seems to be unmaintained (last commit is from > 2 years ago), and `black` now runs on Jupyter Notebooks directly
---
 docs/integrations/editors.md | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/docs/integrations/editors.md b/docs/integrations/editors.md
index b1ca84e42fc..6098631e2a0 100644
--- a/docs/integrations/editors.md
+++ b/docs/integrations/editors.md
@@ -291,10 +291,6 @@ Use the
 
 Use [sublack plugin](https://github.com/jgirardet/sublack).
 
-## Jupyter Notebook Magic
-
-Use [blackcellmagic](https://github.com/csurfer/blackcellmagic).
-
 ## Python LSP Server
 
 If your editor supports the [Language Server Protocol](https://langserver.org/) (Atom,

From 41e670064063e3e221b1c3c40db5aaae784b5231 Mon Sep 17 00:00:00 2001
From: Sorin Sbarnea <sorin.sbarnea@gmail.com>
Date: Mon, 6 Sep 2021 22:10:39 +0100
Subject: [PATCH 0298/1034] Fix missing toml extra w/ setuptools-scm (GH-2475)

Project packaging is using TOML due to pyproject.toml but fails to
mention it, causing installation failures with newer setuptools-scm 6.3.0.

Commit history before merge:

* Fix missing toml extra

Fixed breakage uncovered by setuptools-scm 6.3.0 where installation
would fail for project that missed to mention the toml extra.

* Bump setuptools[-scm] to avoid toml extra

https://github.com/psf/black/pull/2475#issuecomment-912730714

> If you constraint greater than 6.3.0 and setuptools greater than 45
> you can skip the extra,

* Actually for safety reasons, just use the extra

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 CHANGES.md     | 1 +
 pyproject.toml | 5 +----
 setup.cfg      | 2 +-
 3 files changed, 3 insertions(+), 5 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index ef0a57d6142..4b5a291c7b9 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -5,6 +5,7 @@
 ### Packaging
 
 - Fix missing modules in self-contained binaries (#2466)
+- Fix missing toml extra used during installation (#2475)
 
 ## 21.8b0
 
diff --git a/pyproject.toml b/pyproject.toml
index 30e62974475..73e19608108 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -23,10 +23,7 @@ extend-exclude = '''
 # NOTE: You don't need this in your own Black configuration.
 
 [build-system]
-# We're pinning setuptools-scm to bugfix versions only because for build-time
-# deps having them work on install by default is really important. Especially
-# since it's hard for users to work-around the specified build requirements.
-requires = ["setuptools>=41.0", "setuptools_scm~=6.0.1", "wheel"]
+requires = ["setuptools>=45.0", "setuptools_scm[toml]>=6.3.1", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [tool.pytest.ini_options]
diff --git a/setup.cfg b/setup.cfg
index dbd667e8f19..1a0a217eb91 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -1,3 +1,3 @@
 [options]
 setup_requires =
-  setuptools_scm~=6.0.1
+  setuptools_scm[toml]>=6.3.1

From 911470a610e47d9da5ea938b0887c3df62819b85 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Mon, 13 Sep 2021 19:23:11 -0700
Subject: [PATCH 0299/1034] Update CHANGES.md for 21.9b0 release (#2494)

---
 CHANGES.md                                  | 2 +-
 docs/integrations/source_version_control.md | 2 +-
 docs/usage_and_configuration/the_basics.md  | 4 ++--
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 4b5a291c7b9..6ff488ba74e 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,6 +1,6 @@
 # Change Log
 
-## Unreleased
+## 21.9b0
 
 ### Packaging
 
diff --git a/docs/integrations/source_version_control.md b/docs/integrations/source_version_control.md
index 220f429eb20..b07796fda0b 100644
--- a/docs/integrations/source_version_control.md
+++ b/docs/integrations/source_version_control.md
@@ -7,7 +7,7 @@ Use [pre-commit](https://pre-commit.com/). Once you
 ```yaml
 repos:
   - repo: https://github.com/psf/black
-    rev: 21.8b0
+    rev: 21.9b0
     hooks:
       - id: black
         language_version: python3 # Should be a command that runs python3.6+
diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index 4b68ad7b76b..49268b44f7c 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -173,13 +173,13 @@ You can check the version of _Black_ you have installed using the `--version` fl
 
 ```console
 $ black --version
-black, version 21.8b0
+black, version 21.9b0
 ```
 
 An option to require a specific version to be running is also provided.
 
 ```console
-$ black --required-version 21.8b0 -c "format = 'this'"
+$ black --required-version 21.9b0 -c "format = 'this'"
 format = "this"
 $ black --required-version 31.5b2 -c "still = 'beta?!'"
 Oh no! 💥 💔 💥 The required version does not match the running version!

From 22747a6937d53e38397e96c4ed5ed0571db31f71 Mon Sep 17 00:00:00 2001
From: Zsolt Dollenstein <zsol.zsol@gmail.com>
Date: Sat, 18 Sep 2021 22:18:06 +0100
Subject: [PATCH 0300/1034] fix all b904s (#2501)

---
 src/black/__init__.py  | 19 ++++++++++---------
 src/black/linegen.py   | 10 +++++-----
 src/blackd/__init__.py |  2 +-
 3 files changed, 16 insertions(+), 15 deletions(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index d033e01141a..7fed1355f47 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -114,7 +114,7 @@ def read_pyproject_toml(
     except (OSError, ValueError) as e:
         raise click.FileError(
             filename=value, hint=f"Error reading configuration file: {e}"
-        )
+        ) from None
 
     if not config:
         return None
@@ -172,7 +172,7 @@ def validate_regex(
     try:
         return re_compile_maybe_verbose(value) if value is not None else None
     except re.error:
-        raise click.BadParameter("Not a valid regular expression")
+        raise click.BadParameter("Not a valid regular expression") from None
 
 
 @click.command(context_settings=dict(help_option_names=["-h", "--help"]))
@@ -777,7 +777,9 @@ def format_file_in_place(
     except NothingChanged:
         return False
     except JSONDecodeError:
-        raise ValueError(f"File '{src}' cannot be parsed as valid Jupyter notebook.")
+        raise ValueError(
+            f"File '{src}' cannot be parsed as valid Jupyter notebook."
+        ) from None
 
     if write_back == WriteBack.YES:
         with open(src, "w", encoding=encoding, newline=newline) as f:
@@ -947,7 +949,7 @@ def format_cell(src: str, *, fast: bool, mode: Mode) -> str:
     try:
         masked_src, replacements = mask_cell(src_without_trailing_semicolon)
     except SyntaxError:
-        raise NothingChanged
+        raise NothingChanged from None
     masked_dst = format_str(masked_src, mode=mode)
     if not fast:
         check_stability_and_equivalence(masked_src, masked_dst, mode=mode)
@@ -957,7 +959,7 @@ def format_cell(src: str, *, fast: bool, mode: Mode) -> str:
     )
     dst = dst.rstrip("\n")
     if dst == src:
-        raise NothingChanged
+        raise NothingChanged from None
     return dst
 
 
@@ -970,7 +972,7 @@ def validate_metadata(nb: MutableMapping[str, Any]) -> None:
     """
     language = nb.get("metadata", {}).get("language_info", {}).get("name", None)
     if language is not None and language != "python":
-        raise NothingChanged
+        raise NothingChanged from None
 
 
 def format_ipynb_string(src_contents: str, *, fast: bool, mode: Mode) -> FileContent:
@@ -1202,9 +1204,8 @@ def assert_equivalent(src: str, dst: str, *, pass_num: int = 1) -> None:
         src_ast = parse_ast(src)
     except Exception as exc:
         raise AssertionError(
-            "cannot use --safe with this file; failed to parse source file.  AST"
-            f" error message: {exc}"
-        )
+            "cannot use --safe with this file; failed to parse source file."
+        ) from exc
 
     try:
         dst_ast = parse_ast(dst)
diff --git a/src/black/linegen.py b/src/black/linegen.py
index fafaf1032ca..eb53fa0ac56 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -503,14 +503,14 @@ def right_hand_split(
             yield from right_hand_split(line, line_length, features=features, omit=omit)
             return
 
-        except CannotSplit:
+        except CannotSplit as e:
             if not (
                 can_be_split(body)
                 or is_line_short_enough(body, line_length=line_length)
             ):
                 raise CannotSplit(
                     "Splitting failed, body is still too long and can't be split."
-                )
+                ) from e
 
             elif head.contains_multiline_strings() or tail.contains_multiline_strings():
                 raise CannotSplit(
@@ -518,7 +518,7 @@ def right_hand_split(
                     " satisfy the splitting algorithm because the head or the tail"
                     " contains multiline strings which by definition never fit one"
                     " line."
-                )
+                ) from e
 
     ensure_visible(opening_bracket)
     ensure_visible(closing_bracket)
@@ -635,13 +635,13 @@ def delimiter_split(line: Line, features: Collection[Feature] = ()) -> Iterator[
     try:
         last_leaf = line.leaves[-1]
     except IndexError:
-        raise CannotSplit("Line empty")
+        raise CannotSplit("Line empty") from None
 
     bt = line.bracket_tracker
     try:
         delimiter_priority = bt.max_delimiter_priority(exclude={id(last_leaf)})
     except ValueError:
-        raise CannotSplit("No delimiters found")
+        raise CannotSplit("No delimiters found") from None
 
     if delimiter_priority == DOT_PRIORITY:
         if bt.delimiter_count_with_priority(delimiter_priority) == 1:
diff --git a/src/blackd/__init__.py b/src/blackd/__init__.py
index 5fdec152226..d062303fd10 100644
--- a/src/blackd/__init__.py
+++ b/src/blackd/__init__.py
@@ -195,7 +195,7 @@ def parse_python_variant_header(value: str) -> Tuple[bool, Set[black.TargetVersi
                     raise InvalidVariantHeader(f"3.{minor} is not supported")
                 versions.add(black.TargetVersion[version_str])
             except (KeyError, ValueError):
-                raise InvalidVariantHeader("expected e.g. '3.7', 'py3.5'")
+                raise InvalidVariantHeader("expected e.g. '3.7', 'py3.5'") from None
         return False, versions
 
 

From 0540591e256c6121ee0bac970024501fcdcb8c0c Mon Sep 17 00:00:00 2001
From: Marco Edward Gorelli <marcogorelli@protonmail.com>
Date: Sun, 19 Sep 2021 04:24:09 +0100
Subject: [PATCH 0301/1034] add check for version in the-basics example (#2459)

---
 .pre-commit-config.yaml                    | 13 +++++-
 scripts/check_version_in_basics_example.py | 47 ++++++++++++++++++++++
 2 files changed, 59 insertions(+), 1 deletion(-)
 create mode 100644 scripts/check_version_in_basics_example.py

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index b3cbe352e38..a3cd6639384 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -18,7 +18,18 @@ repos:
         entry: python -m scripts.check_pre_commit_rev_in_example
         files: '(CHANGES\.md|source_version_control\.md)$'
         additional_dependencies:
-          ["commonmark==0.9.1", "pyyaml==5.4.1", "beautifulsoup4==4.9.3"]
+          &version_check_dependencies [
+            commonmark==0.9.1,
+            pyyaml==5.4.1,
+            beautifulsoup4==4.9.3,
+          ]
+
+      - id: check-version-in-the-basics-example
+        name: Check black version in the basics example
+        language: python
+        entry: python -m scripts.check_version_in_basics_example
+        files: '(CHANGES\.md|the_basics\.md)$'
+        additional_dependencies: *version_check_dependencies
 
   - repo: https://gitlab.com/pycqa/flake8
     rev: 3.9.2
diff --git a/scripts/check_version_in_basics_example.py b/scripts/check_version_in_basics_example.py
new file mode 100644
index 00000000000..c62780d97ab
--- /dev/null
+++ b/scripts/check_version_in_basics_example.py
@@ -0,0 +1,47 @@
+"""
+Check that the rev value in the example from ``the_basics.md`` matches
+the latest version of Black. This saves us from forgetting to update that
+during the release process.
+"""
+
+import os
+import sys
+
+import commonmark
+from bs4 import BeautifulSoup
+
+
+def main(changes: str, the_basics: str) -> None:
+    changes_html = commonmark.commonmark(changes)
+    changes_soup = BeautifulSoup(changes_html, "html.parser")
+    headers = changes_soup.find_all("h2")
+    tags = [header.string for header in headers if header.string != "Unreleased"]
+    latest_tag = tags[0]
+
+    the_basics_html = commonmark.commonmark(the_basics)
+    the_basics_soup = BeautifulSoup(the_basics_html, "html.parser")
+    (version_example,) = [
+        code_block.string
+        for code_block in the_basics_soup.find_all(class_="language-console")
+        if "$ black --version" in code_block.string
+    ]
+
+    for tag in tags:
+        if tag in version_example and tag != latest_tag:
+            print(
+                "Please set the version in the ``black --version`` "
+                "example from ``the_basics.md`` to be the latest one.\n"
+                f"Expected {latest_tag}, got {tag}.\n"
+            )
+            sys.exit(1)
+
+
+if __name__ == "__main__":
+    with open("CHANGES.md", encoding="utf-8") as fd:
+        changes = fd.read()
+    with open(
+        os.path.join("docs", "usage_and_configuration", "the_basics.md"),
+        encoding="utf-8",
+    ) as fd:
+        the_basics = fd.read()
+    main(changes, the_basics)

From 37861b4ce264f16754f4459d19522a05844daf9f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Cl=C3=A9ment=20Robert?= <cr52@protonmail.com>
Date: Sun, 19 Sep 2021 11:15:39 +0200
Subject: [PATCH 0302/1034] DOC: cleanup pre-commit instructions following
 #2430 (#2481)

---
 docs/integrations/source_version_control.md | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/docs/integrations/source_version_control.md b/docs/integrations/source_version_control.md
index b07796fda0b..6a1aa363d2b 100644
--- a/docs/integrations/source_version_control.md
+++ b/docs/integrations/source_version_control.md
@@ -10,7 +10,11 @@ repos:
     rev: 21.9b0
     hooks:
       - id: black
-        language_version: python3 # Should be a command that runs python3.6+
+        # It is recommended to specify the latest version of Python
+        # supported by your project here, or alternatively use
+        # pre-commit's default_language_version, see
+        # https://pre-commit.com/#top_level-default_language_version
+        language_version: python3.9
 ```
 
 Feel free to switch out the `rev` value to something else, like another

From 7b153936587e17b9db992a2d8c8b6cfba3ef7209 Mon Sep 17 00:00:00 2001
From: Deepyaman Datta <deepyaman.datta@utexas.edu>
Date: Thu, 23 Sep 2021 22:20:48 -0400
Subject: [PATCH 0303/1034] Add Kedro to project list and QuantumBlack to orgs
 (#2502)

---
 README.md | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 709478e1d58..7bf0ed8d16f 100644
--- a/README.md
+++ b/README.md
@@ -134,10 +134,11 @@ code in compliance with many other _Black_ formatted projects.
 The following notable open-source projects trust _Black_ with enforcing a consistent
 code style: pytest, tox, Pyramid, Django Channels, Hypothesis, attrs, SQLAlchemy,
 Poetry, PyPA applications (Warehouse, Bandersnatch, Pipenv, virtualenv), pandas, Pillow,
-Twisted, LocalStack, every Datadog Agent Integration, Home Assistant, Zulip, and many
-more.
+Twisted, LocalStack, every Datadog Agent Integration, Home Assistant, Zulip, Kedro, and
+many more.
 
-The following organizations use _Black_: Facebook, Dropbox, Mozilla, Quora, Duolingo.
+The following organizations use _Black_: Facebook, Dropbox, Mozilla, Quora, Duolingo,
+QuantumBlack.
 
 Are we missing anyone? Let us know.
 

From a5381ba7648f7308145c78c248e29118e18dc530 Mon Sep 17 00:00:00 2001
From: Zsolt Dollenstein <zsol.zsol@gmail.com>
Date: Sat, 25 Sep 2021 12:58:44 +0100
Subject: [PATCH 0304/1034] re-implement simple CORS middleware for blackd
 (#2500)

* re-implement simple CORS middleware for blackd
* remove aiohttp-cors from setup.py
* Remove aiohttp-cors from Pipfile.lock

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 CHANGES.md                |  6 ++++++
 Pipfile                   |  1 -
 Pipfile.lock              | 42 ++++++++++++++++++++++-----------------
 setup.py                  |  2 +-
 src/blackd/__init__.py    | 19 +++++-------------
 src/blackd/middlewares.py | 34 +++++++++++++++++++++++++++++++
 tests/test_blackd.py      | 21 ++++++++++++++++++++
 7 files changed, 91 insertions(+), 34 deletions(-)
 create mode 100644 src/blackd/middlewares.py

diff --git a/CHANGES.md b/CHANGES.md
index 6ff488ba74e..2a9b649d25c 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,5 +1,11 @@
 # Change Log
 
+## Unreleased
+
+### _Blackd_
+
+- Remove dependency on aiohttp-cors (#2500)
+
 ## 21.9b0
 
 ### Packaging
diff --git a/Pipfile b/Pipfile
index 824beda16cc..66ded8b8570 100644
--- a/Pipfile
+++ b/Pipfile
@@ -41,7 +41,6 @@ black = {editable = true, extras = ["d", "jupyter"], path = "."}
 
 [packages]
 aiohttp = ">=3.6.0"
-aiohttp-cors = ">=0.4.0"
 platformdirs= ">=2"
 click = ">=8.0.0"
 mypy_extensions = ">=0.4.3"
diff --git a/Pipfile.lock b/Pipfile.lock
index 30a4defcca3..0cbe9011981 100644
--- a/Pipfile.lock
+++ b/Pipfile.lock
@@ -1,7 +1,7 @@
 {
     "_meta": {
         "hash": {
-            "sha256": "ebf216584cfb2c962a1792d0682f3c08b44c7ae27305a03a54eacd6f42df27db"
+            "sha256": "8b28e41c5a63f0c30361d2a0ed29dc1e3f0468223ef150ae68586839e2ccf1c9"
         },
         "pipfile-spec": 6,
         "requires": {},
@@ -57,14 +57,6 @@
             "index": "pypi",
             "version": "==3.7.4.post0"
         },
-        "aiohttp-cors": {
-            "hashes": [
-                "sha256:0451ba59fdf6909d0e2cd21e4c0a43752bc0703d33fc78ae94d9d9321710193e",
-                "sha256:4d39c6d7100fd9764ed1caf8cebf0eb01bf5e3f24e2e073fda6234bc48b19f5d"
-            ],
-            "index": "pypi",
-            "version": "==0.7.0"
-        },
         "async-timeout": {
             "hashes": [
                 "sha256:0c3c816a028d47f659d6ff5c745cb2acf1f966da1fe5c19c77a70282b25f4c5f",
@@ -188,6 +180,14 @@
             "index": "pypi",
             "version": "==0.4.3"
         },
+        "packaging": {
+            "hashes": [
+                "sha256:7dc96269f53a4ccec5c0670940a4281106dd0bb343f47b7471f779df49c2fbe7",
+                "sha256:c86254f9220d55e31cc94d69bade760f0847da8000def4dfe1c6b872fd14ff14"
+            ],
+            "markers": "python_version >= '3.6'",
+            "version": "==21.0"
+        },
         "pathspec": {
             "hashes": [
                 "sha256:7d15c4ddb0b5c802d161efc417ec1a2558ea2653c2e8ad9c19098201dc1c993a",
@@ -204,6 +204,14 @@
             "index": "pypi",
             "version": "==2.2.0"
         },
+        "pyparsing": {
+            "hashes": [
+                "sha256:c203ec8783bf771a155b207279b9bccb8dea02d8f0c9e5f8ead507bc3246ecc1",
+                "sha256:ef9d7589ef3c200abe66653d3f1ab1033c3c419ae9b9bdb1240a85b024efc88b"
+            ],
+            "markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2, 3.3'",
+            "version": "==2.4.7"
+        },
         "regex": {
             "hashes": [
                 "sha256:03840a07a402576b8e3a6261f17eb88abd653ad4e18ec46ef10c9a63f8c99ebd",
@@ -252,6 +260,9 @@
             "version": "==2021.8.21"
         },
         "setuptools-scm": {
+            "extras": [
+                "toml"
+            ],
             "hashes": [
                 "sha256:c3bd5f701c8def44a5c0bfe8d407bef3f80342217ef3492b951f3777bd2d915c",
                 "sha256:d1925a69cb07e9b29416a275b9fadb009a23c148ace905b2fb220649a6c18e92"
@@ -410,14 +421,6 @@
             "index": "pypi",
             "version": "==3.7.4.post0"
         },
-        "aiohttp-cors": {
-            "hashes": [
-                "sha256:0451ba59fdf6909d0e2cd21e4c0a43752bc0703d33fc78ae94d9d9321710193e",
-                "sha256:4d39c6d7100fd9764ed1caf8cebf0eb01bf5e3f24e2e073fda6234bc48b19f5d"
-            ],
-            "index": "pypi",
-            "version": "==0.7.0"
-        },
         "alabaster": {
             "hashes": [
                 "sha256:446438bdcca0e05bd45ea2de1668c1d9b032e1a9154c2c259092d77031ddd359",
@@ -769,7 +772,7 @@
                 "sha256:2480d8e07d1890056cb53c96e3de44fead9c62f2ba949b0f2e4c4345f4afa977",
                 "sha256:a65882a4d0fe5fbf702273456ba2ce74fe44892c25e42e057aca526b702a6d4b"
             ],
-            "markers": "python_version < '3.7' and python_version < '3.7'",
+            "markers": "python_version < '3.7'",
             "version": "==5.2.2"
         },
         "iniconfig": {
@@ -1336,6 +1339,9 @@
             "version": "==3.3.1"
         },
         "setuptools-scm": {
+            "extras": [
+                "toml"
+            ],
             "hashes": [
                 "sha256:c3bd5f701c8def44a5c0bfe8d407bef3f80342217ef3492b951f3777bd2d915c",
                 "sha256:d1925a69cb07e9b29416a275b9fadb009a23c148ace905b2fb220649a6c18e92"
diff --git a/setup.py b/setup.py
index 929096a2098..19df9beb24e 100644
--- a/setup.py
+++ b/setup.py
@@ -86,7 +86,7 @@ def get_long_description() -> str:
         "mypy_extensions>=0.4.3",
     ],
     extras_require={
-        "d": ["aiohttp>=3.6.0", "aiohttp-cors>=0.4.0"],
+        "d": ["aiohttp>=3.6.0"],
         "colorama": ["colorama>=0.4.3"],
         "python2": ["typed-ast>=1.4.2"],
         "uvloop": ["uvloop>=0.15.2"],
diff --git a/src/blackd/__init__.py b/src/blackd/__init__.py
index d062303fd10..cc966404a74 100644
--- a/src/blackd/__init__.py
+++ b/src/blackd/__init__.py
@@ -8,7 +8,7 @@
 
 try:
     from aiohttp import web
-    import aiohttp_cors
+    from .middlewares import cors
 except ImportError as ie:
     raise ImportError(
         f"aiohttp dependency is not installed: {ie}. "
@@ -67,20 +67,11 @@ def main(bind_host: str, bind_port: int) -> None:
 
 
 def make_app() -> web.Application:
-    app = web.Application()
-    executor = ProcessPoolExecutor()
-
-    cors = aiohttp_cors.setup(app)
-    resource = cors.add(app.router.add_resource("/"))
-    cors.add(
-        resource.add_route("POST", partial(handle, executor=executor)),
-        {
-            "*": aiohttp_cors.ResourceOptions(
-                allow_headers=(*BLACK_HEADERS, "Content-Type"), expose_headers="*"
-            )
-        },
+    app = web.Application(
+        middlewares=[cors(allow_headers=(*BLACK_HEADERS, "Content-Type"))]
     )
-
+    executor = ProcessPoolExecutor()
+    app.add_routes([web.post("/", partial(handle, executor=executor))])
     return app
 
 
diff --git a/src/blackd/middlewares.py b/src/blackd/middlewares.py
new file mode 100644
index 00000000000..97994ecc1df
--- /dev/null
+++ b/src/blackd/middlewares.py
@@ -0,0 +1,34 @@
+from typing import Iterable, Awaitable, Callable
+from aiohttp.web_response import StreamResponse
+from aiohttp.web_request import Request
+from aiohttp.web_middlewares import middleware
+
+Handler = Callable[[Request], Awaitable[StreamResponse]]
+Middleware = Callable[[Request, Handler], Awaitable[StreamResponse]]
+
+
+def cors(allow_headers: Iterable[str]) -> Middleware:
+    @middleware
+    async def impl(request: Request, handler: Handler) -> StreamResponse:
+        is_options = request.method == "OPTIONS"
+        is_preflight = is_options and "Access-Control-Request-Method" in request.headers
+        if is_preflight:
+            resp = StreamResponse()
+        else:
+            resp = await handler(request)
+
+        origin = request.headers.get("Origin")
+        if not origin:
+            return resp
+
+        resp.headers["Access-Control-Allow-Origin"] = "*"
+        resp.headers["Access-Control-Expose-Headers"] = "*"
+        if is_options:
+            resp.headers["Access-Control-Allow-Headers"] = ", ".join(allow_headers)
+            resp.headers["Access-Control-Allow-Methods"] = ", ".join(
+                ("OPTIONS", "POST")
+            )
+
+        return resp
+
+    return impl  # type: ignore
diff --git a/tests/test_blackd.py b/tests/test_blackd.py
index 9ca19d49dc6..cc750b40567 100644
--- a/tests/test_blackd.py
+++ b/tests/test_blackd.py
@@ -164,3 +164,24 @@ async def test_blackd_invalid_line_length(self) -> None:
     async def test_blackd_response_black_version_header(self) -> None:
         response = await self.client.post("/")
         self.assertIsNotNone(response.headers.get(blackd.BLACK_VERSION_HEADER))
+
+    @unittest_run_loop
+    async def test_cors_preflight(self) -> None:
+        response = await self.client.options(
+            "/",
+            headers={
+                "Access-Control-Request-Method": "POST",
+                "Origin": "*",
+                "Access-Control-Request-Headers": "Content-Type",
+            },
+        )
+        self.assertEqual(response.status, 200)
+        self.assertIsNotNone(response.headers.get("Access-Control-Allow-Origin"))
+        self.assertIsNotNone(response.headers.get("Access-Control-Allow-Headers"))
+        self.assertIsNotNone(response.headers.get("Access-Control-Allow-Methods"))
+
+    @unittest_run_loop
+    async def test_cors_headers_present(self) -> None:
+        response = await self.client.post("/", headers={"Origin": "*"})
+        self.assertIsNotNone(response.headers.get("Access-Control-Allow-Origin"))
+        self.assertIsNotNone(response.headers.get("Access-Control-Expose-Headers"))

From 1af533108968e40cc005079a328ad117a864af13 Mon Sep 17 00:00:00 2001
From: Zsolt Dollenstein <zsol.zsol@gmail.com>
Date: Sat, 25 Sep 2021 20:45:13 +0100
Subject: [PATCH 0305/1034] Bump required aiohttp version to 3.7.4 (#2509)

Commit history before merge:

* Bump required aiohttp version to 3.7.4

This release includes an important security fix
(https://github.com/aio-libs/aiohttp/security/advisories/GHSA-v6wp-4m6f-gcjg) and many
other improvements.

* add changelog entry
* Let's not forget about Pipfile

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 CHANGES.md | 1 +
 Pipfile    | 2 +-
 setup.py   | 2 +-
 3 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 2a9b649d25c..1ff2cea84ca 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -5,6 +5,7 @@
 ### _Blackd_
 
 - Remove dependency on aiohttp-cors (#2500)
+- Bump required aiohttp version to 3.7.4 (#2509)
 
 ## 21.9b0
 
diff --git a/Pipfile b/Pipfile
index 66ded8b8570..6c635a63c66 100644
--- a/Pipfile
+++ b/Pipfile
@@ -40,7 +40,7 @@ readme_renderer = "*"
 black = {editable = true, extras = ["d", "jupyter"], path = "."}
 
 [packages]
-aiohttp = ">=3.6.0"
+aiohttp = ">=3.7.4"
 platformdirs= ">=2"
 click = ">=8.0.0"
 mypy_extensions = ">=0.4.3"
diff --git a/setup.py b/setup.py
index 19df9beb24e..015f321eaa9 100644
--- a/setup.py
+++ b/setup.py
@@ -86,7 +86,7 @@ def get_long_description() -> str:
         "mypy_extensions>=0.4.3",
     ],
     extras_require={
-        "d": ["aiohttp>=3.6.0"],
+        "d": ["aiohttp>=3.7.4"],
         "colorama": ["colorama>=0.4.3"],
         "python2": ["typed-ast>=1.4.2"],
         "uvloop": ["uvloop>=0.15.2"],

From 39b55f787cff41ef9726b256cfdbedefe6d5c716 Mon Sep 17 00:00:00 2001
From: Marco Edward Gorelli <marcogorelli@protonmail.com>
Date: Sat, 25 Sep 2021 20:46:36 +0100
Subject: [PATCH 0306/1034] Add test to cover when unable to replace magics
 (#2471)

Another follow-up from #2357, adding a test for uncovered code.
---
 src/black/handle_ipynb_magics.py | 7 ++++---
 tests/test_ipynb.py              | 9 +++++++++
 2 files changed, 13 insertions(+), 3 deletions(-)

diff --git a/src/black/handle_ipynb_magics.py b/src/black/handle_ipynb_magics.py
index b18f8629136..63c8aafe35b 100644
--- a/src/black/handle_ipynb_magics.py
+++ b/src/black/handle_ipynb_magics.py
@@ -53,6 +53,7 @@
         "%%writefile",
     )
 )
+TOKEN_HEX = secrets.token_hex
 
 
 @dataclasses.dataclass(frozen=True)
@@ -188,10 +189,10 @@ def get_token(src: str, magic: str) -> str:
     """
     assert magic
     nbytes = max(len(magic) // 2 - 1, 1)
-    token = secrets.token_hex(nbytes)
+    token = TOKEN_HEX(nbytes)
     counter = 0
-    while token in src:  # pragma: nocover
-        token = secrets.token_hex(nbytes)
+    while token in src:
+        token = TOKEN_HEX(nbytes)
         counter += 1
         if counter > 100:
             raise AssertionError(
diff --git a/tests/test_ipynb.py b/tests/test_ipynb.py
index 038155e9270..12f176c9341 100644
--- a/tests/test_ipynb.py
+++ b/tests/test_ipynb.py
@@ -453,3 +453,12 @@ def test_ipynb_and_pyi_flags() -> None:
     assert isinstance(result.exception, SystemExit)
     expected = "Cannot pass both `pyi` and `ipynb` flags!\n"
     assert result.output == expected
+
+
+def test_unable_to_replace_magics(monkeypatch: MonkeyPatch) -> None:
+    src = "%%time\na = 'foo'"
+    monkeypatch.setattr("black.handle_ipynb_magics.TOKEN_HEX", lambda _: "foo")
+    with pytest.raises(
+        AssertionError, match="Black was not able to replace IPython magic"
+    ):
+        format_cell(src, fast=True, mode=JUPYTER_MODE)

From 31a9d8a184a4dd2268df53672ec5dbc017a5eec9 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Tue, 28 Sep 2021 18:41:35 -0400
Subject: [PATCH 0307/1034] Fix python_version markers in Pipfile.lock (#2511)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This took way too much effort but in the end I was able to achieve a
(mostly) functional Pipfile.lock ranging from 3.6 to 3.9 🎉
---
 Pipfile      |  4 ++--
 Pipfile.lock | 17 +++++++----------
 2 files changed, 9 insertions(+), 12 deletions(-)

diff --git a/Pipfile b/Pipfile
index 6c635a63c66..c6cd8d41ef5 100644
--- a/Pipfile
+++ b/Pipfile
@@ -48,6 +48,6 @@ pathspec = ">=0.8.1"
 regex = ">=2020.1.8"
 tomli = ">=0.2.6, <2.0.0"
 typed-ast = "==1.4.2"
-typing_extensions = {"python_version <" = "3.10","version >=" = "3.10.0.0"}
+typing_extensions = {markers = "python_version < '3.10'", version = ">=3.10.0.0"}
 black = {editable = true,extras = ["d"],path = "."}
-dataclasses = {"python_version <" = "3.7","version >" = "0.1.3"}
+dataclasses = {markers = "python_version < '3.7'", version = ">0.1.3"}
diff --git a/Pipfile.lock b/Pipfile.lock
index 0cbe9011981..22b66ba8ca3 100644
--- a/Pipfile.lock
+++ b/Pipfile.lock
@@ -1,7 +1,7 @@
 {
     "_meta": {
         "hash": {
-            "sha256": "8b28e41c5a63f0c30361d2a0ed29dc1e3f0468223ef150ae68586839e2ccf1c9"
+            "sha256": "192f075f04e702887745a3f19056b0172d83e4bc494fff4e0bcd6cfcafedd512"
         },
         "pipfile-spec": 6,
         "requires": {},
@@ -102,9 +102,8 @@
                 "sha256:8479067f342acf957dc82ec415d355ab5edb7e7646b90dc6e2fd1d96ad084c97"
             ],
             "index": "pypi",
-            "python_version <": "3.7",
-            "version": "==0.8",
-            "version >": "0.1.3"
+            "markers": "python_version < '3.7'",
+            "version": "==0.8"
         },
         "idna": {
             "hashes": [
@@ -321,9 +320,8 @@
                 "sha256:779383f6086d90c99ae41cf0ff39aac8a7937a9283ce0a414e5dd782f4c94a84"
             ],
             "index": "pypi",
-            "python_version <": "3.10",
-            "version": "==3.10.0.0",
-            "version >=": "3.10.0.0"
+            "markers": "python_version < '3.10'",
+            "version": "==3.10.0.0"
         },
         "yarl": {
             "hashes": [
@@ -1558,9 +1556,8 @@
                 "sha256:779383f6086d90c99ae41cf0ff39aac8a7937a9283ce0a414e5dd782f4c94a84"
             ],
             "index": "pypi",
-            "python_version <": "3.10",
-            "version": "==3.10.0.0",
-            "version >=": "3.10.0.0"
+            "markers": "python_version < '3.10'",
+            "version": "==3.10.0.0"
         },
         "urllib3": {
             "hashes": [

From 09915f4bd2d13652c089b9a96408b39116d82eb0 Mon Sep 17 00:00:00 2001
From: shaoran <shaoran@sakuranohana.org>
Date: Wed, 29 Sep 2021 02:31:29 +0200
Subject: [PATCH 0308/1034] Allow to pass the FileMode options in the vim
 plugin (#1319)

---
 CHANGES.md                   |  4 +++
 autoload/black.vim           | 49 +++++++++++++++++++++++++++++++++---
 docs/integrations/editors.md |  2 ++
 plugin/black.vim             | 14 ++++++++++-
 4 files changed, 65 insertions(+), 4 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 1ff2cea84ca..61d3178f922 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -7,6 +7,10 @@
 - Remove dependency on aiohttp-cors (#2500)
 - Bump required aiohttp version to 3.7.4 (#2509)
 
+### Integrations
+
+- Allow to pass `target_version` in the vim plugin (#1319)
+
 ## 21.9b0
 
 ### Packaging
diff --git a/autoload/black.vim b/autoload/black.vim
index 29d8f2b88e4..9ff5c2341fe 100644
--- a/autoload/black.vim
+++ b/autoload/black.vim
@@ -98,13 +98,47 @@ if _initialize_black_env():
   import black
   import time
 
-def Black():
+def get_target_version(tv):
+  if isinstance(tv, black.TargetVersion):
+    return tv
+  ret = None
+  try:
+    ret = black.TargetVersion[tv.upper()]
+  except KeyError:
+    print(f"WARNING: Target version {tv!r} not recognized by Black, using default target")
+  return ret
+
+def Black(**kwargs):
+  """
+  kwargs allows you to override ``target_versions`` argument of
+  ``black.FileMode``.
+
+  ``target_version`` needs to be cleaned because ``black.FileMode``
+  expects the ``target_versions`` argument to be a set of TargetVersion enums.
+
+  Allow kwargs["target_version"] to be a string to allow
+  to type it more quickly.
+
+  Using also target_version instead of target_versions to remain
+  consistent to Black's documentation of the structure of pyproject.toml.
+  """
   start = time.time()
   configs = get_configs()
+
+  black_kwargs = {}
+  if "target_version" in kwargs:
+    target_version = kwargs["target_version"]
+
+    if not isinstance(target_version, (list, set)):
+      target_version = [target_version]
+    target_version = set(filter(lambda x: x, map(lambda tv: get_target_version(tv), target_version)))
+    black_kwargs["target_versions"] = target_version
+
   mode = black.FileMode(
     line_length=configs["line_length"],
     string_normalization=not configs["skip_string_normalization"],
     is_pyi=vim.current.buffer.name.endswith('.pyi'),
+    **black_kwargs,
   )
   quiet = configs["quiet"]
 
@@ -160,8 +194,17 @@ def BlackVersion():
 
 EndPython3
 
-function black#Black()
-  :py3 Black()
+function black#Black(...)
+    let kwargs = {}
+    for arg in a:000
+        let arg_list = split(arg, '=')
+        let kwargs[arg_list[0]] = arg_list[1]
+    endfor
+python3 << EOF
+import vim
+kwargs = vim.eval("kwargs")
+EOF
+  :py3 Black(**kwargs)
 endfunction
 
 function black#BlackUpgrade()
diff --git a/docs/integrations/editors.md b/docs/integrations/editors.md
index 6098631e2a0..d3be7c0ea84 100644
--- a/docs/integrations/editors.md
+++ b/docs/integrations/editors.md
@@ -116,6 +116,8 @@ Wing supports black via the OS Commands tool, as explained in the Wing documenta
 Commands and shortcuts:
 
 - `:Black` to format the entire file (ranges not supported);
+  - you can optionally pass `target_version=<version>` with the same values as in the
+    command line.
 - `:BlackUpgrade` to upgrade _Black_ inside the virtualenv;
 - `:BlackVersion` to get the current version of _Black_ inside the virtualenv.
 
diff --git a/plugin/black.vim b/plugin/black.vim
index 3bdca62e6ad..90d2047790b 100644
--- a/plugin/black.vim
+++ b/plugin/black.vim
@@ -53,8 +53,20 @@ endif
 if !exists("g:black_quiet")
   let g:black_quiet = 0
 endif
+if !exists("g:black_target_version")
+  let g:black_target_version = ""
+endif
 
+function BlackComplete(ArgLead, CmdLine, CursorPos)
+  return [
+\    'target_version=py27',
+\    'target_version=py36',
+\    'target_version=py37',
+\    'target_version=py38',
+\    'target_version=py39',
+\  ]
+endfunction
 
-command! Black :call black#Black()
+command! -nargs=* -complete=customlist,BlackComplete Black :call black#Black(<f-args>)
 command! BlackUpgrade :call black#BlackUpgrade()
 command! BlackVersion :call black#BlackVersion()

From 0fd353f1639c580c32599bf435902d08dbd9a560 Mon Sep 17 00:00:00 2001
From: Fergus Mitchell <fergus.htm@gmail.com>
Date: Wed, 29 Sep 2021 17:50:44 +0100
Subject: [PATCH 0309/1034] Add --workers CLI parameter (fixes #2513) (#2514)

Fixes #2513
---
 CHANGES.md            |  4 ++++
 src/black/__init__.py | 21 +++++++++++++++++++--
 2 files changed, 23 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 61d3178f922..04e9edf692c 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### _Black_
+
+- Add new `--workers` parameter (#2514)
+
 ### _Blackd_
 
 - Remove dependency on aiohttp-cors (#2500)
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 7fed1355f47..83a39234d38 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -95,6 +95,8 @@ def from_configuration(
 # Legacy name, left for integrations.
 FileMode = Mode
 
+DEFAULT_WORKERS = os.cpu_count()
+
 
 def read_pyproject_toml(
     ctx: click.Context, param: click.Parameter, value: Optional[str]
@@ -318,6 +320,14 @@ def validate_regex(
         "editors that rely on using stdin."
     ),
 )
+@click.option(
+    "-W",
+    "--workers",
+    type=click.IntRange(min=1),
+    default=DEFAULT_WORKERS,
+    show_default=True,
+    help="Number of parallel workers",
+)
 @click.option(
     "-q",
     "--quiet",
@@ -383,6 +393,7 @@ def main(
     extend_exclude: Optional[Pattern],
     force_exclude: Optional[Pattern],
     stdin_filename: Optional[str],
+    workers: int,
     src: Tuple[str, ...],
     config: Optional[str],
 ) -> None:
@@ -468,6 +479,7 @@ def main(
                 write_back=write_back,
                 mode=mode,
                 report=report,
+                workers=workers,
             )
 
     if verbose or not quiet:
@@ -644,12 +656,17 @@ def reformat_one(
 
 
 def reformat_many(
-    sources: Set[Path], fast: bool, write_back: WriteBack, mode: Mode, report: "Report"
+    sources: Set[Path],
+    fast: bool,
+    write_back: WriteBack,
+    mode: Mode,
+    report: "Report",
+    workers: Optional[int],
 ) -> None:
     """Reformat multiple files using a ProcessPoolExecutor."""
     executor: Executor
     loop = asyncio.get_event_loop()
-    worker_count = os.cpu_count()
+    worker_count = workers if workers is not None else DEFAULT_WORKERS
     if sys.platform == "win32":
         # Work around https://bugs.python.org/issue26903
         worker_count = min(worker_count, 60)

From 3500e1cda5bef73ddc7eaf79be6c67c918738936 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Sat, 2 Oct 2021 19:37:32 -0400
Subject: [PATCH 0310/1034] MNT: remove unnecessary test deps + some
 refactoring (GH-2510)

The main goals of this commit include:

* improving consistency on how strict the test suite is -- Jelle has
  seen cases where a test did not fail to an incomplete test setup
  even though it should've
* simplifying tests for both ease of creation and reading via
  parametrization and helpers
* reorganizing the test suite by grouping more tests
* dropping test suite dependencies that aren't strictly necessary

The test suite could definitely do with more refactoring, but this is a
good first pass. Anyway it would've gotten too big to review effectively
if I did continue on this PR.

Commit history before squash merge:

* Drop parameterized dep and refactor format tests

Since the test suite is already using pytest-only features we can drop
the parameterized test dependency in favour of pytest's own offering.

I also added an utility function called assert_format that makes it
even easier to verify Black formats some code correctly. We already
have great tooling if the case is very simple in test_format.py but
any sort of complication makes it hard to use. Also if you're writing
a non-standard test case, you have to be careful to include all of
the steps so issues don't go undetected. assert_format aims to
1) improve consistency, 2) avoid wasted CPU cycles, and 3) avoid
logical errors that hide issues.

Finally, quite a few tests were either moved and/or simplified with
the new setup.

* Move file collection tests
* Add assert_collected_sources helper function

Testing source collection involves a lot of repetitive boilerplate,
something that black.files.get_sources's signature does not help with.
So to cut down on boilerplate like `report=black.Report()` I added
a convenience function to tests/test_black.py which wraps
black.get_sources. Its signature is designed to be much more lax to
make it much easier to use. Somehow this leads to cutting 100 lines!

Also IMO the test cases are much easier to read since it's more
declarative than really procedural now.

* Run isort on some test files
* Move cache tests
* Use pytest-style asserts & add parametrization
* Drop now unnecessary test dependencies

*pytest-cases might be interesting for further refactoring but I
haven't been able to wrap my head around it for the time being. We
can always revisit anyway.
---
 Pipfile               |    3 -
 Pipfile.lock          |   45 +-
 test_requirements.txt |    3 -
 tests/test_black.py   | 1456 +++++++++++++++++------------------------
 tests/test_format.py  |  159 ++++-
 tests/util.py         |   87 ++-
 6 files changed, 786 insertions(+), 967 deletions(-)

diff --git a/Pipfile b/Pipfile
index c6cd8d41ef5..534ca50fa5d 100644
--- a/Pipfile
+++ b/Pipfile
@@ -7,11 +7,8 @@ verify_ssl = true
 # Testing related requirements.
 coverage = ">= 5.3"
 pytest = " >= 6.1.1"
-pytest-mock = ">= 3.3.1"
-pytest-cases = ">= 2.3.0"
 pytest-xdist = ">= 2.2.1"
 pytest-cov = ">= 2.11.1"
-parameterized = ">= 0.7.4"
 tox = "*"
 
 # Linting related requirements.
diff --git a/Pipfile.lock b/Pipfile.lock
index 22b66ba8ca3..280e6498af1 100644
--- a/Pipfile.lock
+++ b/Pipfile.lock
@@ -1,7 +1,7 @@
 {
     "_meta": {
         "hash": {
-            "sha256": "192f075f04e702887745a3f19056b0172d83e4bc494fff4e0bcd6cfcafedd512"
+            "sha256": "6dbdff058fac8e6492f9d64194e98e48e062946ec4c06f9bb7df517d1dd89ce8"
         },
         "pipfile-spec": 6,
         "requires": {},
@@ -661,16 +661,8 @@
                 "sha256:8479067f342acf957dc82ec415d355ab5edb7e7646b90dc6e2fd1d96ad084c97"
             ],
             "index": "pypi",
-            "python_version <": "3.7",
-            "version": "==0.8",
-            "version >": "0.1.3"
-        },
-        "decopatch": {
-            "hashes": [
-                "sha256:29a74d5d753423b188d5b537532da4f4b88e33ddccb95a8a20a5eff5b13265d4",
-                "sha256:c66b0815f15db04de7bb52b0b276432b76b7346fe7046f28033f48a14340d144"
-            ],
-            "version": "==1.4.8"
+            "markers": "python_version < '3.7'",
+            "version": "==0.8"
         },
         "decorator": {
             "hashes": [
@@ -827,13 +819,6 @@
             "markers": "python_version >= '3.6'",
             "version": "==23.1.0"
         },
-        "makefun": {
-            "hashes": [
-                "sha256:033eed65e2c1804fca84161a38d1fc8bb8650d32a89ac1c5dc7e54b2b2c2e88c",
-                "sha256:a19bddf07efb6bf92e3ccde5d593e49bc59001fd6c17cf7301d7a73a2647ae83"
-            ],
-            "version": "==1.11.3"
-        },
         "markdown-it-py": {
             "hashes": [
                 "sha256:36be6bb3ad987bfdb839f5ba78ddf094552ca38ccbd784ae4f74a4e1419fc6e3",
@@ -1028,14 +1013,6 @@
             "markers": "python_version >= '3.6'",
             "version": "==21.0"
         },
-        "parameterized": {
-            "hashes": [
-                "sha256:41bbff37d6186430f77f900d777e5bb6a24928a1c46fb1de692f8b52b8833b5c",
-                "sha256:9cbb0b69a03e8695d68b3399a8a5825200976536fe1cb79db60ed6a4c8c9efe9"
-            ],
-            "index": "pypi",
-            "version": "==0.8.1"
-        },
         "parso": {
             "hashes": [
                 "sha256:12b83492c6239ce32ff5eed6d3639d6a536170723c6f3f1506869f1ace413398",
@@ -1169,14 +1146,6 @@
             "index": "pypi",
             "version": "==6.2.4"
         },
-        "pytest-cases": {
-            "hashes": [
-                "sha256:13136269240615bc79041f8af8fc96e0e3e085da72dd22b18625451fda2443b8",
-                "sha256:a4abe0ec2b8acf8f8b5ab73060de72eac745c6ed9cfa317d59ae71b4a0bbbdf5"
-            ],
-            "index": "pypi",
-            "version": "==3.6.3"
-        },
         "pytest-cov": {
             "hashes": [
                 "sha256:261bb9e47e65bd099c89c3edf92972865210c36813f80ede5277dceb77a4a62a",
@@ -1193,14 +1162,6 @@
             "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
             "version": "==1.3.0"
         },
-        "pytest-mock": {
-            "hashes": [
-                "sha256:30c2f2cc9759e76eee674b81ea28c9f0b94f8f0445a1b87762cadf774f0df7e3",
-                "sha256:40217a058c52a63f1042f0784f62009e976ba824c418cced42e88d5f40ab0e62"
-            ],
-            "index": "pypi",
-            "version": "==3.6.1"
-        },
         "pytest-xdist": {
             "hashes": [
                 "sha256:e8ecde2f85d88fbcadb7d28cb33da0fa29bca5cf7d5967fa89fc0e97e5299ea5",
diff --git a/test_requirements.txt b/test_requirements.txt
index 31ab2d05fea..5bc494d5999 100644
--- a/test_requirements.txt
+++ b/test_requirements.txt
@@ -1,9 +1,6 @@
 coverage >= 5.3
 pre-commit
 pytest >= 6.1.1
-pytest-mock >= 3.3.1
-pytest-cases >= 2.3.0
 pytest-xdist >= 2.2.1
 pytest-cov >= 2.11.1
-parameterized >= 0.7.4
 tox
diff --git a/tests/test_black.py b/tests/test_black.py
index 398a528bee9..f25db1b73d1 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -1,69 +1,70 @@
 #!/usr/bin/env python3
-import multiprocessing
+
 import asyncio
+import inspect
+import io
 import logging
+import multiprocessing
+import os
+import sys
+import types
+import unittest
 from concurrent.futures import ThreadPoolExecutor
 from contextlib import contextmanager
 from dataclasses import replace
-import inspect
-import io
 from io import BytesIO
-import os
 from pathlib import Path
 from platform import system
-import regex as re
-import sys
 from tempfile import TemporaryDirectory
-import types
 from typing import (
     Any,
     Callable,
     Dict,
-    List,
     Iterator,
+    List,
+    Optional,
+    Sequence,
     TypeVar,
+    Union,
 )
-import pytest
-import unittest
-from unittest.mock import patch, MagicMock
-from parameterized import parameterized
+from unittest.mock import MagicMock, patch
 
 import click
+import pytest
+import regex as re
 from click import unstyle
 from click.testing import CliRunner
+from pathspec import PathSpec
 
 import black
+import black.files
 from black import Feature, TargetVersion
+from black import re_compile_maybe_verbose as compile_pattern
 from black.cache import get_cache_file
 from black.debug import DebugVisitor
-from black.output import diff, color_diff
+from black.output import color_diff, diff
 from black.report import Report
-import black.files
-
-from pathspec import PathSpec
 
 # Import other test classes
 from tests.util import (
-    THIS_DIR,
-    change_directory,
-    read_data,
+    DATA_DIR,
+    DEFAULT_MODE,
     DETERMINISTIC_HEADER,
+    PY36_VERSIONS,
+    THIS_DIR,
     BlackBaseTestCase,
-    DEFAULT_MODE,
-    fs,
-    ff,
+    assert_format,
+    change_directory,
     dump_to_stderr,
+    ff,
+    fs,
+    read_data,
 )
 
-
 THIS_FILE = Path(__file__)
-PY36_VERSIONS = {
-    TargetVersion.PY36,
-    TargetVersion.PY37,
-    TargetVersion.PY38,
-    TargetVersion.PY39,
-}
 PY36_ARGS = [f"--target-version={version.name.lower()}" for version in PY36_VERSIONS]
+DEFAULT_EXCLUDE = black.re_compile_maybe_verbose(black.const.DEFAULT_EXCLUDES)
+DEFAULT_INCLUDE = black.re_compile_maybe_verbose(black.const.DEFAULT_INCLUDES)
 T = TypeVar("T")
 R = TypeVar("R")
 
@@ -114,34 +115,26 @@ def __init__(self) -> None:
         super().__init__(mix_stderr=False)
 
 
-class BlackTestCase(BlackBaseTestCase):
-    def invokeBlack(
-        self, args: List[str], exit_code: int = 0, ignore_config: bool = True
-    ) -> None:
-        runner = BlackRunner()
-        if ignore_config:
-            args = ["--verbose", "--config", str(THIS_DIR / "empty.toml"), *args]
-        result = runner.invoke(black.main, args)
-        assert result.stdout_bytes is not None
-        assert result.stderr_bytes is not None
-        self.assertEqual(
-            result.exit_code,
-            exit_code,
-            msg=(
-                f"Failed with args: {args}\n"
-                f"stdout: {result.stdout_bytes.decode()!r}\n"
-                f"stderr: {result.stderr_bytes.decode()!r}\n"
-                f"exception: {result.exception}"
-            ),
-        )
+def invokeBlack(
+    args: List[str], exit_code: int = 0, ignore_config: bool = True
+) -> None:
+    runner = BlackRunner()
+    if ignore_config:
+        args = ["--verbose", "--config", str(THIS_DIR / "empty.toml"), *args]
+    result = runner.invoke(black.main, args)
+    assert result.stdout_bytes is not None
+    assert result.stderr_bytes is not None
+    msg = (
+        f"Failed with args: {args}\n"
+        f"stdout: {result.stdout_bytes.decode()!r}\n"
+        f"stderr: {result.stderr_bytes.decode()!r}\n"
+        f"exception: {result.exception}"
+    )
+    assert result.exit_code == exit_code, msg
 
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_empty(self) -> None:
-        source = expected = ""
-        actual = fs(source)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
+
+class BlackTestCase(BlackBaseTestCase):
+    invokeBlack = staticmethod(invokeBlack)
 
     def test_empty_ff(self) -> None:
         expected = ""
@@ -266,32 +259,6 @@ def test_trailing_comma_optional_parens_stability3_pass2(self) -> None:
         actual = fs(fs(source))  # this is what `format_file_contents` does with --safe
         black.assert_stable(source, actual, DEFAULT_MODE)
 
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_pep_572(self) -> None:
-        source, expected = read_data("pep_572")
-        actual = fs(source)
-        self.assertFormatEqual(expected, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-        if sys.version_info >= (3, 8):
-            black.assert_equivalent(source, actual)
-
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_pep_572_remove_parens(self) -> None:
-        source, expected = read_data("pep_572_remove_parens")
-        actual = fs(source)
-        self.assertFormatEqual(expected, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-        if sys.version_info >= (3, 8):
-            black.assert_equivalent(source, actual)
-
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_pep_572_do_not_remove_parens(self) -> None:
-        source, expected = read_data("pep_572_do_not_remove_parens")
-        # the AST safety checks will fail, but that's expected, just make sure no
-        # parentheses are touched
-        actual = black.format_str(source, mode=DEFAULT_MODE)
-        self.assertFormatEqual(expected, actual)
-
     def test_pep_572_version_detection(self) -> None:
         source, _ = read_data("pep_572")
         root = black.lib2to3_parse(source)
@@ -300,14 +267,6 @@ def test_pep_572_version_detection(self) -> None:
         versions = black.detect_target_versions(root)
         self.assertIn(black.TargetVersion.PY38, versions)
 
-    @parameterized.expand([(3, 9), (3, 10)])
-    def test_pep_572_newer_syntax(self, major: int, minor: int) -> None:
-        source, expected = read_data(f"pep_572_py{major}{minor}")
-        actual = fs(source, mode=DEFAULT_MODE)
-        self.assertFormatEqual(expected, actual)
-        if sys.version_info >= (major, minor):
-            black.assert_equivalent(source, actual)
-
     def test_expression_ff(self) -> None:
         source, expected = read_data("expression")
         tmp_file = Path(black.dump_to_file(source))
@@ -369,15 +328,6 @@ def test_expression_diff_with_color(self) -> None:
         self.assertIn("\033[31m", actual)
         self.assertIn("\033[0m", actual)
 
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_pep_570(self) -> None:
-        source, expected = read_data("pep_570")
-        actual = fs(source)
-        self.assertFormatEqual(expected, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-        if sys.version_info >= (3, 8):
-            black.assert_equivalent(source, actual)
-
     def test_detect_pos_only_arguments(self) -> None:
         source, _ = read_data("pep_570")
         root = black.lib2to3_parse(source)
@@ -390,52 +340,13 @@ def test_detect_pos_only_arguments(self) -> None:
     def test_string_quotes(self) -> None:
         source, expected = read_data("string_quotes")
         mode = black.Mode(experimental_string_processing=True)
-        actual = fs(source, mode=mode)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, mode)
+        assert_format(source, expected, mode)
         mode = replace(mode, string_normalization=False)
         not_normalized = fs(source, mode=mode)
         self.assertFormatEqual(source.replace("\\\n", ""), not_normalized)
         black.assert_equivalent(source, not_normalized)
         black.assert_stable(source, not_normalized, mode=mode)
 
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_docstring_no_string_normalization(self) -> None:
-        """Like test_docstring but with string normalization off."""
-        source, expected = read_data("docstring_no_string_normalization")
-        mode = replace(DEFAULT_MODE, string_normalization=False)
-        actual = fs(source, mode=mode)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, mode)
-
-    def test_long_strings_flag_disabled(self) -> None:
-        """Tests for turning off the string processing logic."""
-        source, expected = read_data("long_strings_flag_disabled")
-        mode = replace(DEFAULT_MODE, experimental_string_processing=False)
-        actual = fs(source, mode=mode)
-        self.assertFormatEqual(expected, actual)
-        black.assert_stable(expected, actual, mode)
-
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_numeric_literals(self) -> None:
-        source, expected = read_data("numeric_literals")
-        mode = replace(DEFAULT_MODE, target_versions=PY36_VERSIONS)
-        actual = fs(source, mode=mode)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, mode)
-
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_numeric_literals_ignoring_underscores(self) -> None:
-        source, expected = read_data("numeric_literals_skip_underscores")
-        mode = replace(DEFAULT_MODE, target_versions=PY36_VERSIONS)
-        actual = fs(source, mode=mode)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, mode)
-
     def test_skip_magic_trailing_comma(self) -> None:
         source, _ = read_data("expression.py")
         expected, _ = read_data("expression_skip_magic_trailing_comma.diff")
@@ -461,24 +372,6 @@ def test_skip_magic_trailing_comma(self) -> None:
             )
             self.assertEqual(expected, actual, msg)
 
-    @pytest.mark.python2
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_python2_print_function(self) -> None:
-        source, expected = read_data("python2_print_function")
-        mode = replace(DEFAULT_MODE, target_versions={TargetVersion.PY27})
-        actual = fs(source, mode=mode)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, mode)
-
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_stub(self) -> None:
-        mode = replace(DEFAULT_MODE, is_pyi=True)
-        source, expected = read_data("stub.pyi")
-        actual = fs(source, mode=mode)
-        self.assertFormatEqual(expected, actual)
-        black.assert_stable(source, actual, mode)
-
     @patch("black.dump_to_file", dump_to_stderr)
     def test_async_as_identifier(self) -> None:
         source_path = (THIS_DIR / "data" / "async_as_identifier.py").resolve()
@@ -509,26 +402,6 @@ def test_python37(self) -> None:
         # but not on 3.6, because we use async as a reserved keyword
         self.invokeBlack([str(source_path), "--target-version", "py36"], exit_code=123)
 
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_python38(self) -> None:
-        source, expected = read_data("python38")
-        actual = fs(source)
-        self.assertFormatEqual(expected, actual)
-        major, minor = sys.version_info[:2]
-        if major > 3 or (major == 3 and minor >= 8):
-            black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_python39(self) -> None:
-        source, expected = read_data("python39")
-        actual = fs(source)
-        self.assertFormatEqual(expected, actual)
-        major, minor = sys.version_info[:2]
-        if major > 3 or (major == 3 and minor >= 9):
-            black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
     def test_tab_comment_indentation(self) -> None:
         contents_tab = "if 1:\n\tif 2:\n\t\tpass\n\t# comment\n\tpass\n"
         contents_spc = "if 1:\n    if 2:\n        pass\n    # comment\n    pass\n"
@@ -1033,256 +906,67 @@ def err(msg: str, **kwargs: Any) -> None:
         self.assertTrue("Actual tree:" in out_str)
         self.assertEqual("".join(err_lines), "")
 
-    def test_cache_broken_file(self) -> None:
-        mode = DEFAULT_MODE
-        with cache_dir() as workspace:
-            cache_file = get_cache_file(mode)
-            with cache_file.open("w") as fobj:
-                fobj.write("this is not a pickle")
-            self.assertEqual(black.read_cache(mode), {})
-            src = (workspace / "test.py").resolve()
-            with src.open("w") as fobj:
-                fobj.write("print('hello')")
-            self.invokeBlack([str(src)])
-            cache = black.read_cache(mode)
-            self.assertIn(str(src), cache)
-
-    def test_cache_single_file_already_cached(self) -> None:
-        mode = DEFAULT_MODE
+    @event_loop()
+    @patch("black.ProcessPoolExecutor", MagicMock(side_effect=OSError))
+    def test_works_in_mono_process_only_environment(self) -> None:
         with cache_dir() as workspace:
-            src = (workspace / "test.py").resolve()
-            with src.open("w") as fobj:
-                fobj.write("print('hello')")
-            black.write_cache({}, [src], mode)
-            self.invokeBlack([str(src)])
-            with src.open("r") as fobj:
-                self.assertEqual(fobj.read(), "print('hello')")
+            for f in [
+                (workspace / "one.py").resolve(),
+                (workspace / "two.py").resolve(),
+            ]:
+                f.write_text('print("hello")\n')
+            self.invokeBlack([str(workspace)])
 
     @event_loop()
-    def test_cache_multiple_files(self) -> None:
-        mode = DEFAULT_MODE
-        with cache_dir() as workspace, patch(
-            "black.ProcessPoolExecutor", new=ThreadPoolExecutor
-        ):
-            one = (workspace / "one.py").resolve()
-            with one.open("w") as fobj:
-                fobj.write("print('hello')")
-            two = (workspace / "two.py").resolve()
-            with two.open("w") as fobj:
-                fobj.write("print('hello')")
-            black.write_cache({}, [one], mode)
-            self.invokeBlack([str(workspace)])
-            with one.open("r") as fobj:
-                self.assertEqual(fobj.read(), "print('hello')")
-            with two.open("r") as fobj:
-                self.assertEqual(fobj.read(), 'print("hello")\n')
-            cache = black.read_cache(mode)
-            self.assertIn(str(one), cache)
-            self.assertIn(str(two), cache)
+    def test_check_diff_use_together(self) -> None:
+        with cache_dir():
+            # Files which will be reformatted.
+            src1 = (THIS_DIR / "data" / "string_quotes.py").resolve()
+            self.invokeBlack([str(src1), "--diff", "--check"], exit_code=1)
+            # Files which will not be reformatted.
+            src2 = (THIS_DIR / "data" / "composition.py").resolve()
+            self.invokeBlack([str(src2), "--diff", "--check"])
+            # Multi file command.
+            self.invokeBlack([str(src1), str(src2), "--diff", "--check"], exit_code=1)
 
-    def test_no_cache_when_writeback_diff(self) -> None:
-        mode = DEFAULT_MODE
-        with cache_dir() as workspace:
-            src = (workspace / "test.py").resolve()
-            with src.open("w") as fobj:
-                fobj.write("print('hello')")
-            with patch("black.read_cache") as read_cache, patch(
-                "black.write_cache"
-            ) as write_cache:
-                self.invokeBlack([str(src), "--diff"])
-                cache_file = get_cache_file(mode)
-                self.assertFalse(cache_file.exists())
-                write_cache.assert_not_called()
-                read_cache.assert_not_called()
+    def test_no_files(self) -> None:
+        with cache_dir():
+            # Without an argument, black exits with error code 0.
+            self.invokeBlack([])
 
-    def test_no_cache_when_writeback_color_diff(self) -> None:
-        mode = DEFAULT_MODE
+    def test_broken_symlink(self) -> None:
         with cache_dir() as workspace:
-            src = (workspace / "test.py").resolve()
-            with src.open("w") as fobj:
-                fobj.write("print('hello')")
-            with patch("black.read_cache") as read_cache, patch(
-                "black.write_cache"
-            ) as write_cache:
-                self.invokeBlack([str(src), "--diff", "--color"])
-                cache_file = get_cache_file(mode)
-                self.assertFalse(cache_file.exists())
-                write_cache.assert_not_called()
-                read_cache.assert_not_called()
+            symlink = workspace / "broken_link.py"
+            try:
+                symlink.symlink_to("nonexistent.py")
+            except OSError as e:
+                self.skipTest(f"Can't create symlinks: {e}")
+            self.invokeBlack([str(workspace.resolve())])
 
-    @event_loop()
-    def test_output_locking_when_writeback_diff(self) -> None:
+    def test_single_file_force_pyi(self) -> None:
+        pyi_mode = replace(DEFAULT_MODE, is_pyi=True)
+        contents, expected = read_data("force_pyi")
         with cache_dir() as workspace:
-            for tag in range(0, 4):
-                src = (workspace / f"test{tag}.py").resolve()
-                with src.open("w") as fobj:
-                    fobj.write("print('hello')")
-            with patch("black.Manager", wraps=multiprocessing.Manager) as mgr:
-                self.invokeBlack(["--diff", str(workspace)], exit_code=0)
-                # this isn't quite doing what we want, but if it _isn't_
-                # called then we cannot be using the lock it provides
-                mgr.assert_called()
+            path = (workspace / "file.py").resolve()
+            with open(path, "w") as fh:
+                fh.write(contents)
+            self.invokeBlack([str(path), "--pyi"])
+            with open(path, "r") as fh:
+                actual = fh.read()
+            # verify cache with --pyi is separate
+            pyi_cache = black.read_cache(pyi_mode)
+            self.assertIn(str(path), pyi_cache)
+            normal_cache = black.read_cache(DEFAULT_MODE)
+            self.assertNotIn(str(path), normal_cache)
+        self.assertFormatEqual(expected, actual)
+        black.assert_equivalent(contents, actual)
+        black.assert_stable(contents, actual, pyi_mode)
 
     @event_loop()
-    def test_output_locking_when_writeback_color_diff(self) -> None:
-        with cache_dir() as workspace:
-            for tag in range(0, 4):
-                src = (workspace / f"test{tag}.py").resolve()
-                with src.open("w") as fobj:
-                    fobj.write("print('hello')")
-            with patch("black.Manager", wraps=multiprocessing.Manager) as mgr:
-                self.invokeBlack(["--diff", "--color", str(workspace)], exit_code=0)
-                # this isn't quite doing what we want, but if it _isn't_
-                # called then we cannot be using the lock it provides
-                mgr.assert_called()
-
-    def test_no_cache_when_stdin(self) -> None:
-        mode = DEFAULT_MODE
-        with cache_dir():
-            result = CliRunner().invoke(
-                black.main, ["-"], input=BytesIO(b"print('hello')")
-            )
-            self.assertEqual(result.exit_code, 0)
-            cache_file = get_cache_file(mode)
-            self.assertFalse(cache_file.exists())
-
-    def test_read_cache_no_cachefile(self) -> None:
-        mode = DEFAULT_MODE
-        with cache_dir():
-            self.assertEqual(black.read_cache(mode), {})
-
-    def test_write_cache_read_cache(self) -> None:
-        mode = DEFAULT_MODE
-        with cache_dir() as workspace:
-            src = (workspace / "test.py").resolve()
-            src.touch()
-            black.write_cache({}, [src], mode)
-            cache = black.read_cache(mode)
-            self.assertIn(str(src), cache)
-            self.assertEqual(cache[str(src)], black.get_cache_info(src))
-
-    def test_filter_cached(self) -> None:
-        with TemporaryDirectory() as workspace:
-            path = Path(workspace)
-            uncached = (path / "uncached").resolve()
-            cached = (path / "cached").resolve()
-            cached_but_changed = (path / "changed").resolve()
-            uncached.touch()
-            cached.touch()
-            cached_but_changed.touch()
-            cache = {
-                str(cached): black.get_cache_info(cached),
-                str(cached_but_changed): (0.0, 0),
-            }
-            todo, done = black.filter_cached(
-                cache, {uncached, cached, cached_but_changed}
-            )
-            self.assertEqual(todo, {uncached, cached_but_changed})
-            self.assertEqual(done, {cached})
-
-    def test_write_cache_creates_directory_if_needed(self) -> None:
-        mode = DEFAULT_MODE
-        with cache_dir(exists=False) as workspace:
-            self.assertFalse(workspace.exists())
-            black.write_cache({}, [], mode)
-            self.assertTrue(workspace.exists())
-
-    @event_loop()
-    def test_failed_formatting_does_not_get_cached(self) -> None:
-        mode = DEFAULT_MODE
-        with cache_dir() as workspace, patch(
-            "black.ProcessPoolExecutor", new=ThreadPoolExecutor
-        ):
-            failing = (workspace / "failing.py").resolve()
-            with failing.open("w") as fobj:
-                fobj.write("not actually python")
-            clean = (workspace / "clean.py").resolve()
-            with clean.open("w") as fobj:
-                fobj.write('print("hello")\n')
-            self.invokeBlack([str(workspace)], exit_code=123)
-            cache = black.read_cache(mode)
-            self.assertNotIn(str(failing), cache)
-            self.assertIn(str(clean), cache)
-
-    def test_write_cache_write_fail(self) -> None:
-        mode = DEFAULT_MODE
-        with cache_dir(), patch.object(Path, "open") as mock:
-            mock.side_effect = OSError
-            black.write_cache({}, [], mode)
-
-    @event_loop()
-    @patch("black.ProcessPoolExecutor", MagicMock(side_effect=OSError))
-    def test_works_in_mono_process_only_environment(self) -> None:
-        with cache_dir() as workspace:
-            for f in [
-                (workspace / "one.py").resolve(),
-                (workspace / "two.py").resolve(),
-            ]:
-                f.write_text('print("hello")\n')
-            self.invokeBlack([str(workspace)])
-
-    @event_loop()
-    def test_check_diff_use_together(self) -> None:
-        with cache_dir():
-            # Files which will be reformatted.
-            src1 = (THIS_DIR / "data" / "string_quotes.py").resolve()
-            self.invokeBlack([str(src1), "--diff", "--check"], exit_code=1)
-            # Files which will not be reformatted.
-            src2 = (THIS_DIR / "data" / "composition.py").resolve()
-            self.invokeBlack([str(src2), "--diff", "--check"])
-            # Multi file command.
-            self.invokeBlack([str(src1), str(src2), "--diff", "--check"], exit_code=1)
-
-    def test_no_files(self) -> None:
-        with cache_dir():
-            # Without an argument, black exits with error code 0.
-            self.invokeBlack([])
-
-    def test_broken_symlink(self) -> None:
-        with cache_dir() as workspace:
-            symlink = workspace / "broken_link.py"
-            try:
-                symlink.symlink_to("nonexistent.py")
-            except OSError as e:
-                self.skipTest(f"Can't create symlinks: {e}")
-            self.invokeBlack([str(workspace.resolve())])
-
-    def test_read_cache_line_lengths(self) -> None:
-        mode = DEFAULT_MODE
-        short_mode = replace(DEFAULT_MODE, line_length=1)
-        with cache_dir() as workspace:
-            path = (workspace / "file.py").resolve()
-            path.touch()
-            black.write_cache({}, [path], mode)
-            one = black.read_cache(mode)
-            self.assertIn(str(path), one)
-            two = black.read_cache(short_mode)
-            self.assertNotIn(str(path), two)
-
-    def test_single_file_force_pyi(self) -> None:
-        pyi_mode = replace(DEFAULT_MODE, is_pyi=True)
-        contents, expected = read_data("force_pyi")
-        with cache_dir() as workspace:
-            path = (workspace / "file.py").resolve()
-            with open(path, "w") as fh:
-                fh.write(contents)
-            self.invokeBlack([str(path), "--pyi"])
-            with open(path, "r") as fh:
-                actual = fh.read()
-            # verify cache with --pyi is separate
-            pyi_cache = black.read_cache(pyi_mode)
-            self.assertIn(str(path), pyi_cache)
-            normal_cache = black.read_cache(DEFAULT_MODE)
-            self.assertNotIn(str(path), normal_cache)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(contents, actual)
-        black.assert_stable(contents, actual, pyi_mode)
-
-    @event_loop()
-    def test_multi_file_force_pyi(self) -> None:
-        reg_mode = DEFAULT_MODE
-        pyi_mode = replace(DEFAULT_MODE, is_pyi=True)
-        contents, expected = read_data("force_pyi")
+    def test_multi_file_force_pyi(self) -> None:
+        reg_mode = DEFAULT_MODE
+        pyi_mode = replace(DEFAULT_MODE, is_pyi=True)
+        contents, expected = read_data("force_pyi")
         with cache_dir() as workspace:
             paths = [
                 (workspace / "file1.py").resolve(),
@@ -1366,216 +1050,6 @@ def test_pipe_force_py36(self) -> None:
         actual = result.output
         self.assertFormatEqual(actual, expected)
 
-    def test_include_exclude(self) -> None:
-        path = THIS_DIR / "data" / "include_exclude_tests"
-        include = re.compile(r"\.pyi?$")
-        exclude = re.compile(r"/exclude/|/\.definitely_exclude/")
-        report = black.Report()
-        gitignore = PathSpec.from_lines("gitwildmatch", [])
-        sources: List[Path] = []
-        expected = [
-            Path(path / "b/dont_exclude/a.py"),
-            Path(path / "b/dont_exclude/a.pyi"),
-        ]
-        this_abs = THIS_DIR.resolve()
-        sources.extend(
-            black.gen_python_files(
-                path.iterdir(),
-                this_abs,
-                include,
-                exclude,
-                None,
-                None,
-                report,
-                gitignore,
-                verbose=False,
-                quiet=False,
-            )
-        )
-        self.assertEqual(sorted(expected), sorted(sources))
-
-    def test_gitignore_used_as_default(self) -> None:
-        path = Path(THIS_DIR / "data" / "include_exclude_tests")
-        include = re.compile(r"\.pyi?$")
-        extend_exclude = re.compile(r"/exclude/")
-        src = str(path / "b/")
-        report = black.Report()
-        expected: List[Path] = [
-            path / "b/.definitely_exclude/a.py",
-            path / "b/.definitely_exclude/a.pyi",
-        ]
-        sources = list(
-            black.get_sources(
-                ctx=FakeContext(),
-                src=(src,),
-                quiet=True,
-                verbose=False,
-                include=include,
-                exclude=None,
-                extend_exclude=extend_exclude,
-                force_exclude=None,
-                report=report,
-                stdin_filename=None,
-            )
-        )
-        self.assertEqual(sorted(expected), sorted(sources))
-
-    @patch("black.find_project_root", lambda *args: THIS_DIR.resolve())
-    def test_exclude_for_issue_1572(self) -> None:
-        # Exclude shouldn't touch files that were explicitly given to Black through the
-        # CLI. Exclude is supposed to only apply to the recursive discovery of files.
-        # https://github.com/psf/black/issues/1572
-        path = THIS_DIR / "data" / "include_exclude_tests"
-        include = ""
-        exclude = r"/exclude/|a\.py"
-        src = str(path / "b/exclude/a.py")
-        report = black.Report()
-        expected = [Path(path / "b/exclude/a.py")]
-        sources = list(
-            black.get_sources(
-                ctx=FakeContext(),
-                src=(src,),
-                quiet=True,
-                verbose=False,
-                include=re.compile(include),
-                exclude=re.compile(exclude),
-                extend_exclude=None,
-                force_exclude=None,
-                report=report,
-                stdin_filename=None,
-            )
-        )
-        self.assertEqual(sorted(expected), sorted(sources))
-
-    @patch("black.find_project_root", lambda *args: THIS_DIR.resolve())
-    def test_get_sources_with_stdin(self) -> None:
-        include = ""
-        exclude = r"/exclude/|a\.py"
-        src = "-"
-        report = black.Report()
-        expected = [Path("-")]
-        sources = list(
-            black.get_sources(
-                ctx=FakeContext(),
-                src=(src,),
-                quiet=True,
-                verbose=False,
-                include=re.compile(include),
-                exclude=re.compile(exclude),
-                extend_exclude=None,
-                force_exclude=None,
-                report=report,
-                stdin_filename=None,
-            )
-        )
-        self.assertEqual(sorted(expected), sorted(sources))
-
-    @patch("black.find_project_root", lambda *args: THIS_DIR.resolve())
-    def test_get_sources_with_stdin_filename(self) -> None:
-        include = ""
-        exclude = r"/exclude/|a\.py"
-        src = "-"
-        report = black.Report()
-        stdin_filename = str(THIS_DIR / "data/collections.py")
-        expected = [Path(f"__BLACK_STDIN_FILENAME__{stdin_filename}")]
-        sources = list(
-            black.get_sources(
-                ctx=FakeContext(),
-                src=(src,),
-                quiet=True,
-                verbose=False,
-                include=re.compile(include),
-                exclude=re.compile(exclude),
-                extend_exclude=None,
-                force_exclude=None,
-                report=report,
-                stdin_filename=stdin_filename,
-            )
-        )
-        self.assertEqual(sorted(expected), sorted(sources))
-
-    @patch("black.find_project_root", lambda *args: THIS_DIR.resolve())
-    def test_get_sources_with_stdin_filename_and_exclude(self) -> None:
-        # Exclude shouldn't exclude stdin_filename since it is mimicking the
-        # file being passed directly. This is the same as
-        # test_exclude_for_issue_1572
-        path = THIS_DIR / "data" / "include_exclude_tests"
-        include = ""
-        exclude = r"/exclude/|a\.py"
-        src = "-"
-        report = black.Report()
-        stdin_filename = str(path / "b/exclude/a.py")
-        expected = [Path(f"__BLACK_STDIN_FILENAME__{stdin_filename}")]
-        sources = list(
-            black.get_sources(
-                ctx=FakeContext(),
-                src=(src,),
-                quiet=True,
-                verbose=False,
-                include=re.compile(include),
-                exclude=re.compile(exclude),
-                extend_exclude=None,
-                force_exclude=None,
-                report=report,
-                stdin_filename=stdin_filename,
-            )
-        )
-        self.assertEqual(sorted(expected), sorted(sources))
-
-    @patch("black.find_project_root", lambda *args: THIS_DIR.resolve())
-    def test_get_sources_with_stdin_filename_and_extend_exclude(self) -> None:
-        # Extend exclude shouldn't exclude stdin_filename since it is mimicking the
-        # file being passed directly. This is the same as
-        # test_exclude_for_issue_1572
-        path = THIS_DIR / "data" / "include_exclude_tests"
-        include = ""
-        extend_exclude = r"/exclude/|a\.py"
-        src = "-"
-        report = black.Report()
-        stdin_filename = str(path / "b/exclude/a.py")
-        expected = [Path(f"__BLACK_STDIN_FILENAME__{stdin_filename}")]
-        sources = list(
-            black.get_sources(
-                ctx=FakeContext(),
-                src=(src,),
-                quiet=True,
-                verbose=False,
-                include=re.compile(include),
-                exclude=re.compile(""),
-                extend_exclude=re.compile(extend_exclude),
-                force_exclude=None,
-                report=report,
-                stdin_filename=stdin_filename,
-            )
-        )
-        self.assertEqual(sorted(expected), sorted(sources))
-
-    @patch("black.find_project_root", lambda *args: THIS_DIR.resolve())
-    def test_get_sources_with_stdin_filename_and_force_exclude(self) -> None:
-        # Force exclude should exclude the file when passing it through
-        # stdin_filename
-        path = THIS_DIR / "data" / "include_exclude_tests"
-        include = ""
-        force_exclude = r"/exclude/|a\.py"
-        src = "-"
-        report = black.Report()
-        stdin_filename = str(path / "b/exclude/a.py")
-        sources = list(
-            black.get_sources(
-                ctx=FakeContext(),
-                src=(src,),
-                quiet=True,
-                verbose=False,
-                include=re.compile(include),
-                exclude=re.compile(""),
-                extend_exclude=None,
-                force_exclude=re.compile(force_exclude),
-                report=report,
-                stdin_filename=stdin_filename,
-            )
-        )
-        self.assertEqual([], sorted(sources))
-
     def test_reformat_one_with_stdin(self) -> None:
         with patch(
             "black.format_stdin_to_stdout",
@@ -1701,158 +1175,13 @@ def test_reformat_one_with_stdin_empty(self) -> None:
                 pass  # StringIO does not support detach
             assert output.getvalue() == ""
 
-    def test_gitignore_exclude(self) -> None:
-        path = THIS_DIR / "data" / "include_exclude_tests"
-        include = re.compile(r"\.pyi?$")
-        exclude = re.compile(r"")
-        report = black.Report()
-        gitignore = PathSpec.from_lines(
-            "gitwildmatch", ["exclude/", ".definitely_exclude"]
-        )
-        sources: List[Path] = []
-        expected = [
-            Path(path / "b/dont_exclude/a.py"),
-            Path(path / "b/dont_exclude/a.pyi"),
-        ]
-        this_abs = THIS_DIR.resolve()
-        sources.extend(
-            black.gen_python_files(
-                path.iterdir(),
-                this_abs,
-                include,
-                exclude,
-                None,
-                None,
-                report,
-                gitignore,
-                verbose=False,
-                quiet=False,
-            )
-        )
-        self.assertEqual(sorted(expected), sorted(sources))
-
-    def test_nested_gitignore(self) -> None:
-        path = Path(THIS_DIR / "data" / "nested_gitignore_tests")
-        include = re.compile(r"\.pyi?$")
-        exclude = re.compile(r"")
-        root_gitignore = black.files.get_gitignore(path)
-        report = black.Report()
-        expected: List[Path] = [
-            Path(path / "x.py"),
-            Path(path / "root/b.py"),
-            Path(path / "root/c.py"),
-            Path(path / "root/child/c.py"),
-        ]
-        this_abs = THIS_DIR.resolve()
-        sources = list(
-            black.gen_python_files(
-                path.iterdir(),
-                this_abs,
-                include,
-                exclude,
-                None,
-                None,
-                report,
-                root_gitignore,
-                verbose=False,
-                quiet=False,
-            )
-        )
-        self.assertEqual(sorted(expected), sorted(sources))
-
-    def test_invalid_gitignore(self) -> None:
-        path = THIS_DIR / "data" / "invalid_gitignore_tests"
-        empty_config = path / "pyproject.toml"
-        result = BlackRunner().invoke(
-            black.main, ["--verbose", "--config", str(empty_config), str(path)]
-        )
-        assert result.exit_code == 1
-        assert result.stderr_bytes is not None
-
-        gitignore = path / ".gitignore"
-        assert f"Could not parse {gitignore}" in result.stderr_bytes.decode()
-
-    def test_invalid_nested_gitignore(self) -> None:
-        path = THIS_DIR / "data" / "invalid_nested_gitignore_tests"
-        empty_config = path / "pyproject.toml"
-        result = BlackRunner().invoke(
-            black.main, ["--verbose", "--config", str(empty_config), str(path)]
-        )
-        assert result.exit_code == 1
-        assert result.stderr_bytes is not None
-
-        gitignore = path / "a" / ".gitignore"
-        assert f"Could not parse {gitignore}" in result.stderr_bytes.decode()
-
-    def test_empty_include(self) -> None:
-        path = THIS_DIR / "data" / "include_exclude_tests"
-        report = black.Report()
-        gitignore = PathSpec.from_lines("gitwildmatch", [])
-        empty = re.compile(r"")
-        sources: List[Path] = []
-        expected = [
-            Path(path / "b/exclude/a.pie"),
-            Path(path / "b/exclude/a.py"),
-            Path(path / "b/exclude/a.pyi"),
-            Path(path / "b/dont_exclude/a.pie"),
-            Path(path / "b/dont_exclude/a.py"),
-            Path(path / "b/dont_exclude/a.pyi"),
-            Path(path / "b/.definitely_exclude/a.pie"),
-            Path(path / "b/.definitely_exclude/a.py"),
-            Path(path / "b/.definitely_exclude/a.pyi"),
-            Path(path / ".gitignore"),
-            Path(path / "pyproject.toml"),
-        ]
-        this_abs = THIS_DIR.resolve()
-        sources.extend(
-            black.gen_python_files(
-                path.iterdir(),
-                this_abs,
-                empty,
-                re.compile(black.DEFAULT_EXCLUDES),
-                None,
-                None,
-                report,
-                gitignore,
-                verbose=False,
-                quiet=False,
-            )
-        )
-        self.assertEqual(sorted(expected), sorted(sources))
-
-    def test_extend_exclude(self) -> None:
-        path = THIS_DIR / "data" / "include_exclude_tests"
-        report = black.Report()
-        gitignore = PathSpec.from_lines("gitwildmatch", [])
-        sources: List[Path] = []
-        expected = [
-            Path(path / "b/exclude/a.py"),
-            Path(path / "b/dont_exclude/a.py"),
-        ]
-        this_abs = THIS_DIR.resolve()
-        sources.extend(
-            black.gen_python_files(
-                path.iterdir(),
-                this_abs,
-                re.compile(black.DEFAULT_INCLUDES),
-                re.compile(r"\.pyi$"),
-                re.compile(r"\.definitely_exclude"),
-                None,
-                report,
-                gitignore,
-                verbose=False,
-                quiet=False,
-            )
-        )
-        self.assertEqual(sorted(expected), sorted(sources))
-
-    def test_invalid_cli_regex(self) -> None:
-        for option in ["--include", "--exclude", "--extend-exclude", "--force-exclude"]:
-            self.invokeBlack(["-", option, "**()(!!*)"], exit_code=2)
-
-    def test_required_version_matches_version(self) -> None:
-        self.invokeBlack(
-            ["--required-version", black.__version__], exit_code=0, ignore_config=True
+    def test_invalid_cli_regex(self) -> None:
+        for option in ["--include", "--exclude", "--extend-exclude", "--force-exclude"]:
+            self.invokeBlack(["-", option, "**()(!!*)"], exit_code=2)
+
+    def test_required_version_matches_version(self) -> None:
+        self.invokeBlack(
+            ["--required-version", black.__version__], exit_code=0, ignore_config=True
         )
 
     def test_required_version_does_not_match_version(self) -> None:
@@ -1889,65 +1218,6 @@ def test_assert_equivalent_different_asts(self) -> None:
         with self.assertRaises(AssertionError):
             black.assert_equivalent("{}", "None")
 
-    def test_symlink_out_of_root_directory(self) -> None:
-        path = MagicMock()
-        root = THIS_DIR.resolve()
-        child = MagicMock()
-        include = re.compile(black.DEFAULT_INCLUDES)
-        exclude = re.compile(black.DEFAULT_EXCLUDES)
-        report = black.Report()
-        gitignore = PathSpec.from_lines("gitwildmatch", [])
-        # `child` should behave like a symlink which resolved path is clearly
-        # outside of the `root` directory.
-        path.iterdir.return_value = [child]
-        child.resolve.return_value = Path("/a/b/c")
-        child.as_posix.return_value = "/a/b/c"
-        child.is_symlink.return_value = True
-        try:
-            list(
-                black.gen_python_files(
-                    path.iterdir(),
-                    root,
-                    include,
-                    exclude,
-                    None,
-                    None,
-                    report,
-                    gitignore,
-                    verbose=False,
-                    quiet=False,
-                )
-            )
-        except ValueError as ve:
-            self.fail(f"`get_python_files_in_dir()` failed: {ve}")
-        path.iterdir.assert_called_once()
-        child.resolve.assert_called_once()
-        child.is_symlink.assert_called_once()
-        # `child` should behave like a strange file which resolved path is clearly
-        # outside of the `root` directory.
-        child.is_symlink.return_value = False
-        with self.assertRaises(ValueError):
-            list(
-                black.gen_python_files(
-                    path.iterdir(),
-                    root,
-                    include,
-                    exclude,
-                    None,
-                    None,
-                    report,
-                    gitignore,
-                    verbose=False,
-                    quiet=False,
-                )
-            )
-        path.iterdir.assert_called()
-        self.assertEqual(path.iterdir.call_count, 2)
-        child.resolve.assert_called()
-        self.assertEqual(child.resolve.call_count, 2)
-        child.is_symlink.assert_called()
-        self.assertEqual(child.is_symlink.call_count, 2)
-
     def test_shhh_click(self) -> None:
         try:
             from click import _unicodefun
@@ -2270,31 +1540,497 @@ def test_code_option_parent_config(self) -> None:
                 ), "Incorrect config loaded."
 
 
-with open(black.__file__, "r", encoding="utf-8") as _bf:
-    black_source_lines = _bf.readlines()
+class TestCaching:
+    def test_cache_broken_file(self) -> None:
+        mode = DEFAULT_MODE
+        with cache_dir() as workspace:
+            cache_file = get_cache_file(mode)
+            cache_file.write_text("this is not a pickle")
+            assert black.read_cache(mode) == {}
+            src = (workspace / "test.py").resolve()
+            src.write_text("print('hello')")
+            invokeBlack([str(src)])
+            cache = black.read_cache(mode)
+            assert str(src) in cache
 
+    def test_cache_single_file_already_cached(self) -> None:
+        mode = DEFAULT_MODE
+        with cache_dir() as workspace:
+            src = (workspace / "test.py").resolve()
+            src.write_text("print('hello')")
+            black.write_cache({}, [src], mode)
+            invokeBlack([str(src)])
+            assert src.read_text() == "print('hello')"
 
-def tracefunc(frame: types.FrameType, event: str, arg: Any) -> Callable:
-    """Show function calls `from black/__init__.py` as they happen.
+    @event_loop()
+    def test_cache_multiple_files(self) -> None:
+        mode = DEFAULT_MODE
+        with cache_dir() as workspace, patch(
+            "black.ProcessPoolExecutor", new=ThreadPoolExecutor
+        ):
+            one = (workspace / "one.py").resolve()
+            with one.open("w") as fobj:
+                fobj.write("print('hello')")
+            two = (workspace / "two.py").resolve()
+            with two.open("w") as fobj:
+                fobj.write("print('hello')")
+            black.write_cache({}, [one], mode)
+            invokeBlack([str(workspace)])
+            with one.open("r") as fobj:
+                assert fobj.read() == "print('hello')"
+            with two.open("r") as fobj:
+                assert fobj.read() == 'print("hello")\n'
+            cache = black.read_cache(mode)
+            assert str(one) in cache
+            assert str(two) in cache
 
-    Register this with `sys.settrace()` in a test you're debugging.
-    """
-    if event != "call":
-        return tracefunc
+    @pytest.mark.parametrize("color", [False, True], ids=["no-color", "with-color"])
+    def test_no_cache_when_writeback_diff(self, color: bool) -> None:
+        mode = DEFAULT_MODE
+        with cache_dir() as workspace:
+            src = (workspace / "test.py").resolve()
+            with src.open("w") as fobj:
+                fobj.write("print('hello')")
+            with patch("black.read_cache") as read_cache, patch(
+                "black.write_cache"
+            ) as write_cache:
+                cmd = [str(src), "--diff"]
+                if color:
+                    cmd.append("--color")
+                invokeBlack(cmd)
+                cache_file = get_cache_file(mode)
+                assert cache_file.exists() is False
+                write_cache.assert_not_called()
+                read_cache.assert_not_called()
 
-    stack = len(inspect.stack()) - 19
-    stack *= 2
-    filename = frame.f_code.co_filename
-    lineno = frame.f_lineno
-    func_sig_lineno = lineno - 1
-    funcname = black_source_lines[func_sig_lineno].strip()
-    while funcname.startswith("@"):
-        func_sig_lineno += 1
-        funcname = black_source_lines[func_sig_lineno].strip()
-    if "black/__init__.py" in filename:
-        print(f"{' ' * stack}{lineno}:{funcname}")
-    return tracefunc
+    @pytest.mark.parametrize("color", [False, True], ids=["no-color", "with-color"])
+    @event_loop()
+    def test_output_locking_when_writeback_diff(self, color: bool) -> None:
+        with cache_dir() as workspace:
+            for tag in range(0, 4):
+                src = (workspace / f"test{tag}.py").resolve()
+                with src.open("w") as fobj:
+                    fobj.write("print('hello')")
+            with patch("black.Manager", wraps=multiprocessing.Manager) as mgr:
+                cmd = ["--diff", str(workspace)]
+                if color:
+                    cmd.append("--color")
+                invokeBlack(cmd, exit_code=0)
+                # this isn't quite doing what we want, but if it _isn't_
+                # called then we cannot be using the lock it provides
+                mgr.assert_called()
 
+    def test_no_cache_when_stdin(self) -> None:
+        mode = DEFAULT_MODE
+        with cache_dir():
+            result = CliRunner().invoke(
+                black.main, ["-"], input=BytesIO(b"print('hello')")
+            )
+            assert not result.exit_code
+            cache_file = get_cache_file(mode)
+            assert not cache_file.exists()
 
-if __name__ == "__main__":
-    unittest.main(module="test_black")
+    def test_read_cache_no_cachefile(self) -> None:
+        mode = DEFAULT_MODE
+        with cache_dir():
+            assert black.read_cache(mode) == {}
+
+    def test_write_cache_read_cache(self) -> None:
+        mode = DEFAULT_MODE
+        with cache_dir() as workspace:
+            src = (workspace / "test.py").resolve()
+            src.touch()
+            black.write_cache({}, [src], mode)
+            cache = black.read_cache(mode)
+            assert str(src) in cache
+            assert cache[str(src)] == black.get_cache_info(src)
+
+    def test_filter_cached(self) -> None:
+        with TemporaryDirectory() as workspace:
+            path = Path(workspace)
+            uncached = (path / "uncached").resolve()
+            cached = (path / "cached").resolve()
+            cached_but_changed = (path / "changed").resolve()
+            uncached.touch()
+            cached.touch()
+            cached_but_changed.touch()
+            cache = {
+                str(cached): black.get_cache_info(cached),
+                str(cached_but_changed): (0.0, 0),
+            }
+            todo, done = black.filter_cached(
+                cache, {uncached, cached, cached_but_changed}
+            )
+            assert todo == {uncached, cached_but_changed}
+            assert done == {cached}
+
+    def test_write_cache_creates_directory_if_needed(self) -> None:
+        mode = DEFAULT_MODE
+        with cache_dir(exists=False) as workspace:
+            assert not workspace.exists()
+            black.write_cache({}, [], mode)
+            assert workspace.exists()
+
+    @event_loop()
+    def test_failed_formatting_does_not_get_cached(self) -> None:
+        mode = DEFAULT_MODE
+        with cache_dir() as workspace, patch(
+            "black.ProcessPoolExecutor", new=ThreadPoolExecutor
+        ):
+            failing = (workspace / "failing.py").resolve()
+            with failing.open("w") as fobj:
+                fobj.write("not actually python")
+            clean = (workspace / "clean.py").resolve()
+            with clean.open("w") as fobj:
+                fobj.write('print("hello")\n')
+            invokeBlack([str(workspace)], exit_code=123)
+            cache = black.read_cache(mode)
+            assert str(failing) not in cache
+            assert str(clean) in cache
+
+    def test_write_cache_write_fail(self) -> None:
+        mode = DEFAULT_MODE
+        with cache_dir(), patch.object(Path, "open") as mock:
+            mock.side_effect = OSError
+            black.write_cache({}, [], mode)
+
+    def test_read_cache_line_lengths(self) -> None:
+        mode = DEFAULT_MODE
+        short_mode = replace(DEFAULT_MODE, line_length=1)
+        with cache_dir() as workspace:
+            path = (workspace / "file.py").resolve()
+            path.touch()
+            black.write_cache({}, [path], mode)
+            one = black.read_cache(mode)
+            assert str(path) in one
+            two = black.read_cache(short_mode)
+            assert str(path) not in two
+
+
+def assert_collected_sources(
+    src: Sequence[Union[str, Path]],
+    expected: Sequence[Union[str, Path]],
+    *,
+    exclude: Optional[str] = None,
+    include: Optional[str] = None,
+    extend_exclude: Optional[str] = None,
+    force_exclude: Optional[str] = None,
+    stdin_filename: Optional[str] = None,
+) -> None:
+    gs_src = tuple(str(Path(s)) for s in src)
+    gs_expected = [Path(s) for s in expected]
+    gs_exclude = None if exclude is None else compile_pattern(exclude)
+    gs_include = DEFAULT_INCLUDE if include is None else compile_pattern(include)
+    gs_extend_exclude = (
+        None if extend_exclude is None else compile_pattern(extend_exclude)
+    )
+    gs_force_exclude = None if force_exclude is None else compile_pattern(force_exclude)
+    collected = black.get_sources(
+        ctx=FakeContext(),
+        src=gs_src,
+        quiet=False,
+        verbose=False,
+        include=gs_include,
+        exclude=gs_exclude,
+        extend_exclude=gs_extend_exclude,
+        force_exclude=gs_force_exclude,
+        report=black.Report(),
+        stdin_filename=stdin_filename,
+    )
+    assert sorted(list(collected)) == sorted(gs_expected)
+
+
+class TestFileCollection:
+    def test_include_exclude(self) -> None:
+        path = THIS_DIR / "data" / "include_exclude_tests"
+        src = [path]
+        expected = [
+            Path(path / "b/dont_exclude/a.py"),
+            Path(path / "b/dont_exclude/a.pyi"),
+        ]
+        assert_collected_sources(
+            src,
+            expected,
+            include=r"\.pyi?$",
+            exclude=r"/exclude/|/\.definitely_exclude/",
+        )
+
+    def test_gitignore_used_as_default(self) -> None:
+        base = Path(DATA_DIR / "include_exclude_tests")
+        expected = [
+            base / "b/.definitely_exclude/a.py",
+            base / "b/.definitely_exclude/a.pyi",
+        ]
+        src = [base / "b/"]
+        assert_collected_sources(src, expected, extend_exclude=r"/exclude/")
+
+    @patch("black.find_project_root", lambda *args: THIS_DIR.resolve())
+    def test_exclude_for_issue_1572(self) -> None:
+        # Exclude shouldn't touch files that were explicitly given to Black through the
+        # CLI. Exclude is supposed to only apply to the recursive discovery of files.
+        # https://github.com/psf/black/issues/1572
+        path = DATA_DIR / "include_exclude_tests"
+        src = [path / "b/exclude/a.py"]
+        expected = [path / "b/exclude/a.py"]
+        assert_collected_sources(src, expected, include="", exclude=r"/exclude/|a\.py")
+
+    def test_gitignore_exclude(self) -> None:
+        path = THIS_DIR / "data" / "include_exclude_tests"
+        include = re.compile(r"\.pyi?$")
+        exclude = re.compile(r"")
+        report = black.Report()
+        gitignore = PathSpec.from_lines(
+            "gitwildmatch", ["exclude/", ".definitely_exclude"]
+        )
+        sources: List[Path] = []
+        expected = [
+            Path(path / "b/dont_exclude/a.py"),
+            Path(path / "b/dont_exclude/a.pyi"),
+        ]
+        this_abs = THIS_DIR.resolve()
+        sources.extend(
+            black.gen_python_files(
+                path.iterdir(),
+                this_abs,
+                include,
+                exclude,
+                None,
+                None,
+                report,
+                gitignore,
+                verbose=False,
+                quiet=False,
+            )
+        )
+        assert sorted(expected) == sorted(sources)
+
+    def test_nested_gitignore(self) -> None:
+        path = Path(THIS_DIR / "data" / "nested_gitignore_tests")
+        include = re.compile(r"\.pyi?$")
+        exclude = re.compile(r"")
+        root_gitignore = black.files.get_gitignore(path)
+        report = black.Report()
+        expected: List[Path] = [
+            Path(path / "x.py"),
+            Path(path / "root/b.py"),
+            Path(path / "root/c.py"),
+            Path(path / "root/child/c.py"),
+        ]
+        this_abs = THIS_DIR.resolve()
+        sources = list(
+            black.gen_python_files(
+                path.iterdir(),
+                this_abs,
+                include,
+                exclude,
+                None,
+                None,
+                report,
+                root_gitignore,
+                verbose=False,
+                quiet=False,
+            )
+        )
+        assert sorted(expected) == sorted(sources)
+
+    def test_invalid_gitignore(self) -> None:
+        path = THIS_DIR / "data" / "invalid_gitignore_tests"
+        empty_config = path / "pyproject.toml"
+        result = BlackRunner().invoke(
+            black.main, ["--verbose", "--config", str(empty_config), str(path)]
+        )
+        assert result.exit_code == 1
+        assert result.stderr_bytes is not None
+
+        gitignore = path / ".gitignore"
+        assert f"Could not parse {gitignore}" in result.stderr_bytes.decode()
+
+    def test_invalid_nested_gitignore(self) -> None:
+        path = THIS_DIR / "data" / "invalid_nested_gitignore_tests"
+        empty_config = path / "pyproject.toml"
+        result = BlackRunner().invoke(
+            black.main, ["--verbose", "--config", str(empty_config), str(path)]
+        )
+        assert result.exit_code == 1
+        assert result.stderr_bytes is not None
+
+        gitignore = path / "a" / ".gitignore"
+        assert f"Could not parse {gitignore}" in result.stderr_bytes.decode()
+
+    def test_empty_include(self) -> None:
+        path = DATA_DIR / "include_exclude_tests"
+        src = [path]
+        expected = [
+            Path(path / "b/exclude/a.pie"),
+            Path(path / "b/exclude/a.py"),
+            Path(path / "b/exclude/a.pyi"),
+            Path(path / "b/dont_exclude/a.pie"),
+            Path(path / "b/dont_exclude/a.py"),
+            Path(path / "b/dont_exclude/a.pyi"),
+            Path(path / "b/.definitely_exclude/a.pie"),
+            Path(path / "b/.definitely_exclude/a.py"),
+            Path(path / "b/.definitely_exclude/a.pyi"),
+            Path(path / ".gitignore"),
+            Path(path / "pyproject.toml"),
+        ]
+        # Setting exclude explicitly to an empty string to block .gitignore usage.
+        assert_collected_sources(src, expected, include="", exclude="")
+
+    def test_extend_exclude(self) -> None:
+        path = DATA_DIR / "include_exclude_tests"
+        src = [path]
+        expected = [
+            Path(path / "b/exclude/a.py"),
+            Path(path / "b/dont_exclude/a.py"),
+        ]
+        assert_collected_sources(
+            src, expected, exclude=r"\.pyi$", extend_exclude=r"\.definitely_exclude"
+        )
+
+    def test_symlink_out_of_root_directory(self) -> None:
+        path = MagicMock()
+        root = THIS_DIR.resolve()
+        child = MagicMock()
+        include = re.compile(black.DEFAULT_INCLUDES)
+        exclude = re.compile(black.DEFAULT_EXCLUDES)
+        report = black.Report()
+        gitignore = PathSpec.from_lines("gitwildmatch", [])
+        # `child` should behave like a symlink which resolved path is clearly
+        # outside of the `root` directory.
+        path.iterdir.return_value = [child]
+        child.resolve.return_value = Path("/a/b/c")
+        child.as_posix.return_value = "/a/b/c"
+        child.is_symlink.return_value = True
+        try:
+            list(
+                black.gen_python_files(
+                    path.iterdir(),
+                    root,
+                    include,
+                    exclude,
+                    None,
+                    None,
+                    report,
+                    gitignore,
+                    verbose=False,
+                    quiet=False,
+                )
+            )
+        except ValueError as ve:
+            pytest.fail(f"`get_python_files_in_dir()` failed: {ve}")
+        path.iterdir.assert_called_once()
+        child.resolve.assert_called_once()
+        child.is_symlink.assert_called_once()
+        # `child` should behave like a strange file which resolved path is clearly
+        # outside of the `root` directory.
+        child.is_symlink.return_value = False
+        with pytest.raises(ValueError):
+            list(
+                black.gen_python_files(
+                    path.iterdir(),
+                    root,
+                    include,
+                    exclude,
+                    None,
+                    None,
+                    report,
+                    gitignore,
+                    verbose=False,
+                    quiet=False,
+                )
+            )
+        path.iterdir.assert_called()
+        assert path.iterdir.call_count == 2
+        child.resolve.assert_called()
+        assert child.resolve.call_count == 2
+        child.is_symlink.assert_called()
+        assert child.is_symlink.call_count == 2
+
+    @patch("black.find_project_root", lambda *args: THIS_DIR.resolve())
+    def test_get_sources_with_stdin(self) -> None:
+        src = ["-"]
+        expected = ["-"]
+        assert_collected_sources(src, expected, include="", exclude=r"/exclude/|a\.py")
+
+    @patch("black.find_project_root", lambda *args: THIS_DIR.resolve())
+    def test_get_sources_with_stdin_filename(self) -> None:
+        src = ["-"]
+        stdin_filename = str(THIS_DIR / "data/collections.py")
+        expected = [f"__BLACK_STDIN_FILENAME__{stdin_filename}"]
+        assert_collected_sources(
+            src,
+            expected,
+            exclude=r"/exclude/a\.py",
+            stdin_filename=stdin_filename,
+        )
+
+    @patch("black.find_project_root", lambda *args: THIS_DIR.resolve())
+    def test_get_sources_with_stdin_filename_and_exclude(self) -> None:
+        # Exclude shouldn't exclude stdin_filename since it is mimicking the
+        # file being passed directly. This is the same as
+        # test_exclude_for_issue_1572
+        path = DATA_DIR / "include_exclude_tests"
+        src = ["-"]
+        stdin_filename = str(path / "b/exclude/a.py")
+        expected = [f"__BLACK_STDIN_FILENAME__{stdin_filename}"]
+        assert_collected_sources(
+            src,
+            expected,
+            exclude=r"/exclude/|a\.py",
+            stdin_filename=stdin_filename,
+        )
+
+    @patch("black.find_project_root", lambda *args: THIS_DIR.resolve())
+    def test_get_sources_with_stdin_filename_and_extend_exclude(self) -> None:
+        # Extend exclude shouldn't exclude stdin_filename since it is mimicking the
+        # file being passed directly. This is the same as
+        # test_exclude_for_issue_1572
+        src = ["-"]
+        path = THIS_DIR / "data" / "include_exclude_tests"
+        stdin_filename = str(path / "b/exclude/a.py")
+        expected = [f"__BLACK_STDIN_FILENAME__{stdin_filename}"]
+        assert_collected_sources(
+            src,
+            expected,
+            extend_exclude=r"/exclude/|a\.py",
+            stdin_filename=stdin_filename,
+        )
+
+    @patch("black.find_project_root", lambda *args: THIS_DIR.resolve())
+    def test_get_sources_with_stdin_filename_and_force_exclude(self) -> None:
+        # Force exclude should exclude the file when passing it through
+        # stdin_filename
+        path = THIS_DIR / "data" / "include_exclude_tests"
+        stdin_filename = str(path / "b/exclude/a.py")
+        assert_collected_sources(
+            src=["-"],
+            expected=[],
+            force_exclude=r"/exclude/|a\.py",
+            stdin_filename=stdin_filename,
+        )
+
+
+with open(black.__file__, "r", encoding="utf-8") as _bf:
+    black_source_lines = _bf.readlines()
+
+
+def tracefunc(frame: types.FrameType, event: str, arg: Any) -> Callable:
+    """Show function calls `from black/__init__.py` as they happen.
+
+    Register this with `sys.settrace()` in a test you're debugging.
+    """
+    if event != "call":
+        return tracefunc
+
+    stack = len(inspect.stack()) - 19
+    stack *= 2
+    filename = frame.f_code.co_filename
+    lineno = frame.f_lineno
+    func_sig_lineno = lineno - 1
+    funcname = black_source_lines[func_sig_lineno].strip()
+    while funcname.startswith("@"):
+        func_sig_lineno += 1
+        funcname = black_source_lines[func_sig_lineno].strip()
+    if "black/__init__.py" in filename:
+        print(f"{' ' * stack}{lineno}:{funcname}")
+    return tracefunc
diff --git a/tests/test_format.py b/tests/test_format.py
index fc9678ad27c..a659382092a 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -1,16 +1,17 @@
+from dataclasses import replace
+from typing import Any, Iterator
 from unittest.mock import patch
 
-import black
 import pytest
-from parameterized import parameterized
 
+import black
 from tests.util import (
-    BlackBaseTestCase,
-    fs,
     DEFAULT_MODE,
+    PY36_VERSIONS,
+    THIS_DIR,
+    assert_format,
     dump_to_stderr,
     read_data,
-    THIS_DIR,
 )
 
 SIMPLE_CASES = [
@@ -113,33 +114,121 @@
 ]
 
 
-class TestSimpleFormat(BlackBaseTestCase):
-    @parameterized.expand(SIMPLE_CASES_PY2)
-    @pytest.mark.python2
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_simple_format_py2(self, filename: str) -> None:
-        self.check_file(filename, DEFAULT_MODE)
-
-    @parameterized.expand(SIMPLE_CASES)
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_simple_format(self, filename: str) -> None:
-        self.check_file(filename, DEFAULT_MODE)
-
-    @parameterized.expand(EXPERIMENTAL_STRING_PROCESSING_CASES)
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_experimental_format(self, filename: str) -> None:
-        self.check_file(filename, black.Mode(experimental_string_processing=True))
-
-    @parameterized.expand(SOURCES)
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_source_is_formatted(self, filename: str) -> None:
-        path = THIS_DIR.parent / filename
-        self.check_file(str(path), DEFAULT_MODE, data=False)
-
-    def check_file(self, filename: str, mode: black.Mode, *, data: bool = True) -> None:
-        source, expected = read_data(filename, data=data)
-        actual = fs(source, mode=mode)
-        self.assertFormatEqual(expected, actual)
-        if source != actual:
-            black.assert_equivalent(source, actual)
-            black.assert_stable(source, actual, mode)
+@pytest.fixture(autouse=True)
+def patch_dump_to_file(request: Any) -> Iterator[None]:
+    with patch("black.dump_to_file", dump_to_stderr):
+        yield
+
+
+def check_file(filename: str, mode: black.Mode, *, data: bool = True) -> None:
+    source, expected = read_data(filename, data=data)
+    assert_format(source, expected, mode, fast=False)
+
+
+@pytest.mark.parametrize("filename", SIMPLE_CASES_PY2)
+@pytest.mark.python2
+def test_simple_format_py2(filename: str) -> None:
+    check_file(filename, DEFAULT_MODE)
+
+
+@pytest.mark.parametrize("filename", SIMPLE_CASES)
+def test_simple_format(filename: str) -> None:
+    check_file(filename, DEFAULT_MODE)
+
+
+@pytest.mark.parametrize("filename", EXPERIMENTAL_STRING_PROCESSING_CASES)
+def test_experimental_format(filename: str) -> None:
+    check_file(filename, black.Mode(experimental_string_processing=True))
+
+
+@pytest.mark.parametrize("filename", SOURCES)
+def test_source_is_formatted(filename: str) -> None:
+    path = THIS_DIR.parent / filename
+    check_file(str(path), DEFAULT_MODE, data=False)
+
+
+# =============== #
+# Complex cases
+# ============= #
+
+
+def test_empty() -> None:
+    source = expected = ""
+    assert_format(source, expected)
+
+
+def test_pep_572() -> None:
+    source, expected = read_data("pep_572")
+    assert_format(source, expected, minimum_version=(3, 8))
+
+
+def test_pep_572_remove_parens() -> None:
+    source, expected = read_data("pep_572_remove_parens")
+    assert_format(source, expected, minimum_version=(3, 8))
+
+
+def test_pep_572_do_not_remove_parens() -> None:
+    source, expected = read_data("pep_572_do_not_remove_parens")
+    # the AST safety checks will fail, but that's expected, just make sure no
+    # parentheses are touched
+    assert_format(source, expected, fast=True)
+
+
+@pytest.mark.parametrize("major, minor", [(3, 9), (3, 10)])
+def test_pep_572_newer_syntax(major: int, minor: int) -> None:
+    source, expected = read_data(f"pep_572_py{major}{minor}")
+    assert_format(source, expected, minimum_version=(major, minor))
+
+
+def test_pep_570() -> None:
+    source, expected = read_data("pep_570")
+    assert_format(source, expected, minimum_version=(3, 8))
+
+
+def test_docstring_no_string_normalization() -> None:
+    """Like test_docstring but with string normalization off."""
+    source, expected = read_data("docstring_no_string_normalization")
+    mode = replace(DEFAULT_MODE, string_normalization=False)
+    assert_format(source, expected, mode)
+
+
+def test_long_strings_flag_disabled() -> None:
+    """Tests for turning off the string processing logic."""
+    source, expected = read_data("long_strings_flag_disabled")
+    mode = replace(DEFAULT_MODE, experimental_string_processing=False)
+    assert_format(source, expected, mode)
+
+
+def test_numeric_literals() -> None:
+    source, expected = read_data("numeric_literals")
+    mode = replace(DEFAULT_MODE, target_versions=PY36_VERSIONS)
+    assert_format(source, expected, mode)
+
+
+def test_numeric_literals_ignoring_underscores() -> None:
+    source, expected = read_data("numeric_literals_skip_underscores")
+    mode = replace(DEFAULT_MODE, target_versions=PY36_VERSIONS)
+    assert_format(source, expected, mode)
+
+
+@pytest.mark.python2
+def test_python2_print_function() -> None:
+    source, expected = read_data("python2_print_function")
+    mode = replace(DEFAULT_MODE, target_versions={black.TargetVersion.PY27})
+    assert_format(source, expected, mode)
+
+
+def test_stub() -> None:
+    mode = replace(DEFAULT_MODE, is_pyi=True)
+    source, expected = read_data("stub.pyi")
+    assert_format(source, expected, mode)
+
+
+def test_python38() -> None:
+    source, expected = read_data("python38")
+    assert_format(source, expected, minimum_version=(3, 8))
+
+
+def test_python39() -> None:
+    source, expected = read_data("python39")
+    assert_format(source, expected, minimum_version=(3, 9))
diff --git a/tests/util.py b/tests/util.py
index e83017f5ad3..84e98bb0fbd 100644
--- a/tests/util.py
+++ b/tests/util.py
@@ -1,58 +1,97 @@
 import os
+import sys
 import unittest
-from pathlib import Path
-from typing import Iterator, List, Tuple, Any
 from contextlib import contextmanager
 from functools import partial
+from pathlib import Path
+from typing import Any, Iterator, List, Optional, Tuple
 
 import black
-from black.output import out, err
 from black.debug import DebugVisitor
+from black.mode import TargetVersion
+from black.output import err, out
 
 THIS_DIR = Path(__file__).parent
+DATA_DIR = THIS_DIR / "data"
 PROJECT_ROOT = THIS_DIR.parent
 EMPTY_LINE = "# EMPTY LINE WITH WHITESPACE" + " (this comment will be removed)"
 DETERMINISTIC_HEADER = "[Deterministic header]"
 
+PY36_VERSIONS = {
+    TargetVersion.PY36,
+    TargetVersion.PY37,
+    TargetVersion.PY38,
+    TargetVersion.PY39,
+}
 
 DEFAULT_MODE = black.Mode()
 ff = partial(black.format_file_in_place, mode=DEFAULT_MODE, fast=True)
 fs = partial(black.format_str, mode=DEFAULT_MODE)
 
 
+def _assert_format_equal(expected: str, actual: str) -> None:
+    if actual != expected and not os.environ.get("SKIP_AST_PRINT"):
+        bdv: DebugVisitor[Any]
+        out("Expected tree:", fg="green")
+        try:
+            exp_node = black.lib2to3_parse(expected)
+            bdv = DebugVisitor()
+            list(bdv.visit(exp_node))
+        except Exception as ve:
+            err(str(ve))
+        out("Actual tree:", fg="red")
+        try:
+            exp_node = black.lib2to3_parse(actual)
+            bdv = DebugVisitor()
+            list(bdv.visit(exp_node))
+        except Exception as ve:
+            err(str(ve))
+
+    assert actual == expected
+
+
+def assert_format(
+    source: str,
+    expected: str,
+    mode: black.Mode = DEFAULT_MODE,
+    *,
+    fast: bool = False,
+    minimum_version: Optional[Tuple[int, int]] = None,
+) -> None:
+    """Convenience function to check that Black formats as expected.
+
+    You can pass @minimum_version if you're passing code with newer syntax to guard
+    safety guards so they don't just crash with a SyntaxError. Please note this is
+    separate from TargetVerson Mode configuration.
+    """
+    actual = black.format_str(source, mode=mode)
+    _assert_format_equal(expected, actual)
+    # It's not useful to run safety checks if we're expecting no changes anyway. The
+    # assertion right above will raise if reality does actually make changes. This just
+    # avoids wasted CPU cycles.
+    if not fast and source != expected:
+        # Unfortunately the AST equivalence check relies on the built-in ast module
+        # being able to parse the code being formatted. This doesn't always work out
+        # when checking modern code on older versions.
+        if minimum_version is None or sys.version_info >= minimum_version:
+            black.assert_equivalent(source, actual)
+        black.assert_stable(source, actual, mode=mode)
+
+
 def dump_to_stderr(*output: str) -> str:
     return "\n" + "\n".join(output) + "\n"
 
 
 class BlackBaseTestCase(unittest.TestCase):
-    maxDiff = None
-    _diffThreshold = 2 ** 20
-
     def assertFormatEqual(self, expected: str, actual: str) -> None:
-        if actual != expected and not os.environ.get("SKIP_AST_PRINT"):
-            bdv: DebugVisitor[Any]
-            out("Expected tree:", fg="green")
-            try:
-                exp_node = black.lib2to3_parse(expected)
-                bdv = DebugVisitor()
-                list(bdv.visit(exp_node))
-            except Exception as ve:
-                err(str(ve))
-            out("Actual tree:", fg="red")
-            try:
-                exp_node = black.lib2to3_parse(actual)
-                bdv = DebugVisitor()
-                list(bdv.visit(exp_node))
-            except Exception as ve:
-                err(str(ve))
-        self.assertMultiLineEqual(expected, actual)
+        _assert_format_equal(expected, actual)
 
 
 def read_data(name: str, data: bool = True) -> Tuple[str, str]:
     """read_data('test_name') -> 'input', 'output'"""
     if not name.endswith((".py", ".pyi", ".out", ".diff")):
         name += ".py"
-    base_dir = THIS_DIR / "data" if data else PROJECT_ROOT
+    base_dir = DATA_DIR if data else PROJECT_ROOT
     return read_data_from_file(base_dir / name)
 
 

From 872bb9474efe683efaed1626c4c0172738634f28 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Mon, 4 Oct 2021 20:36:57 -0400
Subject: [PATCH 0311/1034] Bump typed-ast minimum to 1.4.3 for 3.10 compat
 (#2519)

---
 CHANGES.md   | 1 +
 Pipfile      | 2 +-
 Pipfile.lock | 6 +++---
 setup.py     | 2 +-
 4 files changed, 6 insertions(+), 5 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 04e9edf692c..f5b11de4803 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -5,6 +5,7 @@
 ### _Black_
 
 - Add new `--workers` parameter (#2514)
+- Bumped typed-ast version minimum to 1.4.3 for 3.10 compatiblity (#2519)
 
 ### _Blackd_
 
diff --git a/Pipfile b/Pipfile
index 534ca50fa5d..90e8f62d666 100644
--- a/Pipfile
+++ b/Pipfile
@@ -44,7 +44,7 @@ mypy_extensions = ">=0.4.3"
 pathspec = ">=0.8.1"
 regex = ">=2020.1.8"
 tomli = ">=0.2.6, <2.0.0"
-typed-ast = "==1.4.2"
+typed-ast = "==1.4.3"
 typing_extensions = {markers = "python_version < '3.10'", version = ">=3.10.0.0"}
 black = {editable = true,extras = ["d"],path = "."}
 dataclasses = {markers = "python_version < '3.7'", version = ">0.1.3"}
diff --git a/Pipfile.lock b/Pipfile.lock
index 280e6498af1..2ddeca88fff 100644
--- a/Pipfile.lock
+++ b/Pipfile.lock
@@ -1,7 +1,7 @@
 {
     "_meta": {
         "hash": {
-            "sha256": "6dbdff058fac8e6492f9d64194e98e48e062946ec4c06f9bb7df517d1dd89ce8"
+            "sha256": "4baa020356174f89177af103f1966928e7b9c2a69df3a9d4e8070eb83ee19387"
         },
         "pipfile-spec": 6,
         "requires": {},
@@ -311,7 +311,7 @@
                 "sha256:e683e409e5c45d5c9082dc1daf13f6374300806240719f95dc783d1fc942af10"
             ],
             "index": "pypi",
-            "version": "==1.4.2"
+            "version": "==1.4.3"
         },
         "typing-extensions": {
             "hashes": [
@@ -1484,7 +1484,7 @@
                 "sha256:e683e409e5c45d5c9082dc1daf13f6374300806240719f95dc783d1fc942af10"
             ],
             "index": "pypi",
-            "version": "==1.4.2"
+            "version": "==1.4.3"
         },
         "types-dataclasses": {
             "hashes": [
diff --git a/setup.py b/setup.py
index 015f321eaa9..de84dc37bb8 100644
--- a/setup.py
+++ b/setup.py
@@ -88,7 +88,7 @@ def get_long_description() -> str:
     extras_require={
         "d": ["aiohttp>=3.7.4"],
         "colorama": ["colorama>=0.4.3"],
-        "python2": ["typed-ast>=1.4.2"],
+        "python2": ["typed-ast>=1.4.3"],
         "uvloop": ["uvloop>=0.15.2"],
         "jupyter": ["ipython>=7.8.0", "tokenize-rt>=3.2.0"],
     },

From 3b2a7d196bc1984aed194cca26a7900968ce4409 Mon Sep 17 00:00:00 2001
From: Mathieu Kniewallner <mathieu.kniewallner@gmail.com>
Date: Tue, 5 Oct 2021 23:22:56 +0200
Subject: [PATCH 0312/1034] chore(ci): use official Python 3.10 (#2521)

Python 3.10 (final) was released yesterday and is now available on GHA!
---
 .github/workflows/fuzz.yml   | 2 +-
 .github/workflows/primer.yml | 2 +-
 .github/workflows/test.yml   | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/fuzz.yml b/.github/workflows/fuzz.yml
index 6b3ca6bb068..146277a7312 100644
--- a/.github/workflows/fuzz.yml
+++ b/.github/workflows/fuzz.yml
@@ -15,7 +15,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.6", "3.7", "3.8", "3.9", "3.10-dev"]
+        python-version: ["3.6", "3.7", "3.8", "3.9", "3.10"]
 
     steps:
       - uses: actions/checkout@v2
diff --git a/.github/workflows/primer.yml b/.github/workflows/primer.yml
index 01eb4ef6187..5fa6ac066e3 100644
--- a/.github/workflows/primer.yml
+++ b/.github/workflows/primer.yml
@@ -24,7 +24,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.6", "3.7", "3.8", "3.9", "3.10-dev"]
+        python-version: ["3.6", "3.7", "3.8", "3.9", "3.10"]
         os: [ubuntu-latest, windows-latest]
 
     steps:
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 8e6b4a7a72d..296ac34a3fb 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -24,7 +24,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.6", "3.7", "3.8", "3.9", "3.10-dev"]
+        python-version: ["3.6", "3.7", "3.8", "3.9", "3.10"]
         os: [ubuntu-latest, macOS-latest, windows-latest]
 
     steps:

From 2f3fa1f6d0cbc2a3f31c7440c422da173b068e7b Mon Sep 17 00:00:00 2001
From: Zac Hatfield-Dodds <zac.hatfield.dodds@gmail.com>
Date: Tue, 12 Oct 2021 15:45:58 +1100
Subject: [PATCH 0313/1034] Fix feature detection for positional-only arguments
 in lambdas (#2532)

---
 CHANGES.md            | 1 +
 src/black/__init__.py | 6 +++++-
 tests/test_black.py   | 4 ++++
 3 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index f5b11de4803..864f0a54410 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -5,6 +5,7 @@
 ### _Black_
 
 - Add new `--workers` parameter (#2514)
+- Fixed feature detection for positional-only arguments in lambdas (#2532)
 - Bumped typed-ast version minimum to 1.4.3 for 3.10 compatiblity (#2519)
 
 ### _Blackd_
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 83a39234d38..fdbaf040d64 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -1123,7 +1123,11 @@ def get_features_used(node: Node) -> Set[Feature]:
                 features.add(Feature.NUMERIC_UNDERSCORES)
 
         elif n.type == token.SLASH:
-            if n.parent and n.parent.type in {syms.typedargslist, syms.arglist}:
+            if n.parent and n.parent.type in {
+                syms.typedargslist,
+                syms.arglist,
+                syms.varargslist,
+            }:
                 features.add(Feature.POS_ONLY_ARGUMENTS)
 
         elif n.type == token.COLONEQUAL:
diff --git a/tests/test_black.py b/tests/test_black.py
index f25db1b73d1..beb56cf1fdb 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -805,6 +805,10 @@ def test_get_features_used(self) -> None:
         self.assertEqual(black.get_features_used(node), set())
         node = black.lib2to3_parse(expected)
         self.assertEqual(black.get_features_used(node), set())
+        node = black.lib2to3_parse("lambda a, /, b: ...")
+        self.assertEqual(black.get_features_used(node), {Feature.POS_ONLY_ARGUMENTS})
+        node = black.lib2to3_parse("def fn(a, /, b): ...")
+        self.assertEqual(black.get_features_used(node), {Feature.POS_ONLY_ARGUMENTS})
 
     def test_get_future_imports(self) -> None:
         node = black.lib2to3_parse("\n")

From 847d468b828faff7daae297d8a20d899d2259824 Mon Sep 17 00:00:00 2001
From: Marco Edward Gorelli <marcogorelli@protonmail.com>
Date: Tue, 19 Oct 2021 18:52:10 +0100
Subject: [PATCH 0314/1034] bump sphinx so it works on Python3.10 (#2546)

---
 docs/requirements.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index 4c5b700412a..296efc5cc84 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,6 +1,6 @@
 # Used by ReadTheDocs; pinned requirements for stability.
 
 myst-parser==0.15.1
-Sphinx==4.1.2
+Sphinx==4.2.0
 sphinxcontrib-programoutput==0.17
 sphinx_copybutton==0.4.0

From c75abed63ef284d7de54db87777951d6c668eefc Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Thu, 21 Oct 2021 08:02:38 -0700
Subject: [PATCH 0315/1034] Define a stability policy (#2529)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fixes #2394. Eventually fixes #517.

This is essentially @pradyunsg's suggestion from #2394. I suggest that at the
same time we start the formal stability policy, we take a few other disruptive steps
and drop Python 2 and the "b" marker.

Co-authored-by: Pradyun Gedam <pradyunsg@gmail.com>
Co-authored-by: Łukasz Langa <lukasz@langa.pl>
---
 CHANGES.md                          |  1 +
 docs/faq.md                         | 12 +++++++++---
 docs/the_black_code_style/index.rst | 30 ++++++++++++++++++++++++++---
 3 files changed, 37 insertions(+), 6 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 864f0a54410..2a3a60f82c6 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -4,6 +4,7 @@
 
 ### _Black_
 
+- Document stability policy, that will apply for non-beta releases (#2529)
 - Add new `--workers` parameter (#2514)
 - Fixed feature detection for positional-only arguments in lambdas (#2532)
 - Bumped typed-ast version minimum to 1.4.3 for 3.10 compatiblity (#2519)
diff --git a/docs/faq.md b/docs/faq.md
index c361addf7ae..9fe53922b6d 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -31,6 +31,10 @@ pragmatism. However, _Black_ is still in beta so style changes are both planned
 still proposed on the issue tracker. See
 [The Black Code Style](the_black_code_style/index.rst) for more details.
 
+Starting in 2022, the formatting output will be stable for the releases made in the same
+year (other than unintentional bugs). It is possible to opt-in to the latest formatting
+styles, using the `--future` flag.
+
 ## Why is my file not formatted?
 
 Most likely because it is ignored in `.gitignore` or excluded with configuration. See
@@ -71,9 +75,11 @@ disabled-by-default counterpart W504. E203 should be disabled while changes are
 ## Does Black support Python 2?
 
 For formatting, yes! [Install](getting_started.md#installation) with the `python2` extra
-to format Python 2 files too! There are no current plans to drop support, but most
-likely it is bound to happen. Sometime. Eventually. In terms of running _Black_ though,
-Python 3.6 or newer is required.
+to format Python 2 files too! In terms of running _Black_ though, Python 3.6 or newer is
+required.
+
+Note that this support will be dropped in the first stable release, expected for
+January 2022. See [The Black Code Style](the_black_code_style/index.rst) for details.
 
 ## Why does my linter or typechecker complain after I format my code?
 
diff --git a/docs/the_black_code_style/index.rst b/docs/the_black_code_style/index.rst
index 4693437be8b..7c2e1753937 100644
--- a/docs/the_black_code_style/index.rst
+++ b/docs/the_black_code_style/index.rst
@@ -9,9 +9,33 @@ The Black Code Style
 
 *Black* is a PEP 8 compliant opinionated formatter with its own style.
 
-It should be noted that while keeping the style unchanged throughout releases is a
-goal, the *Black* code style isn't set in stone. Sometimes it's modified in response to
-user feedback or even changes to the Python language!
+While keeping the style unchanged throughout releases has always been a goal,
+the *Black* code style isn't set in stone. It evolves to accomodate for new features
+in the Python language and, ocassionally, in response to user feedback.
+
+Stability Policy
+----------------
+
+The following policy applies for the *Black* code style, in non pre-release
+versions of *Black*:
+
+- The same code, formatted with the same options, will produce the same
+  output for all releases in a given calendar year.
+
+  This means projects can safely use `black ~= 22.0` without worrying about
+  major formatting changes disrupting their project in 2022. We may still
+  fix bugs where *Black* crashes on some code, and make other improvements
+  that do not affect formatting.
+
+- The first release in a new calendar year *may* contain formatting changes,
+  although these will be minimised as much as possible. This is to allow for
+  improved formatting enabled by newer Python language syntax as well as due
+  to improvements in the formatting logic.
+
+- The ``--future`` flag is exempt from this policy. There are no guarentees
+  around the stability of the output with that flag passed into *Black*. This
+  flag is intended for allowing experimentation with the proposed changes to
+  the *Black* code style.
 
 Documentation for both the current and future styles can be found:
 

From da8a5bb1895e5434695d9dc2d844119cd8f88524 Mon Sep 17 00:00:00 2001
From: Nipunn Koorapati <nipunn1313@gmail.com>
Date: Thu, 21 Oct 2021 19:38:39 -0700
Subject: [PATCH 0316/1034] Disallow any Generics on mypy except in
 black_primer (#2556)

Only black_primer needs the disallowal - means we'll
get better typing everywhere else.
---
 mypy.ini                |  8 ++++++--
 src/black/__init__.py   | 10 +++++-----
 src/black_primer/lib.py |  2 +-
 tests/test_black.py     |  4 +++-
 tests/test_primer.py    |  6 ++++--
 5 files changed, 19 insertions(+), 11 deletions(-)

diff --git a/mypy.ini b/mypy.ini
index 7e563e6f696..dabef458341 100644
--- a/mypy.ini
+++ b/mypy.ini
@@ -22,8 +22,7 @@ strict_optional=True
 warn_no_return=True
 warn_redundant_casts=True
 warn_unused_ignores=True
-# Until we're not supporting 3.6 primer needs this
-disallow_any_generics=False
+disallow_any_generics=True
 
 # The following are off by default.  Flip them on if you feel
 # adventurous.
@@ -35,6 +34,11 @@ cache_dir=/dev/null
 
 [mypy-aiohttp.*]
 follow_imports=skip
+
+[mypy-black_primer.*]
+# Until we're not supporting 3.6 primer needs this
+disallow_any_generics=False
+
 [mypy-black]
 # The following is because of `patch_click()`. Remove when
 # we drop Python 3.6 support.
diff --git a/src/black/__init__.py b/src/black/__init__.py
index fdbaf040d64..f01e449ea05 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -170,7 +170,7 @@ def validate_regex(
     ctx: click.Context,
     param: click.Parameter,
     value: Optional[str],
-) -> Optional[Pattern]:
+) -> Optional[Pattern[str]]:
     try:
         return re_compile_maybe_verbose(value) if value is not None else None
     except re.error:
@@ -388,10 +388,10 @@ def main(
     quiet: bool,
     verbose: bool,
     required_version: str,
-    include: Pattern,
-    exclude: Optional[Pattern],
-    extend_exclude: Optional[Pattern],
-    force_exclude: Optional[Pattern],
+    include: Pattern[str],
+    exclude: Optional[Pattern[str]],
+    extend_exclude: Optional[Pattern[str]],
+    force_exclude: Optional[Pattern[str]],
     stdin_filename: Optional[str],
     workers: int,
     src: Tuple[str, ...],
diff --git a/src/black_primer/lib.py b/src/black_primer/lib.py
index 7494ae6dc7d..c7842797485 100644
--- a/src/black_primer/lib.py
+++ b/src/black_primer/lib.py
@@ -258,7 +258,7 @@ async def git_checkout_or_rebase(
 
 
 def handle_PermissionError(
-    func: Callable, path: Path, exc: Tuple[Any, Any, Any]
+    func: Callable[..., None], path: Path, exc: Tuple[Any, Any, Any]
 ) -> None:
     """
     Handle PermissionError during shutil.rmtree.
diff --git a/tests/test_black.py b/tests/test_black.py
index beb56cf1fdb..1fc63c942e9 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -2018,7 +2018,9 @@ def test_get_sources_with_stdin_filename_and_force_exclude(self) -> None:
     black_source_lines = _bf.readlines()
 
 
-def tracefunc(frame: types.FrameType, event: str, arg: Any) -> Callable:
+def tracefunc(
+    frame: types.FrameType, event: str, arg: Any
+) -> Callable[[types.FrameType, str, Any], Any]:
     """Show function calls `from black/__init__.py` as they happen.
 
     Register this with `sys.settrace()` in a test you're debugging.
diff --git a/tests/test_primer.py b/tests/test_primer.py
index e7f99fdb0c2..dc30a7a2244 100644
--- a/tests/test_primer.py
+++ b/tests/test_primer.py
@@ -11,7 +11,7 @@
 from platform import system
 from subprocess import CalledProcessError
 from tempfile import TemporaryDirectory, gettempdir
-from typing import Any, Callable, Generator, Iterator, Tuple
+from typing import Any, Callable, Iterator, Tuple
 from unittest.mock import Mock, patch
 
 from click.testing import CliRunner
@@ -44,7 +44,9 @@
 
 
 @contextmanager
-def capture_stdout(command: Callable, *args: Any, **kwargs: Any) -> Generator:
+def capture_stdout(
+    command: Callable[..., Any], *args: Any, **kwargs: Any
+) -> Iterator[str]:
     old_stdout, sys.stdout = sys.stdout, StringIO()
     try:
         command(*args, **kwargs)

From 62ed5389fca51384721245ff1c2f1c62a13a04ff Mon Sep 17 00:00:00 2001
From: Nipunn Koorapati <nipunn1313@gmail.com>
Date: Thu, 21 Oct 2021 20:59:48 -0700
Subject: [PATCH 0317/1034] Remove some unneeded exceptions from mypy.ini
 (#2557)

---
 mypy.ini              | 8 --------
 src/black/__init__.py | 2 +-
 2 files changed, 1 insertion(+), 9 deletions(-)

diff --git a/mypy.ini b/mypy.ini
index dabef458341..6e8b7906e1d 100644
--- a/mypy.ini
+++ b/mypy.ini
@@ -32,14 +32,6 @@ check_untyped_defs=True
 # No incremental mode
 cache_dir=/dev/null
 
-[mypy-aiohttp.*]
-follow_imports=skip
-
 [mypy-black_primer.*]
 # Until we're not supporting 3.6 primer needs this
 disallow_any_generics=False
-
-[mypy-black]
-# The following is because of `patch_click()`. Remove when
-# we drop Python 3.6 support.
-warn_unused_ignores=False
diff --git a/src/black/__init__.py b/src/black/__init__.py
index f01e449ea05..5c6cb672aa2 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -1287,7 +1287,7 @@ def patch_click() -> None:
     """
     try:
         from click import core
-        from click import _unicodefun  # type: ignore
+        from click import _unicodefun
     except ModuleNotFoundError:
         return
 

From 26970742b76ddfd921fa36e4005738048477c952 Mon Sep 17 00:00:00 2001
From: Marco Edward Gorelli <marcogorelli@protonmail.com>
Date: Wed, 27 Oct 2021 15:36:10 +0100
Subject: [PATCH 0318/1034] Refactor Jupyter magic handling (#2545)

---
 src/black/handle_ipynb_magics.py | 72 ++++++++++++++++----------------
 1 file changed, 37 insertions(+), 35 deletions(-)

diff --git a/src/black/handle_ipynb_magics.py b/src/black/handle_ipynb_magics.py
index 63c8aafe35b..f10eaed4f3e 100644
--- a/src/black/handle_ipynb_magics.py
+++ b/src/black/handle_ipynb_magics.py
@@ -39,18 +39,18 @@
 )
 NON_PYTHON_CELL_MAGICS = frozenset(
     (
-        "%%bash",
-        "%%html",
-        "%%javascript",
-        "%%js",
-        "%%latex",
-        "%%markdown",
-        "%%perl",
-        "%%ruby",
-        "%%script",
-        "%%sh",
-        "%%svg",
-        "%%writefile",
+        "bash",
+        "html",
+        "javascript",
+        "js",
+        "latex",
+        "markdown",
+        "perl",
+        "ruby",
+        "script",
+        "sh",
+        "svg",
+        "writefile",
     )
 )
 TOKEN_HEX = secrets.token_hex
@@ -230,10 +230,11 @@ def replace_cell_magics(src: str) -> Tuple[str, List[Replacement]]:
     cell_magic_finder.visit(tree)
     if cell_magic_finder.cell_magic is None:
         return src, replacements
-    if cell_magic_finder.cell_magic.header.split()[0] in NON_PYTHON_CELL_MAGICS:
+    if cell_magic_finder.cell_magic.name in NON_PYTHON_CELL_MAGICS:
         raise NothingChanged
-    mask = get_token(src, cell_magic_finder.cell_magic.header)
-    replacements.append(Replacement(mask=mask, src=cell_magic_finder.cell_magic.header))
+    header = cell_magic_finder.cell_magic.header
+    mask = get_token(src, header)
+    replacements.append(Replacement(mask=mask, src=header))
     return f"{mask}\n{cell_magic_finder.cell_magic.body}", replacements
 
 
@@ -311,11 +312,26 @@ def _is_ipython_magic(node: ast.expr) -> TypeGuard[ast.Attribute]:
     )
 
 
+def _get_str_args(args: List[ast.expr]) -> List[str]:
+    str_args = []
+    for arg in args:
+        assert isinstance(arg, ast.Str)
+        str_args.append(arg.s)
+    return str_args
+
+
 @dataclasses.dataclass(frozen=True)
 class CellMagic:
-    header: str
+    name: str
+    params: Optional[str]
     body: str
 
+    @property
+    def header(self) -> str:
+        if self.params:
+            return f"%%{self.name} {self.params}"
+        return f"%%{self.name}"
+
 
 @dataclasses.dataclass
 class CellMagicFinder(ast.NodeVisitor):
@@ -345,14 +361,8 @@ def visit_Expr(self, node: ast.Expr) -> None:
             and _is_ipython_magic(node.value.func)
             and node.value.func.attr == "run_cell_magic"
         ):
-            args = []
-            for arg in node.value.args:
-                assert isinstance(arg, ast.Str)
-                args.append(arg.s)
-            header = f"%%{args[0]}"
-            if args[1]:
-                header += f" {args[1]}"
-            self.cell_magic = CellMagic(header=header, body=args[2])
+            args = _get_str_args(node.value.args)
+            self.cell_magic = CellMagic(name=args[0], params=args[1], body=args[2])
         self.generic_visit(node)
 
 
@@ -404,12 +414,8 @@ def visit_Assign(self, node: ast.Assign) -> None:
             and _is_ipython_magic(node.value.func)
             and node.value.func.attr == "getoutput"
         ):
-            args = []
-            for arg in node.value.args:
-                assert isinstance(arg, ast.Str)
-                args.append(arg.s)
-            assert args
-            src = f"!{args[0]}"
+            (arg,) = _get_str_args(node.value.args)
+            src = f"!{arg}"
             self.magics[node.value.lineno].append(
                 OffsetAndMagic(node.value.col_offset, src)
             )
@@ -435,11 +441,7 @@ def visit_Expr(self, node: ast.Expr) -> None:
         and we look for instances of any of the latter.
         """
         if isinstance(node.value, ast.Call) and _is_ipython_magic(node.value.func):
-            args = []
-            for arg in node.value.args:
-                assert isinstance(arg, ast.Str)
-                args.append(arg.s)
-            assert args
+            args = _get_str_args(node.value.args)
             if node.value.func.attr == "run_line_magic":
                 if args[0] == "pinfo":
                     src = f"?{args[1]}"

From aedb4ff7f061b321ea5804bc4fc4943c52c6a786 Mon Sep 17 00:00:00 2001
From: Nipunn Koorapati <nipunn1313@gmail.com>
Date: Wed, 27 Oct 2021 07:37:20 -0700
Subject: [PATCH 0319/1034] Print out line diff on test failure (#2552)

It currently prints both ASTs - this also
adds the line diff, making it much easier to visualize
the changes as well. Not too verbose since it's only a diff.
---
 tests/util.py | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/tests/util.py b/tests/util.py
index 84e98bb0fbd..8755111f7c5 100644
--- a/tests/util.py
+++ b/tests/util.py
@@ -9,7 +9,7 @@
 import black
 from black.debug import DebugVisitor
 from black.mode import TargetVersion
-from black.output import err, out
+from black.output import diff, err, out
 
 THIS_DIR = Path(__file__).parent
 DATA_DIR = THIS_DIR / "data"
@@ -47,6 +47,9 @@ def _assert_format_equal(expected: str, actual: str) -> None:
         except Exception as ve:
             err(str(ve))
 
+    if actual != expected:
+        out(diff(expected, actual, "expected", "actual"))
+
     assert actual == expected
 
 

From 467efe15562e3bad88b1eb3bc11f76b5b9a68816 Mon Sep 17 00:00:00 2001
From: Nipunn Koorapati <nipunn1313@gmail.com>
Date: Wed, 27 Oct 2021 11:31:34 -0700
Subject: [PATCH 0320/1034] Add --projects cli flag to black-primer (#2555)

* Add --projects cli flag to black-primer

Makes it possible to run a subset of projects on black primer

* Refactor into click callback
---
 CHANGES.md              |  1 +
 mypy.ini                |  4 ++++
 src/black_primer/cli.py | 43 +++++++++++++++++++++++++++++++++-
 src/black_primer/lib.py | 11 +++++----
 tests/test_format.py    |  2 ++
 tests/test_primer.py    | 51 +++++++++++++++++++++++++++++++++++++++--
 6 files changed, 104 insertions(+), 8 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 2a3a60f82c6..a8307ee61ec 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -8,6 +8,7 @@
 - Add new `--workers` parameter (#2514)
 - Fixed feature detection for positional-only arguments in lambdas (#2532)
 - Bumped typed-ast version minimum to 1.4.3 for 3.10 compatiblity (#2519)
+- Add primer support for --projects (#2555)
 
 ### _Blackd_
 
diff --git a/mypy.ini b/mypy.ini
index 6e8b7906e1d..62c1c7fefaa 100644
--- a/mypy.ini
+++ b/mypy.ini
@@ -35,3 +35,7 @@ cache_dir=/dev/null
 [mypy-black_primer.*]
 # Until we're not supporting 3.6 primer needs this
 disallow_any_generics=False
+
+[mypy-tests.test_primer]
+# Until we're not supporting 3.6 primer needs this
+disallow_any_generics=False
diff --git a/src/black_primer/cli.py b/src/black_primer/cli.py
index 8360fc3c703..2395d35886a 100644
--- a/src/black_primer/cli.py
+++ b/src/black_primer/cli.py
@@ -1,13 +1,14 @@
 # coding=utf8
 
 import asyncio
+import json
 import logging
 import sys
 from datetime import datetime
 from pathlib import Path
 from shutil import rmtree, which
 from tempfile import gettempdir
-from typing import Any, Union, Optional
+from typing import Any, List, Optional, Union
 
 import click
 
@@ -42,12 +43,42 @@ def _handle_debug(
     return debug
 
 
+def load_projects(config_path: Path) -> List[str]:
+    with open(config_path) as config:
+        return sorted(json.load(config)["projects"].keys())
+
+
+# Unfortunately does import time file IO - but appears to be the only
+# way to get `black-primer --help` to show projects list
+DEFAULT_PROJECTS = load_projects(DEFAULT_CONFIG)
+
+
+def _projects_callback(
+    ctx: click.core.Context,
+    param: Optional[Union[click.core.Option, click.core.Parameter]],
+    projects: str,
+) -> List[str]:
+    requested_projects = set(projects.split(","))
+    available_projects = set(
+        DEFAULT_PROJECTS
+        if str(DEFAULT_CONFIG) == ctx.params["config"]
+        else load_projects(ctx.params["config"])
+    )
+
+    unavailable = requested_projects - available_projects
+    if unavailable:
+        LOG.error(f"Projects not found: {unavailable}. Available: {available_projects}")
+
+    return sorted(requested_projects & available_projects)
+
+
 async def async_main(
     config: str,
     debug: bool,
     keep: bool,
     long_checkouts: bool,
     no_diff: bool,
+    projects: List[str],
     rebase: bool,
     workdir: str,
     workers: int,
@@ -66,6 +97,7 @@ async def async_main(
             config,
             work_path,
             workers,
+            projects,
             keep,
             long_checkouts,
             rebase,
@@ -88,6 +120,8 @@ async def async_main(
     type=click.Path(exists=True),
     show_default=True,
     help="JSON config file path",
+    # Eager - because config path is used by other callback options
+    is_eager=True,
 )
 @click.option(
     "--debug",
@@ -116,6 +150,13 @@ async def async_main(
     show_default=True,
     help="Disable showing source file changes in black output",
 )
+@click.option(
+    "--projects",
+    default=",".join(DEFAULT_PROJECTS),
+    callback=_projects_callback,
+    show_default=True,
+    help="Comma separated list of projects to run",
+)
 @click.option(
     "-R",
     "--rebase",
diff --git a/src/black_primer/lib.py b/src/black_primer/lib.py
index c7842797485..351501673f8 100644
--- a/src/black_primer/lib.py
+++ b/src/black_primer/lib.py
@@ -283,16 +283,16 @@ def handle_PermissionError(
 
 async def load_projects_queue(
     config_path: Path,
+    projects_to_run: List[str],
 ) -> Tuple[Dict[str, Any], asyncio.Queue]:
     """Load project config and fill queue with all the project names"""
     with config_path.open("r") as cfp:
         config = json.load(cfp)
 
     # TODO: Offer more options here
-    # e.g. Run on X random packages or specific sub list etc.
-    project_names = sorted(config["projects"].keys())
-    queue: asyncio.Queue = asyncio.Queue(maxsize=len(project_names))
-    for project in project_names:
+    # e.g. Run on X random packages etc.
+    queue: asyncio.Queue = asyncio.Queue(maxsize=len(projects_to_run))
+    for project in projects_to_run:
         await queue.put(project)
 
     return config, queue
@@ -365,6 +365,7 @@ async def process_queue(
     config_file: str,
     work_path: Path,
     workers: int,
+    projects_to_run: List[str],
     keep: bool = False,
     long_checkouts: bool = False,
     rebase: bool = False,
@@ -383,7 +384,7 @@ async def process_queue(
     results.stats["success"] = 0
     results.stats["wrong_py_ver"] = 0
 
-    config, queue = await load_projects_queue(Path(config_file))
+    config, queue = await load_projects_queue(Path(config_file), projects_to_run)
     project_count = queue.qsize()
     s = "" if project_count == 1 else "s"
     LOG.info(f"{project_count} project{s} to run Black over")
diff --git a/tests/test_format.py b/tests/test_format.py
index a659382092a..649c1572bee 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -93,6 +93,8 @@
     "src/black/strings.py",
     "src/black/trans.py",
     "src/blackd/__init__.py",
+    "src/black_primer/cli.py",
+    "src/black_primer/lib.py",
     "src/blib2to3/pygram.py",
     "src/blib2to3/pytree.py",
     "src/blib2to3/pgen2/conv.py",
diff --git a/tests/test_primer.py b/tests/test_primer.py
index dc30a7a2244..8d00d8353a7 100644
--- a/tests/test_primer.py
+++ b/tests/test_primer.py
@@ -11,7 +11,7 @@
 from platform import system
 from subprocess import CalledProcessError
 from tempfile import TemporaryDirectory, gettempdir
-from typing import Any, Callable, Iterator, Tuple
+from typing import Any, Callable, Iterator, List, Tuple, TypeVar
 from unittest.mock import Mock, patch
 
 from click.testing import CliRunner
@@ -89,6 +89,24 @@ async def return_zero(*args: Any, **kwargs: Any) -> int:
     return 0
 
 
+if sys.version_info >= (3, 9):
+    T = TypeVar("T")
+    Q = asyncio.Queue[T]
+else:
+    T = Any
+    Q = asyncio.Queue
+
+
+def collect(queue: Q) -> List[T]:
+    ret = []
+    while True:
+        try:
+            item = queue.get_nowait()
+            ret.append(item)
+        except asyncio.QueueEmpty:
+            return ret
+
+
 class PrimerLibTests(unittest.TestCase):
     def test_analyze_results(self) -> None:
         fake_results = lib.Results(
@@ -198,10 +216,25 @@ def test_process_queue(self, mock_stdout: Mock) -> None:
         with patch("black_primer.lib.git_checkout_or_rebase", return_false):
             with TemporaryDirectory() as td:
                 return_val = loop.run_until_complete(
-                    lib.process_queue(str(config_path), Path(td), 2)
+                    lib.process_queue(
+                        str(config_path), Path(td), 2, ["django", "pyramid"]
+                    )
                 )
                 self.assertEqual(0, return_val)
 
+    @event_loop()
+    def test_load_projects_queue(self) -> None:
+        """Test the process queue on primer itself
+        - If you have non black conforming formatting in primer itself this can fail"""
+        loop = asyncio.get_event_loop()
+        config_path = Path(lib.__file__).parent / "primer.json"
+
+        config, projects_queue = loop.run_until_complete(
+            lib.load_projects_queue(config_path, ["django", "pyramid"])
+        )
+        projects = collect(projects_queue)
+        self.assertEqual(projects, ["django", "pyramid"])
+
 
 class PrimerCLITests(unittest.TestCase):
     @event_loop()
@@ -217,6 +250,7 @@ def test_async_main(self) -> None:
             "workdir": str(work_dir),
             "workers": 69,
             "no_diff": False,
+            "projects": "",
         }
         with patch("black_primer.cli.lib.process_queue", return_zero):
             return_val = loop.run_until_complete(cli.async_main(**args))  # type: ignore
@@ -230,6 +264,19 @@ def test_help_output(self) -> None:
         result = runner.invoke(cli.main, ["--help"])
         self.assertEqual(result.exit_code, 0)
 
+    def test_projects(self) -> None:
+        runner = CliRunner()
+        with event_loop():
+            result = runner.invoke(cli.main, ["--projects=tox,asdf"])
+            self.assertEqual(result.exit_code, 0)
+            assert "1 / 1 succeeded" in result.output
+
+        with event_loop():
+            runner = CliRunner()
+            result = runner.invoke(cli.main, ["--projects=tox,attrs"])
+            self.assertEqual(result.exit_code, 0)
+            assert "2 / 2 succeeded" in result.output
+
 
 if __name__ == "__main__":
     unittest.main()

From 5434407af7ba262f74d272c738006cbf1d0ab11a Mon Sep 17 00:00:00 2001
From: Nipunn Koorapati <nipunn1313@gmail.com>
Date: Thu, 28 Oct 2021 10:35:37 -0700
Subject: [PATCH 0321/1034] black-primer: Print summary after individual
 failures (#2570)

If the individual failures are verbose, it's useful to have
the summary at the end. Otherwise, it can be really difficult
to figure out which projects have an issue.
---
 CHANGES.md              |  6 +++++-
 src/black_primer/lib.py | 24 ++++++++++++++----------
 tests/test_primer.py    | 15 +++++++++------
 3 files changed, 28 insertions(+), 17 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index a8307ee61ec..76a7ca6fd3d 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -8,13 +8,17 @@
 - Add new `--workers` parameter (#2514)
 - Fixed feature detection for positional-only arguments in lambdas (#2532)
 - Bumped typed-ast version minimum to 1.4.3 for 3.10 compatiblity (#2519)
-- Add primer support for --projects (#2555)
 
 ### _Blackd_
 
 - Remove dependency on aiohttp-cors (#2500)
 - Bump required aiohttp version to 3.7.4 (#2509)
 
+### _Black-Primer_
+
+- Add primer support for --projects (#2555)
+- Print primer summary after individual failures (#2570)
+
 ### Integrations
 
 - Allow to pass `target_version` in the vim plugin (#1319)
diff --git a/src/black_primer/lib.py b/src/black_primer/lib.py
index 351501673f8..13724f431ce 100644
--- a/src/black_primer/lib.py
+++ b/src/black_primer/lib.py
@@ -88,6 +88,18 @@ def analyze_results(project_count: int, results: Results) -> int:
     failed_pct = round(((results.stats["failed"] / project_count) * 100), 2)
     success_pct = round(((results.stats["success"] / project_count) * 100), 2)
 
+    if results.failed_projects:
+        click.secho("\nFailed projects:\n", bold=True)
+
+    for project_name, project_cpe in results.failed_projects.items():
+        print(f"## {project_name}:")
+        print(f" - Returned {project_cpe.returncode}")
+        if project_cpe.stderr:
+            print(f" - stderr:\n{project_cpe.stderr.decode('utf8')}")
+        if project_cpe.stdout:
+            print(f" - stdout:\n{project_cpe.stdout.decode('utf8')}")
+        print("")
+
     click.secho("-- primer results 📊 --\n", bold=True)
     click.secho(
         f"{results.stats['success']} / {project_count} succeeded ({success_pct}%) ✅",
@@ -110,16 +122,8 @@ def analyze_results(project_count: int, results: Results) -> int:
     )
 
     if results.failed_projects:
-        click.secho("\nFailed projects:\n", bold=True)
-
-    for project_name, project_cpe in results.failed_projects.items():
-        print(f"## {project_name}:")
-        print(f" - Returned {project_cpe.returncode}")
-        if project_cpe.stderr:
-            print(f" - stderr:\n{project_cpe.stderr.decode('utf8')}")
-        if project_cpe.stdout:
-            print(f" - stdout:\n{project_cpe.stdout.decode('utf8')}")
-        print("")
+        failed = ", ".join(results.failed_projects.keys())
+        click.secho(f"\nFailed projects: {failed}\n", bold=True)
 
     return results.stats["failed"]
 
diff --git a/tests/test_primer.py b/tests/test_primer.py
index 8d00d8353a7..2aac2d09ff5 100644
--- a/tests/test_primer.py
+++ b/tests/test_primer.py
@@ -20,6 +20,14 @@
 
 
 EXPECTED_ANALYSIS_OUTPUT = """\
+
+Failed projects:
+
+## black:
+ - Returned 69
+ - stdout:
+Black didn't work
+
 -- primer results 📊 --
 
 68 / 69 succeeded (98.55%) ✅
@@ -28,12 +36,7 @@
  - 0 projects skipped due to Python version
  - 0 skipped due to long checkout
 
-Failed projects:
-
-## black:
- - Returned 69
- - stdout:
-Black didn't work
+Failed projects: black
 
 """
 FAKE_PROJECT_CONFIG = {

From cbf5401efff0524f7395c5fb81551de75b17c89e Mon Sep 17 00:00:00 2001
From: dawn <78233879+dawnofmidnight@users.noreply.github.com>
Date: Sat, 30 Oct 2021 11:50:45 -0400
Subject: [PATCH 0322/1034] fix: allow tests to be run from (hopefully) any
 directory (GH-2574)

* fix: allow tests to be run from the tests/ directory
* fix: try fixing windows build with MarcoGorelli's suggestion
* Windows hotfix + better respect test's spirit

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 tests/test_black.py |  9 ++++++---
 tests/test_ipynb.py | 49 +++++++++++++++++----------------------------
 2 files changed, 24 insertions(+), 34 deletions(-)

diff --git a/tests/test_black.py b/tests/test_black.py
index 1fc63c942e9..5647a00e48b 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -50,6 +50,7 @@
     DATA_DIR,
     DEFAULT_MODE,
     DETERMINISTIC_HEADER,
+    PROJECT_ROOT,
     PY36_VERSIONS,
     THIS_DIR,
     BlackBaseTestCase,
@@ -1512,9 +1513,11 @@ def test_code_option_config(self) -> None:
         """
         with patch.object(black, "parse_pyproject_toml", return_value={}) as parse:
             args = ["--code", "print"]
-            CliRunner().invoke(black.main, args)
+            # This is the only directory known to contain a pyproject.toml
+            with change_directory(PROJECT_ROOT):
+                CliRunner().invoke(black.main, args)
+                pyproject_path = Path(Path.cwd(), "pyproject.toml").resolve()
 
-            pyproject_path = Path(Path().cwd(), "pyproject.toml").resolve()
             assert (
                 len(parse.mock_calls) >= 1
             ), "Expected config parse to be called with the current directory."
@@ -1529,7 +1532,7 @@ def test_code_option_parent_config(self) -> None:
         Test that the code option finds the pyproject.toml in the parent directory.
         """
         with patch.object(black, "parse_pyproject_toml", return_value={}) as parse:
-            with change_directory(Path("tests")):
+            with change_directory(THIS_DIR):
                 args = ["--code", "print"]
                 CliRunner().invoke(black.main, args)
 
diff --git a/tests/test_ipynb.py b/tests/test_ipynb.py
index 12f176c9341..ba460074e9a 100644
--- a/tests/test_ipynb.py
+++ b/tests/test_ipynb.py
@@ -1,4 +1,5 @@
-import pathlib
+import re
+
 from click.testing import CliRunner
 from black.handle_ipynb_magics import jupyter_dependencies_are_installed
 from black import (
@@ -8,11 +9,11 @@
     format_file_contents,
     format_file_in_place,
 )
-import os
 import pytest
 from black import Mode
 from _pytest.monkeypatch import MonkeyPatch
 from py.path import local
+from tests.util import DATA_DIR
 
 pytestmark = pytest.mark.jupyter
 pytest.importorskip("IPython", reason="IPython is an optional dependency")
@@ -178,9 +179,7 @@ def test_empty_cell() -> None:
 
 
 def test_entire_notebook_empty_metadata() -> None:
-    with open(
-        os.path.join("tests", "data", "notebook_empty_metadata.ipynb"), "rb"
-    ) as fd:
+    with open(DATA_DIR / "notebook_empty_metadata.ipynb", "rb") as fd:
         content_bytes = fd.read()
     content = content_bytes.decode()
     result = format_file_contents(content, fast=True, mode=JUPYTER_MODE)
@@ -217,9 +216,7 @@ def test_entire_notebook_empty_metadata() -> None:
 
 
 def test_entire_notebook_trailing_newline() -> None:
-    with open(
-        os.path.join("tests", "data", "notebook_trailing_newline.ipynb"), "rb"
-    ) as fd:
+    with open(DATA_DIR / "notebook_trailing_newline.ipynb", "rb") as fd:
         content_bytes = fd.read()
     content = content_bytes.decode()
     result = format_file_contents(content, fast=True, mode=JUPYTER_MODE)
@@ -268,9 +265,7 @@ def test_entire_notebook_trailing_newline() -> None:
 
 
 def test_entire_notebook_no_trailing_newline() -> None:
-    with open(
-        os.path.join("tests", "data", "notebook_no_trailing_newline.ipynb"), "rb"
-    ) as fd:
+    with open(DATA_DIR / "notebook_no_trailing_newline.ipynb", "rb") as fd:
         content_bytes = fd.read()
     content = content_bytes.decode()
     result = format_file_contents(content, fast=True, mode=JUPYTER_MODE)
@@ -319,9 +314,7 @@ def test_entire_notebook_no_trailing_newline() -> None:
 
 
 def test_entire_notebook_without_changes() -> None:
-    with open(
-        os.path.join("tests", "data", "notebook_without_changes.ipynb"), "rb"
-    ) as fd:
+    with open(DATA_DIR / "notebook_without_changes.ipynb", "rb") as fd:
         content_bytes = fd.read()
     content = content_bytes.decode()
     with pytest.raises(NothingChanged):
@@ -329,7 +322,7 @@ def test_entire_notebook_without_changes() -> None:
 
 
 def test_non_python_notebook() -> None:
-    with open(os.path.join("tests", "data", "non_python_notebook.ipynb"), "rb") as fd:
+    with open(DATA_DIR / "non_python_notebook.ipynb", "rb") as fd:
         content_bytes = fd.read()
     content = content_bytes.decode()
     with pytest.raises(NothingChanged):
@@ -342,23 +335,17 @@ def test_empty_string() -> None:
 
 
 def test_unparseable_notebook() -> None:
-    msg = (
-        r"File 'tests[/\\]data[/\\]notebook_which_cant_be_parsed\.ipynb' "
-        r"cannot be parsed as valid Jupyter notebook\."
-    )
+    path = DATA_DIR / "notebook_which_cant_be_parsed.ipynb"
+    msg = rf"File '{re.escape(str(path))}' cannot be parsed as valid Jupyter notebook\."
     with pytest.raises(ValueError, match=msg):
-        format_file_in_place(
-            pathlib.Path("tests") / "data/notebook_which_cant_be_parsed.ipynb",
-            fast=True,
-            mode=JUPYTER_MODE,
-        )
+        format_file_in_place(path, fast=True, mode=JUPYTER_MODE)
 
 
 def test_ipynb_diff_with_change() -> None:
     result = runner.invoke(
         main,
         [
-            os.path.join("tests", "data", "notebook_trailing_newline.ipynb"),
+            str(DATA_DIR / "notebook_trailing_newline.ipynb"),
             "--diff",
         ],
     )
@@ -370,7 +357,7 @@ def test_ipynb_diff_with_no_change() -> None:
     result = runner.invoke(
         main,
         [
-            os.path.join("tests", "data", "notebook_without_changes.ipynb"),
+            str(DATA_DIR / "notebook_without_changes.ipynb"),
             "--diff",
         ],
     )
@@ -383,7 +370,7 @@ def test_cache_isnt_written_if_no_jupyter_deps_single(
 ) -> None:
     # Check that the cache isn't written to if Jupyter dependencies aren't installed.
     jupyter_dependencies_are_installed.cache_clear()
-    nb = os.path.join("tests", "data", "notebook_trailing_newline.ipynb")
+    nb = DATA_DIR / "notebook_trailing_newline.ipynb"
     tmp_nb = tmpdir / "notebook.ipynb"
     with open(nb) as src, open(tmp_nb, "w") as dst:
         dst.write(src.read())
@@ -405,7 +392,7 @@ def test_cache_isnt_written_if_no_jupyter_deps_dir(
 ) -> None:
     # Check that the cache isn't written to if Jupyter dependencies aren't installed.
     jupyter_dependencies_are_installed.cache_clear()
-    nb = os.path.join("tests", "data", "notebook_trailing_newline.ipynb")
+    nb = DATA_DIR / "notebook_trailing_newline.ipynb"
     tmp_nb = tmpdir / "notebook.ipynb"
     with open(nb) as src, open(tmp_nb, "w") as dst:
         dst.write(src.read())
@@ -423,7 +410,7 @@ def test_cache_isnt_written_if_no_jupyter_deps_dir(
 
 
 def test_ipynb_flag(tmpdir: local) -> None:
-    nb = os.path.join("tests", "data", "notebook_trailing_newline.ipynb")
+    nb = DATA_DIR / "notebook_trailing_newline.ipynb"
     tmp_nb = tmpdir / "notebook.a_file_extension_which_is_definitely_not_ipynb"
     with open(nb) as src, open(tmp_nb, "w") as dst:
         dst.write(src.read())
@@ -440,11 +427,11 @@ def test_ipynb_flag(tmpdir: local) -> None:
 
 
 def test_ipynb_and_pyi_flags() -> None:
-    nb = os.path.join("tests", "data", "notebook_trailing_newline.ipynb")
+    nb = DATA_DIR / "notebook_trailing_newline.ipynb"
     result = runner.invoke(
         main,
         [
-            nb,
+            str(nb),
             "--pyi",
             "--ipynb",
             "--diff",

From 6b38b52187a7a7b9fedcf257c5ba45cc16f2e8a2 Mon Sep 17 00:00:00 2001
From: Roma <81729714+rtdev-com@users.noreply.github.com>
Date: Sat, 30 Oct 2021 11:45:09 -0700
Subject: [PATCH 0323/1034] Add Tesla to organizations list (#2577)

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 7bf0ed8d16f..f9061c33863 100644
--- a/README.md
+++ b/README.md
@@ -138,7 +138,7 @@ Twisted, LocalStack, every Datadog Agent Integration, Home Assistant, Zulip, Ked
 many more.
 
 The following organizations use _Black_: Facebook, Dropbox, Mozilla, Quora, Duolingo,
-QuantumBlack.
+QuantumBlack, Tesla.
 
 Are we missing anyone? Let us know.
 

From 92eeacc2e3ce917d6364ec06d891436f11536a1c Mon Sep 17 00:00:00 2001
From: Nipunn Koorapati <nipunn1313@gmail.com>
Date: Sat, 30 Oct 2021 11:54:43 -0700
Subject: [PATCH 0324/1034] Use STDIN project in test_projects to ensure it
 runs quickly (#2575)

Existing test was actually running a full black-primer
run which could be slow. This goes from 8 seconds to
0.4 seconds on my machine.

Needed to move to top level scope to leverage the caplog
feature of pytest in order to test that the command line
was parsing the bogus arguments and dumping to stderr.
---
 tests/test_primer.py | 28 +++++++++++++++++-----------
 1 file changed, 17 insertions(+), 11 deletions(-)

diff --git a/tests/test_primer.py b/tests/test_primer.py
index 2aac2d09ff5..9bb401574ca 100644
--- a/tests/test_primer.py
+++ b/tests/test_primer.py
@@ -9,6 +9,7 @@
 from os import getpid
 from pathlib import Path
 from platform import system
+from pytest import LogCaptureFixture
 from subprocess import CalledProcessError
 from tempfile import TemporaryDirectory, gettempdir
 from typing import Any, Callable, Iterator, List, Tuple, TypeVar
@@ -267,18 +268,23 @@ def test_help_output(self) -> None:
         result = runner.invoke(cli.main, ["--help"])
         self.assertEqual(result.exit_code, 0)
 
-    def test_projects(self) -> None:
+
+def test_projects(caplog: LogCaptureFixture) -> None:
+    with event_loop():
+        runner = CliRunner()
+        result = runner.invoke(cli.main, ["--projects=STDIN,asdf"])
+        assert result.exit_code == 0
+        assert "1 / 1 succeeded" in result.output
+        assert "Projects not found: {'asdf'}" in caplog.text
+
+    caplog.clear()
+
+    with event_loop():
         runner = CliRunner()
-        with event_loop():
-            result = runner.invoke(cli.main, ["--projects=tox,asdf"])
-            self.assertEqual(result.exit_code, 0)
-            assert "1 / 1 succeeded" in result.output
-
-        with event_loop():
-            runner = CliRunner()
-            result = runner.invoke(cli.main, ["--projects=tox,attrs"])
-            self.assertEqual(result.exit_code, 0)
-            assert "2 / 2 succeeded" in result.output
+        result = runner.invoke(cli.main, ["--projects=fdsa,STDIN"])
+        assert result.exit_code == 0
+        assert "1 / 1 succeeded" in result.output
+        assert "Projects not found: {'fdsa'}" in caplog.text
 
 
 if __name__ == "__main__":

From fac498bf31af509e0f62bf61459014c9a4e094a1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Felix=20Hild=C3=A9n?= <felix.hilden@gmail.com>
Date: Sun, 31 Oct 2021 01:01:40 +0300
Subject: [PATCH 0325/1034] Update bug template (#2538)

---
 .github/ISSUE_TEMPLATE/bug_report.md | 59 ++++++++++++++++++----------
 1 file changed, 38 insertions(+), 21 deletions(-)

diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
index e8d232c8b34..cb64cf9325d 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -6,41 +6,58 @@ labels: "T: bug"
 assignees: ""
 ---
 
+<!--
+Please make sure that the bug is not already fixed either in newer versions or the
+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.
+3. Or run _Black_ on your machine:
+   - create a new virtualenv (make sure it's the same Python version);
+   - clone this repository;
+   - run `pip install -e .[d,python2]`;
+   - run `pip install -r test_requirements.txt`
+   - make sure it's sane by running `python -m pytest`; and
+   - run `black` like you did last time.
+-->
+
 **Describe the bug**
 
 <!-- A clear and concise description of what the bug is. -->
 
 **To Reproduce**
 
-<!-- Steps to reproduce the behavior:
+<!--
+Minimal steps to reproduce the behavior with source code and Black's configuration.
+-->
 
-For example:
-1. Take this file '...'
-1. Run _Black_ on it with these arguments '...'
-1. See error -->
+For example, take this code:
 
-**Expected behavior**
+```python
+this = "code"
+```
 
-<!-- A clear and concise description of what you expected to happen. -->
+And run it with these arguments:
 
-**Environment (please complete the following information):**
+```sh
+$ black file.py --target-version py39
+```
 
-- Version: <!-- e.g. [main] -->
-- OS and Python version: <!-- e.g. [Linux/Python 3.7.4rc1] -->
+The resulting error is:
 
-**Does this bug also happen on main?**
+> cannot format file.py: INTERNAL ERROR: ...
 
-<!-- To answer this, you have two options:
+**Expected behavior**
 
-1. Use the online formatter at <https://black.vercel.app/?version=main>, which will use
-   the latest main branch.
-1. Or run _Black_ on your machine:
-   - create a new virtualenv (make sure it's the same Python version);
-   - clone this repository;
-   - run `pip install -e .[d,python2]`;
-   - run `pip install -r test_requirements.txt`
-   - make sure it's sane by running `python -m pytest`; and
-   - run `black` like you did last time. -->
+<!-- A clear and concise description of what you expected to happen. -->
+
+**Environment**
+
+<!-- Please complete the following information: -->
+
+- Black's version: <!-- e.g. [main] -->
+- OS and Python version: <!-- e.g. [Linux/Python 3.7.4rc1] -->
 
 **Additional context**
 

From 9afffacaa0e5ac911f9feacb916bc48473dcb117 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Sat, 30 Oct 2021 18:35:55 -0400
Subject: [PATCH 0326/1034] Address mypy errors on 3.10 w/ asyncio loop
 parameter (#2580)

---
 CHANGES.md               | 2 ++
 src/black/__init__.py    | 5 ++++-
 src/black/concurrency.py | 9 ++++++---
 3 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 76a7ca6fd3d..c49516c9081 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -8,6 +8,8 @@
 - Add new `--workers` parameter (#2514)
 - Fixed feature detection for positional-only arguments in lambdas (#2532)
 - Bumped typed-ast version minimum to 1.4.3 for 3.10 compatiblity (#2519)
+- Fixed a Python 3.10 compatibility issue where the loop argument was still being passed
+  even though it has been removed (#2580)
 
 ### _Blackd_
 
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 5c6cb672aa2..c503c1a55f7 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -763,7 +763,10 @@ async def schedule_formatting(
                     sources_to_cache.append(src)
                 report.done(src, changed)
     if cancelled:
-        await asyncio.gather(*cancelled, loop=loop, return_exceptions=True)
+        if sys.version_info >= (3, 7):
+            await asyncio.gather(*cancelled, return_exceptions=True)
+        else:
+            await asyncio.gather(*cancelled, loop=loop, return_exceptions=True)
     if sources_to_cache:
         write_cache(cache, sources_to_cache, mode)
 
diff --git a/src/black/concurrency.py b/src/black/concurrency.py
index 69d79f534e8..24f67b62f06 100644
--- a/src/black/concurrency.py
+++ b/src/black/concurrency.py
@@ -42,9 +42,12 @@ def shutdown(loop: asyncio.AbstractEventLoop) -> None:
 
         for task in to_cancel:
             task.cancel()
-        loop.run_until_complete(
-            asyncio.gather(*to_cancel, loop=loop, return_exceptions=True)
-        )
+        if sys.version_info >= (3, 7):
+            loop.run_until_complete(asyncio.gather(*to_cancel, return_exceptions=True))
+        else:
+            loop.run_until_complete(
+                asyncio.gather(*to_cancel, loop=loop, return_exceptions=True)
+            )
     finally:
         # `concurrent.futures.Future` objects cannot be cancelled once they
         # are already running. There might be some when the `shutdown()` happened.

From 7bf233a9446a7611b22bc2f73f7e221886632725 Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Sun, 31 Oct 2021 10:41:12 -0700
Subject: [PATCH 0327/1034] Pin regex in docker to 2021.10.8 (GH-2579)

* Pin regex in docker to 2021.10.8
- This is due to 2021.10.8 having arm wheels and newer versions not

I will go see if I can help restore arm build @ https://bitbucket.org/mrabarnett/mrab-regex/issues/399/missing-wheel-for-macosx-and-the-new-m1 soon.

Test: Build on my M1 mac: `docker build -t cooperlees/black .`

* Add in that the pin is only for docker
---
 CHANGES.md | 2 ++
 Dockerfile | 2 ++
 2 files changed, 4 insertions(+)

diff --git a/CHANGES.md b/CHANGES.md
index c49516c9081..4c04eccde48 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -24,6 +24,8 @@
 ### Integrations
 
 - Allow to pass `target_version` in the vim plugin (#1319)
+- Pin regex module to 2021.10.8 in our docker file as it has arm wheels available
+  (#2579)
 
 ## 21.9b0
 
diff --git a/Dockerfile b/Dockerfile
index 9542479eca5..ce88f0ce5e3 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -1,10 +1,12 @@
 FROM python:3-slim
 
+# TODO: Remove regex version pin once we get newer arm wheels
 RUN mkdir /src
 COPY . /src/
 RUN pip install --no-cache-dir --upgrade pip setuptools wheel \
     && apt update && apt install -y git \
     && cd /src \
+    && pip install --no-cache-dir regex==2021.10.8 \
     && pip install --no-cache-dir .[colorama,d] \
     && rm -rf /src \
     && apt remove -y git \

From b21c0c3d28d87bc944a1fdc979b30a0707b0df89 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Sun, 31 Oct 2021 19:46:12 -0400
Subject: [PATCH 0328/1034] Deprecate Python 2 formatting support (#2523)

* Prepare for Python 2 depreciation

- Use BlackRunner and .stdout in command line test

So the next commit won't break this test. This is in its own commit so
we can just revert the depreciation commit when dropping Python 2
support completely.

* Deprecate Python 2 formatting support
---
 CHANGES.md                  |  1 +
 docs/faq.md                 | 10 +++++++---
 src/black/__init__.py       | 17 ++++++++++++++++-
 src/black/mode.py           | 10 +++++++++-
 src/blib2to3/pgen2/token.py |  3 +++
 tests/test_black.py         | 19 +++++++++++++++++--
 6 files changed, 53 insertions(+), 7 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 4c04eccde48..9990d8cf459 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -10,6 +10,7 @@
 - Bumped typed-ast version minimum to 1.4.3 for 3.10 compatiblity (#2519)
 - Fixed a Python 3.10 compatibility issue where the loop argument was still being passed
   even though it has been removed (#2580)
+- Deprecate Python 2 formatting support (#2523)
 
 ### _Blackd_
 
diff --git a/docs/faq.md b/docs/faq.md
index 9fe53922b6d..77f9df51fd4 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -74,13 +74,17 @@ disabled-by-default counterpart W504. E203 should be disabled while changes are
 
 ## Does Black support Python 2?
 
+```{warning}
+Python 2 support has been deprecated since 21.10b0.
+
+This support will be dropped in the first stable release, expected for January 2022.
+See [The Black Code Style](the_black_code_style/index.rst) for details.
+```
+
 For formatting, yes! [Install](getting_started.md#installation) with the `python2` extra
 to format Python 2 files too! In terms of running _Black_ though, Python 3.6 or newer is
 required.
 
-Note that this support will be dropped in the first stable release, expected for
-January 2022. See [The Black Code Style](the_black_code_style/index.rst) for details.
-
 ## Why does my linter or typechecker complain after I format my code?
 
 Some linters and other tools use magical comments (e.g., `# noqa`, `# type: ignore`) to
diff --git a/src/black/__init__.py b/src/black/__init__.py
index c503c1a55f7..831cda934a8 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -1061,6 +1061,15 @@ def f(
         versions = mode.target_versions
     else:
         versions = detect_target_versions(src_node)
+
+    # TODO: fully drop support and this code hopefully in January 2022 :D
+    if TargetVersion.PY27 in mode.target_versions or versions == {TargetVersion.PY27}:
+        msg = (
+            "DEPRECATION: Python 2 support will be removed in the first stable release"
+            "expected in January 2022."
+        )
+        err(msg, fg="yellow", bold=True)
+
     normalize_fmt_off(src_node)
     lines = LineGenerator(
         mode=mode,
@@ -1103,7 +1112,7 @@ def decode_bytes(src: bytes) -> Tuple[FileContent, Encoding, NewLine]:
         return tiow.read(), encoding, newline
 
 
-def get_features_used(node: Node) -> Set[Feature]:
+def get_features_used(node: Node) -> Set[Feature]:  # noqa: C901
     """Return a set of (relatively) new Python features used in this file.
 
     Currently looking for:
@@ -1113,6 +1122,7 @@ def get_features_used(node: Node) -> Set[Feature]:
     - positional only arguments in function signatures and lambdas;
     - assignment expression;
     - relaxed decorator syntax;
+    - print / exec statements;
     """
     features: Set[Feature] = set()
     for n in node.pre_order():
@@ -1161,6 +1171,11 @@ def get_features_used(node: Node) -> Set[Feature]:
                         if argch.type in STARS:
                             features.add(feature)
 
+        elif n.type == token.PRINT_STMT:
+            features.add(Feature.PRINT_STMT)
+        elif n.type == token.EXEC_STMT:
+            features.add(Feature.EXEC_STMT)
+
     return features
 
 
diff --git a/src/black/mode.py b/src/black/mode.py
index 0b7624eaf8a..374c47a42eb 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -41,9 +41,17 @@ class Feature(Enum):
     RELAXED_DECORATORS = 10
     FORCE_OPTIONAL_PARENTHESES = 50
 
+    # temporary for Python 2 deprecation
+    PRINT_STMT = 200
+    EXEC_STMT = 201
+
 
 VERSION_TO_FEATURES: Dict[TargetVersion, Set[Feature]] = {
-    TargetVersion.PY27: {Feature.ASYNC_IDENTIFIERS},
+    TargetVersion.PY27: {
+        Feature.ASYNC_IDENTIFIERS,
+        Feature.PRINT_STMT,
+        Feature.EXEC_STMT,
+    },
     TargetVersion.PY33: {Feature.UNICODE_LITERALS, Feature.ASYNC_IDENTIFIERS},
     TargetVersion.PY34: {Feature.UNICODE_LITERALS, Feature.ASYNC_IDENTIFIERS},
     TargetVersion.PY35: {
diff --git a/src/blib2to3/pgen2/token.py b/src/blib2to3/pgen2/token.py
index 1e0dec9c714..349ba8023a2 100644
--- a/src/blib2to3/pgen2/token.py
+++ b/src/blib2to3/pgen2/token.py
@@ -74,6 +74,9 @@
 COLONEQUAL: Final = 59
 N_TOKENS: Final = 60
 NT_OFFSET: Final = 256
+# temporary for Python 2 deprecation
+PRINT_STMT: Final = 316
+EXEC_STMT: Final = 288
 # --end constants--
 
 tok_name: Final[Dict[int, str]] = {}
diff --git a/tests/test_black.py b/tests/test_black.py
index 5647a00e48b..b96a5438557 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -1401,14 +1401,14 @@ def test_docstring_reformat_for_py27(self) -> None:
         )
         expected = 'def foo():\n    """Testing\n    Testing"""\n    print "Foo"\n'
 
-        result = CliRunner().invoke(
+        result = BlackRunner().invoke(
             black.main,
             ["-", "-q", "--target-version=py27"],
             input=BytesIO(source),
         )
 
         self.assertEqual(result.exit_code, 0)
-        actual = result.output
+        actual = result.stdout
         self.assertFormatEqual(actual, expected)
 
     @staticmethod
@@ -2017,6 +2017,21 @@ def test_get_sources_with_stdin_filename_and_force_exclude(self) -> None:
         )
 
 
+@pytest.mark.parametrize("explicit", [True, False], ids=["explicit", "autodetection"])
+def test_python_2_deprecation_with_target_version(explicit: bool) -> None:
+    args = [
+        "--config",
+        str(THIS_DIR / "empty.toml"),
+        str(DATA_DIR / "python2.py"),
+        "--check",
+    ]
+    if explicit:
+        args.append("--target-version=py27")
+    with cache_dir():
+        result = BlackRunner().invoke(black.main, args)
+    assert "DEPRECATION: Python 2 support will be removed" in result.stderr
+
+
 with open(black.__file__, "r", encoding="utf-8") as _bf:
     black_source_lines = _bf.readlines()
 

From bd961304b63ad8178610df7242edf180d825e336 Mon Sep 17 00:00:00 2001
From: Vincent Barbaresi <vincent.barbaresi@datadoghq.com>
Date: Mon, 1 Nov 2021 01:43:34 +0100
Subject: [PATCH 0329/1034]  install build-essential to compile dependencies
 and use multi-stage build  (#2582)

- Install build-essential to avoid build issues like #2568 when dependencies don't have prebuilt wheels available
- Use multi-stage build instead of trying to purge packages and cache from the image
  Copying `/root/.local/` installs only black's built Python dependencies (< 20 MB).
  So the image is barely larger than python:3-slim base image
---
 CHANGES.md |  4 ++--
 Dockerfile | 19 ++++++++++---------
 2 files changed, 12 insertions(+), 11 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 9990d8cf459..aa40d87ab71 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -25,8 +25,8 @@
 ### Integrations
 
 - Allow to pass `target_version` in the vim plugin (#1319)
-- Pin regex module to 2021.10.8 in our docker file as it has arm wheels available
-  (#2579)
+- Install build tools in docker file and use multi-stage build to keep the image size
+  down (#2582)
 
 ## 21.9b0
 
diff --git a/Dockerfile b/Dockerfile
index ce88f0ce5e3..c393e29f632 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -1,16 +1,17 @@
-FROM python:3-slim
+FROM python:3-slim AS builder
 
-# TODO: Remove regex version pin once we get newer arm wheels
 RUN mkdir /src
 COPY . /src/
 RUN pip install --no-cache-dir --upgrade pip setuptools wheel \
-    && apt update && apt install -y git \
+    # 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 regex==2021.10.8 \
-    && pip install --no-cache-dir .[colorama,d] \
-    && rm -rf /src \
-    && apt remove -y git \
-    && apt autoremove -y \
-    && rm -rf /var/lib/apt/lists/*
+    && pip install --user --no-cache-dir .[colorama,d]
+
+FROM python:3-slim
+
+# copy only Python packages to limit the image size
+COPY --from=builder /root/.local /root/.local
+ENV PATH=/root/.local/bin:$PATH
 
 CMD ["black"]

From 64c8be01f0cfedc94cb1c9ebd342ea77cafbb78a Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Sun, 31 Oct 2021 17:59:39 -0700
Subject: [PATCH 0330/1034] Update CHANGES.md for 21.10b0 release (#2583)

* Update CHANGES.md for 21.10b0 release

* Update version in docs/usage_and_configuration/the_basics.md

* Also update docs/integrations/source_version_control.md ...
---
 CHANGES.md                                  | 2 +-
 docs/integrations/source_version_control.md | 2 +-
 docs/usage_and_configuration/the_basics.md  | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index aa40d87ab71..b454a73edab 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,6 +1,6 @@
 # Change Log
 
-## Unreleased
+## 21.10b0
 
 ### _Black_
 
diff --git a/docs/integrations/source_version_control.md b/docs/integrations/source_version_control.md
index 6a1aa363d2b..cf0ef1dfed9 100644
--- a/docs/integrations/source_version_control.md
+++ b/docs/integrations/source_version_control.md
@@ -7,7 +7,7 @@ Use [pre-commit](https://pre-commit.com/). Once you
 ```yaml
 repos:
   - repo: https://github.com/psf/black
-    rev: 21.9b0
+    rev: 21.10b0
     hooks:
       - id: black
         # It is recommended to specify the latest version of Python
diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index 49268b44f7c..533c213a4da 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -173,7 +173,7 @@ You can check the version of _Black_ you have installed using the `--version` fl
 
 ```console
 $ black --version
-black, version 21.9b0
+black, version 21.10b0
 ```
 
 An option to require a specific version to be running is also provided.

From f80f49767cacafaeb20016d483b8315474504e6a Mon Sep 17 00:00:00 2001
From: LordOfPolls <22540825+LordOfPolls@users.noreply.github.com>
Date: Sat, 6 Nov 2021 16:04:27 +0000
Subject: [PATCH 0331/1034] Add a missing space in Python 2 deprecation
 (GH-2590)

`DEPRECATION: Python 2 support will be removed in the first stable releaseexpected in January 2022` - > `DEPRECATION: Python 2 support will be removed in the first stable release expected in January 2022`
---
 src/black/__init__.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index 831cda934a8..ba4d3dea70e 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -1065,7 +1065,7 @@ def f(
     # TODO: fully drop support and this code hopefully in January 2022 :D
     if TargetVersion.PY27 in mode.target_versions or versions == {TargetVersion.PY27}:
         msg = (
-            "DEPRECATION: Python 2 support will be removed in the first stable release"
+            "DEPRECATION: Python 2 support will be removed in the first stable release "
             "expected in January 2022."
         )
         err(msg, fg="yellow", bold=True)

From f297c4644ee561ceadfb0bf3a08a89ac92b5a2ee Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Thu, 11 Nov 2021 17:52:13 -0500
Subject: [PATCH 0332/1034] primer: Hypothesis now requires Python>=3.8
 (GH-2602)

looks like their project dev tooling uses some newer syntax or something
---
 .gitignore                   | 7 ++++++-
 src/black_primer/primer.json | 4 ++--
 2 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/.gitignore b/.gitignore
index f81bce8fd4e..249499b135e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,13 +7,18 @@ _build
 docs/_static/pypi.svg
 .tox
 __pycache__
+
+# Packaging artifacts
 black.egg-info
+black.dist-info
 build/
 dist/
 pip-wheel-metadata/
+.eggs
+
 src/_black_version.py
 .idea
-.eggs
+
 .dmypy.json
 *.swp
 .hypothesis/
diff --git a/src/black_primer/primer.json b/src/black_primer/primer.json
index 0d1018fc50e..2290d1df005 100644
--- a/src/black_primer/primer.json
+++ b/src/black_primer/primer.json
@@ -77,7 +77,7 @@
       "expect_formatting_changes": true,
       "git_clone_url": "https://github.com/django/django.git",
       "long_checkout": false,
-      "py_versions": ["3.8", "3.9"]
+      "py_versions": ["3.8", "3.9", "3.10"]
     },
     "flake8-bugbear": {
       "cli_arguments": ["--experimental-string-processing"],
@@ -91,7 +91,7 @@
       "expect_formatting_changes": true,
       "git_clone_url": "https://github.com/HypothesisWorks/hypothesis.git",
       "long_checkout": false,
-      "py_versions": ["all"]
+      "py_versions": ["3.8", "3.9", "3.10"]
     },
     "pandas": {
       "cli_arguments": ["--experimental-string-processing"],

From 0753d99519b0c90f0f9f280b73783b537900dc16 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Thu, 11 Nov 2021 20:28:48 -0500
Subject: [PATCH 0333/1034] Improve Python 2 only syntax detection (GH-2592)

* Improve Python 2 only syntax detection

First of all this fixes a mistake I made in Python 2 deprecation PR
using token.* to check for print/exec statements. Turns out that
for nodes with a type value higher than 256 its numeric type isn't
guaranteed to be constant. Using syms.* instead fixes this.

Also add support for the following cases:

    print "hello, world!"

    exec "print('hello, world!')"

    def set_position((x, y), value):
        pass

    try:
        pass
    except Exception, err:
        pass

    raise RuntimeError, "I feel like crashing today :p"

    `wow_these_really_did_exist`

    10L

* Add octal support, more test cases, and fixup long ints

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 CHANGES.md                      |  7 +++
 src/black/__init__.py           | 36 +++++++++++--
 src/black/mode.py               | 12 +++++
 src/blib2to3/pgen2/token.py     |  3 --
 tests/data/python2_detection.py | 90 +++++++++++++++++++++++++++++++++
 tests/test_black.py             | 15 ++++++
 6 files changed, 157 insertions(+), 6 deletions(-)
 create mode 100644 tests/data/python2_detection.py

diff --git a/CHANGES.md b/CHANGES.md
index b454a73edab..215680ff2ee 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,5 +1,12 @@
 # Change Log
 
+## _Unreleased_
+
+### _Black_
+
+- Warn about Python 2 deprecation in more cases by improving Python 2 only syntax
+  detection (#2592)
+
 ## 21.10b0
 
 ### _Black_
diff --git a/src/black/__init__.py b/src/black/__init__.py
index ba4d3dea70e..ad4ee1a0d1a 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -1132,8 +1132,17 @@ def get_features_used(node: Node) -> Set[Feature]:  # noqa: C901
                 features.add(Feature.F_STRINGS)
 
         elif n.type == token.NUMBER:
-            if "_" in n.value:  # type: ignore
+            assert isinstance(n, Leaf)
+            if "_" in n.value:
                 features.add(Feature.NUMERIC_UNDERSCORES)
+            elif n.value.endswith(("L", "l")):
+                # Python 2: 10L
+                features.add(Feature.LONG_INT_LITERAL)
+            elif len(n.value) >= 2 and n.value[0] == "0" and n.value[1].isdigit():
+                # Python 2: 0123; 00123; ...
+                if not all(char == "0" for char in n.value):
+                    # although we don't want to match 0000 or similar
+                    features.add(Feature.OCTAL_INT_LITERAL)
 
         elif n.type == token.SLASH:
             if n.parent and n.parent.type in {
@@ -1171,10 +1180,31 @@ def get_features_used(node: Node) -> Set[Feature]:  # noqa: C901
                         if argch.type in STARS:
                             features.add(feature)
 
-        elif n.type == token.PRINT_STMT:
+        # Python 2 only features (for its deprecation) except for integers, see above
+        elif n.type == syms.print_stmt:
             features.add(Feature.PRINT_STMT)
-        elif n.type == token.EXEC_STMT:
+        elif n.type == syms.exec_stmt:
             features.add(Feature.EXEC_STMT)
+        elif n.type == syms.tfpdef:
+            # def set_position((x, y), value):
+            #     ...
+            features.add(Feature.AUTOMATIC_PARAMETER_UNPACKING)
+        elif n.type == syms.except_clause:
+            # try:
+            #     ...
+            # except Exception, err:
+            #     ...
+            if len(n.children) >= 4:
+                if n.children[-2].type == token.COMMA:
+                    features.add(Feature.COMMA_STYLE_EXCEPT)
+        elif n.type == syms.raise_stmt:
+            # raise Exception, "msg"
+            if len(n.children) >= 4:
+                if n.children[-2].type == token.COMMA:
+                    features.add(Feature.COMMA_STYLE_RAISE)
+        elif n.type == token.BACKQUOTE:
+            # `i'm surprised this ever existed`
+            features.add(Feature.BACKQUOTE_REPR)
 
     return features
 
diff --git a/src/black/mode.py b/src/black/mode.py
index 374c47a42eb..01ee336366c 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -44,6 +44,12 @@ class Feature(Enum):
     # temporary for Python 2 deprecation
     PRINT_STMT = 200
     EXEC_STMT = 201
+    AUTOMATIC_PARAMETER_UNPACKING = 202
+    COMMA_STYLE_EXCEPT = 203
+    COMMA_STYLE_RAISE = 204
+    LONG_INT_LITERAL = 205
+    OCTAL_INT_LITERAL = 206
+    BACKQUOTE_REPR = 207
 
 
 VERSION_TO_FEATURES: Dict[TargetVersion, Set[Feature]] = {
@@ -51,6 +57,12 @@ class Feature(Enum):
         Feature.ASYNC_IDENTIFIERS,
         Feature.PRINT_STMT,
         Feature.EXEC_STMT,
+        Feature.AUTOMATIC_PARAMETER_UNPACKING,
+        Feature.COMMA_STYLE_EXCEPT,
+        Feature.COMMA_STYLE_RAISE,
+        Feature.LONG_INT_LITERAL,
+        Feature.OCTAL_INT_LITERAL,
+        Feature.BACKQUOTE_REPR,
     },
     TargetVersion.PY33: {Feature.UNICODE_LITERALS, Feature.ASYNC_IDENTIFIERS},
     TargetVersion.PY34: {Feature.UNICODE_LITERALS, Feature.ASYNC_IDENTIFIERS},
diff --git a/src/blib2to3/pgen2/token.py b/src/blib2to3/pgen2/token.py
index 349ba8023a2..1e0dec9c714 100644
--- a/src/blib2to3/pgen2/token.py
+++ b/src/blib2to3/pgen2/token.py
@@ -74,9 +74,6 @@
 COLONEQUAL: Final = 59
 N_TOKENS: Final = 60
 NT_OFFSET: Final = 256
-# temporary for Python 2 deprecation
-PRINT_STMT: Final = 316
-EXEC_STMT: Final = 288
 # --end constants--
 
 tok_name: Final[Dict[int, str]] = {}
diff --git a/tests/data/python2_detection.py b/tests/data/python2_detection.py
new file mode 100644
index 00000000000..8de2bb58adc
--- /dev/null
+++ b/tests/data/python2_detection.py
@@ -0,0 +1,90 @@
+# This uses a similar construction to the decorators.py test data file FYI.
+
+print "hello, world!"
+
+###
+
+exec "print('hello, world!')"
+
+###
+
+def set_position((x, y), value):
+    pass
+
+###
+
+try:
+    pass
+except Exception, err:
+    pass
+
+###
+
+raise RuntimeError, "I feel like crashing today :p"
+
+###
+
+`wow_these_really_did_exist`
+
+###
+
+10L
+
+###
+
+10l
+
+###
+
+0123
+
+# output
+
+print("hello python three!")
+
+###
+
+exec("I'm not sure if you can use exec like this but that's not important here!")
+
+###
+
+try:
+    pass
+except make_exception(1, 2):
+    pass
+
+###
+
+try:
+    pass
+except Exception as err:
+    pass
+
+###
+
+raise RuntimeError(make_msg(1, 2))
+
+###
+
+raise RuntimeError("boom!",)
+
+###
+
+def set_position(x, y, value):
+    pass
+
+###
+
+10
+
+###
+
+0
+
+###
+
+000
+
+###
+
+0o12
\ No newline at end of file
diff --git a/tests/test_black.py b/tests/test_black.py
index b96a5438557..7dbc3809d26 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -2017,6 +2017,7 @@ def test_get_sources_with_stdin_filename_and_force_exclude(self) -> None:
         )
 
 
+@pytest.mark.python2
 @pytest.mark.parametrize("explicit", [True, False], ids=["explicit", "autodetection"])
 def test_python_2_deprecation_with_target_version(explicit: bool) -> None:
     args = [
@@ -2032,6 +2033,20 @@ def test_python_2_deprecation_with_target_version(explicit: bool) -> None:
     assert "DEPRECATION: Python 2 support will be removed" in result.stderr
 
 
+@pytest.mark.python2
+def test_python_2_deprecation_autodetection_extended() -> None:
+    # this test has a similar construction to test_get_features_used_decorator
+    python2, non_python2 = read_data("python2_detection")
+    for python2_case in python2.split("###"):
+        node = black.lib2to3_parse(python2_case)
+        assert black.detect_target_versions(node) == {TargetVersion.PY27}, python2_case
+    for non_python2_case in non_python2.split("###"):
+        node = black.lib2to3_parse(non_python2_case)
+        assert black.detect_target_versions(node) != {
+            TargetVersion.PY27
+        }, non_python2_case
+
+
 with open(black.__file__, "r", encoding="utf-8") as _bf:
     black_source_lines = _bf.readlines()
 

From 53cabe7265eba322e102572acf8af69ea9b2fd62 Mon Sep 17 00:00:00 2001
From: Kian Meng Ang <kianmeng.ang@gmail.com>
Date: Fri, 12 Nov 2021 11:02:43 +0800
Subject: [PATCH 0334/1034] Fix typos (#2603)

---
 CHANGES.md                          | 2 +-
 docs/the_black_code_style/index.rst | 6 +++---
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 215680ff2ee..4b8dc57388c 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -14,7 +14,7 @@
 - Document stability policy, that will apply for non-beta releases (#2529)
 - Add new `--workers` parameter (#2514)
 - Fixed feature detection for positional-only arguments in lambdas (#2532)
-- Bumped typed-ast version minimum to 1.4.3 for 3.10 compatiblity (#2519)
+- Bumped typed-ast version minimum to 1.4.3 for 3.10 compatibility (#2519)
 - Fixed a Python 3.10 compatibility issue where the loop argument was still being passed
   even though it has been removed (#2580)
 - Deprecate Python 2 formatting support (#2523)
diff --git a/docs/the_black_code_style/index.rst b/docs/the_black_code_style/index.rst
index 7c2e1753937..d53703277e4 100644
--- a/docs/the_black_code_style/index.rst
+++ b/docs/the_black_code_style/index.rst
@@ -10,8 +10,8 @@ The Black Code Style
 *Black* is a PEP 8 compliant opinionated formatter with its own style.
 
 While keeping the style unchanged throughout releases has always been a goal,
-the *Black* code style isn't set in stone. It evolves to accomodate for new features
-in the Python language and, ocassionally, in response to user feedback.
+the *Black* code style isn't set in stone. It evolves to accommodate for new features
+in the Python language and, occasionally, in response to user feedback.
 
 Stability Policy
 ----------------
@@ -32,7 +32,7 @@ versions of *Black*:
   improved formatting enabled by newer Python language syntax as well as due
   to improvements in the formatting logic.
 
-- The ``--future`` flag is exempt from this policy. There are no guarentees
+- The ``--future`` flag is exempt from this policy. There are no guarantees
   around the stability of the output with that flag passed into *Black*. This
   flag is intended for allowing experimentation with the proposed changes to
   the *Black* code style.

From 5e191c29d4492d14f9090a924a77b3dc055443a6 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Fri, 12 Nov 2021 20:41:46 -0500
Subject: [PATCH 0335/1034] Bump deps in Pipfile.lock (GH-2605)

Mostly because the hashes for typed-ast were valid for 1.4.2 when the
version is pinned to 1.4.3 ... pipenv is pleasant to use /s
---
 Pipfile.lock | 1891 +++++++++++++++++++++++++++++++-------------------
 1 file changed, 1165 insertions(+), 726 deletions(-)

diff --git a/Pipfile.lock b/Pipfile.lock
index 2ddeca88fff..9d0f708bead 100644
--- a/Pipfile.lock
+++ b/Pipfile.lock
@@ -16,54 +16,105 @@
     "default": {
         "aiohttp": {
             "hashes": [
-                "sha256:02f46fc0e3c5ac58b80d4d56eb0a7c7d97fcef69ace9326289fb9f1955e65cfe",
-                "sha256:0563c1b3826945eecd62186f3f5c7d31abb7391fedc893b7e2b26303b5a9f3fe",
-                "sha256:114b281e4d68302a324dd33abb04778e8557d88947875cbf4e842c2c01a030c5",
-                "sha256:14762875b22d0055f05d12abc7f7d61d5fd4fe4642ce1a249abdf8c700bf1fd8",
-                "sha256:15492a6368d985b76a2a5fdd2166cddfea5d24e69eefed4630cbaae5c81d89bd",
-                "sha256:17c073de315745a1510393a96e680d20af8e67e324f70b42accbd4cb3315c9fb",
-                "sha256:209b4a8ee987eccc91e2bd3ac36adee0e53a5970b8ac52c273f7f8fd4872c94c",
-                "sha256:230a8f7e24298dea47659251abc0fd8b3c4e38a664c59d4b89cca7f6c09c9e87",
-                "sha256:2e19413bf84934d651344783c9f5e22dee452e251cfd220ebadbed2d9931dbf0",
-                "sha256:393f389841e8f2dfc86f774ad22f00923fdee66d238af89b70ea314c4aefd290",
-                "sha256:3cf75f7cdc2397ed4442594b935a11ed5569961333d49b7539ea741be2cc79d5",
-                "sha256:3d78619672183be860b96ed96f533046ec97ca067fd46ac1f6a09cd9b7484287",
-                "sha256:40eced07f07a9e60e825554a31f923e8d3997cfc7fb31dbc1328c70826e04cde",
-                "sha256:493d3299ebe5f5a7c66b9819eacdcfbbaaf1a8e84911ddffcdc48888497afecf",
-                "sha256:4b302b45040890cea949ad092479e01ba25911a15e648429c7c5aae9650c67a8",
-                "sha256:515dfef7f869a0feb2afee66b957cc7bbe9ad0cdee45aec7fdc623f4ecd4fb16",
-                "sha256:547da6cacac20666422d4882cfcd51298d45f7ccb60a04ec27424d2f36ba3eaf",
-                "sha256:5df68496d19f849921f05f14f31bd6ef53ad4b00245da3195048c69934521809",
-                "sha256:64322071e046020e8797117b3658b9c2f80e3267daec409b350b6a7a05041213",
-                "sha256:7615dab56bb07bff74bc865307aeb89a8bfd9941d2ef9d817b9436da3a0ea54f",
-                "sha256:79ebfc238612123a713a457d92afb4096e2148be17df6c50fb9bf7a81c2f8013",
-                "sha256:7b18b97cf8ee5452fa5f4e3af95d01d84d86d32c5e2bfa260cf041749d66360b",
-                "sha256:932bb1ea39a54e9ea27fc9232163059a0b8855256f4052e776357ad9add6f1c9",
-                "sha256:a00bb73540af068ca7390e636c01cbc4f644961896fa9363154ff43fd37af2f5",
-                "sha256:a5ca29ee66f8343ed336816c553e82d6cade48a3ad702b9ffa6125d187e2dedb",
-                "sha256:af9aa9ef5ba1fd5b8c948bb11f44891968ab30356d65fd0cc6707d989cd521df",
-                "sha256:bb437315738aa441251214dad17428cafda9cdc9729499f1d6001748e1d432f4",
-                "sha256:bdb230b4943891321e06fc7def63c7aace16095be7d9cf3b1e01be2f10fba439",
-                "sha256:c6e9dcb4cb338d91a73f178d866d051efe7c62a7166653a91e7d9fb18274058f",
-                "sha256:cffe3ab27871bc3ea47df5d8f7013945712c46a3cc5a95b6bee15887f1675c22",
-                "sha256:d012ad7911653a906425d8473a1465caa9f8dea7fcf07b6d870397b774ea7c0f",
-                "sha256:d9e13b33afd39ddeb377eff2c1c4f00544e191e1d1dee5b6c51ddee8ea6f0cf5",
-                "sha256:e4b2b334e68b18ac9817d828ba44d8fcb391f6acb398bcc5062b14b2cbeac970",
-                "sha256:e54962802d4b8b18b6207d4a927032826af39395a3bd9196a5af43fc4e60b009",
-                "sha256:f705e12750171c0ab4ef2a3c76b9a4024a62c4103e3a55dd6f99265b9bc6fcfc",
-                "sha256:f881853d2643a29e643609da57b96d5f9c9b93f62429dcc1cbb413c7d07f0e1a",
-                "sha256:fe60131d21b31fd1a14bd43e6bb88256f69dfc3188b3a89d736d6c71ed43ec95"
+                "sha256:09754a0d5eaab66c37591f2f8fac8f9781a5f61d51aa852a3261c4805ca6b984",
+                "sha256:097ecf52f6b9859b025c1e36401f8aa4573552e887d1b91b4b999d68d0b5a3b3",
+                "sha256:0a96473a1f61d7920a9099bc8e729dc8282539d25f79c12573ee0fdb9c8b66a8",
+                "sha256:0af379221975054162959e00daf21159ff69a712fc42ed0052caddbd70d52ff4",
+                "sha256:0d7b056fd3972d353cb4bc305c03f9381583766b7f8c7f1c44478dba69099e33",
+                "sha256:14a6f026eca80dfa3d52e86be89feb5cd878f6f4a6adb34457e2c689fd85229b",
+                "sha256:15a660d06092b7c92ed17c1dbe6c1eab0a02963992d60e3e8b9d5fa7fa81f01e",
+                "sha256:1fa9f50aa1f114249b7963c98e20dc35c51be64096a85bc92433185f331de9cc",
+                "sha256:257f4fad1714d26d562572095c8c5cd271d5a333252795cb7a002dca41fdbad7",
+                "sha256:28369fe331a59d80393ec82df3d43307c7461bfaf9217999e33e2acc7984ff7c",
+                "sha256:2bdd655732e38b40f8a8344d330cfae3c727fb257585df923316aabbd489ccb8",
+                "sha256:2f44d1b1c740a9e2275160d77c73a11f61e8a916191c572876baa7b282bcc934",
+                "sha256:3ba08a71caa42eef64357257878fb17f3fba3fba6e81a51d170e32321569e079",
+                "sha256:3c5e9981e449d54308c6824f172ec8ab63eb9c5f922920970249efee83f7e919",
+                "sha256:3f58aa995b905ab82fe228acd38538e7dc1509e01508dcf307dad5046399130f",
+                "sha256:48c996eb91bfbdab1e01e2c02e7ff678c51e2b28e3a04e26e41691991cc55795",
+                "sha256:48f218a5257b6bc16bcf26a91d97ecea0c7d29c811a90d965f3dd97c20f016d6",
+                "sha256:4a6551057a846bf72c7a04f73de3fcaca269c0bd85afe475ceb59d261c6a938c",
+                "sha256:51f90dabd9933b1621260b32c2f0d05d36923c7a5a909eb823e429dba0fd2f3e",
+                "sha256:577cc2c7b807b174814dac2d02e673728f2e46c7f90ceda3a70ea4bb6d90b769",
+                "sha256:5d79174d96446a02664e2bffc95e7b6fa93b9e6d8314536c5840dff130d0878b",
+                "sha256:5e3f81fbbc170418e22918a9585fd7281bbc11d027064d62aa4b507552c92671",
+                "sha256:5ecffdc748d3b40dd3618ede0170e4f5e1d3c9647cfb410d235d19e62cb54ee0",
+                "sha256:63fa57a0708573d3c059f7b5527617bd0c291e4559298473df238d502e4ab98c",
+                "sha256:67ca7032dfac8d001023fadafc812d9f48bf8a8c3bb15412d9cdcf92267593f4",
+                "sha256:688a1eb8c1a5f7e795c7cb67e0fe600194e6723ba35f138dfae0db20c0cb8f94",
+                "sha256:6a038cb1e6e55b26bb5520ccffab7f539b3786f5553af2ee47eb2ec5cbd7084e",
+                "sha256:6b79f6c31e68b6dafc0317ec453c83c86dd8db1f8f0c6f28e97186563fca87a0",
+                "sha256:6d3e027fe291b77f6be9630114a0200b2c52004ef20b94dc50ca59849cd623b3",
+                "sha256:6f1d39a744101bf4043fa0926b3ead616607578192d0a169974fb5265ab1e9d2",
+                "sha256:707adc30ea6918fba725c3cb3fe782d271ba352b22d7ae54a7f9f2e8a8488c41",
+                "sha256:730b7c2b7382194d9985ffdc32ab317e893bca21e0665cb1186bdfbb4089d990",
+                "sha256:764c7c6aa1f78bd77bd9674fc07d1ec44654da1818d0eef9fb48aa8371a3c847",
+                "sha256:78d51e35ed163783d721b6f2ce8ce3f82fccfe471e8e50a10fba13a766d31f5a",
+                "sha256:7a315ceb813208ef32bdd6ec3a85cbe3cb3be9bbda5fd030c234592fa9116993",
+                "sha256:7ba09bb3dcb0b7ec936a485db2b64be44fe14cdce0a5eac56f50e55da3627385",
+                "sha256:7d76e8a83396e06abe3df569b25bd3fc88bf78b7baa2c8e4cf4aaf5983af66a3",
+                "sha256:84fe1732648c1bc303a70faa67cbc2f7f2e810c8a5bca94f6db7818e722e4c0a",
+                "sha256:871d4fdc56288caa58b1094c20f2364215f7400411f76783ea19ad13be7c8e19",
+                "sha256:88d4917c30fcd7f6404fb1dc713fa21de59d3063dcc048f4a8a1a90e6bbbd739",
+                "sha256:8a50150419b741ee048b53146c39c47053f060cb9d98e78be08fdbe942eaa3c4",
+                "sha256:90a97c2ed2830e7974cbe45f0838de0aefc1c123313f7c402e21c29ec063fbb4",
+                "sha256:949a605ef3907254b122f845baa0920407080cdb1f73aa64f8d47df4a7f4c4f9",
+                "sha256:9689af0f0a89e5032426c143fa3683b0451f06c83bf3b1e27902bd33acfae769",
+                "sha256:98b1ea2763b33559dd9ec621d67fc17b583484cb90735bfb0ec3614c17b210e4",
+                "sha256:9951c2696c4357703001e1fe6edc6ae8e97553ac630492ea1bf64b429cb712a3",
+                "sha256:9a52b141ff3b923a9166595de6e3768a027546e75052ffba267d95b54267f4ab",
+                "sha256:9e8723c3256641e141cd18f6ce478d54a004138b9f1a36e41083b36d9ecc5fc5",
+                "sha256:a2fee4d656a7cc9ab47771b2a9e8fad8a9a33331c1b59c3057ecf0ac858f5bfe",
+                "sha256:a4759e85a191de58e0ea468ab6fd9c03941986eee436e0518d7a9291fab122c8",
+                "sha256:a5399a44a529083951b55521cf4ecbf6ad79fd54b9df57dbf01699ffa0549fc9",
+                "sha256:a6074a3b2fa2d0c9bf0963f8dfc85e1e54a26114cc8594126bc52d3fa061c40e",
+                "sha256:a84c335337b676d832c1e2bc47c3a97531b46b82de9f959dafb315cbcbe0dfcd",
+                "sha256:adf0cb251b1b842c9dee5cfcdf880ba0aae32e841b8d0e6b6feeaef002a267c5",
+                "sha256:b76669b7c058b8020b11008283c3b8e9c61bfd978807c45862956119b77ece45",
+                "sha256:bda75d73e7400e81077b0910c9a60bf9771f715420d7e35fa7739ae95555f195",
+                "sha256:be03a7483ad9ea60388f930160bb3728467dd0af538aa5edc60962ee700a0bdc",
+                "sha256:c62d4791a8212c885b97a63ef5f3974b2cd41930f0cd224ada9c6ee6654f8150",
+                "sha256:cb751ef712570d3bda9a73fd765ff3e1aba943ec5d52a54a0c2e89c7eef9da1e",
+                "sha256:d3b19d8d183bcfd68b25beebab8dc3308282fe2ca3d6ea3cb4cd101b3c279f8d",
+                "sha256:d3f90ee275b1d7c942e65b5c44c8fb52d55502a0b9a679837d71be2bd8927661",
+                "sha256:d5f8c04574efa814a24510122810e3a3c77c0552f9f6ff65c9862f1f046be2c3",
+                "sha256:d6a1a66bb8bac9bc2892c2674ea363486bfb748b86504966a390345a11b1680e",
+                "sha256:d7715daf84f10bcebc083ad137e3eced3e1c8e7fa1f096ade9a8d02b08f0d91c",
+                "sha256:dafc01a32b4a1d7d3ef8bfd3699406bb44f7b2e0d3eb8906d574846e1019b12f",
+                "sha256:dcc4d5dd5fba3affaf4fd08f00ef156407573de8c63338787614ccc64f96b321",
+                "sha256:de42f513ed7a997bc821bddab356b72e55e8396b1b7ba1bf39926d538a76a90f",
+                "sha256:e27cde1e8d17b09730801ce97b6e0c444ba2a1f06348b169fd931b51d3402f0d",
+                "sha256:ecb314e59bedb77188017f26e6b684b1f6d0465e724c3122a726359fa62ca1ba",
+                "sha256:f348ebd20554e8bc26e8ef3ed8a134110c0f4bf015b3b4da6a4ddf34e0515b19",
+                "sha256:fa818609357dde5c4a94a64c097c6404ad996b1d38ca977a72834b682830a722",
+                "sha256:fe4a327da0c6b6e59f2e474ae79d6ee7745ac3279fd15f200044602fa31e3d79"
             ],
             "index": "pypi",
-            "version": "==3.7.4.post0"
+            "version": "==3.8.0"
+        },
+        "aiosignal": {
+            "hashes": [
+                "sha256:26e62109036cd181df6e6ad646f91f0dcfd05fe16d0cb924138ff2ab75d64e3a",
+                "sha256:78ed67db6c7b7ced4f98e495e572106d5c432a93e1ddd1bf475e1dc05f5b7df2"
+            ],
+            "markers": "python_version >= '3.6'",
+            "version": "==1.2.0"
         },
         "async-timeout": {
             "hashes": [
-                "sha256:0c3c816a028d47f659d6ff5c745cb2acf1f966da1fe5c19c77a70282b25f4c5f",
-                "sha256:4291ca197d287d274d0b6cb5d6f8f8f82d434ed288f962539ff18cc9012f9ea3"
+                "sha256:a22c0b311af23337eb05fcf05a8b51c3ea53729d46fb5460af62bee033cec690",
+                "sha256:b930cb161a39042f9222f6efb7301399c87eeab394727ec5437924a36d6eef51"
             ],
-            "markers": "python_full_version >= '3.5.3'",
-            "version": "==3.0.1"
+            "markers": "python_version >= '3.6'",
+            "version": "==4.0.1"
+        },
+        "asynctest": {
+            "hashes": [
+                "sha256:5da6118a7e6d6b54d83a8f7197769d046922a44d2a99c21382f0a6e4fadae676",
+                "sha256:c27862842d15d83e6a34eb0b2866c323880eb3a75e4485b079ea11748fd77fac"
+            ],
+            "markers": "python_version < '3.8'",
+            "version": "==0.13.0"
         },
         "attrs": {
             "hashes": [
@@ -80,21 +131,21 @@
             ],
             "path": "."
         },
-        "chardet": {
+        "charset-normalizer": {
             "hashes": [
-                "sha256:0d6f53a15db4120f2b08c94f11e7d93d2c911ee118b6b30a04ec3ee8310179fa",
-                "sha256:f864054d66fd9118f2e67044ac8981a54775ec5b67aed0441892edb553d21da5"
+                "sha256:e019de665e2bcf9c2b64e2e5aa025fa991da8720daa3c1138cadd2fd1856aed0",
+                "sha256:f7af805c321bfa1ce6714c51f254e0d5bb5e5834039bc17db7ebe3a4cec9492b"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
-            "version": "==4.0.0"
+            "markers": "python_version >= '3.5'",
+            "version": "==2.0.7"
         },
         "click": {
             "hashes": [
-                "sha256:8c04c11192119b1ef78ea049e0a6f0463e4c48ef00a30160c704337586f3ad7a",
-                "sha256:fba402a4a47334742d782209a7c79bc448911afe1149d07bdabdf480b3e2f4b6"
+                "sha256:353f466495adaeb40b6b5f592f9f91cb22372351c84caeb068132442a4518ef3",
+                "sha256:410e932b050f5eed773c4cda94de75971c89cdb3155a72a0831139a79e5ecb5b"
             ],
             "index": "pypi",
-            "version": "==8.0.1"
+            "version": "==8.0.3"
         },
         "dataclasses": {
             "hashes": [
@@ -105,13 +156,91 @@
             "markers": "python_version < '3.7'",
             "version": "==0.8"
         },
+        "frozenlist": {
+            "hashes": [
+                "sha256:01d79515ed5aa3d699b05f6bdcf1fe9087d61d6b53882aa599a10853f0479c6c",
+                "sha256:0a7c7cce70e41bc13d7d50f0e5dd175f14a4f1837a8549b0936ed0cbe6170bf9",
+                "sha256:11ff401951b5ac8c0701a804f503d72c048173208490c54ebb8d7bb7c07a6d00",
+                "sha256:14a5cef795ae3e28fb504b73e797c1800e9249f950e1c964bb6bdc8d77871161",
+                "sha256:16eef427c51cb1203a7c0ab59d1b8abccaba9a4f58c4bfca6ed278fc896dc193",
+                "sha256:16ef7dd5b7d17495404a2e7a49bac1bc13d6d20c16d11f4133c757dd94c4144c",
+                "sha256:181754275d5d32487431a0a29add4f897968b7157204bc1eaaf0a0ce80c5ba7d",
+                "sha256:1cf63243bc5f5c19762943b0aa9e0d3fb3723d0c514d820a18a9b9a5ef864315",
+                "sha256:1cfe6fef507f8bac40f009c85c7eddfed88c1c0d38c75e72fe10476cef94e10f",
+                "sha256:1fef737fd1388f9b93bba8808c5f63058113c10f4e3c0763ced68431773f72f9",
+                "sha256:25b358aaa7dba5891b05968dd539f5856d69f522b6de0bf34e61f133e077c1a4",
+                "sha256:26f602e380a5132880fa245c92030abb0fc6ff34e0c5500600366cedc6adb06a",
+                "sha256:28e164722ea0df0cf6d48c4d5bdf3d19e87aaa6dfb39b0ba91153f224b912020",
+                "sha256:2de5b931701257d50771a032bba4e448ff958076380b049fd36ed8738fdb375b",
+                "sha256:3457f8cf86deb6ce1ba67e120f1b0128fcba1332a180722756597253c465fc1d",
+                "sha256:351686ca020d1bcd238596b1fa5c8efcbc21bffda9d0efe237aaa60348421e2a",
+                "sha256:406aeb340613b4b559db78d86864485f68919b7141dec82aba24d1477fd2976f",
+                "sha256:41de4db9b9501679cf7cddc16d07ac0f10ef7eb58c525a1c8cbff43022bddca4",
+                "sha256:41f62468af1bd4e4b42b5508a3fe8cc46a693f0cdd0ca2f443f51f207893d837",
+                "sha256:4766632cd8a68e4f10f156a12c9acd7b1609941525569dd3636d859d79279ed3",
+                "sha256:47b2848e464883d0bbdcd9493c67443e5e695a84694efff0476f9059b4cb6257",
+                "sha256:4a495c3d513573b0b3f935bfa887a85d9ae09f0627cf47cad17d0cc9b9ba5c38",
+                "sha256:4ad065b2ebd09f32511ff2be35c5dfafee6192978b5a1e9d279a5c6e121e3b03",
+                "sha256:4c457220468d734e3077580a3642b7f682f5fd9507f17ddf1029452450912cdc",
+                "sha256:4f52d0732e56906f8ddea4bd856192984650282424049c956857fed43697ea43",
+                "sha256:54a1e09ab7a69f843cd28fefd2bcaf23edb9e3a8d7680032c8968b8ac934587d",
+                "sha256:5a72eecf37eface331636951249d878750db84034927c997d47f7f78a573b72b",
+                "sha256:5df31bb2b974f379d230a25943d9bf0d3bc666b4b0807394b131a28fca2b0e5f",
+                "sha256:66a518731a21a55b7d3e087b430f1956a36793acc15912e2878431c7aec54210",
+                "sha256:6790b8d96bbb74b7a6f4594b6f131bd23056c25f2aa5d816bd177d95245a30e3",
+                "sha256:68201be60ac56aff972dc18085800b6ee07973c49103a8aba669dee3d71079de",
+                "sha256:6e105013fa84623c057a4381dc8ea0361f4d682c11f3816cc80f49a1f3bc17c6",
+                "sha256:705c184b77565955a99dc360f359e8249580c6b7eaa4dc0227caa861ef46b27a",
+                "sha256:72cfbeab7a920ea9e74b19aa0afe3b4ad9c89471e3badc985d08756efa9b813b",
+                "sha256:735f386ec522e384f511614c01d2ef9cf799f051353876b4c6fb93ef67a6d1ee",
+                "sha256:82d22f6e6f2916e837c91c860140ef9947e31194c82aaeda843d6551cec92f19",
+                "sha256:83334e84a290a158c0c4cc4d22e8c7cfe0bba5b76d37f1c2509dabd22acafe15",
+                "sha256:84e97f59211b5b9083a2e7a45abf91cfb441369e8bb6d1f5287382c1c526def3",
+                "sha256:87521e32e18a2223311afc2492ef2d99946337da0779ddcda77b82ee7319df59",
+                "sha256:878ebe074839d649a1cdb03a61077d05760624f36d196884a5cafb12290e187b",
+                "sha256:89fdfc84c6bf0bff2ff3170bb34ecba8a6911b260d318d377171429c4be18c73",
+                "sha256:8b4c7665a17c3a5430edb663e4ad4e1ad457614d1b2f2b7f87052e2ef4fa45ca",
+                "sha256:8b54cdd2fda15467b9b0bfa78cee2ddf6dbb4585ef23a16e14926f4b076dfae4",
+                "sha256:94728f97ddf603d23c8c3dd5cae2644fa12d33116e69f49b1644a71bb77b89ae",
+                "sha256:954b154a4533ef28bd3e83ffdf4eadf39deeda9e38fb8feaf066d6069885e034",
+                "sha256:977a1438d0e0d96573fd679d291a1542097ea9f4918a8b6494b06610dfeefbf9",
+                "sha256:9ade70aea559ca98f4b1b1e5650c45678052e76a8ab2f76d90f2ac64180215a2",
+                "sha256:9b6e21e5770df2dea06cb7b6323fbc008b13c4a4e3b52cb54685276479ee7676",
+                "sha256:a0d3ffa8772464441b52489b985d46001e2853a3b082c655ec5fad9fb6a3d618",
+                "sha256:a37594ad6356e50073fe4f60aa4187b97d15329f2138124d252a5a19c8553ea4",
+                "sha256:a8d86547a5e98d9edd47c432f7a14b0c5592624b496ae9880fb6332f34af1edc",
+                "sha256:aa44c4740b4e23fcfa259e9dd52315d2b1770064cde9507457e4c4a65a04c397",
+                "sha256:acc4614e8d1feb9f46dd829a8e771b8f5c4b1051365d02efb27a3229048ade8a",
+                "sha256:af2a51c8a381d76eabb76f228f565ed4c3701441ecec101dd18be70ebd483cfd",
+                "sha256:b2ae2f5e9fa10805fb1c9adbfefaaecedd9e31849434be462c3960a0139ed729",
+                "sha256:b46f997d5ed6d222a863b02cdc9c299101ee27974d9bbb2fd1b3c8441311c408",
+                "sha256:bc93f5f62df3bdc1f677066327fc81f92b83644852a31c6aa9b32c2dde86ea7d",
+                "sha256:bfbaa08cf1452acad9cb1c1d7b89394a41e712f88df522cea1a0f296b57782a0",
+                "sha256:c1e8e9033d34c2c9e186e58279879d78c94dd365068a3607af33f2bc99357a53",
+                "sha256:c5328ed53fdb0a73c8a50105306a3bc013e5ca36cca714ec4f7bd31d38d8a97f",
+                "sha256:c6a9d84ee6427b65a81fc24e6ef589cb794009f5ca4150151251c062773e7ed2",
+                "sha256:c98d3c04701773ad60d9545cd96df94d955329efc7743fdb96422c4b669c633b",
+                "sha256:cb3957c39668d10e2b486acc85f94153520a23263b6401e8f59422ef65b9520d",
+                "sha256:e63ad0beef6ece06475d29f47d1f2f29727805376e09850ebf64f90777962792",
+                "sha256:e74f8b4d8677ebb4015ac01fcaf05f34e8a1f22775db1f304f497f2f88fdc697",
+                "sha256:e7d0dd3e727c70c2680f5f09a0775525229809f1a35d8552b92ff10b2b14f2c2",
+                "sha256:ec6cf345771cdb00791d271af9a0a6fbfc2b6dd44cb753f1eeaa256e21622adb",
+                "sha256:ed58803563a8c87cf4c0771366cf0ad1aa265b6b0ae54cbbb53013480c7ad74d",
+                "sha256:f0081a623c886197ff8de9e635528fd7e6a387dccef432149e25c13946cb0cd0",
+                "sha256:f025f1d6825725b09c0038775acab9ae94264453a696cc797ce20c0769a7b367",
+                "sha256:f5f3b2942c3b8b9bfe76b408bbaba3d3bb305ee3693e8b1d631fe0a0d4f93673",
+                "sha256:fbd4844ff111449f3bbe20ba24fbb906b5b1c2384d0f3287c9f7da2354ce6d23"
+            ],
+            "markers": "python_version >= '3.6'",
+            "version": "==1.2.0"
+        },
         "idna": {
             "hashes": [
-                "sha256:14475042e284991034cb48e06f6851428fb14c4dc953acd9be9a5e95c7b6dd7a",
-                "sha256:467fbad99067910785144ce333826c71fb0e63a425657295239737f7ecd125f3"
+                "sha256:84d9dd047ffa80596e0f246e2eab0b391788b0503584e8945f2368256d2735ff",
+                "sha256:9d643ff0a55b762d5cdb124b8eaa99c66322e2157b69160bc32796e824360e6d"
             ],
             "markers": "python_version >= '3.5'",
-            "version": "==3.2"
+            "version": "==3.3"
         },
         "idna-ssl": {
             "hashes": [
@@ -122,54 +251,89 @@
         },
         "importlib-metadata": {
             "hashes": [
-                "sha256:7b30a78db2922d78a6f47fb30683156a14f3c6aa5cc23f77cc8967e9ab2d002f",
-                "sha256:ed5157fef23a4bc4594615a0dd8eba94b2bb36bf2a343fa3d8bb2fa0a62a99d5"
+                "sha256:53ccfd5c134223e497627b9815d5030edf77d2ed573922f7a0b8f8bb81a1c100",
+                "sha256:75bdec14c397f528724c1bfd9709d660b33a4d2e77387a3358f20b848bb5e5fb"
             ],
             "markers": "python_version < '3.8'",
-            "version": "==4.6.4"
+            "version": "==4.8.2"
         },
         "multidict": {
             "hashes": [
-                "sha256:018132dbd8688c7a69ad89c4a3f39ea2f9f33302ebe567a879da8f4ca73f0d0a",
-                "sha256:051012ccee979b2b06be928a6150d237aec75dd6bf2d1eeeb190baf2b05abc93",
-                "sha256:05c20b68e512166fddba59a918773ba002fdd77800cad9f55b59790030bab632",
-                "sha256:07b42215124aedecc6083f1ce6b7e5ec5b50047afa701f3442054373a6deb656",
-                "sha256:0e3c84e6c67eba89c2dbcee08504ba8644ab4284863452450520dad8f1e89b79",
-                "sha256:0e929169f9c090dae0646a011c8b058e5e5fb391466016b39d21745b48817fd7",
-                "sha256:1ab820665e67373de5802acae069a6a05567ae234ddb129f31d290fc3d1aa56d",
-                "sha256:25b4e5f22d3a37ddf3effc0710ba692cfc792c2b9edfb9c05aefe823256e84d5",
-                "sha256:2e68965192c4ea61fff1b81c14ff712fc7dc15d2bd120602e4a3494ea6584224",
-                "sha256:2f1a132f1c88724674271d636e6b7351477c27722f2ed789f719f9e3545a3d26",
-                "sha256:37e5438e1c78931df5d3c0c78ae049092877e5e9c02dd1ff5abb9cf27a5914ea",
-                "sha256:3a041b76d13706b7fff23b9fc83117c7b8fe8d5fe9e6be45eee72b9baa75f348",
-                "sha256:3a4f32116f8f72ecf2a29dabfb27b23ab7cdc0ba807e8459e59a93a9be9506f6",
-                "sha256:46c73e09ad374a6d876c599f2328161bcd95e280f84d2060cf57991dec5cfe76",
-                "sha256:46dd362c2f045095c920162e9307de5ffd0a1bfbba0a6e990b344366f55a30c1",
-                "sha256:4b186eb7d6ae7c06eb4392411189469e6a820da81447f46c0072a41c748ab73f",
-                "sha256:54fd1e83a184e19c598d5e70ba508196fd0bbdd676ce159feb412a4a6664f952",
-                "sha256:585fd452dd7782130d112f7ddf3473ffdd521414674c33876187e101b588738a",
-                "sha256:5cf3443199b83ed9e955f511b5b241fd3ae004e3cb81c58ec10f4fe47c7dce37",
-                "sha256:6a4d5ce640e37b0efcc8441caeea8f43a06addace2335bd11151bc02d2ee31f9",
-                "sha256:7df80d07818b385f3129180369079bd6934cf70469f99daaebfac89dca288359",
-                "sha256:806068d4f86cb06af37cd65821554f98240a19ce646d3cd24e1c33587f313eb8",
-                "sha256:830f57206cc96ed0ccf68304141fec9481a096c4d2e2831f311bde1c404401da",
-                "sha256:929006d3c2d923788ba153ad0de8ed2e5ed39fdbe8e7be21e2f22ed06c6783d3",
-                "sha256:9436dc58c123f07b230383083855593550c4d301d2532045a17ccf6eca505f6d",
-                "sha256:9dd6e9b1a913d096ac95d0399bd737e00f2af1e1594a787e00f7975778c8b2bf",
-                "sha256:ace010325c787c378afd7f7c1ac66b26313b3344628652eacd149bdd23c68841",
-                "sha256:b47a43177a5e65b771b80db71e7be76c0ba23cc8aa73eeeb089ed5219cdbe27d",
-                "sha256:b797515be8743b771aa868f83563f789bbd4b236659ba52243b735d80b29ed93",
-                "sha256:b7993704f1a4b204e71debe6095150d43b2ee6150fa4f44d6d966ec356a8d61f",
-                "sha256:d5c65bdf4484872c4af3150aeebe101ba560dcfb34488d9a8ff8dbcd21079647",
-                "sha256:d81eddcb12d608cc08081fa88d046c78afb1bf8107e6feab5d43503fea74a635",
-                "sha256:dc862056f76443a0db4509116c5cd480fe1b6a2d45512a653f9a855cc0517456",
-                "sha256:ecc771ab628ea281517e24fd2c52e8f31c41e66652d07599ad8818abaad38cda",
-                "sha256:f200755768dc19c6f4e2b672421e0ebb3dd54c38d5a4f262b872d8cfcc9e93b5",
-                "sha256:f21756997ad8ef815d8ef3d34edd98804ab5ea337feedcd62fb52d22bf531281",
-                "sha256:fc13a9524bc18b6fb6e0dbec3533ba0496bbed167c56d0aabefd965584557d80"
+                "sha256:06560fbdcf22c9387100979e65b26fba0816c162b888cb65b845d3def7a54c9b",
+                "sha256:067150fad08e6f2dd91a650c7a49ba65085303fcc3decbd64a57dc13a2733031",
+                "sha256:0a2cbcfbea6dc776782a444db819c8b78afe4db597211298dd8b2222f73e9cd0",
+                "sha256:0dd1c93edb444b33ba2274b66f63def8a327d607c6c790772f448a53b6ea59ce",
+                "sha256:0fed465af2e0eb6357ba95795d003ac0bdb546305cc2366b1fc8f0ad67cc3fda",
+                "sha256:116347c63ba049c1ea56e157fa8aa6edaf5e92925c9b64f3da7769bdfa012858",
+                "sha256:1b4ac3ba7a97b35a5ccf34f41b5a8642a01d1e55454b699e5e8e7a99b5a3acf5",
+                "sha256:1c7976cd1c157fa7ba5456ae5d31ccdf1479680dc9b8d8aa28afabc370df42b8",
+                "sha256:246145bff76cc4b19310f0ad28bd0769b940c2a49fc601b86bfd150cbd72bb22",
+                "sha256:25cbd39a9029b409167aa0a20d8a17f502d43f2efebfe9e3ac019fe6796c59ac",
+                "sha256:28e6d883acd8674887d7edc896b91751dc2d8e87fbdca8359591a13872799e4e",
+                "sha256:2d1d55cdf706ddc62822d394d1df53573d32a7a07d4f099470d3cb9323b721b6",
+                "sha256:2e77282fd1d677c313ffcaddfec236bf23f273c4fba7cdf198108f5940ae10f5",
+                "sha256:32fdba7333eb2351fee2596b756d730d62b5827d5e1ab2f84e6cbb287cc67fe0",
+                "sha256:35591729668a303a02b06e8dba0eb8140c4a1bfd4c4b3209a436a02a5ac1de11",
+                "sha256:380b868f55f63d048a25931a1632818f90e4be71d2081c2338fcf656d299949a",
+                "sha256:3822c5894c72e3b35aae9909bef66ec83e44522faf767c0ad39e0e2de11d3b55",
+                "sha256:38ba256ee9b310da6a1a0f013ef4e422fca30a685bcbec86a969bd520504e341",
+                "sha256:3bc3b1621b979621cee9f7b09f024ec76ec03cc365e638126a056317470bde1b",
+                "sha256:3d2d7d1fff8e09d99354c04c3fd5b560fb04639fd45926b34e27cfdec678a704",
+                "sha256:517d75522b7b18a3385726b54a081afd425d4f41144a5399e5abd97ccafdf36b",
+                "sha256:5f79c19c6420962eb17c7e48878a03053b7ccd7b69f389d5831c0a4a7f1ac0a1",
+                "sha256:5f841c4f14331fd1e36cbf3336ed7be2cb2a8f110ce40ea253e5573387db7621",
+                "sha256:637c1896497ff19e1ee27c1c2c2ddaa9f2d134bbb5e0c52254361ea20486418d",
+                "sha256:6ee908c070020d682e9b42c8f621e8bb10c767d04416e2ebe44e37d0f44d9ad5",
+                "sha256:77f0fb7200cc7dedda7a60912f2059086e29ff67cefbc58d2506638c1a9132d7",
+                "sha256:7878b61c867fb2df7a95e44b316f88d5a3742390c99dfba6c557a21b30180cac",
+                "sha256:78c106b2b506b4d895ddc801ff509f941119394b89c9115580014127414e6c2d",
+                "sha256:8b911d74acdc1fe2941e59b4f1a278a330e9c34c6c8ca1ee21264c51ec9b67ef",
+                "sha256:93de39267c4c676c9ebb2057e98a8138bade0d806aad4d864322eee0803140a0",
+                "sha256:9416cf11bcd73c861267e88aea71e9fcc35302b3943e45e1dbb4317f91a4b34f",
+                "sha256:94b117e27efd8e08b4046c57461d5a114d26b40824995a2eb58372b94f9fca02",
+                "sha256:9815765f9dcda04921ba467957be543423e5ec6a1136135d84f2ae092c50d87b",
+                "sha256:98ec9aea6223adf46999f22e2c0ab6cf33f5914be604a404f658386a8f1fba37",
+                "sha256:a37e9a68349f6abe24130846e2f1d2e38f7ddab30b81b754e5a1fde32f782b23",
+                "sha256:a43616aec0f0d53c411582c451f5d3e1123a68cc7b3475d6f7d97a626f8ff90d",
+                "sha256:a4771d0d0ac9d9fe9e24e33bed482a13dfc1256d008d101485fe460359476065",
+                "sha256:a5635bcf1b75f0f6ef3c8a1ad07b500104a971e38d3683167b9454cb6465ac86",
+                "sha256:a9acb76d5f3dd9421874923da2ed1e76041cb51b9337fd7f507edde1d86535d6",
+                "sha256:ac42181292099d91217a82e3fa3ce0e0ddf3a74fd891b7c2b347a7f5aa0edded",
+                "sha256:b227345e4186809d31f22087d0265655114af7cda442ecaf72246275865bebe4",
+                "sha256:b61f85101ef08cbbc37846ac0e43f027f7844f3fade9b7f6dd087178caedeee7",
+                "sha256:b70913cbf2e14275013be98a06ef4b412329fe7b4f83d64eb70dce8269ed1e1a",
+                "sha256:b9aad49466b8d828b96b9e3630006234879c8d3e2b0a9d99219b3121bc5cdb17",
+                "sha256:baf1856fab8212bf35230c019cde7c641887e3fc08cadd39d32a421a30151ea3",
+                "sha256:bd6c9c50bf2ad3f0448edaa1a3b55b2e6866ef8feca5d8dbec10ec7c94371d21",
+                "sha256:c1ff762e2ee126e6f1258650ac641e2b8e1f3d927a925aafcfde943b77a36d24",
+                "sha256:c30ac9f562106cd9e8071c23949a067b10211917fdcb75b4718cf5775356a940",
+                "sha256:c9631c642e08b9fff1c6255487e62971d8b8e821808ddd013d8ac058087591ac",
+                "sha256:cdd68778f96216596218b4e8882944d24a634d984ee1a5a049b300377878fa7c",
+                "sha256:ce8cacda0b679ebc25624d5de66c705bc53dcc7c6f02a7fb0f3ca5e227d80422",
+                "sha256:cfde464ca4af42a629648c0b0d79b8f295cf5b695412451716531d6916461628",
+                "sha256:d3def943bfd5f1c47d51fd324df1e806d8da1f8e105cc7f1c76a1daf0f7e17b0",
+                "sha256:d9b668c065968c5979fe6b6fa6760bb6ab9aeb94b75b73c0a9c1acf6393ac3bf",
+                "sha256:da7d57ea65744d249427793c042094c4016789eb2562576fb831870f9c878d9e",
+                "sha256:dc3a866cf6c13d59a01878cd806f219340f3e82eed514485e094321f24900677",
+                "sha256:df23c83398715b26ab09574217ca21e14694917a0c857e356fd39e1c64f8283f",
+                "sha256:dfc924a7e946dd3c6360e50e8f750d51e3ef5395c95dc054bc9eab0f70df4f9c",
+                "sha256:e4a67f1080123de76e4e97a18d10350df6a7182e243312426d508712e99988d4",
+                "sha256:e5283c0a00f48e8cafcecadebfa0ed1dac8b39e295c7248c44c665c16dc1138b",
+                "sha256:e58a9b5cc96e014ddf93c2227cbdeca94b56a7eb77300205d6e4001805391747",
+                "sha256:e6453f3cbeb78440747096f239d282cc57a2997a16b5197c9bc839099e1633d0",
+                "sha256:e6c4fa1ec16e01e292315ba76eb1d012c025b99d22896bd14a66628b245e3e01",
+                "sha256:e7d81ce5744757d2f05fc41896e3b2ae0458464b14b5a2c1e87a6a9d69aefaa8",
+                "sha256:ea21d4d5104b4f840b91d9dc8cbc832aba9612121eaba503e54eaab1ad140eb9",
+                "sha256:ecc99bce8ee42dcad15848c7885197d26841cb24fa2ee6e89d23b8993c871c64",
+                "sha256:f0bb0973f42ffcb5e3537548e0767079420aefd94ba990b61cf7bb8d47f4916d",
+                "sha256:f19001e790013ed580abfde2a4465388950728861b52f0da73e8e8a9418533c0",
+                "sha256:f76440e480c3b2ca7f843ff8a48dc82446b86ed4930552d736c0bac507498a52",
+                "sha256:f9bef5cff994ca3026fcc90680e326d1a19df9841c5e3d224076407cc21471a1",
+                "sha256:fc66d4016f6e50ed36fb39cd287a3878ffcebfa90008535c62e0e90a7ab713ae",
+                "sha256:fd77c8f3cba815aa69cb97ee2b2ef385c7c12ada9c734b0f3b32e26bb88bbf1d"
             ],
             "markers": "python_version >= '3.6'",
-            "version": "==5.1.0"
+            "version": "==5.2.0"
         },
         "mypy-extensions": {
             "hashes": [
@@ -181,11 +345,11 @@
         },
         "packaging": {
             "hashes": [
-                "sha256:7dc96269f53a4ccec5c0670940a4281106dd0bb343f47b7471f779df49c2fbe7",
-                "sha256:c86254f9220d55e31cc94d69bade760f0847da8000def4dfe1c6b872fd14ff14"
+                "sha256:096d689d78ca690e4cd8a89568ba06d07ca097e3306a4381635073ca91479966",
+                "sha256:14317396d1e8cdb122989b916fa2c7e9ca8e2be9e8060a6eff75b6b7b4d8a7e0"
             ],
             "markers": "python_version >= '3.6'",
-            "version": "==21.0"
+            "version": "==21.2"
         },
         "pathspec": {
             "hashes": [
@@ -197,227 +361,321 @@
         },
         "platformdirs": {
             "hashes": [
-                "sha256:4666d822218db6a262bdfdc9c39d21f23b4cfdb08af331a81e92751daf6c866c",
-                "sha256:632daad3ab546bd8e6af0537d09805cec458dce201bccfe23012df73332e181e"
+                "sha256:367a5e80b3d04d2428ffa76d33f124cf11e8fff2acdaa9b43d545f5c7d661ef2",
+                "sha256:8868bbe3c3c80d42f20156f22e7131d2fb321f5bc86a2a345375c6481a67021d"
             ],
             "index": "pypi",
-            "version": "==2.2.0"
+            "version": "==2.4.0"
         },
         "pyparsing": {
             "hashes": [
                 "sha256:c203ec8783bf771a155b207279b9bccb8dea02d8f0c9e5f8ead507bc3246ecc1",
                 "sha256:ef9d7589ef3c200abe66653d3f1ab1033c3c419ae9b9bdb1240a85b024efc88b"
             ],
-            "markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2, 3.3'",
+            "markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2'",
             "version": "==2.4.7"
         },
         "regex": {
             "hashes": [
-                "sha256:03840a07a402576b8e3a6261f17eb88abd653ad4e18ec46ef10c9a63f8c99ebd",
-                "sha256:06ba444bbf7ede3890a912bd4904bb65bf0da8f0d8808b90545481362c978642",
-                "sha256:1f9974826aeeda32a76648fc677e3125ade379869a84aa964b683984a2dea9f1",
-                "sha256:330836ad89ff0be756b58758878409f591d4737b6a8cef26a162e2a4961c3321",
-                "sha256:38600fd58c2996829480de7d034fb2d3a0307110e44dae80b6b4f9b3d2eea529",
-                "sha256:3a195e26df1fbb40ebee75865f9b64ba692a5824ecb91c078cc665b01f7a9a36",
-                "sha256:41acdd6d64cd56f857e271009966c2ffcbd07ec9149ca91f71088574eaa4278a",
-                "sha256:45f97ade892ace20252e5ccecdd7515c7df5feeb42c3d2a8b8c55920c3551c30",
-                "sha256:4b0c211c55d4aac4309c3209833c803fada3fc21cdf7b74abedda42a0c9dc3ce",
-                "sha256:5d5209c3ba25864b1a57461526ebde31483db295fc6195fdfc4f8355e10f7376",
-                "sha256:615fb5a524cffc91ab4490b69e10ae76c1ccbfa3383ea2fad72e54a85c7d47dd",
-                "sha256:61e734c2bcb3742c3f454dfa930ea60ea08f56fd1a0eb52d8cb189a2f6be9586",
-                "sha256:640ccca4d0a6fcc6590f005ecd7b16c3d8f5d52174e4854f96b16f34c39d6cb7",
-                "sha256:6dbd51c3db300ce9d3171f4106da18fe49e7045232630fe3d4c6e37cb2b39ab9",
-                "sha256:71a904da8c9c02aee581f4452a5a988c3003207cb8033db426f29e5b2c0b7aea",
-                "sha256:8021dee64899f993f4b5cca323aae65aabc01a546ed44356a0965e29d7893c94",
-                "sha256:8b8d551f1bd60b3e1c59ff55b9e8d74607a5308f66e2916948cafd13480b44a3",
-                "sha256:93f9f720081d97acee38a411e861d4ce84cbc8ea5319bc1f8e38c972c47af49f",
-                "sha256:96f0c79a70642dfdf7e6a018ebcbea7ea5205e27d8e019cad442d2acfc9af267",
-                "sha256:9966337353e436e6ba652814b0a957a517feb492a98b8f9d3b6ba76d22301dcc",
-                "sha256:a34ba9e39f8269fd66ab4f7a802794ffea6d6ac500568ec05b327a862c21ce23",
-                "sha256:a49f85f0a099a5755d0a2cc6fc337e3cb945ad6390ec892332c691ab0a045882",
-                "sha256:a795829dc522227265d72b25d6ee6f6d41eb2105c15912c230097c8f5bfdbcdc",
-                "sha256:a89ca4105f8099de349d139d1090bad387fe2b208b717b288699ca26f179acbe",
-                "sha256:ac95101736239260189f426b1e361dc1b704513963357dc474beb0f39f5b7759",
-                "sha256:ae87ab669431f611c56e581679db33b9a467f87d7bf197ac384e71e4956b4456",
-                "sha256:b091dcfee169ad8de21b61eb2c3a75f9f0f859f851f64fdaf9320759a3244239",
-                "sha256:b511c6009d50d5c0dd0bab85ed25bc8ad6b6f5611de3a63a59786207e82824bb",
-                "sha256:b79dc2b2e313565416c1e62807c7c25c67a6ff0a0f8d83a318df464555b65948",
-                "sha256:bca14dfcfd9aae06d7d8d7e105539bd77d39d06caaae57a1ce945670bae744e0",
-                "sha256:c835c30f3af5c63a80917b72115e1defb83de99c73bc727bddd979a3b449e183",
-                "sha256:ccd721f1d4fc42b541b633d6e339018a08dd0290dc67269df79552843a06ca92",
-                "sha256:d6c2b1d78ceceb6741d703508cd0e9197b34f6bf6864dab30f940f8886e04ade",
-                "sha256:d6ec4ae13760ceda023b2e5ef1f9bc0b21e4b0830458db143794a117fdbdc044",
-                "sha256:d8b623fc429a38a881ab2d9a56ef30e8ea20c72a891c193f5ebbddc016e083ee",
-                "sha256:ea9753d64cba6f226947c318a923dadaf1e21cd8db02f71652405263daa1f033",
-                "sha256:ebbceefbffae118ab954d3cd6bf718f5790db66152f95202ebc231d58ad4e2c2",
-                "sha256:ecb6e7c45f9cd199c10ec35262b53b2247fb9a408803ed00ee5bb2b54aa626f5",
-                "sha256:ef9326c64349e2d718373415814e754183057ebc092261387a2c2f732d9172b2",
-                "sha256:f93a9d8804f4cec9da6c26c8cfae2c777028b4fdd9f49de0302e26e00bb86504",
-                "sha256:faf08b0341828f6a29b8f7dd94d5cf8cc7c39bfc3e67b78514c54b494b66915a"
+                "sha256:05b7d6d7e64efe309972adab77fc2af8907bb93217ec60aa9fe12a0dad35874f",
+                "sha256:0617383e2fe465732af4509e61648b77cbe3aee68b6ac8c0b6fe934db90be5cc",
+                "sha256:07856afef5ffcc052e7eccf3213317fbb94e4a5cd8177a2caa69c980657b3cb4",
+                "sha256:162abfd74e88001d20cb73ceaffbfe601469923e875caf9118333b1a4aaafdc4",
+                "sha256:2207ae4f64ad3af399e2d30dde66f0b36ae5c3129b52885f1bffc2f05ec505c8",
+                "sha256:30ab804ea73972049b7a2a5c62d97687d69b5a60a67adca07eb73a0ddbc9e29f",
+                "sha256:3b5df18db1fccd66de15aa59c41e4f853b5df7550723d26aa6cb7f40e5d9da5a",
+                "sha256:3c5fb32cc6077abad3bbf0323067636d93307c9fa93e072771cf9a64d1c0f3ef",
+                "sha256:416c5f1a188c91e3eb41e9c8787288e707f7d2ebe66e0a6563af280d9b68478f",
+                "sha256:432bd15d40ed835a51617521d60d0125867f7b88acf653e4ed994a1f8e4995dc",
+                "sha256:4aaa4e0705ef2b73dd8e36eeb4c868f80f8393f5f4d855e94025ce7ad8525f50",
+                "sha256:537ca6a3586931b16a85ac38c08cc48f10fc870a5b25e51794c74df843e9966d",
+                "sha256:53db2c6be8a2710b359bfd3d3aa17ba38f8aa72a82309a12ae99d3c0c3dcd74d",
+                "sha256:5537f71b6d646f7f5f340562ec4c77b6e1c915f8baae822ea0b7e46c1f09b733",
+                "sha256:6650f16365f1924d6014d2ea770bde8555b4a39dc9576abb95e3cd1ff0263b36",
+                "sha256:666abff54e474d28ff42756d94544cdfd42e2ee97065857413b72e8a2d6a6345",
+                "sha256:68a067c11463de2a37157930d8b153005085e42bcb7ad9ca562d77ba7d1404e0",
+                "sha256:780b48456a0f0ba4d390e8b5f7c661fdd218934388cde1a974010a965e200e12",
+                "sha256:788aef3549f1924d5c38263104dae7395bf020a42776d5ec5ea2b0d3d85d6646",
+                "sha256:7ee1227cf08b6716c85504aebc49ac827eb88fcc6e51564f010f11a406c0a667",
+                "sha256:7f301b11b9d214f83ddaf689181051e7f48905568b0c7017c04c06dfd065e244",
+                "sha256:83ee89483672b11f8952b158640d0c0ff02dc43d9cb1b70c1564b49abe92ce29",
+                "sha256:85bfa6a5413be0ee6c5c4a663668a2cad2cbecdee367630d097d7823041bdeec",
+                "sha256:9345b6f7ee578bad8e475129ed40123d265464c4cfead6c261fd60fc9de00bcf",
+                "sha256:93a5051fcf5fad72de73b96f07d30bc29665697fb8ecdfbc474f3452c78adcf4",
+                "sha256:962b9a917dd7ceacbe5cd424556914cb0d636001e393b43dc886ba31d2a1e449",
+                "sha256:98ba568e8ae26beb726aeea2273053c717641933836568c2a0278a84987b2a1a",
+                "sha256:a3feefd5e95871872673b08636f96b61ebef62971eab044f5124fb4dea39919d",
+                "sha256:b43c2b8a330a490daaef5a47ab114935002b13b3f9dc5da56d5322ff218eeadb",
+                "sha256:b483c9d00a565633c87abd0aaf27eb5016de23fed952e054ecc19ce32f6a9e7e",
+                "sha256:ba05430e819e58544e840a68b03b28b6d328aff2e41579037e8bab7653b37d83",
+                "sha256:ca5f18a75e1256ce07494e245cdb146f5a9267d3c702ebf9b65c7f8bd843431e",
+                "sha256:d5ca078bb666c4a9d1287a379fe617a6dccd18c3e8a7e6c7e1eb8974330c626a",
+                "sha256:da1a90c1ddb7531b1d5ff1e171b4ee61f6345119be7351104b67ff413843fe94",
+                "sha256:dba70f30fd81f8ce6d32ddeef37d91c8948e5d5a4c63242d16a2b2df8143aafc",
+                "sha256:dd33eb9bdcfbabab3459c9ee651d94c842bc8a05fabc95edf4ee0c15a072495e",
+                "sha256:e0538c43565ee6e703d3a7c3bdfe4037a5209250e8502c98f20fea6f5fdf2965",
+                "sha256:e1f54b9b4b6c53369f40028d2dd07a8c374583417ee6ec0ea304e710a20f80a0",
+                "sha256:e32d2a2b02ccbef10145df9135751abea1f9f076e67a4e261b05f24b94219e36",
+                "sha256:e71255ba42567d34a13c03968736c5d39bb4a97ce98188fafb27ce981115beec",
+                "sha256:ed2e07c6a26ed4bea91b897ee2b0835c21716d9a469a96c3e878dc5f8c55bb23",
+                "sha256:eef2afb0fd1747f33f1ee3e209bce1ed582d1896b240ccc5e2697e3275f037c7",
+                "sha256:f23222527b307970e383433daec128d769ff778d9b29343fb3496472dc20dabe",
+                "sha256:f341ee2df0999bfdf7a95e448075effe0db212a59387de1a70690e4acb03d4c6",
+                "sha256:f7f325be2804246a75a4f45c72d4ce80d2443ab815063cdf70ee8fb2ca59ee1b",
+                "sha256:f8af619e3be812a2059b212064ea7a640aff0568d972cd1b9e920837469eb3cb",
+                "sha256:fa8c626d6441e2d04b6ee703ef2d1e17608ad44c7cb75258c09dd42bacdfc64b",
+                "sha256:fbb9dc00e39f3e6c0ef48edee202f9520dafb233e8b51b06b8428cfcb92abd30",
+                "sha256:fff55f3ce50a3ff63ec8e2a8d3dd924f1941b250b0aac3d3d42b687eeff07a8e"
             ],
             "index": "pypi",
-            "version": "==2021.8.21"
+            "version": "==2021.11.10"
+        },
+        "setuptools": {
+            "hashes": [
+                "sha256:a481fbc56b33f5d8f6b33dce41482e64c68b668be44ff42922903b03872590bf",
+                "sha256:dae6b934a965c8a59d6d230d3867ec408bb95e73bd538ff77e71fedf1eaca729"
+            ],
+            "markers": "python_version >= '3.6'",
+            "version": "==58.5.3"
         },
         "setuptools-scm": {
             "extras": [
                 "toml"
             ],
             "hashes": [
-                "sha256:c3bd5f701c8def44a5c0bfe8d407bef3f80342217ef3492b951f3777bd2d915c",
-                "sha256:d1925a69cb07e9b29416a275b9fadb009a23c148ace905b2fb220649a6c18e92"
+                "sha256:4c64444b1d49c4063ae60bfe1680f611c8b13833d556fd1d6050c0023162a119",
+                "sha256:a49aa8081eeb3514eb9728fa5040f2eaa962d6c6f4ec9c32f6c1fba88f88a0f2"
             ],
             "markers": "python_version >= '3.6'",
-            "version": "==6.0.1"
+            "version": "==6.3.2"
         },
         "tomli": {
             "hashes": [
-                "sha256:8dd0e9524d6f386271a36b41dbf6c57d8e32fd96fd22b6584679dc569d20899f",
-                "sha256:a5b75cb6f3968abb47af1b40c1819dc519ea82bcc065776a866e8d74c5ca9442"
+                "sha256:c6ce0015eb38820eaf32b5db832dbc26deb3dd427bd5f6556cf0acac2c214fee",
+                "sha256:f04066f68f5554911363063a30b108d2b5a5b1a010aa8b6132af78489fe3aade"
             ],
             "index": "pypi",
-            "version": "==1.2.1"
+            "version": "==1.2.2"
         },
         "typed-ast": {
             "hashes": [
-                "sha256:07d49388d5bf7e863f7fa2f124b1b1d89d8aa0e2f7812faff0a5658c01c59aa1",
-                "sha256:14bf1522cdee369e8f5581238edac09150c765ec1cb33615855889cf33dcb92d",
-                "sha256:240296b27397e4e37874abb1df2a608a92df85cf3e2a04d0d4d61055c8305ba6",
-                "sha256:36d829b31ab67d6fcb30e185ec996e1f72b892255a745d3a82138c97d21ed1cd",
-                "sha256:37f48d46d733d57cc70fd5f30572d11ab8ed92da6e6b28e024e4a3edfb456e37",
-                "sha256:4c790331247081ea7c632a76d5b2a265e6d325ecd3179d06e9cf8d46d90dd151",
-                "sha256:5dcfc2e264bd8a1db8b11a892bd1647154ce03eeba94b461effe68790d8b8e07",
-                "sha256:7147e2a76c75f0f64c4319886e7639e490fee87c9d25cb1d4faef1d8cf83a440",
-                "sha256:7703620125e4fb79b64aa52427ec192822e9f45d37d4b6625ab37ef403e1df70",
-                "sha256:8368f83e93c7156ccd40e49a783a6a6850ca25b556c0fa0240ed0f659d2fe496",
-                "sha256:84aa6223d71012c68d577c83f4e7db50d11d6b1399a9c779046d75e24bed74ea",
-                "sha256:85f95aa97a35bdb2f2f7d10ec5bbdac0aeb9dafdaf88e17492da0504de2e6400",
-                "sha256:8db0e856712f79c45956da0c9a40ca4246abc3485ae0d7ecc86a20f5e4c09abc",
-                "sha256:9044ef2df88d7f33692ae3f18d3be63dec69c4fb1b5a4a9ac950f9b4ba571606",
-                "sha256:963c80b583b0661918718b095e02303d8078950b26cc00b5e5ea9ababe0de1fc",
-                "sha256:987f15737aba2ab5f3928c617ccf1ce412e2e321c77ab16ca5a293e7bbffd581",
-                "sha256:9ec45db0c766f196ae629e509f059ff05fc3148f9ffd28f3cfe75d4afb485412",
-                "sha256:9fc0b3cb5d1720e7141d103cf4819aea239f7d136acf9ee4a69b047b7986175a",
-                "sha256:a2c927c49f2029291fbabd673d51a2180038f8cd5a5b2f290f78c4516be48be2",
-                "sha256:a38878a223bdd37c9709d07cd357bb79f4c760b29210e14ad0fb395294583787",
-                "sha256:b4fcdcfa302538f70929eb7b392f536a237cbe2ed9cba88e3bf5027b39f5f77f",
-                "sha256:c0c74e5579af4b977c8b932f40a5464764b2f86681327410aa028a22d2f54937",
-                "sha256:c1c876fd795b36126f773db9cbb393f19808edd2637e00fd6caba0e25f2c7b64",
-                "sha256:c9aadc4924d4b5799112837b226160428524a9a45f830e0d0f184b19e4090487",
-                "sha256:cc7b98bf58167b7f2db91a4327da24fb93368838eb84a44c472283778fc2446b",
-                "sha256:cf54cfa843f297991b7388c281cb3855d911137223c6b6d2dd82a47ae5125a41",
-                "sha256:d003156bb6a59cda9050e983441b7fa2487f7800d76bdc065566b7d728b4581a",
-                "sha256:d175297e9533d8d37437abc14e8a83cbc68af93cc9c1c59c2c292ec59a0697a3",
-                "sha256:d746a437cdbca200622385305aedd9aef68e8a645e385cc483bdc5e488f07166",
-                "sha256:e683e409e5c45d5c9082dc1daf13f6374300806240719f95dc783d1fc942af10"
+                "sha256:01ae5f73431d21eead5015997ab41afa53aa1fbe252f9da060be5dad2c730ace",
+                "sha256:067a74454df670dcaa4e59349a2e5c81e567d8d65458d480a5b3dfecec08c5ff",
+                "sha256:0fb71b8c643187d7492c1f8352f2c15b4c4af3f6338f21681d3681b3dc31a266",
+                "sha256:1b3ead4a96c9101bef08f9f7d1217c096f31667617b58de957f690c92378b528",
+                "sha256:2068531575a125b87a41802130fa7e29f26c09a2833fea68d9a40cf33902eba6",
+                "sha256:209596a4ec71d990d71d5e0d312ac935d86930e6eecff6ccc7007fe54d703808",
+                "sha256:2c726c276d09fc5c414693a2de063f521052d9ea7c240ce553316f70656c84d4",
+                "sha256:398e44cd480f4d2b7ee8d98385ca104e35c81525dd98c519acff1b79bdaac363",
+                "sha256:52b1eb8c83f178ab787f3a4283f68258525f8d70f778a2f6dd54d3b5e5fb4341",
+                "sha256:5feca99c17af94057417d744607b82dd0a664fd5e4ca98061480fd8b14b18d04",
+                "sha256:7538e495704e2ccda9b234b82423a4038f324f3a10c43bc088a1636180f11a41",
+                "sha256:760ad187b1041a154f0e4d0f6aae3e40fdb51d6de16e5c99aedadd9246450e9e",
+                "sha256:777a26c84bea6cd934422ac2e3b78863a37017618b6e5c08f92ef69853e765d3",
+                "sha256:95431a26309a21874005845c21118c83991c63ea800dd44843e42a916aec5899",
+                "sha256:9ad2c92ec681e02baf81fdfa056fe0d818645efa9af1f1cd5fd6f1bd2bdfd805",
+                "sha256:9c6d1a54552b5330bc657b7ef0eae25d00ba7ffe85d9ea8ae6540d2197a3788c",
+                "sha256:aee0c1256be6c07bd3e1263ff920c325b59849dc95392a05f258bb9b259cf39c",
+                "sha256:af3d4a73793725138d6b334d9d247ce7e5f084d96284ed23f22ee626a7b88e39",
+                "sha256:b36b4f3920103a25e1d5d024d155c504080959582b928e91cb608a65c3a49e1a",
+                "sha256:b9574c6f03f685070d859e75c7f9eeca02d6933273b5e69572e5ff9d5e3931c3",
+                "sha256:bff6ad71c81b3bba8fa35f0f1921fb24ff4476235a6e94a26ada2e54370e6da7",
+                "sha256:c190f0899e9f9f8b6b7863debfb739abcb21a5c054f911ca3596d12b8a4c4c7f",
+                "sha256:c907f561b1e83e93fad565bac5ba9c22d96a54e7ea0267c708bffe863cbe4075",
+                "sha256:cae53c389825d3b46fb37538441f75d6aecc4174f615d048321b716df2757fb0",
+                "sha256:dd4a21253f42b8d2b48410cb31fe501d32f8b9fbeb1f55063ad102fe9c425e40",
+                "sha256:dde816ca9dac1d9c01dd504ea5967821606f02e510438120091b84e852367428",
+                "sha256:f2362f3cb0f3172c42938946dbc5b7843c2a28aec307c49100c8b38764eb6927",
+                "sha256:f328adcfebed9f11301eaedfa48e15bdece9b519fb27e6a8c01aa52a17ec31b3",
+                "sha256:f8afcf15cc511ada719a88e013cec87c11aff7b91f019295eb4530f96fe5ef2f",
+                "sha256:fb1bbeac803adea29cedd70781399c99138358c26d05fcbd23c13016b7f5ec65"
             ],
             "index": "pypi",
             "version": "==1.4.3"
         },
         "typing-extensions": {
             "hashes": [
-                "sha256:0ac0f89795dd19de6b97debb0c6af1c70987fd80a2d62d1958f7e56fcc31b497",
-                "sha256:50b6f157849174217d0656f99dc82fe932884fb250826c18350e159ec6cdf342",
-                "sha256:779383f6086d90c99ae41cf0ff39aac8a7937a9283ce0a414e5dd782f4c94a84"
+                "sha256:49f75d16ff11f1cd258e1b988ccff82a3ca5570217d7ad8c5f48205dd99a677e",
+                "sha256:d8226d10bc02a29bcc81df19a26e56a9647f8b0a6d4a83924139f4a8b01f17b7",
+                "sha256:f1d25edafde516b146ecd0613dabcc61409817af4766fbbcfb8d1ad4ec441a34"
             ],
             "index": "pypi",
             "markers": "python_version < '3.10'",
-            "version": "==3.10.0.0"
+            "version": "==3.10.0.2"
         },
         "yarl": {
             "hashes": [
-                "sha256:00d7ad91b6583602eb9c1d085a2cf281ada267e9a197e8b7cae487dadbfa293e",
-                "sha256:0355a701b3998dcd832d0dc47cc5dedf3874f966ac7f870e0f3a6788d802d434",
-                "sha256:15263c3b0b47968c1d90daa89f21fcc889bb4b1aac5555580d74565de6836366",
-                "sha256:2ce4c621d21326a4a5500c25031e102af589edb50c09b321049e388b3934eec3",
-                "sha256:31ede6e8c4329fb81c86706ba8f6bf661a924b53ba191b27aa5fcee5714d18ec",
-                "sha256:324ba3d3c6fee56e2e0b0d09bf5c73824b9f08234339d2b788af65e60040c959",
-                "sha256:329412812ecfc94a57cd37c9d547579510a9e83c516bc069470db5f75684629e",
-                "sha256:4736eaee5626db8d9cda9eb5282028cc834e2aeb194e0d8b50217d707e98bb5c",
-                "sha256:4953fb0b4fdb7e08b2f3b3be80a00d28c5c8a2056bb066169de00e6501b986b6",
-                "sha256:4c5bcfc3ed226bf6419f7a33982fb4b8ec2e45785a0561eb99274ebbf09fdd6a",
-                "sha256:547f7665ad50fa8563150ed079f8e805e63dd85def6674c97efd78eed6c224a6",
-                "sha256:5b883e458058f8d6099e4420f0cc2567989032b5f34b271c0827de9f1079a424",
-                "sha256:63f90b20ca654b3ecc7a8d62c03ffa46999595f0167d6450fa8383bab252987e",
-                "sha256:68dc568889b1c13f1e4745c96b931cc94fdd0defe92a72c2b8ce01091b22e35f",
-                "sha256:69ee97c71fee1f63d04c945f56d5d726483c4762845400a6795a3b75d56b6c50",
-                "sha256:6d6283d8e0631b617edf0fd726353cb76630b83a089a40933043894e7f6721e2",
-                "sha256:72a660bdd24497e3e84f5519e57a9ee9220b6f3ac4d45056961bf22838ce20cc",
-                "sha256:73494d5b71099ae8cb8754f1df131c11d433b387efab7b51849e7e1e851f07a4",
-                "sha256:7356644cbed76119d0b6bd32ffba704d30d747e0c217109d7979a7bc36c4d970",
-                "sha256:8a9066529240171b68893d60dca86a763eae2139dd42f42106b03cf4b426bf10",
-                "sha256:8aa3decd5e0e852dc68335abf5478a518b41bf2ab2f330fe44916399efedfae0",
-                "sha256:97b5bdc450d63c3ba30a127d018b866ea94e65655efaf889ebeabc20f7d12406",
-                "sha256:9ede61b0854e267fd565e7527e2f2eb3ef8858b301319be0604177690e1a3896",
-                "sha256:b2e9a456c121e26d13c29251f8267541bd75e6a1ccf9e859179701c36a078643",
-                "sha256:b5dfc9a40c198334f4f3f55880ecf910adebdcb2a0b9a9c23c9345faa9185721",
-                "sha256:bafb450deef6861815ed579c7a6113a879a6ef58aed4c3a4be54400ae8871478",
-                "sha256:c49ff66d479d38ab863c50f7bb27dee97c6627c5fe60697de15529da9c3de724",
-                "sha256:ce3beb46a72d9f2190f9e1027886bfc513702d748047b548b05dab7dfb584d2e",
-                "sha256:d26608cf178efb8faa5ff0f2d2e77c208f471c5a3709e577a7b3fd0445703ac8",
-                "sha256:d597767fcd2c3dc49d6eea360c458b65643d1e4dbed91361cf5e36e53c1f8c96",
-                "sha256:d5c32c82990e4ac4d8150fd7652b972216b204de4e83a122546dce571c1bdf25",
-                "sha256:d8d07d102f17b68966e2de0e07bfd6e139c7c02ef06d3a0f8d2f0f055e13bb76",
-                "sha256:e46fba844f4895b36f4c398c5af062a9808d1f26b2999c58909517384d5deda2",
-                "sha256:e6b5460dc5ad42ad2b36cca524491dfcaffbfd9c8df50508bddc354e787b8dc2",
-                "sha256:f040bcc6725c821a4c0665f3aa96a4d0805a7aaf2caf266d256b8ed71b9f041c",
-                "sha256:f0b059678fd549c66b89bed03efcabb009075bd131c248ecdf087bdb6faba24a",
-                "sha256:fcbb48a93e8699eae920f8d92f7160c03567b421bc17362a9ffbbd706a816f71"
+                "sha256:044daf3012e43d4b3538562da94a88fb12a6490652dbc29fb19adfa02cf72eac",
+                "sha256:0cba38120db72123db7c58322fa69e3c0efa933040ffb586c3a87c063ec7cae8",
+                "sha256:167ab7f64e409e9bdd99333fe8c67b5574a1f0495dcfd905bc7454e766729b9e",
+                "sha256:1be4bbb3d27a4e9aa5f3df2ab61e3701ce8fcbd3e9846dbce7c033a7e8136746",
+                "sha256:1ca56f002eaf7998b5fcf73b2421790da9d2586331805f38acd9997743114e98",
+                "sha256:1d3d5ad8ea96bd6d643d80c7b8d5977b4e2fb1bab6c9da7322616fd26203d125",
+                "sha256:1eb6480ef366d75b54c68164094a6a560c247370a68c02dddb11f20c4c6d3c9d",
+                "sha256:1edc172dcca3f11b38a9d5c7505c83c1913c0addc99cd28e993efeaafdfaa18d",
+                "sha256:211fcd65c58bf250fb994b53bc45a442ddc9f441f6fec53e65de8cba48ded986",
+                "sha256:29e0656d5497733dcddc21797da5a2ab990c0cb9719f1f969e58a4abac66234d",
+                "sha256:368bcf400247318382cc150aaa632582d0780b28ee6053cd80268c7e72796dec",
+                "sha256:39d5493c5ecd75c8093fa7700a2fb5c94fe28c839c8e40144b7ab7ccba6938c8",
+                "sha256:3abddf0b8e41445426d29f955b24aeecc83fa1072be1be4e0d194134a7d9baee",
+                "sha256:3bf8cfe8856708ede6a73907bf0501f2dc4e104085e070a41f5d88e7faf237f3",
+                "sha256:3ec1d9a0d7780416e657f1e405ba35ec1ba453a4f1511eb8b9fbab81cb8b3ce1",
+                "sha256:45399b46d60c253327a460e99856752009fcee5f5d3c80b2f7c0cae1c38d56dd",
+                "sha256:52690eb521d690ab041c3919666bea13ab9fbff80d615ec16fa81a297131276b",
+                "sha256:534b047277a9a19d858cde163aba93f3e1677d5acd92f7d10ace419d478540de",
+                "sha256:580c1f15500e137a8c37053e4cbf6058944d4c114701fa59944607505c2fe3a0",
+                "sha256:59218fef177296451b23214c91ea3aba7858b4ae3306dde120224cfe0f7a6ee8",
+                "sha256:5ba63585a89c9885f18331a55d25fe81dc2d82b71311ff8bd378fc8004202ff6",
+                "sha256:5bb7d54b8f61ba6eee541fba4b83d22b8a046b4ef4d8eb7f15a7e35db2e1e245",
+                "sha256:6152224d0a1eb254f97df3997d79dadd8bb2c1a02ef283dbb34b97d4f8492d23",
+                "sha256:67e94028817defe5e705079b10a8438b8cb56e7115fa01640e9c0bb3edf67332",
+                "sha256:695ba021a9e04418507fa930d5f0704edbce47076bdcfeeaba1c83683e5649d1",
+                "sha256:6a1a9fe17621af43e9b9fcea8bd088ba682c8192d744b386ee3c47b56eaabb2c",
+                "sha256:6ab0c3274d0a846840bf6c27d2c60ba771a12e4d7586bf550eefc2df0b56b3b4",
+                "sha256:6feca8b6bfb9eef6ee057628e71e1734caf520a907b6ec0d62839e8293e945c0",
+                "sha256:737e401cd0c493f7e3dd4db72aca11cfe069531c9761b8ea474926936b3c57c8",
+                "sha256:788713c2896f426a4e166b11f4ec538b5736294ebf7d5f654ae445fd44270832",
+                "sha256:797c2c412b04403d2da075fb93c123df35239cd7b4cc4e0cd9e5839b73f52c58",
+                "sha256:8300401dc88cad23f5b4e4c1226f44a5aa696436a4026e456fe0e5d2f7f486e6",
+                "sha256:87f6e082bce21464857ba58b569370e7b547d239ca22248be68ea5d6b51464a1",
+                "sha256:89ccbf58e6a0ab89d487c92a490cb5660d06c3a47ca08872859672f9c511fc52",
+                "sha256:8b0915ee85150963a9504c10de4e4729ae700af11df0dc5550e6587ed7891e92",
+                "sha256:8cce6f9fa3df25f55521fbb5c7e4a736683148bcc0c75b21863789e5185f9185",
+                "sha256:95a1873b6c0dd1c437fb3bb4a4aaa699a48c218ac7ca1e74b0bee0ab16c7d60d",
+                "sha256:9b4c77d92d56a4c5027572752aa35082e40c561eec776048330d2907aead891d",
+                "sha256:9bfcd43c65fbb339dc7086b5315750efa42a34eefad0256ba114cd8ad3896f4b",
+                "sha256:9c1f083e7e71b2dd01f7cd7434a5f88c15213194df38bc29b388ccdf1492b739",
+                "sha256:a1d0894f238763717bdcfea74558c94e3bc34aeacd3351d769460c1a586a8b05",
+                "sha256:a467a431a0817a292121c13cbe637348b546e6ef47ca14a790aa2fa8cc93df63",
+                "sha256:aa32aaa97d8b2ed4e54dc65d241a0da1c627454950f7d7b1f95b13985afd6c5d",
+                "sha256:ac10bbac36cd89eac19f4e51c032ba6b412b3892b685076f4acd2de18ca990aa",
+                "sha256:ac35ccde589ab6a1870a484ed136d49a26bcd06b6a1c6397b1967ca13ceb3913",
+                "sha256:bab827163113177aee910adb1f48ff7af31ee0289f434f7e22d10baf624a6dfe",
+                "sha256:baf81561f2972fb895e7844882898bda1eef4b07b5b385bcd308d2098f1a767b",
+                "sha256:bf19725fec28452474d9887a128e98dd67eee7b7d52e932e6949c532d820dc3b",
+                "sha256:c01a89a44bb672c38f42b49cdb0ad667b116d731b3f4c896f72302ff77d71656",
+                "sha256:c0910c6b6c31359d2f6184828888c983d54d09d581a4a23547a35f1d0b9484b1",
+                "sha256:c10ea1e80a697cf7d80d1ed414b5cb8f1eec07d618f54637067ae3c0334133c4",
+                "sha256:c1164a2eac148d85bbdd23e07dfcc930f2e633220f3eb3c3e2a25f6148c2819e",
+                "sha256:c145ab54702334c42237a6c6c4cc08703b6aa9b94e2f227ceb3d477d20c36c63",
+                "sha256:c17965ff3706beedafd458c452bf15bac693ecd146a60a06a214614dc097a271",
+                "sha256:c19324a1c5399b602f3b6e7db9478e5b1adf5cf58901996fc973fe4fccd73eed",
+                "sha256:c2a1ac41a6aa980db03d098a5531f13985edcb451bcd9d00670b03129922cd0d",
+                "sha256:c6ddcd80d79c96eb19c354d9dca95291589c5954099836b7c8d29278a7ec0bda",
+                "sha256:c9c6d927e098c2d360695f2e9d38870b2e92e0919be07dbe339aefa32a090265",
+                "sha256:cc8b7a7254c0fc3187d43d6cb54b5032d2365efd1df0cd1749c0c4df5f0ad45f",
+                "sha256:cff3ba513db55cc6a35076f32c4cdc27032bd075c9faef31fec749e64b45d26c",
+                "sha256:d260d4dc495c05d6600264a197d9d6f7fc9347f21d2594926202fd08cf89a8ba",
+                "sha256:d6f3d62e16c10e88d2168ba2d065aa374e3c538998ed04996cd373ff2036d64c",
+                "sha256:da6df107b9ccfe52d3a48165e48d72db0eca3e3029b5b8cb4fe6ee3cb870ba8b",
+                "sha256:dfe4b95b7e00c6635a72e2d00b478e8a28bfb122dc76349a06e20792eb53a523",
+                "sha256:e39378894ee6ae9f555ae2de332d513a5763276a9265f8e7cbaeb1b1ee74623a",
+                "sha256:ede3b46cdb719c794427dcce9d8beb4abe8b9aa1e97526cc20de9bd6583ad1ef",
+                "sha256:f2a8508f7350512434e41065684076f640ecce176d262a7d54f0da41d99c5a95",
+                "sha256:f44477ae29025d8ea87ec308539f95963ffdc31a82f42ca9deecf2d505242e72",
+                "sha256:f64394bd7ceef1237cc604b5a89bf748c95982a84bcd3c4bbeb40f685c810794",
+                "sha256:fc4dd8b01a8112809e6b636b00f487846956402834a7fd59d46d4f4267181c41",
+                "sha256:fce78593346c014d0d986b7ebc80d782b7f5e19843ca798ed62f8e3ba8728576",
+                "sha256:fd547ec596d90c8676e369dd8a581a21227fe9b4ad37d0dc7feb4ccf544c2d59"
             ],
             "markers": "python_version >= '3.6'",
-            "version": "==1.6.3"
+            "version": "==1.7.2"
         },
         "zipp": {
             "hashes": [
-                "sha256:957cfda87797e389580cb8b9e3870841ca991e2125350677b2ca83a0e99390a3",
-                "sha256:f5812b1e007e48cff63449a5e9f4e7ebea716b4111f9c4f9a645f91d579bf0c4"
+                "sha256:71c644c5369f4a6e07636f0aa966270449561fcea2e3d6747b8d23efaa9d7832",
+                "sha256:9fe5ea21568a0a70e50f273397638d39b03353731e6cbbb3fd8502a33fec40bc"
             ],
             "markers": "python_version >= '3.6'",
-            "version": "==3.5.0"
+            "version": "==3.6.0"
         }
     },
     "develop": {
         "aiohttp": {
             "hashes": [
-                "sha256:02f46fc0e3c5ac58b80d4d56eb0a7c7d97fcef69ace9326289fb9f1955e65cfe",
-                "sha256:0563c1b3826945eecd62186f3f5c7d31abb7391fedc893b7e2b26303b5a9f3fe",
-                "sha256:114b281e4d68302a324dd33abb04778e8557d88947875cbf4e842c2c01a030c5",
-                "sha256:14762875b22d0055f05d12abc7f7d61d5fd4fe4642ce1a249abdf8c700bf1fd8",
-                "sha256:15492a6368d985b76a2a5fdd2166cddfea5d24e69eefed4630cbaae5c81d89bd",
-                "sha256:17c073de315745a1510393a96e680d20af8e67e324f70b42accbd4cb3315c9fb",
-                "sha256:209b4a8ee987eccc91e2bd3ac36adee0e53a5970b8ac52c273f7f8fd4872c94c",
-                "sha256:230a8f7e24298dea47659251abc0fd8b3c4e38a664c59d4b89cca7f6c09c9e87",
-                "sha256:2e19413bf84934d651344783c9f5e22dee452e251cfd220ebadbed2d9931dbf0",
-                "sha256:393f389841e8f2dfc86f774ad22f00923fdee66d238af89b70ea314c4aefd290",
-                "sha256:3cf75f7cdc2397ed4442594b935a11ed5569961333d49b7539ea741be2cc79d5",
-                "sha256:3d78619672183be860b96ed96f533046ec97ca067fd46ac1f6a09cd9b7484287",
-                "sha256:40eced07f07a9e60e825554a31f923e8d3997cfc7fb31dbc1328c70826e04cde",
-                "sha256:493d3299ebe5f5a7c66b9819eacdcfbbaaf1a8e84911ddffcdc48888497afecf",
-                "sha256:4b302b45040890cea949ad092479e01ba25911a15e648429c7c5aae9650c67a8",
-                "sha256:515dfef7f869a0feb2afee66b957cc7bbe9ad0cdee45aec7fdc623f4ecd4fb16",
-                "sha256:547da6cacac20666422d4882cfcd51298d45f7ccb60a04ec27424d2f36ba3eaf",
-                "sha256:5df68496d19f849921f05f14f31bd6ef53ad4b00245da3195048c69934521809",
-                "sha256:64322071e046020e8797117b3658b9c2f80e3267daec409b350b6a7a05041213",
-                "sha256:7615dab56bb07bff74bc865307aeb89a8bfd9941d2ef9d817b9436da3a0ea54f",
-                "sha256:79ebfc238612123a713a457d92afb4096e2148be17df6c50fb9bf7a81c2f8013",
-                "sha256:7b18b97cf8ee5452fa5f4e3af95d01d84d86d32c5e2bfa260cf041749d66360b",
-                "sha256:932bb1ea39a54e9ea27fc9232163059a0b8855256f4052e776357ad9add6f1c9",
-                "sha256:a00bb73540af068ca7390e636c01cbc4f644961896fa9363154ff43fd37af2f5",
-                "sha256:a5ca29ee66f8343ed336816c553e82d6cade48a3ad702b9ffa6125d187e2dedb",
-                "sha256:af9aa9ef5ba1fd5b8c948bb11f44891968ab30356d65fd0cc6707d989cd521df",
-                "sha256:bb437315738aa441251214dad17428cafda9cdc9729499f1d6001748e1d432f4",
-                "sha256:bdb230b4943891321e06fc7def63c7aace16095be7d9cf3b1e01be2f10fba439",
-                "sha256:c6e9dcb4cb338d91a73f178d866d051efe7c62a7166653a91e7d9fb18274058f",
-                "sha256:cffe3ab27871bc3ea47df5d8f7013945712c46a3cc5a95b6bee15887f1675c22",
-                "sha256:d012ad7911653a906425d8473a1465caa9f8dea7fcf07b6d870397b774ea7c0f",
-                "sha256:d9e13b33afd39ddeb377eff2c1c4f00544e191e1d1dee5b6c51ddee8ea6f0cf5",
-                "sha256:e4b2b334e68b18ac9817d828ba44d8fcb391f6acb398bcc5062b14b2cbeac970",
-                "sha256:e54962802d4b8b18b6207d4a927032826af39395a3bd9196a5af43fc4e60b009",
-                "sha256:f705e12750171c0ab4ef2a3c76b9a4024a62c4103e3a55dd6f99265b9bc6fcfc",
-                "sha256:f881853d2643a29e643609da57b96d5f9c9b93f62429dcc1cbb413c7d07f0e1a",
-                "sha256:fe60131d21b31fd1a14bd43e6bb88256f69dfc3188b3a89d736d6c71ed43ec95"
+                "sha256:09754a0d5eaab66c37591f2f8fac8f9781a5f61d51aa852a3261c4805ca6b984",
+                "sha256:097ecf52f6b9859b025c1e36401f8aa4573552e887d1b91b4b999d68d0b5a3b3",
+                "sha256:0a96473a1f61d7920a9099bc8e729dc8282539d25f79c12573ee0fdb9c8b66a8",
+                "sha256:0af379221975054162959e00daf21159ff69a712fc42ed0052caddbd70d52ff4",
+                "sha256:0d7b056fd3972d353cb4bc305c03f9381583766b7f8c7f1c44478dba69099e33",
+                "sha256:14a6f026eca80dfa3d52e86be89feb5cd878f6f4a6adb34457e2c689fd85229b",
+                "sha256:15a660d06092b7c92ed17c1dbe6c1eab0a02963992d60e3e8b9d5fa7fa81f01e",
+                "sha256:1fa9f50aa1f114249b7963c98e20dc35c51be64096a85bc92433185f331de9cc",
+                "sha256:257f4fad1714d26d562572095c8c5cd271d5a333252795cb7a002dca41fdbad7",
+                "sha256:28369fe331a59d80393ec82df3d43307c7461bfaf9217999e33e2acc7984ff7c",
+                "sha256:2bdd655732e38b40f8a8344d330cfae3c727fb257585df923316aabbd489ccb8",
+                "sha256:2f44d1b1c740a9e2275160d77c73a11f61e8a916191c572876baa7b282bcc934",
+                "sha256:3ba08a71caa42eef64357257878fb17f3fba3fba6e81a51d170e32321569e079",
+                "sha256:3c5e9981e449d54308c6824f172ec8ab63eb9c5f922920970249efee83f7e919",
+                "sha256:3f58aa995b905ab82fe228acd38538e7dc1509e01508dcf307dad5046399130f",
+                "sha256:48c996eb91bfbdab1e01e2c02e7ff678c51e2b28e3a04e26e41691991cc55795",
+                "sha256:48f218a5257b6bc16bcf26a91d97ecea0c7d29c811a90d965f3dd97c20f016d6",
+                "sha256:4a6551057a846bf72c7a04f73de3fcaca269c0bd85afe475ceb59d261c6a938c",
+                "sha256:51f90dabd9933b1621260b32c2f0d05d36923c7a5a909eb823e429dba0fd2f3e",
+                "sha256:577cc2c7b807b174814dac2d02e673728f2e46c7f90ceda3a70ea4bb6d90b769",
+                "sha256:5d79174d96446a02664e2bffc95e7b6fa93b9e6d8314536c5840dff130d0878b",
+                "sha256:5e3f81fbbc170418e22918a9585fd7281bbc11d027064d62aa4b507552c92671",
+                "sha256:5ecffdc748d3b40dd3618ede0170e4f5e1d3c9647cfb410d235d19e62cb54ee0",
+                "sha256:63fa57a0708573d3c059f7b5527617bd0c291e4559298473df238d502e4ab98c",
+                "sha256:67ca7032dfac8d001023fadafc812d9f48bf8a8c3bb15412d9cdcf92267593f4",
+                "sha256:688a1eb8c1a5f7e795c7cb67e0fe600194e6723ba35f138dfae0db20c0cb8f94",
+                "sha256:6a038cb1e6e55b26bb5520ccffab7f539b3786f5553af2ee47eb2ec5cbd7084e",
+                "sha256:6b79f6c31e68b6dafc0317ec453c83c86dd8db1f8f0c6f28e97186563fca87a0",
+                "sha256:6d3e027fe291b77f6be9630114a0200b2c52004ef20b94dc50ca59849cd623b3",
+                "sha256:6f1d39a744101bf4043fa0926b3ead616607578192d0a169974fb5265ab1e9d2",
+                "sha256:707adc30ea6918fba725c3cb3fe782d271ba352b22d7ae54a7f9f2e8a8488c41",
+                "sha256:730b7c2b7382194d9985ffdc32ab317e893bca21e0665cb1186bdfbb4089d990",
+                "sha256:764c7c6aa1f78bd77bd9674fc07d1ec44654da1818d0eef9fb48aa8371a3c847",
+                "sha256:78d51e35ed163783d721b6f2ce8ce3f82fccfe471e8e50a10fba13a766d31f5a",
+                "sha256:7a315ceb813208ef32bdd6ec3a85cbe3cb3be9bbda5fd030c234592fa9116993",
+                "sha256:7ba09bb3dcb0b7ec936a485db2b64be44fe14cdce0a5eac56f50e55da3627385",
+                "sha256:7d76e8a83396e06abe3df569b25bd3fc88bf78b7baa2c8e4cf4aaf5983af66a3",
+                "sha256:84fe1732648c1bc303a70faa67cbc2f7f2e810c8a5bca94f6db7818e722e4c0a",
+                "sha256:871d4fdc56288caa58b1094c20f2364215f7400411f76783ea19ad13be7c8e19",
+                "sha256:88d4917c30fcd7f6404fb1dc713fa21de59d3063dcc048f4a8a1a90e6bbbd739",
+                "sha256:8a50150419b741ee048b53146c39c47053f060cb9d98e78be08fdbe942eaa3c4",
+                "sha256:90a97c2ed2830e7974cbe45f0838de0aefc1c123313f7c402e21c29ec063fbb4",
+                "sha256:949a605ef3907254b122f845baa0920407080cdb1f73aa64f8d47df4a7f4c4f9",
+                "sha256:9689af0f0a89e5032426c143fa3683b0451f06c83bf3b1e27902bd33acfae769",
+                "sha256:98b1ea2763b33559dd9ec621d67fc17b583484cb90735bfb0ec3614c17b210e4",
+                "sha256:9951c2696c4357703001e1fe6edc6ae8e97553ac630492ea1bf64b429cb712a3",
+                "sha256:9a52b141ff3b923a9166595de6e3768a027546e75052ffba267d95b54267f4ab",
+                "sha256:9e8723c3256641e141cd18f6ce478d54a004138b9f1a36e41083b36d9ecc5fc5",
+                "sha256:a2fee4d656a7cc9ab47771b2a9e8fad8a9a33331c1b59c3057ecf0ac858f5bfe",
+                "sha256:a4759e85a191de58e0ea468ab6fd9c03941986eee436e0518d7a9291fab122c8",
+                "sha256:a5399a44a529083951b55521cf4ecbf6ad79fd54b9df57dbf01699ffa0549fc9",
+                "sha256:a6074a3b2fa2d0c9bf0963f8dfc85e1e54a26114cc8594126bc52d3fa061c40e",
+                "sha256:a84c335337b676d832c1e2bc47c3a97531b46b82de9f959dafb315cbcbe0dfcd",
+                "sha256:adf0cb251b1b842c9dee5cfcdf880ba0aae32e841b8d0e6b6feeaef002a267c5",
+                "sha256:b76669b7c058b8020b11008283c3b8e9c61bfd978807c45862956119b77ece45",
+                "sha256:bda75d73e7400e81077b0910c9a60bf9771f715420d7e35fa7739ae95555f195",
+                "sha256:be03a7483ad9ea60388f930160bb3728467dd0af538aa5edc60962ee700a0bdc",
+                "sha256:c62d4791a8212c885b97a63ef5f3974b2cd41930f0cd224ada9c6ee6654f8150",
+                "sha256:cb751ef712570d3bda9a73fd765ff3e1aba943ec5d52a54a0c2e89c7eef9da1e",
+                "sha256:d3b19d8d183bcfd68b25beebab8dc3308282fe2ca3d6ea3cb4cd101b3c279f8d",
+                "sha256:d3f90ee275b1d7c942e65b5c44c8fb52d55502a0b9a679837d71be2bd8927661",
+                "sha256:d5f8c04574efa814a24510122810e3a3c77c0552f9f6ff65c9862f1f046be2c3",
+                "sha256:d6a1a66bb8bac9bc2892c2674ea363486bfb748b86504966a390345a11b1680e",
+                "sha256:d7715daf84f10bcebc083ad137e3eced3e1c8e7fa1f096ade9a8d02b08f0d91c",
+                "sha256:dafc01a32b4a1d7d3ef8bfd3699406bb44f7b2e0d3eb8906d574846e1019b12f",
+                "sha256:dcc4d5dd5fba3affaf4fd08f00ef156407573de8c63338787614ccc64f96b321",
+                "sha256:de42f513ed7a997bc821bddab356b72e55e8396b1b7ba1bf39926d538a76a90f",
+                "sha256:e27cde1e8d17b09730801ce97b6e0c444ba2a1f06348b169fd931b51d3402f0d",
+                "sha256:ecb314e59bedb77188017f26e6b684b1f6d0465e724c3122a726359fa62ca1ba",
+                "sha256:f348ebd20554e8bc26e8ef3ed8a134110c0f4bf015b3b4da6a4ddf34e0515b19",
+                "sha256:fa818609357dde5c4a94a64c097c6404ad996b1d38ca977a72834b682830a722",
+                "sha256:fe4a327da0c6b6e59f2e474ae79d6ee7745ac3279fd15f200044602fa31e3d79"
             ],
             "index": "pypi",
-            "version": "==3.7.4.post0"
+            "version": "==3.8.0"
+        },
+        "aiosignal": {
+            "hashes": [
+                "sha256:26e62109036cd181df6e6ad646f91f0dcfd05fe16d0cb924138ff2ab75d64e3a",
+                "sha256:78ed67db6c7b7ced4f98e495e572106d5c432a93e1ddd1bf475e1dc05f5b7df2"
+            ],
+            "markers": "python_version >= '3.6'",
+            "version": "==1.2.0"
         },
         "alabaster": {
             "hashes": [
@@ -428,11 +686,19 @@
         },
         "async-timeout": {
             "hashes": [
-                "sha256:0c3c816a028d47f659d6ff5c745cb2acf1f966da1fe5c19c77a70282b25f4c5f",
-                "sha256:4291ca197d287d274d0b6cb5d6f8f8f82d434ed288f962539ff18cc9012f9ea3"
+                "sha256:a22c0b311af23337eb05fcf05a8b51c3ea53729d46fb5460af62bee033cec690",
+                "sha256:b930cb161a39042f9222f6efb7301399c87eeab394727ec5437924a36d6eef51"
             ],
-            "markers": "python_full_version >= '3.5.3'",
-            "version": "==3.0.1"
+            "markers": "python_version >= '3.6'",
+            "version": "==4.0.1"
+        },
+        "asynctest": {
+            "hashes": [
+                "sha256:5da6118a7e6d6b54d83a8f7197769d046922a44d2a99c21382f0a6e4fadae676",
+                "sha256:c27862842d15d83e6a34eb0b2866c323880eb3a75e4485b079ea11748fd77fac"
+            ],
+            "markers": "python_version < '3.8'",
+            "version": "==0.13.0"
         },
         "attrs": {
             "hashes": [
@@ -459,11 +725,11 @@
         },
         "backports.entry-points-selectable": {
             "hashes": [
-                "sha256:988468260ec1c196dab6ae1149260e2f5472c9110334e5d51adcb77867361f6a",
-                "sha256:a6d9a871cde5e15b4c4a53e3d43ba890cc6861ec1332c9c2428c92f977192acc"
+                "sha256:7fceed9532a7aa2bd888654a7314f864a3c16a4e710b34a58cfc0f08114c663b",
+                "sha256:914b21a479fde881635f7af5adc7f6e38d6b274be32269070c53b698c60d5386"
             ],
             "markers": "python_version >= '2.7'",
-            "version": "==1.1.0"
+            "version": "==1.1.1"
         },
         "black": {
             "editable": true,
@@ -474,100 +740,97 @@
         },
         "bleach": {
             "hashes": [
-                "sha256:c1685a132e6a9a38bf93752e5faab33a9517a6c0bb2f37b785e47bf253bdb51d",
-                "sha256:ffa9221c6ac29399cc50fcc33473366edd0cf8d5e2cbbbb63296dc327fb67cc8"
+                "sha256:0900d8b37eba61a802ee40ac0061f8c2b5dee29c1927dd1d233e075ebf5a71da",
+                "sha256:4d2651ab93271d1129ac9cbc679f524565cc8a1b791909c4a51eac4446a15994"
             ],
             "markers": "python_version >= '3.6'",
-            "version": "==4.0.0"
+            "version": "==4.1.0"
         },
         "certifi": {
             "hashes": [
-                "sha256:2bbf76fd432960138b3ef6dda3dde0544f27cbf8546c458e60baf371917ba9ee",
-                "sha256:50b1e4f8446b06f41be7dd6338db18e0990601dce795c2b1686458aa7e8fa7d8"
+                "sha256:78884e7c1d4b00ce3cea67b44566851c4343c120abd683433ce934a68ea58872",
+                "sha256:d62a0163eb4c2344ac042ab2bdf75399a71a2d8c7d47eac2e2ee91b9d6339569"
             ],
-            "version": "==2021.5.30"
+            "version": "==2021.10.8"
         },
         "cffi": {
             "hashes": [
-                "sha256:06c54a68935738d206570b20da5ef2b6b6d92b38ef3ec45c5422c0ebaf338d4d",
-                "sha256:0c0591bee64e438883b0c92a7bed78f6290d40bf02e54c5bf0978eaf36061771",
-                "sha256:19ca0dbdeda3b2615421d54bef8985f72af6e0c47082a8d26122adac81a95872",
-                "sha256:22b9c3c320171c108e903d61a3723b51e37aaa8c81255b5e7ce102775bd01e2c",
-                "sha256:26bb2549b72708c833f5abe62b756176022a7b9a7f689b571e74c8478ead51dc",
-                "sha256:33791e8a2dc2953f28b8d8d300dde42dd929ac28f974c4b4c6272cb2955cb762",
-                "sha256:3c8d896becff2fa653dc4438b54a5a25a971d1f4110b32bd3068db3722c80202",
-                "sha256:4373612d59c404baeb7cbd788a18b2b2a8331abcc84c3ba40051fcd18b17a4d5",
-                "sha256:487d63e1454627c8e47dd230025780e91869cfba4c753a74fda196a1f6ad6548",
-                "sha256:48916e459c54c4a70e52745639f1db524542140433599e13911b2f329834276a",
-                "sha256:4922cd707b25e623b902c86188aca466d3620892db76c0bdd7b99a3d5e61d35f",
-                "sha256:55af55e32ae468e9946f741a5d51f9896da6b9bf0bbdd326843fec05c730eb20",
-                "sha256:57e555a9feb4a8460415f1aac331a2dc833b1115284f7ded7278b54afc5bd218",
-                "sha256:5d4b68e216fc65e9fe4f524c177b54964af043dde734807586cf5435af84045c",
-                "sha256:64fda793737bc4037521d4899be780534b9aea552eb673b9833b01f945904c2e",
-                "sha256:6d6169cb3c6c2ad50db5b868db6491a790300ade1ed5d1da29289d73bbe40b56",
-                "sha256:7bcac9a2b4fdbed2c16fa5681356d7121ecabf041f18d97ed5b8e0dd38a80224",
-                "sha256:80b06212075346b5546b0417b9f2bf467fea3bfe7352f781ffc05a8ab24ba14a",
-                "sha256:818014c754cd3dba7229c0f5884396264d51ffb87ec86e927ef0be140bfdb0d2",
-                "sha256:8eb687582ed7cd8c4bdbff3df6c0da443eb89c3c72e6e5dcdd9c81729712791a",
-                "sha256:99f27fefe34c37ba9875f224a8f36e31d744d8083e00f520f133cab79ad5e819",
-                "sha256:9f3e33c28cd39d1b655ed1ba7247133b6f7fc16fa16887b120c0c670e35ce346",
-                "sha256:a8661b2ce9694ca01c529bfa204dbb144b275a31685a075ce123f12331be790b",
-                "sha256:a9da7010cec5a12193d1af9872a00888f396aba3dc79186604a09ea3ee7c029e",
-                "sha256:aedb15f0a5a5949ecb129a82b72b19df97bbbca024081ed2ef88bd5c0a610534",
-                "sha256:b315d709717a99f4b27b59b021e6207c64620790ca3e0bde636a6c7f14618abb",
-                "sha256:ba6f2b3f452e150945d58f4badd92310449876c4c954836cfb1803bdd7b422f0",
-                "sha256:c33d18eb6e6bc36f09d793c0dc58b0211fccc6ae5149b808da4a62660678b156",
-                "sha256:c9a875ce9d7fe32887784274dd533c57909b7b1dcadcc128a2ac21331a9765dd",
-                "sha256:c9e005e9bd57bc987764c32a1bee4364c44fdc11a3cc20a40b93b444984f2b87",
-                "sha256:d2ad4d668a5c0645d281dcd17aff2be3212bc109b33814bbb15c4939f44181cc",
-                "sha256:d950695ae4381ecd856bcaf2b1e866720e4ab9a1498cba61c602e56630ca7195",
-                "sha256:e22dcb48709fc51a7b58a927391b23ab37eb3737a98ac4338e2448bef8559b33",
-                "sha256:e8c6a99be100371dbb046880e7a282152aa5d6127ae01783e37662ef73850d8f",
-                "sha256:e9dc245e3ac69c92ee4c167fbdd7428ec1956d4e754223124991ef29eb57a09d",
-                "sha256:eb687a11f0a7a1839719edd80f41e459cc5366857ecbed383ff376c4e3cc6afd",
-                "sha256:eb9e2a346c5238a30a746893f23a9535e700f8192a68c07c0258e7ece6ff3728",
-                "sha256:ed38b924ce794e505647f7c331b22a693bee1538fdf46b0222c4717b42f744e7",
-                "sha256:f0010c6f9d1a4011e429109fda55a225921e3206e7f62a0c22a35344bfd13cca",
-                "sha256:f0c5d1acbfca6ebdd6b1e3eded8d261affb6ddcf2186205518f1428b8569bb99",
-                "sha256:f10afb1004f102c7868ebfe91c28f4a712227fe4cb24974350ace1f90e1febbf",
-                "sha256:f174135f5609428cc6e1b9090f9268f5c8935fddb1b25ccb8255a2d50de6789e",
-                "sha256:f3ebe6e73c319340830a9b2825d32eb6d8475c1dac020b4f0aa774ee3b898d1c",
-                "sha256:f627688813d0a4140153ff532537fbe4afea5a3dffce1f9deb7f91f848a832b5",
-                "sha256:fd4305f86f53dfd8cd3522269ed7fc34856a8ee3709a5e28b2836b2db9d4cd69"
-            ],
-            "version": "==1.14.6"
+                "sha256:00c878c90cb53ccfaae6b8bc18ad05d2036553e6d9d1d9dbcf323bbe83854ca3",
+                "sha256:0104fb5ae2391d46a4cb082abdd5c69ea4eab79d8d44eaaf79f1b1fd806ee4c2",
+                "sha256:06c48159c1abed75c2e721b1715c379fa3200c7784271b3c46df01383b593636",
+                "sha256:0808014eb713677ec1292301ea4c81ad277b6cdf2fdd90fd540af98c0b101d20",
+                "sha256:10dffb601ccfb65262a27233ac273d552ddc4d8ae1bf93b21c94b8511bffe728",
+                "sha256:14cd121ea63ecdae71efa69c15c5543a4b5fbcd0bbe2aad864baca0063cecf27",
+                "sha256:17771976e82e9f94976180f76468546834d22a7cc404b17c22df2a2c81db0c66",
+                "sha256:181dee03b1170ff1969489acf1c26533710231c58f95534e3edac87fff06c443",
+                "sha256:23cfe892bd5dd8941608f93348c0737e369e51c100d03718f108bf1add7bd6d0",
+                "sha256:263cc3d821c4ab2213cbe8cd8b355a7f72a8324577dc865ef98487c1aeee2bc7",
+                "sha256:2756c88cbb94231c7a147402476be2c4df2f6078099a6f4a480d239a8817ae39",
+                "sha256:27c219baf94952ae9d50ec19651a687b826792055353d07648a5695413e0c605",
+                "sha256:2a23af14f408d53d5e6cd4e3d9a24ff9e05906ad574822a10563efcef137979a",
+                "sha256:31fb708d9d7c3f49a60f04cf5b119aeefe5644daba1cd2a0fe389b674fd1de37",
+                "sha256:3415c89f9204ee60cd09b235810be700e993e343a408693e80ce7f6a40108029",
+                "sha256:3773c4d81e6e818df2efbc7dd77325ca0dcb688116050fb2b3011218eda36139",
+                "sha256:3b96a311ac60a3f6be21d2572e46ce67f09abcf4d09344c49274eb9e0bf345fc",
+                "sha256:3f7d084648d77af029acb79a0ff49a0ad7e9d09057a9bf46596dac9514dc07df",
+                "sha256:41d45de54cd277a7878919867c0f08b0cf817605e4eb94093e7516505d3c8d14",
+                "sha256:4238e6dab5d6a8ba812de994bbb0a79bddbdf80994e4ce802b6f6f3142fcc880",
+                "sha256:45db3a33139e9c8f7c09234b5784a5e33d31fd6907800b316decad50af323ff2",
+                "sha256:45e8636704eacc432a206ac7345a5d3d2c62d95a507ec70d62f23cd91770482a",
+                "sha256:4958391dbd6249d7ad855b9ca88fae690783a6be9e86df65865058ed81fc860e",
+                "sha256:4a306fa632e8f0928956a41fa8e1d6243c71e7eb59ffbd165fc0b41e316b2474",
+                "sha256:57e9ac9ccc3101fac9d6014fba037473e4358ef4e89f8e181f8951a2c0162024",
+                "sha256:59888172256cac5629e60e72e86598027aca6bf01fa2465bdb676d37636573e8",
+                "sha256:5e069f72d497312b24fcc02073d70cb989045d1c91cbd53979366077959933e0",
+                "sha256:64d4ec9f448dfe041705426000cc13e34e6e5bb13736e9fd62e34a0b0c41566e",
+                "sha256:6dc2737a3674b3e344847c8686cf29e500584ccad76204efea14f451d4cc669a",
+                "sha256:74fdfdbfdc48d3f47148976f49fab3251e550a8720bebc99bf1483f5bfb5db3e",
+                "sha256:75e4024375654472cc27e91cbe9eaa08567f7fbdf822638be2814ce059f58032",
+                "sha256:786902fb9ba7433aae840e0ed609f45c7bcd4e225ebb9c753aa39725bb3e6ad6",
+                "sha256:8b6c2ea03845c9f501ed1313e78de148cd3f6cad741a75d43a29b43da27f2e1e",
+                "sha256:91d77d2a782be4274da750752bb1650a97bfd8f291022b379bb8e01c66b4e96b",
+                "sha256:91ec59c33514b7c7559a6acda53bbfe1b283949c34fe7440bcf917f96ac0723e",
+                "sha256:920f0d66a896c2d99f0adbb391f990a84091179542c205fa53ce5787aff87954",
+                "sha256:a5263e363c27b653a90078143adb3d076c1a748ec9ecc78ea2fb916f9b861962",
+                "sha256:abb9a20a72ac4e0fdb50dae135ba5e77880518e742077ced47eb1499e29a443c",
+                "sha256:c2051981a968d7de9dd2d7b87bcb9c939c74a34626a6e2f8181455dd49ed69e4",
+                "sha256:c21c9e3896c23007803a875460fb786118f0cdd4434359577ea25eb556e34c55",
+                "sha256:c2502a1a03b6312837279c8c1bd3ebedf6c12c4228ddbad40912d671ccc8a962",
+                "sha256:d4d692a89c5cf08a8557fdeb329b82e7bf609aadfaed6c0d79f5a449a3c7c023",
+                "sha256:da5db4e883f1ce37f55c667e5c0de439df76ac4cb55964655906306918e7363c",
+                "sha256:e7022a66d9b55e93e1a845d8c9eba2a1bebd4966cd8bfc25d9cd07d515b33fa6",
+                "sha256:ef1f279350da2c586a69d32fc8733092fd32cc8ac95139a00377841f59a3f8d8",
+                "sha256:f54a64f8b0c8ff0b64d18aa76675262e1700f3995182267998c31ae974fbc382",
+                "sha256:f5c7150ad32ba43a07c4479f40241756145a1f03b43480e058cfd862bf5041c7",
+                "sha256:f6f824dc3bce0edab5f427efcfb1d63ee75b6fcb7282900ccaf925be84efb0fc",
+                "sha256:fd8a250edc26254fe5b33be00402e6d287f562b6a5b2152dec302fa15bb3e997",
+                "sha256:ffaa5c925128e29efbde7301d8ecaf35c8c60ffbcd6a1ffd3a552177c8e5e796"
+            ],
+            "version": "==1.15.0"
         },
         "cfgv": {
             "hashes": [
-                "sha256:9e600479b3b99e8af981ecdfc80a0296104ee610cab48a5ae4ffd0b668650eb1",
-                "sha256:b449c9c6118fe8cca7fa5e00b9ec60ba08145d281d52164230a69211c5d597a1"
+                "sha256:c6a0883f3917a037485059700b9e75da2464e6c27051014ad85ba6aaa5884426",
+                "sha256:f5a830efb9ce7a445376bb66ec94c638a9787422f96264c98edc6bdeed8ab736"
             ],
             "markers": "python_full_version >= '3.6.1'",
-            "version": "==3.3.0"
-        },
-        "chardet": {
-            "hashes": [
-                "sha256:0d6f53a15db4120f2b08c94f11e7d93d2c911ee118b6b30a04ec3ee8310179fa",
-                "sha256:f864054d66fd9118f2e67044ac8981a54775ec5b67aed0441892edb553d21da5"
-            ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
-            "version": "==4.0.0"
+            "version": "==3.3.1"
         },
         "charset-normalizer": {
             "hashes": [
-                "sha256:0c8911edd15d19223366a194a513099a302055a962bca2cec0f54b8b63175d8b",
-                "sha256:f23667ebe1084be45f6ae0538e4a5a865206544097e4e8bbcacf42cd02a348f3"
+                "sha256:e019de665e2bcf9c2b64e2e5aa025fa991da8720daa3c1138cadd2fd1856aed0",
+                "sha256:f7af805c321bfa1ce6714c51f254e0d5bb5e5834039bc17db7ebe3a4cec9492b"
             ],
-            "markers": "python_version >= '3'",
-            "version": "==2.0.4"
+            "markers": "python_version >= '3.5'",
+            "version": "==2.0.7"
         },
         "click": {
             "hashes": [
-                "sha256:8c04c11192119b1ef78ea049e0a6f0463e4c48ef00a30160c704337586f3ad7a",
-                "sha256:fba402a4a47334742d782209a7c79bc448911afe1149d07bdabdf480b3e2f4b6"
+                "sha256:353f466495adaeb40b6b5f592f9f91cb22372351c84caeb068132442a4518ef3",
+                "sha256:410e932b050f5eed773c4cda94de75971c89cdb3155a72a0831139a79e5ecb5b"
             ],
             "index": "pypi",
-            "version": "==8.0.1"
+            "version": "==8.0.3"
         },
         "colorama": {
             "hashes": [
@@ -579,81 +842,82 @@
         },
         "coverage": {
             "hashes": [
-                "sha256:004d1880bed2d97151facef49f08e255a20ceb6f9432df75f4eef018fdd5a78c",
-                "sha256:01d84219b5cdbfc8122223b39a954820929497a1cb1422824bb86b07b74594b6",
-                "sha256:040af6c32813fa3eae5305d53f18875bedd079960822ef8ec067a66dd8afcd45",
-                "sha256:06191eb60f8d8a5bc046f3799f8a07a2d7aefb9504b0209aff0b47298333302a",
-                "sha256:13034c4409db851670bc9acd836243aeee299949bd5673e11844befcb0149f03",
-                "sha256:13c4ee887eca0f4c5a247b75398d4114c37882658300e153113dafb1d76de529",
-                "sha256:184a47bbe0aa6400ed2d41d8e9ed868b8205046518c52464fde713ea06e3a74a",
-                "sha256:18ba8bbede96a2c3dde7b868de9dcbd55670690af0988713f0603f037848418a",
-                "sha256:1aa846f56c3d49205c952d8318e76ccc2ae23303351d9270ab220004c580cfe2",
-                "sha256:217658ec7187497e3f3ebd901afdca1af062b42cfe3e0dafea4cced3983739f6",
-                "sha256:24d4a7de75446be83244eabbff746d66b9240ae020ced65d060815fac3423759",
-                "sha256:2910f4d36a6a9b4214bb7038d537f015346f413a975d57ca6b43bf23d6563b53",
-                "sha256:2949cad1c5208b8298d5686d5a85b66aae46d73eec2c3e08c817dd3513e5848a",
-                "sha256:2a3859cb82dcbda1cfd3e6f71c27081d18aa251d20a17d87d26d4cd216fb0af4",
-                "sha256:2cafbbb3af0733db200c9b5f798d18953b1a304d3f86a938367de1567f4b5bff",
-                "sha256:2e0d881ad471768bf6e6c2bf905d183543f10098e3b3640fc029509530091502",
-                "sha256:30c77c1dc9f253283e34c27935fded5015f7d1abe83bc7821680ac444eaf7793",
-                "sha256:3487286bc29a5aa4b93a072e9592f22254291ce96a9fbc5251f566b6b7343cdb",
-                "sha256:372da284cfd642d8e08ef606917846fa2ee350f64994bebfbd3afb0040436905",
-                "sha256:41179b8a845742d1eb60449bdb2992196e211341818565abded11cfa90efb821",
-                "sha256:44d654437b8ddd9eee7d1eaee28b7219bec228520ff809af170488fd2fed3e2b",
-                "sha256:4a7697d8cb0f27399b0e393c0b90f0f1e40c82023ea4d45d22bce7032a5d7b81",
-                "sha256:51cb9476a3987c8967ebab3f0fe144819781fca264f57f89760037a2ea191cb0",
-                "sha256:52596d3d0e8bdf3af43db3e9ba8dcdaac724ba7b5ca3f6358529d56f7a166f8b",
-                "sha256:53194af30d5bad77fcba80e23a1441c71abfb3e01192034f8246e0d8f99528f3",
-                "sha256:5fec2d43a2cc6965edc0bb9e83e1e4b557f76f843a77a2496cbe719583ce8184",
-                "sha256:6c90e11318f0d3c436a42409f2749ee1a115cd8b067d7f14c148f1ce5574d701",
-                "sha256:74d881fc777ebb11c63736622b60cb9e4aee5cace591ce274fb69e582a12a61a",
-                "sha256:7501140f755b725495941b43347ba8a2777407fc7f250d4f5a7d2a1050ba8e82",
-                "sha256:796c9c3c79747146ebd278dbe1e5c5c05dd6b10cc3bcb8389dfdf844f3ead638",
-                "sha256:869a64f53488f40fa5b5b9dcb9e9b2962a66a87dab37790f3fcfb5144b996ef5",
-                "sha256:8963a499849a1fc54b35b1c9f162f4108017b2e6db2c46c1bed93a72262ed083",
-                "sha256:8d0a0725ad7c1a0bcd8d1b437e191107d457e2ec1084b9f190630a4fb1af78e6",
-                "sha256:900fbf7759501bc7807fd6638c947d7a831fc9fdf742dc10f02956ff7220fa90",
-                "sha256:92b017ce34b68a7d67bd6d117e6d443a9bf63a2ecf8567bb3d8c6c7bc5014465",
-                "sha256:970284a88b99673ccb2e4e334cfb38a10aab7cd44f7457564d11898a74b62d0a",
-                "sha256:972c85d205b51e30e59525694670de6a8a89691186012535f9d7dbaa230e42c3",
-                "sha256:9a1ef3b66e38ef8618ce5fdc7bea3d9f45f3624e2a66295eea5e57966c85909e",
-                "sha256:af0e781009aaf59e25c5a678122391cb0f345ac0ec272c7961dc5455e1c40066",
-                "sha256:b6d534e4b2ab35c9f93f46229363e17f63c53ad01330df9f2d6bd1187e5eaacf",
-                "sha256:b7895207b4c843c76a25ab8c1e866261bcfe27bfaa20c192de5190121770672b",
-                "sha256:c0891a6a97b09c1f3e073a890514d5012eb256845c451bd48f7968ef939bf4ae",
-                "sha256:c2723d347ab06e7ddad1a58b2a821218239249a9e4365eaff6649d31180c1669",
-                "sha256:d1f8bf7b90ba55699b3a5e44930e93ff0189aa27186e96071fac7dd0d06a1873",
-                "sha256:d1f9ce122f83b2305592c11d64f181b87153fc2c2bbd3bb4a3dde8303cfb1a6b",
-                "sha256:d314ed732c25d29775e84a960c3c60808b682c08d86602ec2c3008e1202e3bb6",
-                "sha256:d636598c8305e1f90b439dbf4f66437de4a5e3c31fdf47ad29542478c8508bbb",
-                "sha256:deee1077aae10d8fa88cb02c845cfba9b62c55e1183f52f6ae6a2df6a2187160",
-                "sha256:ebe78fe9a0e874362175b02371bdfbee64d8edc42a044253ddf4ee7d3c15212c",
-                "sha256:f030f8873312a16414c0d8e1a1ddff2d3235655a2174e3648b4fa66b3f2f1079",
-                "sha256:f0b278ce10936db1a37e6954e15a3730bea96a0997c26d7fee88e6c396c2086d",
-                "sha256:f11642dddbb0253cc8853254301b51390ba0081750a8ac03f20ea8103f0c56b6"
+                "sha256:046647b96969fda1ae0605f61288635209dd69dcd27ba3ec0bf5148bc157f954",
+                "sha256:06d009e8a29483cbc0520665bc46035ffe9ae0e7484a49f9782c2a716e37d0a0",
+                "sha256:0cde7d9fe2fb55ff68ebe7fb319ef188e9b88e0a3d1c9c5db7dd829cd93d2193",
+                "sha256:1de9c6f5039ee2b1860b7bad2c7bc3651fbeb9368e4c4d93e98a76358cdcb052",
+                "sha256:24ed38ec86754c4d5a706fbd5b52b057c3df87901a8610d7e5642a08ec07087e",
+                "sha256:27a3df08a855522dfef8b8635f58bab81341b2fb5f447819bc252da3aa4cf44c",
+                "sha256:310c40bed6b626fd1f463e5a83dba19a61c4eb74e1ac0d07d454ebbdf9047e9d",
+                "sha256:3348865798c077c695cae00da0924136bb5cc501f236cfd6b6d9f7a3c94e0ec4",
+                "sha256:35b246ae3a2c042dc8f410c94bcb9754b18179cdb81ff9477a9089dbc9ecc186",
+                "sha256:3f546f48d5d80a90a266769aa613bc0719cb3e9c2ef3529d53f463996dd15a9d",
+                "sha256:586d38dfc7da4a87f5816b203ff06dd7c1bb5b16211ccaa0e9788a8da2b93696",
+                "sha256:5d3855d5d26292539861f5ced2ed042fc2aa33a12f80e487053aed3bcb6ced13",
+                "sha256:610c0ba11da8de3a753dc4b1f71894f9f9debfdde6559599f303286e70aeb0c2",
+                "sha256:62646d98cf0381ffda301a816d6ac6c35fc97aa81b09c4c52d66a15c4bef9d7c",
+                "sha256:66af99c7f7b64d050d37e795baadf515b4561124f25aae6e1baa482438ecc388",
+                "sha256:675adb3b3380967806b3cbb9c5b00ceb29b1c472692100a338730c1d3e59c8b9",
+                "sha256:6e5a8c947a2a89c56655ecbb789458a3a8e3b0cbf4c04250331df8f647b3de59",
+                "sha256:7a39590d1e6acf6a3c435c5d233f72f5d43b585f5be834cff1f21fec4afda225",
+                "sha256:80cb70264e9a1d04b519cdba3cd0dc42847bf8e982a4d55c769b9b0ee7cdce1e",
+                "sha256:82fdcb64bf08aa5db881db061d96db102c77397a570fbc112e21c48a4d9cb31b",
+                "sha256:8492d37acdc07a6eac6489f6c1954026f2260a85a4c2bb1e343fe3d35f5ee21a",
+                "sha256:94f558f8555e79c48c422045f252ef41eb43becdd945e9c775b45ebfc0cbd78f",
+                "sha256:958ac66272ff20e63d818627216e3d7412fdf68a2d25787b89a5c6f1eb7fdd93",
+                "sha256:95a58336aa111af54baa451c33266a8774780242cab3704b7698d5e514840758",
+                "sha256:96129e41405887a53a9cc564f960d7f853cc63d178f3a182fdd302e4cab2745b",
+                "sha256:97ef6e9119bd39d60ef7b9cd5deea2b34869c9f0b9777450a7e3759c1ab09b9b",
+                "sha256:98d44a8136eebbf544ad91fef5bd2b20ef0c9b459c65a833c923d9aa4546b204",
+                "sha256:9d2c2e3ce7b8cc932a2f918186964bd44de8c84e2f9ef72dc616f5bb8be22e71",
+                "sha256:a300b39c3d5905686c75a369d2a66e68fd01472ea42e16b38c948bd02b29e5bd",
+                "sha256:a34fccb45f7b2d890183a263578d60a392a1a218fdc12f5bce1477a6a68d4373",
+                "sha256:a4d48e42e17d3de212f9af44f81ab73b9378a4b2b8413fd708d0d9023f2bbde4",
+                "sha256:af45eea024c0e3a25462fade161afab4f0d9d9e0d5a5d53e86149f74f0a35ecc",
+                "sha256:ba6125d4e55c0b8e913dad27b22722eac7abdcb1f3eab1bd090eee9105660266",
+                "sha256:bc1ee1318f703bc6c971da700d74466e9b86e0c443eb85983fb2a1bd20447263",
+                "sha256:c18725f3cffe96732ef96f3de1939d81215fd6d7d64900dcc4acfe514ea4fcbf",
+                "sha256:c8e9c4bcaaaa932be581b3d8b88b677489975f845f7714efc8cce77568b6711c",
+                "sha256:cc799916b618ec9fd00135e576424165691fec4f70d7dc12cfaef09268a2478c",
+                "sha256:cd2d11a59afa5001ff28073ceca24ae4c506da4355aba30d1e7dd2bd0d2206dc",
+                "sha256:d0a595a781f8e186580ff8e3352dd4953b1944289bec7705377c80c7e36c4d6c",
+                "sha256:d3c5f49ce6af61154060640ad3b3281dbc46e2e0ef2fe78414d7f8a324f0b649",
+                "sha256:d9a635114b88c0ab462e0355472d00a180a5fbfd8511e7f18e4ac32652e7d972",
+                "sha256:e5432d9c329b11c27be45ee5f62cf20a33065d482c8dec1941d6670622a6fb8f",
+                "sha256:eab14fdd410500dae50fd14ccc332e65543e7b39f6fc076fe90603a0e5d2f929",
+                "sha256:ebcc03e1acef4ff44f37f3c61df478d6e469a573aa688e5a162f85d7e4c3860d",
+                "sha256:fae3fe111670e51f1ebbc475823899524e3459ea2db2cb88279bbfb2a0b8a3de",
+                "sha256:fd92ece726055e80d4e3f01fff3b91f54b18c9c357c48fcf6119e87e2461a091",
+                "sha256:ffa545230ca2ad921ad066bf8fd627e7be43716b6e0fcf8e32af1b8188ccb0ab"
             ],
             "index": "pypi",
-            "version": "==5.5"
+            "version": "==6.1.2"
         },
         "cryptography": {
             "hashes": [
-                "sha256:0f1212a66329c80d68aeeb39b8a16d54ef57071bf22ff4e521657b27372e327d",
-                "sha256:1e056c28420c072c5e3cb36e2b23ee55e260cb04eee08f702e0edfec3fb51959",
-                "sha256:240f5c21aef0b73f40bb9f78d2caff73186700bf1bc6b94285699aff98cc16c6",
-                "sha256:26965837447f9c82f1855e0bc8bc4fb910240b6e0d16a664bb722df3b5b06873",
-                "sha256:37340614f8a5d2fb9aeea67fd159bfe4f5f4ed535b1090ce8ec428b2f15a11f2",
-                "sha256:3d10de8116d25649631977cb37da6cbdd2d6fa0e0281d014a5b7d337255ca713",
-                "sha256:3d8427734c781ea5f1b41d6589c293089704d4759e34597dce91014ac125aad1",
-                "sha256:7ec5d3b029f5fa2b179325908b9cd93db28ab7b85bb6c1db56b10e0b54235177",
-                "sha256:8e56e16617872b0957d1c9742a3f94b43533447fd78321514abbe7db216aa250",
-                "sha256:b01fd6f2737816cb1e08ed4807ae194404790eac7ad030b34f2ce72b332f5586",
-                "sha256:bf40af59ca2465b24e54f671b2de2c59257ddc4f7e5706dbd6930e26823668d3",
-                "sha256:de4e5f7f68220d92b7637fc99847475b59154b7a1b3868fb7385337af54ac9ca",
-                "sha256:eb8cc2afe8b05acbd84a43905832ec78e7b3873fb124ca190f574dca7389a87d",
-                "sha256:ee77aa129f481be46f8d92a1a7db57269a2f23052d5f2433b4621bb457081cc9"
+                "sha256:07bb7fbfb5de0980590ddfc7f13081520def06dc9ed214000ad4372fb4e3c7f6",
+                "sha256:18d90f4711bf63e2fb21e8c8e51ed8189438e6b35a6d996201ebd98a26abbbe6",
+                "sha256:1ed82abf16df40a60942a8c211251ae72858b25b7421ce2497c2eb7a1cee817c",
+                "sha256:22a38e96118a4ce3b97509443feace1d1011d0571fae81fc3ad35f25ba3ea999",
+                "sha256:2d69645f535f4b2c722cfb07a8eab916265545b3475fdb34e0be2f4ee8b0b15e",
+                "sha256:4a2d0e0acc20ede0f06ef7aa58546eee96d2592c00f450c9acb89c5879b61992",
+                "sha256:54b2605e5475944e2213258e0ab8696f4f357a31371e538ef21e8d61c843c28d",
+                "sha256:7075b304cd567694dc692ffc9747f3e9cb393cc4aa4fb7b9f3abd6f5c4e43588",
+                "sha256:7b7ceeff114c31f285528ba8b390d3e9cfa2da17b56f11d366769a807f17cbaa",
+                "sha256:7eba2cebca600a7806b893cb1d541a6e910afa87e97acf2021a22b32da1df52d",
+                "sha256:928185a6d1ccdb816e883f56ebe92e975a262d31cc536429041921f8cb5a62fd",
+                "sha256:9933f28f70d0517686bd7de36166dda42094eac49415459d9bdf5e7df3e0086d",
+                "sha256:a688ebcd08250eab5bb5bca318cc05a8c66de5e4171a65ca51db6bd753ff8953",
+                "sha256:abb5a361d2585bb95012a19ed9b2c8f412c5d723a9836418fab7aaa0243e67d2",
+                "sha256:c10c797ac89c746e488d2ee92bd4abd593615694ee17b2500578b63cad6b93a8",
+                "sha256:ced40344e811d6abba00295ced98c01aecf0c2de39481792d87af4fa58b7b4d6",
+                "sha256:d57e0cdc1b44b6cdf8af1d01807db06886f10177469312fbde8f44ccbb284bc9",
+                "sha256:d99915d6ab265c22873f1b4d6ea5ef462ef797b4140be4c9d8b179915e0985c6",
+                "sha256:eb80e8a1f91e4b7ef8b33041591e6d89b2b8e122d787e87eeb2b08da71bb16ad",
+                "sha256:ebeddd119f526bcf323a89f853afb12e225902a24d29b55fe18dd6fcb2838a76"
             ],
             "markers": "python_version >= '3.6'",
-            "version": "==3.4.7"
+            "version": "==35.0.0"
         },
         "dataclasses": {
             "hashes": [
@@ -666,18 +930,18 @@
         },
         "decorator": {
             "hashes": [
-                "sha256:6e5c199c16f7a9f0e3a61a4a54b3d27e7dad0dbdde92b944426cb20914376323",
-                "sha256:72ecfba4320a893c53f9706bebb2d55c270c1e51a28789361aa93e4a21319ed5"
+                "sha256:7b12e7c3c6ab203a29e157335e9122cb03de9ab7264b137594103fd4a683b374",
+                "sha256:e59913af105b9860aa2c8d3272d9de5a56a4e608db9a2f167a8480b323d529a7"
             ],
             "markers": "python_version >= '3.5'",
-            "version": "==5.0.9"
+            "version": "==5.1.0"
         },
         "distlib": {
             "hashes": [
-                "sha256:106fef6dc37dd8c0e2c0a60d3fca3e77460a48907f335fa28420463a6f799736",
-                "sha256:23e223426b28491b1ced97dc3bbe183027419dfc7982b4fa2f05d5f3ff10711c"
+                "sha256:c8b54e8454e5bf6237cc84c20e8264c3e991e824ef27e8f1e81049867d861e31",
+                "sha256:d982d0751ff6eaaab5e2ec8e691d949ee80eddf01a62eaa96ddb11531fe16b05"
             ],
-            "version": "==0.3.2"
+            "version": "==0.3.3"
         },
         "docutils": {
             "hashes": [
@@ -697,42 +961,121 @@
         },
         "filelock": {
             "hashes": [
-                "sha256:18d82244ee114f543149c66a6e0c14e9c4f8a1044b5cdaadd0f82159d6a6ff59",
-                "sha256:929b7d63ec5b7d6b71b0fa5ac14e030b3f70b75747cef1b10da9b879fef15836"
+                "sha256:7afc856f74fa7006a289fd10fa840e1eebd8bbff6bffb69c26c54a0512ea8cf8",
+                "sha256:bb2a1c717df74c48a2d00ed625e5a66f8572a3a30baacb7657add1d7bac4097b"
             ],
-            "version": "==3.0.12"
+            "markers": "python_version >= '3.6'",
+            "version": "==3.3.2"
         },
         "flake8": {
             "hashes": [
-                "sha256:07528381786f2a6237b061f6e96610a4167b226cb926e2aa2b6b1d78057c576b",
-                "sha256:bf8fd333346d844f616e8d47905ef3a3384edae6b4e9beb0c5101e25e3110907"
+                "sha256:479b1304f72536a55948cb40a32dce8bb0ffe3501e26eaf292c7e60eb5e0428d",
+                "sha256:806e034dda44114815e23c16ef92f95c91e4c71100ff52813adf7132a6ad870d"
             ],
             "index": "pypi",
-            "version": "==3.9.2"
+            "version": "==4.0.1"
         },
         "flake8-bugbear": {
             "hashes": [
-                "sha256:2346c81f889955b39e4a368eb7d508de723d9de05716c287dc860a4073dc57e7",
-                "sha256:4f305dca96be62bf732a218fe6f1825472a621d3452c5b994d8f89dae21dbafa"
+                "sha256:4f7eaa6f05b7d7ea4cbbde93f7bcdc5438e79320fa1ec420d860c181af38b769",
+                "sha256:db9a09893a6c649a197f5350755100bb1dd84f110e60cf532fdfa07e41808ab2"
             ],
             "index": "pypi",
-            "version": "==21.4.3"
+            "version": "==21.9.2"
+        },
+        "frozenlist": {
+            "hashes": [
+                "sha256:01d79515ed5aa3d699b05f6bdcf1fe9087d61d6b53882aa599a10853f0479c6c",
+                "sha256:0a7c7cce70e41bc13d7d50f0e5dd175f14a4f1837a8549b0936ed0cbe6170bf9",
+                "sha256:11ff401951b5ac8c0701a804f503d72c048173208490c54ebb8d7bb7c07a6d00",
+                "sha256:14a5cef795ae3e28fb504b73e797c1800e9249f950e1c964bb6bdc8d77871161",
+                "sha256:16eef427c51cb1203a7c0ab59d1b8abccaba9a4f58c4bfca6ed278fc896dc193",
+                "sha256:16ef7dd5b7d17495404a2e7a49bac1bc13d6d20c16d11f4133c757dd94c4144c",
+                "sha256:181754275d5d32487431a0a29add4f897968b7157204bc1eaaf0a0ce80c5ba7d",
+                "sha256:1cf63243bc5f5c19762943b0aa9e0d3fb3723d0c514d820a18a9b9a5ef864315",
+                "sha256:1cfe6fef507f8bac40f009c85c7eddfed88c1c0d38c75e72fe10476cef94e10f",
+                "sha256:1fef737fd1388f9b93bba8808c5f63058113c10f4e3c0763ced68431773f72f9",
+                "sha256:25b358aaa7dba5891b05968dd539f5856d69f522b6de0bf34e61f133e077c1a4",
+                "sha256:26f602e380a5132880fa245c92030abb0fc6ff34e0c5500600366cedc6adb06a",
+                "sha256:28e164722ea0df0cf6d48c4d5bdf3d19e87aaa6dfb39b0ba91153f224b912020",
+                "sha256:2de5b931701257d50771a032bba4e448ff958076380b049fd36ed8738fdb375b",
+                "sha256:3457f8cf86deb6ce1ba67e120f1b0128fcba1332a180722756597253c465fc1d",
+                "sha256:351686ca020d1bcd238596b1fa5c8efcbc21bffda9d0efe237aaa60348421e2a",
+                "sha256:406aeb340613b4b559db78d86864485f68919b7141dec82aba24d1477fd2976f",
+                "sha256:41de4db9b9501679cf7cddc16d07ac0f10ef7eb58c525a1c8cbff43022bddca4",
+                "sha256:41f62468af1bd4e4b42b5508a3fe8cc46a693f0cdd0ca2f443f51f207893d837",
+                "sha256:4766632cd8a68e4f10f156a12c9acd7b1609941525569dd3636d859d79279ed3",
+                "sha256:47b2848e464883d0bbdcd9493c67443e5e695a84694efff0476f9059b4cb6257",
+                "sha256:4a495c3d513573b0b3f935bfa887a85d9ae09f0627cf47cad17d0cc9b9ba5c38",
+                "sha256:4ad065b2ebd09f32511ff2be35c5dfafee6192978b5a1e9d279a5c6e121e3b03",
+                "sha256:4c457220468d734e3077580a3642b7f682f5fd9507f17ddf1029452450912cdc",
+                "sha256:4f52d0732e56906f8ddea4bd856192984650282424049c956857fed43697ea43",
+                "sha256:54a1e09ab7a69f843cd28fefd2bcaf23edb9e3a8d7680032c8968b8ac934587d",
+                "sha256:5a72eecf37eface331636951249d878750db84034927c997d47f7f78a573b72b",
+                "sha256:5df31bb2b974f379d230a25943d9bf0d3bc666b4b0807394b131a28fca2b0e5f",
+                "sha256:66a518731a21a55b7d3e087b430f1956a36793acc15912e2878431c7aec54210",
+                "sha256:6790b8d96bbb74b7a6f4594b6f131bd23056c25f2aa5d816bd177d95245a30e3",
+                "sha256:68201be60ac56aff972dc18085800b6ee07973c49103a8aba669dee3d71079de",
+                "sha256:6e105013fa84623c057a4381dc8ea0361f4d682c11f3816cc80f49a1f3bc17c6",
+                "sha256:705c184b77565955a99dc360f359e8249580c6b7eaa4dc0227caa861ef46b27a",
+                "sha256:72cfbeab7a920ea9e74b19aa0afe3b4ad9c89471e3badc985d08756efa9b813b",
+                "sha256:735f386ec522e384f511614c01d2ef9cf799f051353876b4c6fb93ef67a6d1ee",
+                "sha256:82d22f6e6f2916e837c91c860140ef9947e31194c82aaeda843d6551cec92f19",
+                "sha256:83334e84a290a158c0c4cc4d22e8c7cfe0bba5b76d37f1c2509dabd22acafe15",
+                "sha256:84e97f59211b5b9083a2e7a45abf91cfb441369e8bb6d1f5287382c1c526def3",
+                "sha256:87521e32e18a2223311afc2492ef2d99946337da0779ddcda77b82ee7319df59",
+                "sha256:878ebe074839d649a1cdb03a61077d05760624f36d196884a5cafb12290e187b",
+                "sha256:89fdfc84c6bf0bff2ff3170bb34ecba8a6911b260d318d377171429c4be18c73",
+                "sha256:8b4c7665a17c3a5430edb663e4ad4e1ad457614d1b2f2b7f87052e2ef4fa45ca",
+                "sha256:8b54cdd2fda15467b9b0bfa78cee2ddf6dbb4585ef23a16e14926f4b076dfae4",
+                "sha256:94728f97ddf603d23c8c3dd5cae2644fa12d33116e69f49b1644a71bb77b89ae",
+                "sha256:954b154a4533ef28bd3e83ffdf4eadf39deeda9e38fb8feaf066d6069885e034",
+                "sha256:977a1438d0e0d96573fd679d291a1542097ea9f4918a8b6494b06610dfeefbf9",
+                "sha256:9ade70aea559ca98f4b1b1e5650c45678052e76a8ab2f76d90f2ac64180215a2",
+                "sha256:9b6e21e5770df2dea06cb7b6323fbc008b13c4a4e3b52cb54685276479ee7676",
+                "sha256:a0d3ffa8772464441b52489b985d46001e2853a3b082c655ec5fad9fb6a3d618",
+                "sha256:a37594ad6356e50073fe4f60aa4187b97d15329f2138124d252a5a19c8553ea4",
+                "sha256:a8d86547a5e98d9edd47c432f7a14b0c5592624b496ae9880fb6332f34af1edc",
+                "sha256:aa44c4740b4e23fcfa259e9dd52315d2b1770064cde9507457e4c4a65a04c397",
+                "sha256:acc4614e8d1feb9f46dd829a8e771b8f5c4b1051365d02efb27a3229048ade8a",
+                "sha256:af2a51c8a381d76eabb76f228f565ed4c3701441ecec101dd18be70ebd483cfd",
+                "sha256:b2ae2f5e9fa10805fb1c9adbfefaaecedd9e31849434be462c3960a0139ed729",
+                "sha256:b46f997d5ed6d222a863b02cdc9c299101ee27974d9bbb2fd1b3c8441311c408",
+                "sha256:bc93f5f62df3bdc1f677066327fc81f92b83644852a31c6aa9b32c2dde86ea7d",
+                "sha256:bfbaa08cf1452acad9cb1c1d7b89394a41e712f88df522cea1a0f296b57782a0",
+                "sha256:c1e8e9033d34c2c9e186e58279879d78c94dd365068a3607af33f2bc99357a53",
+                "sha256:c5328ed53fdb0a73c8a50105306a3bc013e5ca36cca714ec4f7bd31d38d8a97f",
+                "sha256:c6a9d84ee6427b65a81fc24e6ef589cb794009f5ca4150151251c062773e7ed2",
+                "sha256:c98d3c04701773ad60d9545cd96df94d955329efc7743fdb96422c4b669c633b",
+                "sha256:cb3957c39668d10e2b486acc85f94153520a23263b6401e8f59422ef65b9520d",
+                "sha256:e63ad0beef6ece06475d29f47d1f2f29727805376e09850ebf64f90777962792",
+                "sha256:e74f8b4d8677ebb4015ac01fcaf05f34e8a1f22775db1f304f497f2f88fdc697",
+                "sha256:e7d0dd3e727c70c2680f5f09a0775525229809f1a35d8552b92ff10b2b14f2c2",
+                "sha256:ec6cf345771cdb00791d271af9a0a6fbfc2b6dd44cb753f1eeaa256e21622adb",
+                "sha256:ed58803563a8c87cf4c0771366cf0ad1aa265b6b0ae54cbbb53013480c7ad74d",
+                "sha256:f0081a623c886197ff8de9e635528fd7e6a387dccef432149e25c13946cb0cd0",
+                "sha256:f025f1d6825725b09c0038775acab9ae94264453a696cc797ce20c0769a7b367",
+                "sha256:f5f3b2942c3b8b9bfe76b408bbaba3d3bb305ee3693e8b1d631fe0a0d4f93673",
+                "sha256:fbd4844ff111449f3bbe20ba24fbb906b5b1c2384d0f3287c9f7da2354ce6d23"
+            ],
+            "markers": "python_version >= '3.6'",
+            "version": "==1.2.0"
         },
         "identify": {
             "hashes": [
-                "sha256:7199679b5be13a6b40e6e19ea473e789b11b4e3b60986499b1f589ffb03c217c",
-                "sha256:7bc6e829392bd017236531963d2d937d66fc27cadc643ac0aba2ce9f26157c79"
+                "sha256:6f0368ba0f21c199645a331beb7425d5374376e71bc149e9cb55e45cb45f832d",
+                "sha256:ba945bddb4322394afcf3f703fa68eda08a6acc0f99d9573eb2be940aa7b9bba"
             ],
             "markers": "python_full_version >= '3.6.1'",
-            "version": "==2.2.13"
+            "version": "==2.3.5"
         },
         "idna": {
             "hashes": [
-                "sha256:14475042e284991034cb48e06f6851428fb14c4dc953acd9be9a5e95c7b6dd7a",
-                "sha256:467fbad99067910785144ce333826c71fb0e63a425657295239737f7ecd125f3"
+                "sha256:84d9dd047ffa80596e0f246e2eab0b391788b0503584e8945f2368256d2735ff",
+                "sha256:9d643ff0a55b762d5cdb124b8eaa99c66322e2157b69160bc32796e824360e6d"
             ],
             "markers": "python_version >= '3.5'",
-            "version": "==3.2"
+            "version": "==3.3"
         },
         "idna-ssl": {
             "hashes": [
@@ -743,27 +1086,27 @@
         },
         "imagesize": {
             "hashes": [
-                "sha256:6965f19a6a2039c7d48bca7dba2473069ff854c36ae6f19d2cde309d998228a1",
-                "sha256:b1f6b5a4eab1f73479a50fb79fcf729514a900c341d8503d62a62dbc4127a2b1"
+                "sha256:1db2f82529e53c3e929e8926a1fa9235aa82d0bd0c580359c67ec31b2fddaa8c",
+                "sha256:cd1750d452385ca327479d45b64d9c7729ecf0b3969a58148298c77092261f9d"
             ],
             "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==1.2.0"
+            "version": "==1.3.0"
         },
         "importlib-metadata": {
             "hashes": [
-                "sha256:7b30a78db2922d78a6f47fb30683156a14f3c6aa5cc23f77cc8967e9ab2d002f",
-                "sha256:ed5157fef23a4bc4594615a0dd8eba94b2bb36bf2a343fa3d8bb2fa0a62a99d5"
+                "sha256:53ccfd5c134223e497627b9815d5030edf77d2ed573922f7a0b8f8bb81a1c100",
+                "sha256:75bdec14c397f528724c1bfd9709d660b33a4d2e77387a3358f20b848bb5e5fb"
             ],
             "markers": "python_version < '3.8'",
-            "version": "==4.6.4"
+            "version": "==4.8.2"
         },
         "importlib-resources": {
             "hashes": [
-                "sha256:2480d8e07d1890056cb53c96e3de44fead9c62f2ba949b0f2e4c4345f4afa977",
-                "sha256:a65882a4d0fe5fbf702273456ba2ce74fe44892c25e42e057aca526b702a6d4b"
+                "sha256:33a95faed5fc19b4bc16b29a6eeae248a3fe69dd55d4d229d2b480e23eeaad45",
+                "sha256:d756e2f85dd4de2ba89be0b21dba2a3bbec2e871a42a3a16719258a11f87506b"
             ],
             "markers": "python_version < '3.7'",
-            "version": "==5.2.2"
+            "version": "==5.4.0"
         },
         "iniconfig": {
             "hashes": [
@@ -805,19 +1148,19 @@
         },
         "jinja2": {
             "hashes": [
-                "sha256:1f06f2da51e7b56b8f238affdd6b4e2c61e39598a378cc49345bc1bd42a978a4",
-                "sha256:703f484b47a6af502e743c9122595cc812b0271f661722403114f71a79d0f5a4"
+                "sha256:077ce6014f7b40d03b47d1f1ca4b0fc8328a692bd284016f806ed0eaca390ad8",
+                "sha256:611bb273cd68f3b993fabdc4064fc858c5b47a973cb5aa7999ec1ba405c87cd7"
             ],
             "markers": "python_version >= '3.6'",
-            "version": "==3.0.1"
+            "version": "==3.0.3"
         },
         "keyring": {
             "hashes": [
-                "sha256:b32397fd7e7063f8dd74a26db910c9862fc2109285fa16e3b5208bcb42a3e579",
-                "sha256:b7e0156667f5dcc73c1f63a518005cd18a4eb23fe77321194fefcc03748b21a4"
+                "sha256:6334aee6073db2fb1f30892697b1730105b5e9a77ce7e61fca6b435225493efe",
+                "sha256:bd2145a237ed70c8ce72978b497619ddfcae640b6dcf494402d5143e37755c6e"
             ],
             "markers": "python_version >= '3.6'",
-            "version": "==23.1.0"
+            "version": "==23.2.1"
         },
         "markdown-it-py": {
             "hashes": [
@@ -832,6 +1175,7 @@
                 "sha256:01a9b8ea66f1658938f65b93a85ebe8bc016e6769611be228d797c9d998dd298",
                 "sha256:023cb26ec21ece8dc3907c0e8320058b2e0cb3c55cf9564da612bc325bed5e64",
                 "sha256:0446679737af14f45767963a1a9ef7620189912317d095f2d9ffa183a4d25d2b",
+                "sha256:04635854b943835a6ea959e948d19dcd311762c5c0c6e1f0e16ee57022669194",
                 "sha256:0717a7390a68be14b8c793ba258e075c6f4ca819f15edfc2a3a027c823718567",
                 "sha256:0955295dd5eec6cb6cc2fe1698f4c6d84af2e92de33fbcac4111913cd100a6ff",
                 "sha256:0d4b31cc67ab36e3392bbf3862cfbadac3db12bdd8b02a2731f509ed5b829724",
@@ -839,6 +1183,7 @@
                 "sha256:168cd0a3642de83558a5153c8bd34f175a9a6e7f6dc6384b9655d2697312a646",
                 "sha256:1d609f577dc6e1aa17d746f8bd3c31aa4d258f4070d61b2aa5c4166c1539de35",
                 "sha256:1f2ade76b9903f39aa442b4aadd2177decb66525062db244b35d71d0ee8599b6",
+                "sha256:20dca64a3ef2d6e4d5d615a3fd418ad3bde77a47ec8a23d984a12b5b4c74491a",
                 "sha256:2a7d351cbd8cfeb19ca00de495e224dea7e7d919659c2841bbb7f420ad03e2d6",
                 "sha256:2d7d807855b419fc2ed3e631034685db6079889a1f01d5d9dac950f764da3dad",
                 "sha256:2ef54abee730b502252bcdf31b10dacb0a416229b72c18b19e24a4509f273d26",
@@ -846,27 +1191,36 @@
                 "sha256:37205cac2a79194e3750b0af2a5720d95f786a55ce7df90c3af697bfa100eaac",
                 "sha256:3c112550557578c26af18a1ccc9e090bfe03832ae994343cfdacd287db6a6ae7",
                 "sha256:3dd007d54ee88b46be476e293f48c85048603f5f516008bee124ddd891398ed6",
+                "sha256:4296f2b1ce8c86a6aea78613c34bb1a672ea0e3de9c6ba08a960efe0b0a09047",
                 "sha256:47ab1e7b91c098ab893b828deafa1203de86d0bc6ab587b160f78fe6c4011f75",
                 "sha256:49e3ceeabbfb9d66c3aef5af3a60cc43b85c33df25ce03d0031a608b0a8b2e3f",
+                "sha256:4dc8f9fb58f7364b63fd9f85013b780ef83c11857ae79f2feda41e270468dd9b",
                 "sha256:4efca8f86c54b22348a5467704e3fec767b2db12fc39c6d963168ab1d3fc9135",
                 "sha256:53edb4da6925ad13c07b6d26c2a852bd81e364f95301c66e930ab2aef5b5ddd8",
                 "sha256:5855f8438a7d1d458206a2466bf82b0f104a3724bf96a1c781ab731e4201731a",
                 "sha256:594c67807fb16238b30c44bdf74f36c02cdf22d1c8cda91ef8a0ed8dabf5620a",
+                "sha256:5b6d930f030f8ed98e3e6c98ffa0652bdb82601e7a016ec2ab5d7ff23baa78d1",
                 "sha256:5bb28c636d87e840583ee3adeb78172efc47c8b26127267f54a9c0ec251d41a9",
                 "sha256:60bf42e36abfaf9aff1f50f52644b336d4f0a3fd6d8a60ca0d054ac9f713a864",
                 "sha256:611d1ad9a4288cf3e3c16014564df047fe08410e628f89805e475368bd304914",
+                "sha256:6300b8454aa6930a24b9618fbb54b5a68135092bc666f7b06901f897fa5c2fee",
+                "sha256:63f3268ba69ace99cab4e3e3b5840b03340efed0948ab8f78d2fd87ee5442a4f",
                 "sha256:6557b31b5e2c9ddf0de32a691f2312a32f77cd7681d8af66c2692efdbef84c18",
                 "sha256:693ce3f9e70a6cf7d2fb9e6c9d8b204b6b39897a2c4a1aa65728d5ac97dcc1d8",
                 "sha256:6a7fae0dd14cf60ad5ff42baa2e95727c3d81ded453457771d02b7d2b3f9c0c2",
                 "sha256:6c4ca60fa24e85fe25b912b01e62cb969d69a23a5d5867682dd3e80b5b02581d",
                 "sha256:6fcf051089389abe060c9cd7caa212c707e58153afa2c649f00346ce6d260f1b",
                 "sha256:7d91275b0245b1da4d4cfa07e0faedd5b0812efc15b702576d103293e252af1b",
+                "sha256:89c687013cb1cd489a0f0ac24febe8c7a666e6e221b783e53ac50ebf68e45d86",
+                "sha256:8d206346619592c6200148b01a2142798c989edcb9c896f9ac9722a99d4e77e6",
                 "sha256:905fec760bd2fa1388bb5b489ee8ee5f7291d692638ea5f67982d968366bef9f",
                 "sha256:97383d78eb34da7e1fa37dd273c20ad4320929af65d156e35a5e2d89566d9dfb",
                 "sha256:984d76483eb32f1bcb536dc27e4ad56bba4baa70be32fa87152832cdd9db0833",
                 "sha256:99df47edb6bda1249d3e80fdabb1dab8c08ef3975f69aed437cb69d0a5de1e28",
+                "sha256:9f02365d4e99430a12647f09b6cc8bab61a6564363f313126f775eb4f6ef798e",
                 "sha256:a30e67a65b53ea0a5e62fe23682cfe22712e01f453b95233b25502f7c61cb415",
                 "sha256:ab3ef638ace319fa26553db0624c4699e31a28bb2a835c5faca8f8acf6a5a902",
+                "sha256:aca6377c0cb8a8253e493c6b451565ac77e98c2951c45f913e0b52facdcff83f",
                 "sha256:add36cb2dbb8b736611303cd3bfcee00afd96471b09cda130da3581cbdc56a6d",
                 "sha256:b2f4bf27480f5e5e8ce285a8c8fd176c0b03e93dcc6646477d4630e83440c6a9",
                 "sha256:b7f2d075102dc8c794cbde1947378051c4e5180d52d276987b8d28a3bd58c17d",
@@ -874,10 +1228,14 @@
                 "sha256:be98f628055368795d818ebf93da628541e10b75b41c559fdf36d104c5787066",
                 "sha256:bf5d821ffabf0ef3533c39c518f3357b171a1651c1ff6827325e4489b0e46c3c",
                 "sha256:c47adbc92fc1bb2b3274c4b3a43ae0e4573d9fbff4f54cd484555edbf030baf1",
+                "sha256:cdfba22ea2f0029c9261a4bd07e830a8da012291fbe44dc794e488b6c9bb353a",
+                "sha256:d6c7ebd4e944c85e2c3421e612a7057a2f48d478d79e61800d81468a8d842207",
                 "sha256:d7f9850398e85aba693bb640262d3611788b1f29a79f0c93c565694658f4071f",
                 "sha256:d8446c54dc28c01e5a2dbac5a25f071f6653e6e40f3a8818e8b45d790fe6ef53",
+                "sha256:deb993cacb280823246a026e3b2d81c493c53de6acfd5e6bfe31ab3402bb37dd",
                 "sha256:e0f138900af21926a02425cf736db95be9f4af72ba1bb21453432a07f6082134",
                 "sha256:e9936f0b261d4df76ad22f8fee3ae83b60d7c3e871292cd42f40b81b70afae85",
+                "sha256:f0567c4dc99f264f49fe27da5f735f414c4e7e7dd850cfd8e69f0862d7c74ea9",
                 "sha256:f5653a225f31e113b152e56f154ccbe59eeb1c7487b39b9d9f9cdb58e6c79dc5",
                 "sha256:f826e31d18b516f653fe296d967d700fddad5901ae07c622bb3705955e1faa94",
                 "sha256:f8ba0e8349a38d3001fae7eadded3f6606f0da5d748ee53cc1dab1d6527b9509",
@@ -887,14 +1245,6 @@
             "markers": "python_version >= '3.6'",
             "version": "==2.0.1"
         },
-        "matplotlib-inline": {
-            "hashes": [
-                "sha256:5cf1176f554abb4fa98cb362aa2b55c500147e4bdbb07e3fda359143e1da0811",
-                "sha256:f41d5ff73c9f5385775d5c0bc13b424535c8402fe70ea8210f93e11f3683993e"
-            ],
-            "markers": "python_version >= '3.5'",
-            "version": "==0.1.2"
-        },
         "mccabe": {
             "hashes": [
                 "sha256:ab8a6258860da4b6677da4bd2fe5dc2c659cff31b3ee4f7f5d64e79735b80d42",
@@ -912,46 +1262,81 @@
         },
         "multidict": {
             "hashes": [
-                "sha256:018132dbd8688c7a69ad89c4a3f39ea2f9f33302ebe567a879da8f4ca73f0d0a",
-                "sha256:051012ccee979b2b06be928a6150d237aec75dd6bf2d1eeeb190baf2b05abc93",
-                "sha256:05c20b68e512166fddba59a918773ba002fdd77800cad9f55b59790030bab632",
-                "sha256:07b42215124aedecc6083f1ce6b7e5ec5b50047afa701f3442054373a6deb656",
-                "sha256:0e3c84e6c67eba89c2dbcee08504ba8644ab4284863452450520dad8f1e89b79",
-                "sha256:0e929169f9c090dae0646a011c8b058e5e5fb391466016b39d21745b48817fd7",
-                "sha256:1ab820665e67373de5802acae069a6a05567ae234ddb129f31d290fc3d1aa56d",
-                "sha256:25b4e5f22d3a37ddf3effc0710ba692cfc792c2b9edfb9c05aefe823256e84d5",
-                "sha256:2e68965192c4ea61fff1b81c14ff712fc7dc15d2bd120602e4a3494ea6584224",
-                "sha256:2f1a132f1c88724674271d636e6b7351477c27722f2ed789f719f9e3545a3d26",
-                "sha256:37e5438e1c78931df5d3c0c78ae049092877e5e9c02dd1ff5abb9cf27a5914ea",
-                "sha256:3a041b76d13706b7fff23b9fc83117c7b8fe8d5fe9e6be45eee72b9baa75f348",
-                "sha256:3a4f32116f8f72ecf2a29dabfb27b23ab7cdc0ba807e8459e59a93a9be9506f6",
-                "sha256:46c73e09ad374a6d876c599f2328161bcd95e280f84d2060cf57991dec5cfe76",
-                "sha256:46dd362c2f045095c920162e9307de5ffd0a1bfbba0a6e990b344366f55a30c1",
-                "sha256:4b186eb7d6ae7c06eb4392411189469e6a820da81447f46c0072a41c748ab73f",
-                "sha256:54fd1e83a184e19c598d5e70ba508196fd0bbdd676ce159feb412a4a6664f952",
-                "sha256:585fd452dd7782130d112f7ddf3473ffdd521414674c33876187e101b588738a",
-                "sha256:5cf3443199b83ed9e955f511b5b241fd3ae004e3cb81c58ec10f4fe47c7dce37",
-                "sha256:6a4d5ce640e37b0efcc8441caeea8f43a06addace2335bd11151bc02d2ee31f9",
-                "sha256:7df80d07818b385f3129180369079bd6934cf70469f99daaebfac89dca288359",
-                "sha256:806068d4f86cb06af37cd65821554f98240a19ce646d3cd24e1c33587f313eb8",
-                "sha256:830f57206cc96ed0ccf68304141fec9481a096c4d2e2831f311bde1c404401da",
-                "sha256:929006d3c2d923788ba153ad0de8ed2e5ed39fdbe8e7be21e2f22ed06c6783d3",
-                "sha256:9436dc58c123f07b230383083855593550c4d301d2532045a17ccf6eca505f6d",
-                "sha256:9dd6e9b1a913d096ac95d0399bd737e00f2af1e1594a787e00f7975778c8b2bf",
-                "sha256:ace010325c787c378afd7f7c1ac66b26313b3344628652eacd149bdd23c68841",
-                "sha256:b47a43177a5e65b771b80db71e7be76c0ba23cc8aa73eeeb089ed5219cdbe27d",
-                "sha256:b797515be8743b771aa868f83563f789bbd4b236659ba52243b735d80b29ed93",
-                "sha256:b7993704f1a4b204e71debe6095150d43b2ee6150fa4f44d6d966ec356a8d61f",
-                "sha256:d5c65bdf4484872c4af3150aeebe101ba560dcfb34488d9a8ff8dbcd21079647",
-                "sha256:d81eddcb12d608cc08081fa88d046c78afb1bf8107e6feab5d43503fea74a635",
-                "sha256:dc862056f76443a0db4509116c5cd480fe1b6a2d45512a653f9a855cc0517456",
-                "sha256:ecc771ab628ea281517e24fd2c52e8f31c41e66652d07599ad8818abaad38cda",
-                "sha256:f200755768dc19c6f4e2b672421e0ebb3dd54c38d5a4f262b872d8cfcc9e93b5",
-                "sha256:f21756997ad8ef815d8ef3d34edd98804ab5ea337feedcd62fb52d22bf531281",
-                "sha256:fc13a9524bc18b6fb6e0dbec3533ba0496bbed167c56d0aabefd965584557d80"
+                "sha256:06560fbdcf22c9387100979e65b26fba0816c162b888cb65b845d3def7a54c9b",
+                "sha256:067150fad08e6f2dd91a650c7a49ba65085303fcc3decbd64a57dc13a2733031",
+                "sha256:0a2cbcfbea6dc776782a444db819c8b78afe4db597211298dd8b2222f73e9cd0",
+                "sha256:0dd1c93edb444b33ba2274b66f63def8a327d607c6c790772f448a53b6ea59ce",
+                "sha256:0fed465af2e0eb6357ba95795d003ac0bdb546305cc2366b1fc8f0ad67cc3fda",
+                "sha256:116347c63ba049c1ea56e157fa8aa6edaf5e92925c9b64f3da7769bdfa012858",
+                "sha256:1b4ac3ba7a97b35a5ccf34f41b5a8642a01d1e55454b699e5e8e7a99b5a3acf5",
+                "sha256:1c7976cd1c157fa7ba5456ae5d31ccdf1479680dc9b8d8aa28afabc370df42b8",
+                "sha256:246145bff76cc4b19310f0ad28bd0769b940c2a49fc601b86bfd150cbd72bb22",
+                "sha256:25cbd39a9029b409167aa0a20d8a17f502d43f2efebfe9e3ac019fe6796c59ac",
+                "sha256:28e6d883acd8674887d7edc896b91751dc2d8e87fbdca8359591a13872799e4e",
+                "sha256:2d1d55cdf706ddc62822d394d1df53573d32a7a07d4f099470d3cb9323b721b6",
+                "sha256:2e77282fd1d677c313ffcaddfec236bf23f273c4fba7cdf198108f5940ae10f5",
+                "sha256:32fdba7333eb2351fee2596b756d730d62b5827d5e1ab2f84e6cbb287cc67fe0",
+                "sha256:35591729668a303a02b06e8dba0eb8140c4a1bfd4c4b3209a436a02a5ac1de11",
+                "sha256:380b868f55f63d048a25931a1632818f90e4be71d2081c2338fcf656d299949a",
+                "sha256:3822c5894c72e3b35aae9909bef66ec83e44522faf767c0ad39e0e2de11d3b55",
+                "sha256:38ba256ee9b310da6a1a0f013ef4e422fca30a685bcbec86a969bd520504e341",
+                "sha256:3bc3b1621b979621cee9f7b09f024ec76ec03cc365e638126a056317470bde1b",
+                "sha256:3d2d7d1fff8e09d99354c04c3fd5b560fb04639fd45926b34e27cfdec678a704",
+                "sha256:517d75522b7b18a3385726b54a081afd425d4f41144a5399e5abd97ccafdf36b",
+                "sha256:5f79c19c6420962eb17c7e48878a03053b7ccd7b69f389d5831c0a4a7f1ac0a1",
+                "sha256:5f841c4f14331fd1e36cbf3336ed7be2cb2a8f110ce40ea253e5573387db7621",
+                "sha256:637c1896497ff19e1ee27c1c2c2ddaa9f2d134bbb5e0c52254361ea20486418d",
+                "sha256:6ee908c070020d682e9b42c8f621e8bb10c767d04416e2ebe44e37d0f44d9ad5",
+                "sha256:77f0fb7200cc7dedda7a60912f2059086e29ff67cefbc58d2506638c1a9132d7",
+                "sha256:7878b61c867fb2df7a95e44b316f88d5a3742390c99dfba6c557a21b30180cac",
+                "sha256:78c106b2b506b4d895ddc801ff509f941119394b89c9115580014127414e6c2d",
+                "sha256:8b911d74acdc1fe2941e59b4f1a278a330e9c34c6c8ca1ee21264c51ec9b67ef",
+                "sha256:93de39267c4c676c9ebb2057e98a8138bade0d806aad4d864322eee0803140a0",
+                "sha256:9416cf11bcd73c861267e88aea71e9fcc35302b3943e45e1dbb4317f91a4b34f",
+                "sha256:94b117e27efd8e08b4046c57461d5a114d26b40824995a2eb58372b94f9fca02",
+                "sha256:9815765f9dcda04921ba467957be543423e5ec6a1136135d84f2ae092c50d87b",
+                "sha256:98ec9aea6223adf46999f22e2c0ab6cf33f5914be604a404f658386a8f1fba37",
+                "sha256:a37e9a68349f6abe24130846e2f1d2e38f7ddab30b81b754e5a1fde32f782b23",
+                "sha256:a43616aec0f0d53c411582c451f5d3e1123a68cc7b3475d6f7d97a626f8ff90d",
+                "sha256:a4771d0d0ac9d9fe9e24e33bed482a13dfc1256d008d101485fe460359476065",
+                "sha256:a5635bcf1b75f0f6ef3c8a1ad07b500104a971e38d3683167b9454cb6465ac86",
+                "sha256:a9acb76d5f3dd9421874923da2ed1e76041cb51b9337fd7f507edde1d86535d6",
+                "sha256:ac42181292099d91217a82e3fa3ce0e0ddf3a74fd891b7c2b347a7f5aa0edded",
+                "sha256:b227345e4186809d31f22087d0265655114af7cda442ecaf72246275865bebe4",
+                "sha256:b61f85101ef08cbbc37846ac0e43f027f7844f3fade9b7f6dd087178caedeee7",
+                "sha256:b70913cbf2e14275013be98a06ef4b412329fe7b4f83d64eb70dce8269ed1e1a",
+                "sha256:b9aad49466b8d828b96b9e3630006234879c8d3e2b0a9d99219b3121bc5cdb17",
+                "sha256:baf1856fab8212bf35230c019cde7c641887e3fc08cadd39d32a421a30151ea3",
+                "sha256:bd6c9c50bf2ad3f0448edaa1a3b55b2e6866ef8feca5d8dbec10ec7c94371d21",
+                "sha256:c1ff762e2ee126e6f1258650ac641e2b8e1f3d927a925aafcfde943b77a36d24",
+                "sha256:c30ac9f562106cd9e8071c23949a067b10211917fdcb75b4718cf5775356a940",
+                "sha256:c9631c642e08b9fff1c6255487e62971d8b8e821808ddd013d8ac058087591ac",
+                "sha256:cdd68778f96216596218b4e8882944d24a634d984ee1a5a049b300377878fa7c",
+                "sha256:ce8cacda0b679ebc25624d5de66c705bc53dcc7c6f02a7fb0f3ca5e227d80422",
+                "sha256:cfde464ca4af42a629648c0b0d79b8f295cf5b695412451716531d6916461628",
+                "sha256:d3def943bfd5f1c47d51fd324df1e806d8da1f8e105cc7f1c76a1daf0f7e17b0",
+                "sha256:d9b668c065968c5979fe6b6fa6760bb6ab9aeb94b75b73c0a9c1acf6393ac3bf",
+                "sha256:da7d57ea65744d249427793c042094c4016789eb2562576fb831870f9c878d9e",
+                "sha256:dc3a866cf6c13d59a01878cd806f219340f3e82eed514485e094321f24900677",
+                "sha256:df23c83398715b26ab09574217ca21e14694917a0c857e356fd39e1c64f8283f",
+                "sha256:dfc924a7e946dd3c6360e50e8f750d51e3ef5395c95dc054bc9eab0f70df4f9c",
+                "sha256:e4a67f1080123de76e4e97a18d10350df6a7182e243312426d508712e99988d4",
+                "sha256:e5283c0a00f48e8cafcecadebfa0ed1dac8b39e295c7248c44c665c16dc1138b",
+                "sha256:e58a9b5cc96e014ddf93c2227cbdeca94b56a7eb77300205d6e4001805391747",
+                "sha256:e6453f3cbeb78440747096f239d282cc57a2997a16b5197c9bc839099e1633d0",
+                "sha256:e6c4fa1ec16e01e292315ba76eb1d012c025b99d22896bd14a66628b245e3e01",
+                "sha256:e7d81ce5744757d2f05fc41896e3b2ae0458464b14b5a2c1e87a6a9d69aefaa8",
+                "sha256:ea21d4d5104b4f840b91d9dc8cbc832aba9612121eaba503e54eaab1ad140eb9",
+                "sha256:ecc99bce8ee42dcad15848c7885197d26841cb24fa2ee6e89d23b8993c871c64",
+                "sha256:f0bb0973f42ffcb5e3537548e0767079420aefd94ba990b61cf7bb8d47f4916d",
+                "sha256:f19001e790013ed580abfde2a4465388950728861b52f0da73e8e8a9418533c0",
+                "sha256:f76440e480c3b2ca7f843ff8a48dc82446b86ed4930552d736c0bac507498a52",
+                "sha256:f9bef5cff994ca3026fcc90680e326d1a19df9841c5e3d224076407cc21471a1",
+                "sha256:fc66d4016f6e50ed36fb39cd287a3878ffcebfa90008535c62e0e90a7ab713ae",
+                "sha256:fd77c8f3cba815aa69cb97ee2b2ef385c7c12ada9c734b0f3b32e26bb88bbf1d"
             ],
             "markers": "python_version >= '3.6'",
-            "version": "==5.1.0"
+            "version": "==5.2.0"
         },
         "mypy": {
             "hashes": [
@@ -992,11 +1377,11 @@
         },
         "myst-parser": {
             "hashes": [
-                "sha256:7c3c78a36c4bc30ce6a67933ebd800a880c8d81f1688fad5c2ebd82cddbc1603",
-                "sha256:e8baa9959dac0bcf0f3ea5fc32a1a28792959471d8a8094e3ed5ee0de9733ade"
+                "sha256:40124b6f27a4c42ac7f06b385e23a9dcd03d84801e9c7130b59b3729a554b1f9",
+                "sha256:f7f3b2d62db7655cde658eb5d62b2ec2a4631308137bd8d10f296a40d57bbbeb"
             ],
             "index": "pypi",
-            "version": "==0.15.1"
+            "version": "==0.15.2"
         },
         "nodeenv": {
             "hashes": [
@@ -1007,11 +1392,11 @@
         },
         "packaging": {
             "hashes": [
-                "sha256:7dc96269f53a4ccec5c0670940a4281106dd0bb343f47b7471f779df49c2fbe7",
-                "sha256:c86254f9220d55e31cc94d69bade760f0847da8000def4dfe1c6b872fd14ff14"
+                "sha256:096d689d78ca690e4cd8a89568ba06d07ca097e3306a4381635073ca91479966",
+                "sha256:14317396d1e8cdb122989b916fa2c7e9ca8e2be9e8060a6eff75b6b7b4d8a7e0"
             ],
             "markers": "python_version >= '3.6'",
-            "version": "==21.0"
+            "version": "==21.2"
         },
         "parso": {
             "hashes": [
@@ -1053,35 +1438,35 @@
         },
         "platformdirs": {
             "hashes": [
-                "sha256:4666d822218db6a262bdfdc9c39d21f23b4cfdb08af331a81e92751daf6c866c",
-                "sha256:632daad3ab546bd8e6af0537d09805cec458dce201bccfe23012df73332e181e"
+                "sha256:367a5e80b3d04d2428ffa76d33f124cf11e8fff2acdaa9b43d545f5c7d661ef2",
+                "sha256:8868bbe3c3c80d42f20156f22e7131d2fb321f5bc86a2a345375c6481a67021d"
             ],
             "index": "pypi",
-            "version": "==2.2.0"
+            "version": "==2.4.0"
         },
         "pluggy": {
             "hashes": [
-                "sha256:15b2acde666561e1298d71b523007ed7364de07029219b604cf808bfa1c765b0",
-                "sha256:966c145cd83c96502c3c3868f50408687b38434af77734af1e9ca461a4081d2d"
+                "sha256:4224373bacce55f955a878bf9cfa763c1e360858e330072059e10bad68531159",
+                "sha256:74134bbf457f031a36d68416e1509f34bd5ccc019f0bcc952c7b909d06b37bd3"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==0.13.1"
+            "markers": "python_version >= '3.6'",
+            "version": "==1.0.0"
         },
         "pre-commit": {
             "hashes": [
-                "sha256:2386eeb4cf6633712c7cc9ede83684d53c8cafca6b59f79c738098b51c6d206c",
-                "sha256:ec3045ae62e1aa2eecfb8e86fa3025c2e3698f77394ef8d2011ce0aedd85b2d4"
+                "sha256:3c25add78dbdfb6a28a651780d5c311ac40dd17f160eb3954a0c59da40a505a7",
+                "sha256:a4ed01000afcb484d9eb8d504272e642c4c4099bbad3a6b27e519bd6a3e928a6"
             ],
             "index": "pypi",
-            "version": "==2.14.0"
+            "version": "==2.15.0"
         },
         "prompt-toolkit": {
             "hashes": [
-                "sha256:6076e46efae19b1e0ca1ec003ed37a933dc94b4d20f486235d436e64771dcd5c",
-                "sha256:eb71d5a6b72ce6db177af4a7d4d7085b99756bf656d98ffcc4fecd36850eea6c"
+                "sha256:449f333dd120bd01f5d296a8ce1452114ba3a71fae7288d2f0ae2c918764fa72",
+                "sha256:48d85cdca8b6c4f16480c7ce03fd193666b62b0a21667ca56b4bb5ad679d1170"
             ],
             "markers": "python_full_version >= '3.6.2'",
-            "version": "==3.0.20"
+            "version": "==3.0.22"
         },
         "ptyprocess": {
             "hashes": [
@@ -1092,35 +1477,34 @@
         },
         "py": {
             "hashes": [
-                "sha256:21b81bda15b66ef5e1a777a21c4dcd9c20ad3efd0b3f817e7a809035269e1bd3",
-                "sha256:3b80836aa6d1feeaa108e046da6423ab8f6ceda6468545ae8d02d9d58d18818a"
+                "sha256:51c75c4126074b472f746a24399ad32f6053d1b34b68d2fa41e558e6f4a98719",
+                "sha256:607c53218732647dff4acdfcd50cb62615cedf612e72d1724fb1a0cc6405b378"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==1.10.0"
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
+            "version": "==1.11.0"
         },
         "pycodestyle": {
             "hashes": [
-                "sha256:514f76d918fcc0b55c6680472f0a37970994e07bbb80725808c17089be302068",
-                "sha256:c389c1d06bf7904078ca03399a4816f974a1d590090fecea0c63ec26ebaf1cef"
+                "sha256:720f8b39dde8b293825e7ff02c475f3077124006db4f440dcbc9a20b76548a20",
+                "sha256:eddd5847ef438ea1c7870ca7eb78a9d47ce0cdb4851a5523949f2601d0cbbe7f"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==2.7.0"
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
+            "version": "==2.8.0"
         },
         "pycparser": {
             "hashes": [
-                "sha256:2d475327684562c3a96cc71adf7dc8c4f0565175cf86b6d7a404ff4c771f15f0",
-                "sha256:7582ad22678f0fcd81102833f60ef8d0e57288b6b5fb00323d101be910e35705"
+                "sha256:8ee45429555515e1f6b185e78100aea234072576aa43ab53aefcae078162fca9",
+                "sha256:e644fdec12f7872f86c58ff790da456218b10f863970249516d60a5eaca77206"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==2.20"
+            "version": "==2.21"
         },
         "pyflakes": {
             "hashes": [
-                "sha256:7893783d01b8a89811dd72d7dfd4d84ff098e5eed95cfa8905b22bbffe52efc3",
-                "sha256:f5bc8ecabc05bb9d291eb5203d6810b49040f6ff446a756326104746cc00c1db"
+                "sha256:05a85c2872edf37a4ed30b0cce2f6093e1d0581f8c19d7393122da7e25b2b24c",
+                "sha256:3bb3a3f256f4b7968c9c788781e4ff07dce46bdf12339dcda61053375426ee2e"
             ],
             "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==2.3.1"
+            "version": "==2.4.0"
         },
         "pygments": {
             "hashes": [
@@ -1135,24 +1519,24 @@
                 "sha256:c203ec8783bf771a155b207279b9bccb8dea02d8f0c9e5f8ead507bc3246ecc1",
                 "sha256:ef9d7589ef3c200abe66653d3f1ab1033c3c419ae9b9bdb1240a85b024efc88b"
             ],
-            "markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2, 3.3'",
+            "markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2'",
             "version": "==2.4.7"
         },
         "pytest": {
             "hashes": [
-                "sha256:50bcad0a0b9c5a72c8e4e7c9855a3ad496ca6a881a3641b4260605450772c54b",
-                "sha256:91ef2131a9bd6be8f76f1f08eac5c5317221d6ad1e143ae03894b862e8976890"
+                "sha256:131b36680866a76e6781d13f101efb86cf674ebb9762eb70d3082b6f29889e89",
+                "sha256:7310f8d27bc79ced999e760ca304d69f6ba6c6649c0b60fb0e04a4a77cacc134"
             ],
             "index": "pypi",
-            "version": "==6.2.4"
+            "version": "==6.2.5"
         },
         "pytest-cov": {
             "hashes": [
-                "sha256:261bb9e47e65bd099c89c3edf92972865210c36813f80ede5277dceb77a4a62a",
-                "sha256:261ceeb8c227b726249b376b8526b600f38667ee314f910353fa318caa01f4d7"
+                "sha256:578d5d15ac4a25e5f961c938b85a05b09fdaae9deef3bb6de9a6e766622ca7a6",
+                "sha256:e7f0f5b1617d2210a2cabc266dfe2f4c75a8d32fb89eafb7ad9d06f6d076d470"
             ],
             "index": "pypi",
-            "version": "==2.12.1"
+            "version": "==3.0.0"
         },
         "pytest-forked": {
             "hashes": [
@@ -1164,108 +1548,120 @@
         },
         "pytest-xdist": {
             "hashes": [
-                "sha256:e8ecde2f85d88fbcadb7d28cb33da0fa29bca5cf7d5967fa89fc0e97e5299ea5",
-                "sha256:ed3d7da961070fce2a01818b51f6888327fb88df4379edeb6b9d990e789d9c8d"
+                "sha256:7b61ebb46997a0820a263553179d6d1e25a8c50d8a8620cd1aa1e20e3be99168",
+                "sha256:89b330316f7fc475f999c81b577c2b926c9569f3d397ae432c0c2e2496d61ff9"
             ],
             "index": "pypi",
-            "version": "==2.3.0"
+            "version": "==2.4.0"
         },
         "pytz": {
             "hashes": [
-                "sha256:83a4a90894bf38e243cf052c8b58f381bfe9a7a483f6a9cab140bc7f702ac4da",
-                "sha256:eb10ce3e7736052ed3623d49975ce333bcd712c7bb19a58b9e2089d4057d0798"
+                "sha256:3672058bc3453457b622aab7a1c3bfd5ab0bdae451512f6cf25f64ed37f5b87c",
+                "sha256:acad2d8b20a1af07d4e4c9d2e9285c5ed9104354062f275f3fcd88dcef4f1326"
             ],
-            "version": "==2021.1"
+            "version": "==2021.3"
         },
         "pyyaml": {
             "hashes": [
-                "sha256:08682f6b72c722394747bddaf0aa62277e02557c0fd1c42cb853016a38f8dedf",
-                "sha256:0f5f5786c0e09baddcd8b4b45f20a7b5d61a7e7e99846e3c799b05c7c53fa696",
-                "sha256:129def1b7c1bf22faffd67b8f3724645203b79d8f4cc81f674654d9902cb4393",
-                "sha256:294db365efa064d00b8d1ef65d8ea2c3426ac366c0c4368d930bf1c5fb497f77",
-                "sha256:3b2b1824fe7112845700f815ff6a489360226a5609b96ec2190a45e62a9fc922",
-                "sha256:3bd0e463264cf257d1ffd2e40223b197271046d09dadf73a0fe82b9c1fc385a5",
-                "sha256:4465124ef1b18d9ace298060f4eccc64b0850899ac4ac53294547536533800c8",
-                "sha256:49d4cdd9065b9b6e206d0595fee27a96b5dd22618e7520c33204a4a3239d5b10",
-                "sha256:4e0583d24c881e14342eaf4ec5fbc97f934b999a6828693a99157fde912540cc",
-                "sha256:5accb17103e43963b80e6f837831f38d314a0495500067cb25afab2e8d7a4018",
-                "sha256:607774cbba28732bfa802b54baa7484215f530991055bb562efbed5b2f20a45e",
-                "sha256:6c78645d400265a062508ae399b60b8c167bf003db364ecb26dcab2bda048253",
-                "sha256:72a01f726a9c7851ca9bfad6fd09ca4e090a023c00945ea05ba1638c09dc3347",
-                "sha256:74c1485f7707cf707a7aef42ef6322b8f97921bd89be2ab6317fd782c2d53183",
-                "sha256:895f61ef02e8fed38159bb70f7e100e00f471eae2bc838cd0f4ebb21e28f8541",
-                "sha256:8c1be557ee92a20f184922c7b6424e8ab6691788e6d86137c5d93c1a6ec1b8fb",
-                "sha256:bb4191dfc9306777bc594117aee052446b3fa88737cd13b7188d0e7aa8162185",
-                "sha256:bfb51918d4ff3d77c1c856a9699f8492c612cde32fd3bcd344af9be34999bfdc",
-                "sha256:c20cfa2d49991c8b4147af39859b167664f2ad4561704ee74c1de03318e898db",
-                "sha256:cb333c16912324fd5f769fff6bc5de372e9e7a202247b48870bc251ed40239aa",
-                "sha256:d2d9808ea7b4af864f35ea216be506ecec180628aced0704e34aca0b040ffe46",
-                "sha256:d483ad4e639292c90170eb6f7783ad19490e7a8defb3e46f97dfe4bacae89122",
-                "sha256:dd5de0646207f053eb0d6c74ae45ba98c3395a571a2891858e87df7c9b9bd51b",
-                "sha256:e1d4970ea66be07ae37a3c2e48b5ec63f7ba6804bdddfdbd3cfd954d25a82e63",
-                "sha256:e4fac90784481d221a8e4b1162afa7c47ed953be40d31ab4629ae917510051df",
-                "sha256:fa5ae20527d8e831e8230cbffd9f8fe952815b2b7dae6ffec25318803a7528fc",
-                "sha256:fd7f6999a8070df521b6384004ef42833b9bd62cfee11a09bda1079b4b704247",
-                "sha256:fdc842473cd33f45ff6bce46aea678a54e3d21f1b61a7750ce3c498eedfe25d6",
-                "sha256:fe69978f3f768926cfa37b867e3843918e012cf83f680806599ddce33c2c68b0"
+                "sha256:0283c35a6a9fbf047493e3a0ce8d79ef5030852c51e9d911a27badfde0605293",
+                "sha256:055d937d65826939cb044fc8c9b08889e8c743fdc6a32b33e2390f66013e449b",
+                "sha256:07751360502caac1c067a8132d150cf3d61339af5691fe9e87803040dbc5db57",
+                "sha256:0b4624f379dab24d3725ffde76559cff63d9ec94e1736b556dacdfebe5ab6d4b",
+                "sha256:0ce82d761c532fe4ec3f87fc45688bdd3a4c1dc5e0b4a19814b9009a29baefd4",
+                "sha256:1e4747bc279b4f613a09eb64bba2ba602d8a6664c6ce6396a4d0cd413a50ce07",
+                "sha256:213c60cd50106436cc818accf5baa1aba61c0189ff610f64f4a3e8c6726218ba",
+                "sha256:231710d57adfd809ef5d34183b8ed1eeae3f76459c18fb4a0b373ad56bedcdd9",
+                "sha256:277a0ef2981ca40581a47093e9e2d13b3f1fbbeffae064c1d21bfceba2030287",
+                "sha256:2cd5df3de48857ed0544b34e2d40e9fac445930039f3cfe4bcc592a1f836d513",
+                "sha256:40527857252b61eacd1d9af500c3337ba8deb8fc298940291486c465c8b46ec0",
+                "sha256:473f9edb243cb1935ab5a084eb238d842fb8f404ed2193a915d1784b5a6b5fc0",
+                "sha256:48c346915c114f5fdb3ead70312bd042a953a8ce5c7106d5bfb1a5254e47da92",
+                "sha256:50602afada6d6cbfad699b0c7bb50d5ccffa7e46a3d738092afddc1f9758427f",
+                "sha256:68fb519c14306fec9720a2a5b45bc9f0c8d1b9c72adf45c37baedfcd949c35a2",
+                "sha256:77f396e6ef4c73fdc33a9157446466f1cff553d979bd00ecb64385760c6babdc",
+                "sha256:819b3830a1543db06c4d4b865e70ded25be52a2e0631ccd2f6a47a2822f2fd7c",
+                "sha256:897b80890765f037df3403d22bab41627ca8811ae55e9a722fd0392850ec4d86",
+                "sha256:98c4d36e99714e55cfbaaee6dd5badbc9a1ec339ebfc3b1f52e293aee6bb71a4",
+                "sha256:9df7ed3b3d2e0ecfe09e14741b857df43adb5a3ddadc919a2d94fbdf78fea53c",
+                "sha256:9fa600030013c4de8165339db93d182b9431076eb98eb40ee068700c9c813e34",
+                "sha256:a80a78046a72361de73f8f395f1f1e49f956c6be882eed58505a15f3e430962b",
+                "sha256:b3d267842bf12586ba6c734f89d1f5b871df0273157918b0ccefa29deb05c21c",
+                "sha256:b5b9eccad747aabaaffbc6064800670f0c297e52c12754eb1d976c57e4f74dcb",
+                "sha256:c5687b8d43cf58545ade1fe3e055f70eac7a5a1a0bf42824308d868289a95737",
+                "sha256:cba8c411ef271aa037d7357a2bc8f9ee8b58b9965831d9e51baf703280dc73d3",
+                "sha256:d15a181d1ecd0d4270dc32edb46f7cb7733c7c508857278d3d378d14d606db2d",
+                "sha256:d4db7c7aef085872ef65a8fd7d6d09a14ae91f691dec3e87ee5ee0539d516f53",
+                "sha256:d4eccecf9adf6fbcc6861a38015c2a64f38b9d94838ac1810a9023a0609e1b78",
+                "sha256:d67d839ede4ed1b28a4e8909735fc992a923cdb84e618544973d7dfc71540803",
+                "sha256:daf496c58a8c52083df09b80c860005194014c3698698d1a57cbcfa182142a3a",
+                "sha256:e61ceaab6f49fb8bdfaa0f92c4b57bcfbea54c09277b1b4f7ac376bfb7a7c174",
+                "sha256:f84fbc98b019fef2ee9a1cb3ce93e3187a6df0b2538a651bfb890254ba9f90b5"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4, 3.5'",
-            "version": "==5.4.1"
+            "markers": "python_version >= '3.6'",
+            "version": "==6.0"
         },
         "readme-renderer": {
             "hashes": [
-                "sha256:63b4075c6698fcfa78e584930f07f39e05d46f3ec97f65006e430b595ca6348c",
-                "sha256:92fd5ac2bf8677f310f3303aa4bce5b9d5f9f2094ab98c29f13791d7b805a3db"
+                "sha256:3286806450d9961d6e3b5f8a59f77e61503799aca5155c8d8d40359b4e1e1adc",
+                "sha256:8299700d7a910c304072a7601eafada6712a5b011a20139417e1b1e9f04645d8"
             ],
             "index": "pypi",
-            "version": "==29.0"
+            "version": "==30.0"
         },
         "regex": {
             "hashes": [
-                "sha256:03840a07a402576b8e3a6261f17eb88abd653ad4e18ec46ef10c9a63f8c99ebd",
-                "sha256:06ba444bbf7ede3890a912bd4904bb65bf0da8f0d8808b90545481362c978642",
-                "sha256:1f9974826aeeda32a76648fc677e3125ade379869a84aa964b683984a2dea9f1",
-                "sha256:330836ad89ff0be756b58758878409f591d4737b6a8cef26a162e2a4961c3321",
-                "sha256:38600fd58c2996829480de7d034fb2d3a0307110e44dae80b6b4f9b3d2eea529",
-                "sha256:3a195e26df1fbb40ebee75865f9b64ba692a5824ecb91c078cc665b01f7a9a36",
-                "sha256:41acdd6d64cd56f857e271009966c2ffcbd07ec9149ca91f71088574eaa4278a",
-                "sha256:45f97ade892ace20252e5ccecdd7515c7df5feeb42c3d2a8b8c55920c3551c30",
-                "sha256:4b0c211c55d4aac4309c3209833c803fada3fc21cdf7b74abedda42a0c9dc3ce",
-                "sha256:5d5209c3ba25864b1a57461526ebde31483db295fc6195fdfc4f8355e10f7376",
-                "sha256:615fb5a524cffc91ab4490b69e10ae76c1ccbfa3383ea2fad72e54a85c7d47dd",
-                "sha256:61e734c2bcb3742c3f454dfa930ea60ea08f56fd1a0eb52d8cb189a2f6be9586",
-                "sha256:640ccca4d0a6fcc6590f005ecd7b16c3d8f5d52174e4854f96b16f34c39d6cb7",
-                "sha256:6dbd51c3db300ce9d3171f4106da18fe49e7045232630fe3d4c6e37cb2b39ab9",
-                "sha256:71a904da8c9c02aee581f4452a5a988c3003207cb8033db426f29e5b2c0b7aea",
-                "sha256:8021dee64899f993f4b5cca323aae65aabc01a546ed44356a0965e29d7893c94",
-                "sha256:8b8d551f1bd60b3e1c59ff55b9e8d74607a5308f66e2916948cafd13480b44a3",
-                "sha256:93f9f720081d97acee38a411e861d4ce84cbc8ea5319bc1f8e38c972c47af49f",
-                "sha256:96f0c79a70642dfdf7e6a018ebcbea7ea5205e27d8e019cad442d2acfc9af267",
-                "sha256:9966337353e436e6ba652814b0a957a517feb492a98b8f9d3b6ba76d22301dcc",
-                "sha256:a34ba9e39f8269fd66ab4f7a802794ffea6d6ac500568ec05b327a862c21ce23",
-                "sha256:a49f85f0a099a5755d0a2cc6fc337e3cb945ad6390ec892332c691ab0a045882",
-                "sha256:a795829dc522227265d72b25d6ee6f6d41eb2105c15912c230097c8f5bfdbcdc",
-                "sha256:a89ca4105f8099de349d139d1090bad387fe2b208b717b288699ca26f179acbe",
-                "sha256:ac95101736239260189f426b1e361dc1b704513963357dc474beb0f39f5b7759",
-                "sha256:ae87ab669431f611c56e581679db33b9a467f87d7bf197ac384e71e4956b4456",
-                "sha256:b091dcfee169ad8de21b61eb2c3a75f9f0f859f851f64fdaf9320759a3244239",
-                "sha256:b511c6009d50d5c0dd0bab85ed25bc8ad6b6f5611de3a63a59786207e82824bb",
-                "sha256:b79dc2b2e313565416c1e62807c7c25c67a6ff0a0f8d83a318df464555b65948",
-                "sha256:bca14dfcfd9aae06d7d8d7e105539bd77d39d06caaae57a1ce945670bae744e0",
-                "sha256:c835c30f3af5c63a80917b72115e1defb83de99c73bc727bddd979a3b449e183",
-                "sha256:ccd721f1d4fc42b541b633d6e339018a08dd0290dc67269df79552843a06ca92",
-                "sha256:d6c2b1d78ceceb6741d703508cd0e9197b34f6bf6864dab30f940f8886e04ade",
-                "sha256:d6ec4ae13760ceda023b2e5ef1f9bc0b21e4b0830458db143794a117fdbdc044",
-                "sha256:d8b623fc429a38a881ab2d9a56ef30e8ea20c72a891c193f5ebbddc016e083ee",
-                "sha256:ea9753d64cba6f226947c318a923dadaf1e21cd8db02f71652405263daa1f033",
-                "sha256:ebbceefbffae118ab954d3cd6bf718f5790db66152f95202ebc231d58ad4e2c2",
-                "sha256:ecb6e7c45f9cd199c10ec35262b53b2247fb9a408803ed00ee5bb2b54aa626f5",
-                "sha256:ef9326c64349e2d718373415814e754183057ebc092261387a2c2f732d9172b2",
-                "sha256:f93a9d8804f4cec9da6c26c8cfae2c777028b4fdd9f49de0302e26e00bb86504",
-                "sha256:faf08b0341828f6a29b8f7dd94d5cf8cc7c39bfc3e67b78514c54b494b66915a"
+                "sha256:05b7d6d7e64efe309972adab77fc2af8907bb93217ec60aa9fe12a0dad35874f",
+                "sha256:0617383e2fe465732af4509e61648b77cbe3aee68b6ac8c0b6fe934db90be5cc",
+                "sha256:07856afef5ffcc052e7eccf3213317fbb94e4a5cd8177a2caa69c980657b3cb4",
+                "sha256:162abfd74e88001d20cb73ceaffbfe601469923e875caf9118333b1a4aaafdc4",
+                "sha256:2207ae4f64ad3af399e2d30dde66f0b36ae5c3129b52885f1bffc2f05ec505c8",
+                "sha256:30ab804ea73972049b7a2a5c62d97687d69b5a60a67adca07eb73a0ddbc9e29f",
+                "sha256:3b5df18db1fccd66de15aa59c41e4f853b5df7550723d26aa6cb7f40e5d9da5a",
+                "sha256:3c5fb32cc6077abad3bbf0323067636d93307c9fa93e072771cf9a64d1c0f3ef",
+                "sha256:416c5f1a188c91e3eb41e9c8787288e707f7d2ebe66e0a6563af280d9b68478f",
+                "sha256:432bd15d40ed835a51617521d60d0125867f7b88acf653e4ed994a1f8e4995dc",
+                "sha256:4aaa4e0705ef2b73dd8e36eeb4c868f80f8393f5f4d855e94025ce7ad8525f50",
+                "sha256:537ca6a3586931b16a85ac38c08cc48f10fc870a5b25e51794c74df843e9966d",
+                "sha256:53db2c6be8a2710b359bfd3d3aa17ba38f8aa72a82309a12ae99d3c0c3dcd74d",
+                "sha256:5537f71b6d646f7f5f340562ec4c77b6e1c915f8baae822ea0b7e46c1f09b733",
+                "sha256:6650f16365f1924d6014d2ea770bde8555b4a39dc9576abb95e3cd1ff0263b36",
+                "sha256:666abff54e474d28ff42756d94544cdfd42e2ee97065857413b72e8a2d6a6345",
+                "sha256:68a067c11463de2a37157930d8b153005085e42bcb7ad9ca562d77ba7d1404e0",
+                "sha256:780b48456a0f0ba4d390e8b5f7c661fdd218934388cde1a974010a965e200e12",
+                "sha256:788aef3549f1924d5c38263104dae7395bf020a42776d5ec5ea2b0d3d85d6646",
+                "sha256:7ee1227cf08b6716c85504aebc49ac827eb88fcc6e51564f010f11a406c0a667",
+                "sha256:7f301b11b9d214f83ddaf689181051e7f48905568b0c7017c04c06dfd065e244",
+                "sha256:83ee89483672b11f8952b158640d0c0ff02dc43d9cb1b70c1564b49abe92ce29",
+                "sha256:85bfa6a5413be0ee6c5c4a663668a2cad2cbecdee367630d097d7823041bdeec",
+                "sha256:9345b6f7ee578bad8e475129ed40123d265464c4cfead6c261fd60fc9de00bcf",
+                "sha256:93a5051fcf5fad72de73b96f07d30bc29665697fb8ecdfbc474f3452c78adcf4",
+                "sha256:962b9a917dd7ceacbe5cd424556914cb0d636001e393b43dc886ba31d2a1e449",
+                "sha256:98ba568e8ae26beb726aeea2273053c717641933836568c2a0278a84987b2a1a",
+                "sha256:a3feefd5e95871872673b08636f96b61ebef62971eab044f5124fb4dea39919d",
+                "sha256:b43c2b8a330a490daaef5a47ab114935002b13b3f9dc5da56d5322ff218eeadb",
+                "sha256:b483c9d00a565633c87abd0aaf27eb5016de23fed952e054ecc19ce32f6a9e7e",
+                "sha256:ba05430e819e58544e840a68b03b28b6d328aff2e41579037e8bab7653b37d83",
+                "sha256:ca5f18a75e1256ce07494e245cdb146f5a9267d3c702ebf9b65c7f8bd843431e",
+                "sha256:d5ca078bb666c4a9d1287a379fe617a6dccd18c3e8a7e6c7e1eb8974330c626a",
+                "sha256:da1a90c1ddb7531b1d5ff1e171b4ee61f6345119be7351104b67ff413843fe94",
+                "sha256:dba70f30fd81f8ce6d32ddeef37d91c8948e5d5a4c63242d16a2b2df8143aafc",
+                "sha256:dd33eb9bdcfbabab3459c9ee651d94c842bc8a05fabc95edf4ee0c15a072495e",
+                "sha256:e0538c43565ee6e703d3a7c3bdfe4037a5209250e8502c98f20fea6f5fdf2965",
+                "sha256:e1f54b9b4b6c53369f40028d2dd07a8c374583417ee6ec0ea304e710a20f80a0",
+                "sha256:e32d2a2b02ccbef10145df9135751abea1f9f076e67a4e261b05f24b94219e36",
+                "sha256:e71255ba42567d34a13c03968736c5d39bb4a97ce98188fafb27ce981115beec",
+                "sha256:ed2e07c6a26ed4bea91b897ee2b0835c21716d9a469a96c3e878dc5f8c55bb23",
+                "sha256:eef2afb0fd1747f33f1ee3e209bce1ed582d1896b240ccc5e2697e3275f037c7",
+                "sha256:f23222527b307970e383433daec128d769ff778d9b29343fb3496472dc20dabe",
+                "sha256:f341ee2df0999bfdf7a95e448075effe0db212a59387de1a70690e4acb03d4c6",
+                "sha256:f7f325be2804246a75a4f45c72d4ce80d2443ab815063cdf70ee8fb2ca59ee1b",
+                "sha256:f8af619e3be812a2059b212064ea7a640aff0568d972cd1b9e920837469eb3cb",
+                "sha256:fa8c626d6441e2d04b6ee703ef2d1e17608ad44c7cb75258c09dd42bacdfc64b",
+                "sha256:fbb9dc00e39f3e6c0ef48edee202f9520dafb233e8b51b06b8428cfcb92abd30",
+                "sha256:fff55f3ce50a3ff63ec8e2a8d3dd924f1941b250b0aac3d3d42b687eeff07a8e"
             ],
             "index": "pypi",
-            "version": "==2021.8.21"
+            "version": "==2021.11.10"
         },
         "requests": {
             "hashes": [
@@ -1297,23 +1693,31 @@
             "markers": "sys_platform == 'linux'",
             "version": "==3.3.1"
         },
+        "setuptools": {
+            "hashes": [
+                "sha256:a481fbc56b33f5d8f6b33dce41482e64c68b668be44ff42922903b03872590bf",
+                "sha256:dae6b934a965c8a59d6d230d3867ec408bb95e73bd538ff77e71fedf1eaca729"
+            ],
+            "markers": "python_version >= '3.6'",
+            "version": "==58.5.3"
+        },
         "setuptools-scm": {
             "extras": [
                 "toml"
             ],
             "hashes": [
-                "sha256:c3bd5f701c8def44a5c0bfe8d407bef3f80342217ef3492b951f3777bd2d915c",
-                "sha256:d1925a69cb07e9b29416a275b9fadb009a23c148ace905b2fb220649a6c18e92"
+                "sha256:4c64444b1d49c4063ae60bfe1680f611c8b13833d556fd1d6050c0023162a119",
+                "sha256:a49aa8081eeb3514eb9728fa5040f2eaa962d6c6f4ec9c32f6c1fba88f88a0f2"
             ],
             "markers": "python_version >= '3.6'",
-            "version": "==6.0.1"
+            "version": "==6.3.2"
         },
         "six": {
             "hashes": [
                 "sha256:1e61c37477a1626458e36f7b1d82aa5c9b094fa4802892072e49de9c60c4c926",
                 "sha256:8abb2f1d86890a2dfb989f9a77cfcfd3e47c2a354b01111771326f8aa26e0254"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2'",
             "version": "==1.16.0"
         },
         "snowballstemmer": {
@@ -1325,11 +1729,11 @@
         },
         "sphinx": {
             "hashes": [
-                "sha256:3092d929cd807926d846018f2ace47ba2f3b671b309c7a89cd3306e80c826b13",
-                "sha256:46d52c6cee13fec44744b8c01ed692c18a640f6910a725cbb938bc36e8d64544"
+                "sha256:6d051ab6e0d06cba786c4656b0fe67ba259fe058410f49e95bee6e49c4052cbf",
+                "sha256:7e2b30da5f39170efcd95c6270f07669d623c276521fee27ad6c380f49d2bf5b"
             ],
             "index": "pypi",
-            "version": "==4.1.2"
+            "version": "==4.3.0"
         },
         "sphinx-copybutton": {
             "hashes": [
@@ -1397,43 +1801,43 @@
         },
         "tokenize-rt": {
             "hashes": [
-                "sha256:ab339b5ff829eb5e198590477f9c03c84e762b3e455e74c018956e7e326cbc70",
-                "sha256:b37251fa28c21e8cce2e42f7769a35fba2dd2ecafb297208f9a9a8add3ca7793"
+                "sha256:08a27fa032a81cf45e8858d0ac706004fcd523e8463415ddf1442be38e204ea8",
+                "sha256:0d4f69026fed520f8a1e0103aa36c406ef4661417f20ca643f913e33531b3b94"
             ],
             "markers": "python_full_version >= '3.6.1'",
-            "version": "==4.1.0"
+            "version": "==4.2.1"
         },
         "toml": {
             "hashes": [
                 "sha256:806143ae5bfb6a3c6e736a764057db0e6a0e05e338b5630894a5f779cabb4f9b",
                 "sha256:b3bda1d108d5dd99f4a20d24d9c348e91c4db7ab1b749200bded2f839ccbe68f"
             ],
-            "markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2, 3.3'",
+            "markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2'",
             "version": "==0.10.2"
         },
         "tomli": {
             "hashes": [
-                "sha256:8dd0e9524d6f386271a36b41dbf6c57d8e32fd96fd22b6584679dc569d20899f",
-                "sha256:a5b75cb6f3968abb47af1b40c1819dc519ea82bcc065776a866e8d74c5ca9442"
+                "sha256:c6ce0015eb38820eaf32b5db832dbc26deb3dd427bd5f6556cf0acac2c214fee",
+                "sha256:f04066f68f5554911363063a30b108d2b5a5b1a010aa8b6132af78489fe3aade"
             ],
             "index": "pypi",
-            "version": "==1.2.1"
+            "version": "==1.2.2"
         },
         "tox": {
             "hashes": [
-                "sha256:9fbf8e2ab758b2a5e7cb2c72945e4728089934853076f67ef18d7575c8ab6b88",
-                "sha256:c6c4e77705ada004283610fd6d9ba4f77bc85d235447f875df9f0ba1bc23b634"
+                "sha256:5e274227a53dc9ef856767c21867377ba395992549f02ce55eb549f9fb9a8d10",
+                "sha256:c30b57fa2477f1fb7c36aa1d83292d5c2336cd0018119e1b1c17340e2c2708ca"
             ],
             "index": "pypi",
-            "version": "==3.24.3"
+            "version": "==3.24.4"
         },
         "tqdm": {
             "hashes": [
-                "sha256:07856e19a1fe4d2d9621b539d3f072fa88c9c1ef1f3b7dd4d4953383134c3164",
-                "sha256:35540feeaca9ac40c304e916729e6b78045cbbeccd3e941b2868f09306798ac9"
+                "sha256:8dd278a422499cd6b727e6ae4061c40b48fce8b76d1ccbf5d34fca9b7f925b0c",
+                "sha256:d359de7217506c9851b7869f3708d8ee53ed70a1b8edbba4dbcb47442592920d"
             ],
             "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==4.62.1"
+            "version": "==4.62.3"
         },
         "traitlets": {
             "hashes": [
@@ -1444,97 +1848,97 @@
         },
         "twine": {
             "hashes": [
-                "sha256:087328e9bb405e7ce18527a2dca4042a84c7918658f951110b38bc135acab218",
-                "sha256:4caec0f1ed78dc4c9b83ad537e453d03ce485725f2aea57f1bb3fdde78dae936"
+                "sha256:4caad5ef4722e127b3749052fcbffaaf71719b19d4fd4973b29c469957adeba2",
+                "sha256:916070f8ecbd1985ebed5dbb02b9bda9a092882a96d7069d542d4fc0bb5c673c"
             ],
             "index": "pypi",
-            "version": "==3.4.2"
+            "version": "==3.6.0"
         },
         "typed-ast": {
             "hashes": [
-                "sha256:07d49388d5bf7e863f7fa2f124b1b1d89d8aa0e2f7812faff0a5658c01c59aa1",
-                "sha256:14bf1522cdee369e8f5581238edac09150c765ec1cb33615855889cf33dcb92d",
-                "sha256:240296b27397e4e37874abb1df2a608a92df85cf3e2a04d0d4d61055c8305ba6",
-                "sha256:36d829b31ab67d6fcb30e185ec996e1f72b892255a745d3a82138c97d21ed1cd",
-                "sha256:37f48d46d733d57cc70fd5f30572d11ab8ed92da6e6b28e024e4a3edfb456e37",
-                "sha256:4c790331247081ea7c632a76d5b2a265e6d325ecd3179d06e9cf8d46d90dd151",
-                "sha256:5dcfc2e264bd8a1db8b11a892bd1647154ce03eeba94b461effe68790d8b8e07",
-                "sha256:7147e2a76c75f0f64c4319886e7639e490fee87c9d25cb1d4faef1d8cf83a440",
-                "sha256:7703620125e4fb79b64aa52427ec192822e9f45d37d4b6625ab37ef403e1df70",
-                "sha256:8368f83e93c7156ccd40e49a783a6a6850ca25b556c0fa0240ed0f659d2fe496",
-                "sha256:84aa6223d71012c68d577c83f4e7db50d11d6b1399a9c779046d75e24bed74ea",
-                "sha256:85f95aa97a35bdb2f2f7d10ec5bbdac0aeb9dafdaf88e17492da0504de2e6400",
-                "sha256:8db0e856712f79c45956da0c9a40ca4246abc3485ae0d7ecc86a20f5e4c09abc",
-                "sha256:9044ef2df88d7f33692ae3f18d3be63dec69c4fb1b5a4a9ac950f9b4ba571606",
-                "sha256:963c80b583b0661918718b095e02303d8078950b26cc00b5e5ea9ababe0de1fc",
-                "sha256:987f15737aba2ab5f3928c617ccf1ce412e2e321c77ab16ca5a293e7bbffd581",
-                "sha256:9ec45db0c766f196ae629e509f059ff05fc3148f9ffd28f3cfe75d4afb485412",
-                "sha256:9fc0b3cb5d1720e7141d103cf4819aea239f7d136acf9ee4a69b047b7986175a",
-                "sha256:a2c927c49f2029291fbabd673d51a2180038f8cd5a5b2f290f78c4516be48be2",
-                "sha256:a38878a223bdd37c9709d07cd357bb79f4c760b29210e14ad0fb395294583787",
-                "sha256:b4fcdcfa302538f70929eb7b392f536a237cbe2ed9cba88e3bf5027b39f5f77f",
-                "sha256:c0c74e5579af4b977c8b932f40a5464764b2f86681327410aa028a22d2f54937",
-                "sha256:c1c876fd795b36126f773db9cbb393f19808edd2637e00fd6caba0e25f2c7b64",
-                "sha256:c9aadc4924d4b5799112837b226160428524a9a45f830e0d0f184b19e4090487",
-                "sha256:cc7b98bf58167b7f2db91a4327da24fb93368838eb84a44c472283778fc2446b",
-                "sha256:cf54cfa843f297991b7388c281cb3855d911137223c6b6d2dd82a47ae5125a41",
-                "sha256:d003156bb6a59cda9050e983441b7fa2487f7800d76bdc065566b7d728b4581a",
-                "sha256:d175297e9533d8d37437abc14e8a83cbc68af93cc9c1c59c2c292ec59a0697a3",
-                "sha256:d746a437cdbca200622385305aedd9aef68e8a645e385cc483bdc5e488f07166",
-                "sha256:e683e409e5c45d5c9082dc1daf13f6374300806240719f95dc783d1fc942af10"
+                "sha256:01ae5f73431d21eead5015997ab41afa53aa1fbe252f9da060be5dad2c730ace",
+                "sha256:067a74454df670dcaa4e59349a2e5c81e567d8d65458d480a5b3dfecec08c5ff",
+                "sha256:0fb71b8c643187d7492c1f8352f2c15b4c4af3f6338f21681d3681b3dc31a266",
+                "sha256:1b3ead4a96c9101bef08f9f7d1217c096f31667617b58de957f690c92378b528",
+                "sha256:2068531575a125b87a41802130fa7e29f26c09a2833fea68d9a40cf33902eba6",
+                "sha256:209596a4ec71d990d71d5e0d312ac935d86930e6eecff6ccc7007fe54d703808",
+                "sha256:2c726c276d09fc5c414693a2de063f521052d9ea7c240ce553316f70656c84d4",
+                "sha256:398e44cd480f4d2b7ee8d98385ca104e35c81525dd98c519acff1b79bdaac363",
+                "sha256:52b1eb8c83f178ab787f3a4283f68258525f8d70f778a2f6dd54d3b5e5fb4341",
+                "sha256:5feca99c17af94057417d744607b82dd0a664fd5e4ca98061480fd8b14b18d04",
+                "sha256:7538e495704e2ccda9b234b82423a4038f324f3a10c43bc088a1636180f11a41",
+                "sha256:760ad187b1041a154f0e4d0f6aae3e40fdb51d6de16e5c99aedadd9246450e9e",
+                "sha256:777a26c84bea6cd934422ac2e3b78863a37017618b6e5c08f92ef69853e765d3",
+                "sha256:95431a26309a21874005845c21118c83991c63ea800dd44843e42a916aec5899",
+                "sha256:9ad2c92ec681e02baf81fdfa056fe0d818645efa9af1f1cd5fd6f1bd2bdfd805",
+                "sha256:9c6d1a54552b5330bc657b7ef0eae25d00ba7ffe85d9ea8ae6540d2197a3788c",
+                "sha256:aee0c1256be6c07bd3e1263ff920c325b59849dc95392a05f258bb9b259cf39c",
+                "sha256:af3d4a73793725138d6b334d9d247ce7e5f084d96284ed23f22ee626a7b88e39",
+                "sha256:b36b4f3920103a25e1d5d024d155c504080959582b928e91cb608a65c3a49e1a",
+                "sha256:b9574c6f03f685070d859e75c7f9eeca02d6933273b5e69572e5ff9d5e3931c3",
+                "sha256:bff6ad71c81b3bba8fa35f0f1921fb24ff4476235a6e94a26ada2e54370e6da7",
+                "sha256:c190f0899e9f9f8b6b7863debfb739abcb21a5c054f911ca3596d12b8a4c4c7f",
+                "sha256:c907f561b1e83e93fad565bac5ba9c22d96a54e7ea0267c708bffe863cbe4075",
+                "sha256:cae53c389825d3b46fb37538441f75d6aecc4174f615d048321b716df2757fb0",
+                "sha256:dd4a21253f42b8d2b48410cb31fe501d32f8b9fbeb1f55063ad102fe9c425e40",
+                "sha256:dde816ca9dac1d9c01dd504ea5967821606f02e510438120091b84e852367428",
+                "sha256:f2362f3cb0f3172c42938946dbc5b7843c2a28aec307c49100c8b38764eb6927",
+                "sha256:f328adcfebed9f11301eaedfa48e15bdece9b519fb27e6a8c01aa52a17ec31b3",
+                "sha256:f8afcf15cc511ada719a88e013cec87c11aff7b91f019295eb4530f96fe5ef2f",
+                "sha256:fb1bbeac803adea29cedd70781399c99138358c26d05fcbd23c13016b7f5ec65"
             ],
             "index": "pypi",
             "version": "==1.4.3"
         },
         "types-dataclasses": {
             "hashes": [
-                "sha256:248075d093d8f7c1541ce515594df7ae40233d1340afde11ce7125368c5209b8",
-                "sha256:fc372bb68b878ac7a68fd04230d923d4a6303a137ecb0b9700b90630bdfcbfc9"
+                "sha256:6568532fed11f854e4db2eb48063385b323b93ecadd09f10a215d56246c306d7",
+                "sha256:aa45bb0dacdba09e3195a36ff8337bba45eac03b6f31c4645e87b4a2a47830dd"
             ],
             "index": "pypi",
-            "version": "==0.1.7"
+            "version": "==0.6.1"
         },
         "types-pyyaml": {
             "hashes": [
-                "sha256:745dcb4b1522423026bcc83abb9925fba747f1e8602d902f71a4058f9e7fb662",
-                "sha256:96f8d3d96aa1a18a465e8f6a220e02cff2f52632314845a364ecbacb0aea6e30"
+                "sha256:2e27b0118ca4248a646101c5c318dc02e4ca2866d6bc42e84045dbb851555a76",
+                "sha256:d5b318269652e809b5c30a5fe666c50159ab80bfd41cd6bafe655bf20b29fcba"
             ],
             "index": "pypi",
-            "version": "==5.4.6"
+            "version": "==6.0.1"
         },
         "types-typed-ast": {
             "hashes": [
-                "sha256:b7f561796b4d002c7522b0020f58b18f715bd28a31429d424a78e2e2dbbd6785",
-                "sha256:ffa0471e0ba19c4ea0cba0436d660871b5f5215854ea9ead3cb5b60f525af75a"
+                "sha256:4a261b6af545af41fd08957993292742959ca5c480ee8d49804dcc68d78773a3",
+                "sha256:d8ea79cbfbc520be8d9bc8de4872f44b342dbdbc091667e2f21b03bbd7969150"
             ],
             "index": "pypi",
-            "version": "==1.4.4"
+            "version": "==1.5.0"
         },
         "typing-extensions": {
             "hashes": [
-                "sha256:0ac0f89795dd19de6b97debb0c6af1c70987fd80a2d62d1958f7e56fcc31b497",
-                "sha256:50b6f157849174217d0656f99dc82fe932884fb250826c18350e159ec6cdf342",
-                "sha256:779383f6086d90c99ae41cf0ff39aac8a7937a9283ce0a414e5dd782f4c94a84"
+                "sha256:49f75d16ff11f1cd258e1b988ccff82a3ca5570217d7ad8c5f48205dd99a677e",
+                "sha256:d8226d10bc02a29bcc81df19a26e56a9647f8b0a6d4a83924139f4a8b01f17b7",
+                "sha256:f1d25edafde516b146ecd0613dabcc61409817af4766fbbcfb8d1ad4ec441a34"
             ],
             "index": "pypi",
             "markers": "python_version < '3.10'",
-            "version": "==3.10.0.0"
+            "version": "==3.10.0.2"
         },
         "urllib3": {
             "hashes": [
-                "sha256:39fb8672126159acb139a7718dd10806104dec1e2f0f6c88aab05d17df10c8d4",
-                "sha256:f57b4c16c62fa2760b7e3d97c35b255512fb6b59a259730f36ba32ce9f8e342f"
+                "sha256:4987c65554f7a2dbf30c18fd48778ef124af6fab771a377103da0585e2336ece",
+                "sha256:c4fdf4019605b6e5423637e01bc9fe4daef873709a7973e195ceba0a62bbc844"
             ],
             "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4' and python_version < '4'",
-            "version": "==1.26.6"
+            "version": "==1.26.7"
         },
         "virtualenv": {
             "hashes": [
-                "sha256:9ef4e8ee4710826e98ff3075c9a4739e2cb1040de6a2a8d35db0055840dc96a0",
-                "sha256:e4670891b3a03eb071748c569a87cceaefbf643c5bac46d996c5a45c34aa0f06"
+                "sha256:4b02e52a624336eece99c96e3ab7111f469c24ba226a53ec474e8e787b365814",
+                "sha256:576d05b46eace16a9c348085f7d0dc8ef28713a2cabaa1cf0aea41e8f12c9218"
             ],
             "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
-            "version": "==20.7.2"
+            "version": "==20.10.0"
         },
         "wcwidth": {
             "hashes": [
@@ -1560,54 +1964,89 @@
         },
         "yarl": {
             "hashes": [
-                "sha256:00d7ad91b6583602eb9c1d085a2cf281ada267e9a197e8b7cae487dadbfa293e",
-                "sha256:0355a701b3998dcd832d0dc47cc5dedf3874f966ac7f870e0f3a6788d802d434",
-                "sha256:15263c3b0b47968c1d90daa89f21fcc889bb4b1aac5555580d74565de6836366",
-                "sha256:2ce4c621d21326a4a5500c25031e102af589edb50c09b321049e388b3934eec3",
-                "sha256:31ede6e8c4329fb81c86706ba8f6bf661a924b53ba191b27aa5fcee5714d18ec",
-                "sha256:324ba3d3c6fee56e2e0b0d09bf5c73824b9f08234339d2b788af65e60040c959",
-                "sha256:329412812ecfc94a57cd37c9d547579510a9e83c516bc069470db5f75684629e",
-                "sha256:4736eaee5626db8d9cda9eb5282028cc834e2aeb194e0d8b50217d707e98bb5c",
-                "sha256:4953fb0b4fdb7e08b2f3b3be80a00d28c5c8a2056bb066169de00e6501b986b6",
-                "sha256:4c5bcfc3ed226bf6419f7a33982fb4b8ec2e45785a0561eb99274ebbf09fdd6a",
-                "sha256:547f7665ad50fa8563150ed079f8e805e63dd85def6674c97efd78eed6c224a6",
-                "sha256:5b883e458058f8d6099e4420f0cc2567989032b5f34b271c0827de9f1079a424",
-                "sha256:63f90b20ca654b3ecc7a8d62c03ffa46999595f0167d6450fa8383bab252987e",
-                "sha256:68dc568889b1c13f1e4745c96b931cc94fdd0defe92a72c2b8ce01091b22e35f",
-                "sha256:69ee97c71fee1f63d04c945f56d5d726483c4762845400a6795a3b75d56b6c50",
-                "sha256:6d6283d8e0631b617edf0fd726353cb76630b83a089a40933043894e7f6721e2",
-                "sha256:72a660bdd24497e3e84f5519e57a9ee9220b6f3ac4d45056961bf22838ce20cc",
-                "sha256:73494d5b71099ae8cb8754f1df131c11d433b387efab7b51849e7e1e851f07a4",
-                "sha256:7356644cbed76119d0b6bd32ffba704d30d747e0c217109d7979a7bc36c4d970",
-                "sha256:8a9066529240171b68893d60dca86a763eae2139dd42f42106b03cf4b426bf10",
-                "sha256:8aa3decd5e0e852dc68335abf5478a518b41bf2ab2f330fe44916399efedfae0",
-                "sha256:97b5bdc450d63c3ba30a127d018b866ea94e65655efaf889ebeabc20f7d12406",
-                "sha256:9ede61b0854e267fd565e7527e2f2eb3ef8858b301319be0604177690e1a3896",
-                "sha256:b2e9a456c121e26d13c29251f8267541bd75e6a1ccf9e859179701c36a078643",
-                "sha256:b5dfc9a40c198334f4f3f55880ecf910adebdcb2a0b9a9c23c9345faa9185721",
-                "sha256:bafb450deef6861815ed579c7a6113a879a6ef58aed4c3a4be54400ae8871478",
-                "sha256:c49ff66d479d38ab863c50f7bb27dee97c6627c5fe60697de15529da9c3de724",
-                "sha256:ce3beb46a72d9f2190f9e1027886bfc513702d748047b548b05dab7dfb584d2e",
-                "sha256:d26608cf178efb8faa5ff0f2d2e77c208f471c5a3709e577a7b3fd0445703ac8",
-                "sha256:d597767fcd2c3dc49d6eea360c458b65643d1e4dbed91361cf5e36e53c1f8c96",
-                "sha256:d5c32c82990e4ac4d8150fd7652b972216b204de4e83a122546dce571c1bdf25",
-                "sha256:d8d07d102f17b68966e2de0e07bfd6e139c7c02ef06d3a0f8d2f0f055e13bb76",
-                "sha256:e46fba844f4895b36f4c398c5af062a9808d1f26b2999c58909517384d5deda2",
-                "sha256:e6b5460dc5ad42ad2b36cca524491dfcaffbfd9c8df50508bddc354e787b8dc2",
-                "sha256:f040bcc6725c821a4c0665f3aa96a4d0805a7aaf2caf266d256b8ed71b9f041c",
-                "sha256:f0b059678fd549c66b89bed03efcabb009075bd131c248ecdf087bdb6faba24a",
-                "sha256:fcbb48a93e8699eae920f8d92f7160c03567b421bc17362a9ffbbd706a816f71"
+                "sha256:044daf3012e43d4b3538562da94a88fb12a6490652dbc29fb19adfa02cf72eac",
+                "sha256:0cba38120db72123db7c58322fa69e3c0efa933040ffb586c3a87c063ec7cae8",
+                "sha256:167ab7f64e409e9bdd99333fe8c67b5574a1f0495dcfd905bc7454e766729b9e",
+                "sha256:1be4bbb3d27a4e9aa5f3df2ab61e3701ce8fcbd3e9846dbce7c033a7e8136746",
+                "sha256:1ca56f002eaf7998b5fcf73b2421790da9d2586331805f38acd9997743114e98",
+                "sha256:1d3d5ad8ea96bd6d643d80c7b8d5977b4e2fb1bab6c9da7322616fd26203d125",
+                "sha256:1eb6480ef366d75b54c68164094a6a560c247370a68c02dddb11f20c4c6d3c9d",
+                "sha256:1edc172dcca3f11b38a9d5c7505c83c1913c0addc99cd28e993efeaafdfaa18d",
+                "sha256:211fcd65c58bf250fb994b53bc45a442ddc9f441f6fec53e65de8cba48ded986",
+                "sha256:29e0656d5497733dcddc21797da5a2ab990c0cb9719f1f969e58a4abac66234d",
+                "sha256:368bcf400247318382cc150aaa632582d0780b28ee6053cd80268c7e72796dec",
+                "sha256:39d5493c5ecd75c8093fa7700a2fb5c94fe28c839c8e40144b7ab7ccba6938c8",
+                "sha256:3abddf0b8e41445426d29f955b24aeecc83fa1072be1be4e0d194134a7d9baee",
+                "sha256:3bf8cfe8856708ede6a73907bf0501f2dc4e104085e070a41f5d88e7faf237f3",
+                "sha256:3ec1d9a0d7780416e657f1e405ba35ec1ba453a4f1511eb8b9fbab81cb8b3ce1",
+                "sha256:45399b46d60c253327a460e99856752009fcee5f5d3c80b2f7c0cae1c38d56dd",
+                "sha256:52690eb521d690ab041c3919666bea13ab9fbff80d615ec16fa81a297131276b",
+                "sha256:534b047277a9a19d858cde163aba93f3e1677d5acd92f7d10ace419d478540de",
+                "sha256:580c1f15500e137a8c37053e4cbf6058944d4c114701fa59944607505c2fe3a0",
+                "sha256:59218fef177296451b23214c91ea3aba7858b4ae3306dde120224cfe0f7a6ee8",
+                "sha256:5ba63585a89c9885f18331a55d25fe81dc2d82b71311ff8bd378fc8004202ff6",
+                "sha256:5bb7d54b8f61ba6eee541fba4b83d22b8a046b4ef4d8eb7f15a7e35db2e1e245",
+                "sha256:6152224d0a1eb254f97df3997d79dadd8bb2c1a02ef283dbb34b97d4f8492d23",
+                "sha256:67e94028817defe5e705079b10a8438b8cb56e7115fa01640e9c0bb3edf67332",
+                "sha256:695ba021a9e04418507fa930d5f0704edbce47076bdcfeeaba1c83683e5649d1",
+                "sha256:6a1a9fe17621af43e9b9fcea8bd088ba682c8192d744b386ee3c47b56eaabb2c",
+                "sha256:6ab0c3274d0a846840bf6c27d2c60ba771a12e4d7586bf550eefc2df0b56b3b4",
+                "sha256:6feca8b6bfb9eef6ee057628e71e1734caf520a907b6ec0d62839e8293e945c0",
+                "sha256:737e401cd0c493f7e3dd4db72aca11cfe069531c9761b8ea474926936b3c57c8",
+                "sha256:788713c2896f426a4e166b11f4ec538b5736294ebf7d5f654ae445fd44270832",
+                "sha256:797c2c412b04403d2da075fb93c123df35239cd7b4cc4e0cd9e5839b73f52c58",
+                "sha256:8300401dc88cad23f5b4e4c1226f44a5aa696436a4026e456fe0e5d2f7f486e6",
+                "sha256:87f6e082bce21464857ba58b569370e7b547d239ca22248be68ea5d6b51464a1",
+                "sha256:89ccbf58e6a0ab89d487c92a490cb5660d06c3a47ca08872859672f9c511fc52",
+                "sha256:8b0915ee85150963a9504c10de4e4729ae700af11df0dc5550e6587ed7891e92",
+                "sha256:8cce6f9fa3df25f55521fbb5c7e4a736683148bcc0c75b21863789e5185f9185",
+                "sha256:95a1873b6c0dd1c437fb3bb4a4aaa699a48c218ac7ca1e74b0bee0ab16c7d60d",
+                "sha256:9b4c77d92d56a4c5027572752aa35082e40c561eec776048330d2907aead891d",
+                "sha256:9bfcd43c65fbb339dc7086b5315750efa42a34eefad0256ba114cd8ad3896f4b",
+                "sha256:9c1f083e7e71b2dd01f7cd7434a5f88c15213194df38bc29b388ccdf1492b739",
+                "sha256:a1d0894f238763717bdcfea74558c94e3bc34aeacd3351d769460c1a586a8b05",
+                "sha256:a467a431a0817a292121c13cbe637348b546e6ef47ca14a790aa2fa8cc93df63",
+                "sha256:aa32aaa97d8b2ed4e54dc65d241a0da1c627454950f7d7b1f95b13985afd6c5d",
+                "sha256:ac10bbac36cd89eac19f4e51c032ba6b412b3892b685076f4acd2de18ca990aa",
+                "sha256:ac35ccde589ab6a1870a484ed136d49a26bcd06b6a1c6397b1967ca13ceb3913",
+                "sha256:bab827163113177aee910adb1f48ff7af31ee0289f434f7e22d10baf624a6dfe",
+                "sha256:baf81561f2972fb895e7844882898bda1eef4b07b5b385bcd308d2098f1a767b",
+                "sha256:bf19725fec28452474d9887a128e98dd67eee7b7d52e932e6949c532d820dc3b",
+                "sha256:c01a89a44bb672c38f42b49cdb0ad667b116d731b3f4c896f72302ff77d71656",
+                "sha256:c0910c6b6c31359d2f6184828888c983d54d09d581a4a23547a35f1d0b9484b1",
+                "sha256:c10ea1e80a697cf7d80d1ed414b5cb8f1eec07d618f54637067ae3c0334133c4",
+                "sha256:c1164a2eac148d85bbdd23e07dfcc930f2e633220f3eb3c3e2a25f6148c2819e",
+                "sha256:c145ab54702334c42237a6c6c4cc08703b6aa9b94e2f227ceb3d477d20c36c63",
+                "sha256:c17965ff3706beedafd458c452bf15bac693ecd146a60a06a214614dc097a271",
+                "sha256:c19324a1c5399b602f3b6e7db9478e5b1adf5cf58901996fc973fe4fccd73eed",
+                "sha256:c2a1ac41a6aa980db03d098a5531f13985edcb451bcd9d00670b03129922cd0d",
+                "sha256:c6ddcd80d79c96eb19c354d9dca95291589c5954099836b7c8d29278a7ec0bda",
+                "sha256:c9c6d927e098c2d360695f2e9d38870b2e92e0919be07dbe339aefa32a090265",
+                "sha256:cc8b7a7254c0fc3187d43d6cb54b5032d2365efd1df0cd1749c0c4df5f0ad45f",
+                "sha256:cff3ba513db55cc6a35076f32c4cdc27032bd075c9faef31fec749e64b45d26c",
+                "sha256:d260d4dc495c05d6600264a197d9d6f7fc9347f21d2594926202fd08cf89a8ba",
+                "sha256:d6f3d62e16c10e88d2168ba2d065aa374e3c538998ed04996cd373ff2036d64c",
+                "sha256:da6df107b9ccfe52d3a48165e48d72db0eca3e3029b5b8cb4fe6ee3cb870ba8b",
+                "sha256:dfe4b95b7e00c6635a72e2d00b478e8a28bfb122dc76349a06e20792eb53a523",
+                "sha256:e39378894ee6ae9f555ae2de332d513a5763276a9265f8e7cbaeb1b1ee74623a",
+                "sha256:ede3b46cdb719c794427dcce9d8beb4abe8b9aa1e97526cc20de9bd6583ad1ef",
+                "sha256:f2a8508f7350512434e41065684076f640ecce176d262a7d54f0da41d99c5a95",
+                "sha256:f44477ae29025d8ea87ec308539f95963ffdc31a82f42ca9deecf2d505242e72",
+                "sha256:f64394bd7ceef1237cc604b5a89bf748c95982a84bcd3c4bbeb40f685c810794",
+                "sha256:fc4dd8b01a8112809e6b636b00f487846956402834a7fd59d46d4f4267181c41",
+                "sha256:fce78593346c014d0d986b7ebc80d782b7f5e19843ca798ed62f8e3ba8728576",
+                "sha256:fd547ec596d90c8676e369dd8a581a21227fe9b4ad37d0dc7feb4ccf544c2d59"
             ],
             "markers": "python_version >= '3.6'",
-            "version": "==1.6.3"
+            "version": "==1.7.2"
         },
         "zipp": {
             "hashes": [
-                "sha256:957cfda87797e389580cb8b9e3870841ca991e2125350677b2ca83a0e99390a3",
-                "sha256:f5812b1e007e48cff63449a5e9f4e7ebea716b4111f9c4f9a645f91d579bf0c4"
+                "sha256:71c644c5369f4a6e07636f0aa966270449561fcea2e3d6747b8d23efaa9d7832",
+                "sha256:9fe5ea21568a0a70e50f273397638d39b03353731e6cbbb3fd8502a33fec40bc"
             ],
             "markers": "python_version >= '3.6'",
-            "version": "==3.5.0"
+            "version": "==3.6.0"
         }
     }
 }

From 1e0ec543ff3a7de715c8ee3359c8defb2c2c0e0d Mon Sep 17 00:00:00 2001
From: Batuhan Taskaya <isidentical@gmail.com>
Date: Sun, 14 Nov 2021 06:15:31 +0300
Subject: [PATCH 0336/1034] black/parser: partial support for pattern matching
 (#2586)

Partial implementation for #2242. Only works when explicitly stated -t py310.

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 CHANGES.md                                   |   3 +
 src/black/linegen.py                         |   6 +-
 src/black/mode.py                            |   5 +
 src/black/parsing.py                         |   3 +
 src/blib2to3/Grammar.txt                     |  41 +++++-
 src/blib2to3/pgen2/driver.py                 |  81 ++++++++++-
 src/blib2to3/pgen2/grammar.py                |   2 +
 src/blib2to3/pgen2/parse.py                  | 135 +++++++++++++++--
 src/blib2to3/pgen2/pgen.py                   |  11 +-
 src/blib2to3/pygram.py                       |  19 ++-
 tests/data/parenthesized_context_managers.py |  21 +++
 tests/data/pattern_matching_complex.py       | 144 +++++++++++++++++++
 tests/data/pattern_matching_simple.py        |  92 ++++++++++++
 tests/test_format.py                         |  12 ++
 14 files changed, 553 insertions(+), 22 deletions(-)
 create mode 100644 tests/data/parenthesized_context_managers.py
 create mode 100644 tests/data/pattern_matching_complex.py
 create mode 100644 tests/data/pattern_matching_simple.py

diff --git a/CHANGES.md b/CHANGES.md
index 4b8dc57388c..b2e8f7439b7 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -6,6 +6,9 @@
 
 - Warn about Python 2 deprecation in more cases by improving Python 2 only syntax
   detection (#2592)
+- Add partial support for the match statement. As it's experimental, it's only enabled
+  when `--target-version py310` is explicitly specified (#2586)
+- Add support for parenthesized with (#2586)
 
 ## 21.10b0
 
diff --git a/src/black/linegen.py b/src/black/linegen.py
index eb53fa0ac56..8cf32c973bb 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -126,7 +126,7 @@ def visit_stmt(
         """Visit a statement.
 
         This implementation is shared for `if`, `while`, `for`, `try`, `except`,
-        `def`, `with`, `class`, `assert` and assignments.
+        `def`, `with`, `class`, `assert`, `match`, `case` and assignments.
 
         The relevant Python language `keywords` for a given statement will be
         NAME leaves within it. This methods puts those on a separate line.
@@ -292,6 +292,10 @@ def __post_init__(self) -> None:
         self.visit_async_funcdef = self.visit_async_stmt
         self.visit_decorated = self.visit_decorators
 
+        # PEP 634
+        self.visit_match_stmt = partial(v, keywords={"match"}, parens=Ø)
+        self.visit_case_block = partial(v, keywords={"case"}, parens=Ø)
+
 
 def transform_line(
     line: Line, mode: Mode, features: Collection[Feature] = ()
diff --git a/src/black/mode.py b/src/black/mode.py
index 01ee336366c..b24c9c60ded 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -20,6 +20,7 @@ class TargetVersion(Enum):
     PY37 = 7
     PY38 = 8
     PY39 = 9
+    PY310 = 10
 
     def is_python2(self) -> bool:
         return self is TargetVersion.PY27
@@ -39,6 +40,7 @@ class Feature(Enum):
     ASSIGNMENT_EXPRESSIONS = 8
     POS_ONLY_ARGUMENTS = 9
     RELAXED_DECORATORS = 10
+    PATTERN_MATCHING = 11
     FORCE_OPTIONAL_PARENTHESES = 50
 
     # temporary for Python 2 deprecation
@@ -108,6 +110,9 @@ class Feature(Enum):
         Feature.RELAXED_DECORATORS,
         Feature.POS_ONLY_ARGUMENTS,
     },
+    TargetVersion.PY310: {
+        Feature.PATTERN_MATCHING,
+    },
 }
 
 
diff --git a/src/black/parsing.py b/src/black/parsing.py
index 0b8d984cedd..fc540ad021d 100644
--- a/src/black/parsing.py
+++ b/src/black/parsing.py
@@ -59,6 +59,9 @@ def get_grammars(target_versions: Set[TargetVersion]) -> List[Grammar]:
 
     # Python 3-compatible code, so only try Python 3 grammar.
     grammars = []
+    if supports_feature(target_versions, Feature.PATTERN_MATCHING):
+        # Python 3.10+
+        grammars.append(pygram.python_grammar_soft_keywords)
     # If we have to parse both, try to parse async as a keyword first
     if not supports_feature(target_versions, Feature.ASYNC_IDENTIFIERS):
         # Python 3.7+
diff --git a/src/blib2to3/Grammar.txt b/src/blib2to3/Grammar.txt
index ac8a067378d..49680323d8b 100644
--- a/src/blib2to3/Grammar.txt
+++ b/src/blib2to3/Grammar.txt
@@ -105,7 +105,7 @@ global_stmt: ('global' | 'nonlocal') NAME (',' NAME)*
 exec_stmt: 'exec' expr ['in' test [',' test]]
 assert_stmt: 'assert' test [',' test]
 
-compound_stmt: if_stmt | while_stmt | for_stmt | try_stmt | with_stmt | funcdef | classdef | decorated | async_stmt
+compound_stmt: if_stmt | while_stmt | for_stmt | try_stmt | with_stmt | funcdef | classdef | decorated | async_stmt | match_stmt
 async_stmt: ASYNC (funcdef | with_stmt | for_stmt)
 if_stmt: 'if' namedexpr_test ':' suite ('elif' namedexpr_test ':' suite)* ['else' ':' suite]
 while_stmt: 'while' namedexpr_test ':' suite ['else' ':' suite]
@@ -115,9 +115,8 @@ try_stmt: ('try' ':' suite
 	    ['else' ':' suite]
 	    ['finally' ':' suite] |
 	   'finally' ':' suite))
-with_stmt: 'with' with_item (',' with_item)*  ':' suite
-with_item: test ['as' expr]
-with_var: 'as' expr
+with_stmt: 'with' asexpr_test (',' asexpr_test)*  ':' suite
+
 # NB compile.c makes sure that the default except clause is last
 except_clause: 'except' [test [(',' | 'as') test]]
 suite: simple_stmt | NEWLINE INDENT stmt+ DEDENT
@@ -131,7 +130,15 @@ testlist_safe: old_test [(',' old_test)+ [',']]
 old_test: or_test | old_lambdef
 old_lambdef: 'lambda' [varargslist] ':' old_test
 
-namedexpr_test: test [':=' test]
+namedexpr_test: asexpr_test [':=' asexpr_test]
+
+# This is actually not a real rule, though since the parser is very
+# limited in terms of the strategy about match/case rules, we are inserting
+# a virtual case (<expr> as <expr>) as a valid expression. Unless a better
+# approach is thought, the only side effect of this seem to be just allowing
+# more stuff to be parser (which would fail on the ast).
+asexpr_test: test ['as' test]
+
 test: or_test ['if' or_test 'else' test] | lambdef
 or_test: and_test ('or' and_test)*
 and_test: not_test ('and' not_test)*
@@ -213,3 +220,27 @@ encoding_decl: NAME
 
 yield_expr: 'yield' [yield_arg]
 yield_arg: 'from' test | testlist_star_expr
+
+
+# 3.10 match statement definition
+
+# PS: normally the grammar is much much more restricted, but
+# at this moment for not trying to bother much with encoding the
+# exact same DSL in a LL(1) parser, we will just accept an expression
+# and let the ast.parse() step of the safe mode to reject invalid
+# grammar.
+
+# The reason why it is more restricted is that, patterns are some
+# sort of a DSL (more advanced than our LHS on assignments, but
+# still in a very limited python subset). They are not really
+# expressions, but who cares. If we can parse them, that is enough
+# to reformat them.
+
+match_stmt: "match" subject_expr ':' NEWLINE INDENT case_block+ DEDENT
+subject_expr: namedexpr_test
+
+# cases
+case_block: "case" patterns [guard] ':' suite
+guard: 'if' namedexpr_test
+patterns: pattern ['as' pattern]
+pattern: (expr|star_expr) (',' (expr|star_expr))* [',']
diff --git a/src/blib2to3/pgen2/driver.py b/src/blib2to3/pgen2/driver.py
index af1dc6b8aeb..5edd75b1333 100644
--- a/src/blib2to3/pgen2/driver.py
+++ b/src/blib2to3/pgen2/driver.py
@@ -28,19 +28,92 @@
     List,
     Optional,
     Text,
+    Iterator,
     Tuple,
+    TypeVar,
+    Generic,
     Union,
 )
+from dataclasses import dataclass, field
 
 # Pgen imports
 from . import grammar, parse, token, tokenize, pgen
 from logging import Logger
 from blib2to3.pytree import _Convert, NL
 from blib2to3.pgen2.grammar import Grammar
+from contextlib import contextmanager
 
 Path = Union[str, "os.PathLike[str]"]
 
 
+@dataclass
+class ReleaseRange:
+    start: int
+    end: Optional[int] = None
+    tokens: List[Any] = field(default_factory=list)
+
+    def lock(self) -> None:
+        total_eaten = len(self.tokens)
+        self.end = self.start + total_eaten
+
+
+class TokenProxy:
+    def __init__(self, generator: Any) -> None:
+        self._tokens = generator
+        self._counter = 0
+        self._release_ranges: List[ReleaseRange] = []
+
+    @contextmanager
+    def release(self) -> Iterator["TokenProxy"]:
+        release_range = ReleaseRange(self._counter)
+        self._release_ranges.append(release_range)
+        try:
+            yield self
+        finally:
+            # Lock the last release range to the final position that
+            # has been eaten.
+            release_range.lock()
+
+    def eat(self, point: int) -> Any:
+        eaten_tokens = self._release_ranges[-1].tokens
+        if point < len(eaten_tokens):
+            return eaten_tokens[point]
+        else:
+            while point >= len(eaten_tokens):
+                token = next(self._tokens)
+                eaten_tokens.append(token)
+            return token
+
+    def __iter__(self) -> "TokenProxy":
+        return self
+
+    def __next__(self) -> Any:
+        # If the current position is already compromised (looked up)
+        # return the eaten token, if not just go further on the given
+        # token producer.
+        for release_range in self._release_ranges:
+            assert release_range.end is not None
+
+            start, end = release_range.start, release_range.end
+            if start <= self._counter < end:
+                token = release_range.tokens[self._counter - start]
+                break
+        else:
+            token = next(self._tokens)
+        self._counter += 1
+        return token
+
+    def can_advance(self, to: int) -> bool:
+        # Try to eat, fail if it can't. The eat operation is cached
+        # so there wont be any additional cost of eating here
+        try:
+            self.eat(to)
+        except StopIteration:
+            return False
+        else:
+            return True
+
+
 class Driver(object):
     def __init__(
         self,
@@ -57,14 +130,18 @@ def __init__(
     def parse_tokens(self, tokens: Iterable[Any], debug: bool = False) -> NL:
         """Parse a series of tokens and return the syntax tree."""
         # XXX Move the prefix computation into a wrapper around tokenize.
+        proxy = TokenProxy(tokens)
+
         p = parse.Parser(self.grammar, self.convert)
-        p.setup()
+        p.setup(proxy=proxy)
+
         lineno = 1
         column = 0
         indent_columns = []
         type = value = start = end = line_text = None
         prefix = ""
-        for quintuple in tokens:
+
+        for quintuple in proxy:
             type, value, start, end, line_text = quintuple
             if start != (lineno, column):
                 assert (lineno, column) <= start, ((lineno, column), start)
diff --git a/src/blib2to3/pgen2/grammar.py b/src/blib2to3/pgen2/grammar.py
index 2882cdac89b..56851070933 100644
--- a/src/blib2to3/pgen2/grammar.py
+++ b/src/blib2to3/pgen2/grammar.py
@@ -89,6 +89,7 @@ def __init__(self) -> None:
         self.dfas: Dict[int, DFAS] = {}
         self.labels: List[Label] = [(0, "EMPTY")]
         self.keywords: Dict[str, int] = {}
+        self.soft_keywords: Dict[str, int] = {}
         self.tokens: Dict[int, int] = {}
         self.symbol2label: Dict[str, int] = {}
         self.start = 256
@@ -136,6 +137,7 @@ def copy(self: _P) -> _P:
             "number2symbol",
             "dfas",
             "keywords",
+            "soft_keywords",
             "tokens",
             "symbol2label",
         ):
diff --git a/src/blib2to3/pgen2/parse.py b/src/blib2to3/pgen2/parse.py
index 47c8f02b4f5..dc405264bad 100644
--- a/src/blib2to3/pgen2/parse.py
+++ b/src/blib2to3/pgen2/parse.py
@@ -9,22 +9,31 @@
 how this parsing engine works.
 
 """
+import copy
+from contextlib import contextmanager
 
 # Local imports
-from . import token
+from . import grammar, token, tokenize
 from typing import (
+    cast,
+    Any,
     Optional,
     Text,
     Union,
     Tuple,
     Dict,
     List,
+    Iterator,
     Callable,
     Set,
+    TYPE_CHECKING,
 )
 from blib2to3.pgen2.grammar import Grammar
 from blib2to3.pytree import NL, Context, RawNode, Leaf, Node
 
+if TYPE_CHECKING:
+    from blib2to3.driver import TokenProxy
+
 
 Results = Dict[Text, NL]
 Convert = Callable[[Grammar, RawNode], Union[Node, Leaf]]
@@ -37,6 +46,61 @@ def lam_sub(grammar: Grammar, node: RawNode) -> NL:
     return Node(type=node[0], children=node[3], context=node[2])
 
 
+class Recorder:
+    def __init__(self, parser: "Parser", ilabels: List[int], context: Context) -> None:
+        self.parser = parser
+        self._ilabels = ilabels
+        self.context = context  # not really matter
+
+        self._dead_ilabels: Set[int] = set()
+        self._start_point = copy.deepcopy(self.parser.stack)
+        self._points = {ilabel: copy.deepcopy(self._start_point) for ilabel in ilabels}
+
+    @property
+    def ilabels(self) -> Set[int]:
+        return self._dead_ilabels.symmetric_difference(self._ilabels)
+
+    @contextmanager
+    def switch_to(self, ilabel: int) -> Iterator[None]:
+        self.parser.stack = self._points[ilabel]
+        try:
+            yield
+        except ParseError:
+            self._dead_ilabels.add(ilabel)
+        finally:
+            self.parser.stack = self._start_point
+
+    def add_token(
+        self, tok_type: int, tok_val: Optional[Text], raw: bool = False
+    ) -> None:
+        func: Callable[..., Any]
+        if raw:
+            func = self.parser._addtoken
+        else:
+            func = self.parser.addtoken
+
+        for ilabel in self.ilabels:
+            with self.switch_to(ilabel):
+                args = [tok_type, tok_val, self.context]
+                if raw:
+                    args.insert(0, ilabel)
+                func(*args)
+
+    def determine_route(
+        self, value: Optional[Text] = None, force: bool = False
+    ) -> Optional[int]:
+        alive_ilabels = self.ilabels
+        if len(alive_ilabels) == 0:
+            *_, most_successful_ilabel = self._dead_ilabels
+            raise ParseError("bad input", most_successful_ilabel, value, self.context)
+
+        ilabel, *rest = alive_ilabels
+        if force or not rest:
+            return ilabel
+        else:
+            return None
+
+
 class ParseError(Exception):
     """Exception to signal the parser is stuck."""
 
@@ -114,7 +178,7 @@ def __init__(self, grammar: Grammar, convert: Optional[Convert] = None) -> None:
         self.grammar = grammar
         self.convert = convert or lam_sub
 
-    def setup(self, start: Optional[int] = None) -> None:
+    def setup(self, proxy: "TokenProxy", start: Optional[int] = None) -> None:
         """Prepare for parsing.
 
         This *must* be called before starting to parse.
@@ -137,11 +201,55 @@ def setup(self, start: Optional[int] = None) -> None:
         self.stack: List[Tuple[DFAS, int, RawNode]] = [stackentry]
         self.rootnode: Optional[NL] = None
         self.used_names: Set[str] = set()
+        self.proxy = proxy
 
     def addtoken(self, type: int, value: Optional[Text], context: Context) -> bool:
         """Add a token; return True iff this is the end of the program."""
         # Map from token to label
-        ilabel = self.classify(type, value, context)
+        ilabels = self.classify(type, value, context)
+        assert len(ilabels) >= 1
+
+        # If we have only one state to advance, we'll directly
+        # take it as is.
+        if len(ilabels) == 1:
+            [ilabel] = ilabels
+            return self._addtoken(ilabel, type, value, context)
+
+        # If there are multiple states which we can advance (only
+        # happen under soft-keywords), then we will try all of them
+        # in parallel and as soon as one state can reach further than
+        # the rest, we'll choose that one. This is a pretty hacky
+        # and hopefully temporary algorithm.
+        #
+        # For a more detailed explanation, check out this post:
+        # https://tree.science/what-the-backtracking.html
+
+        with self.proxy.release() as proxy:
+            counter, force = 0, False
+            recorder = Recorder(self, ilabels, context)
+            recorder.add_token(type, value, raw=True)
+
+            next_token_value = value
+            while recorder.determine_route(next_token_value) is None:
+                if not proxy.can_advance(counter):
+                    force = True
+                    break
+
+                next_token_type, next_token_value, *_ = proxy.eat(counter)
+                if next_token_type == tokenize.OP:
+                    next_token_type = grammar.opmap[cast(str, next_token_value)]
+
+                recorder.add_token(next_token_type, next_token_value)
+                counter += 1
+
+            ilabel = cast(int, recorder.determine_route(next_token_value, force=force))
+            assert ilabel is not None
+
+        return self._addtoken(ilabel, type, value, context)
+
+    def _addtoken(
+        self, ilabel: int, type: int, value: Optional[Text], context: Context
+    ) -> bool:
         # Loop until the token is shifted; may raise exceptions
         while True:
             dfa, state, node = self.stack[-1]
@@ -185,20 +293,29 @@ def addtoken(self, type: int, value: Optional[Text], context: Context) -> bool:
                     # No success finding a transition
                     raise ParseError("bad input", type, value, context)
 
-    def classify(self, type: int, value: Optional[Text], context: Context) -> int:
-        """Turn a token into a label.  (Internal)"""
+    def classify(self, type: int, value: Optional[Text], context: Context) -> List[int]:
+        """Turn a token into a label.  (Internal)
+
+        Depending on whether the value is a soft-keyword or not,
+        this function may return multiple labels to choose from."""
         if type == token.NAME:
             # Keep a listing of all used names
             assert value is not None
             self.used_names.add(value)
             # Check for reserved words
-            ilabel = self.grammar.keywords.get(value)
-            if ilabel is not None:
-                return ilabel
+            if value in self.grammar.keywords:
+                return [self.grammar.keywords[value]]
+            elif value in self.grammar.soft_keywords:
+                assert type in self.grammar.tokens
+                return [
+                    self.grammar.soft_keywords[value],
+                    self.grammar.tokens[type],
+                ]
+
         ilabel = self.grammar.tokens.get(type)
         if ilabel is None:
             raise ParseError("bad token", type, value, context)
-        return ilabel
+        return [ilabel]
 
     def shift(
         self, type: int, value: Optional[Text], newstate: int, context: Context
diff --git a/src/blib2to3/pgen2/pgen.py b/src/blib2to3/pgen2/pgen.py
index 564ebbd1184..631682a77c9 100644
--- a/src/blib2to3/pgen2/pgen.py
+++ b/src/blib2to3/pgen2/pgen.py
@@ -115,12 +115,17 @@ def make_label(self, c: PgenGrammar, label: Text) -> int:
             assert label[0] in ('"', "'"), label
             value = eval(label)
             if value[0].isalpha():
+                if label[0] == '"':
+                    keywords = c.soft_keywords
+                else:
+                    keywords = c.keywords
+
                 # A keyword
-                if value in c.keywords:
-                    return c.keywords[value]
+                if value in keywords:
+                    return keywords[value]
                 else:
                     c.labels.append((token.NAME, value))
-                    c.keywords[value] = ilabel
+                    keywords[value] = ilabel
                     return ilabel
             else:
                 # An operator (any non-numeric token)
diff --git a/src/blib2to3/pygram.py b/src/blib2to3/pygram.py
index b8362b81473..aa20b8104ae 100644
--- a/src/blib2to3/pygram.py
+++ b/src/blib2to3/pygram.py
@@ -39,12 +39,14 @@ class _python_symbols(Symbols):
     arglist: int
     argument: int
     arith_expr: int
+    asexpr_test: int
     assert_stmt: int
     async_funcdef: int
     async_stmt: int
     atom: int
     augassign: int
     break_stmt: int
+    case_block: int
     classdef: int
     comp_for: int
     comp_if: int
@@ -74,6 +76,7 @@ class _python_symbols(Symbols):
     for_stmt: int
     funcdef: int
     global_stmt: int
+    guard: int
     if_stmt: int
     import_as_name: int
     import_as_names: int
@@ -82,6 +85,7 @@ class _python_symbols(Symbols):
     import_stmt: int
     lambdef: int
     listmaker: int
+    match_stmt: int
     namedexpr_test: int
     not_test: int
     old_comp_for: int
@@ -92,6 +96,8 @@ class _python_symbols(Symbols):
     or_test: int
     parameters: int
     pass_stmt: int
+    pattern: int
+    patterns: int
     power: int
     print_stmt: int
     raise_stmt: int
@@ -101,6 +107,7 @@ class _python_symbols(Symbols):
     single_input: int
     sliceop: int
     small_stmt: int
+    subject_expr: int
     star_expr: int
     stmt: int
     subscript: int
@@ -124,9 +131,7 @@ class _python_symbols(Symbols):
     vfplist: int
     vname: int
     while_stmt: int
-    with_item: int
     with_stmt: int
-    with_var: int
     xor_expr: int
     yield_arg: int
     yield_expr: int
@@ -149,6 +154,7 @@ class _pattern_symbols(Symbols):
 python_grammar_no_print_statement_no_exec_statement_async_keywords: Grammar
 python_grammar_no_exec_statement: Grammar
 pattern_grammar: Grammar
+python_grammar_soft_keywords: Grammar
 
 python_symbols: _python_symbols
 pattern_symbols: _pattern_symbols
@@ -159,6 +165,7 @@ def initialize(cache_dir: Union[str, "os.PathLike[str]", None] = None) -> None:
     global python_grammar_no_print_statement
     global python_grammar_no_print_statement_no_exec_statement
     global python_grammar_no_print_statement_no_exec_statement_async_keywords
+    global python_grammar_soft_keywords
     global python_symbols
     global pattern_grammar
     global pattern_symbols
@@ -171,6 +178,8 @@ def initialize(cache_dir: Union[str, "os.PathLike[str]", None] = None) -> None:
 
     # Python 2
     python_grammar = driver.load_packaged_grammar("blib2to3", _GRAMMAR_FILE, cache_dir)
+    soft_keywords = python_grammar.soft_keywords.copy()
+    python_grammar.soft_keywords.clear()
 
     python_symbols = _python_symbols(python_grammar)
 
@@ -191,6 +200,12 @@ def initialize(cache_dir: Union[str, "os.PathLike[str]", None] = None) -> None:
         True
     )
 
+    # Python 3.10+
+    python_grammar_soft_keywords = (
+        python_grammar_no_print_statement_no_exec_statement_async_keywords.copy()
+    )
+    python_grammar_soft_keywords.soft_keywords = soft_keywords
+
     pattern_grammar = driver.load_packaged_grammar(
         "blib2to3", _PATTERN_GRAMMAR_FILE, cache_dir
     )
diff --git a/tests/data/parenthesized_context_managers.py b/tests/data/parenthesized_context_managers.py
new file mode 100644
index 00000000000..ccf1f94883e
--- /dev/null
+++ b/tests/data/parenthesized_context_managers.py
@@ -0,0 +1,21 @@
+with (CtxManager() as example):
+    ...
+
+with (CtxManager1(), CtxManager2()):
+    ...
+
+with (CtxManager1() as example, CtxManager2()):
+    ...
+
+with (CtxManager1(), CtxManager2() as example):
+    ...
+
+with (CtxManager1() as example1, CtxManager2() as example2):
+    ...
+
+with (
+    CtxManager1() as example1,
+    CtxManager2() as example2,
+    CtxManager3() as example3,
+):
+    ...
diff --git a/tests/data/pattern_matching_complex.py b/tests/data/pattern_matching_complex.py
new file mode 100644
index 00000000000..97ee194fd39
--- /dev/null
+++ b/tests/data/pattern_matching_complex.py
@@ -0,0 +1,144 @@
+# Cases sampled from Lib/test/test_patma.py
+
+# case black_test_patma_098
+match x:
+    case -0j:
+        y = 0
+# case black_test_patma_142
+match x:
+    case bytes(z):
+        y = 0
+# case black_test_patma_073
+match x:
+    case 0 if 0:
+        y = 0
+    case 0 if 1:
+        y = 1
+# case black_test_patma_006
+match 3:
+    case 0 | 1 | 2 | 3:
+        x = True
+# case black_test_patma_049
+match x:
+    case [0, 1] | [1, 0]:
+        y = 0
+# case black_check_sequence_then_mapping
+match x:
+    case [*_]:
+        return "seq"
+    case {}:
+        return "map"
+# case black_test_patma_035
+match x:
+    case {0: [1, 2, {}]}:
+        y = 0
+    case {0: [1, 2, {}] | True} | {1: [[]]} | {0: [1, 2, {}]} | [] | "X" | {}:
+        y = 1
+    case []:
+        y = 2
+# case black_test_patma_107
+match x:
+    case 0.25 + 1.75j:
+        y = 0
+# case black_test_patma_097
+match x:
+    case -0j:
+        y = 0
+# case black_test_patma_007
+match 4:
+    case 0 | 1 | 2 | 3:
+        x = True
+# case black_test_patma_154
+match x:
+    case 0 if x:
+        y = 0
+# case black_test_patma_134
+match x:
+    case {1: 0}:
+        y = 0
+    case {0: 0}:
+        y = 1
+    case {**z}:
+        y = 2
+# case black_test_patma_185
+match Seq():
+    case [*_]:
+        y = 0
+# case black_test_patma_063
+match x:
+    case 1:
+        y = 0
+    case 1:
+        y = 1
+# case black_test_patma_248
+match x:
+    case {"foo": bar}:
+        y = bar
+# case black_test_patma_019
+match (0, 1, 2):
+    case [0, 1, *x, 2]:
+        y = 0
+# case black_test_patma_052
+match x:
+    case [0]:
+        y = 0
+    case [1, 0] if (x := x[:0]):
+        y = 1
+    case [1, 0]:
+        y = 2
+# case black_test_patma_191
+match w:
+    case [x, y, *_]:
+        z = 0
+# case black_test_patma_110
+match x:
+    case -0.25 - 1.75j:
+        y = 0
+# case black_test_patma_151
+match (x,):
+    case [y]:
+        z = 0
+# case black_test_patma_114
+match x:
+    case A.B.C.D:
+        y = 0
+# case black_test_patma_232
+match x:
+    case None:
+        y = 0
+# case black_test_patma_058
+match x:
+    case 0:
+        y = 0
+# case black_test_patma_233
+match x:
+    case False:
+        y = 0
+# case black_test_patma_078
+match x:
+    case []:
+        y = 0
+    case [""]:
+        y = 1
+    case "":
+        y = 2
+# case black_test_patma_156
+match x:
+    case z:
+        y = 0
+# case black_test_patma_189
+match w:
+    case [x, y, *rest]:
+        z = 0
+# case black_test_patma_042
+match x:
+    case (0 as z) | (1 as z) | (2 as z) if z == x % 2:
+        y = 0
+# case black_test_patma_034
+match x:
+    case {0: [1, 2, {}]}:
+        y = 0
+    case {0: [1, 2, {}] | False} | {1: [[]]} | {0: [1, 2, {}]} | [] | "X" | {}:
+        y = 1
+    case []:
+        y = 2
diff --git a/tests/data/pattern_matching_simple.py b/tests/data/pattern_matching_simple.py
new file mode 100644
index 00000000000..5ed62415a4b
--- /dev/null
+++ b/tests/data/pattern_matching_simple.py
@@ -0,0 +1,92 @@
+# Cases sampled from PEP 636 examples
+
+match command.split():
+    case [action, obj]:
+        ...  # interpret action, obj
+
+match command.split():
+    case [action]:
+        ...  # interpret single-verb action
+    case [action, obj]:
+        ...  # interpret action, obj
+
+match command.split():
+    case ["quit"]:
+        print("Goodbye!")
+        quit_game()
+    case ["look"]:
+        current_room.describe()
+    case ["get", obj]:
+        character.get(obj, current_room)
+    case ["go", direction]:
+        current_room = current_room.neighbor(direction)
+    # The rest of your commands go here
+
+match command.split():
+    case ["drop", *objects]:
+        for obj in objects:
+            character.drop(obj, current_room)
+    # The rest of your commands go here
+
+match command.split():
+    case ["quit"]:
+        pass
+    case ["go", direction]:
+        print("Going:", direction)
+    case ["drop", *objects]:
+        print("Dropping: ", *objects)
+    case _:
+        print(f"Sorry, I couldn't understand {command!r}")
+
+match command.split():
+    case ["north"] | ["go", "north"]:
+        current_room = current_room.neighbor("north")
+    case ["get", obj] | ["pick", "up", obj] | ["pick", obj, "up"]:
+        ...  # Code for picking up the given object
+
+match command.split():
+    case ["go", ("north" | "south" | "east" | "west")]:
+        current_room = current_room.neighbor(...)
+        # how do I know which direction to go?
+
+match command.split():
+    case ["go", ("north" | "south" | "east" | "west") as direction]:
+        current_room = current_room.neighbor(direction)
+
+match command.split():
+    case ["go", direction] if direction in current_room.exits:
+        current_room = current_room.neighbor(direction)
+    case ["go", _]:
+        print("Sorry, you can't go that way")
+
+match event.get():
+    case Click(position=(x, y)):
+        handle_click_at(x, y)
+    case KeyPress(key_name="Q") | Quit():
+        game.quit()
+    case KeyPress(key_name="up arrow"):
+        game.go_north()
+    case KeyPress():
+        pass  # Ignore other keystrokes
+    case other_event:
+        raise ValueError(f"Unrecognized event: {other_event}")
+
+match event.get():
+    case Click((x, y), button=Button.LEFT):  # This is a left click
+        handle_click_at(x, y)
+    case Click():
+        pass  # ignore other clicks
+
+
+def where_is(point):
+    match point:
+        case Point(x=0, y=0):
+            print("Origin")
+        case Point(x=0, y=y):
+            print(f"Y={y}")
+        case Point(x=x, y=0):
+            print(f"X={x}")
+        case Point():
+            print("Somewhere else")
+        case _:
+            print("Not a point")
diff --git a/tests/test_format.py b/tests/test_format.py
index 649c1572bee..4359deea92b 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -70,6 +70,11 @@
     "percent_precedence",
 ]
 
+PY310_CASES = [
+    "pattern_matching_simple",
+    "pattern_matching_complex",
+    "parenthesized_context_managers",
+]
 
 SOURCES = [
     "src/black/__init__.py",
@@ -187,6 +192,13 @@ def test_pep_570() -> None:
     assert_format(source, expected, minimum_version=(3, 8))
 
 
+@pytest.mark.parametrize("filename", PY310_CASES)
+def test_python_310(filename: str) -> None:
+    source, expected = read_data(filename)
+    mode = black.Mode(target_versions={black.TargetVersion.PY310})
+    assert_format(source, expected, mode, minimum_version=(3, 10))
+
+
 def test_docstring_no_string_normalization() -> None:
     """Like test_docstring but with string normalization off."""
     source, expected = read_data("docstring_no_string_normalization")

From eb9d0396cd51065c975e366f06dfea60221a2d03 Mon Sep 17 00:00:00 2001
From: Oliver Margetts <oliver.margetts@gmail.com>
Date: Sun, 14 Nov 2021 03:46:15 +0000
Subject: [PATCH 0337/1034] Allow install under pypy (#2559)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 .github/workflows/test.yml |  8 +++++++-
 CHANGES.md                 |  1 +
 docs/faq.md                |  5 +++++
 setup.py                   |  2 +-
 src/black/cache.py         |  2 +-
 src/black/parsing.py       | 25 +++++++++++++++++--------
 tests/test_black.py        |  2 +-
 tox.ini                    | 27 ++++++++++++++++++++++++++-
 8 files changed, 59 insertions(+), 13 deletions(-)

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 296ac34a3fb..7ba2a84d049 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -24,7 +24,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.6", "3.7", "3.8", "3.9", "3.10"]
+        python-version: ["3.6", "3.7", "3.8", "3.9", "3.10", "pypy-3.7"]
         os: [ubuntu-latest, macOS-latest, windows-latest]
 
     steps:
@@ -41,9 +41,15 @@ jobs:
           python -m pip install --upgrade tox
 
       - name: Unit tests
+        if: "!startsWith(matrix.python-version, 'pypy')"
         run: |
           tox -e ci-py -- -v --color=yes
 
+      - name: Unit tests pypy
+        if: "startsWith(matrix.python-version, 'pypy')"
+        run: |
+          tox -e ci-pypy3 -- -v --color=yes
+
       - name: Publish coverage to Coveralls
         # If pushed / is a pull request against main repo AND
         # we're running on Linux (this action only supports Linux)
diff --git a/CHANGES.md b/CHANGES.md
index b2e8f7439b7..c8b9c849815 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -6,6 +6,7 @@
 
 - Warn about Python 2 deprecation in more cases by improving Python 2 only syntax
   detection (#2592)
+- Add experimental PyPy support (#2559)
 - Add partial support for the match statement. As it's experimental, it's only enabled
   when `--target-version py310` is explicitly specified (#2586)
 - Add support for parenthesized with (#2586)
diff --git a/docs/faq.md b/docs/faq.md
index 77f9df51fd4..72bae6b389d 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -92,3 +92,8 @@ influence their behavior. While Black does its best to recognize such comments a
 them in the right place, this detection is not and cannot be perfect. Therefore, you'll
 sometimes have to manually move these comments to the right place after you format your
 codebase with _Black_.
+
+## Can I run black with PyPy?
+
+Yes, there is support for PyPy 3.7 and higher. You cannot format Python 2 files under
+PyPy, because PyPy's inbuilt ast module does not support this.
diff --git a/setup.py b/setup.py
index de84dc37bb8..a0c2006ef33 100644
--- a/setup.py
+++ b/setup.py
@@ -75,7 +75,7 @@ def get_long_description() -> str:
         "click>=7.1.2",
         "platformdirs>=2",
         "tomli>=0.2.6,<2.0.0",
-        "typed-ast>=1.4.2; python_version < '3.8'",
+        "typed-ast>=1.4.2; python_version < '3.8' and implementation_name == 'cpython'",
         "regex>=2020.1.8",
         "pathspec>=0.9.0, <1",
         "dataclasses>=0.6; python_version < '3.7'",
diff --git a/src/black/cache.py b/src/black/cache.py
index 3f165de2ed6..bca7279f990 100644
--- a/src/black/cache.py
+++ b/src/black/cache.py
@@ -35,7 +35,7 @@ def read_cache(mode: Mode) -> Cache:
     with cache_file.open("rb") as fobj:
         try:
             cache: Cache = pickle.load(fobj)
-        except (pickle.UnpicklingError, ValueError):
+        except (pickle.UnpicklingError, ValueError, IndexError):
             return {}
 
     return cache
diff --git a/src/black/parsing.py b/src/black/parsing.py
index fc540ad021d..ee6aae1e7ff 100644
--- a/src/black/parsing.py
+++ b/src/black/parsing.py
@@ -2,6 +2,7 @@
 Parse Python code and perform AST validation.
 """
 import ast
+import platform
 import sys
 from typing import Iterable, Iterator, List, Set, Union, Tuple
 
@@ -15,10 +16,13 @@
 from black.mode import TargetVersion, Feature, supports_feature
 from black.nodes import syms
 
+_IS_PYPY = platform.python_implementation() == "PyPy"
+
 try:
     from typed_ast import ast3, ast27
 except ImportError:
-    if sys.version_info < (3, 8):
+    # Either our python version is too low, or we're on pypy
+    if sys.version_info < (3, 7) or (sys.version_info < (3, 8) and not _IS_PYPY):
         print(
             "The typed_ast package is required but not installed.\n"
             "You can upgrade to Python 3.8+ or install typed_ast with\n"
@@ -117,7 +121,10 @@ def parse_single_version(
     if sys.version_info >= (3, 8) and version >= (3,):
         return ast.parse(src, filename, feature_version=version)
     elif version >= (3,):
-        return ast3.parse(src, filename, feature_version=version[1])
+        if _IS_PYPY:
+            return ast3.parse(src, filename)
+        else:
+            return ast3.parse(src, filename, feature_version=version[1])
     elif version == (2, 7):
         return ast27.parse(src)
     raise AssertionError("INTERNAL ERROR: Tried parsing unsupported Python version!")
@@ -151,12 +158,14 @@ def stringify_ast(
     yield f"{'  ' * depth}{node.__class__.__name__}("
 
     for field in sorted(node._fields):  # noqa: F402
-        # TypeIgnore has only one field 'lineno' which breaks this comparison
-        type_ignore_classes = (ast3.TypeIgnore, ast27.TypeIgnore)
-        if sys.version_info >= (3, 8):
-            type_ignore_classes += (ast.TypeIgnore,)
-        if isinstance(node, type_ignore_classes):
-            break
+        # TypeIgnore will not be present using pypy < 3.8, so need for this
+        if not (_IS_PYPY and sys.version_info < (3, 8)):
+            # TypeIgnore has only one field 'lineno' which breaks this comparison
+            type_ignore_classes = (ast3.TypeIgnore, ast27.TypeIgnore)
+            if sys.version_info >= (3, 8):
+                type_ignore_classes += (ast.TypeIgnore,)
+            if isinstance(node, type_ignore_classes):
+                break
 
         try:
             value = getattr(node, field)
diff --git a/tests/test_black.py b/tests/test_black.py
index 7dbc3809d26..301a3a5b363 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -944,7 +944,7 @@ def test_broken_symlink(self) -> None:
             symlink = workspace / "broken_link.py"
             try:
                 symlink.symlink_to("nonexistent.py")
-            except OSError as e:
+            except (OSError, NotImplementedError) as e:
                 self.skipTest(f"Can't create symlinks: {e}")
             self.invokeBlack([str(workspace.resolve())])
 
diff --git a/tox.ini b/tox.ini
index 57f41acb3d1..683a5439ea9 100644
--- a/tox.ini
+++ b/tox.ini
@@ -1,5 +1,5 @@
 [tox]
-envlist = {,ci-}py{36,37,38,39,310},fuzz
+envlist = {,ci-}py{36,37,38,39,310,py3},fuzz
 
 [testenv]
 setenv = PYTHONPATH = {toxinidir}/src
@@ -31,6 +31,31 @@ commands =
         --cov --cov-append {posargs}
     coverage report
 
+[testenv:{,ci-}pypy3]
+setenv = PYTHONPATH = {toxinidir}/src
+skip_install = True
+recreate = True
+deps =
+    -r{toxinidir}/test_requirements.txt
+; a separate worker is required in ci due to https://foss.heptapod.net/pypy/pypy/-/issues/3317
+; this seems to cause tox to wait forever
+; remove this when pypy releases the bugfix
+commands =
+    pip install -e .[d]
+    coverage erase
+    pytest tests --run-optional no_python2 \
+        --run-optional no_jupyter \
+        !ci: --numprocesses auto \
+        ci: --numprocesses 1 \
+        --cov {posargs}
+    pip install -e .[jupyter]
+    pytest tests --run-optional jupyter \
+        -m jupyter \
+        !ci: --numprocesses auto \
+        ci: --numprocesses 1 \
+        --cov --cov-append {posargs}
+    coverage report
+
 [testenv:fuzz]
 skip_install = True
 deps =

From 147d075a4c702ffd6822100dc1f7a6384e52fa57 Mon Sep 17 00:00:00 2001
From: Batuhan Taskaya <isidentical@gmail.com>
Date: Sun, 14 Nov 2021 17:04:31 +0300
Subject: [PATCH 0338/1034] black/parser: support as-exprs within call args
 (#2608)

---
 src/blib2to3/Grammar.txt              | 1 +
 tests/data/pattern_matching_extras.py | 9 +++++++++
 tests/test_format.py                  | 1 +
 3 files changed, 11 insertions(+)
 create mode 100644 tests/data/pattern_matching_extras.py

diff --git a/src/blib2to3/Grammar.txt b/src/blib2to3/Grammar.txt
index 49680323d8b..c2a62543abb 100644
--- a/src/blib2to3/Grammar.txt
+++ b/src/blib2to3/Grammar.txt
@@ -186,6 +186,7 @@ arglist: argument (',' argument)* [',']
 # that precede iterable unpackings are blocked; etc.
 argument: ( test [comp_for] |
             test ':=' test |
+            test 'as' test |
             test '=' test |
 	    '**' test |
             '*' test )
diff --git a/tests/data/pattern_matching_extras.py b/tests/data/pattern_matching_extras.py
new file mode 100644
index 00000000000..b17922d608b
--- /dev/null
+++ b/tests/data/pattern_matching_extras.py
@@ -0,0 +1,9 @@
+match something:
+    case [a as b]:
+        print(b)
+    case [a as b, c, d, e as f]:
+        print(f)
+    case Point(a as b):
+        print(b)
+    case Point(int() as x, int() as y):
+        print(x, y)
diff --git a/tests/test_format.py b/tests/test_format.py
index 4359deea92b..8f8ffb3610e 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -73,6 +73,7 @@
 PY310_CASES = [
     "pattern_matching_simple",
     "pattern_matching_complex",
+    "pattern_matching_extras",
     "parenthesized_context_managers",
 ]
 

From 3cb010ec8ec02392dee5073b74e6eff80030c5f0 Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <hugovk@users.noreply.github.com>
Date: Sun, 14 Nov 2021 16:37:06 +0200
Subject: [PATCH 0339/1034] Declare support for Python 3.10 (#2562)

---
 CHANGES.md | 1 +
 setup.py   | 1 +
 2 files changed, 2 insertions(+)

diff --git a/CHANGES.md b/CHANGES.md
index c8b9c849815..0d409d778af 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -10,6 +10,7 @@
 - Add partial support for the match statement. As it's experimental, it's only enabled
   when `--target-version py310` is explicitly specified (#2586)
 - Add support for parenthesized with (#2586)
+- Declare support for Python 3.10 for running Black (#2562)
 
 ## 21.10b0
 
diff --git a/setup.py b/setup.py
index a0c2006ef33..1914ba745e7 100644
--- a/setup.py
+++ b/setup.py
@@ -104,6 +104,7 @@ def get_long_description() -> str:
         "Programming Language :: Python :: 3.7",
         "Programming Language :: Python :: 3.8",
         "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
         "Programming Language :: Python :: 3 :: Only",
         "Topic :: Software Development :: Libraries :: Python Modules",
         "Topic :: Software Development :: Quality Assurance",

From 78317a4cfb2cc7958ebd553ff6d7cc1aff0d8296 Mon Sep 17 00:00:00 2001
From: Michal Siska <94260368+515k4@users.noreply.github.com>
Date: Mon, 15 Nov 2021 17:51:56 +0100
Subject: [PATCH 0340/1034] Removed distutils import from autoload/black.vim
 (#2607) (#2610)

---
 CHANGES.md         | 4 ++++
 autoload/black.vim | 7 ++++++-
 2 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index 0d409d778af..c565fbe50ca 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -12,6 +12,10 @@
 - Add support for parenthesized with (#2586)
 - Declare support for Python 3.10 for running Black (#2562)
 
+### Integrations
+
+- Fixed vim plugin with Python 3.10 by removing deprecated distutils import (#2610)
+
 ## 21.10b0
 
 ### _Black_
diff --git a/autoload/black.vim b/autoload/black.vim
index 9ff5c2341fe..6c3bbfea81d 100644
--- a/autoload/black.vim
+++ b/autoload/black.vim
@@ -3,8 +3,13 @@ import collections
 import os
 import sys
 import vim
-from distutils.util import strtobool
 
+def strtobool(text):
+  if text.lower() in ['y', 'yes', 't', 'true' 'on', '1']:
+    return True
+  if text.lower() in ['n', 'no', 'f', 'false' 'off', '0']:
+    return False
+  raise ValueError(f"{text} is not convertable to boolean")
 
 class Flag(collections.namedtuple("FlagBase", "name, cast")):
   @property

From d7b091e762121ee38ca313ab25006abf4723d203 Mon Sep 17 00:00:00 2001
From: Batuhan Taskaya <isidentical@gmail.com>
Date: Tue, 16 Nov 2021 05:38:40 +0300
Subject: [PATCH 0341/1034] black/parser: optimize deepcopying nodes (#2611)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The implementation of the new backtracking logic depends heavily on deepcopying the current state of the parser before seeing one of the new keywords, which by default is an very expensive operations. On my system, formatting these 3 files takes 1.3 seconds.

```
 $ touch tests/data/pattern_matching_*; time python -m black -tpy310 tests/data/pattern_matching_*             19ms
All done! ✨ 🍰 ✨
3 files left unchanged.
python -m black -tpy310 tests/data/pattern_matching_*  2,09s user 0,04s system 157% cpu 1,357 total
```

which can be optimized 3X if we integrate the existing copying logic (`clone`) to the deepcopy system;
```
 $ touch tests/data/pattern_matching_*; time python -m black -tpy310 tests/data/pattern_matching_*              1ms
All done! ✨ 🍰 ✨
3 files left unchanged.
python -m black -tpy310 tests/data/pattern_matching_*  0,66s user 0,02s system 147% cpu 0,464 total
```

This still might have some potential, but that would be way trickier than this initial patch.
---
 src/blib2to3/pytree.py                |  5 ++++-
 tests/data/pattern_matching_extras.py | 20 ++++++++++++++++++++
 2 files changed, 24 insertions(+), 1 deletion(-)

diff --git a/src/blib2to3/pytree.py b/src/blib2to3/pytree.py
index 7843467e012..001652df09f 100644
--- a/src/blib2to3/pytree.py
+++ b/src/blib2to3/pytree.py
@@ -52,7 +52,7 @@ def type_repr(type_num: int) -> Union[Text, int]:
     return _type_reprs.setdefault(type_num, type_num)
 
 
-_P = TypeVar("_P")
+_P = TypeVar("_P", bound="Base")
 
 NL = Union["Node", "Leaf"]
 Context = Tuple[Text, Tuple[int, int]]
@@ -109,6 +109,9 @@ def _eq(self: _P, other: _P) -> bool:
         """
         raise NotImplementedError
 
+    def __deepcopy__(self: _P, memo: Any) -> _P:
+        return self.clone()
+
     def clone(self: _P) -> _P:
         """
         Return a cloned (deep) copy of self.
diff --git a/tests/data/pattern_matching_extras.py b/tests/data/pattern_matching_extras.py
index b17922d608b..614e66aebe6 100644
--- a/tests/data/pattern_matching_extras.py
+++ b/tests/data/pattern_matching_extras.py
@@ -1,3 +1,5 @@
+import match
+
 match something:
     case [a as b]:
         print(b)
@@ -7,3 +9,21 @@
         print(b)
     case Point(int() as x, int() as y):
         print(x, y)
+
+
+match = 1
+case: int = re.match(something)
+
+match re.match(case):
+    case type("match", match):
+        pass
+    case match:
+        pass
+
+
+def func(match: case, case: match) -> case:
+    match Something():
+        case another:
+            ...
+        case func(match, case):
+            ...

From 1d7163957a34e8f071aaf9ac59467b912449fb07 Mon Sep 17 00:00:00 2001
From: pszlazak <pszlazak@users.noreply.github.com>
Date: Tue, 16 Nov 2021 03:47:21 +0100
Subject: [PATCH 0342/1034] Docker image usage description (#2412)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 .../black_docker_image.md                     | 46 +++++++++++++++++++
 docs/usage_and_configuration/index.rst        |  2 +
 2 files changed, 48 insertions(+)
 create mode 100644 docs/usage_and_configuration/black_docker_image.md

diff --git a/docs/usage_and_configuration/black_docker_image.md b/docs/usage_and_configuration/black_docker_image.md
new file mode 100644
index 00000000000..0a458434871
--- /dev/null
+++ b/docs/usage_and_configuration/black_docker_image.md
@@ -0,0 +1,46 @@
+# Black Docker image
+
+Official _Black_ Docker images are available on Docker Hub:
+https://hub.docker.com/r/pyfound/black
+
+_Black_ images with the following tags are available:
+
+- release numbers, e.g. `21.5b2`, `21.6b0`, `21.7b0` etc.\
+  ℹ Recommended for users who want to use a particular version of _Black_.
+- `latest_release` - tag created when a new version of _Black_ is released.\
+  ℹ Recommended for users who want to use released versions of _Black_. It maps to [the latest release](https://github.com/psf/black/releases/latest)
+  of _Black_.
+- `latest` - tag used for the newest image of _Black_.\
+  ℹ Recommended for users who always want to use the latest version of _Black_, even before
+  it is released.
+
+There is one more tag used for _Black_ Docker images - `latest_non_release`. It is
+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.
+
+## Usage
+
+A permanent container doesn't have to be created to use _Black_ as a Docker image. It's
+enough to run _Black_ commands for the chosen image denoted as `:tag`. In the below
+examples, the `latest_release` tag is used. If `:tag` is omitted, the `latest` tag will
+be used.
+
+More about _Black_ usage can be found in
+[Usage and Configuration: The basics](./the_basics.md).
+
+### Check Black version
+
+```console
+$ docker run --rm pyfound/black:latest_release black --version
+```
+
+### Check code
+
+```console
+$ docker run --rm --volume $(pwd):/src --workdir /src pyfound/black:latest_release black --check .
+```
+
+_Remark_: besides [regular _Black_ exit codes](./the_basics.md) returned by `--check`
+option, [Docker exit codes](https://docs.docker.com/engine/reference/run/#exit-status)
+should also be considered.
diff --git a/docs/usage_and_configuration/index.rst b/docs/usage_and_configuration/index.rst
index 84a9c0cb99b..f6152eec90c 100644
--- a/docs/usage_and_configuration/index.rst
+++ b/docs/usage_and_configuration/index.rst
@@ -7,6 +7,7 @@ Usage and Configuration
   the_basics
   file_collection_and_discovery
   black_as_a_server
+  black_docker_image
 
 Sometimes, running *Black* with its defaults and passing filepaths to it just won't cut
 it. Passing each file using paths will become burdensome, and maybe you would like
@@ -22,3 +23,4 @@ This section covers features of *Black* and configuring *Black* in detail:
 - :doc:`The basics <./the_basics>`
 - :doc:`File collection and discovery <file_collection_and_discovery>`
 - :doc:`Black as a server (blackd) <./black_as_a_server>`
+- :doc:`Black Docker image <./black_docker_image>`

From 1d7260050d846d2ba2dd5bb22944b032245c7e51 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Mon, 15 Nov 2021 19:03:47 -0800
Subject: [PATCH 0343/1034] vim: Parse skip_magic_trailing_comma from
 pyproject.toml (#2613)

Co-authored-by: Kyle Kovacs <kkovacs@diconfiberoptics.com>
---
 CHANGES.md         | 1 +
 autoload/black.vim | 2 ++
 2 files changed, 3 insertions(+)

diff --git a/CHANGES.md b/CHANGES.md
index c565fbe50ca..4e99c9478f1 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -15,6 +15,7 @@
 ### Integrations
 
 - Fixed vim plugin with Python 3.10 by removing deprecated distutils import (#2610)
+- The vim plugin now parses `skip_magic_trailing_comma` from pyproject.toml (#2613)
 
 ## 21.10b0
 
diff --git a/autoload/black.vim b/autoload/black.vim
index 6c3bbfea81d..66c5b9c2841 100644
--- a/autoload/black.vim
+++ b/autoload/black.vim
@@ -29,6 +29,7 @@ FLAGS = [
   Flag(name="fast", cast=strtobool),
   Flag(name="skip_string_normalization", cast=strtobool),
   Flag(name="quiet", cast=strtobool),
+  Flag(name="skip_magic_trailing_comma", cast=strtobool),
 ]
 
 
@@ -143,6 +144,7 @@ def Black(**kwargs):
     line_length=configs["line_length"],
     string_normalization=not configs["skip_string_normalization"],
     is_pyi=vim.current.buffer.name.endswith('.pyi'),
+    magic_trailing_comma=not configs["skip_magic_trailing_comma"],
     **black_kwargs,
   )
   quiet = configs["quiet"]

From 117891878e5be4d6b771ae5de299e51b679cea27 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Mon, 15 Nov 2021 23:24:16 -0500
Subject: [PATCH 0344/1034] Implementing mypyc support pt. 2  (#2431)

---
 mypy.ini                         | 10 +++-
 pyproject.toml                   |  3 ++
 setup.py                         | 47 ++++++++++++++-----
 src/black/__init__.py            | 23 +++++++--
 src/black/brackets.py            |  2 +-
 src/black/comments.py            | 15 ++++--
 src/black/files.py               |  4 +-
 src/black/handle_ipynb_magics.py | 13 +++---
 src/black/linegen.py             | 25 ++++++----
 src/black/mode.py                |  3 +-
 src/black/nodes.py               | 37 +++++++++------
 src/black/output.py              |  3 ++
 src/black/parsing.py             | 26 +++++++++--
 src/black/strings.py             | 30 +++++++++---
 src/black/trans.py               | 59 ++++++++++++++---------
 src/black_primer/cli.py          |  3 +-
 src/blib2to3/README              |  2 +
 src/blib2to3/pgen2/driver.py     | 23 ++++-----
 src/blib2to3/pgen2/parse.py      | 80 +++++++++++++++-----------------
 src/blib2to3/pgen2/tokenize.py   | 33 +++++++------
 src/blib2to3/pytree.py           | 15 +++---
 tests/test_black.py              | 22 +++++++--
 22 files changed, 310 insertions(+), 168 deletions(-)

diff --git a/mypy.ini b/mypy.ini
index 62c1c7fefaa..cfceaa3ee86 100644
--- a/mypy.ini
+++ b/mypy.ini
@@ -3,7 +3,6 @@
 # free to run mypy on Windows, Linux, or macOS and get consistent
 # results.
 python_version=3.6
-platform=linux
 
 mypy_path=src
 
@@ -24,6 +23,10 @@ warn_redundant_casts=True
 warn_unused_ignores=True
 disallow_any_generics=True
 
+# Unreachable blocks have been an issue when compiling mypyc, let's try
+# to avoid 'em in the first place.
+warn_unreachable=True
+
 # The following are off by default.  Flip them on if you feel
 # adventurous.
 disallow_untyped_defs=True
@@ -32,6 +35,11 @@ check_untyped_defs=True
 # No incremental mode
 cache_dir=/dev/null
 
+[mypy-black]
+# The following is because of `patch_click()`. Remove when
+# we drop Python 3.6 support.
+warn_unused_ignores=False
+
 [mypy-black_primer.*]
 # Until we're not supporting 3.6 primer needs this
 disallow_any_generics=False
diff --git a/pyproject.toml b/pyproject.toml
index 73e19608108..aebbc0da29c 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -33,3 +33,6 @@ optional-tests = [
   "no_blackd: run when `d` extra NOT installed",
   "no_jupyter: run when `jupyter` extra NOT installed",
 ]
+markers = [
+  "incompatible_with_mypyc: run when testing mypyc compiled black"
+]
diff --git a/setup.py b/setup.py
index 1914ba745e7..7022b24345c 100644
--- a/setup.py
+++ b/setup.py
@@ -5,6 +5,7 @@
 
 assert sys.version_info >= (3, 6, 2), "black requires Python 3.6.2+"
 from pathlib import Path  # noqa E402
+from typing import List  # noqa: E402
 
 CURRENT_DIR = Path(__file__).parent
 sys.path.insert(0, str(CURRENT_DIR))  # for setuptools.build_meta
@@ -18,6 +19,17 @@ def get_long_description() -> str:
     )
 
 
+def find_python_files(base: Path) -> List[Path]:
+    files = []
+    for entry in base.iterdir():
+        if entry.is_file() and entry.suffix == ".py":
+            files.append(entry)
+        elif entry.is_dir():
+            files.extend(find_python_files(entry))
+
+    return files
+
+
 USE_MYPYC = False
 # To compile with mypyc, a mypyc checkout must be present on the PYTHONPATH
 if len(sys.argv) > 1 and sys.argv[1] == "--use-mypyc":
@@ -27,21 +39,34 @@ def get_long_description() -> str:
     USE_MYPYC = True
 
 if USE_MYPYC:
+    from mypyc.build import mypycify
+
+    src = CURRENT_DIR / "src"
+    # TIP: filepaths are normalized to use forward slashes and are relative to ./src/
+    # before being checked against.
+    blocklist = [
+        # Not performance sensitive, so save bytes + compilation time:
+        "blib2to3/__init__.py",
+        "blib2to3/pgen2/__init__.py",
+        "black/output.py",
+        "black/concurrency.py",
+        "black/files.py",
+        "black/report.py",
+        # Breaks the test suite when compiled (and is also useless):
+        "black/debug.py",
+        # Compiled modules can't be run directly and that's a problem here:
+        "black/__main__.py",
+    ]
+    discovered = []
+    # black-primer and blackd have no good reason to be compiled.
+    discovered.extend(find_python_files(src / "black"))
+    discovered.extend(find_python_files(src / "blib2to3"))
     mypyc_targets = [
-        "src/black/__init__.py",
-        "src/blib2to3/pytree.py",
-        "src/blib2to3/pygram.py",
-        "src/blib2to3/pgen2/parse.py",
-        "src/blib2to3/pgen2/grammar.py",
-        "src/blib2to3/pgen2/token.py",
-        "src/blib2to3/pgen2/driver.py",
-        "src/blib2to3/pgen2/pgen.py",
+        str(p) for p in discovered if p.relative_to(src).as_posix() not in blocklist
     ]
 
-    from mypyc.build import mypycify
-
     opt_level = os.getenv("MYPYC_OPT_LEVEL", "3")
-    ext_modules = mypycify(mypyc_targets, opt_level=opt_level)
+    ext_modules = mypycify(mypyc_targets, opt_level=opt_level, verbose=True)
 else:
     ext_modules = []
 
diff --git a/src/black/__init__.py b/src/black/__init__.py
index ad4ee1a0d1a..a5ddec91221 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -30,8 +30,9 @@
     Union,
 )
 
-from dataclasses import replace
 import click
+from dataclasses import replace
+from mypy_extensions import mypyc_attr
 
 from black.const import DEFAULT_LINE_LENGTH, DEFAULT_INCLUDES, DEFAULT_EXCLUDES
 from black.const import STDIN_PLACEHOLDER
@@ -66,6 +67,8 @@
 
 from _black_version import version as __version__
 
+COMPILED = Path(__file__).suffix in (".pyd", ".so")
+
 # types
 FileContent = str
 Encoding = str
@@ -177,7 +180,12 @@ def validate_regex(
         raise click.BadParameter("Not a valid regular expression") from None
 
 
-@click.command(context_settings=dict(help_option_names=["-h", "--help"]))
+@click.command(
+    context_settings=dict(help_option_names=["-h", "--help"]),
+    # While Click does set this field automatically using the docstring, mypyc
+    # (annoyingly) strips 'em so we need to set it here too.
+    help="The uncompromising code formatter.",
+)
 @click.option("-c", "--code", type=str, help="Format the code passed in as a string.")
 @click.option(
     "-l",
@@ -346,7 +354,10 @@ def validate_regex(
         " due to exclusion patterns."
     ),
 )
-@click.version_option(version=__version__)
+@click.version_option(
+    version=__version__,
+    message=f"%(prog)s, %(version)s (compiled: {'yes' if COMPILED else 'no'})",
+)
 @click.argument(
     "src",
     nargs=-1,
@@ -387,7 +398,7 @@ def main(
     experimental_string_processing: bool,
     quiet: bool,
     verbose: bool,
-    required_version: str,
+    required_version: Optional[str],
     include: Pattern[str],
     exclude: Optional[Pattern[str]],
     extend_exclude: Optional[Pattern[str]],
@@ -655,6 +666,9 @@ def reformat_one(
         report.failed(src, str(exc))
 
 
+# diff-shades depends on being to monkeypatch this function to operate. I know it's
+# not ideal, but this shouldn't cause any issues ... hopefully. ~ichard26
+@mypyc_attr(patchable=True)
 def reformat_many(
     sources: Set[Path],
     fast: bool,
@@ -669,6 +683,7 @@ def reformat_many(
     worker_count = workers if workers is not None else DEFAULT_WORKERS
     if sys.platform == "win32":
         # Work around https://bugs.python.org/issue26903
+        assert worker_count is not None
         worker_count = min(worker_count, 60)
     try:
         executor = ProcessPoolExecutor(max_workers=worker_count)
diff --git a/src/black/brackets.py b/src/black/brackets.py
index bb865a0d5b7..c5ed4bf5b9f 100644
--- a/src/black/brackets.py
+++ b/src/black/brackets.py
@@ -49,7 +49,7 @@
 DOT_PRIORITY: Final = 1
 
 
-class BracketMatchError(KeyError):
+class BracketMatchError(Exception):
     """Raised when an opening bracket is unable to be matched to a closing bracket."""
 
 
diff --git a/src/black/comments.py b/src/black/comments.py
index c7513c21ef5..a8152d687a3 100644
--- a/src/black/comments.py
+++ b/src/black/comments.py
@@ -1,8 +1,14 @@
+import sys
 from dataclasses import dataclass
 from functools import lru_cache
 import regex as re
 from typing import Iterator, List, Optional, Union
 
+if sys.version_info >= (3, 8):
+    from typing import Final
+else:
+    from typing_extensions import Final
+
 from blib2to3.pytree import Node, Leaf
 from blib2to3.pgen2 import token
 
@@ -12,11 +18,10 @@
 # types
 LN = Union[Leaf, Node]
 
-
-FMT_OFF = {"# fmt: off", "# fmt:off", "# yapf: disable"}
-FMT_SKIP = {"# fmt: skip", "# fmt:skip"}
-FMT_PASS = {*FMT_OFF, *FMT_SKIP}
-FMT_ON = {"# fmt: on", "# fmt:on", "# yapf: enable"}
+FMT_OFF: Final = {"# fmt: off", "# fmt:off", "# yapf: disable"}
+FMT_SKIP: Final = {"# fmt: skip", "# fmt:skip"}
+FMT_PASS: Final = {*FMT_OFF, *FMT_SKIP}
+FMT_ON: Final = {"# fmt: on", "# fmt:on", "# yapf: enable"}
 
 
 @dataclass
diff --git a/src/black/files.py b/src/black/files.py
index 4d7b47aaa9f..560aa05080d 100644
--- a/src/black/files.py
+++ b/src/black/files.py
@@ -17,6 +17,7 @@
     TYPE_CHECKING,
 )
 
+from mypy_extensions import mypyc_attr
 from pathspec import PathSpec
 from pathspec.patterns.gitwildmatch import GitWildMatchPatternError
 import tomli
@@ -88,13 +89,14 @@ def find_pyproject_toml(path_search_start: Tuple[str, ...]) -> Optional[str]:
         return None
 
 
+@mypyc_attr(patchable=True)
 def parse_pyproject_toml(path_config: str) -> Dict[str, Any]:
     """Parse a pyproject toml file, pulling out relevant parts for Black
 
     If parsing fails, will raise a tomli.TOMLDecodeError
     """
     with open(path_config, encoding="utf8") as f:
-        pyproject_toml = tomli.load(f)  # type: ignore  # due to deprecated API usage
+        pyproject_toml = tomli.loads(f.read())
     config = pyproject_toml.get("tool", {}).get("black", {})
     return {k.replace("--", "").replace("-", "_"): v for k, v in config.items()}
 
diff --git a/src/black/handle_ipynb_magics.py b/src/black/handle_ipynb_magics.py
index f10eaed4f3e..2fe6739209d 100644
--- a/src/black/handle_ipynb_magics.py
+++ b/src/black/handle_ipynb_magics.py
@@ -333,7 +333,7 @@ def header(self) -> str:
         return f"%%{self.name}"
 
 
-@dataclasses.dataclass
+# ast.NodeVisitor + dataclass = breakage under mypyc.
 class CellMagicFinder(ast.NodeVisitor):
     """Find cell magics.
 
@@ -352,7 +352,8 @@ class CellMagicFinder(ast.NodeVisitor):
     and we look for instances of the latter.
     """
 
-    cell_magic: Optional[CellMagic] = None
+    def __init__(self, cell_magic: Optional[CellMagic] = None) -> None:
+        self.cell_magic = cell_magic
 
     def visit_Expr(self, node: ast.Expr) -> None:
         """Find cell magic, extract header and body."""
@@ -372,7 +373,8 @@ class OffsetAndMagic:
     magic: str
 
 
-@dataclasses.dataclass
+# Unsurprisingly, subclassing ast.NodeVisitor means we can't use dataclasses here
+# as mypyc will generate broken code.
 class MagicFinder(ast.NodeVisitor):
     """Visit cell to look for get_ipython calls.
 
@@ -392,9 +394,8 @@ class MagicFinder(ast.NodeVisitor):
     types of magics).
     """
 
-    magics: Dict[int, List[OffsetAndMagic]] = dataclasses.field(
-        default_factory=lambda: collections.defaultdict(list)
-    )
+    def __init__(self) -> None:
+        self.magics: Dict[int, List[OffsetAndMagic]] = collections.defaultdict(list)
 
     def visit_Assign(self, node: ast.Assign) -> None:
         """Look for system assign magics.
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 8cf32c973bb..4cba4164fb3 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -5,8 +5,6 @@
 import sys
 from typing import Collection, Iterator, List, Optional, Set, Union
 
-from dataclasses import dataclass, field
-
 from black.nodes import WHITESPACE, RARROW, STATEMENT, STANDALONE_COMMENT
 from black.nodes import ASSIGNMENTS, OPENING_BRACKETS, CLOSING_BRACKETS
 from black.nodes import Visitor, syms, first_child_is_arith, ensure_visible
@@ -40,7 +38,8 @@ class CannotSplit(CannotTransform):
     """A readable split that fits the allotted line length is impossible."""
 
 
-@dataclass
+# This isn't a dataclass because @dataclass + Generic breaks mypyc.
+# See also https://github.com/mypyc/mypyc/issues/827.
 class LineGenerator(Visitor[Line]):
     """Generates reformatted Line objects.  Empty lines are not emitted.
 
@@ -48,9 +47,11 @@ class LineGenerator(Visitor[Line]):
     in ways that will no longer stringify to valid Python code on the tree.
     """
 
-    mode: Mode
-    remove_u_prefix: bool = False
-    current_line: Line = field(init=False)
+    def __init__(self, mode: Mode, remove_u_prefix: bool = False) -> None:
+        self.mode = mode
+        self.remove_u_prefix = remove_u_prefix
+        self.current_line: Line
+        self.__post_init__()
 
     def line(self, indent: int = 0) -> Iterator[Line]:
         """Generate a line.
@@ -339,7 +340,9 @@ def transform_line(
         transformers = [left_hand_split]
     else:
 
-        def rhs(line: Line, features: Collection[Feature]) -> Iterator[Line]:
+        def _rhs(
+            self: object, line: Line, features: Collection[Feature]
+        ) -> Iterator[Line]:
             """Wraps calls to `right_hand_split`.
 
             The calls increasingly `omit` right-hand trailers (bracket pairs with
@@ -366,6 +369,12 @@ def rhs(line: Line, features: Collection[Feature]) -> Iterator[Line]:
                 line, line_length=mode.line_length, features=features
             )
 
+        # HACK: nested functions (like _rhs) compiled by mypyc don't retain their
+        # __name__ attribute which is needed in `run_transformer` further down.
+        # Unfortunately a nested class breaks mypyc too. So a class must be created
+        # via type ... https://github.com/mypyc/mypyc/issues/884
+        rhs = type("rhs", (), {"__call__": _rhs})()
+
         if mode.experimental_string_processing:
             if line.inside_brackets:
                 transformers = [
@@ -980,7 +989,7 @@ def run_transformer(
         result.extend(transform_line(transformed_line, mode=mode, features=features))
 
     if (
-        transform.__name__ != "rhs"
+        transform.__class__.__name__ != "rhs"
         or not line.bracket_tracker.invisible
         or any(bracket.value for bracket in line.bracket_tracker.invisible)
         or line.contains_multiline_strings()
diff --git a/src/black/mode.py b/src/black/mode.py
index b24c9c60ded..3c167569498 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -6,6 +6,7 @@
 
 from dataclasses import dataclass, field
 from enum import Enum
+from operator import attrgetter
 from typing import Dict, Set
 
 from black.const import DEFAULT_LINE_LENGTH
@@ -134,7 +135,7 @@ def get_cache_key(self) -> str:
         if self.target_versions:
             version_str = ",".join(
                 str(version.value)
-                for version in sorted(self.target_versions, key=lambda v: v.value)
+                for version in sorted(self.target_versions, key=attrgetter("value"))
             )
         else:
             version_str = "-"
diff --git a/src/black/nodes.py b/src/black/nodes.py
index 8f2e15b2cc3..36dd1890511 100644
--- a/src/black/nodes.py
+++ b/src/black/nodes.py
@@ -15,10 +15,12 @@
     Union,
 )
 
-if sys.version_info < (3, 8):
-    from typing_extensions import Final
-else:
+if sys.version_info >= (3, 8):
     from typing import Final
+else:
+    from typing_extensions import Final
+
+from mypy_extensions import mypyc_attr
 
 # lib2to3 fork
 from blib2to3.pytree import Node, Leaf, type_repr
@@ -30,7 +32,7 @@
 
 
 pygram.initialize(CACHE_DIR)
-syms = pygram.python_symbols
+syms: Final = pygram.python_symbols
 
 
 # types
@@ -128,16 +130,21 @@
     "//=",
 }
 
-IMPLICIT_TUPLE = {syms.testlist, syms.testlist_star_expr, syms.exprlist}
-BRACKET = {token.LPAR: token.RPAR, token.LSQB: token.RSQB, token.LBRACE: token.RBRACE}
-OPENING_BRACKETS = set(BRACKET.keys())
-CLOSING_BRACKETS = set(BRACKET.values())
-BRACKETS = OPENING_BRACKETS | CLOSING_BRACKETS
-ALWAYS_NO_SPACE = CLOSING_BRACKETS | {token.COMMA, STANDALONE_COMMENT}
+IMPLICIT_TUPLE: Final = {syms.testlist, syms.testlist_star_expr, syms.exprlist}
+BRACKET: Final = {
+    token.LPAR: token.RPAR,
+    token.LSQB: token.RSQB,
+    token.LBRACE: token.RBRACE,
+}
+OPENING_BRACKETS: Final = set(BRACKET.keys())
+CLOSING_BRACKETS: Final = set(BRACKET.values())
+BRACKETS: Final = OPENING_BRACKETS | CLOSING_BRACKETS
+ALWAYS_NO_SPACE: Final = CLOSING_BRACKETS | {token.COMMA, STANDALONE_COMMENT}
 
 RARROW = 55
 
 
+@mypyc_attr(allow_interpreted_subclasses=True)
 class Visitor(Generic[T]):
     """Basic lib2to3 visitor that yields things of type `T` on `visit()`."""
 
@@ -178,9 +185,9 @@ def whitespace(leaf: Leaf, *, complex_subscript: bool) -> str:  # noqa: C901
     `complex_subscript` signals whether the given leaf is part of a subscription
     which has non-trivial arguments, like arithmetic expressions or function calls.
     """
-    NO = ""
-    SPACE = " "
-    DOUBLESPACE = "  "
+    NO: Final = ""
+    SPACE: Final = " "
+    DOUBLESPACE: Final = "  "
     t = leaf.type
     p = leaf.parent
     v = leaf.value
@@ -441,8 +448,8 @@ def prev_siblings_are(node: Optional[LN], tokens: List[Optional[NodeType]]) -> b
 
 def last_two_except(leaves: List[Leaf], omit: Collection[LeafID]) -> Tuple[Leaf, Leaf]:
     """Return (penultimate, last) leaves skipping brackets in `omit` and contents."""
-    stop_after = None
-    last = None
+    stop_after: Optional[Leaf] = None
+    last: Optional[Leaf] = None
     for leaf in reversed(leaves):
         if stop_after:
             if leaf is stop_after:
diff --git a/src/black/output.py b/src/black/output.py
index fd3dbb37627..c85b253c159 100644
--- a/src/black/output.py
+++ b/src/black/output.py
@@ -11,6 +11,7 @@
 from click import echo, style
 
 
+@mypyc_attr(patchable=True)
 def _out(message: Optional[str] = None, nl: bool = True, **styles: Any) -> None:
     if message is not None:
         if "bold" not in styles:
@@ -19,6 +20,7 @@ def _out(message: Optional[str] = None, nl: bool = True, **styles: Any) -> None:
     echo(message, nl=nl, err=True)
 
 
+@mypyc_attr(patchable=True)
 def _err(message: Optional[str] = None, nl: bool = True, **styles: Any) -> None:
     if message is not None:
         if "fg" not in styles:
@@ -27,6 +29,7 @@ def _err(message: Optional[str] = None, nl: bool = True, **styles: Any) -> None:
     echo(message, nl=nl, err=True)
 
 
+@mypyc_attr(patchable=True)
 def out(message: Optional[str] = None, nl: bool = True, **styles: Any) -> None:
     _out(message, nl=nl, **styles)
 
diff --git a/src/black/parsing.py b/src/black/parsing.py
index ee6aae1e7ff..504e20be002 100644
--- a/src/black/parsing.py
+++ b/src/black/parsing.py
@@ -4,11 +4,16 @@
 import ast
 import platform
 import sys
-from typing import Iterable, Iterator, List, Set, Union, Tuple
+from typing import Any, Iterable, Iterator, List, Set, Tuple, Type, Union
+
+if sys.version_info < (3, 8):
+    from typing_extensions import Final
+else:
+    from typing import Final
 
 # lib2to3 fork
 from blib2to3.pytree import Node, Leaf
-from blib2to3 import pygram, pytree
+from blib2to3 import pygram
 from blib2to3.pgen2 import driver
 from blib2to3.pgen2.grammar import Grammar
 from blib2to3.pgen2.parse import ParseError
@@ -16,6 +21,9 @@
 from black.mode import TargetVersion, Feature, supports_feature
 from black.nodes import syms
 
+ast3: Any
+ast27: Any
+
 _IS_PYPY = platform.python_implementation() == "PyPy"
 
 try:
@@ -86,7 +94,7 @@ def lib2to3_parse(src_txt: str, target_versions: Iterable[TargetVersion] = ()) -
         src_txt += "\n"
 
     for grammar in get_grammars(set(target_versions)):
-        drv = driver.Driver(grammar, pytree.convert)
+        drv = driver.Driver(grammar)
         try:
             result = drv.parse_string(src_txt, True)
             break
@@ -148,6 +156,10 @@ def parse_ast(src: str) -> Union[ast.AST, ast3.AST, ast27.AST]:
     raise SyntaxError(first_error)
 
 
+ast3_AST: Final[Type[ast3.AST]] = ast3.AST
+ast27_AST: Final[Type[ast27.AST]] = ast27.AST
+
+
 def stringify_ast(
     node: Union[ast.AST, ast3.AST, ast27.AST], depth: int = 0
 ) -> Iterator[str]:
@@ -189,7 +201,13 @@ def stringify_ast(
                 elif isinstance(item, (ast.AST, ast3.AST, ast27.AST)):
                     yield from stringify_ast(item, depth + 2)
 
-        elif isinstance(value, (ast.AST, ast3.AST, ast27.AST)):
+        # Note that we are referencing the typed-ast ASTs via global variables and not
+        # direct module attribute accesses because that breaks mypyc. It's probably
+        # something to do with the ast3 / ast27 variables being marked as Any leading
+        # mypy to think this branch is always taken, leaving the rest of the code
+        # unanalyzed. Tighting up the types for the typed-ast AST types avoids the
+        # mypyc crash.
+        elif isinstance(value, (ast.AST, ast3_AST, ast27_AST)):
             yield from stringify_ast(value, depth + 2)
 
         else:
diff --git a/src/black/strings.py b/src/black/strings.py
index d7b6c240e80..97debe3b5de 100644
--- a/src/black/strings.py
+++ b/src/black/strings.py
@@ -4,10 +4,20 @@
 
 import regex as re
 import sys
+from functools import lru_cache
 from typing import List, Pattern
 
+if sys.version_info < (3, 8):
+    from typing_extensions import Final
+else:
+    from typing import Final
 
-STRING_PREFIX_CHARS = "furbFURB"  # All possible string prefix characters.
+
+STRING_PREFIX_CHARS: Final = "furbFURB"  # All possible string prefix characters.
+STRING_PREFIX_RE: Final = re.compile(
+    r"^([" + STRING_PREFIX_CHARS + r"]*)(.*)$", re.DOTALL
+)
+FIRST_NON_WHITESPACE_RE: Final = re.compile(r"\s*\t+\s*(\S)")
 
 
 def sub_twice(regex: Pattern[str], replacement: str, original: str) -> str:
@@ -37,7 +47,7 @@ def lines_with_leading_tabs_expanded(s: str) -> List[str]:
     for line in s.splitlines():
         # Find the index of the first non-whitespace character after a string of
         # whitespace that includes at least one tab
-        match = re.match(r"\s*\t+\s*(\S)", line)
+        match = FIRST_NON_WHITESPACE_RE.match(line)
         if match:
             first_non_whitespace_idx = match.start(1)
 
@@ -133,7 +143,7 @@ def normalize_string_prefix(s: str, remove_u_prefix: bool = False) -> str:
 
     If remove_u_prefix is given, also removes any u prefix from the string.
     """
-    match = re.match(r"^([" + STRING_PREFIX_CHARS + r"]*)(.*)$", s, re.DOTALL)
+    match = STRING_PREFIX_RE.match(s)
     assert match is not None, f"failed to match string {s!r}"
     orig_prefix = match.group(1)
     new_prefix = orig_prefix.replace("F", "f").replace("B", "b").replace("U", "u")
@@ -142,6 +152,14 @@ def normalize_string_prefix(s: str, remove_u_prefix: bool = False) -> str:
     return f"{new_prefix}{match.group(2)}"
 
 
+# Re(gex) does actually cache patterns internally but this still improves
+# performance on a long list literal of strings by 5-9% since lru_cache's
+# caching overhead is much lower.
+@lru_cache(maxsize=64)
+def _cached_compile(pattern: str) -> re.Pattern:
+    return re.compile(pattern)
+
+
 def normalize_string_quotes(s: str) -> str:
     """Prefer double quotes but only if it doesn't cause more escaping.
 
@@ -166,9 +184,9 @@ def normalize_string_quotes(s: str) -> str:
         return s  # There's an internal error
 
     prefix = s[:first_quote_pos]
-    unescaped_new_quote = re.compile(rf"(([^\\]|^)(\\\\)*){new_quote}")
-    escaped_new_quote = re.compile(rf"([^\\]|^)\\((?:\\\\)*){new_quote}")
-    escaped_orig_quote = re.compile(rf"([^\\]|^)\\((?:\\\\)*){orig_quote}")
+    unescaped_new_quote = _cached_compile(rf"(([^\\]|^)(\\\\)*){new_quote}")
+    escaped_new_quote = _cached_compile(rf"([^\\]|^)\\((?:\\\\)*){new_quote}")
+    escaped_orig_quote = _cached_compile(rf"([^\\]|^)\\((?:\\\\)*){orig_quote}")
     body = s[first_quote_pos + len(orig_quote) : -len(orig_quote)]
     if "r" in prefix.casefold():
         if unescaped_new_quote.search(body):
diff --git a/src/black/trans.py b/src/black/trans.py
index 023dcd3618a..d918ef111a2 100644
--- a/src/black/trans.py
+++ b/src/black/trans.py
@@ -8,6 +8,7 @@
 from typing import (
     Any,
     Callable,
+    ClassVar,
     Collection,
     Dict,
     Iterable,
@@ -20,6 +21,14 @@
     TypeVar,
     Union,
 )
+import sys
+
+if sys.version_info < (3, 8):
+    from typing_extensions import Final
+else:
+    from typing import Final
+
+from mypy_extensions import trait
 
 from black.rusty import Result, Ok, Err
 
@@ -62,7 +71,6 @@ def TErr(err_msg: str) -> Err[CannotTransform]:
     return Err(cant_transform)
 
 
-@dataclass  # type: ignore
 class StringTransformer(ABC):
     """
     An implementation of the Transformer protocol that relies on its
@@ -90,9 +98,13 @@ class StringTransformer(ABC):
         as much as possible.
     """
 
-    line_length: int
-    normalize_strings: bool
-    __name__ = "StringTransformer"
+    __name__: Final = "StringTransformer"
+
+    # Ideally this would be a dataclass, but unfortunately mypyc breaks when used with
+    # `abc.ABC`.
+    def __init__(self, line_length: int, normalize_strings: bool) -> None:
+        self.line_length = line_length
+        self.normalize_strings = normalize_strings
 
     @abstractmethod
     def do_match(self, line: Line) -> TMatchResult:
@@ -184,6 +196,7 @@ class CustomSplit:
     break_idx: int
 
 
+@trait
 class CustomSplitMapMixin:
     """
     This mixin class is used to map merged strings to a sequence of
@@ -191,8 +204,10 @@ class CustomSplitMapMixin:
     the resultant substrings go over the configured max line length.
     """
 
-    _Key = Tuple[StringID, str]
-    _CUSTOM_SPLIT_MAP: Dict[_Key, Tuple[CustomSplit, ...]] = defaultdict(tuple)
+    _Key: ClassVar = Tuple[StringID, str]
+    _CUSTOM_SPLIT_MAP: ClassVar[Dict[_Key, Tuple[CustomSplit, ...]]] = defaultdict(
+        tuple
+    )
 
     @staticmethod
     def _get_key(string: str) -> "CustomSplitMapMixin._Key":
@@ -243,7 +258,7 @@ def has_custom_splits(self, string: str) -> bool:
         return key in self._CUSTOM_SPLIT_MAP
 
 
-class StringMerger(CustomSplitMapMixin, StringTransformer):
+class StringMerger(StringTransformer, CustomSplitMapMixin):
     """StringTransformer that merges strings together.
 
     Requirements:
@@ -739,7 +754,7 @@ class BaseStringSplitter(StringTransformer):
         * The target string is not a multiline (i.e. triple-quote) string.
     """
 
-    STRING_OPERATORS = [
+    STRING_OPERATORS: Final = [
         token.EQEQUAL,
         token.GREATER,
         token.GREATEREQUAL,
@@ -927,7 +942,7 @@ def _get_max_string_length(self, line: Line, string_idx: int) -> int:
         return max_string_length
 
 
-class StringSplitter(CustomSplitMapMixin, BaseStringSplitter):
+class StringSplitter(BaseStringSplitter, CustomSplitMapMixin):
     """
     StringTransformer that splits "atom" strings (i.e. strings which exist on
     lines by themselves).
@@ -965,9 +980,9 @@ class StringSplitter(CustomSplitMapMixin, BaseStringSplitter):
         CustomSplit objects and add them to the custom split map.
     """
 
-    MIN_SUBSTR_SIZE = 6
+    MIN_SUBSTR_SIZE: Final = 6
     # Matches an "f-expression" (e.g. {var}) that might be found in an f-string.
-    RE_FEXPR = r"""
+    RE_FEXPR: Final = r"""
     (?<!\{) (?:\{\{)* \{ (?!\{)
         (?:
             [^\{\}]
@@ -1426,7 +1441,7 @@ def _get_string_operator_leaves(self, leaves: Iterable[Leaf]) -> List[Leaf]:
         return string_op_leaves
 
 
-class StringParenWrapper(CustomSplitMapMixin, BaseStringSplitter):
+class StringParenWrapper(BaseStringSplitter, CustomSplitMapMixin):
     """
     StringTransformer that splits non-"atom" strings (i.e. strings that do not
     exist on lines by themselves).
@@ -1811,20 +1826,20 @@ class StringParser:
         ```
     """
 
-    DEFAULT_TOKEN = -1
+    DEFAULT_TOKEN: Final = 20210605
 
     # String Parser States
-    START = 1
-    DOT = 2
-    NAME = 3
-    PERCENT = 4
-    SINGLE_FMT_ARG = 5
-    LPAR = 6
-    RPAR = 7
-    DONE = 8
+    START: Final = 1
+    DOT: Final = 2
+    NAME: Final = 3
+    PERCENT: Final = 4
+    SINGLE_FMT_ARG: Final = 5
+    LPAR: Final = 6
+    RPAR: Final = 7
+    DONE: Final = 8
 
     # Lookup Table for Next State
-    _goto: Dict[Tuple[ParserState, NodeType], ParserState] = {
+    _goto: Final[Dict[Tuple[ParserState, NodeType], ParserState]] = {
         # A string trailer may start with '.' OR '%'.
         (START, token.DOT): DOT,
         (START, token.PERCENT): PERCENT,
diff --git a/src/black_primer/cli.py b/src/black_primer/cli.py
index 2395d35886a..8524b59a632 100644
--- a/src/black_primer/cli.py
+++ b/src/black_primer/cli.py
@@ -104,13 +104,12 @@ async def async_main(
             no_diff,
         )
         return int(ret_val)
+
     finally:
         if not keep and work_path.exists():
             LOG.debug(f"Removing {work_path}")
             rmtree(work_path, onerror=lib.handle_PermissionError)
 
-    return -2
-
 
 @click.command(context_settings={"help_option_names": ["-h", "--help"]})
 @click.option(
diff --git a/src/blib2to3/README b/src/blib2to3/README
index ccad28337b6..0d3c607c9c7 100644
--- a/src/blib2to3/README
+++ b/src/blib2to3/README
@@ -19,3 +19,5 @@ Change Log:
     https://github.com/python/cpython/commit/cae60187cf7a7b26281d012e1952fafe4e2e97e9
   - "bpo-42316: Allow unparenthesized walrus operator in indexes (GH-23317)"
     https://github.com/python/cpython/commit/b0aba1fcdc3da952698d99aec2334faa79a8b68c
+- Tweaks to help mypyc compile faster code (including inlining type information,
+  "Final-ing", etc.)
diff --git a/src/blib2to3/pgen2/driver.py b/src/blib2to3/pgen2/driver.py
index 5edd75b1333..8fe820651da 100644
--- a/src/blib2to3/pgen2/driver.py
+++ b/src/blib2to3/pgen2/driver.py
@@ -23,6 +23,7 @@
 import sys
 from typing import (
     Any,
+    cast,
     IO,
     Iterable,
     List,
@@ -34,14 +35,15 @@
     Generic,
     Union,
 )
+from contextlib import contextmanager
 from dataclasses import dataclass, field
 
 # Pgen imports
 from . import grammar, parse, token, tokenize, pgen
 from logging import Logger
-from blib2to3.pytree import _Convert, NL
+from blib2to3.pytree import NL
 from blib2to3.pgen2.grammar import Grammar
-from contextlib import contextmanager
+from blib2to3.pgen2.tokenize import GoodTokenInfo
 
 Path = Union[str, "os.PathLike[str]"]
 
@@ -115,29 +117,23 @@ def can_advance(self, to: int) -> bool:
 
 
 class Driver(object):
-    def __init__(
-        self,
-        grammar: Grammar,
-        convert: Optional[_Convert] = None,
-        logger: Optional[Logger] = None,
-    ) -> None:
+    def __init__(self, grammar: Grammar, logger: Optional[Logger] = None) -> None:
         self.grammar = grammar
         if logger is None:
             logger = logging.getLogger(__name__)
         self.logger = logger
-        self.convert = convert
 
-    def parse_tokens(self, tokens: Iterable[Any], debug: bool = False) -> NL:
+    def parse_tokens(self, tokens: Iterable[GoodTokenInfo], debug: bool = False) -> NL:
         """Parse a series of tokens and return the syntax tree."""
         # XXX Move the prefix computation into a wrapper around tokenize.
         proxy = TokenProxy(tokens)
 
-        p = parse.Parser(self.grammar, self.convert)
+        p = parse.Parser(self.grammar)
         p.setup(proxy=proxy)
 
         lineno = 1
         column = 0
-        indent_columns = []
+        indent_columns: List[int] = []
         type = value = start = end = line_text = None
         prefix = ""
 
@@ -163,6 +159,7 @@ def parse_tokens(self, tokens: Iterable[Any], debug: bool = False) -> NL:
             if type == token.OP:
                 type = grammar.opmap[value]
             if debug:
+                assert type is not None
                 self.logger.debug(
                     "%s %r (prefix=%r)", token.tok_name[type], value, prefix
                 )
@@ -174,7 +171,7 @@ def parse_tokens(self, tokens: Iterable[Any], debug: bool = False) -> NL:
             elif type == token.DEDENT:
                 _indent_col = indent_columns.pop()
                 prefix, _prefix = self._partially_consume_prefix(prefix, _indent_col)
-            if p.addtoken(type, value, (prefix, start)):
+            if p.addtoken(cast(int, type), value, (prefix, start)):
                 if debug:
                     self.logger.debug("Stop.")
                 break
diff --git a/src/blib2to3/pgen2/parse.py b/src/blib2to3/pgen2/parse.py
index dc405264bad..792e8e66698 100644
--- a/src/blib2to3/pgen2/parse.py
+++ b/src/blib2to3/pgen2/parse.py
@@ -29,7 +29,7 @@
     TYPE_CHECKING,
 )
 from blib2to3.pgen2.grammar import Grammar
-from blib2to3.pytree import NL, Context, RawNode, Leaf, Node
+from blib2to3.pytree import convert, NL, Context, RawNode, Leaf, Node
 
 if TYPE_CHECKING:
     from blib2to3.driver import TokenProxy
@@ -70,9 +70,7 @@ def switch_to(self, ilabel: int) -> Iterator[None]:
         finally:
             self.parser.stack = self._start_point
 
-    def add_token(
-        self, tok_type: int, tok_val: Optional[Text], raw: bool = False
-    ) -> None:
+    def add_token(self, tok_type: int, tok_val: Text, raw: bool = False) -> None:
         func: Callable[..., Any]
         if raw:
             func = self.parser._addtoken
@@ -86,9 +84,7 @@ def add_token(
                     args.insert(0, ilabel)
                 func(*args)
 
-    def determine_route(
-        self, value: Optional[Text] = None, force: bool = False
-    ) -> Optional[int]:
+    def determine_route(self, value: Text = None, force: bool = False) -> Optional[int]:
         alive_ilabels = self.ilabels
         if len(alive_ilabels) == 0:
             *_, most_successful_ilabel = self._dead_ilabels
@@ -164,6 +160,11 @@ def __init__(self, grammar: Grammar, convert: Optional[Convert] = None) -> None:
         to be converted.  The syntax tree is converted from the bottom
         up.
 
+        **post-note: the convert argument is ignored since for Black's
+        usage, convert will always be blib2to3.pytree.convert. Allowing
+        this to be dynamic hurts mypyc's ability to use early binding.
+        These docs are left for historical and informational value.
+
         A concrete syntax tree node is a (type, value, context, nodes)
         tuple, where type is the node type (a token or symbol number),
         value is None for symbols and a string for tokens, context is
@@ -176,6 +177,7 @@ def __init__(self, grammar: Grammar, convert: Optional[Convert] = None) -> None:
 
         """
         self.grammar = grammar
+        # See note in docstring above. TL;DR this is ignored.
         self.convert = convert or lam_sub
 
     def setup(self, proxy: "TokenProxy", start: Optional[int] = None) -> None:
@@ -203,7 +205,7 @@ def setup(self, proxy: "TokenProxy", start: Optional[int] = None) -> None:
         self.used_names: Set[str] = set()
         self.proxy = proxy
 
-    def addtoken(self, type: int, value: Optional[Text], context: Context) -> bool:
+    def addtoken(self, type: int, value: Text, context: Context) -> bool:
         """Add a token; return True iff this is the end of the program."""
         # Map from token to label
         ilabels = self.classify(type, value, context)
@@ -237,7 +239,7 @@ def addtoken(self, type: int, value: Optional[Text], context: Context) -> bool:
 
                 next_token_type, next_token_value, *_ = proxy.eat(counter)
                 if next_token_type == tokenize.OP:
-                    next_token_type = grammar.opmap[cast(str, next_token_value)]
+                    next_token_type = grammar.opmap[next_token_value]
 
                 recorder.add_token(next_token_type, next_token_value)
                 counter += 1
@@ -247,9 +249,7 @@ def addtoken(self, type: int, value: Optional[Text], context: Context) -> bool:
 
         return self._addtoken(ilabel, type, value, context)
 
-    def _addtoken(
-        self, ilabel: int, type: int, value: Optional[Text], context: Context
-    ) -> bool:
+    def _addtoken(self, ilabel: int, type: int, value: Text, context: Context) -> bool:
         # Loop until the token is shifted; may raise exceptions
         while True:
             dfa, state, node = self.stack[-1]
@@ -257,10 +257,18 @@ def _addtoken(
             arcs = states[state]
             # Look for a state with this label
             for i, newstate in arcs:
-                t, v = self.grammar.labels[i]
-                if ilabel == i:
+                t = self.grammar.labels[i][0]
+                if t >= 256:
+                    # See if it's a symbol and if we're in its first set
+                    itsdfa = self.grammar.dfas[t]
+                    itsstates, itsfirst = itsdfa
+                    if ilabel in itsfirst:
+                        # Push a symbol
+                        self.push(t, itsdfa, newstate, context)
+                        break  # To continue the outer while loop
+
+                elif ilabel == i:
                     # Look it up in the list of labels
-                    assert t < 256
                     # Shift a token; we're done with it
                     self.shift(type, value, newstate, context)
                     # Pop while we are in an accept-only state
@@ -274,14 +282,7 @@ def _addtoken(
                         states, first = dfa
                     # Done with this token
                     return False
-                elif t >= 256:
-                    # See if it's a symbol and if we're in its first set
-                    itsdfa = self.grammar.dfas[t]
-                    itsstates, itsfirst = itsdfa
-                    if ilabel in itsfirst:
-                        # Push a symbol
-                        self.push(t, self.grammar.dfas[t], newstate, context)
-                        break  # To continue the outer while loop
+
             else:
                 if (0, state) in arcs:
                     # An accepting state, pop it and try something else
@@ -293,14 +294,13 @@ def _addtoken(
                     # No success finding a transition
                     raise ParseError("bad input", type, value, context)
 
-    def classify(self, type: int, value: Optional[Text], context: Context) -> List[int]:
+    def classify(self, type: int, value: Text, context: Context) -> List[int]:
         """Turn a token into a label.  (Internal)
 
         Depending on whether the value is a soft-keyword or not,
         this function may return multiple labels to choose from."""
         if type == token.NAME:
             # Keep a listing of all used names
-            assert value is not None
             self.used_names.add(value)
             # Check for reserved words
             if value in self.grammar.keywords:
@@ -317,18 +317,13 @@ def classify(self, type: int, value: Optional[Text], context: Context) -> List[i
             raise ParseError("bad token", type, value, context)
         return [ilabel]
 
-    def shift(
-        self, type: int, value: Optional[Text], newstate: int, context: Context
-    ) -> None:
+    def shift(self, type: int, value: Text, newstate: int, context: Context) -> None:
         """Shift a token.  (Internal)"""
         dfa, state, node = self.stack[-1]
-        assert value is not None
-        assert context is not None
         rawnode: RawNode = (type, value, context, None)
-        newnode = self.convert(self.grammar, rawnode)
-        if newnode is not None:
-            assert node[-1] is not None
-            node[-1].append(newnode)
+        newnode = convert(self.grammar, rawnode)
+        assert node[-1] is not None
+        node[-1].append(newnode)
         self.stack[-1] = (dfa, newstate, node)
 
     def push(self, type: int, newdfa: DFAS, newstate: int, context: Context) -> None:
@@ -341,12 +336,11 @@ def push(self, type: int, newdfa: DFAS, newstate: int, context: Context) -> None
     def pop(self) -> None:
         """Pop a nonterminal.  (Internal)"""
         popdfa, popstate, popnode = self.stack.pop()
-        newnode = self.convert(self.grammar, popnode)
-        if newnode is not None:
-            if self.stack:
-                dfa, state, node = self.stack[-1]
-                assert node[-1] is not None
-                node[-1].append(newnode)
-            else:
-                self.rootnode = newnode
-                self.rootnode.used_names = self.used_names
+        newnode = convert(self.grammar, popnode)
+        if self.stack:
+            dfa, state, node = self.stack[-1]
+            assert node[-1] is not None
+            node[-1].append(newnode)
+        else:
+            self.rootnode = newnode
+            self.rootnode.used_names = self.used_names
diff --git a/src/blib2to3/pgen2/tokenize.py b/src/blib2to3/pgen2/tokenize.py
index bad79b2dc2c..283fac2d537 100644
--- a/src/blib2to3/pgen2/tokenize.py
+++ b/src/blib2to3/pgen2/tokenize.py
@@ -27,6 +27,7 @@
 function to which the 5 fields described above are passed as 5 arguments,
 each time a new token is found."""
 
+import sys
 from typing import (
     Callable,
     Iterable,
@@ -39,6 +40,12 @@
     Union,
     cast,
 )
+
+if sys.version_info >= (3, 8):
+    from typing import Final
+else:
+    from typing_extensions import Final
+
 from blib2to3.pgen2.token import *
 from blib2to3.pgen2.grammar import Grammar
 
@@ -139,7 +146,7 @@ def _combinations(*l):
 PseudoExtras = group(r"\\\r?\n", Comment, Triple)
 PseudoToken = Whitespace + group(PseudoExtras, Number, Funny, ContStr, Name)
 
-pseudoprog = re.compile(PseudoToken, re.UNICODE)
+pseudoprog: Final = re.compile(PseudoToken, re.UNICODE)
 single3prog = re.compile(Single3)
 double3prog = re.compile(Double3)
 
@@ -149,7 +156,7 @@ def _combinations(*l):
     | {"u", "U", "ur", "uR", "Ur", "UR"}
 )
 
-endprogs = {
+endprogs: Final = {
     "'": re.compile(Single),
     '"': re.compile(Double),
     "'''": single3prog,
@@ -159,12 +166,12 @@ def _combinations(*l):
     **{prefix: None for prefix in _strprefixes},
 }
 
-triple_quoted = (
+triple_quoted: Final = (
     {"'''", '"""'}
     | {f"{prefix}'''" for prefix in _strprefixes}
     | {f'{prefix}"""' for prefix in _strprefixes}
 )
-single_quoted = (
+single_quoted: Final = (
     {"'", '"'}
     | {f"{prefix}'" for prefix in _strprefixes}
     | {f'{prefix}"' for prefix in _strprefixes}
@@ -418,7 +425,7 @@ def generate_tokens(
     logical line; continuation lines are included.
     """
     lnum = parenlev = continued = 0
-    numchars = "0123456789"
+    numchars: Final = "0123456789"
     contstr, needcont = "", 0
     contline: Optional[str] = None
     indents = [0]
@@ -427,7 +434,7 @@ def generate_tokens(
     # `await` as keywords.
     async_keywords = False if grammar is None else grammar.async_keywords
     # 'stashed' and 'async_*' are used for async/await parsing
-    stashed = None
+    stashed: Optional[GoodTokenInfo] = None
     async_def = False
     async_def_indent = 0
     async_def_nl = False
@@ -440,7 +447,7 @@ def generate_tokens(
             line = readline()
         except StopIteration:
             line = ""
-        lnum = lnum + 1
+        lnum += 1
         pos, max = 0, len(line)
 
         if contstr:  # continued string
@@ -481,14 +488,14 @@ def generate_tokens(
             column = 0
             while pos < max:  # measure leading whitespace
                 if line[pos] == " ":
-                    column = column + 1
+                    column += 1
                 elif line[pos] == "\t":
                     column = (column // tabsize + 1) * tabsize
                 elif line[pos] == "\f":
                     column = 0
                 else:
                     break
-                pos = pos + 1
+                pos += 1
             if pos == max:
                 break
 
@@ -507,7 +514,7 @@ def generate_tokens(
                     COMMENT,
                     comment_token,
                     (lnum, pos),
-                    (lnum, pos + len(comment_token)),
+                    (lnum, nl_pos),
                     line,
                 )
                 yield (NL, line[nl_pos:], (lnum, nl_pos), (lnum, len(line)), line)
@@ -652,16 +659,16 @@ def generate_tokens(
                     continued = 1
                 else:
                     if initial in "([{":
-                        parenlev = parenlev + 1
+                        parenlev += 1
                     elif initial in ")]}":
-                        parenlev = parenlev - 1
+                        parenlev -= 1
                     if stashed:
                         yield stashed
                         stashed = None
                     yield (OP, token, spos, epos, line)
             else:
                 yield (ERRORTOKEN, line[pos], (lnum, pos), (lnum, pos + 1), line)
-                pos = pos + 1
+                pos += 1
 
     if stashed:
         yield stashed
diff --git a/src/blib2to3/pytree.py b/src/blib2to3/pytree.py
index 001652df09f..bd86270b8e2 100644
--- a/src/blib2to3/pytree.py
+++ b/src/blib2to3/pytree.py
@@ -14,7 +14,6 @@
 
 from typing import (
     Any,
-    Callable,
     Dict,
     Iterator,
     List,
@@ -92,8 +91,6 @@ def __eq__(self, other: Any) -> bool:
             return NotImplemented
         return self._eq(other)
 
-    __hash__ = None  # type: Any  # For Py3 compatibility.
-
     @property
     def prefix(self) -> Text:
         raise NotImplementedError
@@ -437,7 +434,7 @@ def __str__(self) -> Text:
 
         This reproduces the input source exactly.
         """
-        return self.prefix + str(self.value)
+        return self._prefix + str(self.value)
 
     def _eq(self, other) -> bool:
         """Compare two nodes for equality."""
@@ -672,8 +669,11 @@ def __init__(
             newcontent = list(content)
             for i, item in enumerate(newcontent):
                 assert isinstance(item, BasePattern), (i, item)
-                if isinstance(item, WildcardPattern):
-                    self.wildcards = True
+                # I don't even think this code is used anywhere, but it does cause
+                # unreachable errors from mypy. This function's signature does look
+                # odd though *shrug*.
+                if isinstance(item, WildcardPattern):  # type: ignore[unreachable]
+                    self.wildcards = True  # type: ignore[unreachable]
         self.type = type
         self.content = newcontent
         self.name = name
@@ -978,6 +978,3 @@ def generate_matches(
                     r.update(r0)
                     r.update(r1)
                     yield c0 + c1, r
-
-
-_Convert = Callable[[Grammar, RawNode], Any]
diff --git a/tests/test_black.py b/tests/test_black.py
index 301a3a5b363..3d5d3982817 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -122,7 +122,7 @@ def invokeBlack(
     runner = BlackRunner()
     if ignore_config:
         args = ["--verbose", "--config", str(THIS_DIR / "empty.toml"), *args]
-    result = runner.invoke(black.main, args)
+    result = runner.invoke(black.main, args, catch_exceptions=False)
     assert result.stdout_bytes is not None
     assert result.stderr_bytes is not None
     msg = (
@@ -841,6 +841,7 @@ def test_get_future_imports(self) -> None:
         )
         self.assertEqual({"unicode_literals", "print"}, black.get_future_imports(node))
 
+    @pytest.mark.incompatible_with_mypyc
     def test_debug_visitor(self) -> None:
         source, _ = read_data("debug_visitor.py")
         expected, _ = read_data("debug_visitor.out")
@@ -891,6 +892,7 @@ def test_endmarker(self) -> None:
         self.assertEqual(len(n.children), 1)
         self.assertEqual(n.children[0].type, black.token.ENDMARKER)
 
+    @pytest.mark.incompatible_with_mypyc
     @unittest.skipIf(os.environ.get("SKIP_AST_PRINT"), "user set SKIP_AST_PRINT")
     def test_assertFormatEqual(self) -> None:
         out_lines = []
@@ -1055,6 +1057,7 @@ def test_pipe_force_py36(self) -> None:
         actual = result.output
         self.assertFormatEqual(actual, expected)
 
+    @pytest.mark.incompatible_with_mypyc
     def test_reformat_one_with_stdin(self) -> None:
         with patch(
             "black.format_stdin_to_stdout",
@@ -1072,6 +1075,7 @@ def test_reformat_one_with_stdin(self) -> None:
             fsts.assert_called_once()
             report.done.assert_called_with(path, black.Changed.YES)
 
+    @pytest.mark.incompatible_with_mypyc
     def test_reformat_one_with_stdin_filename(self) -> None:
         with patch(
             "black.format_stdin_to_stdout",
@@ -1094,6 +1098,7 @@ def test_reformat_one_with_stdin_filename(self) -> None:
             # __BLACK_STDIN_FILENAME__ should have been stripped
             report.done.assert_called_with(expected, black.Changed.YES)
 
+    @pytest.mark.incompatible_with_mypyc
     def test_reformat_one_with_stdin_filename_pyi(self) -> None:
         with patch(
             "black.format_stdin_to_stdout",
@@ -1118,6 +1123,7 @@ def test_reformat_one_with_stdin_filename_pyi(self) -> None:
             # __BLACK_STDIN_FILENAME__ should have been stripped
             report.done.assert_called_with(expected, black.Changed.YES)
 
+    @pytest.mark.incompatible_with_mypyc
     def test_reformat_one_with_stdin_filename_ipynb(self) -> None:
         with patch(
             "black.format_stdin_to_stdout",
@@ -1142,6 +1148,7 @@ def test_reformat_one_with_stdin_filename_ipynb(self) -> None:
             # __BLACK_STDIN_FILENAME__ should have been stripped
             report.done.assert_called_with(expected, black.Changed.YES)
 
+    @pytest.mark.incompatible_with_mypyc
     def test_reformat_one_with_stdin_and_existing_path(self) -> None:
         with patch(
             "black.format_stdin_to_stdout",
@@ -1296,6 +1303,7 @@ def test_read_pyproject_toml(self) -> None:
         self.assertEqual(config["exclude"], r"\.pyi?$")
         self.assertEqual(config["include"], r"\.py?$")
 
+    @pytest.mark.incompatible_with_mypyc
     def test_find_project_root(self) -> None:
         with TemporaryDirectory() as workspace:
             root = Path(workspace)
@@ -1483,6 +1491,7 @@ def test_code_option_color_diff(self) -> None:
         assert output == result_diff, "The output did not match the expected value."
         assert result.exit_code == 0, "The exit code is incorrect."
 
+    @pytest.mark.incompatible_with_mypyc
     def test_code_option_safe(self) -> None:
         """Test that the code option throws an error when the sanity checks fail."""
         # Patch black.assert_equivalent to ensure the sanity checks fail
@@ -1507,6 +1516,7 @@ def test_code_option_fast(self) -> None:
 
             self.compare_results(result, formatted, 0)
 
+    @pytest.mark.incompatible_with_mypyc
     def test_code_option_config(self) -> None:
         """
         Test that the code option finds the pyproject.toml in the current directory.
@@ -1527,6 +1537,7 @@ def test_code_option_config(self) -> None:
                 call_args[0].lower() == str(pyproject_path).lower()
             ), "Incorrect config loaded."
 
+    @pytest.mark.incompatible_with_mypyc
     def test_code_option_parent_config(self) -> None:
         """
         Test that the code option finds the pyproject.toml in the parent directory.
@@ -1894,6 +1905,7 @@ def test_extend_exclude(self) -> None:
             src, expected, exclude=r"\.pyi$", extend_exclude=r"\.definitely_exclude"
         )
 
+    @pytest.mark.incompatible_with_mypyc
     def test_symlink_out_of_root_directory(self) -> None:
         path = MagicMock()
         root = THIS_DIR.resolve()
@@ -2047,8 +2059,12 @@ def test_python_2_deprecation_autodetection_extended() -> None:
         }, non_python2_case
 
 
-with open(black.__file__, "r", encoding="utf-8") as _bf:
-    black_source_lines = _bf.readlines()
+try:
+    with open(black.__file__, "r", encoding="utf-8") as _bf:
+        black_source_lines = _bf.readlines()
+except UnicodeDecodeError:
+    if not black.COMPILED:
+        raise
 
 
 def tracefunc(

From 0d1b957d400e2884ad312b4c113ee215effb8256 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Tue, 16 Nov 2021 00:07:25 -0500
Subject: [PATCH 0345/1034] Fix 3.10's supported features (#2614)

---
 src/black/mode.py | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/src/black/mode.py b/src/black/mode.py
index 3c167569498..e2417531240 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -112,6 +112,15 @@ class Feature(Enum):
         Feature.POS_ONLY_ARGUMENTS,
     },
     TargetVersion.PY310: {
+        Feature.UNICODE_LITERALS,
+        Feature.F_STRINGS,
+        Feature.NUMERIC_UNDERSCORES,
+        Feature.TRAILING_COMMA_IN_CALL,
+        Feature.TRAILING_COMMA_IN_DEF,
+        Feature.ASYNC_KEYWORDS,
+        Feature.ASSIGNMENT_EXPRESSIONS,
+        Feature.RELAXED_DECORATORS,
+        Feature.POS_ONLY_ARGUMENTS,
         Feature.PATTERN_MATCHING,
     },
 }

From 7dacdbe6dc0cb1024fcf68dabd6b55a0f7f90cf9 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Tue, 16 Nov 2021 18:22:32 -0800
Subject: [PATCH 0346/1034] fix vim plugin (#2615)

---
 plugin/black.vim | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/plugin/black.vim b/plugin/black.vim
index 90d2047790b..dbe236b5f34 100644
--- a/plugin/black.vim
+++ b/plugin/black.vim
@@ -50,6 +50,13 @@ if !exists("g:black_skip_string_normalization")
     let g:black_skip_string_normalization = 0
   endif
 endif
+if !exists("g:black_skip_magic_trailing_comma")
+  if exists("g:black_magic_trailing_comma")
+    let g:black_skip_magic_trailing_comma = !g:black_magic_trailing_comma
+  else
+    let g:black_skip_magic_trailing_comma = 0
+  endif
+endif
 if !exists("g:black_quiet")
   let g:black_quiet = 0
 endif
@@ -64,6 +71,7 @@ function BlackComplete(ArgLead, CmdLine, CursorPos)
 \    'target_version=py37',
 \    'target_version=py38',
 \    'target_version=py39',
+\    'target_version=py310',
 \  ]
 endfunction
 

From d0b04d9f219a9777cddf82c98f8bc19f578b943e Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Tue, 16 Nov 2021 18:30:19 -0800
Subject: [PATCH 0347/1034] prepare release 21.11b0 (#2616)

---
 CHANGES.md                                  | 2 +-
 docs/integrations/source_version_control.md | 2 +-
 docs/usage_and_configuration/the_basics.md  | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 4e99c9478f1..cd1df15a15a 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,6 +1,6 @@
 # Change Log
 
-## _Unreleased_
+## 21.11b0
 
 ### _Black_
 
diff --git a/docs/integrations/source_version_control.md b/docs/integrations/source_version_control.md
index cf0ef1dfed9..58e3e695522 100644
--- a/docs/integrations/source_version_control.md
+++ b/docs/integrations/source_version_control.md
@@ -7,7 +7,7 @@ Use [pre-commit](https://pre-commit.com/). Once you
 ```yaml
 repos:
   - repo: https://github.com/psf/black
-    rev: 21.10b0
+    rev: 21.11b0
     hooks:
       - id: black
         # It is recommended to specify the latest version of Python
diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index 533c213a4da..bffc45fddb1 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -173,7 +173,7 @@ You can check the version of _Black_ you have installed using the `--version` fl
 
 ```console
 $ black --version
-black, version 21.10b0
+black, version 21.11b0
 ```
 
 An option to require a specific version to be running is also provided.

From ecf8c74481bef13e7a6ca68a953ae470de0d3890 Mon Sep 17 00:00:00 2001
From: Rowan Seymour <rowanseymour@gmail.com>
Date: Wed, 17 Nov 2021 22:46:28 -0500
Subject: [PATCH 0348/1034] Bump regex dependency to 2021.4.4 to fix import of
 Pattern class (#2621)

Fixes #2620
---
 CHANGES.md   |  6 ++++++
 Pipfile      |  2 +-
 Pipfile.lock | 26 +++++++++++++++++++++-----
 setup.py     |  2 +-
 4 files changed, 29 insertions(+), 7 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index cd1df15a15a..9c3be34255d 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,5 +1,11 @@
 # Change Log
 
+## Unreleased
+
+### _Black_
+
+- Bumped regex version minimum to 2021.4.4 to fix Pattern class usage (#2621)
+
 ## 21.11b0
 
 ### _Black_
diff --git a/Pipfile b/Pipfile
index 90e8f62d666..9608f4d4ef7 100644
--- a/Pipfile
+++ b/Pipfile
@@ -42,7 +42,7 @@ platformdirs= ">=2"
 click = ">=8.0.0"
 mypy_extensions = ">=0.4.3"
 pathspec = ">=0.8.1"
-regex = ">=2020.1.8"
+regex = ">=2021.4.4"
 tomli = ">=0.2.6, <2.0.0"
 typed-ast = "==1.4.3"
 typing_extensions = {markers = "python_version < '3.10'", version = ">=3.10.0.0"}
diff --git a/Pipfile.lock b/Pipfile.lock
index 9d0f708bead..a02ea4a2590 100644
--- a/Pipfile.lock
+++ b/Pipfile.lock
@@ -1,7 +1,7 @@
 {
     "_meta": {
         "hash": {
-            "sha256": "4baa020356174f89177af103f1966928e7b9c2a69df3a9d4e8070eb83ee19387"
+            "sha256": "a516705ed9270469fd58d20f1b26a94a6ed052451ef7425d82605b80513a65b3"
         },
         "pipfile-spec": 6,
         "requires": {},
@@ -372,7 +372,7 @@
                 "sha256:c203ec8783bf771a155b207279b9bccb8dea02d8f0c9e5f8ead507bc3246ecc1",
                 "sha256:ef9d7589ef3c200abe66653d3f1ab1033c3c419ae9b9bdb1240a85b024efc88b"
             ],
-            "markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2'",
+            "markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==2.4.7"
         },
         "regex": {
@@ -684,6 +684,14 @@
             ],
             "version": "==0.7.12"
         },
+        "appnope": {
+            "hashes": [
+                "sha256:93aa393e9d6c54c5cd570ccadd8edad61ea0c4b9ea7a01409020c9aa019eb442",
+                "sha256:dd83cd4b5b460958838f6eb3000c660b1f9caf2a5b1de4264e941512f603258a"
+            ],
+            "markers": "sys_platform == 'darwin'",
+            "version": "==0.1.2"
+        },
         "async-timeout": {
             "hashes": [
                 "sha256:a22c0b311af23337eb05fcf05a8b51c3ea53729d46fb5460af62bee033cec690",
@@ -1245,6 +1253,14 @@
             "markers": "python_version >= '3.6'",
             "version": "==2.0.1"
         },
+        "matplotlib-inline": {
+            "hashes": [
+                "sha256:a04bfba22e0d1395479f866853ec1ee28eea1485c1d69a6faf00dc3e24ff34ee",
+                "sha256:aed605ba3b72462d64d475a21a9296f400a19c4f74a31b59103d2a99ffd5aa5c"
+            ],
+            "markers": "python_version >= '3.5'",
+            "version": "==0.1.3"
+        },
         "mccabe": {
             "hashes": [
                 "sha256:ab8a6258860da4b6677da4bd2fe5dc2c659cff31b3ee4f7f5d64e79735b80d42",
@@ -1519,7 +1535,7 @@
                 "sha256:c203ec8783bf771a155b207279b9bccb8dea02d8f0c9e5f8ead507bc3246ecc1",
                 "sha256:ef9d7589ef3c200abe66653d3f1ab1033c3c419ae9b9bdb1240a85b024efc88b"
             ],
-            "markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2'",
+            "markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==2.4.7"
         },
         "pytest": {
@@ -1717,7 +1733,7 @@
                 "sha256:1e61c37477a1626458e36f7b1d82aa5c9b094fa4802892072e49de9c60c4c926",
                 "sha256:8abb2f1d86890a2dfb989f9a77cfcfd3e47c2a354b01111771326f8aa26e0254"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2'",
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==1.16.0"
         },
         "snowballstemmer": {
@@ -1812,7 +1828,7 @@
                 "sha256:806143ae5bfb6a3c6e736a764057db0e6a0e05e338b5630894a5f779cabb4f9b",
                 "sha256:b3bda1d108d5dd99f4a20d24d9c348e91c4db7ab1b749200bded2f839ccbe68f"
             ],
-            "markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2'",
+            "markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==0.10.2"
         },
         "tomli": {
diff --git a/setup.py b/setup.py
index 7022b24345c..33b7239a13e 100644
--- a/setup.py
+++ b/setup.py
@@ -101,7 +101,7 @@ def find_python_files(base: Path) -> List[Path]:
         "platformdirs>=2",
         "tomli>=0.2.6,<2.0.0",
         "typed-ast>=1.4.2; python_version < '3.8' and implementation_name == 'cpython'",
-        "regex>=2020.1.8",
+        "regex>=2021.4.4",
         "pathspec>=0.9.0, <1",
         "dataclasses>=0.6; python_version < '3.7'",
         "typing_extensions>=3.10.0.0",

From 19f6aa8208154de4560ee1e4a3e638e120dcdba5 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Wed, 17 Nov 2021 19:51:49 -0800
Subject: [PATCH 0349/1034] prepare release 2021.11b1 (#2622)

---
 CHANGES.md                                  | 2 +-
 docs/integrations/source_version_control.md | 2 +-
 docs/usage_and_configuration/the_basics.md  | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 9c3be34255d..35024de724d 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,6 +1,6 @@
 # Change Log
 
-## Unreleased
+## 21.11b1
 
 ### _Black_
 
diff --git a/docs/integrations/source_version_control.md b/docs/integrations/source_version_control.md
index 58e3e695522..2149027218d 100644
--- a/docs/integrations/source_version_control.md
+++ b/docs/integrations/source_version_control.md
@@ -7,7 +7,7 @@ Use [pre-commit](https://pre-commit.com/). Once you
 ```yaml
 repos:
   - repo: https://github.com/psf/black
-    rev: 21.11b0
+    rev: 21.11b1
     hooks:
       - id: black
         # It is recommended to specify the latest version of Python
diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index bffc45fddb1..3dc26b7013f 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -173,7 +173,7 @@ You can check the version of _Black_ you have installed using the `--version` fl
 
 ```console
 $ black --version
-black, version 21.11b0
+black, version 21.11b1
 ```
 
 An option to require a specific version to be running is also provided.

From 9a73bb86db59de1e12426fec81dcdb7f3bb9be7b Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Thu, 18 Nov 2021 22:20:44 -0500
Subject: [PATCH 0350/1034] Fix mypyc compat issue w/ AST safety check
 (GH-2628)

I can't wait for when we drop Python 2 support FWIW :)
---
 src/black/parsing.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/black/parsing.py b/src/black/parsing.py
index 504e20be002..32cfa5239f1 100644
--- a/src/black/parsing.py
+++ b/src/black/parsing.py
@@ -169,6 +169,7 @@ def stringify_ast(
 
     yield f"{'  ' * depth}{node.__class__.__name__}("
 
+    type_ignore_classes: Tuple[Type[Any], ...]
     for field in sorted(node._fields):  # noqa: F402
         # TypeIgnore will not be present using pypy < 3.8, so need for this
         if not (_IS_PYPY and sys.version_info < (3, 8)):

From 05954c0950637aa1039d0ac86a4a7e832cbffd9f Mon Sep 17 00:00:00 2001
From: "Matthew D. Scholefield" <matthew331199@gmail.com>
Date: Sat, 20 Nov 2021 11:25:30 -0800
Subject: [PATCH 0351/1034] Fix process pool fallback on Python 3.10 (GH-2631)

In Python 3.10 the exception generated by creating a process pool on
a Python build that doesn't support this is now `NotImplementedError`

Commit history before merge:

* Fix process pool fallback on Python 3.10
* Update CHANGES.md
* Update CHANGES.md

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 CHANGES.md            | 6 ++++++
 src/black/__init__.py | 2 +-
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index 35024de724d..db519ac6bbc 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,5 +1,11 @@
 # Change Log
 
+## Unreleased
+
+### _Black_
+
+- Fixed Python 3.10 support on platforms without ProcessPoolExecutor (#2631)
+
 ## 21.11b1
 
 ### _Black_
diff --git a/src/black/__init__.py b/src/black/__init__.py
index a5ddec91221..aa7970cfd6c 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -687,7 +687,7 @@ def reformat_many(
         worker_count = min(worker_count, 60)
     try:
         executor = ProcessPoolExecutor(max_workers=worker_count)
-    except (ImportError, OSError):
+    except (ImportError, NotImplementedError, OSError):
         # we arrive here if the underlying system does not support multi-processing
         # like in AWS Lambda or Termux, in which case we gracefully fallback to
         # a ThreadPoolExecutor with just a single worker (more workers would not do us

From 40759445c9e5210fb441679d6c0e42921de89ed6 Mon Sep 17 00:00:00 2001
From: Ash <ashisbitt@icloud.com>
Date: Sun, 21 Nov 2021 15:02:08 +0000
Subject: [PATCH 0352/1034] Change `cfg` to `ini` for text highlighting (#2632)

---
 docs/guides/using_black_with_other_tools.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/guides/using_black_with_other_tools.md b/docs/guides/using_black_with_other_tools.md
index 09421819ec3..9938d814073 100644
--- a/docs/guides/using_black_with_other_tools.md
+++ b/docs/guides/using_black_with_other_tools.md
@@ -97,7 +97,7 @@ does not break older versions so you can keep it if you are running previous ver
 <details>
 <summary>.isort.cfg</summary>
 
-```cfg
+```ini
 [settings]
 profile = black
 ```
@@ -107,7 +107,7 @@ profile = black
 <details>
 <summary>setup.cfg</summary>
 
-```cfg
+```ini
 [isort]
 profile = black
 ```
@@ -181,7 +181,7 @@ extend-ignore = E203
 <details>
 <summary>setup.cfg</summary>
 
-```cfg
+```ini
 [flake8]
 max-line-length = 88
 extend-ignore = E203

From dfa45cec9e4991823b06fa655e3e444391fadb65 Mon Sep 17 00:00:00 2001
From: Batuhan Taskaya <isidentical@gmail.com>
Date: Thu, 25 Nov 2021 04:21:36 +0300
Subject: [PATCH 0353/1034] grammar: accept open sequences on match subject
 (GH-2639)

* grammar: accept open sequences on match subject
* give an example about the fixed match subject
---
 CHANGES.md                            |  1 +
 src/blib2to3/Grammar.txt              |  2 +-
 tests/data/pattern_matching_extras.py | 16 ++++++++++++++++
 3 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index db519ac6bbc..94d1c69259a 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -5,6 +5,7 @@
 ### _Black_
 
 - Fixed Python 3.10 support on platforms without ProcessPoolExecutor (#2631)
+- Fixed `match` statements with open sequence subjects, like `match a, b:` (#2639)
 
 ## 21.11b1
 
diff --git a/src/blib2to3/Grammar.txt b/src/blib2to3/Grammar.txt
index c2a62543abb..de9a6a2283f 100644
--- a/src/blib2to3/Grammar.txt
+++ b/src/blib2to3/Grammar.txt
@@ -238,7 +238,7 @@ yield_arg: 'from' test | testlist_star_expr
 # to reformat them.
 
 match_stmt: "match" subject_expr ':' NEWLINE INDENT case_block+ DEDENT
-subject_expr: namedexpr_test
+subject_expr: namedexpr_test (',' namedexpr_test)* [',']
 
 # cases
 case_block: "case" patterns [guard] ':' suite
diff --git a/tests/data/pattern_matching_extras.py b/tests/data/pattern_matching_extras.py
index 614e66aebe6..d4bba38ee7c 100644
--- a/tests/data/pattern_matching_extras.py
+++ b/tests/data/pattern_matching_extras.py
@@ -27,3 +27,19 @@ def func(match: case, case: match) -> case:
             ...
         case func(match, case):
             ...
+
+
+match maybe, multiple:
+    case perhaps, 5:
+        pass
+    case perhaps, 6,:
+        pass
+
+
+match more := (than, one), indeed,:
+    case _, (5, 6):
+        pass
+    case [[5], (6)], [7],:
+        pass
+    case _:
+        pass

From db2715441a391f218863493aa20027f802ab0c7b Mon Sep 17 00:00:00 2001
From: Wael Nasreddine <wael.nasreddine@gmail.com>
Date: Thu, 25 Nov 2021 17:09:47 -0800
Subject: [PATCH 0354/1034] README: Add KeepTruckin to the list of orgs
 (GH-2638)

At KT, we used Black to format all Python code in our Mono-repo.

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index f9061c33863..2adf60a783a 100644
--- a/README.md
+++ b/README.md
@@ -137,8 +137,8 @@ Poetry, PyPA applications (Warehouse, Bandersnatch, Pipenv, virtualenv), pandas,
 Twisted, LocalStack, every Datadog Agent Integration, Home Assistant, Zulip, Kedro, and
 many more.
 
-The following organizations use _Black_: Facebook, Dropbox, Mozilla, Quora, Duolingo,
-QuantumBlack, Tesla.
+The following organizations use _Black_: Facebook, Dropbox, KeepTruckin, Mozilla, Quora,
+Duolingo, QuantumBlack, Tesla.
 
 Are we missing anyone? Let us know.
 

From 17e42cb94b494f0e5d7c80ee842f578a5a3cefcc Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Thu, 25 Nov 2021 18:34:19 -0800
Subject: [PATCH 0355/1034] fix regex (#2643)

---
 tests/test_black.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/tests/test_black.py b/tests/test_black.py
index 3d5d3982817..4267c6110a9 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -31,7 +31,7 @@
 
 import click
 import pytest
-import regex as re
+import re
 from click import unstyle
 from click.testing import CliRunner
 from pathspec import PathSpec
@@ -70,7 +70,7 @@
 R = TypeVar("R")
 
 # Match the time output in a diff, but nothing else
-DIFF_TIME = re.compile(r"\t[\d-:+\. ]+")
+DIFF_TIME = re.compile(r"\t[\d\-:+\. ]+")
 
 
 @contextmanager

From e0253080b0d2b61bf2105a2f5afdf5173e33d0e5 Mon Sep 17 00:00:00 2001
From: Marco Edward Gorelli <marcogorelli@protonmail.com>
Date: Fri, 26 Nov 2021 16:14:57 +0000
Subject: [PATCH 0356/1034]  Assignment to env var in Jupyter Notebook doesn't
 round-trip (#2642)

closes #2641
---
 CHANGES.md                       |  1 +
 src/black/handle_ipynb_magics.py | 27 +++++++++++++++++----------
 tests/test_ipynb.py              |  4 ++++
 3 files changed, 22 insertions(+), 10 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 94d1c69259a..d81c1fd4fc4 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -6,6 +6,7 @@
 
 - Fixed Python 3.10 support on platforms without ProcessPoolExecutor (#2631)
 - Fixed `match` statements with open sequence subjects, like `match a, b:` (#2639)
+- Fixed assignment to environment variables in Jupyter Notebooks (#2642)
 
 ## 21.11b1
 
diff --git a/src/black/handle_ipynb_magics.py b/src/black/handle_ipynb_magics.py
index 2fe6739209d..5807dac14d0 100644
--- a/src/black/handle_ipynb_magics.py
+++ b/src/black/handle_ipynb_magics.py
@@ -403,20 +403,28 @@ def visit_Assign(self, node: ast.Assign) -> None:
         For example,
 
             black_version = !black --version
+            env = %env var
 
-        would have been transformed to
+        would have been (respectively) transformed to
 
             black_version = get_ipython().getoutput('black --version')
+            env = get_ipython().run_line_magic('env', 'var')
 
-        and we look for instances of the latter.
+        and we look for instances of any of the latter.
         """
-        if (
-            isinstance(node.value, ast.Call)
-            and _is_ipython_magic(node.value.func)
-            and node.value.func.attr == "getoutput"
-        ):
-            (arg,) = _get_str_args(node.value.args)
-            src = f"!{arg}"
+        if isinstance(node.value, ast.Call) and _is_ipython_magic(node.value.func):
+            args = _get_str_args(node.value.args)
+            if node.value.func.attr == "getoutput":
+                src = f"!{args[0]}"
+            elif node.value.func.attr == "run_line_magic":
+                src = f"%{args[0]}"
+                if args[1]:
+                    src += f" {args[1]}"
+            else:
+                raise AssertionError(
+                    "Unexpected IPython magic {node.value.func.attr!r} found. "
+                    "Please report a bug on https://github.com/psf/black/issues."
+                ) from None
             self.magics[node.value.lineno].append(
                 OffsetAndMagic(node.value.col_offset, src)
             )
@@ -451,7 +459,6 @@ def visit_Expr(self, node: ast.Expr) -> None:
                 else:
                     src = f"%{args[0]}"
                     if args[1]:
-                        assert src is not None
                         src += f" {args[1]}"
             elif node.value.func.attr == "system":
                 src = f"!{args[0]}"
diff --git a/tests/test_ipynb.py b/tests/test_ipynb.py
index ba460074e9a..5ecdf00b7bc 100644
--- a/tests/test_ipynb.py
+++ b/tests/test_ipynb.py
@@ -90,6 +90,10 @@ def test_cell_magic_noop() -> None:
             id="Line magic with argument",
         ),
         pytest.param("%time\n'foo'", '%time\n"foo"', id="Line magic without argument"),
+        pytest.param(
+            "env =  %env var", "env = %env var", id="Assignment to environment variable"
+        ),
+        pytest.param("env =  %env", "env = %env", id="Assignment to magic"),
     ),
 )
 def test_magic(src: str, expected: str) -> None:

From 72a84d4099f2930979bd1ca1d9e441140b0a304d Mon Sep 17 00:00:00 2001
From: Marco Edward Gorelli <marcogorelli@protonmail.com>
Date: Sat, 27 Nov 2021 02:53:16 +0000
Subject: [PATCH 0357/1034] add missing f-string (#2650)

---
 src/black/handle_ipynb_magics.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/black/handle_ipynb_magics.py b/src/black/handle_ipynb_magics.py
index 5807dac14d0..8ae9d2e2e6c 100644
--- a/src/black/handle_ipynb_magics.py
+++ b/src/black/handle_ipynb_magics.py
@@ -422,7 +422,7 @@ def visit_Assign(self, node: ast.Assign) -> None:
                     src += f" {args[1]}"
             else:
                 raise AssertionError(
-                    "Unexpected IPython magic {node.value.func.attr!r} found. "
+                    f"Unexpected IPython magic {node.value.func.attr!r} found. "
                     "Please report a bug on https://github.com/psf/black/issues."
                 ) from None
             self.magics[node.value.lineno].append(

From a18ee4018f855007bf4a23027a8d6478e56a36bf Mon Sep 17 00:00:00 2001
From: danieleades <33452915+danieleades@users.noreply.github.com>
Date: Mon, 29 Nov 2021 02:20:52 +0000
Subject: [PATCH 0358/1034] add more flake8 lints (#2653)

---
 .pre-commit-config.yaml | 5 ++++-
 CHANGES.md              | 1 +
 src/black/__init__.py   | 2 +-
 src/black/output.py     | 4 ++--
 tests/optional.py       | 2 +-
 tests/test_black.py     | 2 +-
 6 files changed, 10 insertions(+), 6 deletions(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index a3cd6639384..45810d2844a 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -35,7 +35,10 @@ repos:
     rev: 3.9.2
     hooks:
       - id: flake8
-        additional_dependencies: [flake8-bugbear]
+        additional_dependencies:
+          - flake8-bugbear
+          - flake8-comprehensions
+          - flake8-simplify
 
   - repo: https://github.com/pre-commit/mirrors-mypy
     rev: v0.910
diff --git a/CHANGES.md b/CHANGES.md
index d81c1fd4fc4..235919ec7ac 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -7,6 +7,7 @@
 - Fixed Python 3.10 support on platforms without ProcessPoolExecutor (#2631)
 - Fixed `match` statements with open sequence subjects, like `match a, b:` (#2639)
 - Fixed assignment to environment variables in Jupyter Notebooks (#2642)
+- Add `flake8-simplify` and `flake8-comprehensions` plugins (#2653)
 
 ## 21.11b1
 
diff --git a/src/black/__init__.py b/src/black/__init__.py
index aa7970cfd6c..d99c48a1b04 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -181,7 +181,7 @@ def validate_regex(
 
 
 @click.command(
-    context_settings=dict(help_option_names=["-h", "--help"]),
+    context_settings={"help_option_names": ["-h", "--help"]},
     # While Click does set this field automatically using the docstring, mypyc
     # (annoyingly) strips 'em so we need to set it here too.
     help="The uncompromising code formatter.",
diff --git a/src/black/output.py b/src/black/output.py
index c85b253c159..f030d0a0d08 100644
--- a/src/black/output.py
+++ b/src/black/output.py
@@ -59,8 +59,8 @@ def diff(a: str, b: str, a_name: str, b_name: str) -> str:
     """Return a unified diff string between strings `a` and `b`."""
     import difflib
 
-    a_lines = [line for line in a.splitlines(keepends=True)]
-    b_lines = [line for line in b.splitlines(keepends=True)]
+    a_lines = a.splitlines(keepends=True)
+    b_lines = b.splitlines(keepends=True)
     diff_lines = []
     for line in difflib.unified_diff(
         a_lines, b_lines, fromfile=a_name, tofile=b_name, n=5
diff --git a/tests/optional.py b/tests/optional.py
index e12b94cd29e..1cddeeaa576 100644
--- a/tests/optional.py
+++ b/tests/optional.py
@@ -96,7 +96,7 @@ def pytest_collection_modifyitems(config: "Config", items: "List[Node]") -> None
     enabled_optional_markers = store[ENABLED_OPTIONAL_MARKERS]
 
     for item in items:
-        all_markers_on_test = set(m.name for m in item.iter_markers())
+        all_markers_on_test = {m.name for m in item.iter_markers()}
         optional_markers_on_test = all_markers_on_test & all_possible_optional_markers
         if not optional_markers_on_test or (
             optional_markers_on_test & enabled_optional_markers
diff --git a/tests/test_black.py b/tests/test_black.py
index 4267c6110a9..51a20307e56 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -1755,7 +1755,7 @@ def assert_collected_sources(
         report=black.Report(),
         stdin_filename=stdin_filename,
     )
-    assert sorted(list(collected)) == sorted(gs_expected)
+    assert sorted(collected) == sorted(gs_expected)
 
 
 class TestFileCollection:

From a066a2bc8b1b7d87b2029f5ebd684582231b0bbc Mon Sep 17 00:00:00 2001
From: Daniel Sparing <dsparing@google.com>
Date: Mon, 29 Nov 2021 18:07:35 -0500
Subject: [PATCH 0359/1034] Return `NothingChanged` if non-Python cell magic is
 detected, to avoid tokenize error (#2630)

Fixes https://github.com/psf/black/issues/2627 , a non-Python cell magic such as `%%writeline` can legitimately contain "incorrect" indentation, however this causes `tokenize-rt` to return an error. To avoid this, `validate_cell` should early detect cell magics (just like it detects `TransformerManager` transformations).

Test added too, in the shape of a "badly indented" `%%writefile` within `test_non_python_magics`.

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Co-authored-by: Marco Edward Gorelli <marcogorelli@protonmail.com>
---
 CHANGES.md                       |  3 +++
 docs/faq.md                      |  1 +
 src/black/__init__.py            |  7 ++++++-
 src/black/handle_ipynb_magics.py | 23 ++++++++---------------
 tests/test_ipynb.py              |  5 +++--
 5 files changed, 21 insertions(+), 18 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 235919ec7ac..57af2c5deae 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -4,6 +4,9 @@
 
 ### _Black_
 
+- Cell magics are now only processed if they are known Python cell magics. Earlier, all
+  cell magics were tokenized, leading to possible indentation errors e.g. with
+  `%%writefile`. (#2630)
 - Fixed Python 3.10 support on platforms without ProcessPoolExecutor (#2631)
 - Fixed `match` statements with open sequence subjects, like `match a, b:` (#2639)
 - Fixed assignment to environment variables in Jupyter Notebooks (#2642)
diff --git a/docs/faq.md b/docs/faq.md
index 72bae6b389d..88bf35b1e6a 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -47,6 +47,7 @@ _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`)
 - multiline magics, e.g.:
 
   ```python
diff --git a/src/black/__init__.py b/src/black/__init__.py
index d99c48a1b04..c2b52e6eadb 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -57,6 +57,7 @@
     remove_trailing_semicolon,
     put_trailing_semicolon_back,
     TRANSFORMED_MAGICS,
+    PYTHON_CELL_MAGICS,
     jupyter_dependencies_are_installed,
 )
 
@@ -943,7 +944,9 @@ def format_file_contents(src_contents: str, *, fast: bool, mode: Mode) -> FileCo
 
 
 def validate_cell(src: str) -> None:
-    """Check that cell does not already contain TransformerManager transformations.
+    """Check that cell does not already contain TransformerManager transformations,
+    or non-Python cell magics, which might cause tokenizer_rt to break because of
+    indentations.
 
     If a cell contains ``!ls``, then it'll be transformed to
     ``get_ipython().system('ls')``. However, if the cell originally contained
@@ -959,6 +962,8 @@ def validate_cell(src: str) -> None:
     """
     if any(transformed_magic in src for transformed_magic in TRANSFORMED_MAGICS):
         raise NothingChanged
+    if src[:2] == "%%" and src.split()[0][2:] not in PYTHON_CELL_MAGICS:
+        raise NothingChanged
 
 
 def format_cell(src: str, *, fast: bool, mode: Mode) -> str:
diff --git a/src/black/handle_ipynb_magics.py b/src/black/handle_ipynb_magics.py
index 8ae9d2e2e6c..a0ed56baafc 100644
--- a/src/black/handle_ipynb_magics.py
+++ b/src/black/handle_ipynb_magics.py
@@ -37,20 +37,15 @@
         "ESCAPED_NL",
     )
 )
-NON_PYTHON_CELL_MAGICS = frozenset(
+PYTHON_CELL_MAGICS = frozenset(
     (
-        "bash",
-        "html",
-        "javascript",
-        "js",
-        "latex",
-        "markdown",
-        "perl",
-        "ruby",
-        "script",
-        "sh",
-        "svg",
-        "writefile",
+        "capture",
+        "prun",
+        "pypy",
+        "python",
+        "python3",
+        "time",
+        "timeit",
     )
 )
 TOKEN_HEX = secrets.token_hex
@@ -230,8 +225,6 @@ def replace_cell_magics(src: str) -> Tuple[str, List[Replacement]]:
     cell_magic_finder.visit(tree)
     if cell_magic_finder.cell_magic is None:
         return src, replacements
-    if cell_magic_finder.cell_magic.name in NON_PYTHON_CELL_MAGICS:
-        raise NothingChanged
     header = cell_magic_finder.cell_magic.header
     mask = get_token(src, header)
     replacements.append(Replacement(mask=mask, src=header))
diff --git a/tests/test_ipynb.py b/tests/test_ipynb.py
index 5ecdf00b7bc..141e865815a 100644
--- a/tests/test_ipynb.py
+++ b/tests/test_ipynb.py
@@ -106,6 +106,7 @@ def test_magic(src: str, expected: str) -> None:
     (
         "%%bash\n2+2",
         "%%html --isolated\n2+2",
+        "%%writefile e.txt\n  meh\n meh",
     ),
 )
 def test_non_python_magics(src: str) -> None:
@@ -132,9 +133,9 @@ def test_magic_noop() -> None:
 
 
 def test_cell_magic_with_magic() -> None:
-    src = "%%t -n1\nls =!ls"
+    src = "%%timeit -n1\nls =!ls"
     result = format_cell(src, fast=True, mode=JUPYTER_MODE)
-    expected = "%%t -n1\nls = !ls"
+    expected = "%%timeit -n1\nls = !ls"
     assert result == expected
 
 

From 8cdac18a04b64376e87c716cb9c2eafd182e63ff Mon Sep 17 00:00:00 2001
From: Batuhan Taskaya <isidentical@gmail.com>
Date: Tue, 30 Nov 2021 18:52:25 +0300
Subject: [PATCH 0360/1034] Allow top-level starred expression on match (#2659)

Fixes #2647
---
 CHANGES.md                            | 3 ++-
 src/blib2to3/Grammar.txt              | 6 +++++-
 tests/data/pattern_matching_extras.py | 7 +++++++
 3 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 57af2c5deae..4a8ee0e692c 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -8,7 +8,8 @@
   cell magics were tokenized, leading to possible indentation errors e.g. with
   `%%writefile`. (#2630)
 - Fixed Python 3.10 support on platforms without ProcessPoolExecutor (#2631)
-- Fixed `match` statements with open sequence subjects, like `match a, b:` (#2639)
+- Fixed `match` statements with open sequence subjects, like `match a, b:` or
+  `match a, *b:` (#2639) (#2659)
 - Fixed assignment to environment variables in Jupyter Notebooks (#2642)
 - Add `flake8-simplify` and `flake8-comprehensions` plugins (#2653)
 
diff --git a/src/blib2to3/Grammar.txt b/src/blib2to3/Grammar.txt
index de9a6a2283f..c3001e81065 100644
--- a/src/blib2to3/Grammar.txt
+++ b/src/blib2to3/Grammar.txt
@@ -238,7 +238,11 @@ yield_arg: 'from' test | testlist_star_expr
 # to reformat them.
 
 match_stmt: "match" subject_expr ':' NEWLINE INDENT case_block+ DEDENT
-subject_expr: namedexpr_test (',' namedexpr_test)* [',']
+
+# This is more permissive than the actual version. For example it
+# accepts `match *something:`, even though single-item starred expressions
+# are forbidden.
+subject_expr: (namedexpr_test|star_expr) (',' (namedexpr_test|star_expr))* [',']
 
 # cases
 case_block: "case" patterns [guard] ':' suite
diff --git a/tests/data/pattern_matching_extras.py b/tests/data/pattern_matching_extras.py
index d4bba38ee7c..706148561a2 100644
--- a/tests/data/pattern_matching_extras.py
+++ b/tests/data/pattern_matching_extras.py
@@ -43,3 +43,10 @@ def func(match: case, case: match) -> case:
         pass
     case _:
         pass
+
+
+match a, *b, c:
+    case [*_]:
+        return "seq"
+    case {}:
+        return "map"

From e151686c6fc291a72058a26de8e6279669d756cc Mon Sep 17 00:00:00 2001
From: Jameel Al-Aziz <247849+jalaziz@users.noreply.github.com>
Date: Tue, 30 Nov 2021 08:20:27 -0800
Subject: [PATCH 0361/1034] Remove hidden import from PyInstaller build (#2657)

The recent 2021.4 release of pyinstaller-hooks-contrib now contains a
built-in hook for platformdirs. Manually specifying the hidden import
arg should no longer be needed.
---
 .github/workflows/upload_binary.yml | 9 ++-------
 1 file changed, 2 insertions(+), 7 deletions(-)

diff --git a/.github/workflows/upload_binary.yml b/.github/workflows/upload_binary.yml
index 8f44d4ec27b..766f37cc321 100644
--- a/.github/workflows/upload_binary.yml
+++ b/.github/workflows/upload_binary.yml
@@ -16,17 +16,14 @@ jobs:
             pathsep: ";"
             asset_name: black_windows.exe
             executable_mime: "application/vnd.microsoft.portable-executable"
-            platform: windows
           - os: ubuntu-20.04
             pathsep: ":"
             asset_name: black_linux
             executable_mime: "application/x-executable"
-            platform: unix
           - os: macos-latest
             pathsep: ":"
             asset_name: black_macos
             executable_mime: "application/x-mach-binary"
-            platform: macos
 
     steps:
       - uses: actions/checkout@v2
@@ -43,10 +40,8 @@ jobs:
           python -m pip install pyinstaller
 
       - name: Build binary
-        run: >
-          python -m PyInstaller -F --name ${{ matrix.asset_name }} --add-data
-          'src/blib2to3${{ matrix.pathsep }}blib2to3' --hidden-import platformdirs.${{
-          matrix.platform }} src/black/__main__.py
+        run: |
+          python -m PyInstaller -F --name ${{ matrix.asset_name }} --add-data 'src/blib2to3${{ matrix.pathsep }}blib2to3' src/black/__main__.py
 
       - name: Upload binary as release asset
         uses: actions/upload-release-asset@v1

From ebd3e391dab8d97ce7dbd837473641ddd5fb51c0 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Tue, 30 Nov 2021 12:34:45 -0800
Subject: [PATCH 0362/1034] add FAQ entry about undetected syntax errors
 (#2645)

This came up in #2644.
---
 docs/faq.md | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/docs/faq.md b/docs/faq.md
index 88bf35b1e6a..0a966c99c7f 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -94,7 +94,14 @@ them in the right place, this detection is not and cannot be perfect. Therefore,
 sometimes have to manually move these comments to the right place after you format your
 codebase with _Black_.
 
-## Can I run black with PyPy?
+## Can I run Black with PyPy?
 
 Yes, there is support for PyPy 3.7 and higher. You cannot format Python 2 files under
 PyPy, because PyPy's inbuilt ast module does not support this.
+
+## Why does Black not detect syntax errors in my code?
+
+_Black_ is an autoformatter, not a Python linter or interpreter. Detecting all syntax
+errors is not a goal. It can format all code accepted by CPython (if you find an example
+where that doesn't hold, please report a bug!), but it may also format some code that
+CPython doesn't accept.

From b336b390d0613348e6208b392e41e5512b0a85be Mon Sep 17 00:00:00 2001
From: Batuhan Taskaya <isidentical@gmail.com>
Date: Tue, 30 Nov 2021 23:56:38 +0300
Subject: [PATCH 0363/1034] Fix line generation for `match match:` / `case
 case:` (GH-2661)

---
 CHANGES.md                            |  2 ++
 src/black/linegen.py                  | 14 ++++++++---
 tests/data/pattern_matching_extras.py | 35 ++++++++++++++++++++++++---
 3 files changed, 44 insertions(+), 7 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 4a8ee0e692c..85feb1a7600 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -10,6 +10,8 @@
 - Fixed Python 3.10 support on platforms without ProcessPoolExecutor (#2631)
 - Fixed `match` statements with open sequence subjects, like `match a, b:` or
   `match a, *b:` (#2639) (#2659)
+- Fixed `match`/`case` statements that contain `match`/`case` soft keywords multiple
+  times, like `match re.match()` (#2661)
 - Fixed assignment to environment variables in Jupyter Notebooks (#2642)
 - Add `flake8-simplify` and `flake8-comprehensions` plugins (#2653)
 
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 4cba4164fb3..f234913a161 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -127,7 +127,7 @@ def visit_stmt(
         """Visit a statement.
 
         This implementation is shared for `if`, `while`, `for`, `try`, `except`,
-        `def`, `with`, `class`, `assert`, `match`, `case` and assignments.
+        `def`, `with`, `class`, `assert`, and assignments.
 
         The relevant Python language `keywords` for a given statement will be
         NAME leaves within it. This methods puts those on a separate line.
@@ -142,6 +142,14 @@ def visit_stmt(
 
             yield from self.visit(child)
 
+    def visit_match_case(self, node: Node) -> Iterator[Line]:
+        """Visit either a match or case statement."""
+        normalize_invisible_parens(node, parens_after=set())
+
+        yield from self.line()
+        for child in node.children:
+            yield from self.visit(child)
+
     def visit_suite(self, node: Node) -> Iterator[Line]:
         """Visit a suite."""
         if self.mode.is_pyi and is_stub_suite(node):
@@ -294,8 +302,8 @@ def __post_init__(self) -> None:
         self.visit_decorated = self.visit_decorators
 
         # PEP 634
-        self.visit_match_stmt = partial(v, keywords={"match"}, parens=Ø)
-        self.visit_case_block = partial(v, keywords={"case"}, parens=Ø)
+        self.visit_match_stmt = self.visit_match_case
+        self.visit_case_block = self.visit_match_case
 
 
 def transform_line(
diff --git a/tests/data/pattern_matching_extras.py b/tests/data/pattern_matching_extras.py
index 706148561a2..095c1a2b3bb 100644
--- a/tests/data/pattern_matching_extras.py
+++ b/tests/data/pattern_matching_extras.py
@@ -23,10 +23,10 @@
 
 def func(match: case, case: match) -> case:
     match Something():
-        case another:
-            ...
         case func(match, case):
             ...
+        case another:
+            ...
 
 
 match maybe, multiple:
@@ -47,6 +47,33 @@ def func(match: case, case: match) -> case:
 
 match a, *b, c:
     case [*_]:
-        return "seq"
+        assert "seq" == _
     case {}:
-        return "map"
+        assert "map" == b
+
+
+match match(
+    case,
+    match(
+        match, case, match, looooooooooooooooooooooooooooooooooooong, match, case, match
+    ),
+    case,
+):
+    case case(
+        match=case,
+        case=re.match(
+            loooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong
+        ),
+    ):
+        pass
+
+    case [a as match]:
+        pass
+
+    case case:
+        pass
+
+
+match match:
+    case case:
+        pass

From 5e2bb528e09df368ed7dea6b7fb9c53e799a569f Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Tue, 30 Nov 2021 18:01:36 -0800
Subject: [PATCH 0364/1034] Reduce usage of regex (#2644)

This removes all but one usage of the `regex` dependency. Tricky bits included:
- A bug in test_black.py where we were incorrectly using a character range. Fix also submitted separately in #2643.
- `tokenize.py` was the original use case for regex (#1047). The important bit is that we rely on `\w` to match anything valid in an identifier, and `re` fails to match a few characters as part of identifiers. My solution is to instead match all characters *except* those we know to mean something else in Python: whitespace and ASCII punctuation. This will make Black able to parse some invalid Python programs, like those that contain non-ASCII punctuation in the place of an identifier, but that seems fine to me.
- One import of `regex` remains, in `trans.py`. We use a recursive regex to parse f-strings, and only `regex` supports that. I haven't thought of a better fix there (except maybe writing a manual parser), so I'm leaving that for now.

My goal is to remove the `regex` dependency to reduce the risk of breakage due to dependencies and make life easier for users on platforms without wheels.
---
 CHANGES.md                     | 9 +++++----
 src/black/__init__.py          | 2 +-
 src/black/comments.py          | 2 +-
 src/black/strings.py           | 4 ++--
 src/black/trans.py             | 2 +-
 src/blib2to3/pgen2/conv.py     | 2 +-
 src/blib2to3/pgen2/tokenize.py | 4 ++--
 7 files changed, 13 insertions(+), 12 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 85feb1a7600..7214405c429 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -7,12 +7,13 @@
 - Cell magics are now only processed if they are known Python cell magics. Earlier, all
   cell magics were tokenized, leading to possible indentation errors e.g. with
   `%%writefile`. (#2630)
-- Fixed Python 3.10 support on platforms without ProcessPoolExecutor (#2631)
-- Fixed `match` statements with open sequence subjects, like `match a, b:` or
+- Fix Python 3.10 support on platforms without ProcessPoolExecutor (#2631)
+- Reduce usage of the `regex` dependency (#2644)
+- Fix `match` statements with open sequence subjects, like `match a, b:` or
   `match a, *b:` (#2639) (#2659)
-- Fixed `match`/`case` statements that contain `match`/`case` soft keywords multiple
+- Fix `match`/`case` statements that contain `match`/`case` soft keywords multiple
   times, like `match re.match()` (#2661)
-- Fixed assignment to environment variables in Jupyter Notebooks (#2642)
+- Fix assignment to environment variables in Jupyter Notebooks (#2642)
 - Add `flake8-simplify` and `flake8-comprehensions` plugins (#2653)
 
 ## 21.11b1
diff --git a/src/black/__init__.py b/src/black/__init__.py
index c2b52e6eadb..1923c069ede 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -10,7 +10,7 @@
 import os
 from pathlib import Path
 from pathspec.patterns.gitwildmatch import GitWildMatchPatternError
-import regex as re
+import re
 import signal
 import sys
 import tokenize
diff --git a/src/black/comments.py b/src/black/comments.py
index a8152d687a3..28b9117101d 100644
--- a/src/black/comments.py
+++ b/src/black/comments.py
@@ -1,7 +1,7 @@
 import sys
 from dataclasses import dataclass
 from functools import lru_cache
-import regex as re
+import re
 from typing import Iterator, List, Optional, Union
 
 if sys.version_info >= (3, 8):
diff --git a/src/black/strings.py b/src/black/strings.py
index 97debe3b5de..06a5da01f0c 100644
--- a/src/black/strings.py
+++ b/src/black/strings.py
@@ -2,7 +2,7 @@
 Simple formatting on strings. Further string formatting code is in trans.py.
 """
 
-import regex as re
+import re
 import sys
 from functools import lru_cache
 from typing import List, Pattern
@@ -156,7 +156,7 @@ def normalize_string_prefix(s: str, remove_u_prefix: bool = False) -> str:
 # performance on a long list literal of strings by 5-9% since lru_cache's
 # caching overhead is much lower.
 @lru_cache(maxsize=64)
-def _cached_compile(pattern: str) -> re.Pattern:
+def _cached_compile(pattern: str) -> Pattern[str]:
     return re.compile(pattern)
 
 
diff --git a/src/black/trans.py b/src/black/trans.py
index d918ef111a2..a4d1e6fbc79 100644
--- a/src/black/trans.py
+++ b/src/black/trans.py
@@ -4,7 +4,7 @@
 from abc import ABC, abstractmethod
 from collections import defaultdict
 from dataclasses import dataclass
-import regex as re
+import regex as re  # We need recursive patterns here (?R)
 from typing import (
     Any,
     Callable,
diff --git a/src/blib2to3/pgen2/conv.py b/src/blib2to3/pgen2/conv.py
index 78165217a1b..fa9825e54d6 100644
--- a/src/blib2to3/pgen2/conv.py
+++ b/src/blib2to3/pgen2/conv.py
@@ -29,7 +29,7 @@
 """
 
 # Python imports
-import regex as re
+import re
 
 # Local imports
 from pgen2 import grammar, token
diff --git a/src/blib2to3/pgen2/tokenize.py b/src/blib2to3/pgen2/tokenize.py
index 283fac2d537..a7e17df1e8f 100644
--- a/src/blib2to3/pgen2/tokenize.py
+++ b/src/blib2to3/pgen2/tokenize.py
@@ -52,7 +52,7 @@
 __author__ = "Ka-Ping Yee <ping@lfw.org>"
 __credits__ = "GvR, ESR, Tim Peters, Thomas Wouters, Fred Drake, Skip Montanaro"
 
-import regex as re
+import re
 from codecs import BOM_UTF8, lookup
 from blib2to3.pgen2.token import *
 
@@ -86,7 +86,7 @@ def _combinations(*l):
 Comment = r"#[^\r\n]*"
 Ignore = Whitespace + any(r"\\\r?\n" + Whitespace) + maybe(Comment)
 Name = (  # this is invalid but it's fine because Name comes after Number in all groups
-    r"\w+"
+    r"[^\s#\(\)\[\]\{\}+\-*/!@$%^&=|;:'\",\.<>/?`~\\]+"
 )
 
 Binnumber = r"0[bB]_?[01]+(?:_[01]+)*"

From 0f7cf9187f9c9644565570a67a66f690f8f2bfbb Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Tue, 30 Nov 2021 18:39:39 -0800
Subject: [PATCH 0365/1034] fix error message for match (#2649)

Fixes #2648.

Co-authored-by: Batuhan Taskaya <isidentical@gmail.com>
---
 CHANGES.md                             |  1 +
 src/black/parsing.py                   |  6 ++++--
 tests/data/pattern_matching_invalid.py | 18 ++++++++++++++++++
 tests/test_format.py                   |  9 +++++++++
 4 files changed, 32 insertions(+), 2 deletions(-)
 create mode 100644 tests/data/pattern_matching_invalid.py

diff --git a/CHANGES.md b/CHANGES.md
index 7214405c429..c0cf60af98a 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -15,6 +15,7 @@
   times, like `match re.match()` (#2661)
 - Fix assignment to environment variables in Jupyter Notebooks (#2642)
 - Add `flake8-simplify` and `flake8-comprehensions` plugins (#2653)
+- Fix parser error location on invalid syntax in a `match` statement (#2649)
 
 ## 21.11b1
 
diff --git a/src/black/parsing.py b/src/black/parsing.py
index 32cfa5239f1..e38405637cd 100644
--- a/src/black/parsing.py
+++ b/src/black/parsing.py
@@ -75,8 +75,10 @@ def get_grammars(target_versions: Set[TargetVersion]) -> List[Grammar]:
         # Python 3.10+
         grammars.append(pygram.python_grammar_soft_keywords)
     # If we have to parse both, try to parse async as a keyword first
-    if not supports_feature(target_versions, Feature.ASYNC_IDENTIFIERS):
-        # Python 3.7+
+    if not supports_feature(
+        target_versions, Feature.ASYNC_IDENTIFIERS
+    ) and not supports_feature(target_versions, Feature.PATTERN_MATCHING):
+        # Python 3.7-3.9
         grammars.append(
             pygram.python_grammar_no_print_statement_no_exec_statement_async_keywords
         )
diff --git a/tests/data/pattern_matching_invalid.py b/tests/data/pattern_matching_invalid.py
new file mode 100644
index 00000000000..22b5b94c0a4
--- /dev/null
+++ b/tests/data/pattern_matching_invalid.py
@@ -0,0 +1,18 @@
+# First match, no errors
+match something:
+    case bla():
+        pass
+
+# Problem on line 10
+match invalid_case:
+    case valid_case:
+        pass
+    case a := b:
+        pass
+    case valid_case:
+        pass
+
+# No problems either
+match something:
+    case bla():
+        pass
diff --git a/tests/test_format.py b/tests/test_format.py
index 8f8ffb3610e..f97d7165b1a 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -200,6 +200,15 @@ def test_python_310(filename: str) -> None:
     assert_format(source, expected, mode, minimum_version=(3, 10))
 
 
+def test_patma_invalid() -> None:
+    source, expected = read_data("pattern_matching_invalid")
+    mode = black.Mode(target_versions={black.TargetVersion.PY310})
+    with pytest.raises(black.parsing.InvalidInput) as exc_info:
+        assert_format(source, expected, mode, minimum_version=(3, 10))
+
+    exc_info.match("Cannot parse: 10:11")
+
+
 def test_docstring_no_string_normalization() -> None:
     """Like test_docstring but with string normalization off."""
     source, expected = read_data("docstring_no_string_normalization")

From f1813e31b6deed0901c8a7fb1f102b9af53de351 Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Wed, 1 Dec 2021 09:52:24 -0800
Subject: [PATCH 0366/1034] Fix determination of f-string expression spans
 (#2654)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 CHANGES.md          |  1 +
 src/black/trans.py  | 72 ++++++++++++++++++++++++++++++++++-----------
 tests/test_trans.py | 50 +++++++++++++++++++++++++++++++
 3 files changed, 106 insertions(+), 17 deletions(-)
 create mode 100644 tests/test_trans.py

diff --git a/CHANGES.md b/CHANGES.md
index c0cf60af98a..5b648225ad7 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -15,6 +15,7 @@
   times, like `match re.match()` (#2661)
 - Fix assignment to environment variables in Jupyter Notebooks (#2642)
 - Add `flake8-simplify` and `flake8-comprehensions` plugins (#2653)
+- Fix determination of f-string expression spans (#2654)
 - Fix parser error location on invalid syntax in a `match` statement (#2649)
 
 ## 21.11b1
diff --git a/src/black/trans.py b/src/black/trans.py
index a4d1e6fbc79..6aca3a8733f 100644
--- a/src/black/trans.py
+++ b/src/black/trans.py
@@ -942,6 +942,57 @@ def _get_max_string_length(self, line: Line, string_idx: int) -> int:
         return max_string_length
 
 
+def iter_fexpr_spans(s: str) -> Iterator[Tuple[int, int]]:
+    """
+    Yields spans corresponding to expressions in a given f-string.
+    Spans are half-open ranges (left inclusive, right exclusive).
+    Assumes the input string is a valid f-string, but will not crash if the input
+    string is invalid.
+    """
+    stack: List[int] = []  # our curly paren stack
+    i = 0
+    while i < len(s):
+        if s[i] == "{":
+            # if we're in a string part of the f-string, ignore escaped curly braces
+            if not stack and i + 1 < len(s) and s[i + 1] == "{":
+                i += 2
+                continue
+            stack.append(i)
+            i += 1
+            continue
+
+        if s[i] == "}":
+            if not stack:
+                i += 1
+                continue
+            j = stack.pop()
+            # we've made it back out of the expression! yield the span
+            if not stack:
+                yield (j, i + 1)
+            i += 1
+            continue
+
+        # if we're in an expression part of the f-string, fast forward through strings
+        # note that backslashes are not legal in the expression portion of f-strings
+        if stack:
+            delim = None
+            if s[i : i + 3] in ("'''", '"""'):
+                delim = s[i : i + 3]
+            elif s[i] in ("'", '"'):
+                delim = s[i]
+            if delim:
+                i += len(delim)
+                while i < len(s) and s[i : i + len(delim)] != delim:
+                    i += 1
+                i += len(delim)
+                continue
+        i += 1
+
+
+def fstring_contains_expr(s: str) -> bool:
+    return any(iter_fexpr_spans(s))
+
+
 class StringSplitter(BaseStringSplitter, CustomSplitMapMixin):
     """
     StringTransformer that splits "atom" strings (i.e. strings which exist on
@@ -981,17 +1032,6 @@ class StringSplitter(BaseStringSplitter, CustomSplitMapMixin):
     """
 
     MIN_SUBSTR_SIZE: Final = 6
-    # Matches an "f-expression" (e.g. {var}) that might be found in an f-string.
-    RE_FEXPR: Final = r"""
-    (?<!\{) (?:\{\{)* \{ (?!\{)
-        (?:
-            [^\{\}]
-            | \{\{
-            | \}\}
-            | (?R)
-        )+
-    \}
-    """
 
     def do_splitter_match(self, line: Line) -> TMatchResult:
         LL = line.leaves
@@ -1058,8 +1098,8 @@ def do_transform(self, line: Line, string_idx: int) -> Iterator[TResult[Line]]:
         # contain any f-expressions, but ONLY if the original f-string
         # contains at least one f-expression. Otherwise, we will alter the AST
         # of the program.
-        drop_pointless_f_prefix = ("f" in prefix) and re.search(
-            self.RE_FEXPR, LL[string_idx].value, re.VERBOSE
+        drop_pointless_f_prefix = ("f" in prefix) and fstring_contains_expr(
+            LL[string_idx].value
         )
 
         first_string_line = True
@@ -1299,9 +1339,7 @@ def _iter_fexpr_slices(self, string: str) -> Iterator[Tuple[Index, Index]]:
         """
         if "f" not in get_string_prefix(string).lower():
             return
-
-        for match in re.finditer(self.RE_FEXPR, string, re.VERBOSE):
-            yield match.span()
+        yield from iter_fexpr_spans(string)
 
     def _get_illegal_split_indices(self, string: str) -> Set[Index]:
         illegal_indices: Set[Index] = set()
@@ -1417,7 +1455,7 @@ def _normalize_f_string(self, string: str, prefix: str) -> str:
         """
         assert_is_leaf_string(string)
 
-        if "f" in prefix and not re.search(self.RE_FEXPR, string, re.VERBOSE):
+        if "f" in prefix and not fstring_contains_expr(string):
             new_prefix = prefix.replace("f", "")
 
             temp = string[len(prefix) :]
diff --git a/tests/test_trans.py b/tests/test_trans.py
new file mode 100644
index 00000000000..a1666a9c166
--- /dev/null
+++ b/tests/test_trans.py
@@ -0,0 +1,50 @@
+from typing import List, Tuple
+from black.trans import iter_fexpr_spans
+
+
+def test_fexpr_spans() -> None:
+    def check(
+        string: str, expected_spans: List[Tuple[int, int]], expected_slices: List[str]
+    ) -> None:
+        spans = list(iter_fexpr_spans(string))
+
+        # Checking slices isn't strictly necessary, but it's easier to verify at
+        # a glance than only spans
+        assert len(spans) == len(expected_slices)
+        for (i, j), slice in zip(spans, expected_slices):
+            assert len(string[i:j]) == j - i
+            assert string[i:j] == slice
+
+        assert spans == expected_spans
+
+    # Most of these test cases omit the leading 'f' and leading / closing quotes
+    # for convenience
+    # Some additional property-based tests can be found in
+    # https://github.com/psf/black/pull/2654#issuecomment-981411748
+    check("""{var}""", [(0, 5)], ["{var}"])
+    check("""f'{var}'""", [(2, 7)], ["{var}"])
+    check("""f'{1 + f() + 2 + "asdf"}'""", [(2, 24)], ["""{1 + f() + 2 + "asdf"}"""])
+    check("""text {var} text""", [(5, 10)], ["{var}"])
+    check("""text {{ {var} }} text""", [(8, 13)], ["{var}"])
+    check("""{a} {b} {c}""", [(0, 3), (4, 7), (8, 11)], ["{a}", "{b}", "{c}"])
+    check("""f'{a} {b} {c}'""", [(2, 5), (6, 9), (10, 13)], ["{a}", "{b}", "{c}"])
+    check("""{ {} }""", [(0, 6)], ["{ {} }"])
+    check("""{ {{}} }""", [(0, 8)], ["{ {{}} }"])
+    check("""{ {{{}}} }""", [(0, 10)], ["{ {{{}}} }"])
+    check("""{{ {{{}}} }}""", [(5, 7)], ["{}"])
+    check("""{{ {{{var}}} }}""", [(5, 10)], ["{var}"])
+    check("""{f"{0}"}""", [(0, 8)], ["""{f"{0}"}"""])
+    check("""{"'"}""", [(0, 5)], ["""{"'"}"""])
+    check("""{"{"}""", [(0, 5)], ["""{"{"}"""])
+    check("""{"}"}""", [(0, 5)], ["""{"}"}"""])
+    check("""{"{{"}""", [(0, 6)], ["""{"{{"}"""])
+    check("""{''' '''}""", [(0, 9)], ["""{''' '''}"""])
+    check("""{'''{'''}""", [(0, 9)], ["""{'''{'''}"""])
+    check("""{''' {'{ '''}""", [(0, 13)], ["""{''' {'{ '''}"""])
+    check(
+        '''f\'\'\'-{f"""*{f"+{f'.{x}.'}+"}*"""}-'y\\'\'\'\'''',
+        [(5, 33)],
+        ['''{f"""*{f"+{f'.{x}.'}+"}*"""}'''],
+    )
+    check(r"""{}{""", [(0, 2)], ["{}"])
+    check("""f"{'{'''''''''}\"""", [(2, 15)], ["{'{'''''''''}"])

From 84851914488b2f3f6388a0760ee04306e4c2fc18 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Wed, 1 Dec 2021 13:47:33 -0800
Subject: [PATCH 0367/1034] slightly better example link (#2617)

Since we also need to update two places in the docs
---
 docs/contributing/release_process.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/contributing/release_process.md b/docs/contributing/release_process.md
index 718ea3dc9a2..9ee7dbc607c 100644
--- a/docs/contributing/release_process.md
+++ b/docs/contributing/release_process.md
@@ -8,8 +8,8 @@ explain what everything does and how to release _Black_ using said automation.
 To cut a release, you must be a _Black_ maintainer with `GitHub Release` creation
 access. Using this access, the release process is:
 
-1. Cut a new PR editing `CHANGES.md` to version the latest changes
-   1. Example PR: https://github.com/psf/black/pull/2192
+1. Cut a new PR editing `CHANGES.md` and the docs to version the latest changes
+   1. Example PR: [#2616](https://github.com/psf/black/pull/2616)
    2. Example title: `Update CHANGES.md for XX.X release`
 2. Once the release PR is merged ensure all CI passes
    1. If not, ensure there is an Issue open for the cause of failing CI (generally we'd

From b0c2bcc9537d238c8a580294ecbc41de465d7f55 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Wed, 1 Dec 2021 18:05:59 -0500
Subject: [PATCH 0368/1034] Treat functions/classes in blocks as if they're
 nested (GH-2472)

* Treat functions/classes in blocks as if they're nested

One curveball is that we still want two preceding newlines before blocks
that are probably logically disconnected. In other words:

    if condition:

        def foo():
            return "hi"
                             # <- aside: this is the goal of this commit
    else:

        def foo():
            return "cya"
                             # <- the two newlines spacing here should stay
                             #    since this probably isn't related
    with open("db.json", encoding="utf-8") as f:
        data = f.read()

Unfortunately that means we have to special case specific clause types
instead of just being able to just for a colon leaf. The hack used here
is to check whether we're adding preceding newlines for a standalone or
dependent clause. "Standalone" being a clause that doesn't need another
clause to be valid (eg. if) and vice versa.

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 CHANGES.md                   |  1 +
 src/black/lines.py           | 24 ++++++++++++--
 src/black_primer/primer.json |  2 +-
 tests/data/function2.py      | 63 ++++++++++++++++++++++++++++++++++++
 4 files changed, 87 insertions(+), 3 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 5b648225ad7..59042914174 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -17,6 +17,7 @@
 - Add `flake8-simplify` and `flake8-comprehensions` plugins (#2653)
 - Fix determination of f-string expression spans (#2654)
 - Fix parser error location on invalid syntax in a `match` statement (#2649)
+- Functions and classes in blocks now have more consistent surrounding spacing (#2472)
 
 ## 21.11b1
 
diff --git a/src/black/lines.py b/src/black/lines.py
index 63225c0e6d3..f2bdada008a 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -447,11 +447,31 @@ def _maybe_empty_lines(self, current_line: Line) -> Tuple[int, int]:
             before = 0
         depth = current_line.depth
         while self.previous_defs and self.previous_defs[-1] >= depth:
-            self.previous_defs.pop()
             if self.is_pyi:
                 before = 0 if depth else 1
             else:
-                before = 1 if depth else 2
+                if depth:
+                    before = 1
+                elif (
+                    not depth
+                    and self.previous_defs[-1]
+                    and current_line.leaves[-1].type == token.COLON
+                    and (
+                        current_line.leaves[0].value
+                        not in ("with", "try", "for", "while", "if", "match")
+                    )
+                ):
+                    # We shouldn't add two newlines between an indented function and
+                    # a dependent non-indented clause. This is to avoid issues with
+                    # conditional function definitions that are technically top-level
+                    # and therefore get two trailing newlines, but look weird and
+                    # inconsistent when they're followed by elif, else, etc. This is
+                    # worse because these functions only get *one* preceding newline
+                    # already.
+                    before = 1
+                else:
+                    before = 2
+            self.previous_defs.pop()
         if current_line.is_decorator or current_line.is_def or current_line.is_class:
             return self._maybe_empty_lines_for_class_or_def(current_line, before)
 
diff --git a/src/black_primer/primer.json b/src/black_primer/primer.json
index 2290d1df005..8fe61e889f8 100644
--- a/src/black_primer/primer.json
+++ b/src/black_primer/primer.json
@@ -116,7 +116,7 @@
     },
     "pyanalyze": {
       "cli_arguments": ["--experimental-string-processing"],
-      "expect_formatting_changes": false,
+      "expect_formatting_changes": true,
       "git_clone_url": "https://github.com/quora/pyanalyze.git",
       "long_checkout": false,
       "py_versions": ["all"]
diff --git a/tests/data/function2.py b/tests/data/function2.py
index cfc259ea7bd..5bb36c26318 100644
--- a/tests/data/function2.py
+++ b/tests/data/function2.py
@@ -23,6 +23,35 @@ def inner():
         pass
     print("Inner defs should breathe a little.")
 
+
+if os.name == "posix":
+    import termios
+    def i_should_be_followed_by_only_one_newline():
+        pass
+elif os.name == "nt":
+    try:
+        import msvcrt
+        def i_should_be_followed_by_only_one_newline():
+            pass
+
+    except ImportError:
+
+        def i_should_be_followed_by_only_one_newline():
+            pass
+
+elif False:
+
+    class IHopeYouAreHavingALovelyDay:
+        def __call__(self):
+            print("i_should_be_followed_by_only_one_newline")
+else:
+
+    def foo():
+        pass
+
+with hmm_but_this_should_get_two_preceding_newlines():
+    pass
+
 # output
 
 def f(
@@ -56,3 +85,37 @@ def inner():
         pass
 
     print("Inner defs should breathe a little.")
+
+
+if os.name == "posix":
+    import termios
+
+    def i_should_be_followed_by_only_one_newline():
+        pass
+
+elif os.name == "nt":
+    try:
+        import msvcrt
+
+        def i_should_be_followed_by_only_one_newline():
+            pass
+
+    except ImportError:
+
+        def i_should_be_followed_by_only_one_newline():
+            pass
+
+elif False:
+
+    class IHopeYouAreHavingALovelyDay:
+        def __call__(self):
+            print("i_should_be_followed_by_only_one_newline")
+
+else:
+
+    def foo():
+        pass
+
+
+with hmm_but_this_should_get_two_preceding_newlines():
+    pass

From 20d7ae0676be4931d0b2e6d4a6a0877070264d13 Mon Sep 17 00:00:00 2001
From: Batuhan Taskaya <isidentical@gmail.com>
Date: Thu, 2 Dec 2021 20:58:22 +0300
Subject: [PATCH 0369/1034] Ensure match/case are recognized as statements
 (#2665)

---
 CHANGES.md                           |  1 +
 src/black/nodes.py                   |  2 ++
 tests/data/pattern_matching_style.py | 27 +++++++++++++++++++++++++++
 tests/test_format.py                 |  1 +
 4 files changed, 31 insertions(+)
 create mode 100644 tests/data/pattern_matching_style.py

diff --git a/CHANGES.md b/CHANGES.md
index 59042914174..c9a4f09a72a 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -13,6 +13,7 @@
   `match a, *b:` (#2639) (#2659)
 - Fix `match`/`case` statements that contain `match`/`case` soft keywords multiple
   times, like `match re.match()` (#2661)
+- Fix `case` statements with an inline body (#2665)
 - Fix assignment to environment variables in Jupyter Notebooks (#2642)
 - Add `flake8-simplify` and `flake8-comprehensions` plugins (#2653)
 - Fix determination of f-string expression spans (#2654)
diff --git a/src/black/nodes.py b/src/black/nodes.py
index 36dd1890511..437051d3f6d 100644
--- a/src/black/nodes.py
+++ b/src/black/nodes.py
@@ -52,6 +52,8 @@
     syms.with_stmt,
     syms.funcdef,
     syms.classdef,
+    syms.match_stmt,
+    syms.case_block,
 }
 STANDALONE_COMMENT: Final = 153
 token.tok_name[STANDALONE_COMMENT] = "STANDALONE_COMMENT"
diff --git a/tests/data/pattern_matching_style.py b/tests/data/pattern_matching_style.py
new file mode 100644
index 00000000000..c1c0aeedb70
--- /dev/null
+++ b/tests/data/pattern_matching_style.py
@@ -0,0 +1,27 @@
+match something:
+    case b(): print(1+1)
+    case c(
+        very_complex=True,
+        perhaps_even_loooooooooooooooooooooooooooooooooooooong=-   1
+    ): print(1)
+    case c(
+        very_complex=True,
+        perhaps_even_loooooooooooooooooooooooooooooooooooooong=-1
+    ): print(2)
+    case a: pass
+
+# output
+
+match something:
+    case b():
+        print(1 + 1)
+    case c(
+        very_complex=True, perhaps_even_loooooooooooooooooooooooooooooooooooooong=-1
+    ):
+        print(1)
+    case c(
+        very_complex=True, perhaps_even_loooooooooooooooooooooooooooooooooooooong=-1
+    ):
+        print(2)
+    case a:
+        pass
diff --git a/tests/test_format.py b/tests/test_format.py
index f97d7165b1a..d44be1e8712 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -74,6 +74,7 @@
     "pattern_matching_simple",
     "pattern_matching_complex",
     "pattern_matching_extras",
+    "pattern_matching_style",
     "parenthesized_context_managers",
 ]
 

From bd9d52b52d58df60bffe164309a48cb61ac8d3b7 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Thu, 2 Dec 2021 14:35:02 -0800
Subject: [PATCH 0370/1034] Remove regex dependency (GH-2663)

We were no longer using it since GH-2644 and GH-2654. This should hopefully
make using Black easier to use as there's one less compiled dependency.
The core team also doesn't have to deal with the surprisingly frequent fires
the regex packaging setup goes through.

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 CHANGES.md                   |   2 +-
 Pipfile                      |   1 -
 Pipfile.lock                 | 112 +----------------------------------
 docs/integrations/editors.md |  28 ++++-----
 setup.py                     |   1 -
 src/black/trans.py           |   4 +-
 6 files changed, 17 insertions(+), 131 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index c9a4f09a72a..fc198a8f8c0 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -8,7 +8,7 @@
   cell magics were tokenized, leading to possible indentation errors e.g. with
   `%%writefile`. (#2630)
 - Fix Python 3.10 support on platforms without ProcessPoolExecutor (#2631)
-- Reduce usage of the `regex` dependency (#2644)
+- Remove dependency on `regex` (#2644) (#2663)
 - Fix `match` statements with open sequence subjects, like `match a, b:` or
   `match a, *b:` (#2639) (#2659)
 - Fix `match`/`case` statements that contain `match`/`case` soft keywords multiple
diff --git a/Pipfile b/Pipfile
index 9608f4d4ef7..a3af5fd8844 100644
--- a/Pipfile
+++ b/Pipfile
@@ -42,7 +42,6 @@ platformdirs= ">=2"
 click = ">=8.0.0"
 mypy_extensions = ">=0.4.3"
 pathspec = ">=0.8.1"
-regex = ">=2021.4.4"
 tomli = ">=0.2.6, <2.0.0"
 typed-ast = "==1.4.3"
 typing_extensions = {markers = "python_version < '3.10'", version = ">=3.10.0.0"}
diff --git a/Pipfile.lock b/Pipfile.lock
index a02ea4a2590..b2a9f6c6fc0 100644
--- a/Pipfile.lock
+++ b/Pipfile.lock
@@ -1,7 +1,7 @@
 {
     "_meta": {
         "hash": {
-            "sha256": "a516705ed9270469fd58d20f1b26a94a6ed052451ef7425d82605b80513a65b3"
+            "sha256": "7728caac52b47ed119a804ead88afa002d62c17a324e962b7833b8944049609b"
         },
         "pipfile-spec": 6,
         "requires": {},
@@ -375,61 +375,6 @@
             "markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==2.4.7"
         },
-        "regex": {
-            "hashes": [
-                "sha256:05b7d6d7e64efe309972adab77fc2af8907bb93217ec60aa9fe12a0dad35874f",
-                "sha256:0617383e2fe465732af4509e61648b77cbe3aee68b6ac8c0b6fe934db90be5cc",
-                "sha256:07856afef5ffcc052e7eccf3213317fbb94e4a5cd8177a2caa69c980657b3cb4",
-                "sha256:162abfd74e88001d20cb73ceaffbfe601469923e875caf9118333b1a4aaafdc4",
-                "sha256:2207ae4f64ad3af399e2d30dde66f0b36ae5c3129b52885f1bffc2f05ec505c8",
-                "sha256:30ab804ea73972049b7a2a5c62d97687d69b5a60a67adca07eb73a0ddbc9e29f",
-                "sha256:3b5df18db1fccd66de15aa59c41e4f853b5df7550723d26aa6cb7f40e5d9da5a",
-                "sha256:3c5fb32cc6077abad3bbf0323067636d93307c9fa93e072771cf9a64d1c0f3ef",
-                "sha256:416c5f1a188c91e3eb41e9c8787288e707f7d2ebe66e0a6563af280d9b68478f",
-                "sha256:432bd15d40ed835a51617521d60d0125867f7b88acf653e4ed994a1f8e4995dc",
-                "sha256:4aaa4e0705ef2b73dd8e36eeb4c868f80f8393f5f4d855e94025ce7ad8525f50",
-                "sha256:537ca6a3586931b16a85ac38c08cc48f10fc870a5b25e51794c74df843e9966d",
-                "sha256:53db2c6be8a2710b359bfd3d3aa17ba38f8aa72a82309a12ae99d3c0c3dcd74d",
-                "sha256:5537f71b6d646f7f5f340562ec4c77b6e1c915f8baae822ea0b7e46c1f09b733",
-                "sha256:6650f16365f1924d6014d2ea770bde8555b4a39dc9576abb95e3cd1ff0263b36",
-                "sha256:666abff54e474d28ff42756d94544cdfd42e2ee97065857413b72e8a2d6a6345",
-                "sha256:68a067c11463de2a37157930d8b153005085e42bcb7ad9ca562d77ba7d1404e0",
-                "sha256:780b48456a0f0ba4d390e8b5f7c661fdd218934388cde1a974010a965e200e12",
-                "sha256:788aef3549f1924d5c38263104dae7395bf020a42776d5ec5ea2b0d3d85d6646",
-                "sha256:7ee1227cf08b6716c85504aebc49ac827eb88fcc6e51564f010f11a406c0a667",
-                "sha256:7f301b11b9d214f83ddaf689181051e7f48905568b0c7017c04c06dfd065e244",
-                "sha256:83ee89483672b11f8952b158640d0c0ff02dc43d9cb1b70c1564b49abe92ce29",
-                "sha256:85bfa6a5413be0ee6c5c4a663668a2cad2cbecdee367630d097d7823041bdeec",
-                "sha256:9345b6f7ee578bad8e475129ed40123d265464c4cfead6c261fd60fc9de00bcf",
-                "sha256:93a5051fcf5fad72de73b96f07d30bc29665697fb8ecdfbc474f3452c78adcf4",
-                "sha256:962b9a917dd7ceacbe5cd424556914cb0d636001e393b43dc886ba31d2a1e449",
-                "sha256:98ba568e8ae26beb726aeea2273053c717641933836568c2a0278a84987b2a1a",
-                "sha256:a3feefd5e95871872673b08636f96b61ebef62971eab044f5124fb4dea39919d",
-                "sha256:b43c2b8a330a490daaef5a47ab114935002b13b3f9dc5da56d5322ff218eeadb",
-                "sha256:b483c9d00a565633c87abd0aaf27eb5016de23fed952e054ecc19ce32f6a9e7e",
-                "sha256:ba05430e819e58544e840a68b03b28b6d328aff2e41579037e8bab7653b37d83",
-                "sha256:ca5f18a75e1256ce07494e245cdb146f5a9267d3c702ebf9b65c7f8bd843431e",
-                "sha256:d5ca078bb666c4a9d1287a379fe617a6dccd18c3e8a7e6c7e1eb8974330c626a",
-                "sha256:da1a90c1ddb7531b1d5ff1e171b4ee61f6345119be7351104b67ff413843fe94",
-                "sha256:dba70f30fd81f8ce6d32ddeef37d91c8948e5d5a4c63242d16a2b2df8143aafc",
-                "sha256:dd33eb9bdcfbabab3459c9ee651d94c842bc8a05fabc95edf4ee0c15a072495e",
-                "sha256:e0538c43565ee6e703d3a7c3bdfe4037a5209250e8502c98f20fea6f5fdf2965",
-                "sha256:e1f54b9b4b6c53369f40028d2dd07a8c374583417ee6ec0ea304e710a20f80a0",
-                "sha256:e32d2a2b02ccbef10145df9135751abea1f9f076e67a4e261b05f24b94219e36",
-                "sha256:e71255ba42567d34a13c03968736c5d39bb4a97ce98188fafb27ce981115beec",
-                "sha256:ed2e07c6a26ed4bea91b897ee2b0835c21716d9a469a96c3e878dc5f8c55bb23",
-                "sha256:eef2afb0fd1747f33f1ee3e209bce1ed582d1896b240ccc5e2697e3275f037c7",
-                "sha256:f23222527b307970e383433daec128d769ff778d9b29343fb3496472dc20dabe",
-                "sha256:f341ee2df0999bfdf7a95e448075effe0db212a59387de1a70690e4acb03d4c6",
-                "sha256:f7f325be2804246a75a4f45c72d4ce80d2443ab815063cdf70ee8fb2ca59ee1b",
-                "sha256:f8af619e3be812a2059b212064ea7a640aff0568d972cd1b9e920837469eb3cb",
-                "sha256:fa8c626d6441e2d04b6ee703ef2d1e17608ad44c7cb75258c09dd42bacdfc64b",
-                "sha256:fbb9dc00e39f3e6c0ef48edee202f9520dafb233e8b51b06b8428cfcb92abd30",
-                "sha256:fff55f3ce50a3ff63ec8e2a8d3dd924f1941b250b0aac3d3d42b687eeff07a8e"
-            ],
-            "index": "pypi",
-            "version": "==2021.11.10"
-        },
         "setuptools": {
             "hashes": [
                 "sha256:a481fbc56b33f5d8f6b33dce41482e64c68b668be44ff42922903b03872590bf",
@@ -1624,61 +1569,6 @@
             "index": "pypi",
             "version": "==30.0"
         },
-        "regex": {
-            "hashes": [
-                "sha256:05b7d6d7e64efe309972adab77fc2af8907bb93217ec60aa9fe12a0dad35874f",
-                "sha256:0617383e2fe465732af4509e61648b77cbe3aee68b6ac8c0b6fe934db90be5cc",
-                "sha256:07856afef5ffcc052e7eccf3213317fbb94e4a5cd8177a2caa69c980657b3cb4",
-                "sha256:162abfd74e88001d20cb73ceaffbfe601469923e875caf9118333b1a4aaafdc4",
-                "sha256:2207ae4f64ad3af399e2d30dde66f0b36ae5c3129b52885f1bffc2f05ec505c8",
-                "sha256:30ab804ea73972049b7a2a5c62d97687d69b5a60a67adca07eb73a0ddbc9e29f",
-                "sha256:3b5df18db1fccd66de15aa59c41e4f853b5df7550723d26aa6cb7f40e5d9da5a",
-                "sha256:3c5fb32cc6077abad3bbf0323067636d93307c9fa93e072771cf9a64d1c0f3ef",
-                "sha256:416c5f1a188c91e3eb41e9c8787288e707f7d2ebe66e0a6563af280d9b68478f",
-                "sha256:432bd15d40ed835a51617521d60d0125867f7b88acf653e4ed994a1f8e4995dc",
-                "sha256:4aaa4e0705ef2b73dd8e36eeb4c868f80f8393f5f4d855e94025ce7ad8525f50",
-                "sha256:537ca6a3586931b16a85ac38c08cc48f10fc870a5b25e51794c74df843e9966d",
-                "sha256:53db2c6be8a2710b359bfd3d3aa17ba38f8aa72a82309a12ae99d3c0c3dcd74d",
-                "sha256:5537f71b6d646f7f5f340562ec4c77b6e1c915f8baae822ea0b7e46c1f09b733",
-                "sha256:6650f16365f1924d6014d2ea770bde8555b4a39dc9576abb95e3cd1ff0263b36",
-                "sha256:666abff54e474d28ff42756d94544cdfd42e2ee97065857413b72e8a2d6a6345",
-                "sha256:68a067c11463de2a37157930d8b153005085e42bcb7ad9ca562d77ba7d1404e0",
-                "sha256:780b48456a0f0ba4d390e8b5f7c661fdd218934388cde1a974010a965e200e12",
-                "sha256:788aef3549f1924d5c38263104dae7395bf020a42776d5ec5ea2b0d3d85d6646",
-                "sha256:7ee1227cf08b6716c85504aebc49ac827eb88fcc6e51564f010f11a406c0a667",
-                "sha256:7f301b11b9d214f83ddaf689181051e7f48905568b0c7017c04c06dfd065e244",
-                "sha256:83ee89483672b11f8952b158640d0c0ff02dc43d9cb1b70c1564b49abe92ce29",
-                "sha256:85bfa6a5413be0ee6c5c4a663668a2cad2cbecdee367630d097d7823041bdeec",
-                "sha256:9345b6f7ee578bad8e475129ed40123d265464c4cfead6c261fd60fc9de00bcf",
-                "sha256:93a5051fcf5fad72de73b96f07d30bc29665697fb8ecdfbc474f3452c78adcf4",
-                "sha256:962b9a917dd7ceacbe5cd424556914cb0d636001e393b43dc886ba31d2a1e449",
-                "sha256:98ba568e8ae26beb726aeea2273053c717641933836568c2a0278a84987b2a1a",
-                "sha256:a3feefd5e95871872673b08636f96b61ebef62971eab044f5124fb4dea39919d",
-                "sha256:b43c2b8a330a490daaef5a47ab114935002b13b3f9dc5da56d5322ff218eeadb",
-                "sha256:b483c9d00a565633c87abd0aaf27eb5016de23fed952e054ecc19ce32f6a9e7e",
-                "sha256:ba05430e819e58544e840a68b03b28b6d328aff2e41579037e8bab7653b37d83",
-                "sha256:ca5f18a75e1256ce07494e245cdb146f5a9267d3c702ebf9b65c7f8bd843431e",
-                "sha256:d5ca078bb666c4a9d1287a379fe617a6dccd18c3e8a7e6c7e1eb8974330c626a",
-                "sha256:da1a90c1ddb7531b1d5ff1e171b4ee61f6345119be7351104b67ff413843fe94",
-                "sha256:dba70f30fd81f8ce6d32ddeef37d91c8948e5d5a4c63242d16a2b2df8143aafc",
-                "sha256:dd33eb9bdcfbabab3459c9ee651d94c842bc8a05fabc95edf4ee0c15a072495e",
-                "sha256:e0538c43565ee6e703d3a7c3bdfe4037a5209250e8502c98f20fea6f5fdf2965",
-                "sha256:e1f54b9b4b6c53369f40028d2dd07a8c374583417ee6ec0ea304e710a20f80a0",
-                "sha256:e32d2a2b02ccbef10145df9135751abea1f9f076e67a4e261b05f24b94219e36",
-                "sha256:e71255ba42567d34a13c03968736c5d39bb4a97ce98188fafb27ce981115beec",
-                "sha256:ed2e07c6a26ed4bea91b897ee2b0835c21716d9a469a96c3e878dc5f8c55bb23",
-                "sha256:eef2afb0fd1747f33f1ee3e209bce1ed582d1896b240ccc5e2697e3275f037c7",
-                "sha256:f23222527b307970e383433daec128d769ff778d9b29343fb3496472dc20dabe",
-                "sha256:f341ee2df0999bfdf7a95e448075effe0db212a59387de1a70690e4acb03d4c6",
-                "sha256:f7f325be2804246a75a4f45c72d4ce80d2443ab815063cdf70ee8fb2ca59ee1b",
-                "sha256:f8af619e3be812a2059b212064ea7a640aff0568d972cd1b9e920837469eb3cb",
-                "sha256:fa8c626d6441e2d04b6ee703ef2d1e17608ad44c7cb75258c09dd42bacdfc64b",
-                "sha256:fbb9dc00e39f3e6c0ef48edee202f9520dafb233e8b51b06b8428cfcb92abd30",
-                "sha256:fff55f3ce50a3ff63ec8e2a8d3dd924f1941b250b0aac3d3d42b687eeff07a8e"
-            ],
-            "index": "pypi",
-            "version": "==2021.11.10"
-        },
         "requests": {
             "hashes": [
                 "sha256:6c1246513ecd5ecd4528a0906f910e8f0f9c6b8ec72030dc9fd154dc1a6efd24",
diff --git a/docs/integrations/editors.md b/docs/integrations/editors.md
index d3be7c0ea84..9c279564fa3 100644
--- a/docs/integrations/editors.md
+++ b/docs/integrations/editors.md
@@ -204,30 +204,28 @@ Traceback (most recent call last):
 ImportError: /home/gui/.vim/black/lib/python3.7/site-packages/typed_ast/_ast3.cpython-37m-x86_64-linux-gnu.so: undefined symbool: PyExc_KeyboardInterrupt
 ```
 
-Then you need to install `typed_ast` and `regex` directly from the source code. The
-error happens because `pip` will download [Python wheels](https://pythonwheels.com/) if
-they are available. Python wheels are a new standard of distributing Python packages and
-packages that have Cython and extensions written in C are already compiled, so the
-installation is much more faster. The problem here is that somehow the Python
-environment inside Vim does not match with those already compiled C extensions and these
-kind of errors are the result. Luckily there is an easy fix: installing the packages
-from the source code.
-
-The two packages that cause the problem are:
-
-- [regex](https://pypi.org/project/regex/)
+Then you need to install `typed_ast` directly from the source code. The error happens
+because `pip` will download [Python wheels](https://pythonwheels.com/) if they are
+available. Python wheels are a new standard of distributing Python packages and packages
+that have Cython and extensions written in C are already compiled, so the installation
+is much more faster. The problem here is that somehow the Python environment inside Vim
+does not match with those already compiled C extensions and these kind of errors are the
+result. Luckily there is an easy fix: installing the packages from the source code.
+
+The package that causes problems is:
+
 - [typed-ast](https://pypi.org/project/typed-ast/)
 
 Now remove those two packages:
 
 ```console
-$ pip uninstall regex typed-ast -y
+$ pip uninstall typed-ast -y
 ```
 
 And now you can install them with:
 
 ```console
-$ pip install --no-binary :all: regex typed-ast
+$ pip install --no-binary :all: typed-ast
 ```
 
 The C extensions will be compiled and now Vim's Python environment will match. Note that
@@ -237,7 +235,7 @@ Ubuntu/Debian do `sudo apt-get install build-essential python3-dev`).
 If you later want to update _Black_, you should do it like this:
 
 ```console
-$ pip install -U black --no-binary regex,typed-ast
+$ pip install -U black --no-binary typed-ast
 ```
 
 ### With ALE
diff --git a/setup.py b/setup.py
index 33b7239a13e..a21bc87264d 100644
--- a/setup.py
+++ b/setup.py
@@ -101,7 +101,6 @@ def find_python_files(base: Path) -> List[Path]:
         "platformdirs>=2",
         "tomli>=0.2.6,<2.0.0",
         "typed-ast>=1.4.2; python_version < '3.8' and implementation_name == 'cpython'",
-        "regex>=2021.4.4",
         "pathspec>=0.9.0, <1",
         "dataclasses>=0.6; python_version < '3.7'",
         "typing_extensions>=3.10.0.0",
diff --git a/src/black/trans.py b/src/black/trans.py
index 6aca3a8733f..cb41c1be487 100644
--- a/src/black/trans.py
+++ b/src/black/trans.py
@@ -4,7 +4,7 @@
 from abc import ABC, abstractmethod
 from collections import defaultdict
 from dataclasses import dataclass
-import regex as re  # We need recursive patterns here (?R)
+import re
 from typing import (
     Any,
     Callable,
@@ -453,7 +453,7 @@ def make_naked(string: str, string_prefix: str) -> str:
             # with 'f'...
             if "f" in prefix and "f" not in next_prefix:
                 # Then we must escape any braces contained in this substring.
-                SS = re.subf(r"(\{|\})", "{1}{1}", SS)
+                SS = re.sub(r"(\{|\})", r"\1\1", SS)
 
             NSS = make_naked(SS, next_prefix)
 

From 136930fccb99320865622e12ffc21bdd45fd7501 Mon Sep 17 00:00:00 2001
From: Batuhan Taskaya <isidentical@gmail.com>
Date: Fri, 3 Dec 2021 17:49:33 +0300
Subject: [PATCH 0371/1034] Make star-expression spacing consistent in
 match/case (#2667)

---
 CHANGES.md                            | 1 +
 src/black/nodes.py                    | 2 ++
 tests/data/pattern_matching_extras.py | 5 +++++
 3 files changed, 8 insertions(+)

diff --git a/CHANGES.md b/CHANGES.md
index fc198a8f8c0..e5f4a1fdf82 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -14,6 +14,7 @@
 - Fix `match`/`case` statements that contain `match`/`case` soft keywords multiple
   times, like `match re.match()` (#2661)
 - Fix `case` statements with an inline body (#2665)
+- Fix styling of starred expressions inside `match` subject (#2667)
 - Fix assignment to environment variables in Jupyter Notebooks (#2642)
 - Add `flake8-simplify` and `flake8-comprehensions` plugins (#2653)
 - Fix determination of f-string expression spans (#2654)
diff --git a/src/black/nodes.py b/src/black/nodes.py
index 437051d3f6d..8bf1934bc2a 100644
--- a/src/black/nodes.py
+++ b/src/black/nodes.py
@@ -97,6 +97,8 @@
     syms.listmaker,
     syms.testlist_gexp,
     syms.testlist_star_expr,
+    syms.subject_expr,
+    syms.pattern,
 }
 TEST_DESCENDANTS: Final = {
     syms.test,
diff --git a/tests/data/pattern_matching_extras.py b/tests/data/pattern_matching_extras.py
index 095c1a2b3bb..60ad8a3d81b 100644
--- a/tests/data/pattern_matching_extras.py
+++ b/tests/data/pattern_matching_extras.py
@@ -77,3 +77,8 @@ def func(match: case, case: match) -> case:
 match match:
     case case:
         pass
+
+
+match a, *b(), c:
+    case d, *f, g:
+        pass

From f52cb0fe3775829245acfeae191e8d63120c8416 Mon Sep 17 00:00:00 2001
From: Tanvi Moharir <74228962+tanvimoharir@users.noreply.github.com>
Date: Sun, 5 Dec 2021 01:51:26 +0530
Subject: [PATCH 0372/1034] Don't let TokenError bubble up from lib2to3_parse
 (GH-2343)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

error: cannot format <string>: ('EOF in multi-line statement', (2, 0))

 ▲ before ▼ after

error: cannot format <string>: Cannot parse: 2:0: EOF in multi-line statement

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 CHANGES.md           | 1 +
 src/black/parsing.py | 7 +++++++
 tests/test_black.py  | 9 +++++++++
 3 files changed, 17 insertions(+)

diff --git a/CHANGES.md b/CHANGES.md
index e5f4a1fdf82..5d89c71f580 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -19,6 +19,7 @@
 - Add `flake8-simplify` and `flake8-comprehensions` plugins (#2653)
 - Fix determination of f-string expression spans (#2654)
 - Fix parser error location on invalid syntax in a `match` statement (#2649)
+- Fix bad formatting of error messages about EOF in multi-line statements (#2343)
 - Functions and classes in blocks now have more consistent surrounding spacing (#2472)
 
 ## 21.11b1
diff --git a/src/black/parsing.py b/src/black/parsing.py
index e38405637cd..b673027022f 100644
--- a/src/black/parsing.py
+++ b/src/black/parsing.py
@@ -17,6 +17,7 @@
 from blib2to3.pgen2 import driver
 from blib2to3.pgen2.grammar import Grammar
 from blib2to3.pgen2.parse import ParseError
+from blib2to3.pgen2.tokenize import TokenError
 
 from black.mode import TargetVersion, Feature, supports_feature
 from black.nodes import syms
@@ -109,6 +110,12 @@ def lib2to3_parse(src_txt: str, target_versions: Iterable[TargetVersion] = ()) -
             except IndexError:
                 faulty_line = "<line number missing in source>"
             exc = InvalidInput(f"Cannot parse: {lineno}:{column}: {faulty_line}")
+
+        except TokenError as te:
+            # In edge cases these are raised; and typically don't have a "faulty_line".
+            lineno, column = te.args[1]
+            exc = InvalidInput(f"Cannot parse: {lineno}:{column}: {te.args[0]}")
+
     else:
         raise exc from None
 
diff --git a/tests/test_black.py b/tests/test_black.py
index 51a20307e56..92598532e2c 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -1557,6 +1557,15 @@ def test_code_option_parent_config(self) -> None:
                     call_args[0].lower() == str(pyproject_path).lower()
                 ), "Incorrect config loaded."
 
+    def test_for_handled_unexpected_eof_error(self) -> None:
+        """
+        Test that an unexpected EOF SyntaxError is nicely presented.
+        """
+        with pytest.raises(black.parsing.InvalidInput) as exc_info:
+            black.lib2to3_parse("print(", {})
+
+        exc_info.match("Cannot parse: 2:0: EOF in multi-line statement")
+
 
 class TestCaching:
     def test_cache_broken_file(self) -> None:

From dc8cdda8fdd6941103240ae3279034d2acdc69bc Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Sat, 4 Dec 2021 15:30:23 -0800
Subject: [PATCH 0373/1034] tell users to use -t py310 (#2668)

---
 CHANGES.md           |  1 +
 src/black/parsing.py | 24 +++++++++++++++++++++++-
 tests/test_format.py |  9 +++++++++
 3 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index 5d89c71f580..dcb51f7e98a 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -4,6 +4,7 @@
 
 ### _Black_
 
+- Point users to using `--target-version py310` if we detect 3.10-only syntax (#2668)
 - Cell magics are now only processed if they are known Python cell magics. Earlier, all
   cell magics were tokenized, leading to possible indentation errors e.g. with
   `%%writefile`. (#2630)
diff --git a/src/black/parsing.py b/src/black/parsing.py
index b673027022f..2fd41f03ecd 100644
--- a/src/black/parsing.py
+++ b/src/black/parsing.py
@@ -43,6 +43,11 @@
         ast3 = ast27 = ast
 
 
+PY310_HINT: Final[
+    str
+] = "Consider using --target-version py310 to parse Python 3.10 code."
+
+
 class InvalidInput(ValueError):
     """Raised when input source code fails all parse attempts."""
 
@@ -96,7 +101,8 @@ def lib2to3_parse(src_txt: str, target_versions: Iterable[TargetVersion] = ()) -
     if not src_txt.endswith("\n"):
         src_txt += "\n"
 
-    for grammar in get_grammars(set(target_versions)):
+    grammars = get_grammars(set(target_versions))
+    for grammar in grammars:
         drv = driver.Driver(grammar)
         try:
             result = drv.parse_string(src_txt, True)
@@ -117,6 +123,12 @@ def lib2to3_parse(src_txt: str, target_versions: Iterable[TargetVersion] = ()) -
             exc = InvalidInput(f"Cannot parse: {lineno}:{column}: {te.args[0]}")
 
     else:
+        if pygram.python_grammar_soft_keywords not in grammars and matches_grammar(
+            src_txt, pygram.python_grammar_soft_keywords
+        ):
+            original_msg = exc.args[0]
+            msg = f"{original_msg}\n{PY310_HINT}"
+            raise InvalidInput(msg) from None
         raise exc from None
 
     if isinstance(result, Leaf):
@@ -124,6 +136,16 @@ def lib2to3_parse(src_txt: str, target_versions: Iterable[TargetVersion] = ()) -
     return result
 
 
+def matches_grammar(src_txt: str, grammar: Grammar) -> bool:
+    drv = driver.Driver(grammar)
+    try:
+        drv.parse_string(src_txt, True)
+    except ParseError:
+        return False
+    else:
+        return True
+
+
 def lib2to3_unparse(node: Node) -> str:
     """Given a lib2to3 node, return its string representation."""
     code = str(node)
diff --git a/tests/test_format.py b/tests/test_format.py
index d44be1e8712..30099aaf1bc 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -210,6 +210,15 @@ def test_patma_invalid() -> None:
     exc_info.match("Cannot parse: 10:11")
 
 
+def test_patma_hint() -> None:
+    source, expected = read_data("pattern_matching_simple")
+    mode = black.Mode(target_versions={black.TargetVersion.PY39})
+    with pytest.raises(black.parsing.InvalidInput) as exc_info:
+        assert_format(source, expected, mode, minimum_version=(3, 10))
+
+    exc_info.match(black.parsing.PY310_HINT)
+
+
 def test_docstring_no_string_normalization() -> None:
     """Like test_docstring but with string normalization off."""
     source, expected = read_data("docstring_no_string_normalization")

From 9424e795bf662743da6423b74e30ab74d1a93775 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Sat, 4 Dec 2021 15:57:40 -0800
Subject: [PATCH 0374/1034] Reorganize changelog (#2669)

I believe it would be useful to split up the long list of changes a bit more.

Specific changes:
- Removed the entry for new flake8 plugins; this is purely internal and not of interest to users
- Put regex in the packaging section
- New section for Jupyter Notebook
- New section for Python 3.10, mostly match/case stuff
---
 CHANGES.md | 24 ++++++++++++++++--------
 1 file changed, 16 insertions(+), 8 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index dcb51f7e98a..097725ec0be 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -4,24 +4,32 @@
 
 ### _Black_
 
-- Point users to using `--target-version py310` if we detect 3.10-only syntax (#2668)
+- Fix determination of f-string expression spans (#2654)
+- Fix bad formatting of error messages about EOF in multi-line statements (#2343)
+- Functions and classes in blocks now have more consistent surrounding spacing (#2472)
+
+#### Jupyter Notebook support
+
 - Cell magics are now only processed if they are known Python cell magics. Earlier, all
   cell magics were tokenized, leading to possible indentation errors e.g. with
   `%%writefile`. (#2630)
-- Fix Python 3.10 support on platforms without ProcessPoolExecutor (#2631)
-- Remove dependency on `regex` (#2644) (#2663)
+- Fix assignment to environment variables in Jupyter Notebooks (#2642)
+
+#### Python 3.10 support
+
+- Point users to using `--target-version py310` if we detect 3.10-only syntax (#2668)
 - Fix `match` statements with open sequence subjects, like `match a, b:` or
   `match a, *b:` (#2639) (#2659)
 - Fix `match`/`case` statements that contain `match`/`case` soft keywords multiple
   times, like `match re.match()` (#2661)
 - Fix `case` statements with an inline body (#2665)
 - Fix styling of starred expressions inside `match` subject (#2667)
-- Fix assignment to environment variables in Jupyter Notebooks (#2642)
-- Add `flake8-simplify` and `flake8-comprehensions` plugins (#2653)
-- Fix determination of f-string expression spans (#2654)
 - Fix parser error location on invalid syntax in a `match` statement (#2649)
-- Fix bad formatting of error messages about EOF in multi-line statements (#2343)
-- Functions and classes in blocks now have more consistent surrounding spacing (#2472)
+- Fix Python 3.10 support on platforms without ProcessPoolExecutor (#2631)
+
+### Packaging
+
+- Remove dependency on `regex` (#2644) (#2663)
 
 ## 21.11b1
 

From d9eee31ec81c42d9953aee0d7f0adaf211519a10 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Sun, 5 Dec 2021 11:53:58 -0500
Subject: [PATCH 0375/1034] blib2to3 can raise TokenError and IndentationError
 too (#2671)

---
 src/black/parsing.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/black/parsing.py b/src/black/parsing.py
index 2fd41f03ecd..c101643fe11 100644
--- a/src/black/parsing.py
+++ b/src/black/parsing.py
@@ -140,7 +140,7 @@ def matches_grammar(src_txt: str, grammar: Grammar) -> bool:
     drv = driver.Driver(grammar)
     try:
         drv.parse_string(src_txt, True)
-    except ParseError:
+    except (ParseError, TokenError, IndentationError):
         return False
     else:
         return True

From 28ab82aab013978b7ed91bda816de3d41385f260 Mon Sep 17 00:00:00 2001
From: Batuhan Taskaya <isidentical@gmail.com>
Date: Mon, 6 Dec 2021 00:03:48 +0300
Subject: [PATCH 0376/1034] perf: drop the initial stack copy (#2670)

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 CHANGES.md                  | 2 ++
 src/blib2to3/pgen2/parse.py | 2 +-
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index 097725ec0be..434f80980a5 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -26,6 +26,8 @@
 - Fix styling of starred expressions inside `match` subject (#2667)
 - Fix parser error location on invalid syntax in a `match` statement (#2649)
 - Fix Python 3.10 support on platforms without ProcessPoolExecutor (#2631)
+- Improve parsing performance on code that uses `match` under `--target-version py310`
+  up to ~50% (#2670)
 
 ### Packaging
 
diff --git a/src/blib2to3/pgen2/parse.py b/src/blib2to3/pgen2/parse.py
index 792e8e66698..e5dad3ae766 100644
--- a/src/blib2to3/pgen2/parse.py
+++ b/src/blib2to3/pgen2/parse.py
@@ -53,7 +53,7 @@ def __init__(self, parser: "Parser", ilabels: List[int], context: Context) -> No
         self.context = context  # not really matter
 
         self._dead_ilabels: Set[int] = set()
-        self._start_point = copy.deepcopy(self.parser.stack)
+        self._start_point = self.parser.stack
         self._points = {ilabel: copy.deepcopy(self._start_point) for ilabel in ilabels}
 
     @property

From f1d4e742c91dd5179d742b0db9293c4472b765f8 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Sun, 5 Dec 2021 16:39:34 -0500
Subject: [PATCH 0377/1034] Prepare for release 21.12b0 (GH-2673)

Let's do this!
---
 CHANGES.md                                  | 2 +-
 docs/integrations/source_version_control.md | 2 +-
 docs/usage_and_configuration/the_basics.md  | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 434f80980a5..9e13ef438cb 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,6 +1,6 @@
 # Change Log
 
-## Unreleased
+## 21.12b0
 
 ### _Black_
 
diff --git a/docs/integrations/source_version_control.md b/docs/integrations/source_version_control.md
index 2149027218d..9c53f30687d 100644
--- a/docs/integrations/source_version_control.md
+++ b/docs/integrations/source_version_control.md
@@ -7,7 +7,7 @@ Use [pre-commit](https://pre-commit.com/). Once you
 ```yaml
 repos:
   - repo: https://github.com/psf/black
-    rev: 21.11b1
+    rev: 21.12b0
     hooks:
       - id: black
         # It is recommended to specify the latest version of Python
diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index 3dc26b7013f..d002ff0173a 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -173,7 +173,7 @@ You can check the version of _Black_ you have installed using the `--version` fl
 
 ```console
 $ black --version
-black, version 21.11b1
+black, version 21.12b0
 ```
 
 An option to require a specific version to be running is also provided.

From 085efac037c07ef299edbf48a4d871f17b296743 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Sun, 5 Dec 2021 15:47:53 -0800
Subject: [PATCH 0378/1034] no longer expect changes on pyanalyze (#2674)

https://github.com/quora/pyanalyze/pull/316
---
 src/black_primer/primer.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/black_primer/primer.json b/src/black_primer/primer.json
index 8fe61e889f8..2290d1df005 100644
--- a/src/black_primer/primer.json
+++ b/src/black_primer/primer.json
@@ -116,7 +116,7 @@
     },
     "pyanalyze": {
       "cli_arguments": ["--experimental-string-processing"],
-      "expect_formatting_changes": true,
+      "expect_formatting_changes": false,
       "git_clone_url": "https://github.com/quora/pyanalyze.git",
       "long_checkout": false,
       "py_versions": ["all"]

From e7ddf524b056d2bc42ee6b2b5c3314e0dd5d95fb Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Tue, 7 Dec 2021 19:13:05 -0800
Subject: [PATCH 0379/1034] Show details when a regex fails to compile
 (GH-2678)

---
 CHANGES.md            | 6 ++++++
 src/black/__init__.py | 4 ++--
 2 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 9e13ef438cb..37248202750 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,5 +1,11 @@
 # Change Log
 
+## Unreleased
+
+### _Black_
+
+- Improve error message for invalid regular expression (#2678)
+
 ## 21.12b0
 
 ### _Black_
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 1923c069ede..e2376c45617 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -177,8 +177,8 @@ def validate_regex(
 ) -> Optional[Pattern[str]]:
     try:
         return re_compile_maybe_verbose(value) if value is not None else None
-    except re.error:
-        raise click.BadParameter("Not a valid regular expression") from None
+    except re.error as e:
+        raise click.BadParameter(f"Not a valid regular expression: {e}") from None
 
 
 @click.command(

From 1c6b3a3a6fbc50b651d4ac34247903041d3f6329 Mon Sep 17 00:00:00 2001
From: Batuhan Taskaya <isidentical@gmail.com>
Date: Mon, 13 Dec 2021 00:10:22 +0300
Subject: [PATCH 0380/1034] Support as-expressions on dict items (GH-2686)

---
 CHANGES.md                            |  2 ++
 src/blib2to3/Grammar.txt              |  4 ++--
 tests/data/pattern_matching_extras.py | 10 ++++++++++
 3 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 37248202750..0dcf35ea199 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -5,6 +5,8 @@
 ### _Black_
 
 - Improve error message for invalid regular expression (#2678)
+- Fix mapping cases that contain as-expressions, like `case {"key": 1 | 2 as password}`
+  (#2686)
 
 ## 21.12b0
 
diff --git a/src/blib2to3/Grammar.txt b/src/blib2to3/Grammar.txt
index c3001e81065..600712ce2f0 100644
--- a/src/blib2to3/Grammar.txt
+++ b/src/blib2to3/Grammar.txt
@@ -168,8 +168,8 @@ subscript: test [':=' test] | [test] ':' [test] [sliceop]
 sliceop: ':' [test]
 exprlist: (expr|star_expr) (',' (expr|star_expr))* [',']
 testlist: test (',' test)* [',']
-dictsetmaker: ( ((test ':' test | '**' expr)
-                 (comp_for | (',' (test ':' test | '**' expr))* [','])) |
+dictsetmaker: ( ((test ':' asexpr_test | '**' expr)
+                 (comp_for | (',' (test ':' asexpr_test | '**' expr))* [','])) |
                 ((test [':=' test] | star_expr)
 		 (comp_for | (',' (test [':=' test] | star_expr))* [','])) )
 
diff --git a/tests/data/pattern_matching_extras.py b/tests/data/pattern_matching_extras.py
index 60ad8a3d81b..c00585e9285 100644
--- a/tests/data/pattern_matching_extras.py
+++ b/tests/data/pattern_matching_extras.py
@@ -82,3 +82,13 @@ def func(match: case, case: match) -> case:
 match a, *b(), c:
     case d, *f, g:
         pass
+
+
+match something:
+    case {
+        "key": key as key_1,
+        "password": PASS.ONE | PASS.TWO | PASS.THREE as password,
+    }:
+        pass
+    case {"maybe": something(complicated as this) as that}:
+        pass

From ab8651371075ced6f58f519e48fc4e8ac529e8ce Mon Sep 17 00:00:00 2001
From: Batuhan Taskaya <isidentical@gmail.com>
Date: Wed, 15 Dec 2021 02:22:56 +0300
Subject: [PATCH 0381/1034] `from __future__ import annotations` now implies
 3.7+ (#2690)

---
 CHANGES.md            |  1 +
 src/black/__init__.py | 22 +++++++++++++++++-----
 src/black/mode.py     | 19 +++++++++++++++++++
 tests/test_black.py   | 18 ++++++++++++++++++
 4 files changed, 55 insertions(+), 5 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 0dcf35ea199..87e36f4dbe7 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -15,6 +15,7 @@
 - Fix determination of f-string expression spans (#2654)
 - Fix bad formatting of error messages about EOF in multi-line statements (#2343)
 - Functions and classes in blocks now have more consistent surrounding spacing (#2472)
+- `from __future__ import annotations` statement now implies Python 3.7+ (#2690)
 
 #### Jupyter Notebook support
 
diff --git a/src/black/__init__.py b/src/black/__init__.py
index e2376c45617..59018d00de4 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -40,7 +40,7 @@
 from black.lines import Line, EmptyLineTracker
 from black.linegen import transform_line, LineGenerator, LN
 from black.comments import normalize_fmt_off
-from black.mode import Mode, TargetVersion
+from black.mode import FUTURE_FLAG_TO_FEATURE, Mode, TargetVersion
 from black.mode import Feature, supports_feature, VERSION_TO_FEATURES
 from black.cache import read_cache, write_cache, get_cache_info, filter_cached, Cache
 from black.concurrency import cancel, shutdown, maybe_install_uvloop
@@ -1080,7 +1080,7 @@ def f(
     if mode.target_versions:
         versions = mode.target_versions
     else:
-        versions = detect_target_versions(src_node)
+        versions = detect_target_versions(src_node, future_imports=future_imports)
 
     # TODO: fully drop support and this code hopefully in January 2022 :D
     if TargetVersion.PY27 in mode.target_versions or versions == {TargetVersion.PY27}:
@@ -1132,7 +1132,9 @@ def decode_bytes(src: bytes) -> Tuple[FileContent, Encoding, NewLine]:
         return tiow.read(), encoding, newline
 
 
-def get_features_used(node: Node) -> Set[Feature]:  # noqa: C901
+def get_features_used(  # noqa: C901
+    node: Node, *, future_imports: Optional[Set[str]] = None
+) -> Set[Feature]:
     """Return a set of (relatively) new Python features used in this file.
 
     Currently looking for:
@@ -1142,9 +1144,17 @@ def get_features_used(node: Node) -> Set[Feature]:  # noqa: C901
     - positional only arguments in function signatures and lambdas;
     - assignment expression;
     - relaxed decorator syntax;
+    - usage of __future__ flags (annotations);
     - print / exec statements;
     """
     features: Set[Feature] = set()
+    if future_imports:
+        features |= {
+            FUTURE_FLAG_TO_FEATURE[future_import]
+            for future_import in future_imports
+            if future_import in FUTURE_FLAG_TO_FEATURE
+        }
+
     for n in node.pre_order():
         if n.type == token.STRING:
             value_head = n.value[:2]  # type: ignore
@@ -1229,9 +1239,11 @@ def get_features_used(node: Node) -> Set[Feature]:  # noqa: C901
     return features
 
 
-def detect_target_versions(node: Node) -> Set[TargetVersion]:
+def detect_target_versions(
+    node: Node, *, future_imports: Optional[Set[str]] = None
+) -> Set[TargetVersion]:
     """Detect the version to target based on the nodes used."""
-    features = get_features_used(node)
+    features = get_features_used(node, future_imports=future_imports)
     return {
         version for version in TargetVersion if features <= VERSION_TO_FEATURES[version]
     }
diff --git a/src/black/mode.py b/src/black/mode.py
index e2417531240..a2b7d9e9e2d 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -4,11 +4,18 @@
 chosen by the user.
 """
 
+import sys
+
 from dataclasses import dataclass, field
 from enum import Enum
 from operator import attrgetter
 from typing import Dict, Set
 
+if sys.version_info < (3, 8):
+    from typing_extensions import Final
+else:
+    from typing import Final
+
 from black.const import DEFAULT_LINE_LENGTH
 
 
@@ -44,6 +51,9 @@ class Feature(Enum):
     PATTERN_MATCHING = 11
     FORCE_OPTIONAL_PARENTHESES = 50
 
+    # __future__ flags
+    FUTURE_ANNOTATIONS = 51
+
     # temporary for Python 2 deprecation
     PRINT_STMT = 200
     EXEC_STMT = 201
@@ -55,6 +65,11 @@ class Feature(Enum):
     BACKQUOTE_REPR = 207
 
 
+FUTURE_FLAG_TO_FEATURE: Final = {
+    "annotations": Feature.FUTURE_ANNOTATIONS,
+}
+
+
 VERSION_TO_FEATURES: Dict[TargetVersion, Set[Feature]] = {
     TargetVersion.PY27: {
         Feature.ASYNC_IDENTIFIERS,
@@ -89,6 +104,7 @@ class Feature(Enum):
         Feature.TRAILING_COMMA_IN_CALL,
         Feature.TRAILING_COMMA_IN_DEF,
         Feature.ASYNC_KEYWORDS,
+        Feature.FUTURE_ANNOTATIONS,
     },
     TargetVersion.PY38: {
         Feature.UNICODE_LITERALS,
@@ -97,6 +113,7 @@ class Feature(Enum):
         Feature.TRAILING_COMMA_IN_CALL,
         Feature.TRAILING_COMMA_IN_DEF,
         Feature.ASYNC_KEYWORDS,
+        Feature.FUTURE_ANNOTATIONS,
         Feature.ASSIGNMENT_EXPRESSIONS,
         Feature.POS_ONLY_ARGUMENTS,
     },
@@ -107,6 +124,7 @@ class Feature(Enum):
         Feature.TRAILING_COMMA_IN_CALL,
         Feature.TRAILING_COMMA_IN_DEF,
         Feature.ASYNC_KEYWORDS,
+        Feature.FUTURE_ANNOTATIONS,
         Feature.ASSIGNMENT_EXPRESSIONS,
         Feature.RELAXED_DECORATORS,
         Feature.POS_ONLY_ARGUMENTS,
@@ -118,6 +136,7 @@ class Feature(Enum):
         Feature.TRAILING_COMMA_IN_CALL,
         Feature.TRAILING_COMMA_IN_DEF,
         Feature.ASYNC_KEYWORDS,
+        Feature.FUTURE_ANNOTATIONS,
         Feature.ASSIGNMENT_EXPRESSIONS,
         Feature.RELAXED_DECORATORS,
         Feature.POS_ONLY_ARGUMENTS,
diff --git a/tests/test_black.py b/tests/test_black.py
index 92598532e2c..2d0a7dfd4e2 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -811,6 +811,24 @@ def test_get_features_used(self) -> None:
         node = black.lib2to3_parse("def fn(a, /, b): ...")
         self.assertEqual(black.get_features_used(node), {Feature.POS_ONLY_ARGUMENTS})
 
+    def test_get_features_used_for_future_flags(self) -> None:
+        for src, features in [
+            ("from __future__ import annotations", {Feature.FUTURE_ANNOTATIONS}),
+            (
+                "from __future__ import (other, annotations)",
+                {Feature.FUTURE_ANNOTATIONS},
+            ),
+            ("a = 1 + 2\nfrom something import annotations", set()),
+            ("from __future__ import x, y", set()),
+        ]:
+            with self.subTest(src=src, features=features):
+                node = black.lib2to3_parse(src)
+                future_imports = black.get_future_imports(node)
+                self.assertEqual(
+                    black.get_features_used(node, future_imports=future_imports),
+                    features,
+                )
+
     def test_get_future_imports(self) -> None:
         node = black.lib2to3_parse("\n")
         self.assertEqual(set(), black.get_future_imports(node))

From 3083f4470bba6838d0ad59e9748f45a7621623b5 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Tue, 14 Dec 2021 19:32:14 -0500
Subject: [PATCH 0382/1034] Don't colour diff headers white, only bold
 (GH-2691)

So people with light themed terminals can still read 'em.
---
 CHANGES.md          | 2 ++
 src/black/output.py | 2 +-
 tests/test_black.py | 4 ++--
 3 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 87e36f4dbe7..c73295c4a0d 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -7,6 +7,8 @@
 - Improve error message for invalid regular expression (#2678)
 - Fix mapping cases that contain as-expressions, like `case {"key": 1 | 2 as password}`
   (#2686)
+- No longer color diff headers white as it's unreadable in light themed terminals
+  (#2691)
 
 ## 21.12b0
 
diff --git a/src/black/output.py b/src/black/output.py
index f030d0a0d08..9561d4b57d2 100644
--- a/src/black/output.py
+++ b/src/black/output.py
@@ -81,7 +81,7 @@ def color_diff(contents: str) -> str:
     lines = contents.split("\n")
     for i, line in enumerate(lines):
         if line.startswith("+++") or line.startswith("---"):
-            line = "\033[1;37m" + line + "\033[0m"  # bold white, reset
+            line = "\033[1m" + line + "\033[0m"  # bold, reset
         elif line.startswith("@@"):
             line = "\033[36m" + line + "\033[0m"  # cyan, reset
         elif line.startswith("+"):
diff --git a/tests/test_black.py b/tests/test_black.py
index 2d0a7dfd4e2..468f00fcafb 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -200,7 +200,7 @@ def test_piping_diff_with_color(self) -> None:
         )
         actual = result.output
         # Again, the contents are checked in a different test, so only look for colors.
-        self.assertIn("\033[1;37m", actual)
+        self.assertIn("\033[1m", actual)
         self.assertIn("\033[36m", actual)
         self.assertIn("\033[32m", actual)
         self.assertIn("\033[31m", actual)
@@ -323,7 +323,7 @@ def test_expression_diff_with_color(self) -> None:
         actual = result.output
         # We check the contents of the diff in `test_expression_diff`. All
         # we need to check here is that color codes exist in the result.
-        self.assertIn("\033[1;37m", actual)
+        self.assertIn("\033[1m", actual)
         self.assertIn("\033[36m", actual)
         self.assertIn("\033[32m", actual)
         self.assertIn("\033[31m", actual)

From 72fbacd996b7337af6659d1d7c280e401733af4b Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Tue, 14 Dec 2021 20:25:47 -0500
Subject: [PATCH 0383/1034] chore: dump docs deps and pre-commit hooks (#2676)

---
 .github/dependabot.yml  | 17 +++++++++++++++++
 .pre-commit-config.yaml |  4 ++--
 docs/requirements.txt   |  4 ++--
 3 files changed, 21 insertions(+), 4 deletions(-)
 create mode 100644 .github/dependabot.yml

diff --git a/.github/dependabot.yml b/.github/dependabot.yml
new file mode 100644
index 00000000000..1d9c3ccc032
--- /dev/null
+++ b/.github/dependabot.yml
@@ -0,0 +1,17 @@
+# https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    # Workflow files in .github/workflows will be checked
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels: ["skip news", "C: dependencies"]
+
+  - package-ecosystem: "python"
+    directory: "docs/"
+    schedule:
+      interval: "weekly"
+    labels: ["skip news", "C: dependencies", "T: documentation"]
+    reviewers: ["ichard26"]
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 45810d2844a..52a18623612 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -41,7 +41,7 @@ repos:
           - flake8-simplify
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v0.910
+    rev: v0.910-1
     hooks:
       - id: mypy
         exclude: ^docs/conf.py
@@ -54,7 +54,7 @@ repos:
           - platformdirs >= 2.1.0
 
   - repo: https://github.com/pre-commit/mirrors-prettier
-    rev: v2.3.2
+    rev: v2.5.1
     hooks:
       - id: prettier
         exclude: ^Pipfile\.lock
diff --git a/docs/requirements.txt b/docs/requirements.txt
index 296efc5cc84..b15d6b62c39 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,6 +1,6 @@
 # Used by ReadTheDocs; pinned requirements for stability.
 
-myst-parser==0.15.1
-Sphinx==4.2.0
+myst-parser==0.15.2
+Sphinx==4.3.1
 sphinxcontrib-programoutput==0.17
 sphinx_copybutton==0.4.0

From 93701d249e2cadf0ec096a752a5cbbe8da1a1130 Mon Sep 17 00:00:00 2001
From: aru <genericusername414@gmail.com>
Date: Tue, 14 Dec 2021 21:21:15 -0500
Subject: [PATCH 0384/1034] use valid package-ecosystem key (#2694)

---
 .github/dependabot.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/dependabot.yml b/.github/dependabot.yml
index 1d9c3ccc032..325cb31af1c 100644
--- a/.github/dependabot.yml
+++ b/.github/dependabot.yml
@@ -9,7 +9,7 @@ updates:
       interval: "weekly"
     labels: ["skip news", "C: dependencies"]
 
-  - package-ecosystem: "python"
+  - package-ecosystem: "pip"
     directory: "docs/"
     schedule:
       interval: "weekly"

From 3501cefb09eb8448bd82287840c9093f10c25299 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Tue, 14 Dec 2021 21:21:28 -0500
Subject: [PATCH 0385/1034] Include underlying error when AST safety check
 parsing fails (#2693)

---
 CHANGES.md            |  2 ++
 src/black/__init__.py |  2 +-
 tests/test_black.py   | 10 ++++++++++
 3 files changed, 13 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index c73295c4a0d..9208be7cd96 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -5,6 +5,8 @@
 ### _Black_
 
 - Improve error message for invalid regular expression (#2678)
+- Improve error message when parsing fails during AST safety check by embedding the
+  underlying SyntaxError (#2693)
 - Fix mapping cases that contain as-expressions, like `case {"key": 1 | 2 as password}`
   (#2686)
 - No longer color diff headers white as it's unreadable in light themed terminals
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 59018d00de4..f2efdec83b2 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -1305,7 +1305,7 @@ def assert_equivalent(src: str, dst: str, *, pass_num: int = 1) -> None:
         src_ast = parse_ast(src)
     except Exception as exc:
         raise AssertionError(
-            "cannot use --safe with this file; failed to parse source file."
+            f"cannot use --safe with this file; failed to parse source file: {exc}"
         ) from exc
 
     try:
diff --git a/tests/test_black.py b/tests/test_black.py
index 468f00fcafb..63cd716c0bb 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -1584,6 +1584,16 @@ def test_for_handled_unexpected_eof_error(self) -> None:
 
         exc_info.match("Cannot parse: 2:0: EOF in multi-line statement")
 
+    def test_equivalency_ast_parse_failure_includes_error(self) -> None:
+        with pytest.raises(AssertionError) as err:
+            black.assert_equivalent("a«»a  = 1", "a«»a  = 1")
+
+        err.match("--safe")
+        # Unfortunately the SyntaxError message has changed in newer versions so we
+        # can't match it directly.
+        err.match("invalid character")
+        err.match(r"\(<unknown>, line 1\)")
+
 
 class TestCaching:
     def test_cache_broken_file(self) -> None:

From e9f520c16abc8a864b61ae658bc3c91fda46fdd0 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Wed, 15 Dec 2021 18:26:01 -0500
Subject: [PATCH 0386/1034] Bump myst-parser from 0.15.2 to 0.16.0 in /docs
 (GH-2696)

Bumps [myst-parser](https://github.com/executablebooks/MyST-Parser) from 0.15.2 to 0.16.0.
- [Release notes](https://github.com/executablebooks/MyST-Parser/releases)
- [Changelog](https://github.com/executablebooks/MyST-Parser/blob/master/CHANGELOG.md)
- [Commits](https://github.com/executablebooks/MyST-Parser/compare/v0.15.2...v0.16.0)

---
updated-dependencies:
- dependency-name: myst-parser
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 docs/requirements.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index b15d6b62c39..57eccb7818f 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,6 +1,6 @@
 # Used by ReadTheDocs; pinned requirements for stability.
 
-myst-parser==0.15.2
+myst-parser==0.16.0
 Sphinx==4.3.1
 sphinxcontrib-programoutput==0.17
 sphinx_copybutton==0.4.0

From f10ce0c942b41cd4c6802ba690a432c6adedc05e Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Wed, 15 Dec 2021 18:55:26 -0500
Subject: [PATCH 0387/1034] Bump pre-commit/action from 2.0.2 to 2.0.3
 (GH-2695)

Bumps [pre-commit/action](https://github.com/pre-commit/action) from 2.0.2 to 2.0.3.
- [Release notes](https://github.com/pre-commit/action/releases)
- [Commits](https://github.com/pre-commit/action/compare/v2.0.2...v2.0.3)

---
updated-dependencies:
- dependency-name: pre-commit/action
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/lint.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index 51f6d02e2e6..2f6c504d3f2 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -25,4 +25,4 @@ jobs:
           python -m pip install -e '.[d]'
 
       - name: Lint
-        uses: pre-commit/action@v2.0.2
+        uses: pre-commit/action@v2.0.3

From dc90d4951f66ac665582159537b902017d9a0361 Mon Sep 17 00:00:00 2001
From: Batuhan Taskaya <isidentical@gmail.com>
Date: Thu, 16 Dec 2021 03:17:33 +0300
Subject: [PATCH 0388/1034] Unpacking on flow constructs (return/yield) now
 implies 3.8+ (#2700)

---
 CHANGES.md            | 1 +
 src/black/__init__.py | 8 ++++++++
 src/black/mode.py     | 4 ++++
 tests/test_black.py   | 8 ++++++++
 4 files changed, 21 insertions(+)

diff --git a/CHANGES.md b/CHANGES.md
index 9208be7cd96..ae0bf80da48 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -11,6 +11,7 @@
   (#2686)
 - No longer color diff headers white as it's unreadable in light themed terminals
   (#2691)
+- Tuple unpacking on `return` and `yield` constructs now implies 3.8+ (#2700)
 
 ## 21.12b0
 
diff --git a/src/black/__init__.py b/src/black/__init__.py
index f2efdec83b2..08c239dc155 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -1210,6 +1210,14 @@ def get_features_used(  # noqa: C901
                         if argch.type in STARS:
                             features.add(feature)
 
+        elif (
+            n.type in {syms.return_stmt, syms.yield_expr}
+            and len(n.children) >= 2
+            and n.children[1].type == syms.testlist_star_expr
+            and any(child.type == syms.star_expr for child in n.children[1].children)
+        ):
+            features.add(Feature.UNPACKING_ON_FLOW)
+
         # Python 2 only features (for its deprecation) except for integers, see above
         elif n.type == syms.print_stmt:
             features.add(Feature.PRINT_STMT)
diff --git a/src/black/mode.py b/src/black/mode.py
index a2b7d9e9e2d..b28dcd8d149 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -49,6 +49,7 @@ class Feature(Enum):
     POS_ONLY_ARGUMENTS = 9
     RELAXED_DECORATORS = 10
     PATTERN_MATCHING = 11
+    UNPACKING_ON_FLOW = 12
     FORCE_OPTIONAL_PARENTHESES = 50
 
     # __future__ flags
@@ -116,6 +117,7 @@ class Feature(Enum):
         Feature.FUTURE_ANNOTATIONS,
         Feature.ASSIGNMENT_EXPRESSIONS,
         Feature.POS_ONLY_ARGUMENTS,
+        Feature.UNPACKING_ON_FLOW,
     },
     TargetVersion.PY39: {
         Feature.UNICODE_LITERALS,
@@ -128,6 +130,7 @@ class Feature(Enum):
         Feature.ASSIGNMENT_EXPRESSIONS,
         Feature.RELAXED_DECORATORS,
         Feature.POS_ONLY_ARGUMENTS,
+        Feature.UNPACKING_ON_FLOW,
     },
     TargetVersion.PY310: {
         Feature.UNICODE_LITERALS,
@@ -140,6 +143,7 @@ class Feature(Enum):
         Feature.ASSIGNMENT_EXPRESSIONS,
         Feature.RELAXED_DECORATORS,
         Feature.POS_ONLY_ARGUMENTS,
+        Feature.UNPACKING_ON_FLOW,
         Feature.PATTERN_MATCHING,
     },
 }
diff --git a/tests/test_black.py b/tests/test_black.py
index 63cd716c0bb..8726cc10ddc 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -810,6 +810,14 @@ def test_get_features_used(self) -> None:
         self.assertEqual(black.get_features_used(node), {Feature.POS_ONLY_ARGUMENTS})
         node = black.lib2to3_parse("def fn(a, /, b): ...")
         self.assertEqual(black.get_features_used(node), {Feature.POS_ONLY_ARGUMENTS})
+        node = black.lib2to3_parse("def fn(): yield a, b")
+        self.assertEqual(black.get_features_used(node), set())
+        node = black.lib2to3_parse("def fn(): return a, b")
+        self.assertEqual(black.get_features_used(node), set())
+        node = black.lib2to3_parse("def fn(): yield *b, c")
+        self.assertEqual(black.get_features_used(node), {Feature.UNPACKING_ON_FLOW})
+        node = black.lib2to3_parse("def fn(): return a, *b, c")
+        self.assertEqual(black.get_features_used(node), {Feature.UNPACKING_ON_FLOW})
 
     def test_get_features_used_for_future_flags(self) -> None:
         for src, features in [

From 61fe8418cc868723759fb08d76adab1542bb7630 Mon Sep 17 00:00:00 2001
From: Mike Taves <mwtoews@gmail.com>
Date: Thu, 16 Dec 2021 16:35:01 +1300
Subject: [PATCH 0389/1034] Use 'python -m build' to build wheel and source
 distributions (#2701)

---
 .github/workflows/pypi_upload.yml | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/pypi_upload.yml b/.github/workflows/pypi_upload.yml
index 201d94fd85e..0921b624c45 100644
--- a/.github/workflows/pypi_upload.yml
+++ b/.github/workflows/pypi_upload.yml
@@ -15,14 +15,14 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v2
 
-      - name: Install latest pip, setuptools, twine + wheel
+      - name: Install latest pip, build, twine
         run: |
-          python -m pip install --upgrade pip setuptools twine wheel
+          python -m pip install --upgrade --disable-pip-version-check pip
+          python -m pip install --upgrade build twine
 
-      - name: Build wheels
+      - name: Build wheel and source distributions
         run: |
-          python setup.py bdist_wheel
-          python setup.py sdist
+          python -m build
 
       - name: Upload to PyPI via Twine
         env:

From b97ec62368ac57b29a0ccd5fc68ba875418eb8cc Mon Sep 17 00:00:00 2001
From: Batuhan Taskaya <isidentical@gmail.com>
Date: Sat, 18 Dec 2021 00:43:14 +0300
Subject: [PATCH 0390/1034] Imply 3.8+ when annotated assigments used with
 unparenthesized tuples (#2708)

---
 CHANGES.md            |  2 ++
 src/black/__init__.py |  7 +++++++
 src/black/mode.py     |  4 ++++
 tests/test_black.py   | 12 ++++++++++++
 4 files changed, 25 insertions(+)

diff --git a/CHANGES.md b/CHANGES.md
index ae0bf80da48..0452f1820c4 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -12,6 +12,8 @@
 - No longer color diff headers white as it's unreadable in light themed terminals
   (#2691)
 - Tuple unpacking on `return` and `yield` constructs now implies 3.8+ (#2700)
+- Unparenthesized tuples on annotated assignments (e.g
+  `values: Tuple[int, ...] = 1, 2, 3`) now implies 3.8+ (#2708)
 
 ## 21.12b0
 
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 08c239dc155..d8b98196aa0 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -1218,6 +1218,13 @@ def get_features_used(  # noqa: C901
         ):
             features.add(Feature.UNPACKING_ON_FLOW)
 
+        elif (
+            n.type == syms.annassign
+            and len(n.children) >= 4
+            and n.children[3].type == syms.testlist_star_expr
+        ):
+            features.add(Feature.ANN_ASSIGN_EXTENDED_RHS)
+
         # Python 2 only features (for its deprecation) except for integers, see above
         elif n.type == syms.print_stmt:
             features.add(Feature.PRINT_STMT)
diff --git a/src/black/mode.py b/src/black/mode.py
index b28dcd8d149..bd4428add66 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -50,6 +50,7 @@ class Feature(Enum):
     RELAXED_DECORATORS = 10
     PATTERN_MATCHING = 11
     UNPACKING_ON_FLOW = 12
+    ANN_ASSIGN_EXTENDED_RHS = 13
     FORCE_OPTIONAL_PARENTHESES = 50
 
     # __future__ flags
@@ -118,6 +119,7 @@ class Feature(Enum):
         Feature.ASSIGNMENT_EXPRESSIONS,
         Feature.POS_ONLY_ARGUMENTS,
         Feature.UNPACKING_ON_FLOW,
+        Feature.ANN_ASSIGN_EXTENDED_RHS,
     },
     TargetVersion.PY39: {
         Feature.UNICODE_LITERALS,
@@ -131,6 +133,7 @@ class Feature(Enum):
         Feature.RELAXED_DECORATORS,
         Feature.POS_ONLY_ARGUMENTS,
         Feature.UNPACKING_ON_FLOW,
+        Feature.ANN_ASSIGN_EXTENDED_RHS,
     },
     TargetVersion.PY310: {
         Feature.UNICODE_LITERALS,
@@ -144,6 +147,7 @@ class Feature(Enum):
         Feature.RELAXED_DECORATORS,
         Feature.POS_ONLY_ARGUMENTS,
         Feature.UNPACKING_ON_FLOW,
+        Feature.ANN_ASSIGN_EXTENDED_RHS,
         Feature.PATTERN_MATCHING,
     },
 }
diff --git a/tests/test_black.py b/tests/test_black.py
index 8726cc10ddc..628647ed977 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -818,6 +818,18 @@ def test_get_features_used(self) -> None:
         self.assertEqual(black.get_features_used(node), {Feature.UNPACKING_ON_FLOW})
         node = black.lib2to3_parse("def fn(): return a, *b, c")
         self.assertEqual(black.get_features_used(node), {Feature.UNPACKING_ON_FLOW})
+        node = black.lib2to3_parse("x = a, *b, c")
+        self.assertEqual(black.get_features_used(node), set())
+        node = black.lib2to3_parse("x: Any = regular")
+        self.assertEqual(black.get_features_used(node), set())
+        node = black.lib2to3_parse("x: Any = (regular, regular)")
+        self.assertEqual(black.get_features_used(node), set())
+        node = black.lib2to3_parse("x: Any = Complex(Type(1))[something]")
+        self.assertEqual(black.get_features_used(node), set())
+        node = black.lib2to3_parse("x: Tuple[int, ...] = a, b, c")
+        self.assertEqual(
+            black.get_features_used(node), {Feature.ANN_ASSIGN_EXTENDED_RHS}
+        )
 
     def test_get_features_used_for_future_flags(self) -> None:
         for src, features in [

From 6ef3e466db7ad91dd6300d2412222ec912ae56e2 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 20 Dec 2021 07:24:53 -0800
Subject: [PATCH 0391/1034] Bump sphinx from 4.3.1 to 4.3.2 in /docs (#2709)

Bumps [sphinx](https://github.com/sphinx-doc/sphinx) from 4.3.1 to 4.3.2.
- [Release notes](https://github.com/sphinx-doc/sphinx/releases)
- [Changelog](https://github.com/sphinx-doc/sphinx/blob/4.x/CHANGES)
- [Commits](https://github.com/sphinx-doc/sphinx/compare/v4.3.1...v4.3.2)

---
updated-dependencies:
- dependency-name: sphinx
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 docs/requirements.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index 57eccb7818f..f08c389f459 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,6 +1,6 @@
 # Used by ReadTheDocs; pinned requirements for stability.
 
 myst-parser==0.16.0
-Sphinx==4.3.1
+Sphinx==4.3.2
 sphinxcontrib-programoutput==0.17
 sphinx_copybutton==0.4.0

From c5b458ef4ba1b6a62685461c6731f1775bee132b Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 20 Dec 2021 07:42:03 -0800
Subject: [PATCH 0392/1034] Bump myst-parser from 0.16.0 to 0.16.1 in /docs
 (#2710)

Bumps [myst-parser](https://github.com/executablebooks/MyST-Parser) from 0.16.0 to 0.16.1.
- [Release notes](https://github.com/executablebooks/MyST-Parser/releases)
- [Changelog](https://github.com/executablebooks/MyST-Parser/blob/master/CHANGELOG.md)
- [Commits](https://github.com/executablebooks/MyST-Parser/compare/v0.16.0...v0.16.1)

---
updated-dependencies:
- dependency-name: myst-parser
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 docs/requirements.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index f08c389f459..0cdef2a39dd 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,6 +1,6 @@
 # Used by ReadTheDocs; pinned requirements for stability.
 
-myst-parser==0.16.0
+myst-parser==0.16.1
 Sphinx==4.3.2
 sphinxcontrib-programoutput==0.17
 sphinx_copybutton==0.4.0

From 389e9c23a9e622ee6090d902cc5f56c5f76cdee9 Mon Sep 17 00:00:00 2001
From: Taneli Hukkinen <3275109+hukkin@users.noreply.github.com>
Date: Tue, 21 Dec 2021 18:03:07 +0200
Subject: [PATCH 0393/1034] Disable universal newlines when reading TOML
 (#2408)

---
 CHANGES.md         | 1 +
 Pipfile            | 2 +-
 setup.py           | 2 +-
 src/black/files.py | 4 ++--
 4 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 0452f1820c4..252f2cc8863 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -4,6 +4,7 @@
 
 ### _Black_
 
+- Do not accept bare carriage return line endings in pyproject.toml (#2408)
 - Improve error message for invalid regular expression (#2678)
 - Improve error message when parsing fails during AST safety check by embedding the
   underlying SyntaxError (#2693)
diff --git a/Pipfile b/Pipfile
index a3af5fd8844..90d4a2a78c1 100644
--- a/Pipfile
+++ b/Pipfile
@@ -42,7 +42,7 @@ platformdirs= ">=2"
 click = ">=8.0.0"
 mypy_extensions = ">=0.4.3"
 pathspec = ">=0.8.1"
-tomli = ">=0.2.6, <2.0.0"
+tomli = ">=1.1.0, <3.0.0"
 typed-ast = "==1.4.3"
 typing_extensions = {markers = "python_version < '3.10'", version = ">=3.10.0.0"}
 black = {editable = true,extras = ["d"],path = "."}
diff --git a/setup.py b/setup.py
index a21bc87264d..d314bb283f2 100644
--- a/setup.py
+++ b/setup.py
@@ -99,7 +99,7 @@ def find_python_files(base: Path) -> List[Path]:
     install_requires=[
         "click>=7.1.2",
         "platformdirs>=2",
-        "tomli>=0.2.6,<2.0.0",
+        "tomli>=1.1.0,<3.0.0",
         "typed-ast>=1.4.2; python_version < '3.8' and implementation_name == 'cpython'",
         "pathspec>=0.9.0, <1",
         "dataclasses>=0.6; python_version < '3.7'",
diff --git a/src/black/files.py b/src/black/files.py
index 560aa05080d..dfab9f73039 100644
--- a/src/black/files.py
+++ b/src/black/files.py
@@ -95,8 +95,8 @@ def parse_pyproject_toml(path_config: str) -> Dict[str, Any]:
 
     If parsing fails, will raise a tomli.TOMLDecodeError
     """
-    with open(path_config, encoding="utf8") as f:
-        pyproject_toml = tomli.loads(f.read())
+    with open(path_config, "rb") as f:
+        pyproject_toml = tomli.load(f)
     config = pyproject_toml.get("tool", {}).get("black", {})
     return {k.replace("--", "").replace("-", "_"): v for k, v in config.items()}
 

From 7c94ed61a55f8ae0c60737cbc6cfee3b5066ce11 Mon Sep 17 00:00:00 2001
From: Marco Edward Gorelli <marcogorelli@protonmail.com>
Date: Tue, 21 Dec 2021 16:20:55 +0000
Subject: [PATCH 0394/1034] Define is_name_token (and friends) to resolve some
 `type: ignore`s (GH-2714)

Gets rid of a few # type: ignores by using TypeGuard.
---
 src/black/__init__.py |  5 +++--
 src/black/linegen.py  | 13 +++++++------
 src/black/nodes.py    | 28 ++++++++++++++++++++++++----
 3 files changed, 34 insertions(+), 12 deletions(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index d8b98196aa0..9bc8fc15c49 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -37,6 +37,7 @@
 from black.const import DEFAULT_LINE_LENGTH, DEFAULT_INCLUDES, DEFAULT_EXCLUDES
 from black.const import STDIN_PLACEHOLDER
 from black.nodes import STARS, syms, is_simple_decorator_expression
+from black.nodes import is_string_token
 from black.lines import Line, EmptyLineTracker
 from black.linegen import transform_line, LineGenerator, LN
 from black.comments import normalize_fmt_off
@@ -1156,8 +1157,8 @@ def get_features_used(  # noqa: C901
         }
 
     for n in node.pre_order():
-        if n.type == token.STRING:
-            value_head = n.value[:2]  # type: ignore
+        if is_string_token(n):
+            value_head = n.value[:2]
             if value_head in {'f"', 'F"', "f'", "F'", "rf", "fr", "RF", "FR"}:
                 features.add(Feature.F_STRINGS)
 
diff --git a/src/black/linegen.py b/src/black/linegen.py
index f234913a161..c1cd6fa22d9 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -9,6 +9,7 @@
 from black.nodes import ASSIGNMENTS, OPENING_BRACKETS, CLOSING_BRACKETS
 from black.nodes import Visitor, syms, first_child_is_arith, ensure_visible
 from black.nodes import is_docstring, is_empty_tuple, is_one_tuple, is_one_tuple_between
+from black.nodes import is_name_token, is_lpar_token, is_rpar_token
 from black.nodes import is_walrus_assignment, is_yield, is_vararg, is_multiline_string
 from black.nodes import is_stub_suite, is_stub_body, is_atom_with_invisible_parens
 from black.nodes import wrap_in_parentheses
@@ -137,7 +138,7 @@ def visit_stmt(
         """
         normalize_invisible_parens(node, parens_after=parens)
         for child in node.children:
-            if child.type == token.NAME and child.value in keywords:  # type: ignore
+            if is_name_token(child) and child.value in keywords:
                 yield from self.line()
 
             yield from self.visit(child)
@@ -813,9 +814,9 @@ def normalize_invisible_parens(node: Node, parens_after: Set[str]) -> None:
             elif node.type == syms.import_from:
                 # "import from" nodes store parentheses directly as part of
                 # the statement
-                if child.type == token.LPAR:
+                if is_lpar_token(child):
                     # make parentheses invisible
-                    child.value = ""  # type: ignore
+                    child.value = ""
                     node.children[-1].value = ""  # type: ignore
                 elif child.type != token.STAR:
                     # insert invisible parentheses
@@ -861,11 +862,11 @@ def maybe_make_parens_invisible_in_atom(node: LN, parent: LN) -> bool:
 
     first = node.children[0]
     last = node.children[-1]
-    if first.type == token.LPAR and last.type == token.RPAR:
+    if is_lpar_token(first) and is_rpar_token(last):
         middle = node.children[1]
         # make parentheses invisible
-        first.value = ""  # type: ignore
-        last.value = ""  # type: ignore
+        first.value = ""
+        last.value = ""
         maybe_make_parens_invisible_in_atom(middle, parent=parent)
 
         if is_atom_with_invisible_parens(middle):
diff --git a/src/black/nodes.py b/src/black/nodes.py
index 8bf1934bc2a..75a23474024 100644
--- a/src/black/nodes.py
+++ b/src/black/nodes.py
@@ -19,11 +19,15 @@
     from typing import Final
 else:
     from typing_extensions import Final
+if sys.version_info >= (3, 10):
+    from typing import TypeGuard
+else:
+    from typing_extensions import TypeGuard
 
 from mypy_extensions import mypyc_attr
 
 # lib2to3 fork
-from blib2to3.pytree import Node, Leaf, type_repr
+from blib2to3.pytree import Node, Leaf, type_repr, NL
 from blib2to3 import pygram
 from blib2to3.pgen2 import token
 
@@ -260,8 +264,8 @@ def whitespace(leaf: Leaf, *, complex_subscript: bool) -> str:  # noqa: C901
             and prevp.parent
             and prevp.parent.type == syms.shift_expr
             and prevp.prev_sibling
-            and prevp.prev_sibling.type == token.NAME
-            and prevp.prev_sibling.value == "print"  # type: ignore
+            and is_name_token(prevp.prev_sibling)
+            and prevp.prev_sibling.value == "print"
         ):
             # Python 2 print chevron
             return NO
@@ -687,7 +691,7 @@ def is_yield(node: LN) -> bool:
     if node.type == syms.yield_expr:
         return True
 
-    if node.type == token.NAME and node.value == "yield":  # type: ignore
+    if is_name_token(node) and node.value == "yield":
         return True
 
     if node.type != syms.atom:
@@ -854,3 +858,19 @@ def ensure_visible(leaf: Leaf) -> None:
         leaf.value = "("
     elif leaf.type == token.RPAR:
         leaf.value = ")"
+
+
+def is_name_token(nl: NL) -> TypeGuard[Leaf]:
+    return nl.type == token.NAME
+
+
+def is_lpar_token(nl: NL) -> TypeGuard[Leaf]:
+    return nl.type == token.LPAR
+
+
+def is_rpar_token(nl: NL) -> TypeGuard[Leaf]:
+    return nl.type == token.RPAR
+
+
+def is_string_token(nl: NL) -> TypeGuard[Leaf]:
+    return nl.type == token.STRING

From c758126a270bb5a78513f3f07ddd60bc4aacf4a4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C5=81ukasz=20Langa?= <lukasz@langa.pl>
Date: Tue, 21 Dec 2021 17:24:20 +0100
Subject: [PATCH 0395/1034] Remove usage of Pipenv, rely on good ol' `pip` and
 `virtualenv` in docs (#2717)

---
 Pipfile                         |   49 -
 Pipfile.lock                    | 1958 -------------------------------
 docs/contributing/the_basics.md |   33 +-
 3 files changed, 12 insertions(+), 2028 deletions(-)
 delete mode 100644 Pipfile
 delete mode 100644 Pipfile.lock

diff --git a/Pipfile b/Pipfile
deleted file mode 100644
index 90d4a2a78c1..00000000000
--- a/Pipfile
+++ /dev/null
@@ -1,49 +0,0 @@
-[[source]]
-name = "pypi"
-url = "https://pypi.python.org/simple"
-verify_ssl = true
-
-[dev-packages]
-# Testing related requirements.
-coverage = ">= 5.3"
-pytest = " >= 6.1.1"
-pytest-xdist = ">= 2.2.1"
-pytest-cov = ">= 2.11.1"
-tox = "*"
-
-# Linting related requirements.
-pre-commit = ">=2.9.2"
-flake8 = ">=3.9.2"
-flake8-bugbear = "*"
-mypy = ">=0.910"
-types-dataclasses = ">=0.1.3"
-types-typed-ast = ">=1.4.1"
-types-PyYAML = ">=5.4.1"
-
-# Documentation related requirements.
-Sphinx = ">=4.1.2"
-MyST-Parser = ">=0.15.1"
-sphinxcontrib-programoutput = ">=0.17"
-sphinx-copybutton = ">=0.4.0"
-docutils = "==0.17.1"  # not a direct dependency, see https://github.com/pypa/pipenv/issues/3865
-
-# Packaging related requirements.
-setuptools = ">=39.2.0"
-setuptools-scm = "*"
-twine = ">=1.11.0"
-wheel = ">=0.31.1"
-readme_renderer = "*"
-
-black = {editable = true, extras = ["d", "jupyter"], path = "."}
-
-[packages]
-aiohttp = ">=3.7.4"
-platformdirs= ">=2"
-click = ">=8.0.0"
-mypy_extensions = ">=0.4.3"
-pathspec = ">=0.8.1"
-tomli = ">=1.1.0, <3.0.0"
-typed-ast = "==1.4.3"
-typing_extensions = {markers = "python_version < '3.10'", version = ">=3.10.0.0"}
-black = {editable = true,extras = ["d"],path = "."}
-dataclasses = {markers = "python_version < '3.7'", version = ">0.1.3"}
diff --git a/Pipfile.lock b/Pipfile.lock
deleted file mode 100644
index b2a9f6c6fc0..00000000000
--- a/Pipfile.lock
+++ /dev/null
@@ -1,1958 +0,0 @@
-{
-    "_meta": {
-        "hash": {
-            "sha256": "7728caac52b47ed119a804ead88afa002d62c17a324e962b7833b8944049609b"
-        },
-        "pipfile-spec": 6,
-        "requires": {},
-        "sources": [
-            {
-                "name": "pypi",
-                "url": "https://pypi.python.org/simple",
-                "verify_ssl": true
-            }
-        ]
-    },
-    "default": {
-        "aiohttp": {
-            "hashes": [
-                "sha256:09754a0d5eaab66c37591f2f8fac8f9781a5f61d51aa852a3261c4805ca6b984",
-                "sha256:097ecf52f6b9859b025c1e36401f8aa4573552e887d1b91b4b999d68d0b5a3b3",
-                "sha256:0a96473a1f61d7920a9099bc8e729dc8282539d25f79c12573ee0fdb9c8b66a8",
-                "sha256:0af379221975054162959e00daf21159ff69a712fc42ed0052caddbd70d52ff4",
-                "sha256:0d7b056fd3972d353cb4bc305c03f9381583766b7f8c7f1c44478dba69099e33",
-                "sha256:14a6f026eca80dfa3d52e86be89feb5cd878f6f4a6adb34457e2c689fd85229b",
-                "sha256:15a660d06092b7c92ed17c1dbe6c1eab0a02963992d60e3e8b9d5fa7fa81f01e",
-                "sha256:1fa9f50aa1f114249b7963c98e20dc35c51be64096a85bc92433185f331de9cc",
-                "sha256:257f4fad1714d26d562572095c8c5cd271d5a333252795cb7a002dca41fdbad7",
-                "sha256:28369fe331a59d80393ec82df3d43307c7461bfaf9217999e33e2acc7984ff7c",
-                "sha256:2bdd655732e38b40f8a8344d330cfae3c727fb257585df923316aabbd489ccb8",
-                "sha256:2f44d1b1c740a9e2275160d77c73a11f61e8a916191c572876baa7b282bcc934",
-                "sha256:3ba08a71caa42eef64357257878fb17f3fba3fba6e81a51d170e32321569e079",
-                "sha256:3c5e9981e449d54308c6824f172ec8ab63eb9c5f922920970249efee83f7e919",
-                "sha256:3f58aa995b905ab82fe228acd38538e7dc1509e01508dcf307dad5046399130f",
-                "sha256:48c996eb91bfbdab1e01e2c02e7ff678c51e2b28e3a04e26e41691991cc55795",
-                "sha256:48f218a5257b6bc16bcf26a91d97ecea0c7d29c811a90d965f3dd97c20f016d6",
-                "sha256:4a6551057a846bf72c7a04f73de3fcaca269c0bd85afe475ceb59d261c6a938c",
-                "sha256:51f90dabd9933b1621260b32c2f0d05d36923c7a5a909eb823e429dba0fd2f3e",
-                "sha256:577cc2c7b807b174814dac2d02e673728f2e46c7f90ceda3a70ea4bb6d90b769",
-                "sha256:5d79174d96446a02664e2bffc95e7b6fa93b9e6d8314536c5840dff130d0878b",
-                "sha256:5e3f81fbbc170418e22918a9585fd7281bbc11d027064d62aa4b507552c92671",
-                "sha256:5ecffdc748d3b40dd3618ede0170e4f5e1d3c9647cfb410d235d19e62cb54ee0",
-                "sha256:63fa57a0708573d3c059f7b5527617bd0c291e4559298473df238d502e4ab98c",
-                "sha256:67ca7032dfac8d001023fadafc812d9f48bf8a8c3bb15412d9cdcf92267593f4",
-                "sha256:688a1eb8c1a5f7e795c7cb67e0fe600194e6723ba35f138dfae0db20c0cb8f94",
-                "sha256:6a038cb1e6e55b26bb5520ccffab7f539b3786f5553af2ee47eb2ec5cbd7084e",
-                "sha256:6b79f6c31e68b6dafc0317ec453c83c86dd8db1f8f0c6f28e97186563fca87a0",
-                "sha256:6d3e027fe291b77f6be9630114a0200b2c52004ef20b94dc50ca59849cd623b3",
-                "sha256:6f1d39a744101bf4043fa0926b3ead616607578192d0a169974fb5265ab1e9d2",
-                "sha256:707adc30ea6918fba725c3cb3fe782d271ba352b22d7ae54a7f9f2e8a8488c41",
-                "sha256:730b7c2b7382194d9985ffdc32ab317e893bca21e0665cb1186bdfbb4089d990",
-                "sha256:764c7c6aa1f78bd77bd9674fc07d1ec44654da1818d0eef9fb48aa8371a3c847",
-                "sha256:78d51e35ed163783d721b6f2ce8ce3f82fccfe471e8e50a10fba13a766d31f5a",
-                "sha256:7a315ceb813208ef32bdd6ec3a85cbe3cb3be9bbda5fd030c234592fa9116993",
-                "sha256:7ba09bb3dcb0b7ec936a485db2b64be44fe14cdce0a5eac56f50e55da3627385",
-                "sha256:7d76e8a83396e06abe3df569b25bd3fc88bf78b7baa2c8e4cf4aaf5983af66a3",
-                "sha256:84fe1732648c1bc303a70faa67cbc2f7f2e810c8a5bca94f6db7818e722e4c0a",
-                "sha256:871d4fdc56288caa58b1094c20f2364215f7400411f76783ea19ad13be7c8e19",
-                "sha256:88d4917c30fcd7f6404fb1dc713fa21de59d3063dcc048f4a8a1a90e6bbbd739",
-                "sha256:8a50150419b741ee048b53146c39c47053f060cb9d98e78be08fdbe942eaa3c4",
-                "sha256:90a97c2ed2830e7974cbe45f0838de0aefc1c123313f7c402e21c29ec063fbb4",
-                "sha256:949a605ef3907254b122f845baa0920407080cdb1f73aa64f8d47df4a7f4c4f9",
-                "sha256:9689af0f0a89e5032426c143fa3683b0451f06c83bf3b1e27902bd33acfae769",
-                "sha256:98b1ea2763b33559dd9ec621d67fc17b583484cb90735bfb0ec3614c17b210e4",
-                "sha256:9951c2696c4357703001e1fe6edc6ae8e97553ac630492ea1bf64b429cb712a3",
-                "sha256:9a52b141ff3b923a9166595de6e3768a027546e75052ffba267d95b54267f4ab",
-                "sha256:9e8723c3256641e141cd18f6ce478d54a004138b9f1a36e41083b36d9ecc5fc5",
-                "sha256:a2fee4d656a7cc9ab47771b2a9e8fad8a9a33331c1b59c3057ecf0ac858f5bfe",
-                "sha256:a4759e85a191de58e0ea468ab6fd9c03941986eee436e0518d7a9291fab122c8",
-                "sha256:a5399a44a529083951b55521cf4ecbf6ad79fd54b9df57dbf01699ffa0549fc9",
-                "sha256:a6074a3b2fa2d0c9bf0963f8dfc85e1e54a26114cc8594126bc52d3fa061c40e",
-                "sha256:a84c335337b676d832c1e2bc47c3a97531b46b82de9f959dafb315cbcbe0dfcd",
-                "sha256:adf0cb251b1b842c9dee5cfcdf880ba0aae32e841b8d0e6b6feeaef002a267c5",
-                "sha256:b76669b7c058b8020b11008283c3b8e9c61bfd978807c45862956119b77ece45",
-                "sha256:bda75d73e7400e81077b0910c9a60bf9771f715420d7e35fa7739ae95555f195",
-                "sha256:be03a7483ad9ea60388f930160bb3728467dd0af538aa5edc60962ee700a0bdc",
-                "sha256:c62d4791a8212c885b97a63ef5f3974b2cd41930f0cd224ada9c6ee6654f8150",
-                "sha256:cb751ef712570d3bda9a73fd765ff3e1aba943ec5d52a54a0c2e89c7eef9da1e",
-                "sha256:d3b19d8d183bcfd68b25beebab8dc3308282fe2ca3d6ea3cb4cd101b3c279f8d",
-                "sha256:d3f90ee275b1d7c942e65b5c44c8fb52d55502a0b9a679837d71be2bd8927661",
-                "sha256:d5f8c04574efa814a24510122810e3a3c77c0552f9f6ff65c9862f1f046be2c3",
-                "sha256:d6a1a66bb8bac9bc2892c2674ea363486bfb748b86504966a390345a11b1680e",
-                "sha256:d7715daf84f10bcebc083ad137e3eced3e1c8e7fa1f096ade9a8d02b08f0d91c",
-                "sha256:dafc01a32b4a1d7d3ef8bfd3699406bb44f7b2e0d3eb8906d574846e1019b12f",
-                "sha256:dcc4d5dd5fba3affaf4fd08f00ef156407573de8c63338787614ccc64f96b321",
-                "sha256:de42f513ed7a997bc821bddab356b72e55e8396b1b7ba1bf39926d538a76a90f",
-                "sha256:e27cde1e8d17b09730801ce97b6e0c444ba2a1f06348b169fd931b51d3402f0d",
-                "sha256:ecb314e59bedb77188017f26e6b684b1f6d0465e724c3122a726359fa62ca1ba",
-                "sha256:f348ebd20554e8bc26e8ef3ed8a134110c0f4bf015b3b4da6a4ddf34e0515b19",
-                "sha256:fa818609357dde5c4a94a64c097c6404ad996b1d38ca977a72834b682830a722",
-                "sha256:fe4a327da0c6b6e59f2e474ae79d6ee7745ac3279fd15f200044602fa31e3d79"
-            ],
-            "index": "pypi",
-            "version": "==3.8.0"
-        },
-        "aiosignal": {
-            "hashes": [
-                "sha256:26e62109036cd181df6e6ad646f91f0dcfd05fe16d0cb924138ff2ab75d64e3a",
-                "sha256:78ed67db6c7b7ced4f98e495e572106d5c432a93e1ddd1bf475e1dc05f5b7df2"
-            ],
-            "markers": "python_version >= '3.6'",
-            "version": "==1.2.0"
-        },
-        "async-timeout": {
-            "hashes": [
-                "sha256:a22c0b311af23337eb05fcf05a8b51c3ea53729d46fb5460af62bee033cec690",
-                "sha256:b930cb161a39042f9222f6efb7301399c87eeab394727ec5437924a36d6eef51"
-            ],
-            "markers": "python_version >= '3.6'",
-            "version": "==4.0.1"
-        },
-        "asynctest": {
-            "hashes": [
-                "sha256:5da6118a7e6d6b54d83a8f7197769d046922a44d2a99c21382f0a6e4fadae676",
-                "sha256:c27862842d15d83e6a34eb0b2866c323880eb3a75e4485b079ea11748fd77fac"
-            ],
-            "markers": "python_version < '3.8'",
-            "version": "==0.13.0"
-        },
-        "attrs": {
-            "hashes": [
-                "sha256:149e90d6d8ac20db7a955ad60cf0e6881a3f20d37096140088356da6c716b0b1",
-                "sha256:ef6aaac3ca6cd92904cdd0d83f629a15f18053ec84e6432106f7a4d04ae4f5fb"
-            ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
-            "version": "==21.2.0"
-        },
-        "black": {
-            "editable": true,
-            "extras": [
-                "d"
-            ],
-            "path": "."
-        },
-        "charset-normalizer": {
-            "hashes": [
-                "sha256:e019de665e2bcf9c2b64e2e5aa025fa991da8720daa3c1138cadd2fd1856aed0",
-                "sha256:f7af805c321bfa1ce6714c51f254e0d5bb5e5834039bc17db7ebe3a4cec9492b"
-            ],
-            "markers": "python_version >= '3.5'",
-            "version": "==2.0.7"
-        },
-        "click": {
-            "hashes": [
-                "sha256:353f466495adaeb40b6b5f592f9f91cb22372351c84caeb068132442a4518ef3",
-                "sha256:410e932b050f5eed773c4cda94de75971c89cdb3155a72a0831139a79e5ecb5b"
-            ],
-            "index": "pypi",
-            "version": "==8.0.3"
-        },
-        "dataclasses": {
-            "hashes": [
-                "sha256:0201d89fa866f68c8ebd9d08ee6ff50c0b255f8ec63a71c16fda7af82bb887bf",
-                "sha256:8479067f342acf957dc82ec415d355ab5edb7e7646b90dc6e2fd1d96ad084c97"
-            ],
-            "index": "pypi",
-            "markers": "python_version < '3.7'",
-            "version": "==0.8"
-        },
-        "frozenlist": {
-            "hashes": [
-                "sha256:01d79515ed5aa3d699b05f6bdcf1fe9087d61d6b53882aa599a10853f0479c6c",
-                "sha256:0a7c7cce70e41bc13d7d50f0e5dd175f14a4f1837a8549b0936ed0cbe6170bf9",
-                "sha256:11ff401951b5ac8c0701a804f503d72c048173208490c54ebb8d7bb7c07a6d00",
-                "sha256:14a5cef795ae3e28fb504b73e797c1800e9249f950e1c964bb6bdc8d77871161",
-                "sha256:16eef427c51cb1203a7c0ab59d1b8abccaba9a4f58c4bfca6ed278fc896dc193",
-                "sha256:16ef7dd5b7d17495404a2e7a49bac1bc13d6d20c16d11f4133c757dd94c4144c",
-                "sha256:181754275d5d32487431a0a29add4f897968b7157204bc1eaaf0a0ce80c5ba7d",
-                "sha256:1cf63243bc5f5c19762943b0aa9e0d3fb3723d0c514d820a18a9b9a5ef864315",
-                "sha256:1cfe6fef507f8bac40f009c85c7eddfed88c1c0d38c75e72fe10476cef94e10f",
-                "sha256:1fef737fd1388f9b93bba8808c5f63058113c10f4e3c0763ced68431773f72f9",
-                "sha256:25b358aaa7dba5891b05968dd539f5856d69f522b6de0bf34e61f133e077c1a4",
-                "sha256:26f602e380a5132880fa245c92030abb0fc6ff34e0c5500600366cedc6adb06a",
-                "sha256:28e164722ea0df0cf6d48c4d5bdf3d19e87aaa6dfb39b0ba91153f224b912020",
-                "sha256:2de5b931701257d50771a032bba4e448ff958076380b049fd36ed8738fdb375b",
-                "sha256:3457f8cf86deb6ce1ba67e120f1b0128fcba1332a180722756597253c465fc1d",
-                "sha256:351686ca020d1bcd238596b1fa5c8efcbc21bffda9d0efe237aaa60348421e2a",
-                "sha256:406aeb340613b4b559db78d86864485f68919b7141dec82aba24d1477fd2976f",
-                "sha256:41de4db9b9501679cf7cddc16d07ac0f10ef7eb58c525a1c8cbff43022bddca4",
-                "sha256:41f62468af1bd4e4b42b5508a3fe8cc46a693f0cdd0ca2f443f51f207893d837",
-                "sha256:4766632cd8a68e4f10f156a12c9acd7b1609941525569dd3636d859d79279ed3",
-                "sha256:47b2848e464883d0bbdcd9493c67443e5e695a84694efff0476f9059b4cb6257",
-                "sha256:4a495c3d513573b0b3f935bfa887a85d9ae09f0627cf47cad17d0cc9b9ba5c38",
-                "sha256:4ad065b2ebd09f32511ff2be35c5dfafee6192978b5a1e9d279a5c6e121e3b03",
-                "sha256:4c457220468d734e3077580a3642b7f682f5fd9507f17ddf1029452450912cdc",
-                "sha256:4f52d0732e56906f8ddea4bd856192984650282424049c956857fed43697ea43",
-                "sha256:54a1e09ab7a69f843cd28fefd2bcaf23edb9e3a8d7680032c8968b8ac934587d",
-                "sha256:5a72eecf37eface331636951249d878750db84034927c997d47f7f78a573b72b",
-                "sha256:5df31bb2b974f379d230a25943d9bf0d3bc666b4b0807394b131a28fca2b0e5f",
-                "sha256:66a518731a21a55b7d3e087b430f1956a36793acc15912e2878431c7aec54210",
-                "sha256:6790b8d96bbb74b7a6f4594b6f131bd23056c25f2aa5d816bd177d95245a30e3",
-                "sha256:68201be60ac56aff972dc18085800b6ee07973c49103a8aba669dee3d71079de",
-                "sha256:6e105013fa84623c057a4381dc8ea0361f4d682c11f3816cc80f49a1f3bc17c6",
-                "sha256:705c184b77565955a99dc360f359e8249580c6b7eaa4dc0227caa861ef46b27a",
-                "sha256:72cfbeab7a920ea9e74b19aa0afe3b4ad9c89471e3badc985d08756efa9b813b",
-                "sha256:735f386ec522e384f511614c01d2ef9cf799f051353876b4c6fb93ef67a6d1ee",
-                "sha256:82d22f6e6f2916e837c91c860140ef9947e31194c82aaeda843d6551cec92f19",
-                "sha256:83334e84a290a158c0c4cc4d22e8c7cfe0bba5b76d37f1c2509dabd22acafe15",
-                "sha256:84e97f59211b5b9083a2e7a45abf91cfb441369e8bb6d1f5287382c1c526def3",
-                "sha256:87521e32e18a2223311afc2492ef2d99946337da0779ddcda77b82ee7319df59",
-                "sha256:878ebe074839d649a1cdb03a61077d05760624f36d196884a5cafb12290e187b",
-                "sha256:89fdfc84c6bf0bff2ff3170bb34ecba8a6911b260d318d377171429c4be18c73",
-                "sha256:8b4c7665a17c3a5430edb663e4ad4e1ad457614d1b2f2b7f87052e2ef4fa45ca",
-                "sha256:8b54cdd2fda15467b9b0bfa78cee2ddf6dbb4585ef23a16e14926f4b076dfae4",
-                "sha256:94728f97ddf603d23c8c3dd5cae2644fa12d33116e69f49b1644a71bb77b89ae",
-                "sha256:954b154a4533ef28bd3e83ffdf4eadf39deeda9e38fb8feaf066d6069885e034",
-                "sha256:977a1438d0e0d96573fd679d291a1542097ea9f4918a8b6494b06610dfeefbf9",
-                "sha256:9ade70aea559ca98f4b1b1e5650c45678052e76a8ab2f76d90f2ac64180215a2",
-                "sha256:9b6e21e5770df2dea06cb7b6323fbc008b13c4a4e3b52cb54685276479ee7676",
-                "sha256:a0d3ffa8772464441b52489b985d46001e2853a3b082c655ec5fad9fb6a3d618",
-                "sha256:a37594ad6356e50073fe4f60aa4187b97d15329f2138124d252a5a19c8553ea4",
-                "sha256:a8d86547a5e98d9edd47c432f7a14b0c5592624b496ae9880fb6332f34af1edc",
-                "sha256:aa44c4740b4e23fcfa259e9dd52315d2b1770064cde9507457e4c4a65a04c397",
-                "sha256:acc4614e8d1feb9f46dd829a8e771b8f5c4b1051365d02efb27a3229048ade8a",
-                "sha256:af2a51c8a381d76eabb76f228f565ed4c3701441ecec101dd18be70ebd483cfd",
-                "sha256:b2ae2f5e9fa10805fb1c9adbfefaaecedd9e31849434be462c3960a0139ed729",
-                "sha256:b46f997d5ed6d222a863b02cdc9c299101ee27974d9bbb2fd1b3c8441311c408",
-                "sha256:bc93f5f62df3bdc1f677066327fc81f92b83644852a31c6aa9b32c2dde86ea7d",
-                "sha256:bfbaa08cf1452acad9cb1c1d7b89394a41e712f88df522cea1a0f296b57782a0",
-                "sha256:c1e8e9033d34c2c9e186e58279879d78c94dd365068a3607af33f2bc99357a53",
-                "sha256:c5328ed53fdb0a73c8a50105306a3bc013e5ca36cca714ec4f7bd31d38d8a97f",
-                "sha256:c6a9d84ee6427b65a81fc24e6ef589cb794009f5ca4150151251c062773e7ed2",
-                "sha256:c98d3c04701773ad60d9545cd96df94d955329efc7743fdb96422c4b669c633b",
-                "sha256:cb3957c39668d10e2b486acc85f94153520a23263b6401e8f59422ef65b9520d",
-                "sha256:e63ad0beef6ece06475d29f47d1f2f29727805376e09850ebf64f90777962792",
-                "sha256:e74f8b4d8677ebb4015ac01fcaf05f34e8a1f22775db1f304f497f2f88fdc697",
-                "sha256:e7d0dd3e727c70c2680f5f09a0775525229809f1a35d8552b92ff10b2b14f2c2",
-                "sha256:ec6cf345771cdb00791d271af9a0a6fbfc2b6dd44cb753f1eeaa256e21622adb",
-                "sha256:ed58803563a8c87cf4c0771366cf0ad1aa265b6b0ae54cbbb53013480c7ad74d",
-                "sha256:f0081a623c886197ff8de9e635528fd7e6a387dccef432149e25c13946cb0cd0",
-                "sha256:f025f1d6825725b09c0038775acab9ae94264453a696cc797ce20c0769a7b367",
-                "sha256:f5f3b2942c3b8b9bfe76b408bbaba3d3bb305ee3693e8b1d631fe0a0d4f93673",
-                "sha256:fbd4844ff111449f3bbe20ba24fbb906b5b1c2384d0f3287c9f7da2354ce6d23"
-            ],
-            "markers": "python_version >= '3.6'",
-            "version": "==1.2.0"
-        },
-        "idna": {
-            "hashes": [
-                "sha256:84d9dd047ffa80596e0f246e2eab0b391788b0503584e8945f2368256d2735ff",
-                "sha256:9d643ff0a55b762d5cdb124b8eaa99c66322e2157b69160bc32796e824360e6d"
-            ],
-            "markers": "python_version >= '3.5'",
-            "version": "==3.3"
-        },
-        "idna-ssl": {
-            "hashes": [
-                "sha256:a933e3bb13da54383f9e8f35dc4f9cb9eb9b3b78c6b36f311254d6d0d92c6c7c"
-            ],
-            "markers": "python_version < '3.7'",
-            "version": "==1.1.0"
-        },
-        "importlib-metadata": {
-            "hashes": [
-                "sha256:53ccfd5c134223e497627b9815d5030edf77d2ed573922f7a0b8f8bb81a1c100",
-                "sha256:75bdec14c397f528724c1bfd9709d660b33a4d2e77387a3358f20b848bb5e5fb"
-            ],
-            "markers": "python_version < '3.8'",
-            "version": "==4.8.2"
-        },
-        "multidict": {
-            "hashes": [
-                "sha256:06560fbdcf22c9387100979e65b26fba0816c162b888cb65b845d3def7a54c9b",
-                "sha256:067150fad08e6f2dd91a650c7a49ba65085303fcc3decbd64a57dc13a2733031",
-                "sha256:0a2cbcfbea6dc776782a444db819c8b78afe4db597211298dd8b2222f73e9cd0",
-                "sha256:0dd1c93edb444b33ba2274b66f63def8a327d607c6c790772f448a53b6ea59ce",
-                "sha256:0fed465af2e0eb6357ba95795d003ac0bdb546305cc2366b1fc8f0ad67cc3fda",
-                "sha256:116347c63ba049c1ea56e157fa8aa6edaf5e92925c9b64f3da7769bdfa012858",
-                "sha256:1b4ac3ba7a97b35a5ccf34f41b5a8642a01d1e55454b699e5e8e7a99b5a3acf5",
-                "sha256:1c7976cd1c157fa7ba5456ae5d31ccdf1479680dc9b8d8aa28afabc370df42b8",
-                "sha256:246145bff76cc4b19310f0ad28bd0769b940c2a49fc601b86bfd150cbd72bb22",
-                "sha256:25cbd39a9029b409167aa0a20d8a17f502d43f2efebfe9e3ac019fe6796c59ac",
-                "sha256:28e6d883acd8674887d7edc896b91751dc2d8e87fbdca8359591a13872799e4e",
-                "sha256:2d1d55cdf706ddc62822d394d1df53573d32a7a07d4f099470d3cb9323b721b6",
-                "sha256:2e77282fd1d677c313ffcaddfec236bf23f273c4fba7cdf198108f5940ae10f5",
-                "sha256:32fdba7333eb2351fee2596b756d730d62b5827d5e1ab2f84e6cbb287cc67fe0",
-                "sha256:35591729668a303a02b06e8dba0eb8140c4a1bfd4c4b3209a436a02a5ac1de11",
-                "sha256:380b868f55f63d048a25931a1632818f90e4be71d2081c2338fcf656d299949a",
-                "sha256:3822c5894c72e3b35aae9909bef66ec83e44522faf767c0ad39e0e2de11d3b55",
-                "sha256:38ba256ee9b310da6a1a0f013ef4e422fca30a685bcbec86a969bd520504e341",
-                "sha256:3bc3b1621b979621cee9f7b09f024ec76ec03cc365e638126a056317470bde1b",
-                "sha256:3d2d7d1fff8e09d99354c04c3fd5b560fb04639fd45926b34e27cfdec678a704",
-                "sha256:517d75522b7b18a3385726b54a081afd425d4f41144a5399e5abd97ccafdf36b",
-                "sha256:5f79c19c6420962eb17c7e48878a03053b7ccd7b69f389d5831c0a4a7f1ac0a1",
-                "sha256:5f841c4f14331fd1e36cbf3336ed7be2cb2a8f110ce40ea253e5573387db7621",
-                "sha256:637c1896497ff19e1ee27c1c2c2ddaa9f2d134bbb5e0c52254361ea20486418d",
-                "sha256:6ee908c070020d682e9b42c8f621e8bb10c767d04416e2ebe44e37d0f44d9ad5",
-                "sha256:77f0fb7200cc7dedda7a60912f2059086e29ff67cefbc58d2506638c1a9132d7",
-                "sha256:7878b61c867fb2df7a95e44b316f88d5a3742390c99dfba6c557a21b30180cac",
-                "sha256:78c106b2b506b4d895ddc801ff509f941119394b89c9115580014127414e6c2d",
-                "sha256:8b911d74acdc1fe2941e59b4f1a278a330e9c34c6c8ca1ee21264c51ec9b67ef",
-                "sha256:93de39267c4c676c9ebb2057e98a8138bade0d806aad4d864322eee0803140a0",
-                "sha256:9416cf11bcd73c861267e88aea71e9fcc35302b3943e45e1dbb4317f91a4b34f",
-                "sha256:94b117e27efd8e08b4046c57461d5a114d26b40824995a2eb58372b94f9fca02",
-                "sha256:9815765f9dcda04921ba467957be543423e5ec6a1136135d84f2ae092c50d87b",
-                "sha256:98ec9aea6223adf46999f22e2c0ab6cf33f5914be604a404f658386a8f1fba37",
-                "sha256:a37e9a68349f6abe24130846e2f1d2e38f7ddab30b81b754e5a1fde32f782b23",
-                "sha256:a43616aec0f0d53c411582c451f5d3e1123a68cc7b3475d6f7d97a626f8ff90d",
-                "sha256:a4771d0d0ac9d9fe9e24e33bed482a13dfc1256d008d101485fe460359476065",
-                "sha256:a5635bcf1b75f0f6ef3c8a1ad07b500104a971e38d3683167b9454cb6465ac86",
-                "sha256:a9acb76d5f3dd9421874923da2ed1e76041cb51b9337fd7f507edde1d86535d6",
-                "sha256:ac42181292099d91217a82e3fa3ce0e0ddf3a74fd891b7c2b347a7f5aa0edded",
-                "sha256:b227345e4186809d31f22087d0265655114af7cda442ecaf72246275865bebe4",
-                "sha256:b61f85101ef08cbbc37846ac0e43f027f7844f3fade9b7f6dd087178caedeee7",
-                "sha256:b70913cbf2e14275013be98a06ef4b412329fe7b4f83d64eb70dce8269ed1e1a",
-                "sha256:b9aad49466b8d828b96b9e3630006234879c8d3e2b0a9d99219b3121bc5cdb17",
-                "sha256:baf1856fab8212bf35230c019cde7c641887e3fc08cadd39d32a421a30151ea3",
-                "sha256:bd6c9c50bf2ad3f0448edaa1a3b55b2e6866ef8feca5d8dbec10ec7c94371d21",
-                "sha256:c1ff762e2ee126e6f1258650ac641e2b8e1f3d927a925aafcfde943b77a36d24",
-                "sha256:c30ac9f562106cd9e8071c23949a067b10211917fdcb75b4718cf5775356a940",
-                "sha256:c9631c642e08b9fff1c6255487e62971d8b8e821808ddd013d8ac058087591ac",
-                "sha256:cdd68778f96216596218b4e8882944d24a634d984ee1a5a049b300377878fa7c",
-                "sha256:ce8cacda0b679ebc25624d5de66c705bc53dcc7c6f02a7fb0f3ca5e227d80422",
-                "sha256:cfde464ca4af42a629648c0b0d79b8f295cf5b695412451716531d6916461628",
-                "sha256:d3def943bfd5f1c47d51fd324df1e806d8da1f8e105cc7f1c76a1daf0f7e17b0",
-                "sha256:d9b668c065968c5979fe6b6fa6760bb6ab9aeb94b75b73c0a9c1acf6393ac3bf",
-                "sha256:da7d57ea65744d249427793c042094c4016789eb2562576fb831870f9c878d9e",
-                "sha256:dc3a866cf6c13d59a01878cd806f219340f3e82eed514485e094321f24900677",
-                "sha256:df23c83398715b26ab09574217ca21e14694917a0c857e356fd39e1c64f8283f",
-                "sha256:dfc924a7e946dd3c6360e50e8f750d51e3ef5395c95dc054bc9eab0f70df4f9c",
-                "sha256:e4a67f1080123de76e4e97a18d10350df6a7182e243312426d508712e99988d4",
-                "sha256:e5283c0a00f48e8cafcecadebfa0ed1dac8b39e295c7248c44c665c16dc1138b",
-                "sha256:e58a9b5cc96e014ddf93c2227cbdeca94b56a7eb77300205d6e4001805391747",
-                "sha256:e6453f3cbeb78440747096f239d282cc57a2997a16b5197c9bc839099e1633d0",
-                "sha256:e6c4fa1ec16e01e292315ba76eb1d012c025b99d22896bd14a66628b245e3e01",
-                "sha256:e7d81ce5744757d2f05fc41896e3b2ae0458464b14b5a2c1e87a6a9d69aefaa8",
-                "sha256:ea21d4d5104b4f840b91d9dc8cbc832aba9612121eaba503e54eaab1ad140eb9",
-                "sha256:ecc99bce8ee42dcad15848c7885197d26841cb24fa2ee6e89d23b8993c871c64",
-                "sha256:f0bb0973f42ffcb5e3537548e0767079420aefd94ba990b61cf7bb8d47f4916d",
-                "sha256:f19001e790013ed580abfde2a4465388950728861b52f0da73e8e8a9418533c0",
-                "sha256:f76440e480c3b2ca7f843ff8a48dc82446b86ed4930552d736c0bac507498a52",
-                "sha256:f9bef5cff994ca3026fcc90680e326d1a19df9841c5e3d224076407cc21471a1",
-                "sha256:fc66d4016f6e50ed36fb39cd287a3878ffcebfa90008535c62e0e90a7ab713ae",
-                "sha256:fd77c8f3cba815aa69cb97ee2b2ef385c7c12ada9c734b0f3b32e26bb88bbf1d"
-            ],
-            "markers": "python_version >= '3.6'",
-            "version": "==5.2.0"
-        },
-        "mypy-extensions": {
-            "hashes": [
-                "sha256:090fedd75945a69ae91ce1303b5824f428daf5a028d2f6ab8a299250a846f15d",
-                "sha256:2d82818f5bb3e369420cb3c4060a7970edba416647068eb4c5343488a6c604a8"
-            ],
-            "index": "pypi",
-            "version": "==0.4.3"
-        },
-        "packaging": {
-            "hashes": [
-                "sha256:096d689d78ca690e4cd8a89568ba06d07ca097e3306a4381635073ca91479966",
-                "sha256:14317396d1e8cdb122989b916fa2c7e9ca8e2be9e8060a6eff75b6b7b4d8a7e0"
-            ],
-            "markers": "python_version >= '3.6'",
-            "version": "==21.2"
-        },
-        "pathspec": {
-            "hashes": [
-                "sha256:7d15c4ddb0b5c802d161efc417ec1a2558ea2653c2e8ad9c19098201dc1c993a",
-                "sha256:e564499435a2673d586f6b2130bb5b95f04a3ba06f81b8f895b651a3c76aabb1"
-            ],
-            "index": "pypi",
-            "version": "==0.9.0"
-        },
-        "platformdirs": {
-            "hashes": [
-                "sha256:367a5e80b3d04d2428ffa76d33f124cf11e8fff2acdaa9b43d545f5c7d661ef2",
-                "sha256:8868bbe3c3c80d42f20156f22e7131d2fb321f5bc86a2a345375c6481a67021d"
-            ],
-            "index": "pypi",
-            "version": "==2.4.0"
-        },
-        "pyparsing": {
-            "hashes": [
-                "sha256:c203ec8783bf771a155b207279b9bccb8dea02d8f0c9e5f8ead507bc3246ecc1",
-                "sha256:ef9d7589ef3c200abe66653d3f1ab1033c3c419ae9b9bdb1240a85b024efc88b"
-            ],
-            "markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==2.4.7"
-        },
-        "setuptools": {
-            "hashes": [
-                "sha256:a481fbc56b33f5d8f6b33dce41482e64c68b668be44ff42922903b03872590bf",
-                "sha256:dae6b934a965c8a59d6d230d3867ec408bb95e73bd538ff77e71fedf1eaca729"
-            ],
-            "markers": "python_version >= '3.6'",
-            "version": "==58.5.3"
-        },
-        "setuptools-scm": {
-            "extras": [
-                "toml"
-            ],
-            "hashes": [
-                "sha256:4c64444b1d49c4063ae60bfe1680f611c8b13833d556fd1d6050c0023162a119",
-                "sha256:a49aa8081eeb3514eb9728fa5040f2eaa962d6c6f4ec9c32f6c1fba88f88a0f2"
-            ],
-            "markers": "python_version >= '3.6'",
-            "version": "==6.3.2"
-        },
-        "tomli": {
-            "hashes": [
-                "sha256:c6ce0015eb38820eaf32b5db832dbc26deb3dd427bd5f6556cf0acac2c214fee",
-                "sha256:f04066f68f5554911363063a30b108d2b5a5b1a010aa8b6132af78489fe3aade"
-            ],
-            "index": "pypi",
-            "version": "==1.2.2"
-        },
-        "typed-ast": {
-            "hashes": [
-                "sha256:01ae5f73431d21eead5015997ab41afa53aa1fbe252f9da060be5dad2c730ace",
-                "sha256:067a74454df670dcaa4e59349a2e5c81e567d8d65458d480a5b3dfecec08c5ff",
-                "sha256:0fb71b8c643187d7492c1f8352f2c15b4c4af3f6338f21681d3681b3dc31a266",
-                "sha256:1b3ead4a96c9101bef08f9f7d1217c096f31667617b58de957f690c92378b528",
-                "sha256:2068531575a125b87a41802130fa7e29f26c09a2833fea68d9a40cf33902eba6",
-                "sha256:209596a4ec71d990d71d5e0d312ac935d86930e6eecff6ccc7007fe54d703808",
-                "sha256:2c726c276d09fc5c414693a2de063f521052d9ea7c240ce553316f70656c84d4",
-                "sha256:398e44cd480f4d2b7ee8d98385ca104e35c81525dd98c519acff1b79bdaac363",
-                "sha256:52b1eb8c83f178ab787f3a4283f68258525f8d70f778a2f6dd54d3b5e5fb4341",
-                "sha256:5feca99c17af94057417d744607b82dd0a664fd5e4ca98061480fd8b14b18d04",
-                "sha256:7538e495704e2ccda9b234b82423a4038f324f3a10c43bc088a1636180f11a41",
-                "sha256:760ad187b1041a154f0e4d0f6aae3e40fdb51d6de16e5c99aedadd9246450e9e",
-                "sha256:777a26c84bea6cd934422ac2e3b78863a37017618b6e5c08f92ef69853e765d3",
-                "sha256:95431a26309a21874005845c21118c83991c63ea800dd44843e42a916aec5899",
-                "sha256:9ad2c92ec681e02baf81fdfa056fe0d818645efa9af1f1cd5fd6f1bd2bdfd805",
-                "sha256:9c6d1a54552b5330bc657b7ef0eae25d00ba7ffe85d9ea8ae6540d2197a3788c",
-                "sha256:aee0c1256be6c07bd3e1263ff920c325b59849dc95392a05f258bb9b259cf39c",
-                "sha256:af3d4a73793725138d6b334d9d247ce7e5f084d96284ed23f22ee626a7b88e39",
-                "sha256:b36b4f3920103a25e1d5d024d155c504080959582b928e91cb608a65c3a49e1a",
-                "sha256:b9574c6f03f685070d859e75c7f9eeca02d6933273b5e69572e5ff9d5e3931c3",
-                "sha256:bff6ad71c81b3bba8fa35f0f1921fb24ff4476235a6e94a26ada2e54370e6da7",
-                "sha256:c190f0899e9f9f8b6b7863debfb739abcb21a5c054f911ca3596d12b8a4c4c7f",
-                "sha256:c907f561b1e83e93fad565bac5ba9c22d96a54e7ea0267c708bffe863cbe4075",
-                "sha256:cae53c389825d3b46fb37538441f75d6aecc4174f615d048321b716df2757fb0",
-                "sha256:dd4a21253f42b8d2b48410cb31fe501d32f8b9fbeb1f55063ad102fe9c425e40",
-                "sha256:dde816ca9dac1d9c01dd504ea5967821606f02e510438120091b84e852367428",
-                "sha256:f2362f3cb0f3172c42938946dbc5b7843c2a28aec307c49100c8b38764eb6927",
-                "sha256:f328adcfebed9f11301eaedfa48e15bdece9b519fb27e6a8c01aa52a17ec31b3",
-                "sha256:f8afcf15cc511ada719a88e013cec87c11aff7b91f019295eb4530f96fe5ef2f",
-                "sha256:fb1bbeac803adea29cedd70781399c99138358c26d05fcbd23c13016b7f5ec65"
-            ],
-            "index": "pypi",
-            "version": "==1.4.3"
-        },
-        "typing-extensions": {
-            "hashes": [
-                "sha256:49f75d16ff11f1cd258e1b988ccff82a3ca5570217d7ad8c5f48205dd99a677e",
-                "sha256:d8226d10bc02a29bcc81df19a26e56a9647f8b0a6d4a83924139f4a8b01f17b7",
-                "sha256:f1d25edafde516b146ecd0613dabcc61409817af4766fbbcfb8d1ad4ec441a34"
-            ],
-            "index": "pypi",
-            "markers": "python_version < '3.10'",
-            "version": "==3.10.0.2"
-        },
-        "yarl": {
-            "hashes": [
-                "sha256:044daf3012e43d4b3538562da94a88fb12a6490652dbc29fb19adfa02cf72eac",
-                "sha256:0cba38120db72123db7c58322fa69e3c0efa933040ffb586c3a87c063ec7cae8",
-                "sha256:167ab7f64e409e9bdd99333fe8c67b5574a1f0495dcfd905bc7454e766729b9e",
-                "sha256:1be4bbb3d27a4e9aa5f3df2ab61e3701ce8fcbd3e9846dbce7c033a7e8136746",
-                "sha256:1ca56f002eaf7998b5fcf73b2421790da9d2586331805f38acd9997743114e98",
-                "sha256:1d3d5ad8ea96bd6d643d80c7b8d5977b4e2fb1bab6c9da7322616fd26203d125",
-                "sha256:1eb6480ef366d75b54c68164094a6a560c247370a68c02dddb11f20c4c6d3c9d",
-                "sha256:1edc172dcca3f11b38a9d5c7505c83c1913c0addc99cd28e993efeaafdfaa18d",
-                "sha256:211fcd65c58bf250fb994b53bc45a442ddc9f441f6fec53e65de8cba48ded986",
-                "sha256:29e0656d5497733dcddc21797da5a2ab990c0cb9719f1f969e58a4abac66234d",
-                "sha256:368bcf400247318382cc150aaa632582d0780b28ee6053cd80268c7e72796dec",
-                "sha256:39d5493c5ecd75c8093fa7700a2fb5c94fe28c839c8e40144b7ab7ccba6938c8",
-                "sha256:3abddf0b8e41445426d29f955b24aeecc83fa1072be1be4e0d194134a7d9baee",
-                "sha256:3bf8cfe8856708ede6a73907bf0501f2dc4e104085e070a41f5d88e7faf237f3",
-                "sha256:3ec1d9a0d7780416e657f1e405ba35ec1ba453a4f1511eb8b9fbab81cb8b3ce1",
-                "sha256:45399b46d60c253327a460e99856752009fcee5f5d3c80b2f7c0cae1c38d56dd",
-                "sha256:52690eb521d690ab041c3919666bea13ab9fbff80d615ec16fa81a297131276b",
-                "sha256:534b047277a9a19d858cde163aba93f3e1677d5acd92f7d10ace419d478540de",
-                "sha256:580c1f15500e137a8c37053e4cbf6058944d4c114701fa59944607505c2fe3a0",
-                "sha256:59218fef177296451b23214c91ea3aba7858b4ae3306dde120224cfe0f7a6ee8",
-                "sha256:5ba63585a89c9885f18331a55d25fe81dc2d82b71311ff8bd378fc8004202ff6",
-                "sha256:5bb7d54b8f61ba6eee541fba4b83d22b8a046b4ef4d8eb7f15a7e35db2e1e245",
-                "sha256:6152224d0a1eb254f97df3997d79dadd8bb2c1a02ef283dbb34b97d4f8492d23",
-                "sha256:67e94028817defe5e705079b10a8438b8cb56e7115fa01640e9c0bb3edf67332",
-                "sha256:695ba021a9e04418507fa930d5f0704edbce47076bdcfeeaba1c83683e5649d1",
-                "sha256:6a1a9fe17621af43e9b9fcea8bd088ba682c8192d744b386ee3c47b56eaabb2c",
-                "sha256:6ab0c3274d0a846840bf6c27d2c60ba771a12e4d7586bf550eefc2df0b56b3b4",
-                "sha256:6feca8b6bfb9eef6ee057628e71e1734caf520a907b6ec0d62839e8293e945c0",
-                "sha256:737e401cd0c493f7e3dd4db72aca11cfe069531c9761b8ea474926936b3c57c8",
-                "sha256:788713c2896f426a4e166b11f4ec538b5736294ebf7d5f654ae445fd44270832",
-                "sha256:797c2c412b04403d2da075fb93c123df35239cd7b4cc4e0cd9e5839b73f52c58",
-                "sha256:8300401dc88cad23f5b4e4c1226f44a5aa696436a4026e456fe0e5d2f7f486e6",
-                "sha256:87f6e082bce21464857ba58b569370e7b547d239ca22248be68ea5d6b51464a1",
-                "sha256:89ccbf58e6a0ab89d487c92a490cb5660d06c3a47ca08872859672f9c511fc52",
-                "sha256:8b0915ee85150963a9504c10de4e4729ae700af11df0dc5550e6587ed7891e92",
-                "sha256:8cce6f9fa3df25f55521fbb5c7e4a736683148bcc0c75b21863789e5185f9185",
-                "sha256:95a1873b6c0dd1c437fb3bb4a4aaa699a48c218ac7ca1e74b0bee0ab16c7d60d",
-                "sha256:9b4c77d92d56a4c5027572752aa35082e40c561eec776048330d2907aead891d",
-                "sha256:9bfcd43c65fbb339dc7086b5315750efa42a34eefad0256ba114cd8ad3896f4b",
-                "sha256:9c1f083e7e71b2dd01f7cd7434a5f88c15213194df38bc29b388ccdf1492b739",
-                "sha256:a1d0894f238763717bdcfea74558c94e3bc34aeacd3351d769460c1a586a8b05",
-                "sha256:a467a431a0817a292121c13cbe637348b546e6ef47ca14a790aa2fa8cc93df63",
-                "sha256:aa32aaa97d8b2ed4e54dc65d241a0da1c627454950f7d7b1f95b13985afd6c5d",
-                "sha256:ac10bbac36cd89eac19f4e51c032ba6b412b3892b685076f4acd2de18ca990aa",
-                "sha256:ac35ccde589ab6a1870a484ed136d49a26bcd06b6a1c6397b1967ca13ceb3913",
-                "sha256:bab827163113177aee910adb1f48ff7af31ee0289f434f7e22d10baf624a6dfe",
-                "sha256:baf81561f2972fb895e7844882898bda1eef4b07b5b385bcd308d2098f1a767b",
-                "sha256:bf19725fec28452474d9887a128e98dd67eee7b7d52e932e6949c532d820dc3b",
-                "sha256:c01a89a44bb672c38f42b49cdb0ad667b116d731b3f4c896f72302ff77d71656",
-                "sha256:c0910c6b6c31359d2f6184828888c983d54d09d581a4a23547a35f1d0b9484b1",
-                "sha256:c10ea1e80a697cf7d80d1ed414b5cb8f1eec07d618f54637067ae3c0334133c4",
-                "sha256:c1164a2eac148d85bbdd23e07dfcc930f2e633220f3eb3c3e2a25f6148c2819e",
-                "sha256:c145ab54702334c42237a6c6c4cc08703b6aa9b94e2f227ceb3d477d20c36c63",
-                "sha256:c17965ff3706beedafd458c452bf15bac693ecd146a60a06a214614dc097a271",
-                "sha256:c19324a1c5399b602f3b6e7db9478e5b1adf5cf58901996fc973fe4fccd73eed",
-                "sha256:c2a1ac41a6aa980db03d098a5531f13985edcb451bcd9d00670b03129922cd0d",
-                "sha256:c6ddcd80d79c96eb19c354d9dca95291589c5954099836b7c8d29278a7ec0bda",
-                "sha256:c9c6d927e098c2d360695f2e9d38870b2e92e0919be07dbe339aefa32a090265",
-                "sha256:cc8b7a7254c0fc3187d43d6cb54b5032d2365efd1df0cd1749c0c4df5f0ad45f",
-                "sha256:cff3ba513db55cc6a35076f32c4cdc27032bd075c9faef31fec749e64b45d26c",
-                "sha256:d260d4dc495c05d6600264a197d9d6f7fc9347f21d2594926202fd08cf89a8ba",
-                "sha256:d6f3d62e16c10e88d2168ba2d065aa374e3c538998ed04996cd373ff2036d64c",
-                "sha256:da6df107b9ccfe52d3a48165e48d72db0eca3e3029b5b8cb4fe6ee3cb870ba8b",
-                "sha256:dfe4b95b7e00c6635a72e2d00b478e8a28bfb122dc76349a06e20792eb53a523",
-                "sha256:e39378894ee6ae9f555ae2de332d513a5763276a9265f8e7cbaeb1b1ee74623a",
-                "sha256:ede3b46cdb719c794427dcce9d8beb4abe8b9aa1e97526cc20de9bd6583ad1ef",
-                "sha256:f2a8508f7350512434e41065684076f640ecce176d262a7d54f0da41d99c5a95",
-                "sha256:f44477ae29025d8ea87ec308539f95963ffdc31a82f42ca9deecf2d505242e72",
-                "sha256:f64394bd7ceef1237cc604b5a89bf748c95982a84bcd3c4bbeb40f685c810794",
-                "sha256:fc4dd8b01a8112809e6b636b00f487846956402834a7fd59d46d4f4267181c41",
-                "sha256:fce78593346c014d0d986b7ebc80d782b7f5e19843ca798ed62f8e3ba8728576",
-                "sha256:fd547ec596d90c8676e369dd8a581a21227fe9b4ad37d0dc7feb4ccf544c2d59"
-            ],
-            "markers": "python_version >= '3.6'",
-            "version": "==1.7.2"
-        },
-        "zipp": {
-            "hashes": [
-                "sha256:71c644c5369f4a6e07636f0aa966270449561fcea2e3d6747b8d23efaa9d7832",
-                "sha256:9fe5ea21568a0a70e50f273397638d39b03353731e6cbbb3fd8502a33fec40bc"
-            ],
-            "markers": "python_version >= '3.6'",
-            "version": "==3.6.0"
-        }
-    },
-    "develop": {
-        "aiohttp": {
-            "hashes": [
-                "sha256:09754a0d5eaab66c37591f2f8fac8f9781a5f61d51aa852a3261c4805ca6b984",
-                "sha256:097ecf52f6b9859b025c1e36401f8aa4573552e887d1b91b4b999d68d0b5a3b3",
-                "sha256:0a96473a1f61d7920a9099bc8e729dc8282539d25f79c12573ee0fdb9c8b66a8",
-                "sha256:0af379221975054162959e00daf21159ff69a712fc42ed0052caddbd70d52ff4",
-                "sha256:0d7b056fd3972d353cb4bc305c03f9381583766b7f8c7f1c44478dba69099e33",
-                "sha256:14a6f026eca80dfa3d52e86be89feb5cd878f6f4a6adb34457e2c689fd85229b",
-                "sha256:15a660d06092b7c92ed17c1dbe6c1eab0a02963992d60e3e8b9d5fa7fa81f01e",
-                "sha256:1fa9f50aa1f114249b7963c98e20dc35c51be64096a85bc92433185f331de9cc",
-                "sha256:257f4fad1714d26d562572095c8c5cd271d5a333252795cb7a002dca41fdbad7",
-                "sha256:28369fe331a59d80393ec82df3d43307c7461bfaf9217999e33e2acc7984ff7c",
-                "sha256:2bdd655732e38b40f8a8344d330cfae3c727fb257585df923316aabbd489ccb8",
-                "sha256:2f44d1b1c740a9e2275160d77c73a11f61e8a916191c572876baa7b282bcc934",
-                "sha256:3ba08a71caa42eef64357257878fb17f3fba3fba6e81a51d170e32321569e079",
-                "sha256:3c5e9981e449d54308c6824f172ec8ab63eb9c5f922920970249efee83f7e919",
-                "sha256:3f58aa995b905ab82fe228acd38538e7dc1509e01508dcf307dad5046399130f",
-                "sha256:48c996eb91bfbdab1e01e2c02e7ff678c51e2b28e3a04e26e41691991cc55795",
-                "sha256:48f218a5257b6bc16bcf26a91d97ecea0c7d29c811a90d965f3dd97c20f016d6",
-                "sha256:4a6551057a846bf72c7a04f73de3fcaca269c0bd85afe475ceb59d261c6a938c",
-                "sha256:51f90dabd9933b1621260b32c2f0d05d36923c7a5a909eb823e429dba0fd2f3e",
-                "sha256:577cc2c7b807b174814dac2d02e673728f2e46c7f90ceda3a70ea4bb6d90b769",
-                "sha256:5d79174d96446a02664e2bffc95e7b6fa93b9e6d8314536c5840dff130d0878b",
-                "sha256:5e3f81fbbc170418e22918a9585fd7281bbc11d027064d62aa4b507552c92671",
-                "sha256:5ecffdc748d3b40dd3618ede0170e4f5e1d3c9647cfb410d235d19e62cb54ee0",
-                "sha256:63fa57a0708573d3c059f7b5527617bd0c291e4559298473df238d502e4ab98c",
-                "sha256:67ca7032dfac8d001023fadafc812d9f48bf8a8c3bb15412d9cdcf92267593f4",
-                "sha256:688a1eb8c1a5f7e795c7cb67e0fe600194e6723ba35f138dfae0db20c0cb8f94",
-                "sha256:6a038cb1e6e55b26bb5520ccffab7f539b3786f5553af2ee47eb2ec5cbd7084e",
-                "sha256:6b79f6c31e68b6dafc0317ec453c83c86dd8db1f8f0c6f28e97186563fca87a0",
-                "sha256:6d3e027fe291b77f6be9630114a0200b2c52004ef20b94dc50ca59849cd623b3",
-                "sha256:6f1d39a744101bf4043fa0926b3ead616607578192d0a169974fb5265ab1e9d2",
-                "sha256:707adc30ea6918fba725c3cb3fe782d271ba352b22d7ae54a7f9f2e8a8488c41",
-                "sha256:730b7c2b7382194d9985ffdc32ab317e893bca21e0665cb1186bdfbb4089d990",
-                "sha256:764c7c6aa1f78bd77bd9674fc07d1ec44654da1818d0eef9fb48aa8371a3c847",
-                "sha256:78d51e35ed163783d721b6f2ce8ce3f82fccfe471e8e50a10fba13a766d31f5a",
-                "sha256:7a315ceb813208ef32bdd6ec3a85cbe3cb3be9bbda5fd030c234592fa9116993",
-                "sha256:7ba09bb3dcb0b7ec936a485db2b64be44fe14cdce0a5eac56f50e55da3627385",
-                "sha256:7d76e8a83396e06abe3df569b25bd3fc88bf78b7baa2c8e4cf4aaf5983af66a3",
-                "sha256:84fe1732648c1bc303a70faa67cbc2f7f2e810c8a5bca94f6db7818e722e4c0a",
-                "sha256:871d4fdc56288caa58b1094c20f2364215f7400411f76783ea19ad13be7c8e19",
-                "sha256:88d4917c30fcd7f6404fb1dc713fa21de59d3063dcc048f4a8a1a90e6bbbd739",
-                "sha256:8a50150419b741ee048b53146c39c47053f060cb9d98e78be08fdbe942eaa3c4",
-                "sha256:90a97c2ed2830e7974cbe45f0838de0aefc1c123313f7c402e21c29ec063fbb4",
-                "sha256:949a605ef3907254b122f845baa0920407080cdb1f73aa64f8d47df4a7f4c4f9",
-                "sha256:9689af0f0a89e5032426c143fa3683b0451f06c83bf3b1e27902bd33acfae769",
-                "sha256:98b1ea2763b33559dd9ec621d67fc17b583484cb90735bfb0ec3614c17b210e4",
-                "sha256:9951c2696c4357703001e1fe6edc6ae8e97553ac630492ea1bf64b429cb712a3",
-                "sha256:9a52b141ff3b923a9166595de6e3768a027546e75052ffba267d95b54267f4ab",
-                "sha256:9e8723c3256641e141cd18f6ce478d54a004138b9f1a36e41083b36d9ecc5fc5",
-                "sha256:a2fee4d656a7cc9ab47771b2a9e8fad8a9a33331c1b59c3057ecf0ac858f5bfe",
-                "sha256:a4759e85a191de58e0ea468ab6fd9c03941986eee436e0518d7a9291fab122c8",
-                "sha256:a5399a44a529083951b55521cf4ecbf6ad79fd54b9df57dbf01699ffa0549fc9",
-                "sha256:a6074a3b2fa2d0c9bf0963f8dfc85e1e54a26114cc8594126bc52d3fa061c40e",
-                "sha256:a84c335337b676d832c1e2bc47c3a97531b46b82de9f959dafb315cbcbe0dfcd",
-                "sha256:adf0cb251b1b842c9dee5cfcdf880ba0aae32e841b8d0e6b6feeaef002a267c5",
-                "sha256:b76669b7c058b8020b11008283c3b8e9c61bfd978807c45862956119b77ece45",
-                "sha256:bda75d73e7400e81077b0910c9a60bf9771f715420d7e35fa7739ae95555f195",
-                "sha256:be03a7483ad9ea60388f930160bb3728467dd0af538aa5edc60962ee700a0bdc",
-                "sha256:c62d4791a8212c885b97a63ef5f3974b2cd41930f0cd224ada9c6ee6654f8150",
-                "sha256:cb751ef712570d3bda9a73fd765ff3e1aba943ec5d52a54a0c2e89c7eef9da1e",
-                "sha256:d3b19d8d183bcfd68b25beebab8dc3308282fe2ca3d6ea3cb4cd101b3c279f8d",
-                "sha256:d3f90ee275b1d7c942e65b5c44c8fb52d55502a0b9a679837d71be2bd8927661",
-                "sha256:d5f8c04574efa814a24510122810e3a3c77c0552f9f6ff65c9862f1f046be2c3",
-                "sha256:d6a1a66bb8bac9bc2892c2674ea363486bfb748b86504966a390345a11b1680e",
-                "sha256:d7715daf84f10bcebc083ad137e3eced3e1c8e7fa1f096ade9a8d02b08f0d91c",
-                "sha256:dafc01a32b4a1d7d3ef8bfd3699406bb44f7b2e0d3eb8906d574846e1019b12f",
-                "sha256:dcc4d5dd5fba3affaf4fd08f00ef156407573de8c63338787614ccc64f96b321",
-                "sha256:de42f513ed7a997bc821bddab356b72e55e8396b1b7ba1bf39926d538a76a90f",
-                "sha256:e27cde1e8d17b09730801ce97b6e0c444ba2a1f06348b169fd931b51d3402f0d",
-                "sha256:ecb314e59bedb77188017f26e6b684b1f6d0465e724c3122a726359fa62ca1ba",
-                "sha256:f348ebd20554e8bc26e8ef3ed8a134110c0f4bf015b3b4da6a4ddf34e0515b19",
-                "sha256:fa818609357dde5c4a94a64c097c6404ad996b1d38ca977a72834b682830a722",
-                "sha256:fe4a327da0c6b6e59f2e474ae79d6ee7745ac3279fd15f200044602fa31e3d79"
-            ],
-            "index": "pypi",
-            "version": "==3.8.0"
-        },
-        "aiosignal": {
-            "hashes": [
-                "sha256:26e62109036cd181df6e6ad646f91f0dcfd05fe16d0cb924138ff2ab75d64e3a",
-                "sha256:78ed67db6c7b7ced4f98e495e572106d5c432a93e1ddd1bf475e1dc05f5b7df2"
-            ],
-            "markers": "python_version >= '3.6'",
-            "version": "==1.2.0"
-        },
-        "alabaster": {
-            "hashes": [
-                "sha256:446438bdcca0e05bd45ea2de1668c1d9b032e1a9154c2c259092d77031ddd359",
-                "sha256:a661d72d58e6ea8a57f7a86e37d86716863ee5e92788398526d58b26a4e4dc02"
-            ],
-            "version": "==0.7.12"
-        },
-        "appnope": {
-            "hashes": [
-                "sha256:93aa393e9d6c54c5cd570ccadd8edad61ea0c4b9ea7a01409020c9aa019eb442",
-                "sha256:dd83cd4b5b460958838f6eb3000c660b1f9caf2a5b1de4264e941512f603258a"
-            ],
-            "markers": "sys_platform == 'darwin'",
-            "version": "==0.1.2"
-        },
-        "async-timeout": {
-            "hashes": [
-                "sha256:a22c0b311af23337eb05fcf05a8b51c3ea53729d46fb5460af62bee033cec690",
-                "sha256:b930cb161a39042f9222f6efb7301399c87eeab394727ec5437924a36d6eef51"
-            ],
-            "markers": "python_version >= '3.6'",
-            "version": "==4.0.1"
-        },
-        "asynctest": {
-            "hashes": [
-                "sha256:5da6118a7e6d6b54d83a8f7197769d046922a44d2a99c21382f0a6e4fadae676",
-                "sha256:c27862842d15d83e6a34eb0b2866c323880eb3a75e4485b079ea11748fd77fac"
-            ],
-            "markers": "python_version < '3.8'",
-            "version": "==0.13.0"
-        },
-        "attrs": {
-            "hashes": [
-                "sha256:149e90d6d8ac20db7a955ad60cf0e6881a3f20d37096140088356da6c716b0b1",
-                "sha256:ef6aaac3ca6cd92904cdd0d83f629a15f18053ec84e6432106f7a4d04ae4f5fb"
-            ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
-            "version": "==21.2.0"
-        },
-        "babel": {
-            "hashes": [
-                "sha256:ab49e12b91d937cd11f0b67cb259a57ab4ad2b59ac7a3b41d6c06c0ac5b0def9",
-                "sha256:bc0c176f9f6a994582230df350aa6e05ba2ebe4b3ac317eab29d9be5d2768da0"
-            ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==2.9.1"
-        },
-        "backcall": {
-            "hashes": [
-                "sha256:5cbdbf27be5e7cfadb448baf0aa95508f91f2bbc6c6437cd9cd06e2a4c215e1e",
-                "sha256:fbbce6a29f263178a1f7915c1940bde0ec2b2a967566fe1c65c1dfb7422bd255"
-            ],
-            "version": "==0.2.0"
-        },
-        "backports.entry-points-selectable": {
-            "hashes": [
-                "sha256:7fceed9532a7aa2bd888654a7314f864a3c16a4e710b34a58cfc0f08114c663b",
-                "sha256:914b21a479fde881635f7af5adc7f6e38d6b274be32269070c53b698c60d5386"
-            ],
-            "markers": "python_version >= '2.7'",
-            "version": "==1.1.1"
-        },
-        "black": {
-            "editable": true,
-            "extras": [
-                "d"
-            ],
-            "path": "."
-        },
-        "bleach": {
-            "hashes": [
-                "sha256:0900d8b37eba61a802ee40ac0061f8c2b5dee29c1927dd1d233e075ebf5a71da",
-                "sha256:4d2651ab93271d1129ac9cbc679f524565cc8a1b791909c4a51eac4446a15994"
-            ],
-            "markers": "python_version >= '3.6'",
-            "version": "==4.1.0"
-        },
-        "certifi": {
-            "hashes": [
-                "sha256:78884e7c1d4b00ce3cea67b44566851c4343c120abd683433ce934a68ea58872",
-                "sha256:d62a0163eb4c2344ac042ab2bdf75399a71a2d8c7d47eac2e2ee91b9d6339569"
-            ],
-            "version": "==2021.10.8"
-        },
-        "cffi": {
-            "hashes": [
-                "sha256:00c878c90cb53ccfaae6b8bc18ad05d2036553e6d9d1d9dbcf323bbe83854ca3",
-                "sha256:0104fb5ae2391d46a4cb082abdd5c69ea4eab79d8d44eaaf79f1b1fd806ee4c2",
-                "sha256:06c48159c1abed75c2e721b1715c379fa3200c7784271b3c46df01383b593636",
-                "sha256:0808014eb713677ec1292301ea4c81ad277b6cdf2fdd90fd540af98c0b101d20",
-                "sha256:10dffb601ccfb65262a27233ac273d552ddc4d8ae1bf93b21c94b8511bffe728",
-                "sha256:14cd121ea63ecdae71efa69c15c5543a4b5fbcd0bbe2aad864baca0063cecf27",
-                "sha256:17771976e82e9f94976180f76468546834d22a7cc404b17c22df2a2c81db0c66",
-                "sha256:181dee03b1170ff1969489acf1c26533710231c58f95534e3edac87fff06c443",
-                "sha256:23cfe892bd5dd8941608f93348c0737e369e51c100d03718f108bf1add7bd6d0",
-                "sha256:263cc3d821c4ab2213cbe8cd8b355a7f72a8324577dc865ef98487c1aeee2bc7",
-                "sha256:2756c88cbb94231c7a147402476be2c4df2f6078099a6f4a480d239a8817ae39",
-                "sha256:27c219baf94952ae9d50ec19651a687b826792055353d07648a5695413e0c605",
-                "sha256:2a23af14f408d53d5e6cd4e3d9a24ff9e05906ad574822a10563efcef137979a",
-                "sha256:31fb708d9d7c3f49a60f04cf5b119aeefe5644daba1cd2a0fe389b674fd1de37",
-                "sha256:3415c89f9204ee60cd09b235810be700e993e343a408693e80ce7f6a40108029",
-                "sha256:3773c4d81e6e818df2efbc7dd77325ca0dcb688116050fb2b3011218eda36139",
-                "sha256:3b96a311ac60a3f6be21d2572e46ce67f09abcf4d09344c49274eb9e0bf345fc",
-                "sha256:3f7d084648d77af029acb79a0ff49a0ad7e9d09057a9bf46596dac9514dc07df",
-                "sha256:41d45de54cd277a7878919867c0f08b0cf817605e4eb94093e7516505d3c8d14",
-                "sha256:4238e6dab5d6a8ba812de994bbb0a79bddbdf80994e4ce802b6f6f3142fcc880",
-                "sha256:45db3a33139e9c8f7c09234b5784a5e33d31fd6907800b316decad50af323ff2",
-                "sha256:45e8636704eacc432a206ac7345a5d3d2c62d95a507ec70d62f23cd91770482a",
-                "sha256:4958391dbd6249d7ad855b9ca88fae690783a6be9e86df65865058ed81fc860e",
-                "sha256:4a306fa632e8f0928956a41fa8e1d6243c71e7eb59ffbd165fc0b41e316b2474",
-                "sha256:57e9ac9ccc3101fac9d6014fba037473e4358ef4e89f8e181f8951a2c0162024",
-                "sha256:59888172256cac5629e60e72e86598027aca6bf01fa2465bdb676d37636573e8",
-                "sha256:5e069f72d497312b24fcc02073d70cb989045d1c91cbd53979366077959933e0",
-                "sha256:64d4ec9f448dfe041705426000cc13e34e6e5bb13736e9fd62e34a0b0c41566e",
-                "sha256:6dc2737a3674b3e344847c8686cf29e500584ccad76204efea14f451d4cc669a",
-                "sha256:74fdfdbfdc48d3f47148976f49fab3251e550a8720bebc99bf1483f5bfb5db3e",
-                "sha256:75e4024375654472cc27e91cbe9eaa08567f7fbdf822638be2814ce059f58032",
-                "sha256:786902fb9ba7433aae840e0ed609f45c7bcd4e225ebb9c753aa39725bb3e6ad6",
-                "sha256:8b6c2ea03845c9f501ed1313e78de148cd3f6cad741a75d43a29b43da27f2e1e",
-                "sha256:91d77d2a782be4274da750752bb1650a97bfd8f291022b379bb8e01c66b4e96b",
-                "sha256:91ec59c33514b7c7559a6acda53bbfe1b283949c34fe7440bcf917f96ac0723e",
-                "sha256:920f0d66a896c2d99f0adbb391f990a84091179542c205fa53ce5787aff87954",
-                "sha256:a5263e363c27b653a90078143adb3d076c1a748ec9ecc78ea2fb916f9b861962",
-                "sha256:abb9a20a72ac4e0fdb50dae135ba5e77880518e742077ced47eb1499e29a443c",
-                "sha256:c2051981a968d7de9dd2d7b87bcb9c939c74a34626a6e2f8181455dd49ed69e4",
-                "sha256:c21c9e3896c23007803a875460fb786118f0cdd4434359577ea25eb556e34c55",
-                "sha256:c2502a1a03b6312837279c8c1bd3ebedf6c12c4228ddbad40912d671ccc8a962",
-                "sha256:d4d692a89c5cf08a8557fdeb329b82e7bf609aadfaed6c0d79f5a449a3c7c023",
-                "sha256:da5db4e883f1ce37f55c667e5c0de439df76ac4cb55964655906306918e7363c",
-                "sha256:e7022a66d9b55e93e1a845d8c9eba2a1bebd4966cd8bfc25d9cd07d515b33fa6",
-                "sha256:ef1f279350da2c586a69d32fc8733092fd32cc8ac95139a00377841f59a3f8d8",
-                "sha256:f54a64f8b0c8ff0b64d18aa76675262e1700f3995182267998c31ae974fbc382",
-                "sha256:f5c7150ad32ba43a07c4479f40241756145a1f03b43480e058cfd862bf5041c7",
-                "sha256:f6f824dc3bce0edab5f427efcfb1d63ee75b6fcb7282900ccaf925be84efb0fc",
-                "sha256:fd8a250edc26254fe5b33be00402e6d287f562b6a5b2152dec302fa15bb3e997",
-                "sha256:ffaa5c925128e29efbde7301d8ecaf35c8c60ffbcd6a1ffd3a552177c8e5e796"
-            ],
-            "version": "==1.15.0"
-        },
-        "cfgv": {
-            "hashes": [
-                "sha256:c6a0883f3917a037485059700b9e75da2464e6c27051014ad85ba6aaa5884426",
-                "sha256:f5a830efb9ce7a445376bb66ec94c638a9787422f96264c98edc6bdeed8ab736"
-            ],
-            "markers": "python_full_version >= '3.6.1'",
-            "version": "==3.3.1"
-        },
-        "charset-normalizer": {
-            "hashes": [
-                "sha256:e019de665e2bcf9c2b64e2e5aa025fa991da8720daa3c1138cadd2fd1856aed0",
-                "sha256:f7af805c321bfa1ce6714c51f254e0d5bb5e5834039bc17db7ebe3a4cec9492b"
-            ],
-            "markers": "python_version >= '3.5'",
-            "version": "==2.0.7"
-        },
-        "click": {
-            "hashes": [
-                "sha256:353f466495adaeb40b6b5f592f9f91cb22372351c84caeb068132442a4518ef3",
-                "sha256:410e932b050f5eed773c4cda94de75971c89cdb3155a72a0831139a79e5ecb5b"
-            ],
-            "index": "pypi",
-            "version": "==8.0.3"
-        },
-        "colorama": {
-            "hashes": [
-                "sha256:5941b2b48a20143d2267e95b1c2a7603ce057ee39fd88e7329b0c292aa16869b",
-                "sha256:9f47eda37229f68eee03b24b9748937c7dc3868f906e8ba69fbcbdd3bc5dc3e2"
-            ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
-            "version": "==0.4.4"
-        },
-        "coverage": {
-            "hashes": [
-                "sha256:046647b96969fda1ae0605f61288635209dd69dcd27ba3ec0bf5148bc157f954",
-                "sha256:06d009e8a29483cbc0520665bc46035ffe9ae0e7484a49f9782c2a716e37d0a0",
-                "sha256:0cde7d9fe2fb55ff68ebe7fb319ef188e9b88e0a3d1c9c5db7dd829cd93d2193",
-                "sha256:1de9c6f5039ee2b1860b7bad2c7bc3651fbeb9368e4c4d93e98a76358cdcb052",
-                "sha256:24ed38ec86754c4d5a706fbd5b52b057c3df87901a8610d7e5642a08ec07087e",
-                "sha256:27a3df08a855522dfef8b8635f58bab81341b2fb5f447819bc252da3aa4cf44c",
-                "sha256:310c40bed6b626fd1f463e5a83dba19a61c4eb74e1ac0d07d454ebbdf9047e9d",
-                "sha256:3348865798c077c695cae00da0924136bb5cc501f236cfd6b6d9f7a3c94e0ec4",
-                "sha256:35b246ae3a2c042dc8f410c94bcb9754b18179cdb81ff9477a9089dbc9ecc186",
-                "sha256:3f546f48d5d80a90a266769aa613bc0719cb3e9c2ef3529d53f463996dd15a9d",
-                "sha256:586d38dfc7da4a87f5816b203ff06dd7c1bb5b16211ccaa0e9788a8da2b93696",
-                "sha256:5d3855d5d26292539861f5ced2ed042fc2aa33a12f80e487053aed3bcb6ced13",
-                "sha256:610c0ba11da8de3a753dc4b1f71894f9f9debfdde6559599f303286e70aeb0c2",
-                "sha256:62646d98cf0381ffda301a816d6ac6c35fc97aa81b09c4c52d66a15c4bef9d7c",
-                "sha256:66af99c7f7b64d050d37e795baadf515b4561124f25aae6e1baa482438ecc388",
-                "sha256:675adb3b3380967806b3cbb9c5b00ceb29b1c472692100a338730c1d3e59c8b9",
-                "sha256:6e5a8c947a2a89c56655ecbb789458a3a8e3b0cbf4c04250331df8f647b3de59",
-                "sha256:7a39590d1e6acf6a3c435c5d233f72f5d43b585f5be834cff1f21fec4afda225",
-                "sha256:80cb70264e9a1d04b519cdba3cd0dc42847bf8e982a4d55c769b9b0ee7cdce1e",
-                "sha256:82fdcb64bf08aa5db881db061d96db102c77397a570fbc112e21c48a4d9cb31b",
-                "sha256:8492d37acdc07a6eac6489f6c1954026f2260a85a4c2bb1e343fe3d35f5ee21a",
-                "sha256:94f558f8555e79c48c422045f252ef41eb43becdd945e9c775b45ebfc0cbd78f",
-                "sha256:958ac66272ff20e63d818627216e3d7412fdf68a2d25787b89a5c6f1eb7fdd93",
-                "sha256:95a58336aa111af54baa451c33266a8774780242cab3704b7698d5e514840758",
-                "sha256:96129e41405887a53a9cc564f960d7f853cc63d178f3a182fdd302e4cab2745b",
-                "sha256:97ef6e9119bd39d60ef7b9cd5deea2b34869c9f0b9777450a7e3759c1ab09b9b",
-                "sha256:98d44a8136eebbf544ad91fef5bd2b20ef0c9b459c65a833c923d9aa4546b204",
-                "sha256:9d2c2e3ce7b8cc932a2f918186964bd44de8c84e2f9ef72dc616f5bb8be22e71",
-                "sha256:a300b39c3d5905686c75a369d2a66e68fd01472ea42e16b38c948bd02b29e5bd",
-                "sha256:a34fccb45f7b2d890183a263578d60a392a1a218fdc12f5bce1477a6a68d4373",
-                "sha256:a4d48e42e17d3de212f9af44f81ab73b9378a4b2b8413fd708d0d9023f2bbde4",
-                "sha256:af45eea024c0e3a25462fade161afab4f0d9d9e0d5a5d53e86149f74f0a35ecc",
-                "sha256:ba6125d4e55c0b8e913dad27b22722eac7abdcb1f3eab1bd090eee9105660266",
-                "sha256:bc1ee1318f703bc6c971da700d74466e9b86e0c443eb85983fb2a1bd20447263",
-                "sha256:c18725f3cffe96732ef96f3de1939d81215fd6d7d64900dcc4acfe514ea4fcbf",
-                "sha256:c8e9c4bcaaaa932be581b3d8b88b677489975f845f7714efc8cce77568b6711c",
-                "sha256:cc799916b618ec9fd00135e576424165691fec4f70d7dc12cfaef09268a2478c",
-                "sha256:cd2d11a59afa5001ff28073ceca24ae4c506da4355aba30d1e7dd2bd0d2206dc",
-                "sha256:d0a595a781f8e186580ff8e3352dd4953b1944289bec7705377c80c7e36c4d6c",
-                "sha256:d3c5f49ce6af61154060640ad3b3281dbc46e2e0ef2fe78414d7f8a324f0b649",
-                "sha256:d9a635114b88c0ab462e0355472d00a180a5fbfd8511e7f18e4ac32652e7d972",
-                "sha256:e5432d9c329b11c27be45ee5f62cf20a33065d482c8dec1941d6670622a6fb8f",
-                "sha256:eab14fdd410500dae50fd14ccc332e65543e7b39f6fc076fe90603a0e5d2f929",
-                "sha256:ebcc03e1acef4ff44f37f3c61df478d6e469a573aa688e5a162f85d7e4c3860d",
-                "sha256:fae3fe111670e51f1ebbc475823899524e3459ea2db2cb88279bbfb2a0b8a3de",
-                "sha256:fd92ece726055e80d4e3f01fff3b91f54b18c9c357c48fcf6119e87e2461a091",
-                "sha256:ffa545230ca2ad921ad066bf8fd627e7be43716b6e0fcf8e32af1b8188ccb0ab"
-            ],
-            "index": "pypi",
-            "version": "==6.1.2"
-        },
-        "cryptography": {
-            "hashes": [
-                "sha256:07bb7fbfb5de0980590ddfc7f13081520def06dc9ed214000ad4372fb4e3c7f6",
-                "sha256:18d90f4711bf63e2fb21e8c8e51ed8189438e6b35a6d996201ebd98a26abbbe6",
-                "sha256:1ed82abf16df40a60942a8c211251ae72858b25b7421ce2497c2eb7a1cee817c",
-                "sha256:22a38e96118a4ce3b97509443feace1d1011d0571fae81fc3ad35f25ba3ea999",
-                "sha256:2d69645f535f4b2c722cfb07a8eab916265545b3475fdb34e0be2f4ee8b0b15e",
-                "sha256:4a2d0e0acc20ede0f06ef7aa58546eee96d2592c00f450c9acb89c5879b61992",
-                "sha256:54b2605e5475944e2213258e0ab8696f4f357a31371e538ef21e8d61c843c28d",
-                "sha256:7075b304cd567694dc692ffc9747f3e9cb393cc4aa4fb7b9f3abd6f5c4e43588",
-                "sha256:7b7ceeff114c31f285528ba8b390d3e9cfa2da17b56f11d366769a807f17cbaa",
-                "sha256:7eba2cebca600a7806b893cb1d541a6e910afa87e97acf2021a22b32da1df52d",
-                "sha256:928185a6d1ccdb816e883f56ebe92e975a262d31cc536429041921f8cb5a62fd",
-                "sha256:9933f28f70d0517686bd7de36166dda42094eac49415459d9bdf5e7df3e0086d",
-                "sha256:a688ebcd08250eab5bb5bca318cc05a8c66de5e4171a65ca51db6bd753ff8953",
-                "sha256:abb5a361d2585bb95012a19ed9b2c8f412c5d723a9836418fab7aaa0243e67d2",
-                "sha256:c10c797ac89c746e488d2ee92bd4abd593615694ee17b2500578b63cad6b93a8",
-                "sha256:ced40344e811d6abba00295ced98c01aecf0c2de39481792d87af4fa58b7b4d6",
-                "sha256:d57e0cdc1b44b6cdf8af1d01807db06886f10177469312fbde8f44ccbb284bc9",
-                "sha256:d99915d6ab265c22873f1b4d6ea5ef462ef797b4140be4c9d8b179915e0985c6",
-                "sha256:eb80e8a1f91e4b7ef8b33041591e6d89b2b8e122d787e87eeb2b08da71bb16ad",
-                "sha256:ebeddd119f526bcf323a89f853afb12e225902a24d29b55fe18dd6fcb2838a76"
-            ],
-            "markers": "python_version >= '3.6'",
-            "version": "==35.0.0"
-        },
-        "dataclasses": {
-            "hashes": [
-                "sha256:0201d89fa866f68c8ebd9d08ee6ff50c0b255f8ec63a71c16fda7af82bb887bf",
-                "sha256:8479067f342acf957dc82ec415d355ab5edb7e7646b90dc6e2fd1d96ad084c97"
-            ],
-            "index": "pypi",
-            "markers": "python_version < '3.7'",
-            "version": "==0.8"
-        },
-        "decorator": {
-            "hashes": [
-                "sha256:7b12e7c3c6ab203a29e157335e9122cb03de9ab7264b137594103fd4a683b374",
-                "sha256:e59913af105b9860aa2c8d3272d9de5a56a4e608db9a2f167a8480b323d529a7"
-            ],
-            "markers": "python_version >= '3.5'",
-            "version": "==5.1.0"
-        },
-        "distlib": {
-            "hashes": [
-                "sha256:c8b54e8454e5bf6237cc84c20e8264c3e991e824ef27e8f1e81049867d861e31",
-                "sha256:d982d0751ff6eaaab5e2ec8e691d949ee80eddf01a62eaa96ddb11531fe16b05"
-            ],
-            "version": "==0.3.3"
-        },
-        "docutils": {
-            "hashes": [
-                "sha256:686577d2e4c32380bb50cbb22f575ed742d58168cee37e99117a854bcd88f125",
-                "sha256:cf316c8370a737a022b72b56874f6602acf974a37a9fba42ec2876387549fc61"
-            ],
-            "index": "pypi",
-            "version": "==0.17.1"
-        },
-        "execnet": {
-            "hashes": [
-                "sha256:8f694f3ba9cc92cab508b152dcfe322153975c29bda272e2fd7f3f00f36e47c5",
-                "sha256:a295f7cc774947aac58dde7fdc85f4aa00c42adf5d8f5468fc630c1acf30a142"
-            ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
-            "version": "==1.9.0"
-        },
-        "filelock": {
-            "hashes": [
-                "sha256:7afc856f74fa7006a289fd10fa840e1eebd8bbff6bffb69c26c54a0512ea8cf8",
-                "sha256:bb2a1c717df74c48a2d00ed625e5a66f8572a3a30baacb7657add1d7bac4097b"
-            ],
-            "markers": "python_version >= '3.6'",
-            "version": "==3.3.2"
-        },
-        "flake8": {
-            "hashes": [
-                "sha256:479b1304f72536a55948cb40a32dce8bb0ffe3501e26eaf292c7e60eb5e0428d",
-                "sha256:806e034dda44114815e23c16ef92f95c91e4c71100ff52813adf7132a6ad870d"
-            ],
-            "index": "pypi",
-            "version": "==4.0.1"
-        },
-        "flake8-bugbear": {
-            "hashes": [
-                "sha256:4f7eaa6f05b7d7ea4cbbde93f7bcdc5438e79320fa1ec420d860c181af38b769",
-                "sha256:db9a09893a6c649a197f5350755100bb1dd84f110e60cf532fdfa07e41808ab2"
-            ],
-            "index": "pypi",
-            "version": "==21.9.2"
-        },
-        "frozenlist": {
-            "hashes": [
-                "sha256:01d79515ed5aa3d699b05f6bdcf1fe9087d61d6b53882aa599a10853f0479c6c",
-                "sha256:0a7c7cce70e41bc13d7d50f0e5dd175f14a4f1837a8549b0936ed0cbe6170bf9",
-                "sha256:11ff401951b5ac8c0701a804f503d72c048173208490c54ebb8d7bb7c07a6d00",
-                "sha256:14a5cef795ae3e28fb504b73e797c1800e9249f950e1c964bb6bdc8d77871161",
-                "sha256:16eef427c51cb1203a7c0ab59d1b8abccaba9a4f58c4bfca6ed278fc896dc193",
-                "sha256:16ef7dd5b7d17495404a2e7a49bac1bc13d6d20c16d11f4133c757dd94c4144c",
-                "sha256:181754275d5d32487431a0a29add4f897968b7157204bc1eaaf0a0ce80c5ba7d",
-                "sha256:1cf63243bc5f5c19762943b0aa9e0d3fb3723d0c514d820a18a9b9a5ef864315",
-                "sha256:1cfe6fef507f8bac40f009c85c7eddfed88c1c0d38c75e72fe10476cef94e10f",
-                "sha256:1fef737fd1388f9b93bba8808c5f63058113c10f4e3c0763ced68431773f72f9",
-                "sha256:25b358aaa7dba5891b05968dd539f5856d69f522b6de0bf34e61f133e077c1a4",
-                "sha256:26f602e380a5132880fa245c92030abb0fc6ff34e0c5500600366cedc6adb06a",
-                "sha256:28e164722ea0df0cf6d48c4d5bdf3d19e87aaa6dfb39b0ba91153f224b912020",
-                "sha256:2de5b931701257d50771a032bba4e448ff958076380b049fd36ed8738fdb375b",
-                "sha256:3457f8cf86deb6ce1ba67e120f1b0128fcba1332a180722756597253c465fc1d",
-                "sha256:351686ca020d1bcd238596b1fa5c8efcbc21bffda9d0efe237aaa60348421e2a",
-                "sha256:406aeb340613b4b559db78d86864485f68919b7141dec82aba24d1477fd2976f",
-                "sha256:41de4db9b9501679cf7cddc16d07ac0f10ef7eb58c525a1c8cbff43022bddca4",
-                "sha256:41f62468af1bd4e4b42b5508a3fe8cc46a693f0cdd0ca2f443f51f207893d837",
-                "sha256:4766632cd8a68e4f10f156a12c9acd7b1609941525569dd3636d859d79279ed3",
-                "sha256:47b2848e464883d0bbdcd9493c67443e5e695a84694efff0476f9059b4cb6257",
-                "sha256:4a495c3d513573b0b3f935bfa887a85d9ae09f0627cf47cad17d0cc9b9ba5c38",
-                "sha256:4ad065b2ebd09f32511ff2be35c5dfafee6192978b5a1e9d279a5c6e121e3b03",
-                "sha256:4c457220468d734e3077580a3642b7f682f5fd9507f17ddf1029452450912cdc",
-                "sha256:4f52d0732e56906f8ddea4bd856192984650282424049c956857fed43697ea43",
-                "sha256:54a1e09ab7a69f843cd28fefd2bcaf23edb9e3a8d7680032c8968b8ac934587d",
-                "sha256:5a72eecf37eface331636951249d878750db84034927c997d47f7f78a573b72b",
-                "sha256:5df31bb2b974f379d230a25943d9bf0d3bc666b4b0807394b131a28fca2b0e5f",
-                "sha256:66a518731a21a55b7d3e087b430f1956a36793acc15912e2878431c7aec54210",
-                "sha256:6790b8d96bbb74b7a6f4594b6f131bd23056c25f2aa5d816bd177d95245a30e3",
-                "sha256:68201be60ac56aff972dc18085800b6ee07973c49103a8aba669dee3d71079de",
-                "sha256:6e105013fa84623c057a4381dc8ea0361f4d682c11f3816cc80f49a1f3bc17c6",
-                "sha256:705c184b77565955a99dc360f359e8249580c6b7eaa4dc0227caa861ef46b27a",
-                "sha256:72cfbeab7a920ea9e74b19aa0afe3b4ad9c89471e3badc985d08756efa9b813b",
-                "sha256:735f386ec522e384f511614c01d2ef9cf799f051353876b4c6fb93ef67a6d1ee",
-                "sha256:82d22f6e6f2916e837c91c860140ef9947e31194c82aaeda843d6551cec92f19",
-                "sha256:83334e84a290a158c0c4cc4d22e8c7cfe0bba5b76d37f1c2509dabd22acafe15",
-                "sha256:84e97f59211b5b9083a2e7a45abf91cfb441369e8bb6d1f5287382c1c526def3",
-                "sha256:87521e32e18a2223311afc2492ef2d99946337da0779ddcda77b82ee7319df59",
-                "sha256:878ebe074839d649a1cdb03a61077d05760624f36d196884a5cafb12290e187b",
-                "sha256:89fdfc84c6bf0bff2ff3170bb34ecba8a6911b260d318d377171429c4be18c73",
-                "sha256:8b4c7665a17c3a5430edb663e4ad4e1ad457614d1b2f2b7f87052e2ef4fa45ca",
-                "sha256:8b54cdd2fda15467b9b0bfa78cee2ddf6dbb4585ef23a16e14926f4b076dfae4",
-                "sha256:94728f97ddf603d23c8c3dd5cae2644fa12d33116e69f49b1644a71bb77b89ae",
-                "sha256:954b154a4533ef28bd3e83ffdf4eadf39deeda9e38fb8feaf066d6069885e034",
-                "sha256:977a1438d0e0d96573fd679d291a1542097ea9f4918a8b6494b06610dfeefbf9",
-                "sha256:9ade70aea559ca98f4b1b1e5650c45678052e76a8ab2f76d90f2ac64180215a2",
-                "sha256:9b6e21e5770df2dea06cb7b6323fbc008b13c4a4e3b52cb54685276479ee7676",
-                "sha256:a0d3ffa8772464441b52489b985d46001e2853a3b082c655ec5fad9fb6a3d618",
-                "sha256:a37594ad6356e50073fe4f60aa4187b97d15329f2138124d252a5a19c8553ea4",
-                "sha256:a8d86547a5e98d9edd47c432f7a14b0c5592624b496ae9880fb6332f34af1edc",
-                "sha256:aa44c4740b4e23fcfa259e9dd52315d2b1770064cde9507457e4c4a65a04c397",
-                "sha256:acc4614e8d1feb9f46dd829a8e771b8f5c4b1051365d02efb27a3229048ade8a",
-                "sha256:af2a51c8a381d76eabb76f228f565ed4c3701441ecec101dd18be70ebd483cfd",
-                "sha256:b2ae2f5e9fa10805fb1c9adbfefaaecedd9e31849434be462c3960a0139ed729",
-                "sha256:b46f997d5ed6d222a863b02cdc9c299101ee27974d9bbb2fd1b3c8441311c408",
-                "sha256:bc93f5f62df3bdc1f677066327fc81f92b83644852a31c6aa9b32c2dde86ea7d",
-                "sha256:bfbaa08cf1452acad9cb1c1d7b89394a41e712f88df522cea1a0f296b57782a0",
-                "sha256:c1e8e9033d34c2c9e186e58279879d78c94dd365068a3607af33f2bc99357a53",
-                "sha256:c5328ed53fdb0a73c8a50105306a3bc013e5ca36cca714ec4f7bd31d38d8a97f",
-                "sha256:c6a9d84ee6427b65a81fc24e6ef589cb794009f5ca4150151251c062773e7ed2",
-                "sha256:c98d3c04701773ad60d9545cd96df94d955329efc7743fdb96422c4b669c633b",
-                "sha256:cb3957c39668d10e2b486acc85f94153520a23263b6401e8f59422ef65b9520d",
-                "sha256:e63ad0beef6ece06475d29f47d1f2f29727805376e09850ebf64f90777962792",
-                "sha256:e74f8b4d8677ebb4015ac01fcaf05f34e8a1f22775db1f304f497f2f88fdc697",
-                "sha256:e7d0dd3e727c70c2680f5f09a0775525229809f1a35d8552b92ff10b2b14f2c2",
-                "sha256:ec6cf345771cdb00791d271af9a0a6fbfc2b6dd44cb753f1eeaa256e21622adb",
-                "sha256:ed58803563a8c87cf4c0771366cf0ad1aa265b6b0ae54cbbb53013480c7ad74d",
-                "sha256:f0081a623c886197ff8de9e635528fd7e6a387dccef432149e25c13946cb0cd0",
-                "sha256:f025f1d6825725b09c0038775acab9ae94264453a696cc797ce20c0769a7b367",
-                "sha256:f5f3b2942c3b8b9bfe76b408bbaba3d3bb305ee3693e8b1d631fe0a0d4f93673",
-                "sha256:fbd4844ff111449f3bbe20ba24fbb906b5b1c2384d0f3287c9f7da2354ce6d23"
-            ],
-            "markers": "python_version >= '3.6'",
-            "version": "==1.2.0"
-        },
-        "identify": {
-            "hashes": [
-                "sha256:6f0368ba0f21c199645a331beb7425d5374376e71bc149e9cb55e45cb45f832d",
-                "sha256:ba945bddb4322394afcf3f703fa68eda08a6acc0f99d9573eb2be940aa7b9bba"
-            ],
-            "markers": "python_full_version >= '3.6.1'",
-            "version": "==2.3.5"
-        },
-        "idna": {
-            "hashes": [
-                "sha256:84d9dd047ffa80596e0f246e2eab0b391788b0503584e8945f2368256d2735ff",
-                "sha256:9d643ff0a55b762d5cdb124b8eaa99c66322e2157b69160bc32796e824360e6d"
-            ],
-            "markers": "python_version >= '3.5'",
-            "version": "==3.3"
-        },
-        "idna-ssl": {
-            "hashes": [
-                "sha256:a933e3bb13da54383f9e8f35dc4f9cb9eb9b3b78c6b36f311254d6d0d92c6c7c"
-            ],
-            "markers": "python_version < '3.7'",
-            "version": "==1.1.0"
-        },
-        "imagesize": {
-            "hashes": [
-                "sha256:1db2f82529e53c3e929e8926a1fa9235aa82d0bd0c580359c67ec31b2fddaa8c",
-                "sha256:cd1750d452385ca327479d45b64d9c7729ecf0b3969a58148298c77092261f9d"
-            ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==1.3.0"
-        },
-        "importlib-metadata": {
-            "hashes": [
-                "sha256:53ccfd5c134223e497627b9815d5030edf77d2ed573922f7a0b8f8bb81a1c100",
-                "sha256:75bdec14c397f528724c1bfd9709d660b33a4d2e77387a3358f20b848bb5e5fb"
-            ],
-            "markers": "python_version < '3.8'",
-            "version": "==4.8.2"
-        },
-        "importlib-resources": {
-            "hashes": [
-                "sha256:33a95faed5fc19b4bc16b29a6eeae248a3fe69dd55d4d229d2b480e23eeaad45",
-                "sha256:d756e2f85dd4de2ba89be0b21dba2a3bbec2e871a42a3a16719258a11f87506b"
-            ],
-            "markers": "python_version < '3.7'",
-            "version": "==5.4.0"
-        },
-        "iniconfig": {
-            "hashes": [
-                "sha256:011e24c64b7f47f6ebd835bb12a743f2fbe9a26d4cecaa7f53bc4f35ee9da8b3",
-                "sha256:bc3af051d7d14b2ee5ef9969666def0cd1a000e121eaea580d4a313df4b37f32"
-            ],
-            "version": "==1.1.1"
-        },
-        "ipython": {
-            "hashes": [
-                "sha256:2dbcc8c27ca7d3cfe4fcdff7f45b27f9a8d3edfa70ff8024a71c7a8eb5f09d64",
-                "sha256:9f4fcb31d3b2c533333893b9172264e4821c1ac91839500f31bd43f2c59b3ccf"
-            ],
-            "markers": "python_version >= '3.6'",
-            "version": "==7.16.1"
-        },
-        "ipython-genutils": {
-            "hashes": [
-                "sha256:72dd37233799e619666c9f639a9da83c34013a73e8bbc79a7a6348d93c61fab8",
-                "sha256:eb2e116e75ecef9d4d228fdc66af54269afa26ab4463042e33785b887c628ba8"
-            ],
-            "version": "==0.2.0"
-        },
-        "jedi": {
-            "hashes": [
-                "sha256:18456d83f65f400ab0c2d3319e48520420ef43b23a086fdc05dff34132f0fb93",
-                "sha256:92550a404bad8afed881a137ec9a461fed49eca661414be45059329614ed0707"
-            ],
-            "markers": "python_version >= '3.6'",
-            "version": "==0.18.0"
-        },
-        "jeepney": {
-            "hashes": [
-                "sha256:1b5a0ea5c0e7b166b2f5895b91a08c14de8915afda4407fb5022a195224958ac",
-                "sha256:fa9e232dfa0c498bd0b8a3a73b8d8a31978304dcef0515adc859d4e096f96f4f"
-            ],
-            "markers": "sys_platform == 'linux'",
-            "version": "==0.7.1"
-        },
-        "jinja2": {
-            "hashes": [
-                "sha256:077ce6014f7b40d03b47d1f1ca4b0fc8328a692bd284016f806ed0eaca390ad8",
-                "sha256:611bb273cd68f3b993fabdc4064fc858c5b47a973cb5aa7999ec1ba405c87cd7"
-            ],
-            "markers": "python_version >= '3.6'",
-            "version": "==3.0.3"
-        },
-        "keyring": {
-            "hashes": [
-                "sha256:6334aee6073db2fb1f30892697b1730105b5e9a77ce7e61fca6b435225493efe",
-                "sha256:bd2145a237ed70c8ce72978b497619ddfcae640b6dcf494402d5143e37755c6e"
-            ],
-            "markers": "python_version >= '3.6'",
-            "version": "==23.2.1"
-        },
-        "markdown-it-py": {
-            "hashes": [
-                "sha256:36be6bb3ad987bfdb839f5ba78ddf094552ca38ccbd784ae4f74a4e1419fc6e3",
-                "sha256:98080fc0bc34c4f2bcf0846a096a9429acbd9d5d8e67ed34026c03c61c464389"
-            ],
-            "markers": "python_version ~= '3.6'",
-            "version": "==1.1.0"
-        },
-        "markupsafe": {
-            "hashes": [
-                "sha256:01a9b8ea66f1658938f65b93a85ebe8bc016e6769611be228d797c9d998dd298",
-                "sha256:023cb26ec21ece8dc3907c0e8320058b2e0cb3c55cf9564da612bc325bed5e64",
-                "sha256:0446679737af14f45767963a1a9ef7620189912317d095f2d9ffa183a4d25d2b",
-                "sha256:04635854b943835a6ea959e948d19dcd311762c5c0c6e1f0e16ee57022669194",
-                "sha256:0717a7390a68be14b8c793ba258e075c6f4ca819f15edfc2a3a027c823718567",
-                "sha256:0955295dd5eec6cb6cc2fe1698f4c6d84af2e92de33fbcac4111913cd100a6ff",
-                "sha256:0d4b31cc67ab36e3392bbf3862cfbadac3db12bdd8b02a2731f509ed5b829724",
-                "sha256:10f82115e21dc0dfec9ab5c0223652f7197feb168c940f3ef61563fc2d6beb74",
-                "sha256:168cd0a3642de83558a5153c8bd34f175a9a6e7f6dc6384b9655d2697312a646",
-                "sha256:1d609f577dc6e1aa17d746f8bd3c31aa4d258f4070d61b2aa5c4166c1539de35",
-                "sha256:1f2ade76b9903f39aa442b4aadd2177decb66525062db244b35d71d0ee8599b6",
-                "sha256:20dca64a3ef2d6e4d5d615a3fd418ad3bde77a47ec8a23d984a12b5b4c74491a",
-                "sha256:2a7d351cbd8cfeb19ca00de495e224dea7e7d919659c2841bbb7f420ad03e2d6",
-                "sha256:2d7d807855b419fc2ed3e631034685db6079889a1f01d5d9dac950f764da3dad",
-                "sha256:2ef54abee730b502252bcdf31b10dacb0a416229b72c18b19e24a4509f273d26",
-                "sha256:36bc903cbb393720fad60fc28c10de6acf10dc6cc883f3e24ee4012371399a38",
-                "sha256:37205cac2a79194e3750b0af2a5720d95f786a55ce7df90c3af697bfa100eaac",
-                "sha256:3c112550557578c26af18a1ccc9e090bfe03832ae994343cfdacd287db6a6ae7",
-                "sha256:3dd007d54ee88b46be476e293f48c85048603f5f516008bee124ddd891398ed6",
-                "sha256:4296f2b1ce8c86a6aea78613c34bb1a672ea0e3de9c6ba08a960efe0b0a09047",
-                "sha256:47ab1e7b91c098ab893b828deafa1203de86d0bc6ab587b160f78fe6c4011f75",
-                "sha256:49e3ceeabbfb9d66c3aef5af3a60cc43b85c33df25ce03d0031a608b0a8b2e3f",
-                "sha256:4dc8f9fb58f7364b63fd9f85013b780ef83c11857ae79f2feda41e270468dd9b",
-                "sha256:4efca8f86c54b22348a5467704e3fec767b2db12fc39c6d963168ab1d3fc9135",
-                "sha256:53edb4da6925ad13c07b6d26c2a852bd81e364f95301c66e930ab2aef5b5ddd8",
-                "sha256:5855f8438a7d1d458206a2466bf82b0f104a3724bf96a1c781ab731e4201731a",
-                "sha256:594c67807fb16238b30c44bdf74f36c02cdf22d1c8cda91ef8a0ed8dabf5620a",
-                "sha256:5b6d930f030f8ed98e3e6c98ffa0652bdb82601e7a016ec2ab5d7ff23baa78d1",
-                "sha256:5bb28c636d87e840583ee3adeb78172efc47c8b26127267f54a9c0ec251d41a9",
-                "sha256:60bf42e36abfaf9aff1f50f52644b336d4f0a3fd6d8a60ca0d054ac9f713a864",
-                "sha256:611d1ad9a4288cf3e3c16014564df047fe08410e628f89805e475368bd304914",
-                "sha256:6300b8454aa6930a24b9618fbb54b5a68135092bc666f7b06901f897fa5c2fee",
-                "sha256:63f3268ba69ace99cab4e3e3b5840b03340efed0948ab8f78d2fd87ee5442a4f",
-                "sha256:6557b31b5e2c9ddf0de32a691f2312a32f77cd7681d8af66c2692efdbef84c18",
-                "sha256:693ce3f9e70a6cf7d2fb9e6c9d8b204b6b39897a2c4a1aa65728d5ac97dcc1d8",
-                "sha256:6a7fae0dd14cf60ad5ff42baa2e95727c3d81ded453457771d02b7d2b3f9c0c2",
-                "sha256:6c4ca60fa24e85fe25b912b01e62cb969d69a23a5d5867682dd3e80b5b02581d",
-                "sha256:6fcf051089389abe060c9cd7caa212c707e58153afa2c649f00346ce6d260f1b",
-                "sha256:7d91275b0245b1da4d4cfa07e0faedd5b0812efc15b702576d103293e252af1b",
-                "sha256:89c687013cb1cd489a0f0ac24febe8c7a666e6e221b783e53ac50ebf68e45d86",
-                "sha256:8d206346619592c6200148b01a2142798c989edcb9c896f9ac9722a99d4e77e6",
-                "sha256:905fec760bd2fa1388bb5b489ee8ee5f7291d692638ea5f67982d968366bef9f",
-                "sha256:97383d78eb34da7e1fa37dd273c20ad4320929af65d156e35a5e2d89566d9dfb",
-                "sha256:984d76483eb32f1bcb536dc27e4ad56bba4baa70be32fa87152832cdd9db0833",
-                "sha256:99df47edb6bda1249d3e80fdabb1dab8c08ef3975f69aed437cb69d0a5de1e28",
-                "sha256:9f02365d4e99430a12647f09b6cc8bab61a6564363f313126f775eb4f6ef798e",
-                "sha256:a30e67a65b53ea0a5e62fe23682cfe22712e01f453b95233b25502f7c61cb415",
-                "sha256:ab3ef638ace319fa26553db0624c4699e31a28bb2a835c5faca8f8acf6a5a902",
-                "sha256:aca6377c0cb8a8253e493c6b451565ac77e98c2951c45f913e0b52facdcff83f",
-                "sha256:add36cb2dbb8b736611303cd3bfcee00afd96471b09cda130da3581cbdc56a6d",
-                "sha256:b2f4bf27480f5e5e8ce285a8c8fd176c0b03e93dcc6646477d4630e83440c6a9",
-                "sha256:b7f2d075102dc8c794cbde1947378051c4e5180d52d276987b8d28a3bd58c17d",
-                "sha256:baa1a4e8f868845af802979fcdbf0bb11f94f1cb7ced4c4b8a351bb60d108145",
-                "sha256:be98f628055368795d818ebf93da628541e10b75b41c559fdf36d104c5787066",
-                "sha256:bf5d821ffabf0ef3533c39c518f3357b171a1651c1ff6827325e4489b0e46c3c",
-                "sha256:c47adbc92fc1bb2b3274c4b3a43ae0e4573d9fbff4f54cd484555edbf030baf1",
-                "sha256:cdfba22ea2f0029c9261a4bd07e830a8da012291fbe44dc794e488b6c9bb353a",
-                "sha256:d6c7ebd4e944c85e2c3421e612a7057a2f48d478d79e61800d81468a8d842207",
-                "sha256:d7f9850398e85aba693bb640262d3611788b1f29a79f0c93c565694658f4071f",
-                "sha256:d8446c54dc28c01e5a2dbac5a25f071f6653e6e40f3a8818e8b45d790fe6ef53",
-                "sha256:deb993cacb280823246a026e3b2d81c493c53de6acfd5e6bfe31ab3402bb37dd",
-                "sha256:e0f138900af21926a02425cf736db95be9f4af72ba1bb21453432a07f6082134",
-                "sha256:e9936f0b261d4df76ad22f8fee3ae83b60d7c3e871292cd42f40b81b70afae85",
-                "sha256:f0567c4dc99f264f49fe27da5f735f414c4e7e7dd850cfd8e69f0862d7c74ea9",
-                "sha256:f5653a225f31e113b152e56f154ccbe59eeb1c7487b39b9d9f9cdb58e6c79dc5",
-                "sha256:f826e31d18b516f653fe296d967d700fddad5901ae07c622bb3705955e1faa94",
-                "sha256:f8ba0e8349a38d3001fae7eadded3f6606f0da5d748ee53cc1dab1d6527b9509",
-                "sha256:f9081981fe268bd86831e5c75f7de206ef275defcb82bc70740ae6dc507aee51",
-                "sha256:fa130dd50c57d53368c9d59395cb5526eda596d3ffe36666cd81a44d56e48872"
-            ],
-            "markers": "python_version >= '3.6'",
-            "version": "==2.0.1"
-        },
-        "matplotlib-inline": {
-            "hashes": [
-                "sha256:a04bfba22e0d1395479f866853ec1ee28eea1485c1d69a6faf00dc3e24ff34ee",
-                "sha256:aed605ba3b72462d64d475a21a9296f400a19c4f74a31b59103d2a99ffd5aa5c"
-            ],
-            "markers": "python_version >= '3.5'",
-            "version": "==0.1.3"
-        },
-        "mccabe": {
-            "hashes": [
-                "sha256:ab8a6258860da4b6677da4bd2fe5dc2c659cff31b3ee4f7f5d64e79735b80d42",
-                "sha256:dd8d182285a0fe56bace7f45b5e7d1a6ebcbf524e8f3bd87eb0f125271b8831f"
-            ],
-            "version": "==0.6.1"
-        },
-        "mdit-py-plugins": {
-            "hashes": [
-                "sha256:1833bf738e038e35d89cb3a07eb0d227ed647ce7dd357579b65343740c6d249c",
-                "sha256:5991cef645502e80a5388ec4fc20885d2313d4871e8b8e320ca2de14ac0c015f"
-            ],
-            "markers": "python_version ~= '3.6'",
-            "version": "==0.2.8"
-        },
-        "multidict": {
-            "hashes": [
-                "sha256:06560fbdcf22c9387100979e65b26fba0816c162b888cb65b845d3def7a54c9b",
-                "sha256:067150fad08e6f2dd91a650c7a49ba65085303fcc3decbd64a57dc13a2733031",
-                "sha256:0a2cbcfbea6dc776782a444db819c8b78afe4db597211298dd8b2222f73e9cd0",
-                "sha256:0dd1c93edb444b33ba2274b66f63def8a327d607c6c790772f448a53b6ea59ce",
-                "sha256:0fed465af2e0eb6357ba95795d003ac0bdb546305cc2366b1fc8f0ad67cc3fda",
-                "sha256:116347c63ba049c1ea56e157fa8aa6edaf5e92925c9b64f3da7769bdfa012858",
-                "sha256:1b4ac3ba7a97b35a5ccf34f41b5a8642a01d1e55454b699e5e8e7a99b5a3acf5",
-                "sha256:1c7976cd1c157fa7ba5456ae5d31ccdf1479680dc9b8d8aa28afabc370df42b8",
-                "sha256:246145bff76cc4b19310f0ad28bd0769b940c2a49fc601b86bfd150cbd72bb22",
-                "sha256:25cbd39a9029b409167aa0a20d8a17f502d43f2efebfe9e3ac019fe6796c59ac",
-                "sha256:28e6d883acd8674887d7edc896b91751dc2d8e87fbdca8359591a13872799e4e",
-                "sha256:2d1d55cdf706ddc62822d394d1df53573d32a7a07d4f099470d3cb9323b721b6",
-                "sha256:2e77282fd1d677c313ffcaddfec236bf23f273c4fba7cdf198108f5940ae10f5",
-                "sha256:32fdba7333eb2351fee2596b756d730d62b5827d5e1ab2f84e6cbb287cc67fe0",
-                "sha256:35591729668a303a02b06e8dba0eb8140c4a1bfd4c4b3209a436a02a5ac1de11",
-                "sha256:380b868f55f63d048a25931a1632818f90e4be71d2081c2338fcf656d299949a",
-                "sha256:3822c5894c72e3b35aae9909bef66ec83e44522faf767c0ad39e0e2de11d3b55",
-                "sha256:38ba256ee9b310da6a1a0f013ef4e422fca30a685bcbec86a969bd520504e341",
-                "sha256:3bc3b1621b979621cee9f7b09f024ec76ec03cc365e638126a056317470bde1b",
-                "sha256:3d2d7d1fff8e09d99354c04c3fd5b560fb04639fd45926b34e27cfdec678a704",
-                "sha256:517d75522b7b18a3385726b54a081afd425d4f41144a5399e5abd97ccafdf36b",
-                "sha256:5f79c19c6420962eb17c7e48878a03053b7ccd7b69f389d5831c0a4a7f1ac0a1",
-                "sha256:5f841c4f14331fd1e36cbf3336ed7be2cb2a8f110ce40ea253e5573387db7621",
-                "sha256:637c1896497ff19e1ee27c1c2c2ddaa9f2d134bbb5e0c52254361ea20486418d",
-                "sha256:6ee908c070020d682e9b42c8f621e8bb10c767d04416e2ebe44e37d0f44d9ad5",
-                "sha256:77f0fb7200cc7dedda7a60912f2059086e29ff67cefbc58d2506638c1a9132d7",
-                "sha256:7878b61c867fb2df7a95e44b316f88d5a3742390c99dfba6c557a21b30180cac",
-                "sha256:78c106b2b506b4d895ddc801ff509f941119394b89c9115580014127414e6c2d",
-                "sha256:8b911d74acdc1fe2941e59b4f1a278a330e9c34c6c8ca1ee21264c51ec9b67ef",
-                "sha256:93de39267c4c676c9ebb2057e98a8138bade0d806aad4d864322eee0803140a0",
-                "sha256:9416cf11bcd73c861267e88aea71e9fcc35302b3943e45e1dbb4317f91a4b34f",
-                "sha256:94b117e27efd8e08b4046c57461d5a114d26b40824995a2eb58372b94f9fca02",
-                "sha256:9815765f9dcda04921ba467957be543423e5ec6a1136135d84f2ae092c50d87b",
-                "sha256:98ec9aea6223adf46999f22e2c0ab6cf33f5914be604a404f658386a8f1fba37",
-                "sha256:a37e9a68349f6abe24130846e2f1d2e38f7ddab30b81b754e5a1fde32f782b23",
-                "sha256:a43616aec0f0d53c411582c451f5d3e1123a68cc7b3475d6f7d97a626f8ff90d",
-                "sha256:a4771d0d0ac9d9fe9e24e33bed482a13dfc1256d008d101485fe460359476065",
-                "sha256:a5635bcf1b75f0f6ef3c8a1ad07b500104a971e38d3683167b9454cb6465ac86",
-                "sha256:a9acb76d5f3dd9421874923da2ed1e76041cb51b9337fd7f507edde1d86535d6",
-                "sha256:ac42181292099d91217a82e3fa3ce0e0ddf3a74fd891b7c2b347a7f5aa0edded",
-                "sha256:b227345e4186809d31f22087d0265655114af7cda442ecaf72246275865bebe4",
-                "sha256:b61f85101ef08cbbc37846ac0e43f027f7844f3fade9b7f6dd087178caedeee7",
-                "sha256:b70913cbf2e14275013be98a06ef4b412329fe7b4f83d64eb70dce8269ed1e1a",
-                "sha256:b9aad49466b8d828b96b9e3630006234879c8d3e2b0a9d99219b3121bc5cdb17",
-                "sha256:baf1856fab8212bf35230c019cde7c641887e3fc08cadd39d32a421a30151ea3",
-                "sha256:bd6c9c50bf2ad3f0448edaa1a3b55b2e6866ef8feca5d8dbec10ec7c94371d21",
-                "sha256:c1ff762e2ee126e6f1258650ac641e2b8e1f3d927a925aafcfde943b77a36d24",
-                "sha256:c30ac9f562106cd9e8071c23949a067b10211917fdcb75b4718cf5775356a940",
-                "sha256:c9631c642e08b9fff1c6255487e62971d8b8e821808ddd013d8ac058087591ac",
-                "sha256:cdd68778f96216596218b4e8882944d24a634d984ee1a5a049b300377878fa7c",
-                "sha256:ce8cacda0b679ebc25624d5de66c705bc53dcc7c6f02a7fb0f3ca5e227d80422",
-                "sha256:cfde464ca4af42a629648c0b0d79b8f295cf5b695412451716531d6916461628",
-                "sha256:d3def943bfd5f1c47d51fd324df1e806d8da1f8e105cc7f1c76a1daf0f7e17b0",
-                "sha256:d9b668c065968c5979fe6b6fa6760bb6ab9aeb94b75b73c0a9c1acf6393ac3bf",
-                "sha256:da7d57ea65744d249427793c042094c4016789eb2562576fb831870f9c878d9e",
-                "sha256:dc3a866cf6c13d59a01878cd806f219340f3e82eed514485e094321f24900677",
-                "sha256:df23c83398715b26ab09574217ca21e14694917a0c857e356fd39e1c64f8283f",
-                "sha256:dfc924a7e946dd3c6360e50e8f750d51e3ef5395c95dc054bc9eab0f70df4f9c",
-                "sha256:e4a67f1080123de76e4e97a18d10350df6a7182e243312426d508712e99988d4",
-                "sha256:e5283c0a00f48e8cafcecadebfa0ed1dac8b39e295c7248c44c665c16dc1138b",
-                "sha256:e58a9b5cc96e014ddf93c2227cbdeca94b56a7eb77300205d6e4001805391747",
-                "sha256:e6453f3cbeb78440747096f239d282cc57a2997a16b5197c9bc839099e1633d0",
-                "sha256:e6c4fa1ec16e01e292315ba76eb1d012c025b99d22896bd14a66628b245e3e01",
-                "sha256:e7d81ce5744757d2f05fc41896e3b2ae0458464b14b5a2c1e87a6a9d69aefaa8",
-                "sha256:ea21d4d5104b4f840b91d9dc8cbc832aba9612121eaba503e54eaab1ad140eb9",
-                "sha256:ecc99bce8ee42dcad15848c7885197d26841cb24fa2ee6e89d23b8993c871c64",
-                "sha256:f0bb0973f42ffcb5e3537548e0767079420aefd94ba990b61cf7bb8d47f4916d",
-                "sha256:f19001e790013ed580abfde2a4465388950728861b52f0da73e8e8a9418533c0",
-                "sha256:f76440e480c3b2ca7f843ff8a48dc82446b86ed4930552d736c0bac507498a52",
-                "sha256:f9bef5cff994ca3026fcc90680e326d1a19df9841c5e3d224076407cc21471a1",
-                "sha256:fc66d4016f6e50ed36fb39cd287a3878ffcebfa90008535c62e0e90a7ab713ae",
-                "sha256:fd77c8f3cba815aa69cb97ee2b2ef385c7c12ada9c734b0f3b32e26bb88bbf1d"
-            ],
-            "markers": "python_version >= '3.6'",
-            "version": "==5.2.0"
-        },
-        "mypy": {
-            "hashes": [
-                "sha256:088cd9c7904b4ad80bec811053272986611b84221835e079be5bcad029e79dd9",
-                "sha256:0aadfb2d3935988ec3815952e44058a3100499f5be5b28c34ac9d79f002a4a9a",
-                "sha256:119bed3832d961f3a880787bf621634ba042cb8dc850a7429f643508eeac97b9",
-                "sha256:1a85e280d4d217150ce8cb1a6dddffd14e753a4e0c3cf90baabb32cefa41b59e",
-                "sha256:3c4b8ca36877fc75339253721f69603a9c7fdb5d4d5a95a1a1b899d8b86a4de2",
-                "sha256:3e382b29f8e0ccf19a2df2b29a167591245df90c0b5a2542249873b5c1d78212",
-                "sha256:42c266ced41b65ed40a282c575705325fa7991af370036d3f134518336636f5b",
-                "sha256:53fd2eb27a8ee2892614370896956af2ff61254c275aaee4c230ae771cadd885",
-                "sha256:704098302473cb31a218f1775a873b376b30b4c18229421e9e9dc8916fd16150",
-                "sha256:7df1ead20c81371ccd6091fa3e2878559b5c4d4caadaf1a484cf88d93ca06703",
-                "sha256:866c41f28cee548475f146aa4d39a51cf3b6a84246969f3759cb3e9c742fc072",
-                "sha256:a155d80ea6cee511a3694b108c4494a39f42de11ee4e61e72bc424c490e46457",
-                "sha256:adaeee09bfde366d2c13fe6093a7df5df83c9a2ba98638c7d76b010694db760e",
-                "sha256:b6fb13123aeef4a3abbcfd7e71773ff3ff1526a7d3dc538f3929a49b42be03f0",
-                "sha256:b94e4b785e304a04ea0828759172a15add27088520dc7e49ceade7834275bedb",
-                "sha256:c0df2d30ed496a08de5daed2a9ea807d07c21ae0ab23acf541ab88c24b26ab97",
-                "sha256:c6c2602dffb74867498f86e6129fd52a2770c48b7cd3ece77ada4fa38f94eba8",
-                "sha256:ceb6e0a6e27fb364fb3853389607cf7eb3a126ad335790fa1e14ed02fba50811",
-                "sha256:d9dd839eb0dc1bbe866a288ba3c1afc33a202015d2ad83b31e875b5905a079b6",
-                "sha256:e4dab234478e3bd3ce83bac4193b2ecd9cf94e720ddd95ce69840273bf44f6de",
-                "sha256:ec4e0cd079db280b6bdabdc807047ff3e199f334050db5cbb91ba3e959a67504",
-                "sha256:ecd2c3fe726758037234c93df7e98deb257fd15c24c9180dacf1ef829da5f921",
-                "sha256:ef565033fa5a958e62796867b1df10c40263ea9ded87164d67572834e57a174d"
-            ],
-            "index": "pypi",
-            "version": "==0.910"
-        },
-        "mypy-extensions": {
-            "hashes": [
-                "sha256:090fedd75945a69ae91ce1303b5824f428daf5a028d2f6ab8a299250a846f15d",
-                "sha256:2d82818f5bb3e369420cb3c4060a7970edba416647068eb4c5343488a6c604a8"
-            ],
-            "index": "pypi",
-            "version": "==0.4.3"
-        },
-        "myst-parser": {
-            "hashes": [
-                "sha256:40124b6f27a4c42ac7f06b385e23a9dcd03d84801e9c7130b59b3729a554b1f9",
-                "sha256:f7f3b2d62db7655cde658eb5d62b2ec2a4631308137bd8d10f296a40d57bbbeb"
-            ],
-            "index": "pypi",
-            "version": "==0.15.2"
-        },
-        "nodeenv": {
-            "hashes": [
-                "sha256:3ef13ff90291ba2a4a7a4ff9a979b63ffdd00a464dbe04acf0ea6471517a4c2b",
-                "sha256:621e6b7076565ddcacd2db0294c0381e01fd28945ab36bcf00f41c5daf63bef7"
-            ],
-            "version": "==1.6.0"
-        },
-        "packaging": {
-            "hashes": [
-                "sha256:096d689d78ca690e4cd8a89568ba06d07ca097e3306a4381635073ca91479966",
-                "sha256:14317396d1e8cdb122989b916fa2c7e9ca8e2be9e8060a6eff75b6b7b4d8a7e0"
-            ],
-            "markers": "python_version >= '3.6'",
-            "version": "==21.2"
-        },
-        "parso": {
-            "hashes": [
-                "sha256:12b83492c6239ce32ff5eed6d3639d6a536170723c6f3f1506869f1ace413398",
-                "sha256:a8c4922db71e4fdb90e0d0bc6e50f9b273d3397925e5e60a717e719201778d22"
-            ],
-            "markers": "python_version >= '3.6'",
-            "version": "==0.8.2"
-        },
-        "pathspec": {
-            "hashes": [
-                "sha256:7d15c4ddb0b5c802d161efc417ec1a2558ea2653c2e8ad9c19098201dc1c993a",
-                "sha256:e564499435a2673d586f6b2130bb5b95f04a3ba06f81b8f895b651a3c76aabb1"
-            ],
-            "index": "pypi",
-            "version": "==0.9.0"
-        },
-        "pexpect": {
-            "hashes": [
-                "sha256:0b48a55dcb3c05f3329815901ea4fc1537514d6ba867a152b581d69ae3710937",
-                "sha256:fc65a43959d153d0114afe13997d439c22823a27cefceb5ff35c2178c6784c0c"
-            ],
-            "markers": "sys_platform != 'win32'",
-            "version": "==4.8.0"
-        },
-        "pickleshare": {
-            "hashes": [
-                "sha256:87683d47965c1da65cdacaf31c8441d12b8044cdec9aca500cd78fc2c683afca",
-                "sha256:9649af414d74d4df115d5d718f82acb59c9d418196b7b4290ed47a12ce62df56"
-            ],
-            "version": "==0.7.5"
-        },
-        "pkginfo": {
-            "hashes": [
-                "sha256:37ecd857b47e5f55949c41ed061eb51a0bee97a87c969219d144c0e023982779",
-                "sha256:e7432f81d08adec7297633191bbf0bd47faf13cd8724c3a13250e51d542635bd"
-            ],
-            "version": "==1.7.1"
-        },
-        "platformdirs": {
-            "hashes": [
-                "sha256:367a5e80b3d04d2428ffa76d33f124cf11e8fff2acdaa9b43d545f5c7d661ef2",
-                "sha256:8868bbe3c3c80d42f20156f22e7131d2fb321f5bc86a2a345375c6481a67021d"
-            ],
-            "index": "pypi",
-            "version": "==2.4.0"
-        },
-        "pluggy": {
-            "hashes": [
-                "sha256:4224373bacce55f955a878bf9cfa763c1e360858e330072059e10bad68531159",
-                "sha256:74134bbf457f031a36d68416e1509f34bd5ccc019f0bcc952c7b909d06b37bd3"
-            ],
-            "markers": "python_version >= '3.6'",
-            "version": "==1.0.0"
-        },
-        "pre-commit": {
-            "hashes": [
-                "sha256:3c25add78dbdfb6a28a651780d5c311ac40dd17f160eb3954a0c59da40a505a7",
-                "sha256:a4ed01000afcb484d9eb8d504272e642c4c4099bbad3a6b27e519bd6a3e928a6"
-            ],
-            "index": "pypi",
-            "version": "==2.15.0"
-        },
-        "prompt-toolkit": {
-            "hashes": [
-                "sha256:449f333dd120bd01f5d296a8ce1452114ba3a71fae7288d2f0ae2c918764fa72",
-                "sha256:48d85cdca8b6c4f16480c7ce03fd193666b62b0a21667ca56b4bb5ad679d1170"
-            ],
-            "markers": "python_full_version >= '3.6.2'",
-            "version": "==3.0.22"
-        },
-        "ptyprocess": {
-            "hashes": [
-                "sha256:4b41f3967fce3af57cc7e94b888626c18bf37a083e3651ca8feeb66d492fef35",
-                "sha256:5c5d0a3b48ceee0b48485e0c26037c0acd7d29765ca3fbb5cb3831d347423220"
-            ],
-            "version": "==0.7.0"
-        },
-        "py": {
-            "hashes": [
-                "sha256:51c75c4126074b472f746a24399ad32f6053d1b34b68d2fa41e558e6f4a98719",
-                "sha256:607c53218732647dff4acdfcd50cb62615cedf612e72d1724fb1a0cc6405b378"
-            ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
-            "version": "==1.11.0"
-        },
-        "pycodestyle": {
-            "hashes": [
-                "sha256:720f8b39dde8b293825e7ff02c475f3077124006db4f440dcbc9a20b76548a20",
-                "sha256:eddd5847ef438ea1c7870ca7eb78a9d47ce0cdb4851a5523949f2601d0cbbe7f"
-            ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
-            "version": "==2.8.0"
-        },
-        "pycparser": {
-            "hashes": [
-                "sha256:8ee45429555515e1f6b185e78100aea234072576aa43ab53aefcae078162fca9",
-                "sha256:e644fdec12f7872f86c58ff790da456218b10f863970249516d60a5eaca77206"
-            ],
-            "version": "==2.21"
-        },
-        "pyflakes": {
-            "hashes": [
-                "sha256:05a85c2872edf37a4ed30b0cce2f6093e1d0581f8c19d7393122da7e25b2b24c",
-                "sha256:3bb3a3f256f4b7968c9c788781e4ff07dce46bdf12339dcda61053375426ee2e"
-            ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==2.4.0"
-        },
-        "pygments": {
-            "hashes": [
-                "sha256:b8e67fe6af78f492b3c4b3e2970c0624cbf08beb1e493b2c99b9fa1b67a20380",
-                "sha256:f398865f7eb6874156579fdf36bc840a03cab64d1cde9e93d68f46a425ec52c6"
-            ],
-            "markers": "python_version >= '3.5'",
-            "version": "==2.10.0"
-        },
-        "pyparsing": {
-            "hashes": [
-                "sha256:c203ec8783bf771a155b207279b9bccb8dea02d8f0c9e5f8ead507bc3246ecc1",
-                "sha256:ef9d7589ef3c200abe66653d3f1ab1033c3c419ae9b9bdb1240a85b024efc88b"
-            ],
-            "markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==2.4.7"
-        },
-        "pytest": {
-            "hashes": [
-                "sha256:131b36680866a76e6781d13f101efb86cf674ebb9762eb70d3082b6f29889e89",
-                "sha256:7310f8d27bc79ced999e760ca304d69f6ba6c6649c0b60fb0e04a4a77cacc134"
-            ],
-            "index": "pypi",
-            "version": "==6.2.5"
-        },
-        "pytest-cov": {
-            "hashes": [
-                "sha256:578d5d15ac4a25e5f961c938b85a05b09fdaae9deef3bb6de9a6e766622ca7a6",
-                "sha256:e7f0f5b1617d2210a2cabc266dfe2f4c75a8d32fb89eafb7ad9d06f6d076d470"
-            ],
-            "index": "pypi",
-            "version": "==3.0.0"
-        },
-        "pytest-forked": {
-            "hashes": [
-                "sha256:6aa9ac7e00ad1a539c41bec6d21011332de671e938c7637378ec9710204e37ca",
-                "sha256:dc4147784048e70ef5d437951728825a131b81714b398d5d52f17c7c144d8815"
-            ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
-            "version": "==1.3.0"
-        },
-        "pytest-xdist": {
-            "hashes": [
-                "sha256:7b61ebb46997a0820a263553179d6d1e25a8c50d8a8620cd1aa1e20e3be99168",
-                "sha256:89b330316f7fc475f999c81b577c2b926c9569f3d397ae432c0c2e2496d61ff9"
-            ],
-            "index": "pypi",
-            "version": "==2.4.0"
-        },
-        "pytz": {
-            "hashes": [
-                "sha256:3672058bc3453457b622aab7a1c3bfd5ab0bdae451512f6cf25f64ed37f5b87c",
-                "sha256:acad2d8b20a1af07d4e4c9d2e9285c5ed9104354062f275f3fcd88dcef4f1326"
-            ],
-            "version": "==2021.3"
-        },
-        "pyyaml": {
-            "hashes": [
-                "sha256:0283c35a6a9fbf047493e3a0ce8d79ef5030852c51e9d911a27badfde0605293",
-                "sha256:055d937d65826939cb044fc8c9b08889e8c743fdc6a32b33e2390f66013e449b",
-                "sha256:07751360502caac1c067a8132d150cf3d61339af5691fe9e87803040dbc5db57",
-                "sha256:0b4624f379dab24d3725ffde76559cff63d9ec94e1736b556dacdfebe5ab6d4b",
-                "sha256:0ce82d761c532fe4ec3f87fc45688bdd3a4c1dc5e0b4a19814b9009a29baefd4",
-                "sha256:1e4747bc279b4f613a09eb64bba2ba602d8a6664c6ce6396a4d0cd413a50ce07",
-                "sha256:213c60cd50106436cc818accf5baa1aba61c0189ff610f64f4a3e8c6726218ba",
-                "sha256:231710d57adfd809ef5d34183b8ed1eeae3f76459c18fb4a0b373ad56bedcdd9",
-                "sha256:277a0ef2981ca40581a47093e9e2d13b3f1fbbeffae064c1d21bfceba2030287",
-                "sha256:2cd5df3de48857ed0544b34e2d40e9fac445930039f3cfe4bcc592a1f836d513",
-                "sha256:40527857252b61eacd1d9af500c3337ba8deb8fc298940291486c465c8b46ec0",
-                "sha256:473f9edb243cb1935ab5a084eb238d842fb8f404ed2193a915d1784b5a6b5fc0",
-                "sha256:48c346915c114f5fdb3ead70312bd042a953a8ce5c7106d5bfb1a5254e47da92",
-                "sha256:50602afada6d6cbfad699b0c7bb50d5ccffa7e46a3d738092afddc1f9758427f",
-                "sha256:68fb519c14306fec9720a2a5b45bc9f0c8d1b9c72adf45c37baedfcd949c35a2",
-                "sha256:77f396e6ef4c73fdc33a9157446466f1cff553d979bd00ecb64385760c6babdc",
-                "sha256:819b3830a1543db06c4d4b865e70ded25be52a2e0631ccd2f6a47a2822f2fd7c",
-                "sha256:897b80890765f037df3403d22bab41627ca8811ae55e9a722fd0392850ec4d86",
-                "sha256:98c4d36e99714e55cfbaaee6dd5badbc9a1ec339ebfc3b1f52e293aee6bb71a4",
-                "sha256:9df7ed3b3d2e0ecfe09e14741b857df43adb5a3ddadc919a2d94fbdf78fea53c",
-                "sha256:9fa600030013c4de8165339db93d182b9431076eb98eb40ee068700c9c813e34",
-                "sha256:a80a78046a72361de73f8f395f1f1e49f956c6be882eed58505a15f3e430962b",
-                "sha256:b3d267842bf12586ba6c734f89d1f5b871df0273157918b0ccefa29deb05c21c",
-                "sha256:b5b9eccad747aabaaffbc6064800670f0c297e52c12754eb1d976c57e4f74dcb",
-                "sha256:c5687b8d43cf58545ade1fe3e055f70eac7a5a1a0bf42824308d868289a95737",
-                "sha256:cba8c411ef271aa037d7357a2bc8f9ee8b58b9965831d9e51baf703280dc73d3",
-                "sha256:d15a181d1ecd0d4270dc32edb46f7cb7733c7c508857278d3d378d14d606db2d",
-                "sha256:d4db7c7aef085872ef65a8fd7d6d09a14ae91f691dec3e87ee5ee0539d516f53",
-                "sha256:d4eccecf9adf6fbcc6861a38015c2a64f38b9d94838ac1810a9023a0609e1b78",
-                "sha256:d67d839ede4ed1b28a4e8909735fc992a923cdb84e618544973d7dfc71540803",
-                "sha256:daf496c58a8c52083df09b80c860005194014c3698698d1a57cbcfa182142a3a",
-                "sha256:e61ceaab6f49fb8bdfaa0f92c4b57bcfbea54c09277b1b4f7ac376bfb7a7c174",
-                "sha256:f84fbc98b019fef2ee9a1cb3ce93e3187a6df0b2538a651bfb890254ba9f90b5"
-            ],
-            "markers": "python_version >= '3.6'",
-            "version": "==6.0"
-        },
-        "readme-renderer": {
-            "hashes": [
-                "sha256:3286806450d9961d6e3b5f8a59f77e61503799aca5155c8d8d40359b4e1e1adc",
-                "sha256:8299700d7a910c304072a7601eafada6712a5b011a20139417e1b1e9f04645d8"
-            ],
-            "index": "pypi",
-            "version": "==30.0"
-        },
-        "requests": {
-            "hashes": [
-                "sha256:6c1246513ecd5ecd4528a0906f910e8f0f9c6b8ec72030dc9fd154dc1a6efd24",
-                "sha256:b8aa58f8cf793ffd8782d3d8cb19e66ef36f7aba4353eec859e74678b01b07a7"
-            ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4, 3.5'",
-            "version": "==2.26.0"
-        },
-        "requests-toolbelt": {
-            "hashes": [
-                "sha256:380606e1d10dc85c3bd47bf5a6095f815ec007be7a8b69c878507068df059e6f",
-                "sha256:968089d4584ad4ad7c171454f0a5c6dac23971e9472521ea3b6d49d610aa6fc0"
-            ],
-            "version": "==0.9.1"
-        },
-        "rfc3986": {
-            "hashes": [
-                "sha256:270aaf10d87d0d4e095063c65bf3ddbc6ee3d0b226328ce21e036f946e421835",
-                "sha256:a86d6e1f5b1dc238b218b012df0aa79409667bb209e58da56d0b94704e712a97"
-            ],
-            "version": "==1.5.0"
-        },
-        "secretstorage": {
-            "hashes": [
-                "sha256:422d82c36172d88d6a0ed5afdec956514b189ddbfb72fefab0c8a1cee4eaf71f",
-                "sha256:fd666c51a6bf200643495a04abb261f83229dcb6fd8472ec393df7ffc8b6f195"
-            ],
-            "markers": "sys_platform == 'linux'",
-            "version": "==3.3.1"
-        },
-        "setuptools": {
-            "hashes": [
-                "sha256:a481fbc56b33f5d8f6b33dce41482e64c68b668be44ff42922903b03872590bf",
-                "sha256:dae6b934a965c8a59d6d230d3867ec408bb95e73bd538ff77e71fedf1eaca729"
-            ],
-            "markers": "python_version >= '3.6'",
-            "version": "==58.5.3"
-        },
-        "setuptools-scm": {
-            "extras": [
-                "toml"
-            ],
-            "hashes": [
-                "sha256:4c64444b1d49c4063ae60bfe1680f611c8b13833d556fd1d6050c0023162a119",
-                "sha256:a49aa8081eeb3514eb9728fa5040f2eaa962d6c6f4ec9c32f6c1fba88f88a0f2"
-            ],
-            "markers": "python_version >= '3.6'",
-            "version": "==6.3.2"
-        },
-        "six": {
-            "hashes": [
-                "sha256:1e61c37477a1626458e36f7b1d82aa5c9b094fa4802892072e49de9c60c4c926",
-                "sha256:8abb2f1d86890a2dfb989f9a77cfcfd3e47c2a354b01111771326f8aa26e0254"
-            ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==1.16.0"
-        },
-        "snowballstemmer": {
-            "hashes": [
-                "sha256:b51b447bea85f9968c13b650126a888aabd4cb4463fca868ec596826325dedc2",
-                "sha256:e997baa4f2e9139951b6f4c631bad912dfd3c792467e2f03d7239464af90e914"
-            ],
-            "version": "==2.1.0"
-        },
-        "sphinx": {
-            "hashes": [
-                "sha256:6d051ab6e0d06cba786c4656b0fe67ba259fe058410f49e95bee6e49c4052cbf",
-                "sha256:7e2b30da5f39170efcd95c6270f07669d623c276521fee27ad6c380f49d2bf5b"
-            ],
-            "index": "pypi",
-            "version": "==4.3.0"
-        },
-        "sphinx-copybutton": {
-            "hashes": [
-                "sha256:4340d33c169dac6dd82dce2c83333412aa786a42dd01a81a8decac3b130dc8b0",
-                "sha256:8daed13a87afd5013c3a9af3575cc4d5bec052075ccd3db243f895c07a689386"
-            ],
-            "index": "pypi",
-            "version": "==0.4.0"
-        },
-        "sphinxcontrib-applehelp": {
-            "hashes": [
-                "sha256:806111e5e962be97c29ec4c1e7fe277bfd19e9652fb1a4392105b43e01af885a",
-                "sha256:a072735ec80e7675e3f432fcae8610ecf509c5f1869d17e2eecff44389cdbc58"
-            ],
-            "markers": "python_version >= '3.5'",
-            "version": "==1.0.2"
-        },
-        "sphinxcontrib-devhelp": {
-            "hashes": [
-                "sha256:8165223f9a335cc1af7ffe1ed31d2871f325254c0423bc0c4c7cd1c1e4734a2e",
-                "sha256:ff7f1afa7b9642e7060379360a67e9c41e8f3121f2ce9164266f61b9f4b338e4"
-            ],
-            "markers": "python_version >= '3.5'",
-            "version": "==1.0.2"
-        },
-        "sphinxcontrib-htmlhelp": {
-            "hashes": [
-                "sha256:d412243dfb797ae3ec2b59eca0e52dac12e75a241bf0e4eb861e450d06c6ed07",
-                "sha256:f5f8bb2d0d629f398bf47d0d69c07bc13b65f75a81ad9e2f71a63d4b7a2f6db2"
-            ],
-            "markers": "python_version >= '3.6'",
-            "version": "==2.0.0"
-        },
-        "sphinxcontrib-jsmath": {
-            "hashes": [
-                "sha256:2ec2eaebfb78f3f2078e73666b1415417a116cc848b72e5172e596c871103178",
-                "sha256:a9925e4a4587247ed2191a22df5f6970656cb8ca2bd6284309578f2153e0c4b8"
-            ],
-            "markers": "python_version >= '3.5'",
-            "version": "==1.0.1"
-        },
-        "sphinxcontrib-programoutput": {
-            "hashes": [
-                "sha256:0ef1c1d9159dbe7103077748214305eb4e0138e861feb71c0c346afc5fe97f84",
-                "sha256:300ee9b8caee8355d25cc74b4d1c7efd12e608d2ad165e3141d31e6fbc152b7f"
-            ],
-            "index": "pypi",
-            "version": "==0.17"
-        },
-        "sphinxcontrib-qthelp": {
-            "hashes": [
-                "sha256:4c33767ee058b70dba89a6fc5c1892c0d57a54be67ddd3e7875a18d14cba5a72",
-                "sha256:bd9fc24bcb748a8d51fd4ecaade681350aa63009a347a8c14e637895444dfab6"
-            ],
-            "markers": "python_version >= '3.5'",
-            "version": "==1.0.3"
-        },
-        "sphinxcontrib-serializinghtml": {
-            "hashes": [
-                "sha256:352a9a00ae864471d3a7ead8d7d79f5fc0b57e8b3f95e9867eb9eb28999b92fd",
-                "sha256:aa5f6de5dfdf809ef505c4895e51ef5c9eac17d0f287933eb49ec495280b6952"
-            ],
-            "markers": "python_version >= '3.5'",
-            "version": "==1.1.5"
-        },
-        "tokenize-rt": {
-            "hashes": [
-                "sha256:08a27fa032a81cf45e8858d0ac706004fcd523e8463415ddf1442be38e204ea8",
-                "sha256:0d4f69026fed520f8a1e0103aa36c406ef4661417f20ca643f913e33531b3b94"
-            ],
-            "markers": "python_full_version >= '3.6.1'",
-            "version": "==4.2.1"
-        },
-        "toml": {
-            "hashes": [
-                "sha256:806143ae5bfb6a3c6e736a764057db0e6a0e05e338b5630894a5f779cabb4f9b",
-                "sha256:b3bda1d108d5dd99f4a20d24d9c348e91c4db7ab1b749200bded2f839ccbe68f"
-            ],
-            "markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==0.10.2"
-        },
-        "tomli": {
-            "hashes": [
-                "sha256:c6ce0015eb38820eaf32b5db832dbc26deb3dd427bd5f6556cf0acac2c214fee",
-                "sha256:f04066f68f5554911363063a30b108d2b5a5b1a010aa8b6132af78489fe3aade"
-            ],
-            "index": "pypi",
-            "version": "==1.2.2"
-        },
-        "tox": {
-            "hashes": [
-                "sha256:5e274227a53dc9ef856767c21867377ba395992549f02ce55eb549f9fb9a8d10",
-                "sha256:c30b57fa2477f1fb7c36aa1d83292d5c2336cd0018119e1b1c17340e2c2708ca"
-            ],
-            "index": "pypi",
-            "version": "==3.24.4"
-        },
-        "tqdm": {
-            "hashes": [
-                "sha256:8dd278a422499cd6b727e6ae4061c40b48fce8b76d1ccbf5d34fca9b7f925b0c",
-                "sha256:d359de7217506c9851b7869f3708d8ee53ed70a1b8edbba4dbcb47442592920d"
-            ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==4.62.3"
-        },
-        "traitlets": {
-            "hashes": [
-                "sha256:70b4c6a1d9019d7b4f6846832288f86998aa3b9207c6821f3578a6a6a467fe44",
-                "sha256:d023ee369ddd2763310e4c3eae1ff649689440d4ae59d7485eb4cfbbe3e359f7"
-            ],
-            "version": "==4.3.3"
-        },
-        "twine": {
-            "hashes": [
-                "sha256:4caad5ef4722e127b3749052fcbffaaf71719b19d4fd4973b29c469957adeba2",
-                "sha256:916070f8ecbd1985ebed5dbb02b9bda9a092882a96d7069d542d4fc0bb5c673c"
-            ],
-            "index": "pypi",
-            "version": "==3.6.0"
-        },
-        "typed-ast": {
-            "hashes": [
-                "sha256:01ae5f73431d21eead5015997ab41afa53aa1fbe252f9da060be5dad2c730ace",
-                "sha256:067a74454df670dcaa4e59349a2e5c81e567d8d65458d480a5b3dfecec08c5ff",
-                "sha256:0fb71b8c643187d7492c1f8352f2c15b4c4af3f6338f21681d3681b3dc31a266",
-                "sha256:1b3ead4a96c9101bef08f9f7d1217c096f31667617b58de957f690c92378b528",
-                "sha256:2068531575a125b87a41802130fa7e29f26c09a2833fea68d9a40cf33902eba6",
-                "sha256:209596a4ec71d990d71d5e0d312ac935d86930e6eecff6ccc7007fe54d703808",
-                "sha256:2c726c276d09fc5c414693a2de063f521052d9ea7c240ce553316f70656c84d4",
-                "sha256:398e44cd480f4d2b7ee8d98385ca104e35c81525dd98c519acff1b79bdaac363",
-                "sha256:52b1eb8c83f178ab787f3a4283f68258525f8d70f778a2f6dd54d3b5e5fb4341",
-                "sha256:5feca99c17af94057417d744607b82dd0a664fd5e4ca98061480fd8b14b18d04",
-                "sha256:7538e495704e2ccda9b234b82423a4038f324f3a10c43bc088a1636180f11a41",
-                "sha256:760ad187b1041a154f0e4d0f6aae3e40fdb51d6de16e5c99aedadd9246450e9e",
-                "sha256:777a26c84bea6cd934422ac2e3b78863a37017618b6e5c08f92ef69853e765d3",
-                "sha256:95431a26309a21874005845c21118c83991c63ea800dd44843e42a916aec5899",
-                "sha256:9ad2c92ec681e02baf81fdfa056fe0d818645efa9af1f1cd5fd6f1bd2bdfd805",
-                "sha256:9c6d1a54552b5330bc657b7ef0eae25d00ba7ffe85d9ea8ae6540d2197a3788c",
-                "sha256:aee0c1256be6c07bd3e1263ff920c325b59849dc95392a05f258bb9b259cf39c",
-                "sha256:af3d4a73793725138d6b334d9d247ce7e5f084d96284ed23f22ee626a7b88e39",
-                "sha256:b36b4f3920103a25e1d5d024d155c504080959582b928e91cb608a65c3a49e1a",
-                "sha256:b9574c6f03f685070d859e75c7f9eeca02d6933273b5e69572e5ff9d5e3931c3",
-                "sha256:bff6ad71c81b3bba8fa35f0f1921fb24ff4476235a6e94a26ada2e54370e6da7",
-                "sha256:c190f0899e9f9f8b6b7863debfb739abcb21a5c054f911ca3596d12b8a4c4c7f",
-                "sha256:c907f561b1e83e93fad565bac5ba9c22d96a54e7ea0267c708bffe863cbe4075",
-                "sha256:cae53c389825d3b46fb37538441f75d6aecc4174f615d048321b716df2757fb0",
-                "sha256:dd4a21253f42b8d2b48410cb31fe501d32f8b9fbeb1f55063ad102fe9c425e40",
-                "sha256:dde816ca9dac1d9c01dd504ea5967821606f02e510438120091b84e852367428",
-                "sha256:f2362f3cb0f3172c42938946dbc5b7843c2a28aec307c49100c8b38764eb6927",
-                "sha256:f328adcfebed9f11301eaedfa48e15bdece9b519fb27e6a8c01aa52a17ec31b3",
-                "sha256:f8afcf15cc511ada719a88e013cec87c11aff7b91f019295eb4530f96fe5ef2f",
-                "sha256:fb1bbeac803adea29cedd70781399c99138358c26d05fcbd23c13016b7f5ec65"
-            ],
-            "index": "pypi",
-            "version": "==1.4.3"
-        },
-        "types-dataclasses": {
-            "hashes": [
-                "sha256:6568532fed11f854e4db2eb48063385b323b93ecadd09f10a215d56246c306d7",
-                "sha256:aa45bb0dacdba09e3195a36ff8337bba45eac03b6f31c4645e87b4a2a47830dd"
-            ],
-            "index": "pypi",
-            "version": "==0.6.1"
-        },
-        "types-pyyaml": {
-            "hashes": [
-                "sha256:2e27b0118ca4248a646101c5c318dc02e4ca2866d6bc42e84045dbb851555a76",
-                "sha256:d5b318269652e809b5c30a5fe666c50159ab80bfd41cd6bafe655bf20b29fcba"
-            ],
-            "index": "pypi",
-            "version": "==6.0.1"
-        },
-        "types-typed-ast": {
-            "hashes": [
-                "sha256:4a261b6af545af41fd08957993292742959ca5c480ee8d49804dcc68d78773a3",
-                "sha256:d8ea79cbfbc520be8d9bc8de4872f44b342dbdbc091667e2f21b03bbd7969150"
-            ],
-            "index": "pypi",
-            "version": "==1.5.0"
-        },
-        "typing-extensions": {
-            "hashes": [
-                "sha256:49f75d16ff11f1cd258e1b988ccff82a3ca5570217d7ad8c5f48205dd99a677e",
-                "sha256:d8226d10bc02a29bcc81df19a26e56a9647f8b0a6d4a83924139f4a8b01f17b7",
-                "sha256:f1d25edafde516b146ecd0613dabcc61409817af4766fbbcfb8d1ad4ec441a34"
-            ],
-            "index": "pypi",
-            "markers": "python_version < '3.10'",
-            "version": "==3.10.0.2"
-        },
-        "urllib3": {
-            "hashes": [
-                "sha256:4987c65554f7a2dbf30c18fd48778ef124af6fab771a377103da0585e2336ece",
-                "sha256:c4fdf4019605b6e5423637e01bc9fe4daef873709a7973e195ceba0a62bbc844"
-            ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4' and python_version < '4'",
-            "version": "==1.26.7"
-        },
-        "virtualenv": {
-            "hashes": [
-                "sha256:4b02e52a624336eece99c96e3ab7111f469c24ba226a53ec474e8e787b365814",
-                "sha256:576d05b46eace16a9c348085f7d0dc8ef28713a2cabaa1cf0aea41e8f12c9218"
-            ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
-            "version": "==20.10.0"
-        },
-        "wcwidth": {
-            "hashes": [
-                "sha256:beb4802a9cebb9144e99086eff703a642a13d6a0052920003a230f3294bbe784",
-                "sha256:c4d647b99872929fdb7bdcaa4fbe7f01413ed3d98077df798530e5b04f116c83"
-            ],
-            "version": "==0.2.5"
-        },
-        "webencodings": {
-            "hashes": [
-                "sha256:a0af1213f3c2226497a97e2b3aa01a7e4bee4f403f95be16fc9acd2947514a78",
-                "sha256:b36a1c245f2d304965eb4e0a82848379241dc04b865afcc4aab16748587e1923"
-            ],
-            "version": "==0.5.1"
-        },
-        "wheel": {
-            "hashes": [
-                "sha256:21014b2bd93c6d0034b6ba5d35e4eb284340e09d63c59aef6fc14b0f346146fd",
-                "sha256:e2ef7239991699e3355d54f8e968a21bb940a1dbf34a4d226741e64462516fad"
-            ],
-            "index": "pypi",
-            "version": "==0.37.0"
-        },
-        "yarl": {
-            "hashes": [
-                "sha256:044daf3012e43d4b3538562da94a88fb12a6490652dbc29fb19adfa02cf72eac",
-                "sha256:0cba38120db72123db7c58322fa69e3c0efa933040ffb586c3a87c063ec7cae8",
-                "sha256:167ab7f64e409e9bdd99333fe8c67b5574a1f0495dcfd905bc7454e766729b9e",
-                "sha256:1be4bbb3d27a4e9aa5f3df2ab61e3701ce8fcbd3e9846dbce7c033a7e8136746",
-                "sha256:1ca56f002eaf7998b5fcf73b2421790da9d2586331805f38acd9997743114e98",
-                "sha256:1d3d5ad8ea96bd6d643d80c7b8d5977b4e2fb1bab6c9da7322616fd26203d125",
-                "sha256:1eb6480ef366d75b54c68164094a6a560c247370a68c02dddb11f20c4c6d3c9d",
-                "sha256:1edc172dcca3f11b38a9d5c7505c83c1913c0addc99cd28e993efeaafdfaa18d",
-                "sha256:211fcd65c58bf250fb994b53bc45a442ddc9f441f6fec53e65de8cba48ded986",
-                "sha256:29e0656d5497733dcddc21797da5a2ab990c0cb9719f1f969e58a4abac66234d",
-                "sha256:368bcf400247318382cc150aaa632582d0780b28ee6053cd80268c7e72796dec",
-                "sha256:39d5493c5ecd75c8093fa7700a2fb5c94fe28c839c8e40144b7ab7ccba6938c8",
-                "sha256:3abddf0b8e41445426d29f955b24aeecc83fa1072be1be4e0d194134a7d9baee",
-                "sha256:3bf8cfe8856708ede6a73907bf0501f2dc4e104085e070a41f5d88e7faf237f3",
-                "sha256:3ec1d9a0d7780416e657f1e405ba35ec1ba453a4f1511eb8b9fbab81cb8b3ce1",
-                "sha256:45399b46d60c253327a460e99856752009fcee5f5d3c80b2f7c0cae1c38d56dd",
-                "sha256:52690eb521d690ab041c3919666bea13ab9fbff80d615ec16fa81a297131276b",
-                "sha256:534b047277a9a19d858cde163aba93f3e1677d5acd92f7d10ace419d478540de",
-                "sha256:580c1f15500e137a8c37053e4cbf6058944d4c114701fa59944607505c2fe3a0",
-                "sha256:59218fef177296451b23214c91ea3aba7858b4ae3306dde120224cfe0f7a6ee8",
-                "sha256:5ba63585a89c9885f18331a55d25fe81dc2d82b71311ff8bd378fc8004202ff6",
-                "sha256:5bb7d54b8f61ba6eee541fba4b83d22b8a046b4ef4d8eb7f15a7e35db2e1e245",
-                "sha256:6152224d0a1eb254f97df3997d79dadd8bb2c1a02ef283dbb34b97d4f8492d23",
-                "sha256:67e94028817defe5e705079b10a8438b8cb56e7115fa01640e9c0bb3edf67332",
-                "sha256:695ba021a9e04418507fa930d5f0704edbce47076bdcfeeaba1c83683e5649d1",
-                "sha256:6a1a9fe17621af43e9b9fcea8bd088ba682c8192d744b386ee3c47b56eaabb2c",
-                "sha256:6ab0c3274d0a846840bf6c27d2c60ba771a12e4d7586bf550eefc2df0b56b3b4",
-                "sha256:6feca8b6bfb9eef6ee057628e71e1734caf520a907b6ec0d62839e8293e945c0",
-                "sha256:737e401cd0c493f7e3dd4db72aca11cfe069531c9761b8ea474926936b3c57c8",
-                "sha256:788713c2896f426a4e166b11f4ec538b5736294ebf7d5f654ae445fd44270832",
-                "sha256:797c2c412b04403d2da075fb93c123df35239cd7b4cc4e0cd9e5839b73f52c58",
-                "sha256:8300401dc88cad23f5b4e4c1226f44a5aa696436a4026e456fe0e5d2f7f486e6",
-                "sha256:87f6e082bce21464857ba58b569370e7b547d239ca22248be68ea5d6b51464a1",
-                "sha256:89ccbf58e6a0ab89d487c92a490cb5660d06c3a47ca08872859672f9c511fc52",
-                "sha256:8b0915ee85150963a9504c10de4e4729ae700af11df0dc5550e6587ed7891e92",
-                "sha256:8cce6f9fa3df25f55521fbb5c7e4a736683148bcc0c75b21863789e5185f9185",
-                "sha256:95a1873b6c0dd1c437fb3bb4a4aaa699a48c218ac7ca1e74b0bee0ab16c7d60d",
-                "sha256:9b4c77d92d56a4c5027572752aa35082e40c561eec776048330d2907aead891d",
-                "sha256:9bfcd43c65fbb339dc7086b5315750efa42a34eefad0256ba114cd8ad3896f4b",
-                "sha256:9c1f083e7e71b2dd01f7cd7434a5f88c15213194df38bc29b388ccdf1492b739",
-                "sha256:a1d0894f238763717bdcfea74558c94e3bc34aeacd3351d769460c1a586a8b05",
-                "sha256:a467a431a0817a292121c13cbe637348b546e6ef47ca14a790aa2fa8cc93df63",
-                "sha256:aa32aaa97d8b2ed4e54dc65d241a0da1c627454950f7d7b1f95b13985afd6c5d",
-                "sha256:ac10bbac36cd89eac19f4e51c032ba6b412b3892b685076f4acd2de18ca990aa",
-                "sha256:ac35ccde589ab6a1870a484ed136d49a26bcd06b6a1c6397b1967ca13ceb3913",
-                "sha256:bab827163113177aee910adb1f48ff7af31ee0289f434f7e22d10baf624a6dfe",
-                "sha256:baf81561f2972fb895e7844882898bda1eef4b07b5b385bcd308d2098f1a767b",
-                "sha256:bf19725fec28452474d9887a128e98dd67eee7b7d52e932e6949c532d820dc3b",
-                "sha256:c01a89a44bb672c38f42b49cdb0ad667b116d731b3f4c896f72302ff77d71656",
-                "sha256:c0910c6b6c31359d2f6184828888c983d54d09d581a4a23547a35f1d0b9484b1",
-                "sha256:c10ea1e80a697cf7d80d1ed414b5cb8f1eec07d618f54637067ae3c0334133c4",
-                "sha256:c1164a2eac148d85bbdd23e07dfcc930f2e633220f3eb3c3e2a25f6148c2819e",
-                "sha256:c145ab54702334c42237a6c6c4cc08703b6aa9b94e2f227ceb3d477d20c36c63",
-                "sha256:c17965ff3706beedafd458c452bf15bac693ecd146a60a06a214614dc097a271",
-                "sha256:c19324a1c5399b602f3b6e7db9478e5b1adf5cf58901996fc973fe4fccd73eed",
-                "sha256:c2a1ac41a6aa980db03d098a5531f13985edcb451bcd9d00670b03129922cd0d",
-                "sha256:c6ddcd80d79c96eb19c354d9dca95291589c5954099836b7c8d29278a7ec0bda",
-                "sha256:c9c6d927e098c2d360695f2e9d38870b2e92e0919be07dbe339aefa32a090265",
-                "sha256:cc8b7a7254c0fc3187d43d6cb54b5032d2365efd1df0cd1749c0c4df5f0ad45f",
-                "sha256:cff3ba513db55cc6a35076f32c4cdc27032bd075c9faef31fec749e64b45d26c",
-                "sha256:d260d4dc495c05d6600264a197d9d6f7fc9347f21d2594926202fd08cf89a8ba",
-                "sha256:d6f3d62e16c10e88d2168ba2d065aa374e3c538998ed04996cd373ff2036d64c",
-                "sha256:da6df107b9ccfe52d3a48165e48d72db0eca3e3029b5b8cb4fe6ee3cb870ba8b",
-                "sha256:dfe4b95b7e00c6635a72e2d00b478e8a28bfb122dc76349a06e20792eb53a523",
-                "sha256:e39378894ee6ae9f555ae2de332d513a5763276a9265f8e7cbaeb1b1ee74623a",
-                "sha256:ede3b46cdb719c794427dcce9d8beb4abe8b9aa1e97526cc20de9bd6583ad1ef",
-                "sha256:f2a8508f7350512434e41065684076f640ecce176d262a7d54f0da41d99c5a95",
-                "sha256:f44477ae29025d8ea87ec308539f95963ffdc31a82f42ca9deecf2d505242e72",
-                "sha256:f64394bd7ceef1237cc604b5a89bf748c95982a84bcd3c4bbeb40f685c810794",
-                "sha256:fc4dd8b01a8112809e6b636b00f487846956402834a7fd59d46d4f4267181c41",
-                "sha256:fce78593346c014d0d986b7ebc80d782b7f5e19843ca798ed62f8e3ba8728576",
-                "sha256:fd547ec596d90c8676e369dd8a581a21227fe9b4ad37d0dc7feb4ccf544c2d59"
-            ],
-            "markers": "python_version >= '3.6'",
-            "version": "==1.7.2"
-        },
-        "zipp": {
-            "hashes": [
-                "sha256:71c644c5369f4a6e07636f0aa966270449561fcea2e3d6747b8d23efaa9d7832",
-                "sha256:9fe5ea21568a0a70e50f273397638d39b03353731e6cbbb3fd8502a33fec40bc"
-            ],
-            "markers": "python_version >= '3.6'",
-            "version": "==3.6.0"
-        }
-    }
-}
diff --git a/docs/contributing/the_basics.md b/docs/contributing/the_basics.md
index d61f3ec45b6..d9df0ea30c4 100644
--- a/docs/contributing/the_basics.md
+++ b/docs/contributing/the_basics.md
@@ -10,20 +10,11 @@ You can use any operating system.
 Install all development dependencies using:
 
 ```console
-$ pipenv install --dev
-$ pipenv shell
-$ pre-commit install
-```
-
-If you haven't used `pipenv` before but are comfortable with virtualenvs, just run
-`pip install pipenv` in the virtualenv you're already using and invoke the command above
-from the cloned _Black_ repo. It will do the correct thing.
-
-Non pipenv install works too:
-
-```console
-$ pip install -r test_requirements.txt
-$ pip install -e .[d]
+$ python3 -m venv .venv
+$ source .venv/bin/activate
+(.venv)$ pip install -r test_requirements.txt
+(.venv)$ pip install -e .[d]
+(.venv)$ pre-commit install
 ```
 
 Before submitting pull requests, run lints and tests with the following commands from
@@ -31,16 +22,16 @@ the root of the black repo:
 
 ```console
 # Linting
-$ pre-commit run -a
+(.venv)$ pre-commit run -a
 
 # Unit tests
-$ tox -e py
+(.venv)$ tox -e py
 
 # Optional Fuzz testing
-$ tox -e fuzz
+(.venv)$ tox -e fuzz
 
 # Optional CI run to test your changes on many popular python projects
-$ black-primer [-k -w /tmp/black_test_repos]
+(.venv)$ black-primer [-k -w /tmp/black_test_repos]
 ```
 
 ### News / Changelog Requirement
@@ -70,9 +61,9 @@ formatting don't need to be mentioned separately though.
 If you make changes to docs, you can test they still build locally too.
 
 ```console
-$ pip install -r docs/requirements.txt
-$ pip install [-e] .[d]
-$ sphinx-build -a -b html -W docs/ docs/_build/
+(.venv)$ pip install -r docs/requirements.txt
+(.venv)$ pip install [-e] .[d]
+(.venv)$ sphinx-build -a -b html -W docs/ docs/_build/
 ```
 
 ## black-primer

From 3fafd806b30cbff5788525f050a635639d97b11c Mon Sep 17 00:00:00 2001
From: Batuhan Taskaya <isidentical@gmail.com>
Date: Tue, 21 Dec 2021 21:16:55 +0300
Subject: [PATCH 0396/1034] Support multiple top-level as-expressions on case
 statements (#2716)

---
 CHANGES.md                            |  2 ++
 src/blib2to3/Grammar.txt              |  4 ++--
 tests/data/pattern_matching_extras.py | 11 +++++++++++
 3 files changed, 15 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 252f2cc8863..d5cfb623c9a 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -10,6 +10,8 @@
   underlying SyntaxError (#2693)
 - Fix mapping cases that contain as-expressions, like `case {"key": 1 | 2 as password}`
   (#2686)
+- Fix cases that contain multiple top-level as-expressions, like `case 1 as a, 2 as b`
+  (#2716)
 - No longer color diff headers white as it's unreadable in light themed terminals
   (#2691)
 - Tuple unpacking on `return` and `yield` constructs now implies 3.8+ (#2700)
diff --git a/src/blib2to3/Grammar.txt b/src/blib2to3/Grammar.txt
index 600712ce2f0..27776a3b65c 100644
--- a/src/blib2to3/Grammar.txt
+++ b/src/blib2to3/Grammar.txt
@@ -247,5 +247,5 @@ subject_expr: (namedexpr_test|star_expr) (',' (namedexpr_test|star_expr))* [',']
 # cases
 case_block: "case" patterns [guard] ':' suite
 guard: 'if' namedexpr_test
-patterns: pattern ['as' pattern]
-pattern: (expr|star_expr) (',' (expr|star_expr))* [',']
+patterns: pattern (',' pattern)* [',']
+pattern: (expr|star_expr) ['as' expr]
diff --git a/tests/data/pattern_matching_extras.py b/tests/data/pattern_matching_extras.py
index c00585e9285..b652d2685ec 100644
--- a/tests/data/pattern_matching_extras.py
+++ b/tests/data/pattern_matching_extras.py
@@ -92,3 +92,14 @@ def func(match: case, case: match) -> case:
         pass
     case {"maybe": something(complicated as this) as that}:
         pass
+
+
+match something:
+    case 1 as a:
+        pass
+
+    case 2 as b, 3 as c:
+        pass
+
+    case 4 as d, (5 as e), (6 | 7 as g), *h:
+        pass

From f0a99f640279adade284eba592630c67ad374574 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Felix=20Hild=C3=A9n?= <felix.hilden@gmail.com>
Date: Tue, 21 Dec 2021 20:43:10 +0200
Subject: [PATCH 0397/1034] Update contributing wording (#2719)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 docs/contributing/the_basics.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/contributing/the_basics.md b/docs/contributing/the_basics.md
index d9df0ea30c4..9a639731073 100644
--- a/docs/contributing/the_basics.md
+++ b/docs/contributing/the_basics.md
@@ -7,7 +7,8 @@ An overview on contributing to the _Black_ project.
 Development on the latest version of Python is preferred. As of this writing it's 3.9.
 You can use any operating system.
 
-Install all development dependencies using:
+Install development dependencies inside a virtual environment of your choice, for
+example:
 
 ```console
 $ python3 -m venv .venv

From ced2d656794568517ba9aa28f781f9151d89de54 Mon Sep 17 00:00:00 2001
From: Marco Edward Gorelli <marcogorelli@protonmail.com>
Date: Sat, 25 Dec 2021 02:25:03 +0000
Subject: [PATCH 0398/1034] remove all type: ignores in src/black (GH-2720)

Excet
;t
---
 src/black/linegen.py |  3 ++-
 src/black/parsing.py | 24 +++++++++++++++---------
 2 files changed, 17 insertions(+), 10 deletions(-)

diff --git a/src/black/linegen.py b/src/black/linegen.py
index c1cd6fa22d9..dc238c3aee4 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -815,9 +815,10 @@ def normalize_invisible_parens(node: Node, parens_after: Set[str]) -> None:
                 # "import from" nodes store parentheses directly as part of
                 # the statement
                 if is_lpar_token(child):
+                    assert is_rpar_token(node.children[-1])
                     # make parentheses invisible
                     child.value = ""
-                    node.children[-1].value = ""  # type: ignore
+                    node.children[-1].value = ""
                 elif child.type != token.STAR:
                     # insert invisible parentheses
                     node.insert_child(index, Leaf(token.LPAR, ""))
diff --git a/src/black/parsing.py b/src/black/parsing.py
index c101643fe11..76e9de023c7 100644
--- a/src/black/parsing.py
+++ b/src/black/parsing.py
@@ -4,7 +4,7 @@
 import ast
 import platform
 import sys
-from typing import Any, Iterable, Iterator, List, Set, Tuple, Type, Union
+from typing import Any, AnyStr, Iterable, Iterator, List, Set, Tuple, Type, Union
 
 if sys.version_info < (3, 8):
     from typing_extensions import Final
@@ -191,6 +191,16 @@ def parse_ast(src: str) -> Union[ast.AST, ast3.AST, ast27.AST]:
 ast27_AST: Final[Type[ast27.AST]] = ast27.AST
 
 
+def _normalize(lineend: AnyStr, value: AnyStr) -> AnyStr:
+    # To normalize, we strip any leading and trailing space from
+    # each line...
+    stripped: List[AnyStr] = [i.strip() for i in value.splitlines()]
+    normalized = lineend.join(stripped)
+    # ...and remove any blank lines at the beginning and end of
+    # the whole string
+    return normalized.strip()
+
+
 def stringify_ast(
     node: Union[ast.AST, ast3.AST, ast27.AST], depth: int = 0
 ) -> Iterator[str]:
@@ -254,14 +264,10 @@ def stringify_ast(
                 and field == "value"
                 and isinstance(value, (str, bytes))
             ):
-                lineend = "\n" if isinstance(value, str) else b"\n"
-                # To normalize, we strip any leading and trailing space from
-                # each line...
-                stripped = [line.strip() for line in value.splitlines()]
-                normalized = lineend.join(stripped)  # type: ignore[attr-defined]
-                # ...and remove any blank lines at the beginning and end of
-                # the whole string
-                normalized = normalized.strip()
+                if isinstance(value, str):
+                    normalized: Union[str, bytes] = _normalize("\n", value)
+                else:
+                    normalized = _normalize(b"\n", value)
             else:
                 normalized = value
             yield f"{'  ' * (depth+2)}{normalized!r},  # {value.__class__.__name__}"

From 092959ff1f9253347b01eeb2d6d72e15bad7e25a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miro=20Hron=C4=8Dok?= <miro@hroncok.cz>
Date: Sat, 25 Dec 2021 04:28:43 +0100
Subject: [PATCH 0399/1034] Support pytest 7 by fixing broken imports (GH-2705)

The tmp_path related changes are not necessary to make pytest 7 work,
but it feels more complete this way.
---
 tests/optional.py      | 11 ++++++++---
 tests/test_ipynb.py    | 22 +++++++++++-----------
 tests/test_no_ipynb.py |  8 ++++----
 3 files changed, 23 insertions(+), 18 deletions(-)

diff --git a/tests/optional.py b/tests/optional.py
index 1cddeeaa576..a4e9441ef1c 100644
--- a/tests/optional.py
+++ b/tests/optional.py
@@ -21,7 +21,12 @@
 from typing import FrozenSet, List, Set, TYPE_CHECKING
 
 import pytest
-from _pytest.store import StoreKey
+
+try:
+    from pytest import StashKey
+except ImportError:
+    # pytest < 7
+    from _pytest.store import StoreKey as StashKey
 
 log = logging.getLogger(__name__)
 
@@ -33,8 +38,8 @@
     from _pytest.nodes import Node
 
 
-ALL_POSSIBLE_OPTIONAL_MARKERS = StoreKey[FrozenSet[str]]()
-ENABLED_OPTIONAL_MARKERS = StoreKey[FrozenSet[str]]()
+ALL_POSSIBLE_OPTIONAL_MARKERS = StashKey[FrozenSet[str]]()
+ENABLED_OPTIONAL_MARKERS = StashKey[FrozenSet[str]]()
 
 
 def pytest_addoption(parser: "Parser") -> None:
diff --git a/tests/test_ipynb.py b/tests/test_ipynb.py
index 141e865815a..fe8d67a7777 100644
--- a/tests/test_ipynb.py
+++ b/tests/test_ipynb.py
@@ -1,3 +1,4 @@
+import pathlib
 import re
 
 from click.testing import CliRunner
@@ -12,7 +13,6 @@
 import pytest
 from black import Mode
 from _pytest.monkeypatch import MonkeyPatch
-from py.path import local
 from tests.util import DATA_DIR
 
 pytestmark = pytest.mark.jupyter
@@ -371,52 +371,52 @@ def test_ipynb_diff_with_no_change() -> None:
 
 
 def test_cache_isnt_written_if_no_jupyter_deps_single(
-    monkeypatch: MonkeyPatch, tmpdir: local
+    monkeypatch: MonkeyPatch, tmp_path: pathlib.Path
 ) -> None:
     # Check that the cache isn't written to if Jupyter dependencies aren't installed.
     jupyter_dependencies_are_installed.cache_clear()
     nb = DATA_DIR / "notebook_trailing_newline.ipynb"
-    tmp_nb = tmpdir / "notebook.ipynb"
+    tmp_nb = tmp_path / "notebook.ipynb"
     with open(nb) as src, open(tmp_nb, "w") as dst:
         dst.write(src.read())
     monkeypatch.setattr(
         "black.jupyter_dependencies_are_installed", lambda verbose, quiet: False
     )
-    result = runner.invoke(main, [str(tmpdir / "notebook.ipynb")])
+    result = runner.invoke(main, [str(tmp_path / "notebook.ipynb")])
     assert "No Python files are present to be formatted. Nothing to do" in result.output
     jupyter_dependencies_are_installed.cache_clear()
     monkeypatch.setattr(
         "black.jupyter_dependencies_are_installed", lambda verbose, quiet: True
     )
-    result = runner.invoke(main, [str(tmpdir / "notebook.ipynb")])
+    result = runner.invoke(main, [str(tmp_path / "notebook.ipynb")])
     assert "reformatted" in result.output
 
 
 def test_cache_isnt_written_if_no_jupyter_deps_dir(
-    monkeypatch: MonkeyPatch, tmpdir: local
+    monkeypatch: MonkeyPatch, tmp_path: pathlib.Path
 ) -> None:
     # Check that the cache isn't written to if Jupyter dependencies aren't installed.
     jupyter_dependencies_are_installed.cache_clear()
     nb = DATA_DIR / "notebook_trailing_newline.ipynb"
-    tmp_nb = tmpdir / "notebook.ipynb"
+    tmp_nb = tmp_path / "notebook.ipynb"
     with open(nb) as src, open(tmp_nb, "w") as dst:
         dst.write(src.read())
     monkeypatch.setattr(
         "black.files.jupyter_dependencies_are_installed", lambda verbose, quiet: False
     )
-    result = runner.invoke(main, [str(tmpdir)])
+    result = runner.invoke(main, [str(tmp_path)])
     assert "No Python files are present to be formatted. Nothing to do" in result.output
     jupyter_dependencies_are_installed.cache_clear()
     monkeypatch.setattr(
         "black.files.jupyter_dependencies_are_installed", lambda verbose, quiet: True
     )
-    result = runner.invoke(main, [str(tmpdir)])
+    result = runner.invoke(main, [str(tmp_path)])
     assert "reformatted" in result.output
 
 
-def test_ipynb_flag(tmpdir: local) -> None:
+def test_ipynb_flag(tmp_path: pathlib.Path) -> None:
     nb = DATA_DIR / "notebook_trailing_newline.ipynb"
-    tmp_nb = tmpdir / "notebook.a_file_extension_which_is_definitely_not_ipynb"
+    tmp_nb = tmp_path / "notebook.a_file_extension_which_is_definitely_not_ipynb"
     with open(nb) as src, open(tmp_nb, "w") as dst:
         dst.write(src.read())
     result = runner.invoke(
diff --git a/tests/test_no_ipynb.py b/tests/test_no_ipynb.py
index bcda2d5369f..b03b8e13f14 100644
--- a/tests/test_no_ipynb.py
+++ b/tests/test_no_ipynb.py
@@ -1,10 +1,10 @@
 import pytest
 import os
+import pathlib
 
 from tests.util import THIS_DIR
 from black import main, jupyter_dependencies_are_installed
 from click.testing import CliRunner
-from _pytest.tmpdir import tmpdir
 
 pytestmark = pytest.mark.no_jupyter
 
@@ -22,14 +22,14 @@ def test_ipynb_diff_with_no_change_single() -> None:
     assert expected_output in result.output
 
 
-def test_ipynb_diff_with_no_change_dir(tmpdir: tmpdir) -> None:
+def test_ipynb_diff_with_no_change_dir(tmp_path: pathlib.Path) -> None:
     jupyter_dependencies_are_installed.cache_clear()
     runner = CliRunner()
     nb = os.path.join("tests", "data", "notebook_trailing_newline.ipynb")
-    tmp_nb = tmpdir / "notebook.ipynb"
+    tmp_nb = tmp_path / "notebook.ipynb"
     with open(nb) as src, open(tmp_nb, "w") as dst:
         dst.write(src.read())
-    result = runner.invoke(main, [str(tmpdir)])
+    result = runner.invoke(main, [str(tmp_path)])
     expected_output = (
         "Skipping .ipynb files as Jupyter dependencies are not installed.\n"
         "You can fix this by running ``pip install black[jupyter]``\n"

From b8df7e4b10bca2d7e478e224502975ec8f220e21 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Thu, 30 Dec 2021 22:17:11 +0100
Subject: [PATCH 0400/1034] Drop upper version bounds on dependencies (GH-2718)

They mostly cause unnecessary trouble.

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 CHANGES.md | 4 ++++
 setup.py   | 4 ++--
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index d5cfb623c9a..cb637d94c11 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -18,6 +18,10 @@
 - Unparenthesized tuples on annotated assignments (e.g
   `values: Tuple[int, ...] = 1, 2, 3`) now implies 3.8+ (#2708)
 
+### Packaging
+
+- All upper version bounds on dependencies have been removed (#2718)
+
 ## 21.12b0
 
 ### _Black_
diff --git a/setup.py b/setup.py
index d314bb283f2..8ff498e4fef 100644
--- a/setup.py
+++ b/setup.py
@@ -99,9 +99,9 @@ def find_python_files(base: Path) -> List[Path]:
     install_requires=[
         "click>=7.1.2",
         "platformdirs>=2",
-        "tomli>=1.1.0,<3.0.0",
+        "tomli>=1.1.0",
         "typed-ast>=1.4.2; python_version < '3.8' and implementation_name == 'cpython'",
-        "pathspec>=0.9.0, <1",
+        "pathspec>=0.9.0",
         "dataclasses>=0.6; python_version < '3.7'",
         "typing_extensions>=3.10.0.0",
         # 3.10.0.1 is broken on at least Python 3.10,

From 4f5268af4f0939fbc0d5ec4fd3d113b40a4c92e9 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Thu, 30 Dec 2021 19:59:53 -0500
Subject: [PATCH 0401/1034] Primer: exclude crashing sqlalchemy file for now
 (GH-2735)

Until we can properly look into and fix it.
-> https://github.com/psf/black/issues/2734
---
 src/black_primer/primer.json | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/src/black_primer/primer.json b/src/black_primer/primer.json
index 2290d1df005..8c966e346d9 100644
--- a/src/black_primer/primer.json
+++ b/src/black_primer/primer.json
@@ -150,7 +150,11 @@
       "py_versions": ["all"]
     },
     "sqlalchemy": {
-      "cli_arguments": ["--experimental-string-processing"],
+      "cli_arguments": [
+        "--experimental-string-processing",
+        "--extend-exclude",
+        "/test/orm/test_relationship_criteria.py"
+      ],
       "expect_formatting_changes": true,
       "git_clone_url": "https://github.com/sqlalchemy/sqlalchemy.git",
       "long_checkout": false,

From 8a84bebcfcabddfd5b82a8cff0b830a745999b6c Mon Sep 17 00:00:00 2001
From: Gunung Pambudi Wibisono <55311527+gunungpw@users.noreply.github.com>
Date: Sun, 2 Jan 2022 10:33:20 +0700
Subject: [PATCH 0402/1034] Documentation: include Wing IDE 8 integrations
 (GH-2733)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Wing IDE 8 now supports autoformatting w/ Black natively 🎉

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 docs/integrations/editors.md | 65 ++++++++++++++++++++++--------------
 1 file changed, 40 insertions(+), 25 deletions(-)

diff --git a/docs/integrations/editors.md b/docs/integrations/editors.md
index 9c279564fa3..5d2f83ace8a 100644
--- a/docs/integrations/editors.md
+++ b/docs/integrations/editors.md
@@ -78,36 +78,51 @@ Options include the following:
 
 ## Wing IDE
 
-Wing supports black via the OS Commands tool, as explained in the Wing documentation on
-[pep8 formatting](https://wingware.com/doc/edit/pep8). The detailed procedure is:
+Wing IDE supports `black` via **Preference Settings** for system wide settings and
+**Project Properties** for per-project or workspace specific settings, as explained in
+the Wing documentation on
+[Auto-Reformatting](https://wingware.com/doc/edit/auto-reformatting). The detailed
+procedure is:
 
-1. Install `black`.
+### Prerequistes
 
-   ```console
-   $ pip install black
-   ```
+- Wing IDE version 8.0+
 
-1. Make sure it runs from the command line, e.g.
+- Install `black`.
 
-   ```console
-   $ black --help
-   ```
+  ```console
+  $ pip install black
+  ```
+
+- Make sure it runs from the command line, e.g.
+
+  ```console
+  $ black --help
+  ```
+
+### Preference Settings
+
+If you want Wing IDE to always reformat with `black` for every project, follow these
+steps:
+
+1. In menubar navigate to `Edit -> Preferences -> Editor -> Reformatting`.
+
+1. Set **Auto-Reformat** from `disable` (default) to `Line after edit` or
+   `Whole files before save`.
+
+1. Set **Reformatter** from `PEP8` (default) to `Black`.
+
+### Project Properties
+
+If you want to just reformat for a specific project and not intervene with Wing IDE
+global setting, follow these steps:
+
+1. In menubar navigate to `Project -> Project Properties -> Options`.
+
+1. Set **Auto-Reformat** from `Use Preferences setting` (default) to `Line after edit`
+   or `Whole files before save`.
 
-1. In Wing IDE, activate the **OS Commands** panel and define the command **black** to
-   execute black on the currently selected file:
-
-   - Use the Tools -> OS Commands menu selection
-   - click on **+** in **OS Commands** -> New: Command line..
-     - Title: black
-     - Command Line: black %s
-     - I/O Encoding: Use Default
-     - Key Binding: F1
-     - [x] Raise OS Commands when executed
-     - [x] Auto-save files before execution
-     - [x] Line mode
-
-1. Select a file in the editor and press **F1** , or whatever key binding you selected
-   in step 3, to reformat the file.
+1. Set **Reformatter** from `Use Preferences setting` (default) to `Black`.
 
 ## Vim
 

From 668bace2aba1589aaa2bfd7c11787d79410bfd05 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Felix=20Hild=C3=A9n?= <felix.hilden@gmail.com>
Date: Fri, 7 Jan 2022 18:19:03 +0200
Subject: [PATCH 0403/1034] Improve CLI reference wording (#2753)

---
 docs/usage_and_configuration/the_basics.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index d002ff0173a..fd39b6c8979 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -26,13 +26,13 @@ python -m black {source_file_or_directory}
 
 ### Command line options
 
-_Black_ has quite a few knobs these days, although _Black_ is opinionated so style
-configuration options are deliberately limited and rarely added. You can list them by
-running `black --help`.
+The CLI options of _Black_ can be displayed by expanding the view below or by running
+`black --help`. While _Black_ has quite a few knobs these days, it is still opinionated
+so style options are deliberately limited and rarely added.
 
 <details>
 
-<summary>Help output</summary>
+<summary>CLI reference</summary>
 
 ```{program-output} black --help
 

From 05e1fbf27d93df36b09c560791ad46c6ce3eb518 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Fri, 7 Jan 2022 11:38:03 -0500
Subject: [PATCH 0404/1034] Stubs: preserve blank line between attributes and
 methods (#2736)

---
 CHANGES.md          |  2 ++
 src/black/lines.py  | 21 +++++++++++++++++----
 tests/data/stub.pyi | 27 +++++++++++++++++++++++++--
 3 files changed, 44 insertions(+), 6 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index cb637d94c11..8bb96bb1f29 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -17,6 +17,8 @@
 - Tuple unpacking on `return` and `yield` constructs now implies 3.8+ (#2700)
 - Unparenthesized tuples on annotated assignments (e.g
   `values: Tuple[int, ...] = 1, 2, 3`) now implies 3.8+ (#2708)
+- For stubs, one blank line between class attributes and methods is now kept if there's
+  at least one pre-existing blank line (#2736)
 
 ### Packaging
 
diff --git a/src/black/lines.py b/src/black/lines.py
index f2bdada008a..d8617d83bf7 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -448,7 +448,14 @@ def _maybe_empty_lines(self, current_line: Line) -> Tuple[int, int]:
         depth = current_line.depth
         while self.previous_defs and self.previous_defs[-1] >= depth:
             if self.is_pyi:
-                before = 0 if depth else 1
+                assert self.previous_line is not None
+                if depth and not current_line.is_def and self.previous_line.is_def:
+                    # Empty lines between attributes and methods should be preserved.
+                    before = min(1, before)
+                elif depth:
+                    before = 0
+                else:
+                    before = 1
             else:
                 if depth:
                     before = 1
@@ -532,9 +539,15 @@ def _maybe_empty_lines_for_class_or_def(
             elif (
                 current_line.is_def or current_line.is_decorator
             ) and not self.previous_line.is_def:
-                # Blank line between a block of functions (maybe with preceding
-                # decorators) and a block of non-functions
-                newlines = 1
+                if not current_line.depth:
+                    # Blank line between a block of functions (maybe with preceding
+                    # decorators) and a block of non-functions
+                    newlines = 1
+                else:
+                    # In classes empty lines between attributes and methods should
+                    # be preserved. The +1 offset is to negate the -1 done later as
+                    # this function is indented.
+                    newlines = min(2, before + 1)
             else:
                 newlines = 0
         else:
diff --git a/tests/data/stub.pyi b/tests/data/stub.pyi
index 94ba852e018..9a246211284 100644
--- a/tests/data/stub.pyi
+++ b/tests/data/stub.pyi
@@ -2,32 +2,55 @@ X: int
 
 def f(): ...
 
+
+class D: 
+    ...
+
+
 class C:
     ...
 
 class B:
-    ...
+    this_lack_of_newline_should_be_kept: int
+    def b(self) -> None: ...
+
+    but_this_newline_should_also_be_kept: int
 
 class A:
+    attr: int
+    attr2: str
+
     def f(self) -> int:
         ...
 
     def g(self) -> str: ...
 
+
+
 def g():
     ...
 
 def h(): ...
 
+
 # output
 X: int
 
 def f(): ...
 
+class D: ...
 class C: ...
-class B: ...
+
+class B:
+    this_lack_of_newline_should_be_kept: int
+    def b(self) -> None: ...
+
+    but_this_newline_should_also_be_kept: int
 
 class A:
+    attr: int
+    attr2: str
+
     def f(self) -> int: ...
     def g(self) -> str: ...
 

From ea4c772746d787a93a0f19ce3cbabfacd8094205 Mon Sep 17 00:00:00 2001
From: Josh Owen <josh.owen@flourish.com>
Date: Fri, 7 Jan 2022 11:50:50 -0500
Subject: [PATCH 0405/1034] Action: Support running in a docker container
 (#2748)

see: https://github.com/actions/runner/issues/716
---
 CHANGES.md | 4 ++++
 action.yml | 2 +-
 2 files changed, 5 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index 8bb96bb1f29..bfecbb7831d 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -24,6 +24,10 @@
 
 - All upper version bounds on dependencies have been removed (#2718)
 
+### Integrations
+
+- Update GitHub action to support containerized runs (#2748)
+
 ## 21.12b0
 
 ### _Black_
diff --git a/action.yml b/action.yml
index ddf07933a3e..dd2de1b62ad 100644
--- a/action.yml
+++ b/action.yml
@@ -38,7 +38,7 @@ runs:
         import subprocess;
         from pathlib import Path;
 
-        MAIN_SCRIPT = Path(r'${{ github.action_path }}') / 'action' / 'main.py';
+        MAIN_SCRIPT = Path(r'${GITHUB_ACTION_PATH}') / 'action' / 'main.py';
 
         proc = subprocess.run([sys.executable, str(MAIN_SCRIPT)]);
         sys.exit(proc.returncode)

From e64949ee69e2a7e7f1d96331f50e801c0979a866 Mon Sep 17 00:00:00 2001
From: Batuhan Taskaya <isidentical@gmail.com>
Date: Fri, 7 Jan 2022 19:51:36 +0300
Subject: [PATCH 0406/1034] Fix call patterns that contain as-expression on the
 kwargs (#2749)

---
 CHANGES.md                            |  2 ++
 src/blib2to3/Grammar.txt              |  2 +-
 tests/data/pattern_matching_extras.py | 14 ++++++++++++++
 3 files changed, 17 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index bfecbb7831d..ec2f5dc52ab 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -12,6 +12,8 @@
   (#2686)
 - Fix cases that contain multiple top-level as-expressions, like `case 1 as a, 2 as b`
   (#2716)
+- Fix call patterns that contain as-expressions with keyword arguments, like
+  `case Foo(bar=baz as quux)` (#2749)
 - No longer color diff headers white as it's unreadable in light themed terminals
   (#2691)
 - Tuple unpacking on `return` and `yield` constructs now implies 3.8+ (#2700)
diff --git a/src/blib2to3/Grammar.txt b/src/blib2to3/Grammar.txt
index 27776a3b65c..cf4799f8abe 100644
--- a/src/blib2to3/Grammar.txt
+++ b/src/blib2to3/Grammar.txt
@@ -187,7 +187,7 @@ arglist: argument (',' argument)* [',']
 argument: ( test [comp_for] |
             test ':=' test |
             test 'as' test |
-            test '=' test |
+            test '=' asexpr_test |
 	    '**' test |
             '*' test )
 
diff --git a/tests/data/pattern_matching_extras.py b/tests/data/pattern_matching_extras.py
index b652d2685ec..9f6907f7575 100644
--- a/tests/data/pattern_matching_extras.py
+++ b/tests/data/pattern_matching_extras.py
@@ -103,3 +103,17 @@ def func(match: case, case: match) -> case:
 
     case 4 as d, (5 as e), (6 | 7 as g), *h:
         pass
+
+
+match bar1:
+    case Foo(aa=Callable() as aa, bb=int()):
+        print(bar1.aa, bar1.bb)
+    case _:
+        print("no match", "\n")
+
+
+match bar1:
+    case Foo(
+        normal=x, perhaps=[list, {an: d, dict: 1.0}] as y, otherwise=something, q=t as u
+    ):
+        pass

From e401b6bb1e1c0ed534bba59d9dc908caf7ba898c Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Mon, 10 Jan 2022 07:16:30 -0500
Subject: [PATCH 0407/1034] Remove Python 2 support (#2740)

*blib2to3's support was left untouched because: 1) I don't want to touch
parsing machinery, and 2) it'll allow us to provide a more useful error
message if someone does try to format Python 2 code.
---
 .github/ISSUE_TEMPLATE/bug_report.md       |  2 +-
 CHANGES.md                                 |  1 +
 README.md                                  |  4 +-
 action/main.py                             |  2 +-
 docs/faq.md                                | 14 +---
 docs/getting_started.md                    |  4 +-
 docs/integrations/github_actions.md        |  4 +-
 docs/the_black_code_style/current_style.md |  3 +-
 pyproject.toml                             |  1 -
 setup.py                                   |  1 -
 src/black/__init__.py                      | 48 +------------
 src/black/linegen.py                       |  9 +--
 src/black/mode.py                          | 42 +----------
 src/black/nodes.py                         | 10 ---
 src/black/numerics.py                      | 15 ++--
 src/black/parsing.py                       | 82 ++++++++--------------
 src/black/strings.py                       | 16 ++---
 src/black_primer/primer.json               | 11 ---
 src/blackd/__init__.py                     |  6 +-
 tests/data/numeric_literals_py2.py         | 16 -----
 tests/data/python2.py                      | 33 ---------
 tests/data/python2_print_function.py       | 16 -----
 tests/data/python2_unicode_literals.py     | 20 ------
 tests/test_black.py                        | 60 ----------------
 tests/test_blackd.py                       |  7 +-
 tests/test_format.py                       | 25 ++-----
 tox.ini                                    | 12 +---
 27 files changed, 73 insertions(+), 391 deletions(-)
 delete mode 100644 tests/data/numeric_literals_py2.py
 delete mode 100644 tests/data/python2.py
 delete mode 100755 tests/data/python2_print_function.py
 delete mode 100644 tests/data/python2_unicode_literals.py

diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
index cb64cf9325d..48aa9291b05 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -16,7 +16,7 @@ current development version. To confirm this, you have three options:
 3. Or run _Black_ on your machine:
    - create a new virtualenv (make sure it's the same Python version);
    - clone this repository;
-   - run `pip install -e .[d,python2]`;
+   - run `pip install -e .[d]`;
    - run `pip install -r test_requirements.txt`
    - make sure it's sane by running `python -m pytest`; and
    - run `black` like you did last time.
diff --git a/CHANGES.md b/CHANGES.md
index ec2f5dc52ab..bfee1b6f259 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -4,6 +4,7 @@
 
 ### _Black_
 
+- **Remove Python 2 support** (#2740)
 - Do not accept bare carriage return line endings in pyproject.toml (#2408)
 - Improve error message for invalid regular expression (#2678)
 - Improve error message when parsing fails during AST safety check by embedding the
diff --git a/README.md b/README.md
index 2adf60a783a..e2b0d17ecfd 100644
--- a/README.md
+++ b/README.md
@@ -40,9 +40,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.6.2+ to
-run. If you want to format Python 2 code as well, install with
-`pip install black[python2]`. If you want to format Jupyter Notebooks, install with
-`pip install black[jupyter]`.
+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:
 
diff --git a/action/main.py b/action/main.py
index fde312553bf..d14b10f421d 100644
--- a/action/main.py
+++ b/action/main.py
@@ -14,7 +14,7 @@
 
 run([sys.executable, "-m", "venv", str(ENV_PATH)], check=True)
 
-req = "black[colorama,python2]"
+req = "black[colorama]"
 if VERSION:
     req += f"=={VERSION}"
 pip_proc = run(
diff --git a/docs/faq.md b/docs/faq.md
index 0a966c99c7f..c7d5ec33ad9 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -75,16 +75,7 @@ disabled-by-default counterpart W504. E203 should be disabled while changes are
 
 ## Does Black support Python 2?
 
-```{warning}
-Python 2 support has been deprecated since 21.10b0.
-
-This support will be dropped in the first stable release, expected for January 2022.
-See [The Black Code Style](the_black_code_style/index.rst) for details.
-```
-
-For formatting, yes! [Install](getting_started.md#installation) with the `python2` extra
-to format Python 2 files too! In terms of running _Black_ though, Python 3.6 or newer is
-required.
+Support for formatting Python 2 code was removed in version 22.0.
 
 ## Why does my linter or typechecker complain after I format my code?
 
@@ -96,8 +87,7 @@ codebase with _Black_.
 
 ## Can I run Black with PyPy?
 
-Yes, there is support for PyPy 3.7 and higher. You cannot format Python 2 files under
-PyPy, because PyPy's inbuilt ast module does not support this.
+Yes, there is support for PyPy 3.7 and higher.
 
 ## Why does Black not detect syntax errors in my code?
 
diff --git a/docs/getting_started.md b/docs/getting_started.md
index c79dc607c4a..987290ac91f 100644
--- a/docs/getting_started.md
+++ b/docs/getting_started.md
@@ -17,9 +17,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.6.2+ to
-run, but can format Python 2 code too. Python 2 support needs the `typed_ast`
-dependency, which be installed with `pip install black[python2]`. If you want to format
-Jupyter Notebooks, install with `pip install black[jupyter]`.
+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:
 
diff --git a/docs/integrations/github_actions.md b/docs/integrations/github_actions.md
index e866a3cc616..c9697cc05de 100644
--- a/docs/integrations/github_actions.md
+++ b/docs/integrations/github_actions.md
@@ -8,8 +8,8 @@ environment. Great for enforcing that your code matches the _Black_ code style.
 This action is known to support all GitHub-hosted runner OSes. In addition, only
 published versions of _Black_ are supported (i.e. whatever is available on PyPI).
 
-Finally, this action installs _Black_ with both the `colorama` and `python2` extras so
-the `--color` flag and formatting Python 2 code are supported.
+Finally, this action installs _Black_ with the `colorama` extra so the `--color` flag
+should work fine.
 
 ## Usage
 
diff --git a/docs/the_black_code_style/current_style.md b/docs/the_black_code_style/current_style.md
index b9ab350cd12..68dff3eef3f 100644
--- a/docs/the_black_code_style/current_style.md
+++ b/docs/the_black_code_style/current_style.md
@@ -281,8 +281,7 @@ removed.
 
 _Black_ standardizes most numeric literals to use lowercase letters for the syntactic
 parts and uppercase letters for the digits themselves: `0xAB` instead of `0XAB` and
-`1e10` instead of `1E10`. Python 2 long literals are styled as `2L` instead of `2l` to
-avoid confusion between `l` and `1`.
+`1e10` instead of `1E10`.
 
 ### Line breaks & binary operators
 
diff --git a/pyproject.toml b/pyproject.toml
index aebbc0da29c..ec617790039 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -29,7 +29,6 @@ build-backend = "setuptools.build_meta"
 [tool.pytest.ini_options]
 # Option below requires `tests/optional.py`
 optional-tests = [
-  "no_python2: run when `python2` extra NOT installed",
   "no_blackd: run when `d` extra NOT installed",
   "no_jupyter: run when `jupyter` extra NOT installed",
 ]
diff --git a/setup.py b/setup.py
index 8ff498e4fef..57632498deb 100644
--- a/setup.py
+++ b/setup.py
@@ -112,7 +112,6 @@ def find_python_files(base: Path) -> List[Path]:
     extras_require={
         "d": ["aiohttp>=3.7.4"],
         "colorama": ["colorama>=0.4.3"],
-        "python2": ["typed-ast>=1.4.3"],
         "uvloop": ["uvloop>=0.15.2"],
         "jupyter": ["ipython>=7.8.0", "tokenize-rt>=3.2.0"],
     },
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 9bc8fc15c49..283c53f0db3 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -1083,20 +1083,8 @@ def f(
     else:
         versions = detect_target_versions(src_node, future_imports=future_imports)
 
-    # TODO: fully drop support and this code hopefully in January 2022 :D
-    if TargetVersion.PY27 in mode.target_versions or versions == {TargetVersion.PY27}:
-        msg = (
-            "DEPRECATION: Python 2 support will be removed in the first stable release "
-            "expected in January 2022."
-        )
-        err(msg, fg="yellow", bold=True)
-
     normalize_fmt_off(src_node)
-    lines = LineGenerator(
-        mode=mode,
-        remove_u_prefix="unicode_literals" in future_imports
-        or supports_feature(versions, Feature.UNICODE_LITERALS),
-    )
+    lines = LineGenerator(mode=mode)
     elt = EmptyLineTracker(is_pyi=mode.is_pyi)
     empty_line = Line(mode=mode)
     after = 0
@@ -1166,14 +1154,6 @@ def get_features_used(  # noqa: C901
             assert isinstance(n, Leaf)
             if "_" in n.value:
                 features.add(Feature.NUMERIC_UNDERSCORES)
-            elif n.value.endswith(("L", "l")):
-                # Python 2: 10L
-                features.add(Feature.LONG_INT_LITERAL)
-            elif len(n.value) >= 2 and n.value[0] == "0" and n.value[1].isdigit():
-                # Python 2: 0123; 00123; ...
-                if not all(char == "0" for char in n.value):
-                    # although we don't want to match 0000 or similar
-                    features.add(Feature.OCTAL_INT_LITERAL)
 
         elif n.type == token.SLASH:
             if n.parent and n.parent.type in {
@@ -1226,32 +1206,6 @@ def get_features_used(  # noqa: C901
         ):
             features.add(Feature.ANN_ASSIGN_EXTENDED_RHS)
 
-        # Python 2 only features (for its deprecation) except for integers, see above
-        elif n.type == syms.print_stmt:
-            features.add(Feature.PRINT_STMT)
-        elif n.type == syms.exec_stmt:
-            features.add(Feature.EXEC_STMT)
-        elif n.type == syms.tfpdef:
-            # def set_position((x, y), value):
-            #     ...
-            features.add(Feature.AUTOMATIC_PARAMETER_UNPACKING)
-        elif n.type == syms.except_clause:
-            # try:
-            #     ...
-            # except Exception, err:
-            #     ...
-            if len(n.children) >= 4:
-                if n.children[-2].type == token.COMMA:
-                    features.add(Feature.COMMA_STYLE_EXCEPT)
-        elif n.type == syms.raise_stmt:
-            # raise Exception, "msg"
-            if len(n.children) >= 4:
-                if n.children[-2].type == token.COMMA:
-                    features.add(Feature.COMMA_STYLE_RAISE)
-        elif n.type == token.BACKQUOTE:
-            # `i'm surprised this ever existed`
-            features.add(Feature.BACKQUOTE_REPR)
-
     return features
 
 
diff --git a/src/black/linegen.py b/src/black/linegen.py
index dc238c3aee4..6008c773f94 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -48,9 +48,8 @@ class LineGenerator(Visitor[Line]):
     in ways that will no longer stringify to valid Python code on the tree.
     """
 
-    def __init__(self, mode: Mode, remove_u_prefix: bool = False) -> None:
+    def __init__(self, mode: Mode) -> None:
         self.mode = mode
-        self.remove_u_prefix = remove_u_prefix
         self.current_line: Line
         self.__post_init__()
 
@@ -92,9 +91,7 @@ def visit_default(self, node: LN) -> Iterator[Line]:
 
             normalize_prefix(node, inside_brackets=any_open_brackets)
             if self.mode.string_normalization and node.type == token.STRING:
-                node.value = normalize_string_prefix(
-                    node.value, remove_u_prefix=self.remove_u_prefix
-                )
+                node.value = normalize_string_prefix(node.value)
                 node.value = normalize_string_quotes(node.value)
             if node.type == token.NUMBER:
                 normalize_numeric_literal(node)
@@ -236,7 +233,7 @@ def visit_STRING(self, leaf: Leaf) -> Iterator[Line]:
         if is_docstring(leaf) and "\\\n" not in leaf.value:
             # We're ignoring docstrings with backslash newline escapes because changing
             # indentation of those changes the AST representation of the code.
-            docstring = normalize_string_prefix(leaf.value, self.remove_u_prefix)
+            docstring = normalize_string_prefix(leaf.value)
             prefix = get_string_prefix(docstring)
             docstring = docstring[len(prefix) :]  # Remove the prefix
             quote_char = docstring[0]
diff --git a/src/black/mode.py b/src/black/mode.py
index bd4428add66..5e04525cfc9 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -20,7 +20,6 @@
 
 
 class TargetVersion(Enum):
-    PY27 = 2
     PY33 = 3
     PY34 = 4
     PY35 = 5
@@ -30,13 +29,8 @@ class TargetVersion(Enum):
     PY39 = 9
     PY310 = 10
 
-    def is_python2(self) -> bool:
-        return self is TargetVersion.PY27
-
 
 class Feature(Enum):
-    # All string literals are unicode
-    UNICODE_LITERALS = 1
     F_STRINGS = 2
     NUMERIC_UNDERSCORES = 3
     TRAILING_COMMA_IN_CALL = 4
@@ -56,16 +50,6 @@ class Feature(Enum):
     # __future__ flags
     FUTURE_ANNOTATIONS = 51
 
-    # temporary for Python 2 deprecation
-    PRINT_STMT = 200
-    EXEC_STMT = 201
-    AUTOMATIC_PARAMETER_UNPACKING = 202
-    COMMA_STYLE_EXCEPT = 203
-    COMMA_STYLE_RAISE = 204
-    LONG_INT_LITERAL = 205
-    OCTAL_INT_LITERAL = 206
-    BACKQUOTE_REPR = 207
-
 
 FUTURE_FLAG_TO_FEATURE: Final = {
     "annotations": Feature.FUTURE_ANNOTATIONS,
@@ -73,26 +57,10 @@ class Feature(Enum):
 
 
 VERSION_TO_FEATURES: Dict[TargetVersion, Set[Feature]] = {
-    TargetVersion.PY27: {
-        Feature.ASYNC_IDENTIFIERS,
-        Feature.PRINT_STMT,
-        Feature.EXEC_STMT,
-        Feature.AUTOMATIC_PARAMETER_UNPACKING,
-        Feature.COMMA_STYLE_EXCEPT,
-        Feature.COMMA_STYLE_RAISE,
-        Feature.LONG_INT_LITERAL,
-        Feature.OCTAL_INT_LITERAL,
-        Feature.BACKQUOTE_REPR,
-    },
-    TargetVersion.PY33: {Feature.UNICODE_LITERALS, Feature.ASYNC_IDENTIFIERS},
-    TargetVersion.PY34: {Feature.UNICODE_LITERALS, Feature.ASYNC_IDENTIFIERS},
-    TargetVersion.PY35: {
-        Feature.UNICODE_LITERALS,
-        Feature.TRAILING_COMMA_IN_CALL,
-        Feature.ASYNC_IDENTIFIERS,
-    },
+    TargetVersion.PY33: {Feature.ASYNC_IDENTIFIERS},
+    TargetVersion.PY34: {Feature.ASYNC_IDENTIFIERS},
+    TargetVersion.PY35: {Feature.TRAILING_COMMA_IN_CALL, Feature.ASYNC_IDENTIFIERS},
     TargetVersion.PY36: {
-        Feature.UNICODE_LITERALS,
         Feature.F_STRINGS,
         Feature.NUMERIC_UNDERSCORES,
         Feature.TRAILING_COMMA_IN_CALL,
@@ -100,7 +68,6 @@ class Feature(Enum):
         Feature.ASYNC_IDENTIFIERS,
     },
     TargetVersion.PY37: {
-        Feature.UNICODE_LITERALS,
         Feature.F_STRINGS,
         Feature.NUMERIC_UNDERSCORES,
         Feature.TRAILING_COMMA_IN_CALL,
@@ -109,7 +76,6 @@ class Feature(Enum):
         Feature.FUTURE_ANNOTATIONS,
     },
     TargetVersion.PY38: {
-        Feature.UNICODE_LITERALS,
         Feature.F_STRINGS,
         Feature.NUMERIC_UNDERSCORES,
         Feature.TRAILING_COMMA_IN_CALL,
@@ -122,7 +88,6 @@ class Feature(Enum):
         Feature.ANN_ASSIGN_EXTENDED_RHS,
     },
     TargetVersion.PY39: {
-        Feature.UNICODE_LITERALS,
         Feature.F_STRINGS,
         Feature.NUMERIC_UNDERSCORES,
         Feature.TRAILING_COMMA_IN_CALL,
@@ -136,7 +101,6 @@ class Feature(Enum):
         Feature.ANN_ASSIGN_EXTENDED_RHS,
     },
     TargetVersion.PY310: {
-        Feature.UNICODE_LITERALS,
         Feature.F_STRINGS,
         Feature.NUMERIC_UNDERSCORES,
         Feature.TRAILING_COMMA_IN_CALL,
diff --git a/src/black/nodes.py b/src/black/nodes.py
index 75a23474024..74dfa896295 100644
--- a/src/black/nodes.py
+++ b/src/black/nodes.py
@@ -259,16 +259,6 @@ def whitespace(leaf: Leaf, *, complex_subscript: bool) -> str:  # noqa: C901
         ):
             return NO
 
-        elif (
-            prevp.type == token.RIGHTSHIFT
-            and prevp.parent
-            and prevp.parent.type == syms.shift_expr
-            and prevp.prev_sibling
-            and is_name_token(prevp.prev_sibling)
-            and prevp.prev_sibling.value == "print"
-        ):
-            # Python 2 print chevron
-            return NO
         elif prevp.type == token.AT and p.parent and p.parent.type == syms.decorator:
             # no space in decorators
             return NO
diff --git a/src/black/numerics.py b/src/black/numerics.py
index cb1c83e7b78..879e5b2cf36 100644
--- a/src/black/numerics.py
+++ b/src/black/numerics.py
@@ -25,13 +25,10 @@ def format_scientific_notation(text: str) -> str:
     return f"{before}e{sign}{after}"
 
 
-def format_long_or_complex_number(text: str) -> str:
-    """Formats a long or complex string like `10L` or `10j`"""
+def format_complex_number(text: str) -> str:
+    """Formats a complex string like `10j`"""
     number = text[:-1]
     suffix = text[-1]
-    # Capitalize in "2L" because "l" looks too similar to "1".
-    if suffix == "l":
-        suffix = "L"
     return f"{format_float_or_int_string(number)}{suffix}"
 
 
@@ -47,9 +44,7 @@ def format_float_or_int_string(text: str) -> str:
 def normalize_numeric_literal(leaf: Leaf) -> None:
     """Normalizes numeric (float, int, and complex) literals.
 
-    All letters used in the representation are normalized to lowercase (except
-    in Python 2 long literals).
-    """
+    All letters used in the representation are normalized to lowercase."""
     text = leaf.value.lower()
     if text.startswith(("0o", "0b")):
         # Leave octal and binary literals alone.
@@ -58,8 +53,8 @@ def normalize_numeric_literal(leaf: Leaf) -> None:
         text = format_hex(text)
     elif "e" in text:
         text = format_scientific_notation(text)
-    elif text.endswith(("j", "l")):
-        text = format_long_or_complex_number(text)
+    elif text.endswith("j"):
+        text = format_complex_number(text)
     else:
         text = format_float_or_int_string(text)
     leaf.value = text
diff --git a/src/black/parsing.py b/src/black/parsing.py
index 76e9de023c7..13fa67ee84d 100644
--- a/src/black/parsing.py
+++ b/src/black/parsing.py
@@ -4,7 +4,7 @@
 import ast
 import platform
 import sys
-from typing import Any, AnyStr, Iterable, Iterator, List, Set, Tuple, Type, Union
+from typing import Any, Iterable, Iterator, List, Set, Tuple, Type, Union
 
 if sys.version_info < (3, 8):
     from typing_extensions import Final
@@ -23,12 +23,11 @@
 from black.nodes import syms
 
 ast3: Any
-ast27: Any
 
 _IS_PYPY = platform.python_implementation() == "PyPy"
 
 try:
-    from typed_ast import ast3, ast27
+    from typed_ast import ast3
 except ImportError:
     # Either our python version is too low, or we're on pypy
     if sys.version_info < (3, 7) or (sys.version_info < (3, 8) and not _IS_PYPY):
@@ -40,12 +39,11 @@
         )
         sys.exit(1)
     else:
-        ast3 = ast27 = ast
+        ast3 = ast
 
 
-PY310_HINT: Final[
-    str
-] = "Consider using --target-version py310 to parse Python 3.10 code."
+PY310_HINT: Final = "Consider using --target-version py310 to parse Python 3.10 code."
+PY2_HINT: Final = "Python 2 support was removed in version 22.0."
 
 
 class InvalidInput(ValueError):
@@ -60,22 +58,8 @@ def get_grammars(target_versions: Set[TargetVersion]) -> List[Grammar]:
             pygram.python_grammar_no_print_statement_no_exec_statement_async_keywords,
             # Python 3.0-3.6
             pygram.python_grammar_no_print_statement_no_exec_statement,
-            # Python 2.7 with future print_function import
-            pygram.python_grammar_no_print_statement,
-            # Python 2.7
-            pygram.python_grammar,
         ]
 
-    if all(version.is_python2() for version in target_versions):
-        # Python 2-only code, so try Python 2 grammars.
-        return [
-            # Python 2.7 with future print_function import
-            pygram.python_grammar_no_print_statement,
-            # Python 2.7
-            pygram.python_grammar,
-        ]
-
-    # Python 3-compatible code, so only try Python 3 grammar.
     grammars = []
     if supports_feature(target_versions, Feature.PATTERN_MATCHING):
         # Python 3.10+
@@ -129,6 +113,14 @@ def lib2to3_parse(src_txt: str, target_versions: Iterable[TargetVersion] = ()) -
             original_msg = exc.args[0]
             msg = f"{original_msg}\n{PY310_HINT}"
             raise InvalidInput(msg) from None
+
+        if matches_grammar(src_txt, pygram.python_grammar) or matches_grammar(
+            src_txt, pygram.python_grammar_no_print_statement
+        ):
+            original_msg = exc.args[0]
+            msg = f"{original_msg}\n{PY2_HINT}"
+            raise InvalidInput(msg) from None
+
         raise exc from None
 
     if isinstance(result, Leaf):
@@ -154,7 +146,7 @@ def lib2to3_unparse(node: Node) -> str:
 
 def parse_single_version(
     src: str, version: Tuple[int, int]
-) -> Union[ast.AST, ast3.AST, ast27.AST]:
+) -> Union[ast.AST, ast3.AST]:
     filename = "<unknown>"
     # typed_ast is needed because of feature version limitations in the builtin ast
     if sys.version_info >= (3, 8) and version >= (3,):
@@ -164,18 +156,13 @@ def parse_single_version(
             return ast3.parse(src, filename)
         else:
             return ast3.parse(src, filename, feature_version=version[1])
-    elif version == (2, 7):
-        return ast27.parse(src)
     raise AssertionError("INTERNAL ERROR: Tried parsing unsupported Python version!")
 
 
-def parse_ast(src: str) -> Union[ast.AST, ast3.AST, ast27.AST]:
+def parse_ast(src: str) -> Union[ast.AST, ast3.AST]:
     # TODO: support Python 4+ ;)
     versions = [(3, minor) for minor in range(3, sys.version_info[1] + 1)]
 
-    if ast27.__name__ != "ast":
-        versions.append((2, 7))
-
     first_error = ""
     for version in sorted(versions, reverse=True):
         try:
@@ -188,22 +175,19 @@ def parse_ast(src: str) -> Union[ast.AST, ast3.AST, ast27.AST]:
 
 
 ast3_AST: Final[Type[ast3.AST]] = ast3.AST
-ast27_AST: Final[Type[ast27.AST]] = ast27.AST
 
 
-def _normalize(lineend: AnyStr, value: AnyStr) -> AnyStr:
+def _normalize(lineend: str, value: str) -> str:
     # To normalize, we strip any leading and trailing space from
     # each line...
-    stripped: List[AnyStr] = [i.strip() for i in value.splitlines()]
+    stripped: List[str] = [i.strip() for i in value.splitlines()]
     normalized = lineend.join(stripped)
     # ...and remove any blank lines at the beginning and end of
     # the whole string
     return normalized.strip()
 
 
-def stringify_ast(
-    node: Union[ast.AST, ast3.AST, ast27.AST], depth: int = 0
-) -> Iterator[str]:
+def stringify_ast(node: Union[ast.AST, ast3.AST], depth: int = 0) -> Iterator[str]:
     """Simple visitor generating strings to compare ASTs by content."""
 
     node = fixup_ast_constants(node)
@@ -215,7 +199,7 @@ def stringify_ast(
         # TypeIgnore will not be present using pypy < 3.8, so need for this
         if not (_IS_PYPY and sys.version_info < (3, 8)):
             # TypeIgnore has only one field 'lineno' which breaks this comparison
-            type_ignore_classes = (ast3.TypeIgnore, ast27.TypeIgnore)
+            type_ignore_classes = (ast3.TypeIgnore,)
             if sys.version_info >= (3, 8):
                 type_ignore_classes += (ast.TypeIgnore,)
             if isinstance(node, type_ignore_classes):
@@ -234,40 +218,34 @@ def stringify_ast(
                 # parentheses and they change the AST.
                 if (
                     field == "targets"
-                    and isinstance(node, (ast.Delete, ast3.Delete, ast27.Delete))
-                    and isinstance(item, (ast.Tuple, ast3.Tuple, ast27.Tuple))
+                    and isinstance(node, (ast.Delete, ast3.Delete))
+                    and isinstance(item, (ast.Tuple, ast3.Tuple))
                 ):
                     for item in item.elts:
                         yield from stringify_ast(item, depth + 2)
 
-                elif isinstance(item, (ast.AST, ast3.AST, ast27.AST)):
+                elif isinstance(item, (ast.AST, ast3.AST)):
                     yield from stringify_ast(item, depth + 2)
 
         # Note that we are referencing the typed-ast ASTs via global variables and not
         # direct module attribute accesses because that breaks mypyc. It's probably
-        # something to do with the ast3 / ast27 variables being marked as Any leading
+        # something to do with the ast3 variables being marked as Any leading
         # mypy to think this branch is always taken, leaving the rest of the code
         # unanalyzed. Tighting up the types for the typed-ast AST types avoids the
         # mypyc crash.
-        elif isinstance(value, (ast.AST, ast3_AST, ast27_AST)):
+        elif isinstance(value, (ast.AST, ast3_AST)):
             yield from stringify_ast(value, depth + 2)
 
         else:
             # Constant strings may be indented across newlines, if they are
             # docstrings; fold spaces after newlines when comparing. Similarly,
             # trailing and leading space may be removed.
-            # Note that when formatting Python 2 code, at least with Windows
-            # line-endings, docstrings can end up here as bytes instead of
-            # str so make sure that we handle both cases.
             if (
                 isinstance(node, ast.Constant)
                 and field == "value"
-                and isinstance(value, (str, bytes))
+                and isinstance(value, str)
             ):
-                if isinstance(value, str):
-                    normalized: Union[str, bytes] = _normalize("\n", value)
-                else:
-                    normalized = _normalize(b"\n", value)
+                normalized = _normalize("\n", value)
             else:
                 normalized = value
             yield f"{'  ' * (depth+2)}{normalized!r},  # {value.__class__.__name__}"
@@ -275,14 +253,12 @@ def stringify_ast(
     yield f"{'  ' * depth})  # /{node.__class__.__name__}"
 
 
-def fixup_ast_constants(
-    node: Union[ast.AST, ast3.AST, ast27.AST]
-) -> Union[ast.AST, ast3.AST, ast27.AST]:
+def fixup_ast_constants(node: Union[ast.AST, ast3.AST]) -> Union[ast.AST, ast3.AST]:
     """Map ast nodes deprecated in 3.8 to Constant."""
-    if isinstance(node, (ast.Str, ast3.Str, ast27.Str, ast.Bytes, ast3.Bytes)):
+    if isinstance(node, (ast.Str, ast3.Str, ast.Bytes, ast3.Bytes)):
         return ast.Constant(value=node.s)
 
-    if isinstance(node, (ast.Num, ast3.Num, ast27.Num)):
+    if isinstance(node, (ast.Num, ast3.Num)):
         return ast.Constant(value=node.n)
 
     if isinstance(node, (ast.NameConstant, ast3.NameConstant)):
diff --git a/src/black/strings.py b/src/black/strings.py
index 06a5da01f0c..262c2ba4313 100644
--- a/src/black/strings.py
+++ b/src/black/strings.py
@@ -138,17 +138,17 @@ def assert_is_leaf_string(string: str) -> None:
     ), f"{set(string[:quote_idx])} is NOT a subset of {set(STRING_PREFIX_CHARS)}."
 
 
-def normalize_string_prefix(s: str, remove_u_prefix: bool = False) -> str:
-    """Make all string prefixes lowercase.
-
-    If remove_u_prefix is given, also removes any u prefix from the string.
-    """
+def normalize_string_prefix(s: str) -> str:
+    """Make all string prefixes lowercase."""
     match = STRING_PREFIX_RE.match(s)
     assert match is not None, f"failed to match string {s!r}"
     orig_prefix = match.group(1)
-    new_prefix = orig_prefix.replace("F", "f").replace("B", "b").replace("U", "u")
-    if remove_u_prefix:
-        new_prefix = new_prefix.replace("u", "")
+    new_prefix = (
+        orig_prefix.replace("F", "f")
+        .replace("B", "b")
+        .replace("U", "")
+        .replace("u", "")
+    )
     return f"{new_prefix}{match.group(2)}"
 
 
diff --git a/src/black_primer/primer.json b/src/black_primer/primer.json
index 8c966e346d9..d8e13edeb06 100644
--- a/src/black_primer/primer.json
+++ b/src/black_primer/primer.json
@@ -149,17 +149,6 @@
       "long_checkout": false,
       "py_versions": ["all"]
     },
-    "sqlalchemy": {
-      "cli_arguments": [
-        "--experimental-string-processing",
-        "--extend-exclude",
-        "/test/orm/test_relationship_criteria.py"
-      ],
-      "expect_formatting_changes": true,
-      "git_clone_url": "https://github.com/sqlalchemy/sqlalchemy.git",
-      "long_checkout": false,
-      "py_versions": ["all"]
-    },
     "tox": {
       "cli_arguments": ["--experimental-string-processing"],
       "expect_formatting_changes": true,
diff --git a/src/blackd/__init__.py b/src/blackd/__init__.py
index cc966404a74..0463f169e19 100644
--- a/src/blackd/__init__.py
+++ b/src/blackd/__init__.py
@@ -174,10 +174,8 @@ def parse_python_variant_header(value: str) -> Tuple[bool, Set[black.TargetVersi
                     raise InvalidVariantHeader("major version must be 2 or 3")
                 if len(rest) > 0:
                     minor = int(rest[0])
-                    if major == 2 and minor != 7:
-                        raise InvalidVariantHeader(
-                            "minor version must be 7 for Python 2"
-                        )
+                    if major == 2:
+                        raise InvalidVariantHeader("Python 2 is not supported")
                 else:
                     # Default to lowest supported minor version.
                     minor = 7 if major == 2 else 3
diff --git a/tests/data/numeric_literals_py2.py b/tests/data/numeric_literals_py2.py
deleted file mode 100644
index 8f85c43f265..00000000000
--- a/tests/data/numeric_literals_py2.py
+++ /dev/null
@@ -1,16 +0,0 @@
-#!/usr/bin/env python2.7
-
-x = 123456789L
-x = 123456789l
-x = 123456789
-x = 0xb1acc
-
-# output
-
-
-#!/usr/bin/env python2.7
-
-x = 123456789L
-x = 123456789L
-x = 123456789
-x = 0xB1ACC
diff --git a/tests/data/python2.py b/tests/data/python2.py
deleted file mode 100644
index 4a22f46de42..00000000000
--- a/tests/data/python2.py
+++ /dev/null
@@ -1,33 +0,0 @@
-#!/usr/bin/env python2
-
-import sys
-
-print >> sys.stderr , "Warning:" ,
-print >> sys.stderr , "this is a blast from the past."
-print >> sys.stderr , "Look, a repr:", `sys`
-
-
-def function((_globals, _locals)):
-    exec ur"print 'hi from exec!'" in _globals, _locals
-
-
-function((globals(), locals()))
-
-
-# output
-
-
-#!/usr/bin/env python2
-
-import sys
-
-print >>sys.stderr, "Warning:",
-print >>sys.stderr, "this is a blast from the past."
-print >>sys.stderr, "Look, a repr:", ` sys `
-
-
-def function((_globals, _locals)):
-    exec ur"print 'hi from exec!'" in _globals, _locals
-
-
-function((globals(), locals()))
diff --git a/tests/data/python2_print_function.py b/tests/data/python2_print_function.py
deleted file mode 100755
index 81b8d8a70ce..00000000000
--- a/tests/data/python2_print_function.py
+++ /dev/null
@@ -1,16 +0,0 @@
-#!/usr/bin/env python2
-from __future__ import print_function
-
-print('hello')
-print(u'hello')
-print(a, file=sys.stderr)
-
-# output
-
-
-#!/usr/bin/env python2
-from __future__ import print_function
-
-print("hello")
-print(u"hello")
-print(a, file=sys.stderr)
diff --git a/tests/data/python2_unicode_literals.py b/tests/data/python2_unicode_literals.py
deleted file mode 100644
index 2fe70392af6..00000000000
--- a/tests/data/python2_unicode_literals.py
+++ /dev/null
@@ -1,20 +0,0 @@
-#!/usr/bin/env python2
-from __future__ import unicode_literals as _unicode_literals
-from __future__ import absolute_import
-from __future__ import print_function as lol, with_function
-
-u'hello'
-U"hello"
-Ur"hello"
-
-# output
-
-
-#!/usr/bin/env python2
-from __future__ import unicode_literals as _unicode_literals
-from __future__ import absolute_import
-from __future__ import print_function as lol, with_function
-
-"hello"
-"hello"
-r"hello"
diff --git a/tests/test_black.py b/tests/test_black.py
index 628647ed977..5be4ae8533c 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -724,24 +724,15 @@ def test_lib2to3_parse(self) -> None:
 
         straddling = "x + y"
         black.lib2to3_parse(straddling)
-        black.lib2to3_parse(straddling, {TargetVersion.PY27})
         black.lib2to3_parse(straddling, {TargetVersion.PY36})
-        black.lib2to3_parse(straddling, {TargetVersion.PY27, TargetVersion.PY36})
 
         py2_only = "print x"
-        black.lib2to3_parse(py2_only)
-        black.lib2to3_parse(py2_only, {TargetVersion.PY27})
         with self.assertRaises(black.InvalidInput):
             black.lib2to3_parse(py2_only, {TargetVersion.PY36})
-        with self.assertRaises(black.InvalidInput):
-            black.lib2to3_parse(py2_only, {TargetVersion.PY27, TargetVersion.PY36})
 
         py3_only = "exec(x, end=y)"
         black.lib2to3_parse(py3_only)
-        with self.assertRaises(black.InvalidInput):
-            black.lib2to3_parse(py3_only, {TargetVersion.PY27})
         black.lib2to3_parse(py3_only, {TargetVersion.PY36})
-        black.lib2to3_parse(py3_only, {TargetVersion.PY27, TargetVersion.PY36})
 
     def test_get_features_used_decorator(self) -> None:
         # Test the feature detection of new decorator syntax
@@ -1436,27 +1427,6 @@ def test_bpo_2142_workaround(self) -> None:
         actual = diff_header.sub(DETERMINISTIC_HEADER, actual)
         self.assertEqual(actual, expected)
 
-    @pytest.mark.python2
-    def test_docstring_reformat_for_py27(self) -> None:
-        """
-        Check that stripping trailing whitespace from Python 2 docstrings
-        doesn't trigger a "not equivalent to source" error
-        """
-        source = (
-            b'def foo():\r\n    """Testing\r\n    Testing """\r\n    print "Foo"\r\n'
-        )
-        expected = 'def foo():\n    """Testing\n    Testing"""\n    print "Foo"\n'
-
-        result = BlackRunner().invoke(
-            black.main,
-            ["-", "-q", "--target-version=py27"],
-            input=BytesIO(source),
-        )
-
-        self.assertEqual(result.exit_code, 0)
-        actual = result.stdout
-        self.assertFormatEqual(actual, expected)
-
     @staticmethod
     def compare_results(
         result: click.testing.Result, expected_value: str, expected_exit_code: int
@@ -2086,36 +2056,6 @@ def test_get_sources_with_stdin_filename_and_force_exclude(self) -> None:
         )
 
 
-@pytest.mark.python2
-@pytest.mark.parametrize("explicit", [True, False], ids=["explicit", "autodetection"])
-def test_python_2_deprecation_with_target_version(explicit: bool) -> None:
-    args = [
-        "--config",
-        str(THIS_DIR / "empty.toml"),
-        str(DATA_DIR / "python2.py"),
-        "--check",
-    ]
-    if explicit:
-        args.append("--target-version=py27")
-    with cache_dir():
-        result = BlackRunner().invoke(black.main, args)
-    assert "DEPRECATION: Python 2 support will be removed" in result.stderr
-
-
-@pytest.mark.python2
-def test_python_2_deprecation_autodetection_extended() -> None:
-    # this test has a similar construction to test_get_features_used_decorator
-    python2, non_python2 = read_data("python2_detection")
-    for python2_case in python2.split("###"):
-        node = black.lib2to3_parse(python2_case)
-        assert black.detect_target_versions(node) == {TargetVersion.PY27}, python2_case
-    for non_python2_case in non_python2.split("###"):
-        node = black.lib2to3_parse(non_python2_case)
-        assert black.detect_target_versions(node) != {
-            TargetVersion.PY27
-        }, non_python2_case
-
-
 try:
     with open(black.__file__, "r", encoding="utf-8") as _bf:
         black_source_lines = _bf.readlines()
diff --git a/tests/test_blackd.py b/tests/test_blackd.py
index cc750b40567..37431fcad00 100644
--- a/tests/test_blackd.py
+++ b/tests/test_blackd.py
@@ -77,6 +77,9 @@ async def check(header_value: str, expected_status: int = 400) -> None:
         await check("ruby3.5")
         await check("pyi3.6")
         await check("py1.5")
+        await check("2")
+        await check("2.7")
+        await check("py2.7")
         await check("2.8")
         await check("py2.8")
         await check("3.0")
@@ -137,10 +140,6 @@ async def check(header_value: str, expected_status: int) -> None:
         await check("py36,py37", 200)
         await check("36", 200)
         await check("3.6.4", 200)
-
-        await check("2", 204)
-        await check("2.7", 204)
-        await check("py2.7", 204)
         await check("3.4", 204)
         await check("py3.4", 204)
         await check("py34,py36", 204)
diff --git a/tests/test_format.py b/tests/test_format.py
index 30099aaf1bc..6651272a87c 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -55,12 +55,6 @@
     "tupleassign",
 ]
 
-SIMPLE_CASES_PY2 = [
-    "numeric_literals_py2",
-    "python2",
-    "python2_unicode_literals",
-]
-
 EXPERIMENTAL_STRING_PROCESSING_CASES = [
     "cantfit",
     "comments7",
@@ -134,12 +128,6 @@ def check_file(filename: str, mode: black.Mode, *, data: bool = True) -> None:
     assert_format(source, expected, mode, fast=False)
 
 
-@pytest.mark.parametrize("filename", SIMPLE_CASES_PY2)
-@pytest.mark.python2
-def test_simple_format_py2(filename: str) -> None:
-    check_file(filename, DEFAULT_MODE)
-
-
 @pytest.mark.parametrize("filename", SIMPLE_CASES)
 def test_simple_format(filename: str) -> None:
     check_file(filename, DEFAULT_MODE)
@@ -219,6 +207,12 @@ def test_patma_hint() -> None:
     exc_info.match(black.parsing.PY310_HINT)
 
 
+def test_python_2_hint() -> None:
+    with pytest.raises(black.parsing.InvalidInput) as exc_info:
+        assert_format("print 'daylily'", "print 'daylily'")
+    exc_info.match(black.parsing.PY2_HINT)
+
+
 def test_docstring_no_string_normalization() -> None:
     """Like test_docstring but with string normalization off."""
     source, expected = read_data("docstring_no_string_normalization")
@@ -245,13 +239,6 @@ def test_numeric_literals_ignoring_underscores() -> None:
     assert_format(source, expected, mode)
 
 
-@pytest.mark.python2
-def test_python2_print_function() -> None:
-    source, expected = read_data("python2_print_function")
-    mode = replace(DEFAULT_MODE, target_versions={black.TargetVersion.PY27})
-    assert_format(source, expected, mode)
-
-
 def test_stub() -> None:
     mode = replace(DEFAULT_MODE, is_pyi=True)
     source, expected = read_data("stub.pyi")
diff --git a/tox.ini b/tox.ini
index 683a5439ea9..090dc522cad 100644
--- a/tox.ini
+++ b/tox.ini
@@ -5,7 +5,7 @@ envlist = {,ci-}py{36,37,38,39,310,py3},fuzz
 setenv = PYTHONPATH = {toxinidir}/src
 skip_install = True
 # We use `recreate=True` because otherwise, on the second run of `tox -e py`,
-# the `no_python2` tests would run with the Python2 extra dependencies installed.
+# the `no_jupyter` tests would run with the jupyter extra dependencies installed.
 # See https://github.com/psf/black/issues/2367.
 recreate = True
 deps =
@@ -15,15 +15,9 @@ deps =
 commands =
     pip install -e .[d]
     coverage erase
-    pytest tests --run-optional no_python2 \
-        --run-optional no_jupyter \
+    pytest tests --run-optional no_jupyter \
         !ci: --numprocesses auto \
         --cov {posargs}
-    pip install -e .[d,python2]
-    pytest tests --run-optional python2 \
-        --run-optional no_jupyter \
-        !ci: --numprocesses auto \
-        --cov --cov-append {posargs}
     pip install -e .[jupyter]
     pytest tests --run-optional jupyter \
         -m jupyter \
@@ -43,7 +37,7 @@ deps =
 commands =
     pip install -e .[d]
     coverage erase
-    pytest tests --run-optional no_python2 \
+    pytest tests \
         --run-optional no_jupyter \
         !ci: --numprocesses auto \
         ci: --numprocesses 1 \

From 521d1b8129c2d83b4ab49270fe7473802259c2a2 Mon Sep 17 00:00:00 2001
From: Shivansh-007 <shivansh-007@outlook.com>
Date: Mon, 10 Jan 2022 19:28:35 +0530
Subject: [PATCH 0408/1034] Enhance `--verbose` (#2526)

Black would now echo the location that it determined as the root path
for the project if `--verbose` is enabled by the user, according to
which it chooses the SRC paths, i.e. the absolute path of the project
is `{root}/{src}`.

Closes #1880
---
 CHANGES.md            |  2 ++
 src/black/__init__.py | 42 +++++++++++++++++++++++++++++++++++-------
 src/black/files.py    | 28 +++++++++++++++++++---------
 tests/test_black.py   | 34 +++++++++++++++++++++++-----------
 4 files changed, 79 insertions(+), 27 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index bfee1b6f259..f6e8343ed00 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -22,6 +22,8 @@
   `values: Tuple[int, ...] = 1, 2, 3`) now implies 3.8+ (#2708)
 - For stubs, one blank line between class attributes and methods is now kept if there's
   at least one pre-existing blank line (#2736)
+- Verbose mode also now describes how a project root was discovered and which paths will
+  be formatted. (#2526)
 
 ### Packaging
 
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 283c53f0db3..cfa2c7663fe 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -31,6 +31,7 @@
 )
 
 import click
+from click.core import ParameterSource
 from dataclasses import replace
 from mypy_extensions import mypyc_attr
 
@@ -411,8 +412,37 @@ def main(
     config: Optional[str],
 ) -> None:
     """The uncompromising code formatter."""
-    if config and verbose:
-        out(f"Using configuration from {config}.", bold=False, fg="blue")
+    ctx.ensure_object(dict)
+    root, method = find_project_root(src) if code is None else (None, None)
+    ctx.obj["root"] = root
+
+    if verbose:
+        if root:
+            out(
+                f"Identified `{root}` as project root containing a {method}.",
+                fg="blue",
+            )
+
+            normalized = [
+                (normalize_path_maybe_ignore(Path(source), root), source)
+                for source in src
+            ]
+            srcs_string = ", ".join(
+                [
+                    f'"{_norm}"'
+                    if _norm
+                    else f'\033[31m"{source} (skipping - invalid)"\033[34m'
+                    for _norm, source in normalized
+                ]
+            )
+            out(f"Sources to be formatted: {srcs_string}", fg="blue")
+
+        if config:
+            config_source = ctx.get_parameter_source("config")
+            if config_source in (ParameterSource.DEFAULT, ParameterSource.DEFAULT_MAP):
+                out("Using configuration from project root.", fg="blue")
+            else:
+                out(f"Using configuration in '{config}'.", fg="blue")
 
     error_msg = "Oh no! 💥 💔 💥"
     if required_version and required_version != __version__:
@@ -516,14 +546,12 @@ def get_sources(
     stdin_filename: Optional[str],
 ) -> Set[Path]:
     """Compute the set of files to be formatted."""
-
-    root = find_project_root(src)
     sources: Set[Path] = set()
     path_empty(src, "No Path provided. Nothing to do 😴", quiet, verbose, ctx)
 
     if exclude is None:
         exclude = re_compile_maybe_verbose(DEFAULT_EXCLUDES)
-        gitignore = get_gitignore(root)
+        gitignore = get_gitignore(ctx.obj["root"])
     else:
         gitignore = None
 
@@ -536,7 +564,7 @@ def get_sources(
             is_stdin = False
 
         if is_stdin or p.is_file():
-            normalized_path = normalize_path_maybe_ignore(p, root, report)
+            normalized_path = normalize_path_maybe_ignore(p, ctx.obj["root"], report)
             if normalized_path is None:
                 continue
 
@@ -563,7 +591,7 @@ def get_sources(
             sources.update(
                 gen_python_files(
                     p.iterdir(),
-                    root,
+                    ctx.obj["root"],
                     include,
                     exclude,
                     extend_exclude,
diff --git a/src/black/files.py b/src/black/files.py
index dfab9f73039..18c84237bf0 100644
--- a/src/black/files.py
+++ b/src/black/files.py
@@ -31,7 +31,7 @@
 
 
 @lru_cache()
-def find_project_root(srcs: Sequence[str]) -> Path:
+def find_project_root(srcs: Sequence[str]) -> Tuple[Path, str]:
     """Return a directory containing .git, .hg, or pyproject.toml.
 
     That directory will be a common parent of all files and directories
@@ -39,6 +39,10 @@ def find_project_root(srcs: Sequence[str]) -> Path:
 
     If no directory in the tree contains a marker that would specify it's the
     project root, the root of the file system is returned.
+
+    Returns a two-tuple with the first element as the project root path and
+    the second element as a string describing the method by which the
+    project root was discovered.
     """
     if not srcs:
         srcs = [str(Path.cwd().resolve())]
@@ -58,20 +62,20 @@ def find_project_root(srcs: Sequence[str]) -> Path:
 
     for directory in (common_base, *common_base.parents):
         if (directory / ".git").exists():
-            return directory
+            return directory, ".git directory"
 
         if (directory / ".hg").is_dir():
-            return directory
+            return directory, ".hg directory"
 
         if (directory / "pyproject.toml").is_file():
-            return directory
+            return directory, "pyproject.toml"
 
-    return directory
+    return directory, "file system root"
 
 
 def find_pyproject_toml(path_search_start: Tuple[str, ...]) -> Optional[str]:
     """Find the absolute filepath to a pyproject.toml if it exists"""
-    path_project_root = find_project_root(path_search_start)
+    path_project_root, _ = find_project_root(path_search_start)
     path_pyproject_toml = path_project_root / "pyproject.toml"
     if path_pyproject_toml.is_file():
         return str(path_pyproject_toml)
@@ -133,7 +137,9 @@ def get_gitignore(root: Path) -> PathSpec:
 
 
 def normalize_path_maybe_ignore(
-    path: Path, root: Path, report: Report
+    path: Path,
+    root: Path,
+    report: Optional[Report] = None,
 ) -> Optional[str]:
     """Normalize `path`. May return `None` if `path` was ignored.
 
@@ -143,12 +149,16 @@ def normalize_path_maybe_ignore(
         abspath = path if path.is_absolute() else Path.cwd() / path
         normalized_path = abspath.resolve().relative_to(root).as_posix()
     except OSError as e:
-        report.path_ignored(path, f"cannot be read because {e}")
+        if report:
+            report.path_ignored(path, f"cannot be read because {e}")
         return None
 
     except ValueError:
         if path.is_symlink():
-            report.path_ignored(path, f"is a symbolic link that points outside {root}")
+            if report:
+                report.path_ignored(
+                    path, f"is a symbolic link that points outside {root}"
+                )
             return None
 
         raise
diff --git a/tests/test_black.py b/tests/test_black.py
index 5be4ae8533c..91d10581f6f 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -100,6 +100,8 @@ class FakeContext(click.Context):
 
     def __init__(self) -> None:
         self.default_map: Dict[str, Any] = {}
+        # Dummy root, since most of the tests don't care about it
+        self.obj: Dict[str, Any] = {"root": PROJECT_ROOT}
 
 
 class FakeParameter(click.Parameter):
@@ -1350,10 +1352,17 @@ def test_find_project_root(self) -> None:
             src_python.touch()
 
             self.assertEqual(
-                black.find_project_root((src_dir, test_dir)), root.resolve()
+                black.find_project_root((src_dir, test_dir)),
+                (root.resolve(), "pyproject.toml"),
+            )
+            self.assertEqual(
+                black.find_project_root((src_dir,)),
+                (src_dir.resolve(), "pyproject.toml"),
+            )
+            self.assertEqual(
+                black.find_project_root((src_python,)),
+                (src_dir.resolve(), "pyproject.toml"),
             )
-            self.assertEqual(black.find_project_root((src_dir,)), src_dir.resolve())
-            self.assertEqual(black.find_project_root((src_python,)), src_dir.resolve())
 
     @patch(
         "black.files.find_user_pyproject_toml",
@@ -1756,6 +1765,7 @@ def assert_collected_sources(
     src: Sequence[Union[str, Path]],
     expected: Sequence[Union[str, Path]],
     *,
+    ctx: Optional[FakeContext] = None,
     exclude: Optional[str] = None,
     include: Optional[str] = None,
     extend_exclude: Optional[str] = None,
@@ -1771,7 +1781,7 @@ def assert_collected_sources(
     )
     gs_force_exclude = None if force_exclude is None else compile_pattern(force_exclude)
     collected = black.get_sources(
-        ctx=FakeContext(),
+        ctx=ctx or FakeContext(),
         src=gs_src,
         quiet=False,
         verbose=False,
@@ -1807,9 +1817,11 @@ def test_gitignore_used_as_default(self) -> None:
             base / "b/.definitely_exclude/a.pyi",
         ]
         src = [base / "b/"]
-        assert_collected_sources(src, expected, extend_exclude=r"/exclude/")
+        ctx = FakeContext()
+        ctx.obj["root"] = base
+        assert_collected_sources(src, expected, ctx=ctx, extend_exclude=r"/exclude/")
 
-    @patch("black.find_project_root", lambda *args: THIS_DIR.resolve())
+    @patch("black.find_project_root", lambda *args: (THIS_DIR.resolve(), None))
     def test_exclude_for_issue_1572(self) -> None:
         # Exclude shouldn't touch files that were explicitly given to Black through the
         # CLI. Exclude is supposed to only apply to the recursive discovery of files.
@@ -1992,13 +2004,13 @@ def test_symlink_out_of_root_directory(self) -> None:
         child.is_symlink.assert_called()
         assert child.is_symlink.call_count == 2
 
-    @patch("black.find_project_root", lambda *args: THIS_DIR.resolve())
+    @patch("black.find_project_root", lambda *args: (THIS_DIR.resolve(), None))
     def test_get_sources_with_stdin(self) -> None:
         src = ["-"]
         expected = ["-"]
         assert_collected_sources(src, expected, include="", exclude=r"/exclude/|a\.py")
 
-    @patch("black.find_project_root", lambda *args: THIS_DIR.resolve())
+    @patch("black.find_project_root", lambda *args: (THIS_DIR.resolve(), None))
     def test_get_sources_with_stdin_filename(self) -> None:
         src = ["-"]
         stdin_filename = str(THIS_DIR / "data/collections.py")
@@ -2010,7 +2022,7 @@ def test_get_sources_with_stdin_filename(self) -> None:
             stdin_filename=stdin_filename,
         )
 
-    @patch("black.find_project_root", lambda *args: THIS_DIR.resolve())
+    @patch("black.find_project_root", lambda *args: (THIS_DIR.resolve(), None))
     def test_get_sources_with_stdin_filename_and_exclude(self) -> None:
         # Exclude shouldn't exclude stdin_filename since it is mimicking the
         # file being passed directly. This is the same as
@@ -2026,7 +2038,7 @@ def test_get_sources_with_stdin_filename_and_exclude(self) -> None:
             stdin_filename=stdin_filename,
         )
 
-    @patch("black.find_project_root", lambda *args: THIS_DIR.resolve())
+    @patch("black.find_project_root", lambda *args: (THIS_DIR.resolve(), None))
     def test_get_sources_with_stdin_filename_and_extend_exclude(self) -> None:
         # Extend exclude shouldn't exclude stdin_filename since it is mimicking the
         # file being passed directly. This is the same as
@@ -2042,7 +2054,7 @@ def test_get_sources_with_stdin_filename_and_extend_exclude(self) -> None:
             stdin_filename=stdin_filename,
         )
 
-    @patch("black.find_project_root", lambda *args: THIS_DIR.resolve())
+    @patch("black.find_project_root", lambda *args: (THIS_DIR.resolve(), None))
     def test_get_sources_with_stdin_filename_and_force_exclude(self) -> None:
         # Force exclude should exclude the file when passing it through
         # stdin_filename

From 3e731527e4418b0b6d9791d6e32caee9227ba69d Mon Sep 17 00:00:00 2001
From: Batuhan Taskaya <isidentical@gmail.com>
Date: Mon, 10 Jan 2022 21:22:00 +0300
Subject: [PATCH 0409/1034] Speed up new backtracking parser (#2728)

---
 CHANGES.md                             |   2 +
 src/blib2to3/pgen2/parse.py            |  89 ++++++++++++++------
 tests/data/pattern_matching_generic.py | 107 +++++++++++++++++++++++++
 tests/test_format.py                   |   1 +
 4 files changed, 176 insertions(+), 23 deletions(-)
 create mode 100644 tests/data/pattern_matching_generic.py

diff --git a/CHANGES.md b/CHANGES.md
index f6e8343ed00..a1c8ccb0b7d 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -24,6 +24,8 @@
   at least one pre-existing blank line (#2736)
 - Verbose mode also now describes how a project root was discovered and which paths will
   be formatted. (#2526)
+- Speed-up the new backtracking parser about 4X in general (enabled when
+  `--target-version` is set to 3.10 and higher). (#2728)
 
 ### Packaging
 
diff --git a/src/blib2to3/pgen2/parse.py b/src/blib2to3/pgen2/parse.py
index e5dad3ae766..8fe96672897 100644
--- a/src/blib2to3/pgen2/parse.py
+++ b/src/blib2to3/pgen2/parse.py
@@ -46,6 +46,17 @@ def lam_sub(grammar: Grammar, node: RawNode) -> NL:
     return Node(type=node[0], children=node[3], context=node[2])
 
 
+# A placeholder node, used when parser is backtracking.
+DUMMY_NODE = (-1, None, None, None)
+
+
+def stack_copy(
+    stack: List[Tuple[DFAS, int, RawNode]]
+) -> List[Tuple[DFAS, int, RawNode]]:
+    """Nodeless stack copy."""
+    return [(copy.deepcopy(dfa), label, DUMMY_NODE) for dfa, label, _ in stack]
+
+
 class Recorder:
     def __init__(self, parser: "Parser", ilabels: List[int], context: Context) -> None:
         self.parser = parser
@@ -54,7 +65,7 @@ def __init__(self, parser: "Parser", ilabels: List[int], context: Context) -> No
 
         self._dead_ilabels: Set[int] = set()
         self._start_point = self.parser.stack
-        self._points = {ilabel: copy.deepcopy(self._start_point) for ilabel in ilabels}
+        self._points = {ilabel: stack_copy(self._start_point) for ilabel in ilabels}
 
     @property
     def ilabels(self) -> Set[int]:
@@ -62,13 +73,32 @@ def ilabels(self) -> Set[int]:
 
     @contextmanager
     def switch_to(self, ilabel: int) -> Iterator[None]:
-        self.parser.stack = self._points[ilabel]
+        with self.backtrack():
+            self.parser.stack = self._points[ilabel]
+            try:
+                yield
+            except ParseError:
+                self._dead_ilabels.add(ilabel)
+            finally:
+                self.parser.stack = self._start_point
+
+    @contextmanager
+    def backtrack(self) -> Iterator[None]:
+        """
+        Use the node-level invariant ones for basic parsing operations (push/pop/shift).
+        These still will operate on the stack; but they won't create any new nodes, or
+        modify the contents of any other existing nodes.
+
+        This saves us a ton of time when we are backtracking, since we
+        want to restore to the initial state as quick as possible, which
+        can only be done by having as little mutatations as possible.
+        """
+        is_backtracking = self.parser.is_backtracking
         try:
+            self.parser.is_backtracking = True
             yield
-        except ParseError:
-            self._dead_ilabels.add(ilabel)
         finally:
-            self.parser.stack = self._start_point
+            self.parser.is_backtracking = is_backtracking
 
     def add_token(self, tok_type: int, tok_val: Text, raw: bool = False) -> None:
         func: Callable[..., Any]
@@ -179,6 +209,7 @@ def __init__(self, grammar: Grammar, convert: Optional[Convert] = None) -> None:
         self.grammar = grammar
         # See note in docstring above. TL;DR this is ignored.
         self.convert = convert or lam_sub
+        self.is_backtracking = False
 
     def setup(self, proxy: "TokenProxy", start: Optional[int] = None) -> None:
         """Prepare for parsing.
@@ -319,28 +350,40 @@ def classify(self, type: int, value: Text, context: Context) -> List[int]:
 
     def shift(self, type: int, value: Text, newstate: int, context: Context) -> None:
         """Shift a token.  (Internal)"""
-        dfa, state, node = self.stack[-1]
-        rawnode: RawNode = (type, value, context, None)
-        newnode = convert(self.grammar, rawnode)
-        assert node[-1] is not None
-        node[-1].append(newnode)
-        self.stack[-1] = (dfa, newstate, node)
+        if self.is_backtracking:
+            dfa, state, _ = self.stack[-1]
+            self.stack[-1] = (dfa, newstate, DUMMY_NODE)
+        else:
+            dfa, state, node = self.stack[-1]
+            rawnode: RawNode = (type, value, context, None)
+            newnode = convert(self.grammar, rawnode)
+            assert node[-1] is not None
+            node[-1].append(newnode)
+            self.stack[-1] = (dfa, newstate, node)
 
     def push(self, type: int, newdfa: DFAS, newstate: int, context: Context) -> None:
         """Push a nonterminal.  (Internal)"""
-        dfa, state, node = self.stack[-1]
-        newnode: RawNode = (type, None, context, [])
-        self.stack[-1] = (dfa, newstate, node)
-        self.stack.append((newdfa, 0, newnode))
+        if self.is_backtracking:
+            dfa, state, _ = self.stack[-1]
+            self.stack[-1] = (dfa, newstate, DUMMY_NODE)
+            self.stack.append((newdfa, 0, DUMMY_NODE))
+        else:
+            dfa, state, node = self.stack[-1]
+            newnode: RawNode = (type, None, context, [])
+            self.stack[-1] = (dfa, newstate, node)
+            self.stack.append((newdfa, 0, newnode))
 
     def pop(self) -> None:
         """Pop a nonterminal.  (Internal)"""
-        popdfa, popstate, popnode = self.stack.pop()
-        newnode = convert(self.grammar, popnode)
-        if self.stack:
-            dfa, state, node = self.stack[-1]
-            assert node[-1] is not None
-            node[-1].append(newnode)
+        if self.is_backtracking:
+            self.stack.pop()
         else:
-            self.rootnode = newnode
-            self.rootnode.used_names = self.used_names
+            popdfa, popstate, popnode = self.stack.pop()
+            newnode = convert(self.grammar, popnode)
+            if self.stack:
+                dfa, state, node = self.stack[-1]
+                assert node[-1] is not None
+                node[-1].append(newnode)
+            else:
+                self.rootnode = newnode
+                self.rootnode.used_names = self.used_names
diff --git a/tests/data/pattern_matching_generic.py b/tests/data/pattern_matching_generic.py
new file mode 100644
index 00000000000..00a0e4a677d
--- /dev/null
+++ b/tests/data/pattern_matching_generic.py
@@ -0,0 +1,107 @@
+re.match()
+match = a
+with match() as match:
+    match = f"{match}"
+
+re.match()
+match = a
+with match() as match:
+    match = f"{match}"
+
+
+def get_grammars(target_versions: Set[TargetVersion]) -> List[Grammar]:
+    if not target_versions:
+        # No target_version specified, so try all grammars.
+        return [
+            # Python 3.7+
+            pygram.python_grammar_no_print_statement_no_exec_statement_async_keywords,
+            # Python 3.0-3.6
+            pygram.python_grammar_no_print_statement_no_exec_statement,
+            # Python 2.7 with future print_function import
+            pygram.python_grammar_no_print_statement,
+            # Python 2.7
+            pygram.python_grammar,
+        ]
+
+    match match:
+        case case:
+            match match:
+                case case:
+                    pass
+
+    if all(version.is_python2() for version in target_versions):
+        # Python 2-only code, so try Python 2 grammars.
+        return [
+            # Python 2.7 with future print_function import
+            pygram.python_grammar_no_print_statement,
+            # Python 2.7
+            pygram.python_grammar,
+        ]
+
+    re.match()
+    match = a
+    with match() as match:
+        match = f"{match}"
+
+    def test_patma_139(self):
+        x = False
+        match x:
+            case bool(z):
+                y = 0
+        self.assertIs(x, False)
+        self.assertEqual(y, 0)
+        self.assertIs(z, x)
+
+    # Python 3-compatible code, so only try Python 3 grammar.
+    grammars = []
+    if supports_feature(target_versions, Feature.PATTERN_MATCHING):
+        # Python 3.10+
+        grammars.append(pygram.python_grammar_soft_keywords)
+    # If we have to parse both, try to parse async as a keyword first
+    if not supports_feature(
+        target_versions, Feature.ASYNC_IDENTIFIERS
+    ) and not supports_feature(target_versions, Feature.PATTERN_MATCHING):
+        # Python 3.7-3.9
+        grammars.append(
+            pygram.python_grammar_no_print_statement_no_exec_statement_async_keywords
+        )
+    if not supports_feature(target_versions, Feature.ASYNC_KEYWORDS):
+        # Python 3.0-3.6
+        grammars.append(pygram.python_grammar_no_print_statement_no_exec_statement)
+
+    def test_patma_155(self):
+        x = 0
+        y = None
+        match x:
+            case 1e1000:
+                y = 0
+        self.assertEqual(x, 0)
+        self.assertIs(y, None)
+
+        x = range(3)
+        match x:
+            case [y, case as x, z]:
+                w = 0
+
+    # At least one of the above branches must have been taken, because every Python
+    # version has exactly one of the two 'ASYNC_*' flags
+    return grammars
+
+
+def lib2to3_parse(src_txt: str, target_versions: Iterable[TargetVersion] = ()) -> Node:
+    """Given a string with source, return the lib2to3 Node."""
+    if not src_txt.endswith("\n"):
+        src_txt += "\n"
+
+    grammars = get_grammars(set(target_versions))
+
+
+re.match()
+match = a
+with match() as match:
+    match = f"{match}"
+
+re.match()
+match = a
+with match() as match:
+    match = f"{match}"
diff --git a/tests/test_format.py b/tests/test_format.py
index 6651272a87c..db39678cdfe 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -69,6 +69,7 @@
     "pattern_matching_complex",
     "pattern_matching_extras",
     "pattern_matching_style",
+    "pattern_matching_generic",
     "parenthesized_context_managers",
 ]
 

From 0f26a0369efc7305a1a0120355f78d85b3030e56 Mon Sep 17 00:00:00 2001
From: Batuhan Taskaya <isidentical@gmail.com>
Date: Mon, 10 Jan 2022 23:22:07 +0300
Subject: [PATCH 0410/1034] Fix handling of standalone match/case with
 newlines/comments (#2760)

Resolves #2759
---
 CHANGES.md                           |  2 +
 src/blib2to3/pgen2/parse.py          |  4 ++
 tests/data/pattern_matching_style.py | 68 +++++++++++++++++++++++++++-
 3 files changed, 72 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index a1c8ccb0b7d..748dbca7019 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -26,6 +26,8 @@
   be formatted. (#2526)
 - Speed-up the new backtracking parser about 4X in general (enabled when
   `--target-version` is set to 3.10 and higher). (#2728)
+- Fix handling of standalone `match()` or `case()` when there is a trailing newline or a
+  comment inside of the parentheses. (#2760)
 
 ### Packaging
 
diff --git a/src/blib2to3/pgen2/parse.py b/src/blib2to3/pgen2/parse.py
index 8fe96672897..4a23d538b49 100644
--- a/src/blib2to3/pgen2/parse.py
+++ b/src/blib2to3/pgen2/parse.py
@@ -269,6 +269,10 @@ def addtoken(self, type: int, value: Text, context: Context) -> bool:
                     break
 
                 next_token_type, next_token_value, *_ = proxy.eat(counter)
+                if next_token_type in (tokenize.COMMENT, tokenize.NL):
+                    counter += 1
+                    continue
+
                 if next_token_type == tokenize.OP:
                     next_token_type = grammar.opmap[next_token_value]
 
diff --git a/tests/data/pattern_matching_style.py b/tests/data/pattern_matching_style.py
index c1c0aeedb70..8e18ce2ada6 100644
--- a/tests/data/pattern_matching_style.py
+++ b/tests/data/pattern_matching_style.py
@@ -6,10 +6,52 @@
     ): print(1)
     case c(
         very_complex=True,
-        perhaps_even_loooooooooooooooooooooooooooooooooooooong=-1
+        perhaps_even_loooooooooooooooooooooooooooooooooooooong=-1,
     ): print(2)
     case a: pass
 
+match(
+    arg # comment
+)
+
+match(
+)
+
+match(
+
+
+)
+
+case(
+    arg # comment
+)
+
+case(
+)
+
+case(
+
+
+)
+
+
+re.match(
+    something # fast
+)
+re.match(
+
+
+
+)
+match match(
+
+
+):
+    case case(
+        arg, # comment
+    ):
+        pass
+
 # output
 
 match something:
@@ -20,8 +62,30 @@
     ):
         print(1)
     case c(
-        very_complex=True, perhaps_even_loooooooooooooooooooooooooooooooooooooong=-1
+        very_complex=True,
+        perhaps_even_loooooooooooooooooooooooooooooooooooooong=-1,
     ):
         print(2)
     case a:
         pass
+
+match(arg)  # comment
+
+match()
+
+match()
+
+case(arg)  # comment
+
+case()
+
+case()
+
+
+re.match(something)  # fast
+re.match()
+match match():
+    case case(
+        arg,  # comment
+    ):
+        pass

From 4efb795129b17b96bdf299eacaca4243d9af86d0 Mon Sep 17 00:00:00 2001
From: cbows <32486983+cbows@users.noreply.github.com>
Date: Tue, 11 Jan 2022 18:31:07 +0100
Subject: [PATCH 0411/1034] Change git url for pip installation in README
 (#2761)

* Change git url for pip installation in README

Unauthenticated git protocol was disabled recently by Github and should not be used anymore.

https://github.blog/2021-09-01-improving-git-protocol-security-github/#no-more-unauthenticated-git

* Update CHANGES.md
---
 CHANGES.md | 4 ++++
 README.md  | 2 +-
 2 files changed, 5 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index 748dbca7019..565c36f8c60 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -37,6 +37,10 @@
 
 - Update GitHub action to support containerized runs (#2748)
 
+### Documentation
+
+- Change protocol in pip installation instructions to `https://` (#2761)
+
 ## 21.12b0
 
 ### _Black_
diff --git a/README.md b/README.md
index e2b0d17ecfd..32db2bf2ce8 100644
--- a/README.md
+++ b/README.md
@@ -44,7 +44,7 @@ run. If you want to format Jupyter Notebooks, install with `pip install black[ju
 
 If you can't wait for the latest _hotness_ and want to install from GitHub, use:
 
-`pip install git+git://github.com/psf/black`
+`pip install git+https://github.com/psf/black`
 
 ### Usage
 

From 8954e58ccf620a9c797f5e6ea3c53bc1f21f14d9 Mon Sep 17 00:00:00 2001
From: Jeffrey Lazar <jeff.p.lazar@gmail.com>
Date: Tue, 11 Jan 2022 17:37:07 -0500
Subject: [PATCH 0412/1034] Change installation url to comply with git security
 change (#2765)

Co-authored-by: Jeffrey Lazar <jlazar@MacBook-Pro-2.local>
---
 docs/getting_started.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/getting_started.md b/docs/getting_started.md
index 987290ac91f..1227f653757 100644
--- a/docs/getting_started.md
+++ b/docs/getting_started.md
@@ -21,7 +21,7 @@ run. If you want to format Jupyter Notebooks, install with `pip install black[ju
 
 If you can't wait for the latest _hotness_ and want to install from GitHub, use:
 
-`pip install git+git://github.com/psf/black`
+`pip install git+https://github.com/psf/black`
 
 ## Basic usage
 

From f298032ddb624067aebc49f792b4308aeeb1841d Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Thu, 13 Jan 2022 09:33:56 -0800
Subject: [PATCH 0413/1034] don't expect changes on poetry (#2769)

They just made themselves ESP-compliant in https://github.com/python-poetry/poetry/commit/ecb030e1f0b7c13cc11971f00ee5012e82a892bc
---
 src/black_primer/primer.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/black_primer/primer.json b/src/black_primer/primer.json
index d8e13edeb06..a8d8fc9e21f 100644
--- a/src/black_primer/primer.json
+++ b/src/black_primer/primer.json
@@ -109,7 +109,7 @@
     },
     "poetry": {
       "cli_arguments": ["--experimental-string-processing"],
-      "expect_formatting_changes": true,
+      "expect_formatting_changes": false,
       "git_clone_url": "https://github.com/python-poetry/poetry.git",
       "long_checkout": false,
       "py_versions": ["all"]

From 799f76f537f72ade97b8e6637c59fee49e05a4ab Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Felix=20Hild=C3=A9n?= <felix.hilden@gmail.com>
Date: Thu, 13 Jan 2022 19:59:43 +0200
Subject: [PATCH 0414/1034] Normalise string prefix order (#2297)

Closes #2171
---
 CHANGES.md                                 |  1 +
 docs/the_black_code_style/current_style.md |  8 +++---
 src/black/strings.py                       |  4 +++
 src/blib2to3/pgen2/tokenize.py             |  2 +-
 tests/data/string_prefixes.py              | 30 +++++++++++++---------
 5 files changed, 28 insertions(+), 17 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 565c36f8c60..5a8a0ef9f7c 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -28,6 +28,7 @@
   `--target-version` is set to 3.10 and higher). (#2728)
 - Fix handling of standalone `match()` or `case()` when there is a trailing newline or a
   comment inside of the parentheses. (#2760)
+- Black now normalizes string prefix order (#2297)
 
 ### Packaging
 
diff --git a/docs/the_black_code_style/current_style.md b/docs/the_black_code_style/current_style.md
index 68dff3eef3f..11fe2c8cceb 100644
--- a/docs/the_black_code_style/current_style.md
+++ b/docs/the_black_code_style/current_style.md
@@ -233,10 +233,10 @@ _Black_ prefers double quotes (`"` and `"""`) over single quotes (`'` and `'''`)
 will replace the latter with the former as long as it does not result in more backslash
 escapes than before.
 
-_Black_ also standardizes string prefixes, making them always lowercase. On top of that,
-if your code is already Python 3.6+ only or it's using the `unicode_literals` future
-import, _Black_ will remove `u` from the string prefix as it is meaningless in those
-scenarios.
+_Black_ also standardizes string prefixes. Prefix characters are made lowercase with the
+exception of [capital "R" prefixes](#rstrings-and-rstrings), unicode literal markers
+(`u`) are removed because they are meaningless in Python 3, and in the case of multiple
+characters "r" is put first as in spoken language: "raw f-string".
 
 The main reason to standardize on a single form of quotes is aesthetics. Having one kind
 of quotes everywhere reduces reader distraction. It will also enable a future version of
diff --git a/src/black/strings.py b/src/black/strings.py
index 262c2ba4313..9d0e2eb8430 100644
--- a/src/black/strings.py
+++ b/src/black/strings.py
@@ -149,6 +149,10 @@ def normalize_string_prefix(s: str) -> str:
         .replace("U", "")
         .replace("u", "")
     )
+
+    # Python syntax guarantees max 2 prefixes and that one of them is "r"
+    if len(new_prefix) == 2 and "r" != new_prefix[0].lower():
+        new_prefix = new_prefix[::-1]
     return f"{new_prefix}{match.group(2)}"
 
 
diff --git a/src/blib2to3/pgen2/tokenize.py b/src/blib2to3/pgen2/tokenize.py
index a7e17df1e8f..257dbef4a19 100644
--- a/src/blib2to3/pgen2/tokenize.py
+++ b/src/blib2to3/pgen2/tokenize.py
@@ -293,7 +293,7 @@ def compat(self, token: Tuple[int, Text], iterable: Iterable[TokenInfo]) -> None
 
 
 cookie_re = re.compile(r"^[ \t\f]*#.*?coding[:=][ \t]*([-\w.]+)", re.ASCII)
-blank_re = re.compile(br"^[ \t\f]*(?:[#\r\n]|$)", re.ASCII)
+blank_re = re.compile(rb"^[ \t\f]*(?:[#\r\n]|$)", re.ASCII)
 
 
 def _get_normal_name(orig_enc: str) -> str:
diff --git a/tests/data/string_prefixes.py b/tests/data/string_prefixes.py
index 9ddc2b540fc..f86da696e15 100644
--- a/tests/data/string_prefixes.py
+++ b/tests/data/string_prefixes.py
@@ -1,10 +1,13 @@
-#!/usr/bin/env python3.6
+#!/usr/bin/env python3
 
-name = R"Łukasz"
-F"hello {name}"
-B"hello"
-r"hello"
-fR"hello"
+name = "Łukasz"
+(f"hello {name}", F"hello {name}")
+(b"", B"")
+(u"", U"")
+(r"", R"")
+
+(rf"", fr"", Rf"", fR"", rF"", Fr"", RF"", FR"")
+(rb"", br"", Rb"", bR"", rB"", Br"", RB"", BR"")
 
 
 def docstring_singleline():
@@ -20,13 +23,16 @@ def docstring_multiline():
 # output
 
 
-#!/usr/bin/env python3.6
+#!/usr/bin/env python3
+
+name = "Łukasz"
+(f"hello {name}", f"hello {name}")
+(b"", b"")
+("", "")
+(r"", R"")
 
-name = R"Łukasz"
-f"hello {name}"
-b"hello"
-r"hello"
-fR"hello"
+(rf"", rf"", Rf"", Rf"", rf"", rf"", Rf"", Rf"")
+(rb"", rb"", Rb"", Rb"", rb"", rb"", Rb"", Rb"")
 
 
 def docstring_singleline():

From 7a2956811534d7d20128ba6e911721749052b627 Mon Sep 17 00:00:00 2001
From: Batuhan Taskaya <isidentical@gmail.com>
Date: Fri, 14 Jan 2022 05:01:44 +0300
Subject: [PATCH 0415/1034] Don't make redundant copies of the DFA (#2763)

---
 src/blib2to3/pgen2/parse.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/blib2to3/pgen2/parse.py b/src/blib2to3/pgen2/parse.py
index 4a23d538b49..a9dc11f39ce 100644
--- a/src/blib2to3/pgen2/parse.py
+++ b/src/blib2to3/pgen2/parse.py
@@ -54,7 +54,7 @@ def stack_copy(
     stack: List[Tuple[DFAS, int, RawNode]]
 ) -> List[Tuple[DFAS, int, RawNode]]:
     """Nodeless stack copy."""
-    return [(copy.deepcopy(dfa), label, DUMMY_NODE) for dfa, label, _ in stack]
+    return [(dfa, label, DUMMY_NODE) for dfa, label, _ in stack]
 
 
 class Recorder:

From 5543d1b55a2a485f2aaf32156ea97f4728264137 Mon Sep 17 00:00:00 2001
From: VanSHOE <75690289+VanSHOE@users.noreply.github.com>
Date: Fri, 14 Jan 2022 08:01:08 +0530
Subject: [PATCH 0416/1034] Added decent coloring (#2712)

---
 CHANGES.md            | 1 +
 src/black/__init__.py | 2 ++
 src/black/report.py   | 6 ++++--
 3 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 5a8a0ef9f7c..6813e86e0da 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -20,6 +20,7 @@
 - Tuple unpacking on `return` and `yield` constructs now implies 3.8+ (#2700)
 - Unparenthesized tuples on annotated assignments (e.g
   `values: Tuple[int, ...] = 1, 2, 3`) now implies 3.8+ (#2708)
+- Text coloring added in the final statistics (#2712)
 - For stubs, one blank line between class attributes and methods is now kept if there's
   at least one pre-existing blank line (#2736)
 - Verbose mode also now describes how a project root was discovered and which paths will
diff --git a/src/black/__init__.py b/src/black/__init__.py
index cfa2c7663fe..fa918ce2931 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -526,6 +526,8 @@ def main(
             )
 
     if verbose or not quiet:
+        if code is None and (verbose or report.change_count or report.failure_count):
+            out()
         out(error_msg if report.return_code else "All done! ✨ 🍰 ✨")
         if code is None:
             click.echo(str(report), err=True)
diff --git a/src/black/report.py b/src/black/report.py
index 7e1c8b4b87f..43b942c9e3c 100644
--- a/src/black/report.py
+++ b/src/black/report.py
@@ -93,11 +93,13 @@ def __str__(self) -> str:
         if self.change_count:
             s = "s" if self.change_count > 1 else ""
             report.append(
-                style(f"{self.change_count} file{s} {reformatted}", bold=True)
+                style(f"{self.change_count} file{s} ", bold=True, fg="blue")
+                + style(f"{reformatted}", bold=True)
             )
+
         if self.same_count:
             s = "s" if self.same_count > 1 else ""
-            report.append(f"{self.same_count} file{s} {unchanged}")
+            report.append(style(f"{self.same_count} file{s} ", fg="blue") + unchanged)
         if self.failure_count:
             s = "s" if self.failure_count > 1 else ""
             report.append(style(f"{self.failure_count} file{s} {failed}", fg="red"))

From 565f9c92b79a72deb7faec7503749979c791b6e1 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Thu, 13 Jan 2022 21:50:02 -0500
Subject: [PATCH 0417/1034] CI: add diff-shades integration (#2725)

Hopefully this makes it much easier to gauge the impacts of future
changes!
---
 .github/workflows/diff_shades.yml         | 134 +++++++++++
 .github/workflows/diff_shades_comment.yml |  47 ++++
 .pre-commit-config.yaml                   |   2 +-
 docs/contributing/gauging_changes.md      |  53 +++++
 scripts/diff_shades_gha_helper.py         | 272 ++++++++++++++++++++++
 5 files changed, 507 insertions(+), 1 deletion(-)
 create mode 100644 .github/workflows/diff_shades.yml
 create mode 100644 .github/workflows/diff_shades_comment.yml
 create mode 100644 scripts/diff_shades_gha_helper.py

diff --git a/.github/workflows/diff_shades.yml b/.github/workflows/diff_shades.yml
new file mode 100644
index 00000000000..b6a9b3355fb
--- /dev/null
+++ b/.github/workflows/diff_shades.yml
@@ -0,0 +1,134 @@
+name: diff-shades
+
+on:
+  push:
+    branches: [main]
+    paths-ignore: ["docs/**", "tests/**", "*.md"]
+
+  pull_request:
+    path-ignore: ["docs/**", "tests/**", "*.md"]
+
+  workflow_dispatch:
+    inputs:
+      baseline:
+        description: >
+          The baseline revision. Pro-tip, use `.pypi` to use the latest version
+          on PyPI or `.XXX` to use a PR.
+        required: true
+        default: main
+      baseline-args:
+        description: "Custom Black arguments (eg. -l 79)"
+        required: false
+      target:
+        description: >
+          The target revision to compare against the baseline. Same tip applies here.
+        required: true
+      target-args:
+        description: "Custom Black arguments (eg. -S)"
+        required: false
+
+jobs:
+  analysis:
+    name: analysis / linux
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout this repository (full clone)
+        uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v2
+
+      - name: Install diff-shades and support dependencies
+        run: |
+          python -m pip install pip --upgrade
+          python -m pip install https://github.com/ichard26/diff-shades/archive/stable.zip
+          python -m pip install click packaging urllib3
+          # After checking out old revisions, this might not exist so we'll use a copy.
+          cat scripts/diff_shades_gha_helper.py > helper.py
+          git config user.name "diff-shades-gha"
+          git config user.email "diff-shades-gha@example.com"
+
+      - name: Calculate run configuration & metadata
+        id: config
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: >
+          python helper.py config ${{ github.event_name }}
+          ${{ github.event.inputs.baseline }} ${{ github.event.inputs.target }}
+          --baseline-args "${{ github.event.inputs.baseline-args }}"
+
+      - name: Attempt to use cached baseline analysis
+        id: baseline-cache
+        uses: actions/cache@v2.1.7
+        with:
+          path: ${{ steps.config.outputs.baseline-analysis }}
+          key: ${{ steps.config.outputs.baseline-cache-key }}
+
+      - name: Install baseline revision
+        if: steps.baseline-cache.outputs.cache-hit != 'true'
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: ${{ steps.config.outputs.baseline-setup-cmd }} && python -m pip install .
+
+      - name: Analyze baseline revision
+        if: steps.baseline-cache.outputs.cache-hit != 'true'
+        run: >
+          diff-shades analyze -v --work-dir projects-cache/
+          ${{ steps.config.outputs.baseline-analysis }} -- ${{ github.event.inputs.baseline-args }}
+
+      - name: Install target revision
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: ${{ steps.config.outputs.target-setup-cmd }} && python -m pip install .
+
+      - name: Analyze target revision
+        run: >
+          diff-shades analyze -v --work-dir projects-cache/
+          ${{ steps.config.outputs.target-analysis }} --repeat-projects-from
+          ${{ steps.config.outputs.baseline-analysis }} -- ${{ github.event.inputs.target-args }}
+
+      - name: Generate HTML diff report
+        run: >
+          diff-shades --dump-html diff.html compare --diff --quiet
+          ${{ steps.config.outputs.baseline-analysis }} ${{ steps.config.outputs.target-analysis }}
+
+      - name: Upload diff report
+        uses: actions/upload-artifact@v2
+        with:
+          name: diff.html
+          path: diff.html
+
+      - name: Upload baseline analysis
+        uses: actions/upload-artifact@v2
+        with:
+          name: ${{ steps.config.outputs.baseline-analysis }}
+          path: ${{ steps.config.outputs.baseline-analysis }}
+
+      - name: Upload target analysis
+        uses: actions/upload-artifact@v2
+        with:
+          name: ${{ steps.config.outputs.target-analysis }}
+          path: ${{ steps.config.outputs.target-analysis }}
+
+      - name: Generate summary file (PR only)
+        if: github.event_name == 'pull_request'
+        run: >
+          python helper.py comment-body
+          ${{ steps.config.outputs.baseline-analysis }} ${{ steps.config.outputs.target-analysis }}
+          ${{ steps.config.outputs.baseline-sha }} ${{ steps.config.outputs.target-sha }}
+
+      - name: Upload summary file (PR only)
+        if: github.event_name == 'pull_request'
+        uses: actions/upload-artifact@v2
+        with:
+          name: .pr-comment-body.md
+          path: .pr-comment-body.md
+
+        # This is last so the diff-shades-comment workflow can still work even if we
+        # end up detecting failed files and failing the run.
+      - name: Check for failed files in both analyses
+        run: >
+          diff-shades show-failed --check --show-log ${{ steps.config.outputs.baseline-analysis }};
+          diff-shades show-failed --check --show-log ${{ steps.config.outputs.target-analysis }}
diff --git a/.github/workflows/diff_shades_comment.yml b/.github/workflows/diff_shades_comment.yml
new file mode 100644
index 00000000000..bdd90321800
--- /dev/null
+++ b/.github/workflows/diff_shades_comment.yml
@@ -0,0 +1,47 @@
+name: diff-shades-comment
+
+on:
+  workflow_run:
+    workflows: [diff-shades]
+    types: [completed]
+
+permissions:
+  pull-requests: write
+
+jobs:
+  comment:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-python@v2
+
+      - name: Install support dependencies
+        run: |
+          python -m pip install pip --upgrade
+          python -m pip install click packaging urllib3
+
+      - name: Get details from initial workflow run
+        id: metadata
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: >
+          python scripts/diff_shades_gha_helper.py comment-details
+          ${{github.event.workflow_run.id }}
+
+      - name: Try to find pre-existing PR comment
+        if: steps.metadata.outputs.needs-comment == 'true'
+        id: find-comment
+        uses: peter-evans/find-comment@v1
+        with:
+          issue-number: ${{ steps.metadata.outputs.pr-number }}
+          comment-author: "github-actions[bot]"
+          body-includes: "diff-shades"
+
+      - name: Create or update PR comment
+        if: steps.metadata.outputs.needs-comment == 'true'
+        uses: peter-evans/create-or-update-comment@v1
+        with:
+          comment-id: ${{ steps.find-comment.outputs.comment-id }}
+          issue-number: ${{ steps.metadata.outputs.pr-number }}
+          body: ${{ steps.metadata.outputs.comment-body }}
+          edit-mode: replace
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 52a18623612..af3c5c2b96e 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -57,7 +57,7 @@ repos:
     rev: v2.5.1
     hooks:
       - id: prettier
-        exclude: ^Pipfile\.lock
+        exclude: \.github/workflows/diff_shades\.yml
 
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.0.1
diff --git a/docs/contributing/gauging_changes.md b/docs/contributing/gauging_changes.md
index b41c7a35dda..3cfa98b3df8 100644
--- a/docs/contributing/gauging_changes.md
+++ b/docs/contributing/gauging_changes.md
@@ -40,3 +40,56 @@ If you're running locally yourself to test black on lots of code try:
 ```{program-output} black-primer --help
 
 ```
+
+## diff-shades
+
+diff-shades is a tool similar to black-primer, it also runs _Black_ across a list of Git
+cloneable OSS projects recording the results. The intention is to eventually fully
+replace black-primer with diff-shades as it's much more feature complete and supports
+our needs better.
+
+The main highlight feature of diff-shades is being able to compare two revisions of
+_Black_. This is incredibly useful as it allows us to see what exact changes will occur,
+say merging a certain PR. Black-primer's results would usually be filled with changes
+caused by pre-existing code in Black drowning out the (new) changes we want to see. It
+operates similarly to black-primer but crucially it saves the results as a JSON file
+which allows for the rich comparison features alluded to above.
+
+For more information, please see the [diff-shades documentation][diff-shades].
+
+### CI integration
+
+diff-shades is also the tool behind the "diff-shades results comparing ..." /
+"diff-shades reports zero changes ..." comments on PRs. The project has a GitHub Actions
+workflow which runs diff-shades twice against two revisions of _Black_ according to
+these rules:
+
+|                       | Baseline revision       | Target revision              |
+| --------------------- | ----------------------- | ---------------------------- |
+| On PRs                | latest commit on `main` | PR commit with `main` merged |
+| On pushes (main only) | latest PyPI version     | the pushed commit            |
+
+Once finished, a PR comment will be posted embedding a summary of the changes and links
+to further information. If there's a pre-existing diff-shades comment, it'll be updated
+instead the next time the workflow is triggered on the same PR.
+
+The workflow uploads 3-4 artifacts upon completion: the two generated analyses (they
+have the .json file extension), `diff.html`, and `.pr-comment-body.md` if triggered by a
+PR. The last one is downloaded by the `diff-shades-comment` workflow and shouldn't be
+downloaded locally. `diff.html` comes in handy for push-based or manually triggered
+runs. And the analyses exist just in case you want to do further analysis using the
+collected data locally.
+
+Note that the workflow will only fail intentionally if while analyzing a file failed to
+format. Otherwise a failure indicates a bug in the workflow.
+
+```{tip}
+Maintainers with write access or higher can trigger the workflow manually from the
+Actions tab using the `workflow_dispatch` event. Simply select "diff-shades"
+from the workflows list on the left, press "Run workflow", and fill in which revisions
+and command line arguments to use.
+
+Once finished, check the logs or download the artifacts for local use.
+```
+
+[diff-shades]: https://github.com/ichard26/diff-shades#readme
diff --git a/scripts/diff_shades_gha_helper.py b/scripts/diff_shades_gha_helper.py
new file mode 100644
index 00000000000..21e04a590a1
--- /dev/null
+++ b/scripts/diff_shades_gha_helper.py
@@ -0,0 +1,272 @@
+"""Helper script for psf/black's diff-shades Github Actions integration.
+
+diff-shades is a tool for analyzing what happens when you run Black on
+OSS code capturing it for comparisons or other usage. It's used here to
+help measure the impact of a change *before* landing it (in particular
+posting a comment on completion for PRs).
+
+This script exists as a more maintainable alternative to using inline
+Javascript in the workflow YAML files. The revision configuration and
+resolving, caching, and PR comment logic is contained here.
+
+For more information, please see the developer docs:
+
+https://black.readthedocs.io/en/latest/contributing/gauging_changes.html#diff-shades
+"""
+
+import json
+import os
+import platform
+import pprint
+import subprocess
+import sys
+import zipfile
+from io import BytesIO
+from pathlib import Path
+from typing import Any, Dict, Optional, Tuple
+
+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_BODY_FILE: Final = ".pr-comment-body.md"
+DIFF_STEP_NAME: Final = "Generate HTML diff report"
+DOCS_URL: Final = (
+    "https://black.readthedocs.io/en/latest/"
+    "contributing/gauging_changes.html#diff-shades"
+)
+USER_AGENT: Final = f"psf/black diff-shades workflow via urllib3/{urllib3.__version__}"
+SHA_LENGTH: Final = 10
+GH_API_TOKEN: Final = os.getenv("GITHUB_TOKEN")
+REPO: Final = os.getenv("GITHUB_REPOSITORY", default="psf/black")
+http = urllib3.PoolManager()
+
+
+def set_output(name: str, value: str) -> None:
+    if len(value) < 200:
+        print(f"[INFO]: setting '{name}' to '{value}'")
+    else:
+        print(f"[INFO]: setting '{name}' to [{len(value)} chars]")
+    print(f"::set-output name={name}::{value}")
+
+
+def http_get(
+    url: str,
+    is_json: bool = True,
+    headers: Optional[Dict[str, str]] = None,
+    **kwargs: Any,
+) -> Any:
+    headers = headers or {}
+    headers["User-Agent"] = USER_AGENT
+    if "github" in url:
+        if GH_API_TOKEN:
+            headers["Authorization"] = f"token {GH_API_TOKEN}"
+        headers["Accept"] = "application/vnd.github.v3+json"
+    r = http.request("GET", url, headers=headers, **kwargs)
+    if is_json:
+        data = json.loads(r.data.decode("utf-8"))
+    else:
+        data = r.data
+    print(f"[INFO]: issued GET request for {r.geturl()}")
+    if not (200 <= r.status < 300):
+        pprint.pprint(dict(r.info()))
+        pprint.pprint(data)
+        raise RuntimeError(f"unexpected status code: {r.status}")
+
+    return data
+
+
+def get_branch_or_tag_revision(sha: str = "main") -> str:
+    data = http_get(
+        f"https://api.github.com/repos/{REPO}/commits",
+        fields={"per_page": "1", "sha": sha},
+    )
+    assert isinstance(data[0]["sha"], str)
+    return data[0]["sha"]
+
+
+def get_pr_revision(pr: int) -> str:
+    data = http_get(f"https://api.github.com/repos/{REPO}/pulls/{pr}")
+    assert isinstance(data["head"]["sha"], str)
+    return data["head"]["sha"]
+
+
+def get_pypi_version() -> Version:
+    data = http_get("https://pypi.org/pypi/black/json")
+    versions = [Version(v) for v in data["releases"]]
+    sorted_versions = sorted(versions, reverse=True)
+    return sorted_versions[0]
+
+
+def resolve_custom_ref(ref: str) -> Tuple[str, str]:
+    if ref == ".pypi":
+        # Special value to get latest PyPI version.
+        version = str(get_pypi_version())
+        return version, f"git checkout {version}"
+
+    if ref.startswith(".") and ref[1:].isnumeric():
+        # Special format to get a PR.
+        number = int(ref[1:])
+        revision = get_pr_revision(number)
+        return (
+            f"pr-{number}-{revision[:SHA_LENGTH]}",
+            f"gh pr checkout {number} && git merge origin/main",
+        )
+
+    # Alright, it's probably a branch, tag, or a commit SHA, let's find out!
+    revision = get_branch_or_tag_revision(ref)
+    # We're cutting the revision short as we might be operating on a short commit SHA.
+    if revision == ref or revision[: len(ref)] == ref:
+        # It's *probably* a commit as the resolved SHA isn't different from the REF.
+        return revision[:SHA_LENGTH], f"git checkout {revision}"
+
+    # It's *probably* a pre-existing branch or tag, yay!
+    return f"{ref}-{revision[:SHA_LENGTH]}", f"git checkout {revision}"
+
+
+@click.group()
+def main() -> None:
+    pass
+
+
+@main.command("config", help="Acquire run configuration and metadata.")
+@click.argument(
+    "event", type=click.Choice(["push", "pull_request", "workflow_dispatch"])
+)
+@click.argument("custom_baseline", required=False)
+@click.argument("custom_target", required=False)
+@click.option("--baseline-args", default="")
+def config(
+    event: Literal["push", "pull_request", "workflow_dispatch"],
+    custom_baseline: Optional[str],
+    custom_target: Optional[str],
+    baseline_args: str,
+) -> None:
+    import diff_shades
+
+    if event == "push":
+        # Push on main, let's use PyPI Black as the baseline.
+        baseline_name = str(get_pypi_version())
+        baseline_cmd = f"git checkout {baseline_name}"
+        target_rev = os.getenv("GITHUB_SHA")
+        assert target_rev is not None
+        target_name = "main-" + target_rev[:SHA_LENGTH]
+        target_cmd = f"git checkout {target_rev}"
+
+    elif event == "pull_request":
+        # PR, let's use main as the baseline.
+        baseline_rev = get_branch_or_tag_revision()
+        baseline_name = "main-" + baseline_rev[:SHA_LENGTH]
+        baseline_cmd = f"git checkout {baseline_rev}"
+
+        pr_ref = os.getenv("GITHUB_REF")
+        assert pr_ref is not None
+        pr_num = int(pr_ref[10:-6])
+        pr_rev = get_pr_revision(pr_num)
+        target_name = f"pr-{pr_num}-{pr_rev[:SHA_LENGTH]}"
+        target_cmd = f"gh pr checkout {pr_num} && git merge origin/main"
+
+        # These are only needed for the PR comment.
+        set_output("baseline-sha", baseline_rev)
+        set_output("target-sha", pr_rev)
+    else:
+        assert custom_baseline is not None and custom_target is not None
+        baseline_name, baseline_cmd = resolve_custom_ref(custom_baseline)
+        target_name, target_cmd = resolve_custom_ref(custom_target)
+        if baseline_name == target_name:
+            # Alright we're using the same revisions but we're (hopefully) using
+            # different command line arguments, let's support that too.
+            baseline_name += "-1"
+            target_name += "-2"
+
+    set_output("baseline-analysis", baseline_name + ".json")
+    set_output("baseline-setup-cmd", baseline_cmd)
+    set_output("target-analysis", target_name + ".json")
+    set_output("target-setup-cmd", target_cmd)
+
+    key = f"{platform.system()}-{platform.python_version()}-{diff_shades.__version__}"
+    key += f"-{baseline_name}-{baseline_args.encode('utf-8').hex()}"
+    set_output("baseline-cache-key", key)
+
+
+@main.command("comment-body", help="Generate the body for a summary PR comment.")
+@click.argument("baseline", type=click.Path(exists=True, path_type=Path))
+@click.argument("target", type=click.Path(exists=True, path_type=Path))
+@click.argument("baseline-sha")
+@click.argument("target-sha")
+def comment_body(
+    baseline: Path, target: Path, baseline_sha: str, target_sha: str
+) -> None:
+    # fmt: off
+    cmd = [
+        sys.executable, "-m", "diff_shades", "--no-color",
+        "compare", str(baseline), str(target), "--quiet", "--check"
+    ]
+    # fmt: on
+    proc = subprocess.run(cmd, stdout=subprocess.PIPE, encoding="utf-8")
+    if not proc.returncode:
+        body = (
+            f"**diff-shades** reports zero changes comparing this PR ({target_sha}) to"
+            f" main ({baseline_sha}).\n\n---\n\n"
+        )
+    else:
+        body = (
+            f"**diff-shades** results comparing this PR ({target_sha}) to main"
+            f" ({baseline_sha}). The full diff is [available in the logs]"
+            f'($job-diff-url) under the "{DIFF_STEP_NAME}" step.'
+        )
+        body += "\n```text\n" + proc.stdout.strip() + "\n```\n"
+    body += (
+        f"[**What is this?**]({DOCS_URL}) | [Workflow run]($workflow-run-url) |"
+        " [diff-shades documentation](https://github.com/ichard26/diff-shades#readme)"
+    )
+    print(f"[INFO]: writing half-completed comment body to {COMMENT_BODY_FILE}")
+    with open(COMMENT_BODY_FILE, "w", encoding="utf-8") as f:
+        f.write(body)
+
+
+@main.command("comment-details", help="Get PR comment resources from a workflow run.")
+@click.argument("run-id")
+def comment_details(run_id: str) -> None:
+    data = http_get(f"https://api.github.com/repos/{REPO}/actions/runs/{run_id}")
+    if data["event"] != "pull_request":
+        set_output("needs-comment", "false")
+        return
+
+    set_output("needs-comment", "true")
+    pulls = data["pull_requests"]
+    assert len(pulls) == 1
+    pr_number = pulls[0]["number"]
+    set_output("pr-number", str(pr_number))
+
+    jobs_data = http_get(data["jobs_url"])
+    assert len(jobs_data["jobs"]) == 1, "multiple jobs not supported nor tested"
+    job = jobs_data["jobs"][0]
+    steps = {s["name"]: s["number"] for s in job["steps"]}
+    diff_step = steps[DIFF_STEP_NAME]
+    diff_url = job["html_url"] + f"#step:{diff_step}:1"
+
+    artifacts_data = http_get(data["artifacts_url"])["artifacts"]
+    artifacts = {a["name"]: a["archive_download_url"] for a in artifacts_data}
+    body_url = artifacts[COMMENT_BODY_FILE]
+    body_zip = BytesIO(http_get(body_url, is_json=False))
+    with zipfile.ZipFile(body_zip) as zfile:
+        with zfile.open(COMMENT_BODY_FILE) as rf:
+            body = rf.read().decode("utf-8")
+    # It's more convenient to fill in these fields after the first workflow is done
+    # since this command can access the workflows API (doing it in the main workflow
+    # while it's still in progress seems impossible).
+    body = body.replace("$workflow-run-url", data["html_url"])
+    body = body.replace("$job-diff-url", diff_url)
+    # # https://github.community/t/set-output-truncates-multiline-strings/16852/3
+    escaped = body.replace("%", "%25").replace("\n", "%0A").replace("\r", "%0D")
+    set_output("comment-body", escaped)
+
+
+if __name__ == "__main__":
+    main()

From 5fe6d48fcd687a972278048d3bfeec9e2040ed64 Mon Sep 17 00:00:00 2001
From: Marco Edward Gorelli <marcogorelli@protonmail.com>
Date: Sat, 15 Jan 2022 04:24:55 +0000
Subject: [PATCH 0418/1034] Dont require typing-extensions in 3.10 (GH-2772)

3.10 ships with TypeGuard which is the newest feature we need.

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 CHANGES.md | 1 +
 setup.py   | 5 +----
 2 files changed, 2 insertions(+), 4 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 6813e86e0da..32059a30548 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -34,6 +34,7 @@
 ### Packaging
 
 - All upper version bounds on dependencies have been removed (#2718)
+- `typing-extensions` is no longer a required dependency in Python 3.10+ (#2772)
 
 ### Integrations
 
diff --git a/setup.py b/setup.py
index 57632498deb..c31baab00ae 100644
--- a/setup.py
+++ b/setup.py
@@ -103,10 +103,7 @@ def find_python_files(base: Path) -> List[Path]:
         "typed-ast>=1.4.2; python_version < '3.8' and implementation_name == 'cpython'",
         "pathspec>=0.9.0",
         "dataclasses>=0.6; python_version < '3.7'",
-        "typing_extensions>=3.10.0.0",
-        # 3.10.0.1 is broken on at least Python 3.10,
-        # https://github.com/python/typing/issues/865
-        "typing_extensions!=3.10.0.1; python_version >= '3.10'",
+        "typing_extensions>=3.10.0.0; python_version < '3.10'",
         "mypy_extensions>=0.4.3",
     ],
     extras_require={

From 33e3bb1e4e326713f85749705179da2e31520670 Mon Sep 17 00:00:00 2001
From: Batuhan Taskaya <isidentical@gmail.com>
Date: Sun, 16 Jan 2022 01:19:37 +0300
Subject: [PATCH 0419/1034] [trivial] Use proper test cases on `unittest`
 (#2775)

---
 tests/test_black.py  | 4 ++--
 tests/test_primer.py | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/tests/test_black.py b/tests/test_black.py
index 91d10581f6f..202fe23ddcd 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -940,8 +940,8 @@ def err(msg: str, **kwargs: Any) -> None:
                 self.assertFormatEqual("j = [1, 2, 3]", "j = [1, 2, 3,]")
 
         out_str = "".join(out_lines)
-        self.assertTrue("Expected tree:" in out_str)
-        self.assertTrue("Actual tree:" in out_str)
+        self.assertIn("Expected tree:", out_str)
+        self.assertIn("Actual tree:", out_str)
         self.assertEqual("".join(err_lines), "")
 
     @event_loop()
diff --git a/tests/test_primer.py b/tests/test_primer.py
index 9bb401574ca..0a9d2aec495 100644
--- a/tests/test_primer.py
+++ b/tests/test_primer.py
@@ -181,7 +181,7 @@ def test_gen_check_output(self) -> None:
         stdout, stderr = loop.run_until_complete(
             lib._gen_check_output([lib.BLACK_BINARY, "--help"])
         )
-        self.assertTrue("The uncompromising code formatter" in stdout.decode("utf8"))
+        self.assertIn("The uncompromising code formatter", stdout.decode("utf8"))
         self.assertEqual(None, stderr)
 
         # TODO: Add a test to see failure works on Windows

From 1d2ed2bb421df94a8d86728a187663f1c3898322 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 17 Jan 2022 06:50:27 -0800
Subject: [PATCH 0420/1034] Bump sphinx from 4.3.2 to 4.4.0 in /docs (#2776)

Bumps [sphinx](https://github.com/sphinx-doc/sphinx) from 4.3.2 to 4.4.0.
- [Release notes](https://github.com/sphinx-doc/sphinx/releases)
- [Changelog](https://github.com/sphinx-doc/sphinx/blob/4.x/CHANGES)
- [Commits](https://github.com/sphinx-doc/sphinx/compare/v4.3.2...v4.4.0)

---
updated-dependencies:
- dependency-name: sphinx
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 docs/requirements.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index 0cdef2a39dd..02874d3c255 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,6 +1,6 @@
 # Used by ReadTheDocs; pinned requirements for stability.
 
 myst-parser==0.16.1
-Sphinx==4.3.2
+Sphinx==4.4.0
 sphinxcontrib-programoutput==0.17
 sphinx_copybutton==0.4.0

From 98db4abc21477cbd247c8fbd4cf9e8d1cf61ca0f Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Mon, 17 Jan 2022 07:52:29 -0800
Subject: [PATCH 0421/1034] Fix typo in diff_shades.yml workflow (#2778)

---
 .github/workflows/diff_shades.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/diff_shades.yml b/.github/workflows/diff_shades.yml
index b6a9b3355fb..a8a443e2cce 100644
--- a/.github/workflows/diff_shades.yml
+++ b/.github/workflows/diff_shades.yml
@@ -6,7 +6,7 @@ on:
     paths-ignore: ["docs/**", "tests/**", "*.md"]
 
   pull_request:
-    path-ignore: ["docs/**", "tests/**", "*.md"]
+    paths-ignore: ["docs/**", "tests/**", "*.md"]
 
   workflow_dispatch:
     inputs:

From 8c22d232b56104376a12d1e68eaf216d04979830 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Felix=20Hild=C3=A9n?= <felix.hilden@gmail.com>
Date: Thu, 20 Jan 2022 03:34:52 +0200
Subject: [PATCH 0422/1034] Create --preview CLI flag (#2752)

---
 CHANGES.md                                |  4 ++++
 docs/contributing/the_basics.md           |  4 +++-
 docs/the_black_code_style/future_style.md |  6 ++++++
 docs/the_black_code_style/index.rst       |  2 +-
 src/black/__init__.py                     | 10 ++++++++++
 src/black/mode.py                         | 15 +++++++++++++++
 tests/test_format.py                      | 17 ++++++++++++-----
 7 files changed, 51 insertions(+), 7 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 32059a30548..4b9ceae81dc 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -36,6 +36,10 @@
 - All upper version bounds on dependencies have been removed (#2718)
 - `typing-extensions` is no longer a required dependency in Python 3.10+ (#2772)
 
+### Preview style
+
+- Introduce the `--preview` flag with no style changes (#2752)
+
 ### Integrations
 
 - Update GitHub action to support containerized runs (#2748)
diff --git a/docs/contributing/the_basics.md b/docs/contributing/the_basics.md
index 9a639731073..23fbb8a3d7e 100644
--- a/docs/contributing/the_basics.md
+++ b/docs/contributing/the_basics.md
@@ -55,7 +55,9 @@ go back and workout what to add to the `CHANGES.md` for each release.
 
 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.
+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.
 
 ### Docs Testing
 
diff --git a/docs/the_black_code_style/future_style.md b/docs/the_black_code_style/future_style.md
index a7676090553..70ffeefc76a 100644
--- a/docs/the_black_code_style/future_style.md
+++ b/docs/the_black_code_style/future_style.md
@@ -40,3 +40,9 @@ Currently, _Black_ does not split long strings to fit the line length limit. Cur
 there is [an experimental option](labels/experimental-string) to enable splitting
 strings. We plan to enable this option by default once it is fully stable. This is
 tracked in [this issue](https://github.com/psf/black/issues/2188).
+
+## Preview style
+
+Experimental, potentially disruptive style changes are gathered under the `--preview`
+CLI flag. At the end of each year, these changes may be adopted into the default style,
+as described in [The Black Code Style](./index.rst).
diff --git a/docs/the_black_code_style/index.rst b/docs/the_black_code_style/index.rst
index d53703277e4..3952a174223 100644
--- a/docs/the_black_code_style/index.rst
+++ b/docs/the_black_code_style/index.rst
@@ -32,7 +32,7 @@ versions of *Black*:
   improved formatting enabled by newer Python language syntax as well as due
   to improvements in the formatting logic.
 
-- The ``--future`` flag is exempt from this policy. There are no guarantees
+- The ``--preview`` flag is exempt from this policy. There are no guarantees
   around the stability of the output with that flag passed into *Black*. This
   flag is intended for allowing experimentation with the proposed changes to
   the *Black* code style.
diff --git a/src/black/__init__.py b/src/black/__init__.py
index fa918ce2931..405a01082e7 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -246,6 +246,14 @@ def validate_regex(
         " Currently disabled because it leads to some crashes."
     ),
 )
+@click.option(
+    "--preview",
+    is_flag=True,
+    help=(
+        "Enable potentially disruptive style changes that will be added to Black's main"
+        " functionality in the next major release."
+    ),
+)
 @click.option(
     "--check",
     is_flag=True,
@@ -399,6 +407,7 @@ def main(
     skip_string_normalization: bool,
     skip_magic_trailing_comma: bool,
     experimental_string_processing: bool,
+    preview: bool,
     quiet: bool,
     verbose: bool,
     required_version: Optional[str],
@@ -469,6 +478,7 @@ def main(
         string_normalization=not skip_string_normalization,
         magic_trailing_comma=not skip_magic_trailing_comma,
         experimental_string_processing=experimental_string_processing,
+        preview=preview,
     )
 
     if code is not None:
diff --git a/src/black/mode.py b/src/black/mode.py
index 5e04525cfc9..c8c2bd4eb26 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -121,6 +121,10 @@ def supports_feature(target_versions: Set[TargetVersion], feature: Feature) -> b
     return all(feature in VERSION_TO_FEATURES[version] for version in target_versions)
 
 
+class Preview(Enum):
+    """Individual preview style features."""
+
+
 @dataclass
 class Mode:
     target_versions: Set[TargetVersion] = field(default_factory=set)
@@ -130,6 +134,16 @@ class Mode:
     is_ipynb: bool = False
     magic_trailing_comma: bool = True
     experimental_string_processing: bool = False
+    preview: bool = False
+
+    def __contains__(self, feature: Preview) -> bool:
+        """
+        Provide `Preview.FEATURE in Mode` syntax that mirrors the ``preview`` flag.
+
+        The argument is not checked and features are not differentiated.
+        They only exist to make development easier by clarifying intent.
+        """
+        return self.preview
 
     def get_cache_key(self) -> str:
         if self.target_versions:
@@ -147,5 +161,6 @@ def get_cache_key(self) -> str:
             str(int(self.is_ipynb)),
             str(int(self.magic_trailing_comma)),
             str(int(self.experimental_string_processing)),
+            str(int(self.preview)),
         ]
         return ".".join(parts)
diff --git a/tests/test_format.py b/tests/test_format.py
index db39678cdfe..00cd07f36f7 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -1,5 +1,5 @@
 from dataclasses import replace
-from typing import Any, Iterator
+from typing import Any, Iterator, List
 from unittest.mock import patch
 
 import pytest
@@ -14,7 +14,7 @@
     read_data,
 )
 
-SIMPLE_CASES = [
+SIMPLE_CASES: List[str] = [
     "beginning_backslash",
     "bracketmatch",
     "class_blank_parentheses",
@@ -55,7 +55,7 @@
     "tupleassign",
 ]
 
-EXPERIMENTAL_STRING_PROCESSING_CASES = [
+EXPERIMENTAL_STRING_PROCESSING_CASES: List[str] = [
     "cantfit",
     "comments7",
     "long_strings",
@@ -64,7 +64,7 @@
     "percent_precedence",
 ]
 
-PY310_CASES = [
+PY310_CASES: List[str] = [
     "pattern_matching_simple",
     "pattern_matching_complex",
     "pattern_matching_extras",
@@ -73,7 +73,9 @@
     "parenthesized_context_managers",
 ]
 
-SOURCES = [
+PREVIEW_CASES: List[str] = []
+
+SOURCES: List[str] = [
     "src/black/__init__.py",
     "src/black/__main__.py",
     "src/black/brackets.py",
@@ -139,6 +141,11 @@ def test_experimental_format(filename: str) -> None:
     check_file(filename, black.Mode(experimental_string_processing=True))
 
 
+@pytest.mark.parametrize("filename", PREVIEW_CASES)
+def test_preview_format(filename: str) -> None:
+    check_file(filename, black.Mode(preview=True))
+
+
 @pytest.mark.parametrize("filename", SOURCES)
 def test_source_is_formatted(filename: str) -> None:
     path = THIS_DIR.parent / filename

From 9bd4134f3138448eb92af7031d994b2cec7d08ad Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Wed, 19 Jan 2022 22:05:58 -0500
Subject: [PATCH 0423/1034] Fix and speedup diff-shades integration  (#2773)

---
 .github/mypyc-requirements.txt            | 14 ++++++
 .github/workflows/diff_shades.yml         | 32 ++++++++++----
 .github/workflows/diff_shades_comment.yml |  4 +-
 docs/contributing/gauging_changes.md      |  2 +-
 scripts/diff_shades_gha_helper.py         | 54 +++++++++++------------
 src/black/parsing.py                      |  3 +-
 6 files changed, 68 insertions(+), 41 deletions(-)
 create mode 100644 .github/mypyc-requirements.txt

diff --git a/.github/mypyc-requirements.txt b/.github/mypyc-requirements.txt
new file mode 100644
index 00000000000..4542673174c
--- /dev/null
+++ b/.github/mypyc-requirements.txt
@@ -0,0 +1,14 @@
+mypy == 0.920
+
+# A bunch of packages for type information
+mypy-extensions >= 0.4.3
+tomli >= 0.10.2
+types-typed-ast >= 1.4.2
+types-dataclasses >= 0.1.3
+typing-extensions > 3.10.0.1
+click >= 8.0.0
+platformdirs >= 2.1.0
+
+# And because build isolation is disabled, we'll need to pull this too
+setuptools-scm[toml] >= 6.3.1
+wheel
diff --git a/.github/workflows/diff_shades.yml b/.github/workflows/diff_shades.yml
index a8a443e2cce..68cc2383306 100644
--- a/.github/workflows/diff_shades.yml
+++ b/.github/workflows/diff_shades.yml
@@ -3,10 +3,10 @@ name: diff-shades
 on:
   push:
     branches: [main]
-    paths-ignore: ["docs/**", "tests/**", "*.md"]
+    paths-ignore: ["docs/**", "tests/**", "**.md", "**.rst"]
 
   pull_request:
-    paths-ignore: ["docs/**", "tests/**", "*.md"]
+    paths-ignore: ["docs/**", "tests/**", "**.md", "**.rst"]
 
   workflow_dispatch:
     inputs:
@@ -27,10 +27,18 @@ on:
         description: "Custom Black arguments (eg. -S)"
         required: false
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.run_id }}
+  cancel-in-progress: true
+
 jobs:
   analysis:
     name: analysis / linux
     runs-on: ubuntu-latest
+    env:
+      # Clang is less picky with the C code it's given than gcc (and may
+      # generate faster binaries too).
+      CC: clang-12
 
     steps:
       - name: Checkout this repository (full clone)
@@ -45,6 +53,7 @@ jobs:
           python -m pip install pip --upgrade
           python -m pip install https://github.com/ichard26/diff-shades/archive/stable.zip
           python -m pip install click packaging urllib3
+          python -m pip install -r .github/mypyc-requirements.txt
           # After checking out old revisions, this might not exist so we'll use a copy.
           cat scripts/diff_shades_gha_helper.py > helper.py
           git config user.name "diff-shades-gha"
@@ -66,11 +75,14 @@ jobs:
           path: ${{ steps.config.outputs.baseline-analysis }}
           key: ${{ steps.config.outputs.baseline-cache-key }}
 
-      - name: Install baseline revision
+      - name: Build and install baseline revision
         if: steps.baseline-cache.outputs.cache-hit != 'true'
         env:
           GITHUB_TOKEN: ${{ github.token }}
-        run: ${{ steps.config.outputs.baseline-setup-cmd }} && python -m pip install .
+        run: >
+          ${{ steps.config.outputs.baseline-setup-cmd }}
+          && python setup.py --use-mypyc bdist_wheel
+          && python -m pip install dist/*.whl && rm build dist -r
 
       - name: Analyze baseline revision
         if: steps.baseline-cache.outputs.cache-hit != 'true'
@@ -78,10 +90,13 @@ jobs:
           diff-shades analyze -v --work-dir projects-cache/
           ${{ steps.config.outputs.baseline-analysis }} -- ${{ github.event.inputs.baseline-args }}
 
-      - name: Install target revision
+      - name: Build and install target revision
         env:
           GITHUB_TOKEN: ${{ github.token }}
-        run: ${{ steps.config.outputs.target-setup-cmd }} && python -m pip install .
+        run: >
+          ${{ steps.config.outputs.target-setup-cmd }}
+          && python setup.py --use-mypyc bdist_wheel
+          && python -m pip install dist/*.whl
 
       - name: Analyze target revision
         run: >
@@ -118,13 +133,14 @@ jobs:
           python helper.py comment-body
           ${{ steps.config.outputs.baseline-analysis }} ${{ steps.config.outputs.target-analysis }}
           ${{ steps.config.outputs.baseline-sha }} ${{ steps.config.outputs.target-sha }}
+          ${{ github.event.pull_request.number }}
 
       - name: Upload summary file (PR only)
         if: github.event_name == 'pull_request'
         uses: actions/upload-artifact@v2
         with:
-          name: .pr-comment-body.md
-          path: .pr-comment-body.md
+          name: .pr-comment.json
+          path: .pr-comment.json
 
         # This is last so the diff-shades-comment workflow can still work even if we
         # end up detecting failed files and failing the run.
diff --git a/.github/workflows/diff_shades_comment.yml b/.github/workflows/diff_shades_comment.yml
index bdd90321800..0433bbbf85f 100644
--- a/.github/workflows/diff_shades_comment.yml
+++ b/.github/workflows/diff_shades_comment.yml
@@ -31,7 +31,7 @@ jobs:
       - name: Try to find pre-existing PR comment
         if: steps.metadata.outputs.needs-comment == 'true'
         id: find-comment
-        uses: peter-evans/find-comment@v1
+        uses: peter-evans/find-comment@d2dae40ed151c634e4189471272b57e76ec19ba8
         with:
           issue-number: ${{ steps.metadata.outputs.pr-number }}
           comment-author: "github-actions[bot]"
@@ -39,7 +39,7 @@ jobs:
 
       - name: Create or update PR comment
         if: steps.metadata.outputs.needs-comment == 'true'
-        uses: peter-evans/create-or-update-comment@v1
+        uses: peter-evans/create-or-update-comment@a35cf36e5301d70b76f316e867e7788a55a31dae
         with:
           comment-id: ${{ steps.find-comment.outputs.comment-id }}
           issue-number: ${{ steps.metadata.outputs.pr-number }}
diff --git a/docs/contributing/gauging_changes.md b/docs/contributing/gauging_changes.md
index 3cfa98b3df8..9b38fe1b628 100644
--- a/docs/contributing/gauging_changes.md
+++ b/docs/contributing/gauging_changes.md
@@ -74,7 +74,7 @@ to further information. If there's a pre-existing diff-shades comment, it'll be
 instead the next time the workflow is triggered on the same PR.
 
 The workflow uploads 3-4 artifacts upon completion: the two generated analyses (they
-have the .json file extension), `diff.html`, and `.pr-comment-body.md` if triggered by a
+have the .json file extension), `diff.html`, and `.pr-comment.json` if triggered by a
 PR. The last one is downloaded by the `diff-shades-comment` workflow and shouldn't be
 downloaded locally. `diff.html` comes in handy for push-based or manually triggered
 runs. And the analyses exist just in case you want to do further analysis using the
diff --git a/scripts/diff_shades_gha_helper.py b/scripts/diff_shades_gha_helper.py
index 21e04a590a1..f1f7f2be91c 100644
--- a/scripts/diff_shades_gha_helper.py
+++ b/scripts/diff_shades_gha_helper.py
@@ -23,7 +23,7 @@
 import zipfile
 from io import BytesIO
 from pathlib import Path
-from typing import Any, Dict, Optional, Tuple
+from typing import Any, Optional, Tuple
 
 import click
 import urllib3
@@ -34,7 +34,7 @@
 else:
     from typing_extensions import Final, Literal
 
-COMMENT_BODY_FILE: Final = ".pr-comment-body.md"
+COMMENT_FILE: Final = ".pr-comment.json"
 DIFF_STEP_NAME: Final = "Generate HTML diff report"
 DOCS_URL: Final = (
     "https://black.readthedocs.io/en/latest/"
@@ -55,19 +55,16 @@ def set_output(name: str, value: str) -> None:
     print(f"::set-output name={name}::{value}")
 
 
-def http_get(
-    url: str,
-    is_json: bool = True,
-    headers: Optional[Dict[str, str]] = None,
-    **kwargs: Any,
-) -> Any:
-    headers = headers or {}
+def http_get(url: str, is_json: bool = True, **kwargs: Any) -> Any:
+    headers = kwargs.get("headers") or {}
     headers["User-Agent"] = USER_AGENT
     if "github" in url:
         if GH_API_TOKEN:
             headers["Authorization"] = f"token {GH_API_TOKEN}"
         headers["Accept"] = "application/vnd.github.v3+json"
-    r = http.request("GET", url, headers=headers, **kwargs)
+    kwargs["headers"] = headers
+
+    r = http.request("GET", url, **kwargs)
     if is_json:
         data = json.loads(r.data.decode("utf-8"))
     else:
@@ -199,8 +196,9 @@ def config(
 @click.argument("target", type=click.Path(exists=True, path_type=Path))
 @click.argument("baseline-sha")
 @click.argument("target-sha")
+@click.argument("pr-num", type=int)
 def comment_body(
-    baseline: Path, target: Path, baseline_sha: str, target_sha: str
+    baseline: Path, target: Path, baseline_sha: str, target_sha: str, pr_num: int
 ) -> None:
     # fmt: off
     cmd = [
@@ -225,45 +223,43 @@ def comment_body(
         f"[**What is this?**]({DOCS_URL}) | [Workflow run]($workflow-run-url) |"
         " [diff-shades documentation](https://github.com/ichard26/diff-shades#readme)"
     )
-    print(f"[INFO]: writing half-completed comment body to {COMMENT_BODY_FILE}")
-    with open(COMMENT_BODY_FILE, "w", encoding="utf-8") as f:
-        f.write(body)
+    print(f"[INFO]: writing comment details to {COMMENT_FILE}")
+    with open(COMMENT_FILE, "w", encoding="utf-8") as f:
+        json.dump({"body": body, "pr-number": pr_num}, f)
 
 
 @main.command("comment-details", help="Get PR comment resources from a workflow run.")
 @click.argument("run-id")
 def comment_details(run_id: str) -> None:
     data = http_get(f"https://api.github.com/repos/{REPO}/actions/runs/{run_id}")
-    if data["event"] != "pull_request":
+    if data["event"] != "pull_request" or data["conclusion"] == "cancelled":
         set_output("needs-comment", "false")
         return
 
     set_output("needs-comment", "true")
-    pulls = data["pull_requests"]
-    assert len(pulls) == 1
-    pr_number = pulls[0]["number"]
-    set_output("pr-number", str(pr_number))
-
-    jobs_data = http_get(data["jobs_url"])
-    assert len(jobs_data["jobs"]) == 1, "multiple jobs not supported nor tested"
-    job = jobs_data["jobs"][0]
+    jobs = http_get(data["jobs_url"])["jobs"]
+    assert len(jobs) == 1, "multiple jobs not supported nor tested"
+    job = jobs[0]
     steps = {s["name"]: s["number"] for s in job["steps"]}
     diff_step = steps[DIFF_STEP_NAME]
     diff_url = job["html_url"] + f"#step:{diff_step}:1"
 
     artifacts_data = http_get(data["artifacts_url"])["artifacts"]
     artifacts = {a["name"]: a["archive_download_url"] for a in artifacts_data}
-    body_url = artifacts[COMMENT_BODY_FILE]
-    body_zip = BytesIO(http_get(body_url, is_json=False))
-    with zipfile.ZipFile(body_zip) as zfile:
-        with zfile.open(COMMENT_BODY_FILE) as rf:
-            body = rf.read().decode("utf-8")
+    comment_url = artifacts[COMMENT_FILE]
+    comment_zip = BytesIO(http_get(comment_url, is_json=False))
+    with zipfile.ZipFile(comment_zip) as zfile:
+        with zfile.open(COMMENT_FILE) as rf:
+            comment_data = json.loads(rf.read().decode("utf-8"))
+
+    set_output("pr-number", str(comment_data["pr-number"]))
+    body = comment_data["body"]
     # It's more convenient to fill in these fields after the first workflow is done
     # since this command can access the workflows API (doing it in the main workflow
     # while it's still in progress seems impossible).
     body = body.replace("$workflow-run-url", data["html_url"])
     body = body.replace("$job-diff-url", diff_url)
-    # # https://github.community/t/set-output-truncates-multiline-strings/16852/3
+    # https://github.community/t/set-output-truncates-multiline-strings/16852/3
     escaped = body.replace("%", "%25").replace("\n", "%0A").replace("\r", "%0D")
     set_output("comment-body", escaped)
 
diff --git a/src/black/parsing.py b/src/black/parsing.py
index 13fa67ee84d..6b63368871c 100644
--- a/src/black/parsing.py
+++ b/src/black/parsing.py
@@ -206,7 +206,7 @@ def stringify_ast(node: Union[ast.AST, ast3.AST], depth: int = 0) -> Iterator[st
                 break
 
         try:
-            value = getattr(node, field)
+            value: object = getattr(node, field)
         except AttributeError:
             continue
 
@@ -237,6 +237,7 @@ def stringify_ast(node: Union[ast.AST, ast3.AST], depth: int = 0) -> Iterator[st
             yield from stringify_ast(value, depth + 2)
 
         else:
+            normalized: object
             # Constant strings may be indented across newlines, if they are
             # docstrings; fold spaces after newlines when comparing. Similarly,
             # trailing and leading space may be removed.

From 6e97c5f47cbec72c72c27aefb206589dd84707a7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Felix=20Hild=C3=A9n?= <felix.hilden@gmail.com>
Date: Fri, 21 Jan 2022 01:42:07 +0200
Subject: [PATCH 0424/1034] Deprecate ESP and move the functionality under
 --preview (#2789)

---
 CHANGES.md                                 |  5 ++++-
 docs/faq.md                                |  2 +-
 docs/the_black_code_style/current_style.md | 14 ++++---------
 docs/the_black_code_style/future_style.md  | 19 +++++++++--------
 src/black/__init__.py                      |  5 +----
 src/black/linegen.py                       |  7 +++----
 src/black/mode.py                          | 20 +++++++++++++++++-
 tests/test_black.py                        |  7 ++++++-
 tests/test_format.py                       | 24 ++++++++--------------
 9 files changed, 58 insertions(+), 45 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 4b9ceae81dc..c3e2a3350d3 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -30,6 +30,8 @@
 - Fix handling of standalone `match()` or `case()` when there is a trailing newline or a
   comment inside of the parentheses. (#2760)
 - Black now normalizes string prefix order (#2297)
+- Deprecate `--experimental-string-processing` and move the functionality under
+  `--preview` (#2789)
 
 ### Packaging
 
@@ -38,7 +40,8 @@
 
 ### Preview style
 
-- Introduce the `--preview` flag with no style changes (#2752)
+- Introduce the `--preview` flag (#2752)
+- Add `--experimental-string-processing` to the preview style (#2789)
 
 ### Integrations
 
diff --git a/docs/faq.md b/docs/faq.md
index c7d5ec33ad9..94a978d826f 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -33,7 +33,7 @@ still proposed on the issue tracker. See
 
 Starting in 2022, the formatting output will be stable for the releases made in the same
 year (other than unintentional bugs). It is possible to opt-in to the latest formatting
-styles, using the `--future` flag.
+styles, using the `--preview` flag.
 
 ## Why is my file not formatted?
 
diff --git a/docs/the_black_code_style/current_style.md b/docs/the_black_code_style/current_style.md
index 11fe2c8cceb..1d1e42e75c8 100644
--- a/docs/the_black_code_style/current_style.md
+++ b/docs/the_black_code_style/current_style.md
@@ -10,6 +10,10 @@ with `# fmt: off` and end with `# fmt: on`, or lines that ends with `# fmt: skip
 [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
+running `black --preview`.
+
 ### How _Black_ wraps lines
 
 _Black_ ignores previous formatting and applies uniform horizontal and vertical
@@ -260,16 +264,6 @@ If you are adopting _Black_ in a large project with pre-existing string conventi
 you can pass `--skip-string-normalization` on the command line. This is meant as an
 adoption helper, avoid using this for new projects.
 
-(labels/experimental-string)=
-
-As an experimental option (can be enabled by `--experimental-string-processing`),
-_Black_ splits long strings (using parentheses where appropriate) and merges short ones.
-When split, parts of f-strings that don't need formatting are converted to plain
-strings. User-made splits are respected when they do not exceed the line length limit.
-Line continuation backslashes are converted into parenthesized strings. Unnecessary
-parentheses are stripped. Because the functionality is experimental, feedback and issue
-reports are highly encouraged!
-
 _Black_ also processes docstrings. Firstly the indentation of docstrings is corrected
 for both quotations and the text within, although relative indentation in the text is
 preserved. Superfluous trailing whitespace on each line and unnecessary new lines at the
diff --git a/docs/the_black_code_style/future_style.md b/docs/the_black_code_style/future_style.md
index 70ffeefc76a..2ec2c0333a5 100644
--- a/docs/the_black_code_style/future_style.md
+++ b/docs/the_black_code_style/future_style.md
@@ -34,15 +34,18 @@ with \
 Although when the target version is Python 3.9 or higher, _Black_ will use parentheses
 instead since they're allowed in Python 3.9 and higher.
 
-## Improved string processing
-
-Currently, _Black_ does not split long strings to fit the line length limit. Currently,
-there is [an experimental option](labels/experimental-string) to enable splitting
-strings. We plan to enable this option by default once it is fully stable. This is
-tracked in [this issue](https://github.com/psf/black/issues/2188).
-
 ## Preview style
 
 Experimental, potentially disruptive style changes are gathered under the `--preview`
 CLI flag. At the end of each year, these changes may be adopted into the default style,
-as described in [The Black Code Style](./index.rst).
+as described in [The Black Code Style](./index.rst). Because the functionality is
+experimental, feedback and issue reports are highly encouraged!
+
+### Improved string processing
+
+_Black_ will split long string literals and merge short ones. Parentheses are used where
+appropriate. When split, parts of f-strings that don't need formatting are converted to
+plain strings. User-made splits are respected when they do not exceed the line length
+limit. Line continuation backslashes are converted into parenthesized strings.
+Unnecessary parentheses are stripped. The stability and status of this feature is
+tracked in [this issue](https://github.com/psf/black/issues/2188).
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 405a01082e7..67c272e3cc9 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -241,10 +241,7 @@ def validate_regex(
     "--experimental-string-processing",
     is_flag=True,
     hidden=True,
-    help=(
-        "Experimental option that performs more normalization on string literals."
-        " Currently disabled because it leads to some crashes."
-    ),
+    help="(DEPRECATED and now included in --preview) Normalize string literals.",
 )
 @click.option(
     "--preview",
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 6008c773f94..9ee42aaaf72 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -23,8 +23,7 @@
 from black.strings import normalize_string_prefix, normalize_string_quotes
 from black.trans import Transformer, CannotTransform, StringMerger
 from black.trans import StringSplitter, StringParenWrapper, StringParenStripper
-from black.mode import Mode
-from black.mode import Feature
+from black.mode import Mode, Feature, Preview
 
 from blib2to3.pytree import Node, Leaf
 from blib2to3.pgen2 import token
@@ -338,7 +337,7 @@ def transform_line(
         and not (line.inside_brackets and line.contains_standalone_comments())
     ):
         # Only apply basic string preprocessing, since lines shouldn't be split here.
-        if mode.experimental_string_processing:
+        if Preview.string_processing in mode:
             transformers = [string_merge, string_paren_strip]
         else:
             transformers = []
@@ -381,7 +380,7 @@ def _rhs(
         # via type ... https://github.com/mypyc/mypyc/issues/884
         rhs = type("rhs", (), {"__call__": _rhs})()
 
-        if mode.experimental_string_processing:
+        if Preview.string_processing in mode:
             if line.inside_brackets:
                 transformers = [
                     string_merge,
diff --git a/src/black/mode.py b/src/black/mode.py
index c8c2bd4eb26..b6d1a1fbbef 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -7,9 +7,10 @@
 import sys
 
 from dataclasses import dataclass, field
-from enum import Enum
+from enum import Enum, auto
 from operator import attrgetter
 from typing import Dict, Set
+from warnings import warn
 
 if sys.version_info < (3, 8):
     from typing_extensions import Final
@@ -124,6 +125,13 @@ def supports_feature(target_versions: Set[TargetVersion], feature: Feature) -> b
 class Preview(Enum):
     """Individual preview style features."""
 
+    string_processing = auto()
+    hug_simple_powers = auto()
+
+
+class Deprecated(UserWarning):
+    """Visible deprecation warning."""
+
 
 @dataclass
 class Mode:
@@ -136,6 +144,14 @@ class Mode:
     experimental_string_processing: bool = False
     preview: bool = False
 
+    def __post_init__(self) -> None:
+        if self.experimental_string_processing:
+            warn(
+                "`experimental string processing` has been included in `preview`"
+                " and deprecated. Use `preview` instead.",
+                Deprecated,
+            )
+
     def __contains__(self, feature: Preview) -> bool:
         """
         Provide `Preview.FEATURE in Mode` syntax that mirrors the ``preview`` flag.
@@ -143,6 +159,8 @@ def __contains__(self, feature: Preview) -> bool:
         The argument is not checked and features are not differentiated.
         They only exist to make development easier by clarifying intent.
         """
+        if feature is Preview.string_processing:
+            return self.preview or self.experimental_string_processing
         return self.preview
 
     def get_cache_key(self) -> str:
diff --git a/tests/test_black.py b/tests/test_black.py
index 202fe23ddcd..19cff23cb89 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -150,6 +150,11 @@ def test_empty_ff(self) -> None:
             os.unlink(tmp_file)
         self.assertFormatEqual(expected, actual)
 
+    def test_experimental_string_processing_warns(self) -> None:
+        self.assertWarns(
+            black.mode.Deprecated, black.Mode, experimental_string_processing=True
+        )
+
     def test_piping(self) -> None:
         source, expected = read_data("src/black/__init__", data=False)
         result = BlackRunner().invoke(
@@ -342,7 +347,7 @@ def test_detect_pos_only_arguments(self) -> None:
     @patch("black.dump_to_file", dump_to_stderr)
     def test_string_quotes(self) -> None:
         source, expected = read_data("string_quotes")
-        mode = black.Mode(experimental_string_processing=True)
+        mode = black.Mode(preview=True)
         assert_format(source, expected, mode)
         mode = replace(mode, string_normalization=False)
         not_normalized = fs(source, mode=mode)
diff --git a/tests/test_format.py b/tests/test_format.py
index 00cd07f36f7..40f225c9554 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -55,15 +55,6 @@
     "tupleassign",
 ]
 
-EXPERIMENTAL_STRING_PROCESSING_CASES: List[str] = [
-    "cantfit",
-    "comments7",
-    "long_strings",
-    "long_strings__edge_case",
-    "long_strings__regression",
-    "percent_precedence",
-]
-
 PY310_CASES: List[str] = [
     "pattern_matching_simple",
     "pattern_matching_complex",
@@ -73,7 +64,15 @@
     "parenthesized_context_managers",
 ]
 
-PREVIEW_CASES: List[str] = []
+PREVIEW_CASES: List[str] = [
+    # string processing
+    "cantfit",
+    "comments7",
+    "long_strings",
+    "long_strings__edge_case",
+    "long_strings__regression",
+    "percent_precedence",
+]
 
 SOURCES: List[str] = [
     "src/black/__init__.py",
@@ -136,11 +135,6 @@ def test_simple_format(filename: str) -> None:
     check_file(filename, DEFAULT_MODE)
 
 
-@pytest.mark.parametrize("filename", EXPERIMENTAL_STRING_PROCESSING_CASES)
-def test_experimental_format(filename: str) -> None:
-    check_file(filename, black.Mode(experimental_string_processing=True))
-
-
 @pytest.mark.parametrize("filename", PREVIEW_CASES)
 def test_preview_format(filename: str) -> None:
     check_file(filename, black.Mode(preview=True))

From e66e0f8ff046e532e8129c78894ca1c4095c5c8b Mon Sep 17 00:00:00 2001
From: emfdavid <84335963+emfdavid@users.noreply.github.com>
Date: Thu, 20 Jan 2022 18:48:49 -0500
Subject: [PATCH 0425/1034] Hint at likely cause of ast parsing failure in
 error message (#2786)

Co-authored-by: Batuhan Taskaya <isidentical@gmail.com>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 src/black/__init__.py | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index 67c272e3cc9..bdece687e45 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -1312,7 +1312,10 @@ def assert_equivalent(src: str, dst: str, *, pass_num: int = 1) -> None:
         src_ast = parse_ast(src)
     except Exception as exc:
         raise AssertionError(
-            f"cannot use --safe with this file; failed to parse source file: {exc}"
+            f"cannot use --safe with this file; failed to parse source file AST: "
+            f"{exc}\n"
+            f"This could be caused by running Black with an older Python version "
+            f"that does not support new syntax used in your source file."
         ) from exc
 
     try:

From 4ea75cd49521ed7fd8384e7a739e1abb1b6de46a Mon Sep 17 00:00:00 2001
From: Michael Marino <mmarino@gmail.com>
Date: Fri, 21 Jan 2022 01:45:28 +0100
Subject: [PATCH 0426/1034] Add support for custom python cell magics (#2744)

Fixes #2742.

This PR adds the ability to configure additional python cell magics. This
will allow formatting cells in Jupyter Notebooks that are using custom (python)
magics.
---
 CHANGES.md            |  2 ++
 src/black/__init__.py | 22 +++++++++++++--
 src/black/mode.py     |  3 ++
 tests/test.toml       |  1 +
 tests/test_black.py   |  1 +
 tests/test_ipynb.py   | 66 ++++++++++++++++++++++++++++++++++++++++---
 6 files changed, 88 insertions(+), 7 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index c3e2a3350d3..a2e5c0a4ff8 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -30,6 +30,8 @@
 - Fix handling of standalone `match()` or `case()` when there is a trailing newline or a
   comment inside of the parentheses. (#2760)
 - Black now normalizes string prefix order (#2297)
+- Add configuration option (`python-cell-magics`) to format cells with custom magics in
+  Jupyter Notebooks (#2744)
 - Deprecate `--experimental-string-processing` and move the functionality under
   `--preview` (#2789)
 
diff --git a/src/black/__init__.py b/src/black/__init__.py
index bdece687e45..eaf72f9c2b3 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -24,6 +24,7 @@
     MutableMapping,
     Optional,
     Pattern,
+    Sequence,
     Set,
     Sized,
     Tuple,
@@ -225,6 +226,16 @@ def validate_regex(
         "(useful when piping source on standard input)."
     ),
 )
+@click.option(
+    "--python-cell-magics",
+    multiple=True,
+    help=(
+        "When processing Jupyter Notebooks, add the given magic to the list"
+        f" of known python-magics ({', '.join(PYTHON_CELL_MAGICS)})."
+        " Useful for formatting cells with custom python magics."
+    ),
+    default=[],
+)
 @click.option(
     "-S",
     "--skip-string-normalization",
@@ -401,6 +412,7 @@ def main(
     fast: bool,
     pyi: bool,
     ipynb: bool,
+    python_cell_magics: Sequence[str],
     skip_string_normalization: bool,
     skip_magic_trailing_comma: bool,
     experimental_string_processing: bool,
@@ -476,6 +488,7 @@ def main(
         magic_trailing_comma=not skip_magic_trailing_comma,
         experimental_string_processing=experimental_string_processing,
         preview=preview,
+        python_cell_magics=set(python_cell_magics),
     )
 
     if code is not None:
@@ -981,7 +994,7 @@ def format_file_contents(src_contents: str, *, fast: bool, mode: Mode) -> FileCo
     return dst_contents
 
 
-def validate_cell(src: str) -> None:
+def validate_cell(src: str, mode: Mode) -> None:
     """Check that cell does not already contain TransformerManager transformations,
     or non-Python cell magics, which might cause tokenizer_rt to break because of
     indentations.
@@ -1000,7 +1013,10 @@ def validate_cell(src: str) -> None:
     """
     if any(transformed_magic in src for transformed_magic in TRANSFORMED_MAGICS):
         raise NothingChanged
-    if src[:2] == "%%" and src.split()[0][2:] not in PYTHON_CELL_MAGICS:
+    if (
+        src[:2] == "%%"
+        and src.split()[0][2:] not in PYTHON_CELL_MAGICS | mode.python_cell_magics
+    ):
         raise NothingChanged
 
 
@@ -1020,7 +1036,7 @@ def format_cell(src: str, *, fast: bool, mode: Mode) -> str:
     could potentially be automagics or multi-line magics, which
     are currently not supported.
     """
-    validate_cell(src)
+    validate_cell(src, mode)
     src_without_trailing_semicolon, has_trailing_semicolon = remove_trailing_semicolon(
         src
     )
diff --git a/src/black/mode.py b/src/black/mode.py
index b6d1a1fbbef..6d45e3dc4da 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -4,6 +4,7 @@
 chosen by the user.
 """
 
+from hashlib import md5
 import sys
 
 from dataclasses import dataclass, field
@@ -142,6 +143,7 @@ class Mode:
     is_ipynb: bool = False
     magic_trailing_comma: bool = True
     experimental_string_processing: bool = False
+    python_cell_magics: Set[str] = field(default_factory=set)
     preview: bool = False
 
     def __post_init__(self) -> None:
@@ -180,5 +182,6 @@ def get_cache_key(self) -> str:
             str(int(self.magic_trailing_comma)),
             str(int(self.experimental_string_processing)),
             str(int(self.preview)),
+            md5((",".join(sorted(self.python_cell_magics))).encode()).hexdigest(),
         ]
         return ".".join(parts)
diff --git a/tests/test.toml b/tests/test.toml
index d3ab1e61202..e5fb9228f19 100644
--- a/tests/test.toml
+++ b/tests/test.toml
@@ -7,6 +7,7 @@ line-length = 79
 target-version = ["py36", "py37", "py38"]
 exclude='\.pyi?$'
 include='\.py?$'
+python-cell-magics = ["custom1", "custom2"]
 
 [v1.0.0-syntax]
 # This shouldn't break Black.
diff --git a/tests/test_black.py b/tests/test_black.py
index 19cff23cb89..fd01425ae74 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -1322,6 +1322,7 @@ def test_parse_pyproject_toml(self) -> None:
         self.assertEqual(config["color"], True)
         self.assertEqual(config["line_length"], 79)
         self.assertEqual(config["target_version"], ["py36", "py37", "py38"])
+        self.assertEqual(config["python_cell_magics"], ["custom1", "custom2"])
         self.assertEqual(config["exclude"], r"\.pyi?$")
         self.assertEqual(config["include"], r"\.py?$")
 
diff --git a/tests/test_ipynb.py b/tests/test_ipynb.py
index fe8d67a7777..d78a68cd9a0 100644
--- a/tests/test_ipynb.py
+++ b/tests/test_ipynb.py
@@ -1,5 +1,8 @@
+from dataclasses import replace
 import pathlib
 import re
+from contextlib import ExitStack as does_not_raise
+from typing import ContextManager
 
 from click.testing import CliRunner
 from black.handle_ipynb_magics import jupyter_dependencies_are_installed
@@ -63,9 +66,19 @@ def test_trailing_semicolon_noop() -> None:
         format_cell(src, fast=True, mode=JUPYTER_MODE)
 
 
-def test_cell_magic() -> None:
+@pytest.mark.parametrize(
+    "mode",
+    [
+        pytest.param(JUPYTER_MODE, id="default mode"),
+        pytest.param(
+            replace(JUPYTER_MODE, python_cell_magics={"cust1", "cust1"}),
+            id="custom cell magics mode",
+        ),
+    ],
+)
+def test_cell_magic(mode: Mode) -> None:
     src = "%%time\nfoo =bar"
-    result = format_cell(src, fast=True, mode=JUPYTER_MODE)
+    result = format_cell(src, fast=True, mode=mode)
     expected = "%%time\nfoo = bar"
     assert result == expected
 
@@ -76,6 +89,16 @@ def test_cell_magic_noop() -> None:
         format_cell(src, fast=True, mode=JUPYTER_MODE)
 
 
+@pytest.mark.parametrize(
+    "mode",
+    [
+        pytest.param(JUPYTER_MODE, id="default mode"),
+        pytest.param(
+            replace(JUPYTER_MODE, python_cell_magics={"cust1", "cust1"}),
+            id="custom cell magics mode",
+        ),
+    ],
+)
 @pytest.mark.parametrize(
     "src, expected",
     (
@@ -96,8 +119,8 @@ def test_cell_magic_noop() -> None:
         pytest.param("env =  %env", "env = %env", id="Assignment to magic"),
     ),
 )
-def test_magic(src: str, expected: str) -> None:
-    result = format_cell(src, fast=True, mode=JUPYTER_MODE)
+def test_magic(src: str, expected: str, mode: Mode) -> None:
+    result = format_cell(src, fast=True, mode=mode)
     assert result == expected
 
 
@@ -139,6 +162,41 @@ def test_cell_magic_with_magic() -> None:
     assert result == expected
 
 
+@pytest.mark.parametrize(
+    "mode, expected_output, expectation",
+    [
+        pytest.param(
+            JUPYTER_MODE,
+            "%%custom_python_magic -n1 -n2\nx=2",
+            pytest.raises(NothingChanged),
+            id="No change when cell magic not registered",
+        ),
+        pytest.param(
+            replace(JUPYTER_MODE, python_cell_magics={"cust1", "cust1"}),
+            "%%custom_python_magic -n1 -n2\nx=2",
+            pytest.raises(NothingChanged),
+            id="No change when other cell magics registered",
+        ),
+        pytest.param(
+            replace(JUPYTER_MODE, python_cell_magics={"custom_python_magic", "cust1"}),
+            "%%custom_python_magic -n1 -n2\nx = 2",
+            does_not_raise(),
+            id="Correctly change when cell magic registered",
+        ),
+    ],
+)
+def test_cell_magic_with_custom_python_magic(
+    mode: Mode, expected_output: str, expectation: ContextManager[object]
+) -> None:
+    with expectation:
+        result = format_cell(
+            "%%custom_python_magic -n1 -n2\nx=2",
+            fast=True,
+            mode=mode,
+        )
+        assert result == expected_output
+
+
 def test_cell_magic_nested() -> None:
     src = "%%time\n%%time\n2+2"
     result = format_cell(src, fast=True, mode=JUPYTER_MODE)

From e0c572833a3e2b42cd45237c26a67c6f5be4b09d Mon Sep 17 00:00:00 2001
From: Shivansh-007 <shivansh-007@outlook.com>
Date: Fri, 21 Jan 2022 22:24:57 +0530
Subject: [PATCH 0427/1034] Set `click` lower bound to `8.0.0` (#2791)

Closes #2774
---
 CHANGES.md | 1 +
 setup.py   | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index a2e5c0a4ff8..83117e65dc4 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -39,6 +39,7 @@
 
 - All upper version bounds on dependencies have been removed (#2718)
 - `typing-extensions` is no longer a required dependency in Python 3.10+ (#2772)
+- Set `click` lower bound to `8.0.0` (#2791)
 
 ### Preview style
 
diff --git a/setup.py b/setup.py
index c31baab00ae..c5917998da4 100644
--- a/setup.py
+++ b/setup.py
@@ -97,7 +97,7 @@ def find_python_files(base: Path) -> List[Path]:
     python_requires=">=3.6.2",
     zip_safe=False,
     install_requires=[
-        "click>=7.1.2",
+        "click>=8.0.0",
         "platformdirs>=2",
         "tomli>=1.1.0",
         "typed-ast>=1.4.2; python_version < '3.8' and implementation_name == 'cpython'",

From 95c03b9638e44eb76611a0e005d447472a4f2f97 Mon Sep 17 00:00:00 2001
From: Rob Hammond <13874373+RHammond2@users.noreply.github.com>
Date: Fri, 21 Jan 2022 11:23:26 -0700
Subject: [PATCH 0428/1034] add wind technology software projects using black
 (#2792)

---
 README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 32db2bf2ce8..daeb7473583 100644
--- a/README.md
+++ b/README.md
@@ -132,8 +132,8 @@ code in compliance with many other _Black_ formatted projects.
 The following notable open-source projects trust _Black_ with enforcing a consistent
 code style: pytest, tox, Pyramid, Django Channels, Hypothesis, attrs, SQLAlchemy,
 Poetry, PyPA applications (Warehouse, Bandersnatch, Pipenv, virtualenv), pandas, Pillow,
-Twisted, LocalStack, every Datadog Agent Integration, Home Assistant, Zulip, Kedro, and
-many more.
+Twisted, LocalStack, every Datadog Agent Integration, Home Assistant, Zulip, Kedro,
+OpenOA, FLORIS, ORBIT, WOMBAT, and many more.
 
 The following organizations use _Black_: Facebook, Dropbox, KeepTruckin, Mozilla, Quora,
 Duolingo, QuantumBlack, Tesla.

From d24bc4364c6ef2337875be1a5b4e0851adaaf0f6 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Fri, 21 Jan 2022 18:00:13 -0500
Subject: [PATCH 0429/1034] Switch to Furo (#2793)

- Add Furo dependency to docs/requirements.txt
- Drop a fair bit of theme configuration
- Fix the toctree declarations in index.rst
- Move stuff around as Furo isn't 100% compatible with Alabaster

Furo was chosen as it provides excellent mobile support, user
controllable light/dark theming, and is overall easier to read
---
 CHANGES.md              |  2 ++
 docs/_static/custom.css | 44 -----------------------------------------
 docs/conf.py            | 25 ++---------------------
 docs/faq.md             |  1 +
 docs/index.rst          | 13 ++++++++----
 docs/requirements.txt   |  1 +
 6 files changed, 15 insertions(+), 71 deletions(-)
 delete mode 100644 docs/_static/custom.css

diff --git a/CHANGES.md b/CHANGES.md
index 83117e65dc4..4f4c6a2ffc7 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -53,6 +53,8 @@
 ### Documentation
 
 - Change protocol in pip installation instructions to `https://` (#2761)
+- Change HTML theme to Furo primarily for its responsive design and mobile support
+  (#2793)
 
 ## 21.12b0
 
diff --git a/docs/_static/custom.css b/docs/_static/custom.css
deleted file mode 100644
index eacd69c15a0..00000000000
--- a/docs/_static/custom.css
+++ /dev/null
@@ -1,44 +0,0 @@
-/* Make the sidebar scrollable. Fixes https://github.com/psf/black/issues/990 */
-div.sphinxsidebar {
-  max-height: calc(100% - 18px);
-  overflow-y: auto;
-}
-
-/* Hide scrollbar for Chrome, Safari and Opera */
-div.sphinxsidebar::-webkit-scrollbar {
-  display: none;
-}
-
-/* Hide scrollbar for IE 6, 7 and 8 */
-@media \0screen\, screen\9 {
-  div.sphinxsidebar {
-    -ms-overflow-style: none;
-  }
-}
-
-/* Hide scrollbar for IE 9 and 10 */
-/* backslash-9 removes ie11+ & old Safari 4 */
-@media screen and (min-width: 0\0) {
-  div.sphinxsidebar {
-    -ms-overflow-style: none\9;
-  }
-}
-
-/* Hide scrollbar for IE 11 and up */
-_:-ms-fullscreen,
-:root div.sphinxsidebar {
-  -ms-overflow-style: none;
-}
-
-/* Hide scrollbar for Edge */
-@supports (-ms-ime-align: auto) {
-  div.sphinxsidebar {
-    -ms-overflow-style: none;
-  }
-}
-
-/* Nicer style for local document toc */
-.contents.topic {
-  background: none;
-  border: none;
-}
diff --git a/docs/conf.py b/docs/conf.py
index 55d0fa99dc6..2801e0eed19 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -115,29 +115,8 @@ def make_pypi_svg(version: str) -> None:
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "alabaster"
-
-html_sidebars = {
-    "**": [
-        "about.html",
-        "navigation.html",
-        "relations.html",
-        "searchbox.html",
-    ]
-}
-
-html_theme_options = {
-    "show_related": False,
-    "description": "“Any color you like.”",
-    "github_button": True,
-    "github_user": "psf",
-    "github_repo": "black",
-    "github_type": "star",
-    "show_powered_by": True,
-    "fixed_sidebar": True,
-    "logo": "logo2.png",
-}
-
+html_theme = "furo"
+html_logo = "_static/logo2-readme.png"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
diff --git a/docs/faq.md b/docs/faq.md
index 94a978d826f..1ebdcd9530d 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -5,6 +5,7 @@ The most common questions and issues users face are aggregated to this FAQ.
 ```{contents}
 :local:
 :backlinks: none
+:class: this-will-duplicate-information-and-it-is-still-useful-here
 ```
 
 ## Does Black have an API?
diff --git a/docs/index.rst b/docs/index.rst
index 1515697f556..6818c03cfe9 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -4,6 +4,8 @@
 The uncompromising code formatter
 =================================
 
+    “Any color you like.”
+
 By using *Black*, you agree to cede control over minutiae of
 hand-formatting. In return, *Black* gives you speed, determinism, and
 freedom from `pycodestyle` nagging about formatting. You will save time
@@ -99,6 +101,7 @@ Contents
 .. toctree::
    :maxdepth: 3
    :includehidden:
+   :caption: User Guide
 
    getting_started
    usage_and_configuration/index
@@ -107,8 +110,9 @@ Contents
    faq
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 2
    :includehidden:
+   :caption: Development
 
    contributing/index
    change_log
@@ -116,10 +120,11 @@ Contents
 
 .. toctree::
    :hidden:
+   :caption: Project Links
 
-   GitHub ↪ <https://github.com/psf/black>
-   PyPI ↪ <https://pypi.org/project/black>
-   Chat ↪ <https://discord.gg/RtVdv86PrH>
+   GitHub <https://github.com/psf/black>
+   PyPI <https://pypi.org/project/black>
+   Chat <https://discord.gg/RtVdv86PrH>
 
 Indices and tables
 ==================
diff --git a/docs/requirements.txt b/docs/requirements.txt
index 02874d3c255..01fea693f07 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -4,3 +4,4 @@ myst-parser==0.16.1
 Sphinx==4.4.0
 sphinxcontrib-programoutput==0.17
 sphinx_copybutton==0.4.0
+furo==2022.1.2

From 10677baa40f818ca06c6a9d5efa0dca052865bfb Mon Sep 17 00:00:00 2001
From: Perry Vargas <perrybvargas@gmail.com>
Date: Fri, 21 Jan 2022 22:00:33 -0800
Subject: [PATCH 0430/1034] Allow setting custom cache directory on all
 platforms (#2739)

Fixes #2506

``XDG_CACHE_HOME`` does not work on Windows. To allow for users to set a custom cache directory on all systems I added a new environment variable ``BLACK_CACHE_DIR`` to set the cache directory. The default remains the same so users will only notice a change if that environment variable is set.

The specific use case I have for this is I need to run black on in different processes at the same time. There is a race condition with the cache pickle file that made this rather difficult. A custom cache directory will remove the race condition.

I created ``get_cache_dir`` function in order to test the logic. This is only used to set the ``CACHE_DIR`` constant.
---
 CHANGES.md                                    |  2 ++
 .../reference/reference_functions.rst         |  2 ++
 .../file_collection_and_discovery.md          | 10 ++++---
 src/black/cache.py                            | 18 +++++++++++-
 tests/test_black.py                           | 29 ++++++++++++++++++-
 5 files changed, 55 insertions(+), 6 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 4f4c6a2ffc7..dc52ca34cbb 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -20,6 +20,8 @@
 - Tuple unpacking on `return` and `yield` constructs now implies 3.8+ (#2700)
 - Unparenthesized tuples on annotated assignments (e.g
   `values: Tuple[int, ...] = 1, 2, 3`) now implies 3.8+ (#2708)
+- Allow setting custom cache directory on all platforms with environment variable
+  `BLACK_CACHE_DIR` (#2739).
 - Text coloring added in the final statistics (#2712)
 - For stubs, one blank line between class attributes and methods is now kept if there's
   at least one pre-existing blank line (#2736)
diff --git a/docs/contributing/reference/reference_functions.rst b/docs/contributing/reference/reference_functions.rst
index 4353d1bf9a9..01ffe44ef53 100644
--- a/docs/contributing/reference/reference_functions.rst
+++ b/docs/contributing/reference/reference_functions.rst
@@ -96,6 +96,8 @@ Caching
 
 .. autofunction:: black.cache.filter_cached
 
+.. autofunction:: black.cache.get_cache_dir
+
 .. autofunction:: black.cache.get_cache_file
 
 .. autofunction:: black.cache.get_cache_info
diff --git a/docs/usage_and_configuration/file_collection_and_discovery.md b/docs/usage_and_configuration/file_collection_and_discovery.md
index 1f436182dda..bd90ccc6af8 100644
--- a/docs/usage_and_configuration/file_collection_and_discovery.md
+++ b/docs/usage_and_configuration/file_collection_and_discovery.md
@@ -22,10 +22,12 @@ run. The file is non-portable. The standard location on common operating systems
 `file-mode` is an int flag that determines whether the file was formatted as 3.6+ only,
 as .pyi, and whether string normalization was omitted.
 
-To override the location of these files on macOS or Linux, set the environment variable
-`XDG_CACHE_HOME` to your preferred location. For example, if you want to put the cache
-in the directory you're running _Black_ from, set `XDG_CACHE_HOME=.cache`. _Black_ will
-then write the above files to `.cache/black/<version>/`.
+To override the location of these files on all systems, set the environment variable
+`BLACK_CACHE_DIR` to the preferred location. Alternatively on macOS and Linux, set
+`XDG_CACHE_HOME` to you your preferred location. For example, if you want to put the
+cache in the directory you're running _Black_ from, set `BLACK_CACHE_DIR=.cache/black`.
+_Black_ will then write the above files to `.cache/black`. Note that `BLACK_CACHE_DIR`
+will take precedence over `XDG_CACHE_HOME` if both are set.
 
 ## .gitignore
 
diff --git a/src/black/cache.py b/src/black/cache.py
index bca7279f990..552c248d2ad 100644
--- a/src/black/cache.py
+++ b/src/black/cache.py
@@ -20,7 +20,23 @@
 Cache = Dict[str, CacheInfo]
 
 
-CACHE_DIR = Path(user_cache_dir("black", version=__version__))
+def get_cache_dir() -> Path:
+    """Get the cache directory used by black.
+
+    Users can customize this directory on all systems using `BLACK_CACHE_DIR`
+    environment variable. By default, the cache directory is the user cache directory
+    under the black application.
+
+    This result is immediately set to a constant `black.cache.CACHE_DIR` as to avoid
+    repeated calls.
+    """
+    # NOTE: Function mostly exists as a clean way to test getting the cache directory.
+    default_cache_dir = user_cache_dir("black", version=__version__)
+    cache_dir = Path(os.environ.get("BLACK_CACHE_DIR", default_cache_dir))
+    return cache_dir
+
+
+CACHE_DIR = get_cache_dir()
 
 
 def read_cache(mode: Mode) -> Cache:
diff --git a/tests/test_black.py b/tests/test_black.py
index fd01425ae74..559690938a8 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -40,7 +40,7 @@
 import black.files
 from black import Feature, TargetVersion
 from black import re_compile_maybe_verbose as compile_pattern
-from black.cache import get_cache_file
+from black.cache import get_cache_dir, get_cache_file
 from black.debug import DebugVisitor
 from black.output import color_diff, diff
 from black.report import Report
@@ -1601,6 +1601,33 @@ def test_equivalency_ast_parse_failure_includes_error(self) -> None:
 
 
 class TestCaching:
+    def test_get_cache_dir(
+        self,
+        tmp_path: Path,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        # Create multiple cache directories
+        workspace1 = tmp_path / "ws1"
+        workspace1.mkdir()
+        workspace2 = tmp_path / "ws2"
+        workspace2.mkdir()
+
+        # Force user_cache_dir to use the temporary directory for easier assertions
+        patch_user_cache_dir = patch(
+            target="black.cache.user_cache_dir",
+            autospec=True,
+            return_value=str(workspace1),
+        )
+
+        # If BLACK_CACHE_DIR is not set, use user_cache_dir
+        monkeypatch.delenv("BLACK_CACHE_DIR", raising=False)
+        with patch_user_cache_dir:
+            assert get_cache_dir() == workspace1
+
+        # If it is set, use the path provided in the env var.
+        monkeypatch.setenv("BLACK_CACHE_DIR", str(workspace2))
+        assert get_cache_dir() == workspace2
+
     def test_cache_broken_file(self) -> None:
         mode = DEFAULT_MODE
         with cache_dir() as workspace:

From fb1d1b2fc85efe422b6ff32d05f537d5394f6259 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Sat, 22 Jan 2022 06:08:27 -0500
Subject: [PATCH 0431/1034] Mark Felix and Batuhan as maintainers (#2794)

Y'all deserve it :)
---
 AUTHORS.md | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

diff --git a/AUTHORS.md b/AUTHORS.md
index 8d112ea6795..8aa6263313e 100644
--- a/AUTHORS.md
+++ b/AUTHORS.md
@@ -2,12 +2,17 @@
 
 Glued together by [Łukasz Langa](mailto:lukasz@langa.pl).
 
-Maintained with [Carol Willing](mailto:carolcode@willingconsulting.com),
-[Carl Meyer](mailto:carl@oddbird.net),
-[Jelle Zijlstra](mailto:jelle.zijlstra@gmail.com),
-[Mika Naylor](mailto:mail@autophagy.io),
-[Zsolt Dollenstein](mailto:zsol.zsol@gmail.com),
-[Cooper Lees](mailto:me@cooperlees.com), and Richard Si.
+Maintained with:
+
+- [Carol Willing](mailto:carolcode@willingconsulting.com)
+- [Carl Meyer](mailto:carl@oddbird.net)
+- [Jelle Zijlstra](mailto:jelle.zijlstra@gmail.com)
+- [Mika Naylor](mailto:mail@autophagy.io)
+- [Zsolt Dollenstein](mailto:zsol.zsol@gmail.com)
+- [Cooper Lees](mailto:me@cooperlees.com)
+- Richard Si
+- [Felix Hildén](mailto:felix.hilden@gmail.com)
+- [Batuhan Taskaya](mailto:batuhan@python.org)
 
 Multiple contributions by:
 

From 811de5f36bb1bb2bc7e14c186cf1af6badb77475 Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Sat, 22 Jan 2022 07:29:38 -0800
Subject: [PATCH 0432/1034] Refactor logic for stub empty lines (#2796)

This PR is intended to have no change to semantics.

This is in preparation for #2784 which will likely introduce more logic
that depends on `current_line.depth`.

Inlining the subtraction gets rid of offsetting and makes it much easier
to see what the result will be.
---
 src/black/lines.py | 21 ++++++++++-----------
 1 file changed, 10 insertions(+), 11 deletions(-)

diff --git a/src/black/lines.py b/src/black/lines.py
index d8617d83bf7..c602aa69ce9 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -529,9 +529,11 @@ def _maybe_empty_lines_for_class_or_def(
 
         if self.is_pyi:
             if self.previous_line.depth > current_line.depth:
-                newlines = 1
+                newlines = 0 if current_line.depth else 1
             elif current_line.is_class or self.previous_line.is_class:
-                if current_line.is_stub_class and self.previous_line.is_stub_class:
+                if current_line.depth:
+                    newlines = 0
+                elif current_line.is_stub_class and self.previous_line.is_stub_class:
                     # No blank line between classes with an empty body
                     newlines = 0
                 else:
@@ -539,21 +541,18 @@ def _maybe_empty_lines_for_class_or_def(
             elif (
                 current_line.is_def or current_line.is_decorator
             ) and not self.previous_line.is_def:
-                if not current_line.depth:
+                if current_line.depth:
+                    # In classes empty lines between attributes and methods should
+                    # be preserved.
+                    newlines = min(1, before)
+                else:
                     # Blank line between a block of functions (maybe with preceding
                     # decorators) and a block of non-functions
                     newlines = 1
-                else:
-                    # In classes empty lines between attributes and methods should
-                    # be preserved. The +1 offset is to negate the -1 done later as
-                    # this function is indented.
-                    newlines = min(2, before + 1)
             else:
                 newlines = 0
         else:
-            newlines = 2
-        if current_line.depth and newlines:
-            newlines -= 1
+            newlines = 1 if current_line.depth else 2
         return newlines, 0
 
 

From b3b341b44fde044938daa6691fa1064ea240ff96 Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Sat, 22 Jan 2022 07:30:18 -0800
Subject: [PATCH 0433/1034] Mention "skip news" label in CHANGELOG action
 (#2797)

Co-authored-by: hauntsaninja <>
---
 .github/workflows/changelog.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/changelog.yml b/.github/workflows/changelog.yml
index d7ee50558d3..476e2545ce8 100644
--- a/.github/workflows/changelog.yml
+++ b/.github/workflows/changelog.yml
@@ -17,5 +17,5 @@ jobs:
         if: contains(github.event.pull_request.labels.*.name, 'skip news') != true
         run: |
           grep -Pz "\((\n\s*)?#${{ github.event.pull_request.number }}(\n\s*)?\)" CHANGES.md || \
-          (echo "Please add '(#${{ github.event.pull_request.number }})' change line to CHANGES.md" && \
+          (echo "Please add '(#${{ github.event.pull_request.number }})' change line to CHANGES.md (or if appropriate, ask a maintainer to add the 'skip news' label)" && \
           exit 1)

From 022f89625f9bb33ab55c82c45ec0eb8512623fd3 Mon Sep 17 00:00:00 2001
From: Batuhan Taskaya <isidentical@gmail.com>
Date: Sat, 22 Jan 2022 23:05:26 +0300
Subject: [PATCH 0434/1034] Enable pattern matching by default (#2758)

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 CHANGES.md                    |  2 ++
 src/black/parsing.py          | 28 ++++++++++++++++------------
 src/blib2to3/pgen2/grammar.py |  2 ++
 src/blib2to3/pygram.py        |  5 +++++
 tests/test_format.py          | 15 ++++++---------
 5 files changed, 31 insertions(+), 21 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index dc52ca34cbb..634db79bf73 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -36,6 +36,8 @@
   Jupyter Notebooks (#2744)
 - Deprecate `--experimental-string-processing` and move the functionality under
   `--preview` (#2789)
+- Enable Python 3.10+ by default, without any extra need to specify
+  `--target-version=py310`. (#2758)
 
 ### Packaging
 
diff --git a/src/black/parsing.py b/src/black/parsing.py
index 6b63368871c..db48ae4baf5 100644
--- a/src/black/parsing.py
+++ b/src/black/parsing.py
@@ -42,7 +42,6 @@
         ast3 = ast
 
 
-PY310_HINT: Final = "Consider using --target-version py310 to parse Python 3.10 code."
 PY2_HINT: Final = "Python 2 support was removed in version 22.0."
 
 
@@ -58,12 +57,11 @@ def get_grammars(target_versions: Set[TargetVersion]) -> List[Grammar]:
             pygram.python_grammar_no_print_statement_no_exec_statement_async_keywords,
             # Python 3.0-3.6
             pygram.python_grammar_no_print_statement_no_exec_statement,
+            # Python 3.10+
+            pygram.python_grammar_soft_keywords,
         ]
 
     grammars = []
-    if supports_feature(target_versions, Feature.PATTERN_MATCHING):
-        # Python 3.10+
-        grammars.append(pygram.python_grammar_soft_keywords)
     # If we have to parse both, try to parse async as a keyword first
     if not supports_feature(
         target_versions, Feature.ASYNC_IDENTIFIERS
@@ -75,6 +73,10 @@ def get_grammars(target_versions: Set[TargetVersion]) -> List[Grammar]:
     if not supports_feature(target_versions, Feature.ASYNC_KEYWORDS):
         # Python 3.0-3.6
         grammars.append(pygram.python_grammar_no_print_statement_no_exec_statement)
+    if supports_feature(target_versions, Feature.PATTERN_MATCHING):
+        # Python 3.10+
+        grammars.append(pygram.python_grammar_soft_keywords)
+
     # At least one of the above branches must have been taken, because every Python
     # version has exactly one of the two 'ASYNC_*' flags
     return grammars
@@ -86,6 +88,7 @@ def lib2to3_parse(src_txt: str, target_versions: Iterable[TargetVersion] = ()) -
         src_txt += "\n"
 
     grammars = get_grammars(set(target_versions))
+    errors = {}
     for grammar in grammars:
         drv = driver.Driver(grammar)
         try:
@@ -99,20 +102,21 @@ def lib2to3_parse(src_txt: str, target_versions: Iterable[TargetVersion] = ()) -
                 faulty_line = lines[lineno - 1]
             except IndexError:
                 faulty_line = "<line number missing in source>"
-            exc = InvalidInput(f"Cannot parse: {lineno}:{column}: {faulty_line}")
+            errors[grammar.version] = InvalidInput(
+                f"Cannot parse: {lineno}:{column}: {faulty_line}"
+            )
 
         except TokenError as te:
             # In edge cases these are raised; and typically don't have a "faulty_line".
             lineno, column = te.args[1]
-            exc = InvalidInput(f"Cannot parse: {lineno}:{column}: {te.args[0]}")
+            errors[grammar.version] = InvalidInput(
+                f"Cannot parse: {lineno}:{column}: {te.args[0]}"
+            )
 
     else:
-        if pygram.python_grammar_soft_keywords not in grammars and matches_grammar(
-            src_txt, pygram.python_grammar_soft_keywords
-        ):
-            original_msg = exc.args[0]
-            msg = f"{original_msg}\n{PY310_HINT}"
-            raise InvalidInput(msg) from None
+        # Choose the latest version when raising the actual parsing error.
+        assert len(errors) >= 1
+        exc = errors[max(errors)]
 
         if matches_grammar(src_txt, pygram.python_grammar) or matches_grammar(
             src_txt, pygram.python_grammar_no_print_statement
diff --git a/src/blib2to3/pgen2/grammar.py b/src/blib2to3/pgen2/grammar.py
index 56851070933..337a64f1726 100644
--- a/src/blib2to3/pgen2/grammar.py
+++ b/src/blib2to3/pgen2/grammar.py
@@ -92,6 +92,7 @@ def __init__(self) -> None:
         self.soft_keywords: Dict[str, int] = {}
         self.tokens: Dict[int, int] = {}
         self.symbol2label: Dict[str, int] = {}
+        self.version: Tuple[int, int] = (0, 0)
         self.start = 256
         # Python 3.7+ parses async as a keyword, not an identifier
         self.async_keywords = False
@@ -145,6 +146,7 @@ def copy(self: _P) -> _P:
         new.labels = self.labels[:]
         new.states = self.states[:]
         new.start = self.start
+        new.version = self.version
         new.async_keywords = self.async_keywords
         return new
 
diff --git a/src/blib2to3/pygram.py b/src/blib2to3/pygram.py
index aa20b8104ae..a3df9be1265 100644
--- a/src/blib2to3/pygram.py
+++ b/src/blib2to3/pygram.py
@@ -178,6 +178,8 @@ def initialize(cache_dir: Union[str, "os.PathLike[str]", None] = None) -> None:
 
     # Python 2
     python_grammar = driver.load_packaged_grammar("blib2to3", _GRAMMAR_FILE, cache_dir)
+    python_grammar.version = (2, 0)
+
     soft_keywords = python_grammar.soft_keywords.copy()
     python_grammar.soft_keywords.clear()
 
@@ -191,6 +193,7 @@ def initialize(cache_dir: Union[str, "os.PathLike[str]", None] = None) -> None:
     python_grammar_no_print_statement_no_exec_statement = python_grammar.copy()
     del python_grammar_no_print_statement_no_exec_statement.keywords["print"]
     del python_grammar_no_print_statement_no_exec_statement.keywords["exec"]
+    python_grammar_no_print_statement_no_exec_statement.version = (3, 0)
 
     # Python 3.7+
     python_grammar_no_print_statement_no_exec_statement_async_keywords = (
@@ -199,12 +202,14 @@ def initialize(cache_dir: Union[str, "os.PathLike[str]", None] = None) -> None:
     python_grammar_no_print_statement_no_exec_statement_async_keywords.async_keywords = (
         True
     )
+    python_grammar_no_print_statement_no_exec_statement_async_keywords.version = (3, 7)
 
     # Python 3.10+
     python_grammar_soft_keywords = (
         python_grammar_no_print_statement_no_exec_statement_async_keywords.copy()
     )
     python_grammar_soft_keywords.soft_keywords = soft_keywords
+    python_grammar_soft_keywords.version = (3, 10)
 
     pattern_grammar = driver.load_packaged_grammar(
         "blib2to3", _PATTERN_GRAMMAR_FILE, cache_dir
diff --git a/tests/test_format.py b/tests/test_format.py
index 40f225c9554..3895a095e86 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -191,6 +191,12 @@ def test_python_310(filename: str) -> None:
     assert_format(source, expected, mode, minimum_version=(3, 10))
 
 
+def test_python_310_without_target_version() -> None:
+    source, expected = read_data("pattern_matching_simple")
+    mode = black.Mode()
+    assert_format(source, expected, mode, minimum_version=(3, 10))
+
+
 def test_patma_invalid() -> None:
     source, expected = read_data("pattern_matching_invalid")
     mode = black.Mode(target_versions={black.TargetVersion.PY310})
@@ -200,15 +206,6 @@ def test_patma_invalid() -> None:
     exc_info.match("Cannot parse: 10:11")
 
 
-def test_patma_hint() -> None:
-    source, expected = read_data("pattern_matching_simple")
-    mode = black.Mode(target_versions={black.TargetVersion.PY39})
-    with pytest.raises(black.parsing.InvalidInput) as exc_info:
-        assert_format(source, expected, mode, minimum_version=(3, 10))
-
-    exc_info.match(black.parsing.PY310_HINT)
-
-
 def test_python_2_hint() -> None:
     with pytest.raises(black.parsing.InvalidInput) as exc_info:
         assert_format("print 'daylily'", "print 'daylily'")

From 6e3677f3f0c0542f858f7fc06d20cca5fab59348 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Sun, 23 Jan 2022 11:49:11 -0500
Subject: [PATCH 0435/1034] Allow blackd to be run as a package (#2800)

---
 src/blackd/__main__.py | 3 +++
 1 file changed, 3 insertions(+)
 create mode 100644 src/blackd/__main__.py

diff --git a/src/blackd/__main__.py b/src/blackd/__main__.py
new file mode 100644
index 00000000000..b5a4b137446
--- /dev/null
+++ b/src/blackd/__main__.py
@@ -0,0 +1,3 @@
+import blackd
+
+blackd.patched_main()

From d2c938eb02c414057aa2186c7ae695d5d0d14377 Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Sun, 23 Jan 2022 12:34:01 -0800
Subject: [PATCH 0436/1034] Remove Beta mentions in README + Docs (#2801)

- State we're now stable and that we'll uphold our formatting changes as per policy
- Link to The Black Style doc.

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 README.md      | 15 ++++++---------
 docs/faq.md    | 11 ++++-------
 docs/index.rst | 14 ++++++--------
 3 files changed, 16 insertions(+), 24 deletions(-)

diff --git a/README.md b/README.md
index daeb7473583..e900d2d75a2 100644
--- a/README.md
+++ b/README.md
@@ -64,16 +64,13 @@ Further information can be found in our docs:
 
 - [Usage and Configuration](https://black.readthedocs.io/en/stable/usage_and_configuration/index.html)
 
-### NOTE: This is a beta product
-
 _Black_ is already [successfully used](https://github.com/psf/black#used-by) by many
-projects, small and big. Black has a comprehensive test suite, with efficient parallel
-tests, and our own auto formatting and parallel Continuous Integration runner. However,
-_Black_ is still beta. Things will probably be wonky for a while. This is made explicit
-by the "Beta" trove classifier, as well as by the "b" in the version number. What this
-means for you is that **until the formatter becomes stable, you should expect some
-formatting to change in the future**. That being said, no drastic stylistic changes are
-planned, mostly responses to bug reports.
+projects, small and big. _Black_ has a comprehensive test suite, with efficient parallel
+tests, and our own auto formatting and parallel Continuous Integration runner. Now that
+we have become stable, you should not expect large formatting to changes in the future.
+Stylistic changes will mostly be responses to bug reports and support for new Python
+syntax. For more information please refer to the
+[The Black Code Style](docs/the_black_code_style/index.rst).
 
 Also, as a safety measure which slows down processing, _Black_ will check that the
 reformatted code still produces a valid AST that is effectively equivalent to the
diff --git a/docs/faq.md b/docs/faq.md
index 1ebdcd9530d..0cff6ae5e1d 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -17,9 +17,8 @@ though.
 
 ## Is Black safe to use?
 
-Yes, for the most part. _Black_ is strictly about formatting, nothing else. But because
-_Black_ is still in [beta](index.rst), some edges are still a bit rough. To combat
-issues, the equivalence of code after formatting is
+Yes. _Black_ is strictly about formatting, nothing else. Black strives to ensure that
+after formatting the AST is
 [checked](the_black_code_style/current_style.md#ast-before-and-after-formatting) with
 limited special cases where the code is allowed to differ. If issues are found, an error
 is raised and the file is left untouched. Magical comments that influence linters and
@@ -27,10 +26,8 @@ other tools, such as `# noqa`, may be moved by _Black_. See below for more detai
 
 ## How stable is Black's style?
 
-Quite stable. _Black_ aims to enforce one style and one style only, with some room for
-pragmatism. However, _Black_ is still in beta so style changes are both planned and
-still proposed on the issue tracker. See
-[The Black Code Style](the_black_code_style/index.rst) for more details.
+Stable. _Black_ aims to enforce one style and one style only, with some room for
+pragmatism. See [The Black Code Style](the_black_code_style/index.rst) for more details.
 
 Starting in 2022, the formatting output will be stable for the releases made in the same
 year (other than unintentional bugs). It is possible to opt-in to the latest formatting
diff --git a/docs/index.rst b/docs/index.rst
index 6818c03cfe9..8a8da0d6127 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -18,16 +18,14 @@ can focus on the content instead.
 
 Try it out now using the `Black Playground <https://black.vercel.app>`_.
 
-.. admonition:: Note - this is a beta product
+.. admonition:: Note - Black is now stable!
 
-   *Black* is already `successfully used <https://github.com/psf/black#used-by>`_ by
+   *Black* is `successfully used <https://github.com/psf/black#used-by>`_ by
    many projects, small and big. *Black* has a comprehensive test suite, with efficient
-   parallel tests, our own auto  formatting and parallel Continuous Integration runner.
-   However, *Black* is still beta. Things will probably be wonky for a while. This is
-   made explicit by the "Beta" trove classifier, as well as by the "b" in the version
-   number. What this means for you is that **until the formatter becomes stable, you
-   should expect some formatting to change in the future**. That being said, no drastic
-   stylistic changes are planned, mostly responses to bug reports.
+   parallel tests, our own auto formatting and parallel Continuous Integration runner.
+   Now that we have become stable, you should not expect large formatting to changes in
+   the future. Stylistic changes will mostly be responses to bug reports and support for new Python
+   syntax.
 
    Also, as a safety measure which slows down processing, *Black* will check that the
    reformatted code still produces a valid AST that is effectively equivalent to the

From 3905173cb32922b580bad184e724586f359c8c7e Mon Sep 17 00:00:00 2001
From: Nikita Sobolev <mail@sobolevn.me>
Date: Sun, 23 Jan 2022 23:34:29 +0300
Subject: [PATCH 0437/1034] Use `magic_trailing_comma` and `preview` for
 `FileMode` in `fuzz` (#2802)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 fuzz.py | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/fuzz.py b/fuzz.py
index a9ca8eff8b0..09a86a2f571 100644
--- a/fuzz.py
+++ b/fuzz.py
@@ -32,7 +32,9 @@
         black.FileMode,
         line_length=st.just(88) | st.integers(0, 200),
         string_normalization=st.booleans(),
+        preview=st.booleans(),
         is_pyi=st.booleans(),
+        magic_trailing_comma=st.booleans(),
     ),
 )
 def test_idempotent_any_syntatically_valid_python(

From 73cb6e7734370108742d992d4fe1fa2829f100fd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Felix=20Hild=C3=A9n?= <felix.hilden@gmail.com>
Date: Mon, 24 Jan 2022 17:35:56 +0200
Subject: [PATCH 0438/1034] Make SRC or code mandatory and mutually exclusive
 (#2360) (#2804)

Closes #2360: I'd like to make passing SRC or `--code` mandatory and the arguments mutually exclusive. This will change our (partially already broken) promises of CLI behavior, but I'll comment below.
---
 CHANGES.md                                 |  1 +
 docs/usage_and_configuration/the_basics.md |  4 ++--
 src/black/__init__.py                      | 12 +++++++++++-
 tests/test_black.py                        | 20 ++++++++++++++------
 4 files changed, 28 insertions(+), 9 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 634db79bf73..458d48cd2c1 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -38,6 +38,7 @@
   `--preview` (#2789)
 - Enable Python 3.10+ by default, without any extra need to specify
   `--target-version=py310`. (#2758)
+- Make passing `SRC` or `--code` mandatory and mutually exclusive (#2804)
 
 ### Packaging
 
diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index fd39b6c8979..b82cef4a52d 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -4,11 +4,11 @@ Foundational knowledge on using and configuring Black.
 
 _Black_ is a well-behaved Unix-style command-line tool:
 
-- it does nothing if no sources are passed to it;
+- it does nothing if it finds no sources to format;
 - it will read from standard input and write to standard output if `-` is used as the
   filename;
 - it only outputs messages to users on standard error;
-- exits with code 0 unless an internal error occurred (or `--check` was used).
+- exits with code 0 unless an internal error occurred or a CLI option prompted it.
 
 ## Usage
 
diff --git a/src/black/__init__.py b/src/black/__init__.py
index eaf72f9c2b3..7024c9d52b0 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -431,6 +431,17 @@ def main(
 ) -> None:
     """The uncompromising code formatter."""
     ctx.ensure_object(dict)
+
+    if src and code is not None:
+        out(
+            main.get_usage(ctx)
+            + "\n\n'SRC' and 'code' cannot be passed simultaneously."
+        )
+        ctx.exit(1)
+    if not src and code is None:
+        out(main.get_usage(ctx) + "\n\nOne of 'SRC' or 'code' is required.")
+        ctx.exit(1)
+
     root, method = find_project_root(src) if code is None else (None, None)
     ctx.obj["root"] = root
 
@@ -569,7 +580,6 @@ def get_sources(
 ) -> Set[Path]:
     """Compute the set of files to be formatted."""
     sources: Set[Path] = set()
-    path_empty(src, "No Path provided. Nothing to do 😴", quiet, verbose, ctx)
 
     if exclude is None:
         exclude = re_compile_maybe_verbose(DEFAULT_EXCLUDES)
diff --git a/tests/test_black.py b/tests/test_black.py
index 559690938a8..8d691d2f019 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -972,10 +972,13 @@ def test_check_diff_use_together(self) -> None:
             # Multi file command.
             self.invokeBlack([str(src1), str(src2), "--diff", "--check"], exit_code=1)
 
-    def test_no_files(self) -> None:
+    def test_no_src_fails(self) -> None:
         with cache_dir():
-            # Without an argument, black exits with error code 0.
-            self.invokeBlack([])
+            self.invokeBlack([], exit_code=1)
+
+    def test_src_and_code_fails(self) -> None:
+        with cache_dir():
+            self.invokeBlack([".", "-c", "0"], exit_code=1)
 
     def test_broken_symlink(self) -> None:
         with cache_dir() as workspace:
@@ -1229,13 +1232,18 @@ def test_invalid_cli_regex(self) -> None:
 
     def test_required_version_matches_version(self) -> None:
         self.invokeBlack(
-            ["--required-version", black.__version__], exit_code=0, ignore_config=True
+            ["--required-version", black.__version__, "-c", "0"],
+            exit_code=0,
+            ignore_config=True,
         )
 
     def test_required_version_does_not_match_version(self) -> None:
-        self.invokeBlack(
-            ["--required-version", "20.99b"], exit_code=1, ignore_config=True
+        result = BlackRunner().invoke(
+            black.main,
+            ["--required-version", "20.99b", "-c", "0"],
         )
+        self.assertEqual(result.exit_code, 1)
+        self.assertIn("required version", result.stderr)
 
     def test_preserves_line_endings(self) -> None:
         with TemporaryDirectory() as workspace:

From 6417c99bfdbdc057e4a10aeff9967a751f4f85e9 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Mon, 24 Jan 2022 22:13:34 -0500
Subject: [PATCH 0439/1034] Hug power operators if its operands are "simple"
 (#2726)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Since power operators almost always have the highest binding power in expressions, it's often more readable to hug it with its operands. The main exception to this is when its operands are non-trivial in which case the power operator will not hug, the rule for this is the following:

> For power ops, an operand is considered "simple" if it's only a NAME, numeric CONSTANT, or attribute access (chained attribute access is allowed), with or without a preceding unary operator.

Fixes GH-538.
Closes GH-2095.

diff-shades results: https://gist.github.com/ichard26/ca6c6ad4bd1de5152d95418c8645354b

Co-authored-by: Diego <dpalma@evernote.com>
Co-authored-by: Felix Hildén <felix.hilden@gmail.com>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 CHANGES.md                                    |   1 +
 docs/the_black_code_style/current_style.md    |  20 ++++
 src/black/linegen.py                          |   7 +-
 src/black/trans.py                            |  86 ++++++++++++++-
 src/black_primer/primer.json                  |   2 +-
 tests/data/expression.diff                    |  44 +++++---
 tests/data/expression.py                      |  30 ++---
 .../expression_skip_magic_trailing_comma.diff |  44 +++++---
 tests/data/pep_572.py                         |   2 +-
 tests/data/pep_572_py39.py                    |   2 +-
 tests/data/power_op_spacing.py                | 103 ++++++++++++++++++
 tests/data/slices.py                          |   2 +-
 tests/test_format.py                          |   1 +
 13 files changed, 293 insertions(+), 51 deletions(-)
 create mode 100644 tests/data/power_op_spacing.py

diff --git a/CHANGES.md b/CHANGES.md
index 458d48cd2c1..d203896a801 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -20,6 +20,7 @@
 - Tuple unpacking on `return` and `yield` constructs now implies 3.8+ (#2700)
 - Unparenthesized tuples on annotated assignments (e.g
   `values: Tuple[int, ...] = 1, 2, 3`) now implies 3.8+ (#2708)
+- Remove spaces around power operators if both operands are simple (#2726)
 - Allow setting custom cache directory on all platforms with environment variable
   `BLACK_CACHE_DIR` (#2739).
 - Text coloring added in the final statistics (#2712)
diff --git a/docs/the_black_code_style/current_style.md b/docs/the_black_code_style/current_style.md
index 1d1e42e75c8..5be7ba6dbdb 100644
--- a/docs/the_black_code_style/current_style.md
+++ b/docs/the_black_code_style/current_style.md
@@ -284,6 +284,26 @@ multiple lines. This is so that _Black_ is compliant with the recent changes in
 [PEP 8](https://www.python.org/dev/peps/pep-0008/#should-a-line-break-before-or-after-a-binary-operator)
 style guide, which emphasizes that this approach improves readability.
 
+Almost all operators will be surrounded by single spaces, the only exceptions are unary
+operators (`+`, `-`, and `~`), and power operators when both operands are simple. For
+powers, an operand is considered simple if it's only a NAME, numeric CONSTANT, or
+attribute access (chained attribute access is allowed), with or without a preceding
+unary operator.
+
+```python
+# For example, these won't be surrounded by whitespace
+a = x**y
+b = config.base**5.2
+c = config.base**runtime.config.exponent
+d = 2**5
+e = 2**~5
+
+# ... but these will be surrounded by whitespace
+f = 2 ** get_exponent()
+g = get_x() ** get_y()
+h = config['base'] ** 2
+```
+
 ### Slices
 
 PEP 8
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 9ee42aaaf72..9fbdfadba6a 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -21,8 +21,8 @@
 from black.numerics import normalize_numeric_literal
 from black.strings import get_string_prefix, fix_docstring
 from black.strings import normalize_string_prefix, normalize_string_quotes
-from black.trans import Transformer, CannotTransform, StringMerger
-from black.trans import StringSplitter, StringParenWrapper, StringParenStripper
+from black.trans import Transformer, CannotTransform, StringMerger, StringSplitter
+from black.trans import StringParenWrapper, StringParenStripper, hug_power_op
 from black.mode import Mode, Feature, Preview
 
 from blib2to3.pytree import Node, Leaf
@@ -404,6 +404,9 @@ def _rhs(
                 transformers = [delimiter_split, standalone_comment_split, rhs]
             else:
                 transformers = [rhs]
+    # It's always safe to attempt hugging of power operations and pretty much every line
+    # could match.
+    transformers.append(hug_power_op)
 
     for transform in transformers:
         # We are accumulating lines in `result` because we might want to abort
diff --git a/src/black/trans.py b/src/black/trans.py
index cb41c1be487..74d052fe2dc 100644
--- a/src/black/trans.py
+++ b/src/black/trans.py
@@ -24,9 +24,9 @@
 import sys
 
 if sys.version_info < (3, 8):
-    from typing_extensions import Final
+    from typing_extensions import Literal, Final
 else:
-    from typing import Final
+    from typing import Literal, Final
 
 from mypy_extensions import trait
 
@@ -71,6 +71,88 @@ def TErr(err_msg: str) -> Err[CannotTransform]:
     return Err(cant_transform)
 
 
+def hug_power_op(line: Line, features: Collection[Feature]) -> Iterator[Line]:
+    """A transformer which normalizes spacing around power operators."""
+
+    # Performance optimization to avoid unnecessary Leaf clones and other ops.
+    for leaf in line.leaves:
+        if leaf.type == token.DOUBLESTAR:
+            break
+    else:
+        raise CannotTransform("No doublestar token was found in the line.")
+
+    def is_simple_lookup(index: int, step: Literal[1, -1]) -> bool:
+        # Brackets and parentheses indicate calls, subscripts, etc. ...
+        # basically stuff that doesn't count as "simple". Only a NAME lookup
+        # or dotted lookup (eg. NAME.NAME) is OK.
+        if step == -1:
+            disallowed = {token.RPAR, token.RSQB}
+        else:
+            disallowed = {token.LPAR, token.LSQB}
+
+        while 0 <= index < len(line.leaves):
+            current = line.leaves[index]
+            if current.type in disallowed:
+                return False
+            if current.type not in {token.NAME, token.DOT} or current.value == "for":
+                # If the current token isn't disallowed, we'll assume this is simple as
+                # only the disallowed tokens are semantically attached to this lookup
+                # expression we're checking. Also, stop early if we hit the 'for' bit
+                # of a comprehension.
+                return True
+
+            index += step
+
+        return True
+
+    def is_simple_operand(index: int, kind: Literal["base", "exponent"]) -> bool:
+        # An operand is considered "simple" if's a NAME, a numeric CONSTANT, a simple
+        # lookup (see above), with or without a preceding unary operator.
+        start = line.leaves[index]
+        if start.type in {token.NAME, token.NUMBER}:
+            return is_simple_lookup(index, step=(1 if kind == "exponent" else -1))
+
+        if start.type in {token.PLUS, token.MINUS, token.TILDE}:
+            if line.leaves[index + 1].type in {token.NAME, token.NUMBER}:
+                # step is always one as bases with a preceding unary op will be checked
+                # for simplicity starting from the next token (so it'll hit the check
+                # above).
+                return is_simple_lookup(index + 1, step=1)
+
+        return False
+
+    leaves: List[Leaf] = []
+    should_hug = False
+    for idx, leaf in enumerate(line.leaves):
+        new_leaf = leaf.clone()
+        if should_hug:
+            new_leaf.prefix = ""
+            should_hug = False
+
+        should_hug = (
+            (0 < idx < len(line.leaves) - 1)
+            and leaf.type == token.DOUBLESTAR
+            and is_simple_operand(idx - 1, kind="base")
+            and line.leaves[idx - 1].value != "lambda"
+            and is_simple_operand(idx + 1, kind="exponent")
+        )
+        if should_hug:
+            new_leaf.prefix = ""
+
+        leaves.append(new_leaf)
+
+    yield Line(
+        mode=line.mode,
+        depth=line.depth,
+        leaves=leaves,
+        comments=line.comments,
+        bracket_tracker=line.bracket_tracker,
+        inside_brackets=line.inside_brackets,
+        should_split_rhs=line.should_split_rhs,
+        magic_trailing_comma=line.magic_trailing_comma,
+    )
+
+
 class StringTransformer(ABC):
     """
     An implementation of the Transformer protocol that relies on its
diff --git a/src/black_primer/primer.json b/src/black_primer/primer.json
index a8d8fc9e21f..a6bfd4a2fec 100644
--- a/src/black_primer/primer.json
+++ b/src/black_primer/primer.json
@@ -81,7 +81,7 @@
     },
     "flake8-bugbear": {
       "cli_arguments": ["--experimental-string-processing"],
-      "expect_formatting_changes": false,
+      "expect_formatting_changes": true,
       "git_clone_url": "https://github.com/PyCQA/flake8-bugbear.git",
       "long_checkout": false,
       "py_versions": ["all"]
diff --git a/tests/data/expression.diff b/tests/data/expression.diff
index 721a07d2141..5f29a18dc7f 100644
--- a/tests/data/expression.diff
+++ b/tests/data/expression.diff
@@ -11,7 +11,17 @@
  True
  False
  1
-@@ -29,63 +29,96 @@
+@@ -21,71 +21,104 @@
+ Name1 or (Name2 and Name3) or Name4
+ Name1 or Name2 and Name3 or Name4
+ v1 << 2
+ 1 >> v2
+ 1 % finished
+-1 + v2 - v3 * 4 ^ 5 ** v6 / 7 // 8
+-((1 + v2) - (v3 * 4)) ^ (((5 ** v6) / 7) // 8)
++1 + v2 - v3 * 4 ^ 5**v6 / 7 // 8
++((1 + v2) - (v3 * 4)) ^ (((5**v6) / 7) // 8)
+ not great
  ~great
  +value
  -1
@@ -19,7 +29,7 @@
  (~int) and (not ((v1 ^ (123 + v2)) | True))
 -+really ** -confusing ** ~operator ** -precedence
 -flags & ~ select.EPOLLIN and waiters.write_task is not None
-++(really ** -(confusing ** ~(operator ** -precedence)))
+++(really ** -(confusing ** ~(operator**-precedence)))
 +flags & ~select.EPOLLIN and waiters.write_task is not None
  lambda arg: None
  lambda a=True: a
@@ -88,15 +98,19 @@
 +    *more,
 +]
  {i for i in (1, 2, 3)}
- {(i ** 2) for i in (1, 2, 3)}
+-{(i ** 2) for i in (1, 2, 3)}
 -{(i ** 2) for i, _ in ((1, 'a'), (2, 'b'), (3, 'c'))}
-+{(i ** 2) for i, _ in ((1, "a"), (2, "b"), (3, "c"))}
- {((i ** 2) + j) for i in (1, 2, 3) for j in (1, 2, 3)}
+-{((i ** 2) + j) for i in (1, 2, 3) for j in (1, 2, 3)}
++{(i**2) for i in (1, 2, 3)}
++{(i**2) for i, _ in ((1, "a"), (2, "b"), (3, "c"))}
++{((i**2) + j) for i in (1, 2, 3) for j in (1, 2, 3)}
  [i for i in (1, 2, 3)]
- [(i ** 2) for i in (1, 2, 3)]
+-[(i ** 2) for i in (1, 2, 3)]
 -[(i ** 2) for i, _ in ((1, 'a'), (2, 'b'), (3, 'c'))]
-+[(i ** 2) for i, _ in ((1, "a"), (2, "b"), (3, "c"))]
- [((i ** 2) + j) for i in (1, 2, 3) for j in (1, 2, 3)]
+-[((i ** 2) + j) for i in (1, 2, 3) for j in (1, 2, 3)]
++[(i**2) for i in (1, 2, 3)]
++[(i**2) for i, _ in ((1, "a"), (2, "b"), (3, "c"))]
++[((i**2) + j) for i in (1, 2, 3) for j in (1, 2, 3)]
  {i: 0 for i in (1, 2, 3)}
 -{i: j for i, j in ((1, 'a'), (2, 'b'), (3, 'c'))}
 +{i: j for i, j in ((1, "a"), (2, "b"), (3, "c"))}
@@ -181,10 +195,12 @@
  SomeName
  (Good, Bad, Ugly)
  (i for i in (1, 2, 3))
- ((i ** 2) for i in (1, 2, 3))
+-((i ** 2) for i in (1, 2, 3))
 -((i ** 2) for i, _ in ((1, 'a'), (2, 'b'), (3, 'c')))
-+((i ** 2) for i, _ in ((1, "a"), (2, "b"), (3, "c")))
- (((i ** 2) + j) for i in (1, 2, 3) for j in (1, 2, 3))
+-(((i ** 2) + j) for i in (1, 2, 3) for j in (1, 2, 3))
++((i**2) for i in (1, 2, 3))
++((i**2) for i, _ in ((1, "a"), (2, "b"), (3, "c")))
++(((i**2) + j) for i in (1, 2, 3) for j in (1, 2, 3))
  (*starred,)
 -{"id": "1","type": "type","started_at": now(),"ended_at": now() + timedelta(days=10),"priority": 1,"import_session_id": 1,**kwargs}
 +{
@@ -403,13 +419,13 @@
 +    return True
 +if (
 +    ~aaaa.a + aaaa.b - aaaa.c * aaaa.d / aaaa.e
-+    | aaaa.f & aaaa.g % aaaa.h ^ aaaa.i << aaaa.k >> aaaa.l ** aaaa.m // aaaa.n
++    | aaaa.f & aaaa.g % aaaa.h ^ aaaa.i << aaaa.k >> aaaa.l**aaaa.m // aaaa.n
 +):
 +    return True
 +if (
 +    ~aaaaaaaa.a + aaaaaaaa.b - aaaaaaaa.c @ aaaaaaaa.d / aaaaaaaa.e
 +    | aaaaaaaa.f & aaaaaaaa.g % aaaaaaaa.h
-+    ^ aaaaaaaa.i << aaaaaaaa.k >> aaaaaaaa.l ** aaaaaaaa.m // aaaaaaaa.n
++    ^ aaaaaaaa.i << aaaaaaaa.k >> aaaaaaaa.l**aaaaaaaa.m // aaaaaaaa.n
 +):
 +    return True
 +if (
@@ -419,7 +435,7 @@
 +    | aaaaaaaaaaaaaaaa.f & aaaaaaaaaaaaaaaa.g % aaaaaaaaaaaaaaaa.h
 +    ^ aaaaaaaaaaaaaaaa.i
 +    << aaaaaaaaaaaaaaaa.k
-+    >> aaaaaaaaaaaaaaaa.l ** aaaaaaaaaaaaaaaa.m // aaaaaaaaaaaaaaaa.n
++    >> aaaaaaaaaaaaaaaa.l**aaaaaaaaaaaaaaaa.m // aaaaaaaaaaaaaaaa.n
 +):
 +    return True
 +(
diff --git a/tests/data/expression.py b/tests/data/expression.py
index d13450cda68..b056841027d 100644
--- a/tests/data/expression.py
+++ b/tests/data/expression.py
@@ -282,15 +282,15 @@ async def f():
 v1 << 2
 1 >> v2
 1 % finished
-1 + v2 - v3 * 4 ^ 5 ** v6 / 7 // 8
-((1 + v2) - (v3 * 4)) ^ (((5 ** v6) / 7) // 8)
+1 + v2 - v3 * 4 ^ 5**v6 / 7 // 8
+((1 + v2) - (v3 * 4)) ^ (((5**v6) / 7) // 8)
 not great
 ~great
 +value
 -1
 ~int and not v1 ^ 123 + v2 | True
 (~int) and (not ((v1 ^ (123 + v2)) | True))
-+(really ** -(confusing ** ~(operator ** -precedence)))
++(really ** -(confusing ** ~(operator**-precedence)))
 flags & ~select.EPOLLIN and waiters.write_task is not None
 lambda arg: None
 lambda a=True: a
@@ -347,13 +347,13 @@ async def f():
     *more,
 ]
 {i for i in (1, 2, 3)}
-{(i ** 2) for i in (1, 2, 3)}
-{(i ** 2) for i, _ in ((1, "a"), (2, "b"), (3, "c"))}
-{((i ** 2) + j) for i in (1, 2, 3) for j in (1, 2, 3)}
+{(i**2) for i in (1, 2, 3)}
+{(i**2) for i, _ in ((1, "a"), (2, "b"), (3, "c"))}
+{((i**2) + j) for i in (1, 2, 3) for j in (1, 2, 3)}
 [i for i in (1, 2, 3)]
-[(i ** 2) for i in (1, 2, 3)]
-[(i ** 2) for i, _ in ((1, "a"), (2, "b"), (3, "c"))]
-[((i ** 2) + j) for i in (1, 2, 3) for j in (1, 2, 3)]
+[(i**2) for i in (1, 2, 3)]
+[(i**2) for i, _ in ((1, "a"), (2, "b"), (3, "c"))]
+[((i**2) + j) for i in (1, 2, 3) for j in (1, 2, 3)]
 {i: 0 for i in (1, 2, 3)}
 {i: j for i, j in ((1, "a"), (2, "b"), (3, "c"))}
 {a: b * 2 for a, b in dictionary.items()}
@@ -441,9 +441,9 @@ async def f():
 SomeName
 (Good, Bad, Ugly)
 (i for i in (1, 2, 3))
-((i ** 2) for i in (1, 2, 3))
-((i ** 2) for i, _ in ((1, "a"), (2, "b"), (3, "c")))
-(((i ** 2) + j) for i in (1, 2, 3) for j in (1, 2, 3))
+((i**2) for i in (1, 2, 3))
+((i**2) for i, _ in ((1, "a"), (2, "b"), (3, "c")))
+(((i**2) + j) for i in (1, 2, 3) for j in (1, 2, 3))
 (*starred,)
 {
     "id": "1",
@@ -588,13 +588,13 @@ async def f():
     return True
 if (
     ~aaaa.a + aaaa.b - aaaa.c * aaaa.d / aaaa.e
-    | aaaa.f & aaaa.g % aaaa.h ^ aaaa.i << aaaa.k >> aaaa.l ** aaaa.m // aaaa.n
+    | aaaa.f & aaaa.g % aaaa.h ^ aaaa.i << aaaa.k >> aaaa.l**aaaa.m // aaaa.n
 ):
     return True
 if (
     ~aaaaaaaa.a + aaaaaaaa.b - aaaaaaaa.c @ aaaaaaaa.d / aaaaaaaa.e
     | aaaaaaaa.f & aaaaaaaa.g % aaaaaaaa.h
-    ^ aaaaaaaa.i << aaaaaaaa.k >> aaaaaaaa.l ** aaaaaaaa.m // aaaaaaaa.n
+    ^ aaaaaaaa.i << aaaaaaaa.k >> aaaaaaaa.l**aaaaaaaa.m // aaaaaaaa.n
 ):
     return True
 if (
@@ -604,7 +604,7 @@ async def f():
     | aaaaaaaaaaaaaaaa.f & aaaaaaaaaaaaaaaa.g % aaaaaaaaaaaaaaaa.h
     ^ aaaaaaaaaaaaaaaa.i
     << aaaaaaaaaaaaaaaa.k
-    >> aaaaaaaaaaaaaaaa.l ** aaaaaaaaaaaaaaaa.m // aaaaaaaaaaaaaaaa.n
+    >> aaaaaaaaaaaaaaaa.l**aaaaaaaaaaaaaaaa.m // aaaaaaaaaaaaaaaa.n
 ):
     return True
 (
diff --git a/tests/data/expression_skip_magic_trailing_comma.diff b/tests/data/expression_skip_magic_trailing_comma.diff
index 4a8a95c7237..5b722c91352 100644
--- a/tests/data/expression_skip_magic_trailing_comma.diff
+++ b/tests/data/expression_skip_magic_trailing_comma.diff
@@ -11,7 +11,17 @@
  True
  False
  1
-@@ -29,63 +29,84 @@
+@@ -21,71 +21,92 @@
+ Name1 or (Name2 and Name3) or Name4
+ Name1 or Name2 and Name3 or Name4
+ v1 << 2
+ 1 >> v2
+ 1 % finished
+-1 + v2 - v3 * 4 ^ 5 ** v6 / 7 // 8
+-((1 + v2) - (v3 * 4)) ^ (((5 ** v6) / 7) // 8)
++1 + v2 - v3 * 4 ^ 5**v6 / 7 // 8
++((1 + v2) - (v3 * 4)) ^ (((5**v6) / 7) // 8)
+ not great
  ~great
  +value
  -1
@@ -19,7 +29,7 @@
  (~int) and (not ((v1 ^ (123 + v2)) | True))
 -+really ** -confusing ** ~operator ** -precedence
 -flags & ~ select.EPOLLIN and waiters.write_task is not None
-++(really ** -(confusing ** ~(operator ** -precedence)))
+++(really ** -(confusing ** ~(operator**-precedence)))
 +flags & ~select.EPOLLIN and waiters.write_task is not None
  lambda arg: None
  lambda a=True: a
@@ -76,15 +86,19 @@
 +    *more,
 +]
  {i for i in (1, 2, 3)}
- {(i ** 2) for i in (1, 2, 3)}
+-{(i ** 2) for i in (1, 2, 3)}
 -{(i ** 2) for i, _ in ((1, 'a'), (2, 'b'), (3, 'c'))}
-+{(i ** 2) for i, _ in ((1, "a"), (2, "b"), (3, "c"))}
- {((i ** 2) + j) for i in (1, 2, 3) for j in (1, 2, 3)}
+-{((i ** 2) + j) for i in (1, 2, 3) for j in (1, 2, 3)}
++{(i**2) for i in (1, 2, 3)}
++{(i**2) for i, _ in ((1, "a"), (2, "b"), (3, "c"))}
++{((i**2) + j) for i in (1, 2, 3) for j in (1, 2, 3)}
  [i for i in (1, 2, 3)]
- [(i ** 2) for i in (1, 2, 3)]
+-[(i ** 2) for i in (1, 2, 3)]
 -[(i ** 2) for i, _ in ((1, 'a'), (2, 'b'), (3, 'c'))]
-+[(i ** 2) for i, _ in ((1, "a"), (2, "b"), (3, "c"))]
- [((i ** 2) + j) for i in (1, 2, 3) for j in (1, 2, 3)]
+-[((i ** 2) + j) for i in (1, 2, 3) for j in (1, 2, 3)]
++[(i**2) for i in (1, 2, 3)]
++[(i**2) for i, _ in ((1, "a"), (2, "b"), (3, "c"))]
++[((i**2) + j) for i in (1, 2, 3) for j in (1, 2, 3)]
  {i: 0 for i in (1, 2, 3)}
 -{i: j for i, j in ((1, 'a'), (2, 'b'), (3, 'c'))}
 +{i: j for i, j in ((1, "a"), (2, "b"), (3, "c"))}
@@ -164,10 +178,12 @@
  SomeName
  (Good, Bad, Ugly)
  (i for i in (1, 2, 3))
- ((i ** 2) for i in (1, 2, 3))
+-((i ** 2) for i in (1, 2, 3))
 -((i ** 2) for i, _ in ((1, 'a'), (2, 'b'), (3, 'c')))
-+((i ** 2) for i, _ in ((1, "a"), (2, "b"), (3, "c")))
- (((i ** 2) + j) for i in (1, 2, 3) for j in (1, 2, 3))
+-(((i ** 2) + j) for i in (1, 2, 3) for j in (1, 2, 3))
++((i**2) for i in (1, 2, 3))
++((i**2) for i, _ in ((1, "a"), (2, "b"), (3, "c")))
++(((i**2) + j) for i in (1, 2, 3) for j in (1, 2, 3))
  (*starred,)
 -{"id": "1","type": "type","started_at": now(),"ended_at": now() + timedelta(days=10),"priority": 1,"import_session_id": 1,**kwargs}
 +{
@@ -384,13 +400,13 @@
 +    return True
 +if (
 +    ~aaaa.a + aaaa.b - aaaa.c * aaaa.d / aaaa.e
-+    | aaaa.f & aaaa.g % aaaa.h ^ aaaa.i << aaaa.k >> aaaa.l ** aaaa.m // aaaa.n
++    | aaaa.f & aaaa.g % aaaa.h ^ aaaa.i << aaaa.k >> aaaa.l**aaaa.m // aaaa.n
 +):
 +    return True
 +if (
 +    ~aaaaaaaa.a + aaaaaaaa.b - aaaaaaaa.c @ aaaaaaaa.d / aaaaaaaa.e
 +    | aaaaaaaa.f & aaaaaaaa.g % aaaaaaaa.h
-+    ^ aaaaaaaa.i << aaaaaaaa.k >> aaaaaaaa.l ** aaaaaaaa.m // aaaaaaaa.n
++    ^ aaaaaaaa.i << aaaaaaaa.k >> aaaaaaaa.l**aaaaaaaa.m // aaaaaaaa.n
 +):
 +    return True
 +if (
@@ -400,7 +416,7 @@
 +    | aaaaaaaaaaaaaaaa.f & aaaaaaaaaaaaaaaa.g % aaaaaaaaaaaaaaaa.h
 +    ^ aaaaaaaaaaaaaaaa.i
 +    << aaaaaaaaaaaaaaaa.k
-+    >> aaaaaaaaaaaaaaaa.l ** aaaaaaaaaaaaaaaa.m // aaaaaaaaaaaaaaaa.n
++    >> aaaaaaaaaaaaaaaa.l**aaaaaaaaaaaaaaaa.m // aaaaaaaaaaaaaaaa.n
 +):
 +    return True
 +(
diff --git a/tests/data/pep_572.py b/tests/data/pep_572.py
index c6867f26258..d41805f1cb1 100644
--- a/tests/data/pep_572.py
+++ b/tests/data/pep_572.py
@@ -4,7 +4,7 @@
     pass
 if match := pattern.search(data):
     pass
-[y := f(x), y ** 2, y ** 3]
+[y := f(x), y**2, y**3]
 filtered_data = [y for x in data if (y := f(x)) is None]
 (y := f(x))
 y0 = (y1 := f(x))
diff --git a/tests/data/pep_572_py39.py b/tests/data/pep_572_py39.py
index 7bbd5091197..b8b081b8c45 100644
--- a/tests/data/pep_572_py39.py
+++ b/tests/data/pep_572_py39.py
@@ -1,7 +1,7 @@
 # Unparenthesized walruses are now allowed in set literals & set comprehensions
 # since Python 3.9
 {x := 1, 2, 3}
-{x4 := x ** 5 for x in range(7)}
+{x4 := x**5 for x in range(7)}
 # We better not remove the parentheses here (since it's a 3.10 feature)
 x[(a := 1)]
 x[(a := 1), (b := 3)]
diff --git a/tests/data/power_op_spacing.py b/tests/data/power_op_spacing.py
new file mode 100644
index 00000000000..87dde7f39dc
--- /dev/null
+++ b/tests/data/power_op_spacing.py
@@ -0,0 +1,103 @@
+def function(**kwargs):
+    t = a**2 + b**3
+    return t ** 2
+
+
+def function_replace_spaces(**kwargs):
+    t = a **2 + b** 3 + c ** 4
+
+
+def function_dont_replace_spaces():
+    {**a, **b, **c}
+
+
+a = 5**~4
+b = 5 ** f()
+c = -(5**2)
+d = 5 ** f["hi"]
+e = lazy(lambda **kwargs: 5)
+f = f() ** 5
+g = a.b**c.d
+h = 5 ** funcs.f()
+i = funcs.f() ** 5
+j = super().name ** 5
+k = [(2**idx, value) for idx, value in pairs]
+l = mod.weights_[0] == pytest.approx(0.95**100, abs=0.001)
+m = [([2**63], [1, 2**63])]
+n = count <= 10**5
+o = settings(max_examples=10**6)
+p = {(k, k**2): v**2 for k, v in pairs}
+q = [10**i for i in range(6)]
+r = x**y
+
+a = 5.0**~4.0
+b = 5.0 ** f()
+c = -(5.0**2.0)
+d = 5.0 ** f["hi"]
+e = lazy(lambda **kwargs: 5)
+f = f() ** 5.0
+g = a.b**c.d
+h = 5.0 ** funcs.f()
+i = funcs.f() ** 5.0
+j = super().name ** 5.0
+k = [(2.0**idx, value) for idx, value in pairs]
+l = mod.weights_[0] == pytest.approx(0.95**100, abs=0.001)
+m = [([2.0**63.0], [1.0, 2**63.0])]
+n = count <= 10**5.0
+o = settings(max_examples=10**6.0)
+p = {(k, k**2): v**2.0 for k, v in pairs}
+q = [10.5**i for i in range(6)]
+
+
+# output
+
+
+def function(**kwargs):
+    t = a**2 + b**3
+    return t**2
+
+
+def function_replace_spaces(**kwargs):
+    t = a**2 + b**3 + c**4
+
+
+def function_dont_replace_spaces():
+    {**a, **b, **c}
+
+
+a = 5**~4
+b = 5 ** f()
+c = -(5**2)
+d = 5 ** f["hi"]
+e = lazy(lambda **kwargs: 5)
+f = f() ** 5
+g = a.b**c.d
+h = 5 ** funcs.f()
+i = funcs.f() ** 5
+j = super().name ** 5
+k = [(2**idx, value) for idx, value in pairs]
+l = mod.weights_[0] == pytest.approx(0.95**100, abs=0.001)
+m = [([2**63], [1, 2**63])]
+n = count <= 10**5
+o = settings(max_examples=10**6)
+p = {(k, k**2): v**2 for k, v in pairs}
+q = [10**i for i in range(6)]
+r = x**y
+
+a = 5.0**~4.0
+b = 5.0 ** f()
+c = -(5.0**2.0)
+d = 5.0 ** f["hi"]
+e = lazy(lambda **kwargs: 5)
+f = f() ** 5.0
+g = a.b**c.d
+h = 5.0 ** funcs.f()
+i = funcs.f() ** 5.0
+j = super().name ** 5.0
+k = [(2.0**idx, value) for idx, value in pairs]
+l = mod.weights_[0] == pytest.approx(0.95**100, abs=0.001)
+m = [([2.0**63.0], [1.0, 2**63.0])]
+n = count <= 10**5.0
+o = settings(max_examples=10**6.0)
+p = {(k, k**2): v**2.0 for k, v in pairs}
+q = [10.5**i for i in range(6)]
diff --git a/tests/data/slices.py b/tests/data/slices.py
index 7a42678f646..165117cdcb4 100644
--- a/tests/data/slices.py
+++ b/tests/data/slices.py
@@ -9,7 +9,7 @@
 slice[:c, c - 1]
 slice[c, c + 1, d::]
 slice[ham[c::d] :: 1]
-slice[ham[cheese ** 2 : -1] : 1 : 1, ham[1:2]]
+slice[ham[cheese**2 : -1] : 1 : 1, ham[1:2]]
 slice[:-1:]
 slice[lambda: None : lambda: None]
 slice[lambda x, y, *args, really=2, **kwargs: None :, None::]
diff --git a/tests/test_format.py b/tests/test_format.py
index 3895a095e86..c6c811040dc 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -48,6 +48,7 @@
     "function2",
     "function_trailing_comma",
     "import_spacing",
+    "power_op_spacing",
     "remove_parens",
     "slices",
     "string_prefixes",

From 32dd9ecb2e9dec8b29c07726d5713ed5b4c36547 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Tue, 25 Jan 2022 15:58:58 -0800
Subject: [PATCH 0440/1034] properly run ourselves twice (#2807)

The previous run-twice logic only affected the stability checks but not the output. Now, we actually output the twice-formatted code.
---
 CHANGES.md                                    |  2 +
 src/black/__init__.py                         | 29 +++++++-------
 tests/data/trailing_comma_optional_parens1.py | 12 ++++++
 tests/data/trailing_comma_optional_parens2.py | 16 +++++++-
 tests/data/trailing_comma_optional_parens3.py | 18 ++++++++-
 tests/test_black.py                           | 39 -------------------
 tests/test_format.py                          |  3 ++
 7 files changed, 65 insertions(+), 54 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index d203896a801..37990686508 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -40,6 +40,8 @@
 - Enable Python 3.10+ by default, without any extra need to specify
   `--target-version=py310`. (#2758)
 - Make passing `SRC` or `--code` mandatory and mutually exclusive (#2804)
+- Work around bug that causes unstable formatting in some cases in the presence of the
+  magic trailing comma (#2807)
 
 ### Packaging
 
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 7024c9d52b0..769e693ed23 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -968,17 +968,7 @@ def check_stability_and_equivalence(
     content differently.
     """
     assert_equivalent(src_contents, dst_contents)
-
-    # Forced second pass to work around optional trailing commas (becoming
-    # forced trailing commas on pass 2) interacting differently with optional
-    # parentheses.  Admittedly ugly.
-    dst_contents_pass2 = format_str(dst_contents, mode=mode)
-    if dst_contents != dst_contents_pass2:
-        dst_contents = dst_contents_pass2
-        assert_equivalent(src_contents, dst_contents, pass_num=2)
-        assert_stable(src_contents, dst_contents, mode=mode)
-    # Note: no need to explicitly call `assert_stable` if `dst_contents` was
-    # the same as `dst_contents_pass2`.
+    assert_stable(src_contents, dst_contents, mode=mode)
 
 
 def format_file_contents(src_contents: str, *, fast: bool, mode: Mode) -> FileContent:
@@ -1108,7 +1098,7 @@ def format_ipynb_string(src_contents: str, *, fast: bool, mode: Mode) -> FileCon
         raise NothingChanged
 
 
-def format_str(src_contents: str, *, mode: Mode) -> FileContent:
+def format_str(src_contents: str, *, mode: Mode) -> str:
     """Reformat a string and return new contents.
 
     `mode` determines formatting options, such as how many characters per line are
@@ -1138,6 +1128,16 @@ def f(
         hey
 
     """
+    dst_contents = _format_str_once(src_contents, mode=mode)
+    # Forced second pass to work around optional trailing commas (becoming
+    # forced trailing commas on pass 2) interacting differently with optional
+    # parentheses.  Admittedly ugly.
+    if src_contents != dst_contents:
+        return _format_str_once(dst_contents, mode=mode)
+    return dst_contents
+
+
+def _format_str_once(src_contents: str, *, mode: Mode) -> str:
     src_node = lib2to3_parse(src_contents.lstrip(), mode.target_versions)
     dst_contents = []
     future_imports = get_future_imports(src_node)
@@ -1367,7 +1367,10 @@ def assert_equivalent(src: str, dst: str, *, pass_num: int = 1) -> None:
 
 def assert_stable(src: str, dst: str, mode: Mode) -> None:
     """Raise AssertionError if `dst` reformats differently the second time."""
-    newdst = format_str(dst, mode=mode)
+    # We shouldn't call format_str() here, because that formats the string
+    # twice and may hide a bug where we bounce back and forth between two
+    # versions.
+    newdst = _format_str_once(dst, mode=mode)
     if dst != newdst:
         log = dump_to_file(
             str(mode),
diff --git a/tests/data/trailing_comma_optional_parens1.py b/tests/data/trailing_comma_optional_parens1.py
index 5ad29a8affd..f5be2f24cf4 100644
--- a/tests/data/trailing_comma_optional_parens1.py
+++ b/tests/data/trailing_comma_optional_parens1.py
@@ -1,3 +1,15 @@
 if e1234123412341234.winerror not in (_winapi.ERROR_SEM_TIMEOUT,
                         _winapi.ERROR_PIPE_BUSY) or _check_timeout(t):
+    pass
+
+# output
+
+if (
+    e1234123412341234.winerror
+    not in (
+        _winapi.ERROR_SEM_TIMEOUT,
+        _winapi.ERROR_PIPE_BUSY,
+    )
+    or _check_timeout(t)
+):
     pass
\ No newline at end of file
diff --git a/tests/data/trailing_comma_optional_parens2.py b/tests/data/trailing_comma_optional_parens2.py
index 2817073816e..1dfb54ca687 100644
--- a/tests/data/trailing_comma_optional_parens2.py
+++ b/tests/data/trailing_comma_optional_parens2.py
@@ -1,3 +1,17 @@
 if (e123456.get_tk_patchlevel() >= (8, 6, 0, 'final') or
     (8, 5, 8) <= get_tk_patchlevel() < (8, 6)):
-    pass
\ No newline at end of file
+    pass
+
+# output
+
+if (
+    e123456.get_tk_patchlevel() >= (8, 6, 0, "final")
+    or (
+        8,
+        5,
+        8,
+    )
+    <= get_tk_patchlevel()
+    < (8, 6)
+):
+    pass
diff --git a/tests/data/trailing_comma_optional_parens3.py b/tests/data/trailing_comma_optional_parens3.py
index e6a673ec537..bccf47430a7 100644
--- a/tests/data/trailing_comma_optional_parens3.py
+++ b/tests/data/trailing_comma_optional_parens3.py
@@ -5,4 +5,20 @@
                 "qweasdzxcqweasdzxcqweasdzxcqweasdzxcqweasdzxcqweasdzxcqweasdzxcqweasdzxcqweasdzxcqweas "
                 + "qweasdzxcqweasdzxcqweasdzxcqweasdzxcqweasdzxcqweasdzxcqweasdzxcqweasdzxcqwegqweasdzxcqweasdzxc.",
                 "qweasdzxcqweasdzxcqweasdzxcqweasdzxcqweasdzxcqweasdzxcqweasdzxcqweasdzxcqweasdzxcqwe",
-            ) % {"reported_username": reported_username, "report_reason": report_reason}
\ No newline at end of file
+            ) % {"reported_username": reported_username, "report_reason": report_reason}
+
+
+# output
+
+
+if True:
+    if True:
+        if True:
+            return _(
+                "qweasdzxcqweasdzxcqweasdzxcqweasdzxcqweasdzxcqweasdzxcqweasdzxcqweasdzxcqweasdzxcqweas "
+                + "qweasdzxcqweasdzxcqweasdzxcqweasdzxcqweasdzxcqweasdzxcqweasdzxcqweasdzxcqwegqweasdzxcqweasdzxc.",
+                "qweasdzxcqweasdzxcqweasdzxcqweasdzxcqweasdzxcqweasdzxcqweasdzxcqweasdzxcqweasdzxcqwe",
+            ) % {
+                "reported_username": reported_username,
+                "report_reason": report_reason,
+            }
\ No newline at end of file
diff --git a/tests/test_black.py b/tests/test_black.py
index 8d691d2f019..2dd284f2cd6 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -228,45 +228,6 @@ def _test_wip(self) -> None:
         black.assert_equivalent(source, actual)
         black.assert_stable(source, actual, black.FileMode())
 
-    @unittest.expectedFailure
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_trailing_comma_optional_parens_stability1(self) -> None:
-        source, _expected = read_data("trailing_comma_optional_parens1")
-        actual = fs(source)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
-    @unittest.expectedFailure
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_trailing_comma_optional_parens_stability2(self) -> None:
-        source, _expected = read_data("trailing_comma_optional_parens2")
-        actual = fs(source)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
-    @unittest.expectedFailure
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_trailing_comma_optional_parens_stability3(self) -> None:
-        source, _expected = read_data("trailing_comma_optional_parens3")
-        actual = fs(source)
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_trailing_comma_optional_parens_stability1_pass2(self) -> None:
-        source, _expected = read_data("trailing_comma_optional_parens1")
-        actual = fs(fs(source))  # this is what `format_file_contents` does with --safe
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_trailing_comma_optional_parens_stability2_pass2(self) -> None:
-        source, _expected = read_data("trailing_comma_optional_parens2")
-        actual = fs(fs(source))  # this is what `format_file_contents` does with --safe
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
-    @patch("black.dump_to_file", dump_to_stderr)
-    def test_trailing_comma_optional_parens_stability3_pass2(self) -> None:
-        source, _expected = read_data("trailing_comma_optional_parens3")
-        actual = fs(fs(source))  # this is what `format_file_contents` does with --safe
-        black.assert_stable(source, actual, DEFAULT_MODE)
-
     def test_pep_572_version_detection(self) -> None:
         source, _ = read_data("pep_572")
         root = black.lib2to3_parse(source)
diff --git a/tests/test_format.py b/tests/test_format.py
index c6c811040dc..a4619b4a652 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -52,6 +52,9 @@
     "remove_parens",
     "slices",
     "string_prefixes",
+    "trailing_comma_optional_parens1",
+    "trailing_comma_optional_parens2",
+    "trailing_comma_optional_parens3",
     "tricky_unicode_symbols",
     "tupleassign",
 ]

From 889a8d5dd27a73aa780e989a850bbdaaa9946a13 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Wed, 26 Jan 2022 16:47:36 -0800
Subject: [PATCH 0441/1034] Fix crash on some power hugging cases (#2806)

Found by the fuzzer. Repro case:

	python -m black -c 'importA;()<<0**0#'
---
 src/black/linegen.py           |  2 ++
 src/black/lines.py             |  4 +++-
 src/blib2to3/pytree.py         |  6 +++++-
 tests/data/power_op_newline.py | 10 ++++++++++
 tests/test_format.py           |  6 ++++++
 5 files changed, 26 insertions(+), 2 deletions(-)
 create mode 100644 tests/data/power_op_newline.py

diff --git a/src/black/linegen.py b/src/black/linegen.py
index 9fbdfadba6a..ac60ed1986d 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -942,6 +942,7 @@ def generate_trailers_to_omit(line: Line, line_length: int) -> Iterator[Set[Leaf
                 if (
                     prev
                     and prev.type == token.COMMA
+                    and leaf.opening_bracket is not None
                     and not is_one_tuple_between(
                         leaf.opening_bracket, leaf, line.leaves
                     )
@@ -969,6 +970,7 @@ def generate_trailers_to_omit(line: Line, line_length: int) -> Iterator[Set[Leaf
             if (
                 prev
                 and prev.type == token.COMMA
+                and leaf.opening_bracket is not None
                 and not is_one_tuple_between(leaf.opening_bracket, leaf, line.leaves)
             ):
                 # Never omit bracket pairs with trailing commas.
diff --git a/src/black/lines.py b/src/black/lines.py
index c602aa69ce9..7d50f02aebc 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -277,7 +277,9 @@ def has_magic_trailing_comma(
         if self.is_import:
             return True
 
-        if not is_one_tuple_between(closing.opening_bracket, closing, self.leaves):
+        if closing.opening_bracket is not None and not is_one_tuple_between(
+            closing.opening_bracket, closing, self.leaves
+        ):
             return True
 
         return False
diff --git a/src/blib2to3/pytree.py b/src/blib2to3/pytree.py
index bd86270b8e2..b203ce5b2ac 100644
--- a/src/blib2to3/pytree.py
+++ b/src/blib2to3/pytree.py
@@ -386,7 +386,8 @@ class Leaf(Base):
     value: Text
     fixers_applied: List[Any]
     bracket_depth: int
-    opening_bracket: "Leaf"
+    # Changed later in brackets.py
+    opening_bracket: Optional["Leaf"] = None
     used_names: Optional[Set[Text]]
     _prefix = ""  # Whitespace and comments preceding this token in the input
     lineno: int = 0  # Line where this token starts in the input
@@ -399,6 +400,7 @@ def __init__(
         context: Optional[Context] = None,
         prefix: Optional[Text] = None,
         fixers_applied: List[Any] = [],
+        opening_bracket: Optional["Leaf"] = None,
     ) -> None:
         """
         Initializer.
@@ -416,6 +418,7 @@ def __init__(
             self._prefix = prefix
         self.fixers_applied: Optional[List[Any]] = fixers_applied[:]
         self.children = []
+        self.opening_bracket = opening_bracket
 
     def __repr__(self) -> str:
         """Return a canonical string representation."""
@@ -448,6 +451,7 @@ def clone(self) -> "Leaf":
             self.value,
             (self.prefix, (self.lineno, self.column)),
             fixers_applied=self.fixers_applied,
+            opening_bracket=self.opening_bracket,
         )
 
     def leaves(self) -> Iterator["Leaf"]:
diff --git a/tests/data/power_op_newline.py b/tests/data/power_op_newline.py
new file mode 100644
index 00000000000..85d434d63f6
--- /dev/null
+++ b/tests/data/power_op_newline.py
@@ -0,0 +1,10 @@
+importA;()<<0**0#
+
+# output
+
+importA
+(
+    ()
+    << 0
+    ** 0
+)  #
diff --git a/tests/test_format.py b/tests/test_format.py
index a4619b4a652..88f084ea478 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -256,3 +256,9 @@ def test_python38() -> None:
 def test_python39() -> None:
     source, expected = read_data("python39")
     assert_format(source, expected, minimum_version=(3, 9))
+
+
+def test_power_op_newline() -> None:
+    # requires line_length=0
+    source, expected = read_data("power_op_newline")
+    assert_format(source, expected, mode=black.Mode(line_length=0))

From b517dfb396a82ef263f0d366c4dc107451cf0c3c Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Wed, 26 Jan 2022 17:18:43 -0800
Subject: [PATCH 0442/1034] black-primer: stop running it (#2809)

At the moment, it's just a source of spurious CI failures and busywork
updating the configuration file.

Unlike diff-shades, it is run across many different platforms and
Python versions, but that doesn't seem essential. We already run unit
tests across platforms and versions.

I chose to leave the code around for now in case somebody is using it,
but CI will no longer run it.
---
 .github/workflows/primer.yml         | 47 --------------------------
 .github/workflows/uvloop_test.yml    |  4 +--
 CHANGES.md                           |  1 +
 README.md                            |  1 -
 docs/contributing/gauging_changes.md | 49 ++++------------------------
 docs/contributing/the_basics.md      | 15 ---------
 6 files changed, 10 insertions(+), 107 deletions(-)
 delete mode 100644 .github/workflows/primer.yml

diff --git a/.github/workflows/primer.yml b/.github/workflows/primer.yml
deleted file mode 100644
index 5fa6ac066e3..00000000000
--- a/.github/workflows/primer.yml
+++ /dev/null
@@ -1,47 +0,0 @@
-name: Primer
-
-on:
-  push:
-    paths-ignore:
-      - "docs/**"
-      - "*.md"
-
-  pull_request:
-    paths-ignore:
-      - "docs/**"
-      - "*.md"
-
-jobs:
-  build:
-    # We want to run on external PRs, but not on our own internal PRs as they'll be run
-    # by the push to the branch. Without this if check, checks are duplicated since
-    # internal PRs match both the push and pull_request events.
-    if:
-      github.event_name == 'push' || github.event.pull_request.head.repo.full_name !=
-      github.repository
-
-    runs-on: ${{ matrix.os }}
-    strategy:
-      fail-fast: false
-      matrix:
-        python-version: ["3.6", "3.7", "3.8", "3.9", "3.10"]
-        os: [ubuntu-latest, windows-latest]
-
-    steps:
-      - uses: actions/checkout@v2
-
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v2
-        with:
-          python-version: ${{ matrix.python-version }}
-
-      - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip
-          python -m pip install -e ".[d,jupyter]"
-
-      - name: Primer run
-        env:
-          pythonioencoding: utf-8
-        run: |
-          black-primer
diff --git a/.github/workflows/uvloop_test.yml b/.github/workflows/uvloop_test.yml
index 5d23ec64299..a639bbd1b97 100644
--- a/.github/workflows/uvloop_test.yml
+++ b/.github/workflows/uvloop_test.yml
@@ -40,6 +40,6 @@ jobs:
         run: |
           python -m pip install -e ".[uvloop]"
 
-      - name: Primer uvloop run
+      - name: Format ourselves
         run: |
-          black-primer
+          python -m black --check src/
diff --git a/CHANGES.md b/CHANGES.md
index 37990686508..0dc4952f069 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -42,6 +42,7 @@
 - Make passing `SRC` or `--code` mandatory and mutually exclusive (#2804)
 - Work around bug that causes unstable formatting in some cases in the presence of the
   magic trailing comma (#2807)
+- Deprecate the `black-primer` tool (#2809)
 
 ### Packaging
 
diff --git a/README.md b/README.md
index e900d2d75a2..a00495c8858 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,6 @@
 
 <p align="center">
 <a href="/psf/black/actions"><img alt="Actions Status" src="https://github.com/psf/black/workflows/Test/badge.svg"></a>
-<a href="/psf/black/actions"><img alt="Actions Status" src="https://github.com/psf/black/workflows/Primer/badge.svg"></a>
 <a href="https://black.readthedocs.io/en/stable/?badge=stable"><img alt="Documentation Status" src="https://readthedocs.org/projects/black/badge/?version=stable"></a>
 <a href="https://coveralls.io/github/psf/black?branch=main"><img alt="Coverage Status" src="https://coveralls.io/repos/github/psf/black/badge.svg?branch=main"></a>
 <a href="/psf/black/blob/main/LICENSE"><img alt="License: MIT" src="https://black.readthedocs.io/en/stable/_static/license.svg"></a>
diff --git a/docs/contributing/gauging_changes.md b/docs/contributing/gauging_changes.md
index 9b38fe1b628..59c40eb3909 100644
--- a/docs/contributing/gauging_changes.md
+++ b/docs/contributing/gauging_changes.md
@@ -9,51 +9,16 @@ enough to cause frustration to projects that are already "black formatted".
 
 ## black-primer
 
-`black-primer` is a tool built for CI (and humans) to have _Black_ `--check` a number of
-Git accessible projects in parallel. (configured in `primer.json`) _(A PR will be
-accepted to add Mercurial support.)_
-
-### Run flow
-
-- Ensure we have a `black` + `git` in PATH
-- Load projects from `primer.json`
-- Run projects in parallel with `--worker` workers (defaults to CPU count / 2)
-  - Checkout projects
-  - Run black and record result
-  - Clean up repository checkout _(can optionally be disabled via `--keep`)_
-- Display results summary to screen
-- Default to cleaning up `--work-dir` (which defaults to tempfile schemantics)
-- Return
-  - 0 for successful run
-  - \< 0 for environment / internal error
-  - \> 0 for each project with an error
-
-### Speed up runs 🏎
-
-If you're running locally yourself to test black on lots of code try:
-
-- Using `-k` / `--keep` + `-w` / `--work-dir` so you don't have to re-checkout the repo
-  each run
-
-### CLI arguments
-
-```{program-output} black-primer --help
-
-```
+`black-primer` is an obsolete tool (now replaced with `diff-shades`) that was used to
+gauge the impact of changes in _Black_ on open-source code. It is no longer used
+internally and will be removed from the _Black_ repository in the future.
 
 ## diff-shades
 
-diff-shades is a tool similar to black-primer, it also runs _Black_ across a list of Git
-cloneable OSS projects recording the results. The intention is to eventually fully
-replace black-primer with diff-shades as it's much more feature complete and supports
-our needs better.
-
-The main highlight feature of diff-shades is being able to compare two revisions of
-_Black_. This is incredibly useful as it allows us to see what exact changes will occur,
-say merging a certain PR. Black-primer's results would usually be filled with changes
-caused by pre-existing code in Black drowning out the (new) changes we want to see. It
-operates similarly to black-primer but crucially it saves the results as a JSON file
-which allows for the rich comparison features alluded to above.
+diff-shades is a tool that runs _Black_ across a list of Git cloneable OSS projects
+recording the results. The main highlight feature of diff-shades is being able to
+compare two revisions of _Black_. This is incredibly useful as it allows us to see what
+exact changes will occur, say merging a certain PR.
 
 For more information, please see the [diff-shades documentation][diff-shades].
 
diff --git a/docs/contributing/the_basics.md b/docs/contributing/the_basics.md
index 23fbb8a3d7e..9325a9e44ed 100644
--- a/docs/contributing/the_basics.md
+++ b/docs/contributing/the_basics.md
@@ -30,9 +30,6 @@ the root of the black repo:
 
 # Optional Fuzz testing
 (.venv)$ tox -e fuzz
-
-# Optional CI run to test your changes on many popular python projects
-(.venv)$ black-primer [-k -w /tmp/black_test_repos]
 ```
 
 ### News / Changelog Requirement
@@ -69,18 +66,6 @@ If you make changes to docs, you can test they still build locally too.
 (.venv)$ sphinx-build -a -b html -W docs/ docs/_build/
 ```
 
-## black-primer
-
-`black-primer` is used by CI to pull down well-known _Black_ formatted projects and see
-if we get source code changes. It will error on formatting changes or errors. Please run
-before pushing your PR to see if you get the actions you would expect from _Black_ with
-your PR. You may need to change
-[primer.json](https://github.com/psf/black/blob/main/src/black_primer/primer.json)
-configuration for it to pass.
-
-For more `black-primer` information visit the
-[documentation](./gauging_changes.md#black-primer).
-
 ## Hygiene
 
 If you're fixing a bug, add a test. Run it first to confirm it fails, then fix the bug,

From b92822afeedd45daa3b1d094a502daf936f7fa9d Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Wed, 26 Jan 2022 19:44:39 -0800
Subject: [PATCH 0443/1034] more trailing comma tests (#2810)

---
 tests/data/trailing_comma_optional_parens1.py | 48 ++++++++++++++++++-
 1 file changed, 47 insertions(+), 1 deletion(-)

diff --git a/tests/data/trailing_comma_optional_parens1.py b/tests/data/trailing_comma_optional_parens1.py
index f5be2f24cf4..f9f4ae5e023 100644
--- a/tests/data/trailing_comma_optional_parens1.py
+++ b/tests/data/trailing_comma_optional_parens1.py
@@ -2,6 +2,25 @@
                         _winapi.ERROR_PIPE_BUSY) or _check_timeout(t):
     pass
 
+
+class X:
+    def get_help_text(self):
+        return ngettext(
+            "Your password must contain at least %(min_length)d character.",
+            "Your password must contain at least %(min_length)d characters.",
+            self.min_length,
+        ) % {'min_length': self.min_length}
+
+class A:
+    def b(self):
+        if self.connection.mysql_is_mariadb and (
+            10,
+            4,
+            3,
+        ) < self.connection.mysql_version < (10, 5, 2):
+            pass
+
+
 # output
 
 if (
@@ -12,4 +31,31 @@
     )
     or _check_timeout(t)
 ):
-    pass
\ No newline at end of file
+    pass
+
+
+class X:
+    def get_help_text(self):
+        return (
+            ngettext(
+                "Your password must contain at least %(min_length)d character.",
+                "Your password must contain at least %(min_length)d characters.",
+                self.min_length,
+            )
+            % {"min_length": self.min_length}
+        )
+
+
+class A:
+    def b(self):
+        if (
+            self.connection.mysql_is_mariadb
+            and (
+                10,
+                4,
+                3,
+            )
+            < self.connection.mysql_version
+            < (10, 5, 2)
+        ):
+            pass

From 777cae55b601f8a501e2138cec99361929b128ea Mon Sep 17 00:00:00 2001
From: Shivansh-007 <shivansh-007@outlook.com>
Date: Fri, 28 Jan 2022 11:01:50 +0530
Subject: [PATCH 0444/1034] Use parentheses on method access on float and int
 literals (#2799)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Co-authored-by: Felix Hildén <felix.hilden@gmail.com>
---
 CHANGES.md                                    |  3 ++
 src/black/linegen.py                          | 22 +++++++++
 src/black/nodes.py                            |  7 +--
 .../attribute_access_on_number_literals.py    | 47 +++++++++++++++++++
 tests/data/expression.diff                    |  9 ++--
 tests/data/expression.py                      |  4 +-
 .../expression_skip_magic_trailing_comma.diff |  9 ++--
 tests/test_format.py                          |  1 +
 8 files changed, 88 insertions(+), 14 deletions(-)
 create mode 100644 tests/data/attribute_access_on_number_literals.py

diff --git a/CHANGES.md b/CHANGES.md
index 0dc4952f069..6966a91aa11 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -42,6 +42,9 @@
 - Make passing `SRC` or `--code` mandatory and mutually exclusive (#2804)
 - Work around bug that causes unstable formatting in some cases in the presence of the
   magic trailing comma (#2807)
+- Use parentheses for attribute access on decimal float and int literals (#2799)
+- Don't add whitespace for attribute access on hexadecimal, binary, octal, and complex
+  literals (#2799)
 - Deprecate the `black-primer` tool (#2809)
 
 ### Packaging
diff --git a/src/black/linegen.py b/src/black/linegen.py
index ac60ed1986d..b572ed0b52f 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -197,6 +197,28 @@ def visit_decorators(self, node: Node) -> Iterator[Line]:
             yield from self.line()
             yield from self.visit(child)
 
+    def visit_power(self, node: Node) -> Iterator[Line]:
+        for idx, leaf in enumerate(node.children[:-1]):
+            next_leaf = node.children[idx + 1]
+
+            if not isinstance(leaf, Leaf):
+                continue
+
+            value = leaf.value.lower()
+            if (
+                leaf.type == token.NUMBER
+                and next_leaf.type == syms.trailer
+                # Ensure that we are in an attribute trailer
+                and next_leaf.children[0].type == token.DOT
+                # It shouldn't wrap hexadecimal, binary and octal literals
+                and not value.startswith(("0x", "0b", "0o"))
+                # It shouldn't wrap complex literals
+                and "j" not in value
+            ):
+                wrap_in_parentheses(node, leaf)
+
+        yield from self.visit_default(node)
+
     def visit_SEMI(self, leaf: Leaf) -> Iterator[Line]:
         """Remove a semicolon and put the other statement on a separate line."""
         yield from self.line()
diff --git a/src/black/nodes.py b/src/black/nodes.py
index 74dfa896295..51d4cb8618d 100644
--- a/src/black/nodes.py
+++ b/src/black/nodes.py
@@ -306,12 +306,7 @@ def whitespace(leaf: Leaf, *, complex_subscript: bool) -> str:  # noqa: C901
             return NO
 
         if not prev:
-            if t == token.DOT:
-                prevp = preceding_leaf(p)
-                if not prevp or prevp.type != token.NUMBER:
-                    return NO
-
-            elif t == token.LSQB:
+            if t == token.DOT or t == token.LSQB:
                 return NO
 
         elif prev.type != token.COMMA:
diff --git a/tests/data/attribute_access_on_number_literals.py b/tests/data/attribute_access_on_number_literals.py
new file mode 100644
index 00000000000..7c16bdfb3a5
--- /dev/null
+++ b/tests/data/attribute_access_on_number_literals.py
@@ -0,0 +1,47 @@
+x = 123456789 .bit_count()
+x = (123456).__abs__()
+x = .1.is_integer()
+x = 1. .imag
+x = 1E+1.imag
+x = 1E-1.real
+x = 123456789.123456789.hex()
+x = 123456789.123456789E123456789 .real
+x = 123456789E123456789 .conjugate()
+x = 123456789J.real
+x = 123456789.123456789J.__add__(0b1011.bit_length())
+x = 0XB1ACC.conjugate()
+x = 0B1011 .conjugate()
+x = 0O777 .real
+x = 0.000000006  .hex()
+x = -100.0000J
+
+if 10 .real:
+    ...
+
+y = 100[no]
+y = 100(no)
+
+# output
+
+x = (123456789).bit_count()
+x = (123456).__abs__()
+x = (0.1).is_integer()
+x = (1.0).imag
+x = (1e1).imag
+x = (1e-1).real
+x = (123456789.123456789).hex()
+x = (123456789.123456789e123456789).real
+x = (123456789e123456789).conjugate()
+x = 123456789j.real
+x = 123456789.123456789j.__add__(0b1011.bit_length())
+x = 0xB1ACC.conjugate()
+x = 0b1011.conjugate()
+x = 0o777.real
+x = (0.000000006).hex()
+x = -100.0000j
+
+if (10).real:
+    ...
+
+y = 100[no]
+y = 100(no)
diff --git a/tests/data/expression.diff b/tests/data/expression.diff
index 5f29a18dc7f..2eaaeb479f8 100644
--- a/tests/data/expression.diff
+++ b/tests/data/expression.diff
@@ -11,7 +11,7 @@
  True
  False
  1
-@@ -21,71 +21,104 @@
+@@ -21,99 +21,135 @@
  Name1 or (Name2 and Name3) or Name4
  Name1 or Name2 and Name3 or Name4
  v1 << 2
@@ -144,8 +144,11 @@
  call(**self.screen_kwargs)
  call(b, **self.screen_kwargs)
  lukasz.langa.pl
-@@ -94,26 +127,29 @@
- 1.0 .real
+ call.me(maybe)
+-1 .real
+-1.0 .real
++(1).real
++(1.0).real
  ....__class__
  list[str]
  dict[str, int]
diff --git a/tests/data/expression.py b/tests/data/expression.py
index b056841027d..06096c589f1 100644
--- a/tests/data/expression.py
+++ b/tests/data/expression.py
@@ -382,8 +382,8 @@ async def f():
 call(b, **self.screen_kwargs)
 lukasz.langa.pl
 call.me(maybe)
-1 .real
-1.0 .real
+(1).real
+(1.0).real
 ....__class__
 list[str]
 dict[str, int]
diff --git a/tests/data/expression_skip_magic_trailing_comma.diff b/tests/data/expression_skip_magic_trailing_comma.diff
index 5b722c91352..eba3fd2da7d 100644
--- a/tests/data/expression_skip_magic_trailing_comma.diff
+++ b/tests/data/expression_skip_magic_trailing_comma.diff
@@ -11,7 +11,7 @@
  True
  False
  1
-@@ -21,71 +21,92 @@
+@@ -21,99 +21,118 @@
  Name1 or (Name2 and Name3) or Name4
  Name1 or Name2 and Name3 or Name4
  v1 << 2
@@ -132,8 +132,11 @@
  call(**self.screen_kwargs)
  call(b, **self.screen_kwargs)
  lukasz.langa.pl
-@@ -94,26 +115,24 @@
- 1.0 .real
+ call.me(maybe)
+-1 .real
+-1.0 .real
++(1).real
++(1.0).real
  ....__class__
  list[str]
  dict[str, int]
diff --git a/tests/test_format.py b/tests/test_format.py
index 88f084ea478..aef22545f5b 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -15,6 +15,7 @@
 )
 
 SIMPLE_CASES: List[str] = [
+    "attribute_access_on_number_literals",
     "beginning_backslash",
     "bracketmatch",
     "class_blank_parentheses",

From fda2561f79e10826dbdeb900b6124d642766229f Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Fri, 28 Jan 2022 00:16:25 -0800
Subject: [PATCH 0445/1034] Tests for unicode identifiers (#2816)

---
 fuzz.py                              | 2 +-
 tests/data/tricky_unicode_symbols.py | 3 +++
 2 files changed, 4 insertions(+), 1 deletion(-)

diff --git a/fuzz.py b/fuzz.py
index 09a86a2f571..f5f655ea279 100644
--- a/fuzz.py
+++ b/fuzz.py
@@ -48,7 +48,7 @@ def test_idempotent_any_syntatically_valid_python(
         dst_contents = black.format_str(src_contents, mode=mode)
     except black.InvalidInput:
         # This is a bug - if it's valid Python code, as above, Black should be
-        # able to cope with it.  See issues #970, #1012, #1358, and #1557.
+        # able to cope with it.  See issues #970, #1012
         # TODO: remove this try-except block when issues are resolved.
         return
     except TokenError as e:
diff --git a/tests/data/tricky_unicode_symbols.py b/tests/data/tricky_unicode_symbols.py
index 366a92fa9d4..ad8b6108590 100644
--- a/tests/data/tricky_unicode_symbols.py
+++ b/tests/data/tricky_unicode_symbols.py
@@ -4,3 +4,6 @@
 x󠄀 = 4
 មុ = 1
 Q̇_per_meter = 4
+
+A᧚ = 3
+A፩ = 8

From 5f01b872e0553e17af1543ea27e500f79f716a29 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Fri, 28 Jan 2022 06:25:24 -0800
Subject: [PATCH 0446/1034] reorganize release notes for 22.1.0 (#2790)

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 CHANGES.md | 79 +++++++++++++++++++++++++++++++++---------------------
 1 file changed, 48 insertions(+), 31 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 6966a91aa11..f81c285d0be 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -2,50 +2,71 @@
 
 ## Unreleased
 
-### _Black_
+At long last, _Black_ is no longer a beta product! This is the first non-beta release
+and the first release covered by our new stability policy.
+
+### Highlights
 
 - **Remove Python 2 support** (#2740)
-- Do not accept bare carriage return line endings in pyproject.toml (#2408)
-- Improve error message for invalid regular expression (#2678)
-- Improve error message when parsing fails during AST safety check by embedding the
-  underlying SyntaxError (#2693)
+- Introduce the `--preview` flag (#2752)
+
+### Style
+
+- Deprecate `--experimental-string-processing` and move the functionality under
+  `--preview` (#2789)
+- For stubs, one blank line between class attributes and methods is now kept if there's
+  at least one pre-existing blank line (#2736)
+- Black now normalizes string prefix order (#2297)
+- Remove spaces around power operators if both operands are simple (#2726)
+- Work around bug that causes unstable formatting in some cases in the presence of the
+  magic trailing comma (#2807)
+- Use parentheses for attribute access on decimal float and int literals (#2799)
+- Don't add whitespace for attribute access on hexadecimal, binary, octal, and complex
+  literals (#2799)
+
+### Parser
+
 - Fix mapping cases that contain as-expressions, like `case {"key": 1 | 2 as password}`
   (#2686)
 - Fix cases that contain multiple top-level as-expressions, like `case 1 as a, 2 as b`
   (#2716)
 - Fix call patterns that contain as-expressions with keyword arguments, like
   `case Foo(bar=baz as quux)` (#2749)
-- No longer color diff headers white as it's unreadable in light themed terminals
-  (#2691)
 - Tuple unpacking on `return` and `yield` constructs now implies 3.8+ (#2700)
 - Unparenthesized tuples on annotated assignments (e.g
   `values: Tuple[int, ...] = 1, 2, 3`) now implies 3.8+ (#2708)
-- Remove spaces around power operators if both operands are simple (#2726)
-- Allow setting custom cache directory on all platforms with environment variable
-  `BLACK_CACHE_DIR` (#2739).
-- Text coloring added in the final statistics (#2712)
-- For stubs, one blank line between class attributes and methods is now kept if there's
-  at least one pre-existing blank line (#2736)
-- Verbose mode also now describes how a project root was discovered and which paths will
-  be formatted. (#2526)
-- Speed-up the new backtracking parser about 4X in general (enabled when
-  `--target-version` is set to 3.10 and higher). (#2728)
 - Fix handling of standalone `match()` or `case()` when there is a trailing newline or a
   comment inside of the parentheses. (#2760)
-- Black now normalizes string prefix order (#2297)
+
+### Performance
+
+- Speed-up the new backtracking parser about 4X in general (enabled when
+  `--target-version` is set to 3.10 and higher). (#2728)
+- _Black_ is now compiled with [mypyc](https://github.com/mypyc/mypyc) for an overall 2x
+  speed-up. 64-bit Windows, MacOS, and Linux (not including musl) are supported. (#1009,
+  #2431)
+
+### Configuration
+
+- Do not accept bare carriage return line endings in pyproject.toml (#2408)
 - Add configuration option (`python-cell-magics`) to format cells with custom magics in
   Jupyter Notebooks (#2744)
-- Deprecate `--experimental-string-processing` and move the functionality under
-  `--preview` (#2789)
+- Allow setting custom cache directory on all platforms with environment variable
+  `BLACK_CACHE_DIR` (#2739).
 - Enable Python 3.10+ by default, without any extra need to specify
   `--target-version=py310`. (#2758)
 - Make passing `SRC` or `--code` mandatory and mutually exclusive (#2804)
-- Work around bug that causes unstable formatting in some cases in the presence of the
-  magic trailing comma (#2807)
-- Use parentheses for attribute access on decimal float and int literals (#2799)
-- Don't add whitespace for attribute access on hexadecimal, binary, octal, and complex
-  literals (#2799)
-- Deprecate the `black-primer` tool (#2809)
+
+### Output
+
+- Improve error message for invalid regular expression (#2678)
+- Improve error message when parsing fails during AST safety check by embedding the
+  underlying SyntaxError (#2693)
+- No longer color diff headers white as it's unreadable in light themed terminals
+  (#2691)
+- Text coloring added in the final statistics (#2712)
+- Verbose mode also now describes how a project root was discovered and which paths will
+  be formatted. (#2526)
 
 ### Packaging
 
@@ -53,11 +74,6 @@
 - `typing-extensions` is no longer a required dependency in Python 3.10+ (#2772)
 - Set `click` lower bound to `8.0.0` (#2791)
 
-### Preview style
-
-- Introduce the `--preview` flag (#2752)
-- Add `--experimental-string-processing` to the preview style (#2789)
-
 ### Integrations
 
 - Update GitHub action to support containerized runs (#2748)
@@ -67,6 +83,7 @@
 - Change protocol in pip installation instructions to `https://` (#2761)
 - Change HTML theme to Furo primarily for its responsive design and mobile support
   (#2793)
+- Deprecate the `black-primer` tool (#2809)
 
 ## 21.12b0
 

From e1506769a428889bc66964edabf76476433c031a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Felix=20Hild=C3=A9n?= <felix.hilden@gmail.com>
Date: Fri, 28 Jan 2022 20:58:17 +0200
Subject: [PATCH 0447/1034] Elaborate on Python support policy (#2819)

---
 CHANGES.md  |  1 +
 docs/faq.md | 11 +++++++++--
 2 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index f81c285d0be..440aaeaa35a 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -84,6 +84,7 @@ and the first release covered by our new stability policy.
 - Change HTML theme to Furo primarily for its responsive design and mobile support
   (#2793)
 - Deprecate the `black-primer` tool (#2809)
+- Document Python support policy (#2819)
 
 ## 21.12b0
 
diff --git a/docs/faq.md b/docs/faq.md
index 0cff6ae5e1d..264141e3f39 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -71,9 +71,16 @@ readability because operators are misaligned. Disable W503 and enable the
 disabled-by-default counterpart W504. E203 should be disabled while changes are still
 [discussed](https://github.com/PyCQA/pycodestyle/issues/373).
 
-## Does Black support Python 2?
+## Which Python versions does Black support?
 
-Support for formatting Python 2 code was removed in version 22.0.
+Currently the runtime requires Python 3.6-3.10. Formatting is supported for files
+containing syntax from Python 3.3 to 3.10. 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.
 
 ## Why does my linter or typechecker complain after I format my code?
 

From 343795029f0d3ffa2f04ca5074a18861b2831d39 Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Fri, 28 Jan 2022 16:29:07 -0800
Subject: [PATCH 0448/1034] Treat blank lines in stubs the same inside
 top-level `if` statements (#2820)

---
 CHANGES.md          |  1 +
 src/black/lines.py  | 10 +++--
 tests/data/stub.pyi | 93 +++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 100 insertions(+), 4 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 440aaeaa35a..274c5640ec0 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -23,6 +23,7 @@ and the first release covered by our new stability policy.
 - Use parentheses for attribute access on decimal float and int literals (#2799)
 - Don't add whitespace for attribute access on hexadecimal, binary, octal, and complex
   literals (#2799)
+- Treat blank lines in stubs the same inside top-level `if` statements (#2820)
 
 ### Parser
 
diff --git a/src/black/lines.py b/src/black/lines.py
index 7d50f02aebc..1c4e38a96c1 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -530,11 +530,11 @@ def _maybe_empty_lines_for_class_or_def(
             return 0, 0
 
         if self.is_pyi:
-            if self.previous_line.depth > current_line.depth:
-                newlines = 0 if current_line.depth else 1
-            elif current_line.is_class or self.previous_line.is_class:
-                if current_line.depth:
+            if current_line.is_class or self.previous_line.is_class:
+                if self.previous_line.depth < current_line.depth:
                     newlines = 0
+                elif self.previous_line.depth > current_line.depth:
+                    newlines = 1
                 elif current_line.is_stub_class and self.previous_line.is_stub_class:
                     # No blank line between classes with an empty body
                     newlines = 0
@@ -551,6 +551,8 @@ def _maybe_empty_lines_for_class_or_def(
                     # Blank line between a block of functions (maybe with preceding
                     # decorators) and a block of non-functions
                     newlines = 1
+            elif self.previous_line.depth > current_line.depth:
+                newlines = 1
             else:
                 newlines = 0
         else:
diff --git a/tests/data/stub.pyi b/tests/data/stub.pyi
index 9a246211284..af2cd2c2c02 100644
--- a/tests/data/stub.pyi
+++ b/tests/data/stub.pyi
@@ -32,6 +32,48 @@ def g():
 
 def h(): ...
 
+if sys.version_info >= (3, 8):
+    class E:
+        def f(self): ...
+    class F:
+
+        def f(self): ...
+    class G: ...
+    class H: ...
+else:
+    class I: ...
+    class J: ...
+    def f(): ...
+
+    class K:
+        def f(self): ...
+    def f(): ...
+
+class Nested:
+    class dirty: ...
+    class little: ...
+    class secret:
+        def who_has_to_know(self): ...
+    def verse(self): ...
+
+class Conditional:
+    def f(self): ...
+    if sys.version_info >= (3, 8):
+        def g(self): ...
+    else:
+        def g(self): ...
+    def h(self): ...
+    def i(self): ...
+    if sys.version_info >= (3, 8):
+        def j(self): ...
+    def k(self): ...
+    if sys.version_info >= (3, 8):
+        class A: ...
+        class B: ...
+        class C:
+            def l(self): ...
+            def m(self): ...
+
 
 # output
 X: int
@@ -56,3 +98,54 @@ class A:
 
 def g(): ...
 def h(): ...
+
+if sys.version_info >= (3, 8):
+    class E:
+        def f(self): ...
+
+    class F:
+        def f(self): ...
+
+    class G: ...
+    class H: ...
+
+else:
+    class I: ...
+    class J: ...
+
+    def f(): ...
+
+    class K:
+        def f(self): ...
+
+    def f(): ...
+
+class Nested:
+    class dirty: ...
+    class little: ...
+
+    class secret:
+        def who_has_to_know(self): ...
+
+    def verse(self): ...
+
+class Conditional:
+    def f(self): ...
+    if sys.version_info >= (3, 8):
+        def g(self): ...
+    else:
+        def g(self): ...
+
+    def h(self): ...
+    def i(self): ...
+    if sys.version_info >= (3, 8):
+        def j(self): ...
+
+    def k(self): ...
+    if sys.version_info >= (3, 8):
+        class A: ...
+        class B: ...
+
+        class C:
+            def l(self): ...
+            def m(self): ...

From 4ce049dbfa8ddd00bff3656cbca6ecf5f85c413e Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Fri, 28 Jan 2022 16:48:38 -0800
Subject: [PATCH 0449/1034] torture test (#2815)

Fixes #2651. Fixes #2754. Fixes #2518. Fixes #2321.

This adds a test that lists a number of cases of unstable formatting
that we have seen in the issue tracker. Checking it in will ensure
that we don't regress on these cases.
---
 tests/data/torture.py | 81 +++++++++++++++++++++++++++++++++++++++++++
 tests/test_format.py  |  1 +
 2 files changed, 82 insertions(+)
 create mode 100644 tests/data/torture.py

diff --git a/tests/data/torture.py b/tests/data/torture.py
new file mode 100644
index 00000000000..79a44c2e34c
--- /dev/null
+++ b/tests/data/torture.py
@@ -0,0 +1,81 @@
+importA;() << 0 ** 101234234242352525425252352352525234890264906820496920680926538059059209922523523525 #
+
+assert sort_by_dependency(
+    {
+        "1": {"2", "3"}, "2": {"2a", "2b"}, "3": {"3a", "3b"},
+        "2a": set(), "2b": set(), "3a": set(), "3b": set()
+    }
+) == ["2a", "2b", "2", "3a", "3b", "3", "1"]
+
+importA
+0;0^0#
+
+class A:
+    def foo(self):
+        for _ in range(10):
+            aaaaaaaaaaaaaaaaaaa = bbbbbbbbbbbbbbb.cccccccccc(  # pylint: disable=no-member
+                xxxxxxxxxxxx
+            )
+
+def test(self, othr):
+    return (1 == 2 and
+            (name, description, self.default, self.selected, self.auto_generated, self.parameters, self.meta_data, self.schedule) ==
+            (name, description, othr.default, othr.selected, othr.auto_generated, othr.parameters, othr.meta_data, othr.schedule))
+
+# output
+
+importA
+(
+    ()
+    << 0
+    ** 101234234242352525425252352352525234890264906820496920680926538059059209922523523525
+)  #
+
+assert (
+    sort_by_dependency(
+        {
+            "1": {"2", "3"},
+            "2": {"2a", "2b"},
+            "3": {"3a", "3b"},
+            "2a": set(),
+            "2b": set(),
+            "3a": set(),
+            "3b": set(),
+        }
+    )
+    == ["2a", "2b", "2", "3a", "3b", "3", "1"]
+)
+
+importA
+0
+0 ^ 0  #
+
+
+class A:
+    def foo(self):
+        for _ in range(10):
+            aaaaaaaaaaaaaaaaaaa = bbbbbbbbbbbbbbb.cccccccccc(
+                xxxxxxxxxxxx
+            )  # pylint: disable=no-member
+
+
+def test(self, othr):
+    return 1 == 2 and (
+        name,
+        description,
+        self.default,
+        self.selected,
+        self.auto_generated,
+        self.parameters,
+        self.meta_data,
+        self.schedule,
+    ) == (
+        name,
+        description,
+        othr.default,
+        othr.selected,
+        othr.auto_generated,
+        othr.parameters,
+        othr.meta_data,
+        othr.schedule,
+    )
diff --git a/tests/test_format.py b/tests/test_format.py
index aef22545f5b..04676c1c2c5 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -53,6 +53,7 @@
     "remove_parens",
     "slices",
     "string_prefixes",
+    "torture",
     "trailing_comma_optional_parens1",
     "trailing_comma_optional_parens2",
     "trailing_comma_optional_parens3",

From df0aeeeee0378f2d2cdc33cbb38e17c3b8b53bde Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Felix=20Hild=C3=A9n?= <felix.hilden@gmail.com>
Date: Sat, 29 Jan 2022 02:49:43 +0200
Subject: [PATCH 0450/1034] Formalise style preference description (#2818)

Closes #1256: I reworded our style docs to be more explicit about the style we're aiming for and how it is changed (or isn't).
---
 docs/the_black_code_style/current_style.md | 15 +++++++++------
 docs/the_black_code_style/index.rst        |  4 ++++
 2 files changed, 13 insertions(+), 6 deletions(-)

diff --git a/docs/the_black_code_style/current_style.md b/docs/the_black_code_style/current_style.md
index 5be7ba6dbdb..0bf5894abdd 100644
--- a/docs/the_black_code_style/current_style.md
+++ b/docs/the_black_code_style/current_style.md
@@ -2,10 +2,14 @@
 
 ## Code style
 
-_Black_ reformats entire files in place. Style configuration options are deliberately
-limited and rarely added. It doesn't take previous formatting into account, except for
-the magic trailing comma and preserving newlines. It doesn't reformat blocks that start
-with `# fmt: off` and end with `# fmt: on`, or lines that ends with `# fmt: skip`.
+_Black_ aims for consistency, generality, readability and reducing git diffs. Similar
+language constructs are formatted with similar rules. Style configuration options are
+deliberately limited and rarely added. Previous formatting is taken into account as
+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 blocks that start with
+`# fmt: off` and end with `# fmt: on`, or lines that ends with `# fmt: skip`.
 `# fmt: on/off` have to be on the same level of indentation. It also recognizes
 [YAPF](https://github.com/google/yapf)'s block comments to the same effect, as a
 courtesy for straddling code.
@@ -18,8 +22,7 @@ running `black --preview`.
 
 _Black_ ignores previous formatting and applies uniform horizontal and vertical
 whitespace to your code. The rules for horizontal whitespace can be summarized as: do
-whatever makes `pycodestyle` happy. The coding style used by _Black_ can be viewed as a
-strict subset of PEP 8.
+whatever makes `pycodestyle` happy.
 
 As for vertical whitespace, _Black_ tries to render one full expression or simple
 statement per line. If this fits the allotted line length, great.
diff --git a/docs/the_black_code_style/index.rst b/docs/the_black_code_style/index.rst
index 3952a174223..511a6ecf099 100644
--- a/docs/the_black_code_style/index.rst
+++ b/docs/the_black_code_style/index.rst
@@ -12,6 +12,10 @@ The Black Code Style
 While keeping the style unchanged throughout releases has always been a goal,
 the *Black* code style isn't set in stone. It evolves to accommodate for new features
 in the Python language and, occasionally, in response to user feedback.
+Large-scale style preferences presented in :doc:`current_style` are very unlikely to
+change, but minor style aspects and details might change according to the stability
+policy presented below. Ongoing style considerations are tracked on GitHub with the
+`design <https://github.com/psf/black/labels/T%3A%20design>`_ issue label.
 
 Stability Policy
 ----------------

From 95e77cb5590a1499d3aa4cf7fe60481347191c35 Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Fri, 28 Jan 2022 16:57:05 -0800
Subject: [PATCH 0451/1034] Fix arithmetic stability issue (#2817)

It turns out "simple_stmt" isn't that simple: it can contain multiple
statements separated by semicolons. Invisible parenthesis logic for
arithmetic expressions only looked at the first child of simple_stmt.
This causes instability in the presence of semicolons, since the next
run through the statement following the semicolon will be the first
child of another simple_stmt.

I believe this along with #2572 fix the known stability issues.
---
 CHANGES.md           |  1 +
 src/black/linegen.py | 10 +++++++---
 src/black/nodes.py   |  7 +++----
 3 files changed, 11 insertions(+), 7 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 274c5640ec0..b57a360f1bc 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -24,6 +24,7 @@ and the first release covered by our new stability policy.
 - Don't add whitespace for attribute access on hexadecimal, binary, octal, and complex
   literals (#2799)
 - Treat blank lines in stubs the same inside top-level `if` statements (#2820)
+- Fix unstable formatting with semicolons and arithmetic expressions (#2817)
 
 ### Parser
 
diff --git a/src/black/linegen.py b/src/black/linegen.py
index b572ed0b52f..495d3230f8f 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -7,7 +7,7 @@
 
 from black.nodes import WHITESPACE, RARROW, STATEMENT, STANDALONE_COMMENT
 from black.nodes import ASSIGNMENTS, OPENING_BRACKETS, CLOSING_BRACKETS
-from black.nodes import Visitor, syms, first_child_is_arith, ensure_visible
+from black.nodes import Visitor, syms, is_arith_like, ensure_visible
 from black.nodes import is_docstring, is_empty_tuple, is_one_tuple, is_one_tuple_between
 from black.nodes import is_name_token, is_lpar_token, is_rpar_token
 from black.nodes import is_walrus_assignment, is_yield, is_vararg, is_multiline_string
@@ -156,8 +156,12 @@ def visit_suite(self, node: Node) -> Iterator[Line]:
 
     def visit_simple_stmt(self, node: Node) -> Iterator[Line]:
         """Visit a statement without nested statements."""
-        if first_child_is_arith(node):
-            wrap_in_parentheses(node, node.children[0], visible=False)
+        prev_type: Optional[int] = None
+        for child in node.children:
+            if (prev_type is None or prev_type == token.SEMI) and is_arith_like(child):
+                wrap_in_parentheses(node, child, visible=False)
+            prev_type = child.type
+
         is_suite_like = node.parent and node.parent.type in STATEMENT
         if is_suite_like:
             if self.mode.is_pyi and is_stub_body(node):
diff --git a/src/black/nodes.py b/src/black/nodes.py
index 51d4cb8618d..7466670be5a 100644
--- a/src/black/nodes.py
+++ b/src/black/nodes.py
@@ -531,15 +531,14 @@ def first_leaf_column(node: Node) -> Optional[int]:
     return None
 
 
-def first_child_is_arith(node: Node) -> bool:
-    """Whether first child is an arithmetic or a binary arithmetic expression"""
-    expr_types = {
+def is_arith_like(node: LN) -> bool:
+    """Whether node is an arithmetic or a binary arithmetic expression"""
+    return node.type in {
         syms.arith_expr,
         syms.shift_expr,
         syms.xor_expr,
         syms.and_expr,
     }
-    return bool(node.children and node.children[0].type in expr_types)
 
 
 def is_docstring(leaf: Leaf) -> bool:

From a24e1f795975350f7b1d8898d831916a9f6dbc6a Mon Sep 17 00:00:00 2001
From: Nipunn Koorapati <nipunn1313@gmail.com>
Date: Fri, 28 Jan 2022 18:13:18 -0800
Subject: [PATCH 0452/1034] Fix instability due to trailing comma logic (#2572)

It was causing stability issues because the first pass
could cause a "magic trailing comma" to appear, meaning
that the second pass might get a different result. It's
not critical.

Some things format differently (with extra parens)
---
 CHANGES.md                                    |  1 +
 src/black/__init__.py                         |  6 +--
 src/black/linegen.py                          |  2 +-
 src/black/lines.py                            | 14 +----
 src/black/nodes.py                            | 23 --------
 tests/data/function_trailing_comma.py         | 23 ++++----
 tests/data/long_strings_flag_disabled.py      | 13 +++--
 tests/data/torture.py                         | 25 ++++-----
 tests/data/trailing_comma_optional_parens1.py | 54 ++++++++++---------
 tests/data/trailing_comma_optional_parens2.py | 15 ++----
 tests/data/trailing_comma_optional_parens3.py |  5 +-
 11 files changed, 72 insertions(+), 109 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index b57a360f1bc..6775cee14e8 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -139,6 +139,7 @@ and the first release covered by our new stability policy.
   when `--target-version py310` is explicitly specified (#2586)
 - Add support for parenthesized with (#2586)
 - Declare support for Python 3.10 for running Black (#2562)
+- Fix unstable black runs around magic trailing comma (#2572)
 
 ### Integrations
 
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 769e693ed23..6192f5c0f8e 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -1332,7 +1332,7 @@ def get_imports_from_children(children: List[LN]) -> Generator[str, None, None]:
     return imports
 
 
-def assert_equivalent(src: str, dst: str, *, pass_num: int = 1) -> None:
+def assert_equivalent(src: str, dst: str) -> None:
     """Raise AssertionError if `src` and `dst` aren't equivalent."""
     try:
         src_ast = parse_ast(src)
@@ -1349,7 +1349,7 @@ def assert_equivalent(src: str, dst: str, *, pass_num: int = 1) -> None:
     except Exception as exc:
         log = dump_to_file("".join(traceback.format_tb(exc.__traceback__)), dst)
         raise AssertionError(
-            f"INTERNAL ERROR: Black produced invalid code on pass {pass_num}: {exc}. "
+            f"INTERNAL ERROR: Black produced invalid code: {exc}. "
             "Please report a bug on https://github.com/psf/black/issues.  "
             f"This invalid output might be helpful: {log}"
         ) from None
@@ -1360,7 +1360,7 @@ def assert_equivalent(src: str, dst: str, *, pass_num: int = 1) -> None:
         log = dump_to_file(diff(src_ast_str, dst_ast_str, "src", "dst"))
         raise AssertionError(
             "INTERNAL ERROR: Black produced code that is not equivalent to the"
-            f" source on pass {pass_num}.  Please report a bug on "
+            f" source.  Please report a bug on "
             f"https://github.com/psf/black/issues.  This diff might be helpful: {log}"
         ) from None
 
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 495d3230f8f..4dc242a1dfe 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -543,7 +543,7 @@ def right_hand_split(
         # there are no standalone comments in the body
         and not body.contains_standalone_comments(0)
         # and we can actually remove the parens
-        and can_omit_invisible_parens(body, line_length, omit_on_explode=omit)
+        and can_omit_invisible_parens(body, line_length)
     ):
         omit = {id(closing_bracket), *omit}
         try:
diff --git a/src/black/lines.py b/src/black/lines.py
index 1c4e38a96c1..f35665c8e0c 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -3,7 +3,6 @@
 import sys
 from typing import (
     Callable,
-    Collection,
     Dict,
     Iterator,
     List,
@@ -22,7 +21,7 @@
 from black.nodes import STANDALONE_COMMENT, TEST_DESCENDANTS
 from black.nodes import BRACKETS, OPENING_BRACKETS, CLOSING_BRACKETS
 from black.nodes import syms, whitespace, replace_child, child_towards
-from black.nodes import is_multiline_string, is_import, is_type_comment, last_two_except
+from black.nodes import is_multiline_string, is_import, is_type_comment
 from black.nodes import is_one_tuple_between
 
 # types
@@ -645,7 +644,6 @@ def can_be_split(line: Line) -> bool:
 def can_omit_invisible_parens(
     line: Line,
     line_length: int,
-    omit_on_explode: Collection[LeafID] = (),
 ) -> bool:
     """Does `line` have a shape safe to reformat without optional parens around it?
 
@@ -683,12 +681,6 @@ def can_omit_invisible_parens(
 
     penultimate = line.leaves[-2]
     last = line.leaves[-1]
-    if line.magic_trailing_comma:
-        try:
-            penultimate, last = last_two_except(line.leaves, omit=omit_on_explode)
-        except LookupError:
-            # Turns out we'd omit everything.  We cannot skip the optional parentheses.
-            return False
 
     if (
         last.type == token.RPAR
@@ -710,10 +702,6 @@ def can_omit_invisible_parens(
             # unnecessary.
             return True
 
-        if line.magic_trailing_comma and penultimate.type == token.COMMA:
-            # The rightmost non-omitted bracket pair is the one we want to explode on.
-            return True
-
         if _can_omit_closing_paren(line, last=last, line_length=line_length):
             return True
 
diff --git a/src/black/nodes.py b/src/black/nodes.py
index 7466670be5a..f130bff990e 100644
--- a/src/black/nodes.py
+++ b/src/black/nodes.py
@@ -4,13 +4,11 @@
 
 import sys
 from typing import (
-    Collection,
     Generic,
     Iterator,
     List,
     Optional,
     Set,
-    Tuple,
     TypeVar,
     Union,
 )
@@ -439,27 +437,6 @@ def prev_siblings_are(node: Optional[LN], tokens: List[Optional[NodeType]]) -> b
     return prev_siblings_are(node.prev_sibling, tokens[:-1])
 
 
-def last_two_except(leaves: List[Leaf], omit: Collection[LeafID]) -> Tuple[Leaf, Leaf]:
-    """Return (penultimate, last) leaves skipping brackets in `omit` and contents."""
-    stop_after: Optional[Leaf] = None
-    last: Optional[Leaf] = None
-    for leaf in reversed(leaves):
-        if stop_after:
-            if leaf is stop_after:
-                stop_after = None
-            continue
-
-        if last:
-            return leaf, last
-
-        if id(leaf) in omit:
-            stop_after = leaf.opening_bracket
-        else:
-            last = leaf
-    else:
-        raise LookupError("Last two leaves were also skipped")
-
-
 def parent_type(node: Optional[LN]) -> Optional[NodeType]:
     """
     Returns:
diff --git a/tests/data/function_trailing_comma.py b/tests/data/function_trailing_comma.py
index 02078219e82..429eb0e330f 100644
--- a/tests/data/function_trailing_comma.py
+++ b/tests/data/function_trailing_comma.py
@@ -89,16 +89,19 @@ def f(
         "a": 1,
         "b": 2,
     }["a"]
-    if a == {
-        "a": 1,
-        "b": 2,
-        "c": 3,
-        "d": 4,
-        "e": 5,
-        "f": 6,
-        "g": 7,
-        "h": 8,
-    }["a"]:
+    if (
+        a
+        == {
+            "a": 1,
+            "b": 2,
+            "c": 3,
+            "d": 4,
+            "e": 5,
+            "f": 6,
+            "g": 7,
+            "h": 8,
+        }["a"]
+    ):
         pass
 
 
diff --git a/tests/data/long_strings_flag_disabled.py b/tests/data/long_strings_flag_disabled.py
index ef3094fd779..db3954e3abd 100644
--- a/tests/data/long_strings_flag_disabled.py
+++ b/tests/data/long_strings_flag_disabled.py
@@ -133,11 +133,14 @@
     "Use f-strings instead!",
 )
 
-old_fmt_string3 = "Whereas only the strings after the percent sign were long in the last example, this example uses a long initial string as well. This is another %s %s %s %s" % (
-    "really really really really really",
-    "old",
-    "way to format strings!",
-    "Use f-strings instead!",
+old_fmt_string3 = (
+    "Whereas only the strings after the percent sign were long in the last example, this example uses a long initial string as well. This is another %s %s %s %s"
+    % (
+        "really really really really really",
+        "old",
+        "way to format strings!",
+        "Use f-strings instead!",
+    )
 )
 
 fstring = f"f-strings definitely make things more {difficult} than they need to be for {{black}}. But boy they sure are handy. The problem is that some lines will need to have the 'f' whereas others do not. This {line}, for example, needs one."
diff --git a/tests/data/torture.py b/tests/data/torture.py
index 79a44c2e34c..7cabd4c163f 100644
--- a/tests/data/torture.py
+++ b/tests/data/torture.py
@@ -31,20 +31,17 @@ def test(self, othr):
     ** 101234234242352525425252352352525234890264906820496920680926538059059209922523523525
 )  #
 
-assert (
-    sort_by_dependency(
-        {
-            "1": {"2", "3"},
-            "2": {"2a", "2b"},
-            "3": {"3a", "3b"},
-            "2a": set(),
-            "2b": set(),
-            "3a": set(),
-            "3b": set(),
-        }
-    )
-    == ["2a", "2b", "2", "3a", "3b", "3", "1"]
-)
+assert sort_by_dependency(
+    {
+        "1": {"2", "3"},
+        "2": {"2a", "2b"},
+        "3": {"3a", "3b"},
+        "2a": set(),
+        "2b": set(),
+        "3a": set(),
+        "3b": set(),
+    }
+) == ["2a", "2b", "2", "3a", "3b", "3", "1"]
 
 importA
 0
diff --git a/tests/data/trailing_comma_optional_parens1.py b/tests/data/trailing_comma_optional_parens1.py
index f9f4ae5e023..85aa8badb26 100644
--- a/tests/data/trailing_comma_optional_parens1.py
+++ b/tests/data/trailing_comma_optional_parens1.py
@@ -2,6 +2,10 @@
                         _winapi.ERROR_PIPE_BUSY) or _check_timeout(t):
     pass
 
+if x:
+    if y:
+        new_id = max(Vegetable.objects.order_by('-id')[0].id,
+                     Mineral.objects.order_by('-id')[0].id) + 1
 
 class X:
     def get_help_text(self):
@@ -23,39 +27,37 @@ def b(self):
 
 # output
 
-if (
-    e1234123412341234.winerror
-    not in (
-        _winapi.ERROR_SEM_TIMEOUT,
-        _winapi.ERROR_PIPE_BUSY,
-    )
-    or _check_timeout(t)
-):
+if e1234123412341234.winerror not in (
+    _winapi.ERROR_SEM_TIMEOUT,
+    _winapi.ERROR_PIPE_BUSY,
+) or _check_timeout(t):
     pass
 
+if x:
+    if y:
+        new_id = (
+            max(
+                Vegetable.objects.order_by("-id")[0].id,
+                Mineral.objects.order_by("-id")[0].id,
+            )
+            + 1
+        )
+
 
 class X:
     def get_help_text(self):
-        return (
-            ngettext(
-                "Your password must contain at least %(min_length)d character.",
-                "Your password must contain at least %(min_length)d characters.",
-                self.min_length,
-            )
-            % {"min_length": self.min_length}
-        )
+        return ngettext(
+            "Your password must contain at least %(min_length)d character.",
+            "Your password must contain at least %(min_length)d characters.",
+            self.min_length,
+        ) % {"min_length": self.min_length}
 
 
 class A:
     def b(self):
-        if (
-            self.connection.mysql_is_mariadb
-            and (
-                10,
-                4,
-                3,
-            )
-            < self.connection.mysql_version
-            < (10, 5, 2)
-        ):
+        if self.connection.mysql_is_mariadb and (
+            10,
+            4,
+            3,
+        ) < self.connection.mysql_version < (10, 5, 2):
             pass
diff --git a/tests/data/trailing_comma_optional_parens2.py b/tests/data/trailing_comma_optional_parens2.py
index 1dfb54ca687..9541670e394 100644
--- a/tests/data/trailing_comma_optional_parens2.py
+++ b/tests/data/trailing_comma_optional_parens2.py
@@ -4,14 +4,9 @@
 
 # output
 
-if (
-    e123456.get_tk_patchlevel() >= (8, 6, 0, "final")
-    or (
-        8,
-        5,
-        8,
-    )
-    <= get_tk_patchlevel()
-    < (8, 6)
-):
+if e123456.get_tk_patchlevel() >= (8, 6, 0, "final") or (
+    8,
+    5,
+    8,
+) <= get_tk_patchlevel() < (8, 6):
     pass
diff --git a/tests/data/trailing_comma_optional_parens3.py b/tests/data/trailing_comma_optional_parens3.py
index bccf47430a7..c0ed699e6a6 100644
--- a/tests/data/trailing_comma_optional_parens3.py
+++ b/tests/data/trailing_comma_optional_parens3.py
@@ -18,7 +18,4 @@
                 "qweasdzxcqweasdzxcqweasdzxcqweasdzxcqweasdzxcqweasdzxcqweasdzxcqweasdzxcqweasdzxcqweas "
                 + "qweasdzxcqweasdzxcqweasdzxcqweasdzxcqweasdzxcqweasdzxcqweasdzxcqweasdzxcqwegqweasdzxcqweasdzxc.",
                 "qweasdzxcqweasdzxcqweasdzxcqweasdzxcqweasdzxcqweasdzxcqweasdzxcqweasdzxcqweasdzxcqwe",
-            ) % {
-                "reported_username": reported_username,
-                "report_reason": report_reason,
-            }
\ No newline at end of file
+            ) % {"reported_username": reported_username, "report_reason": report_reason}

From a4992b4d50d6efa41b49ed0f804c5ed3723399db Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Fri, 28 Jan 2022 19:38:50 -0800
Subject: [PATCH 0453/1034] Add a test case to torture.py (#2822)

Co-authored-by: hauntsaninja <>
---
 tests/data/torture.py | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/tests/data/torture.py b/tests/data/torture.py
index 7cabd4c163f..2a194759a82 100644
--- a/tests/data/torture.py
+++ b/tests/data/torture.py
@@ -22,6 +22,12 @@ def test(self, othr):
             (name, description, self.default, self.selected, self.auto_generated, self.parameters, self.meta_data, self.schedule) ==
             (name, description, othr.default, othr.selected, othr.auto_generated, othr.parameters, othr.meta_data, othr.schedule))
 
+
+assert (
+    a_function(very_long_arguments_that_surpass_the_limit, which_is_eighty_eight_in_this_case_plus_a_bit_more)
+    == {"x": "this need to pass the line limit as well", "b": "but only by a little bit"}
+)
+
 # output
 
 importA
@@ -76,3 +82,10 @@ def test(self, othr):
         othr.meta_data,
         othr.schedule,
     )
+
+
+assert a_function(
+    very_long_arguments_that_surpass_the_limit,
+    which_is_eighty_eight_in_this_case_plus_a_bit_more,
+) == {"x": "this need to pass the line limit as well", "b": "but only by a little bit"}
+

From 8acb8548c36882a124127d25287f4f38de3c2ff8 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Sat, 29 Jan 2022 10:37:51 -0500
Subject: [PATCH 0454/1034] Update classifiers to reflect stable (#2823)

---
 setup.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/setup.py b/setup.py
index c5917998da4..8f904d2cc99 100644
--- a/setup.py
+++ b/setup.py
@@ -114,7 +114,7 @@ def find_python_files(base: Path) -> List[Path]:
     },
     test_suite="tests.test_black",
     classifiers=[
-        "Development Status :: 4 - Beta",
+        "Development Status :: 5 - Production/Stable",
         "Environment :: Console",
         "Intended Audience :: Developers",
         "License :: OSI Approved :: MIT License",

From 0d768e58f42d9aec20637d21ad261f7f9eaacae8 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Sat, 29 Jan 2022 08:00:59 -0800
Subject: [PATCH 0455/1034] Remove test suite from setup.py (#2824)

We no longer use it
---
 setup.py | 1 -
 1 file changed, 1 deletion(-)

diff --git a/setup.py b/setup.py
index 8f904d2cc99..466f1a9c3a6 100644
--- a/setup.py
+++ b/setup.py
@@ -112,7 +112,6 @@ def find_python_files(base: Path) -> List[Path]:
         "uvloop": ["uvloop>=0.15.2"],
         "jupyter": ["ipython>=7.8.0", "tokenize-rt>=3.2.0"],
     },
-    test_suite="tests.test_black",
     classifiers=[
         "Development Status :: 5 - Production/Stable",
         "Environment :: Console",

From c5f8e8bd5904ed21742b28afd7b1d84782a6a6e9 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Sat, 29 Jan 2022 09:32:26 -0800
Subject: [PATCH 0456/1034] Fix changelog entries in the wrong release (#2825)

---
 CHANGES.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 6775cee14e8..5e02027841b 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -25,6 +25,7 @@ and the first release covered by our new stability policy.
   literals (#2799)
 - Treat blank lines in stubs the same inside top-level `if` statements (#2820)
 - Fix unstable formatting with semicolons and arithmetic expressions (#2817)
+- Fix unstable formatting around magic trailing comma (#2572)
 
 ### Parser
 
@@ -39,6 +40,7 @@ and the first release covered by our new stability policy.
   `values: Tuple[int, ...] = 1, 2, 3`) now implies 3.8+ (#2708)
 - Fix handling of standalone `match()` or `case()` when there is a trailing newline or a
   comment inside of the parentheses. (#2760)
+- `from __future__ import annotations` statement now implies Python 3.7+ (#2690)
 
 ### Performance
 
@@ -95,7 +97,6 @@ and the first release covered by our new stability policy.
 - Fix determination of f-string expression spans (#2654)
 - Fix bad formatting of error messages about EOF in multi-line statements (#2343)
 - Functions and classes in blocks now have more consistent surrounding spacing (#2472)
-- `from __future__ import annotations` statement now implies Python 3.7+ (#2690)
 
 #### Jupyter Notebook support
 
@@ -139,7 +140,6 @@ and the first release covered by our new stability policy.
   when `--target-version py310` is explicitly specified (#2586)
 - Add support for parenthesized with (#2586)
 - Declare support for Python 3.10 for running Black (#2562)
-- Fix unstable black runs around magic trailing comma (#2572)
 
 ### Integrations
 

From dea2f94ebd33081bdf8fa75611424890fcb3cace Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Sat, 29 Jan 2022 09:32:52 -0800
Subject: [PATCH 0457/1034] Fix changelog entries in the wrong release (#2825)


From d038a24ca200da9dacc1dcb05090c9e5b45b7869 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Sat, 29 Jan 2022 14:30:25 -0500
Subject: [PATCH 0458/1034] Prepare docs for release 22.1.0 (GH-2826)

---
 CHANGES.md                                  | 2 +-
 docs/integrations/source_version_control.md | 2 +-
 docs/usage_and_configuration/the_basics.md  | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 5e02027841b..9c92f8f9b58 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,6 +1,6 @@
 # Change Log
 
-## Unreleased
+## 22.1.0
 
 At long last, _Black_ is no longer a beta product! This is the first non-beta release
 and the first release covered by our new stability policy.
diff --git a/docs/integrations/source_version_control.md b/docs/integrations/source_version_control.md
index 9c53f30687d..7215e111f5c 100644
--- a/docs/integrations/source_version_control.md
+++ b/docs/integrations/source_version_control.md
@@ -7,7 +7,7 @@ Use [pre-commit](https://pre-commit.com/). Once you
 ```yaml
 repos:
   - repo: https://github.com/psf/black
-    rev: 21.12b0
+    rev: 22.1.0
     hooks:
       - id: black
         # It is recommended to specify the latest version of Python
diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index b82cef4a52d..48dda3ba036 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -173,7 +173,7 @@ You can check the version of _Black_ you have installed using the `--version` fl
 
 ```console
 $ black --version
-black, version 21.12b0
+black, version 22.1.0
 ```
 
 An option to require a specific version to be running is also provided.

From bbe1bdf1edfedf51b40824c5574413c0b1b35284 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Sun, 30 Jan 2022 11:53:45 -0800
Subject: [PATCH 0459/1034] Adjust `--preview` documentation (#2833)

---
 src/black/__init__.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index 6192f5c0f8e..6a703e45046 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -258,7 +258,7 @@ def validate_regex(
     "--preview",
     is_flag=True,
     help=(
-        "Enable potentially disruptive style changes that will be added to Black's main"
+        "Enable potentially disruptive style changes that may be added to Black's main"
         " functionality in the next major release."
     ),
 )

From f61299a62a330dd26d180a8ea420916870f19730 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Sun, 30 Jan 2022 12:01:56 -0800
Subject: [PATCH 0460/1034] Exclude __pypackages__ by default (GH-2836)

PDM uses this as part of not-accepted-yet PEP 582.
---
 CHANGES.md         | 6 ++++++
 src/black/const.py | 2 +-
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index 9c92f8f9b58..a840e013041 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,5 +1,11 @@
 # Change Log
 
+## Unreleased
+
+### Configuration
+
+- Do not format `__pypackages__` directories by default (#2836)
+
 ## 22.1.0
 
 At long last, _Black_ is no longer a beta product! This is the first non-beta release
diff --git a/src/black/const.py b/src/black/const.py
index dbb4826be0e..03afc96e8d6 100644
--- a/src/black/const.py
+++ b/src/black/const.py
@@ -1,4 +1,4 @@
 DEFAULT_LINE_LENGTH = 88
-DEFAULT_EXCLUDES = r"/(\.direnv|\.eggs|\.git|\.hg|\.mypy_cache|\.nox|\.tox|\.venv|venv|\.svn|_build|buck-out|build|dist)/"  # noqa: B950
+DEFAULT_EXCLUDES = r"/(\.direnv|\.eggs|\.git|\.hg|\.mypy_cache|\.nox|\.tox|\.venv|venv|\.svn|_build|buck-out|build|dist|__pypackages__)/"  # noqa: B950
 DEFAULT_INCLUDES = r"(\.pyi?|\.ipynb)$"
 STDIN_PLACEHOLDER = "__BLACK_STDIN_FILENAME__"

From cae7ae3a4d32dc51e0752d4a4e885a7792a0286d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fr=C3=A9d=C3=A9rik=20Paradis?=
 <frederik.paradis.1@ulaval.ca>
Date: Sun, 30 Jan 2022 16:42:56 -0500
Subject: [PATCH 0461/1034] Soft comparison of --required-version (#2832)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Co-authored-by: Felix Hildén <felix.hilden@gmail.com>
---
 CHANGES.md            |  1 +
 src/black/__init__.py |  9 +++++++--
 tests/test_black.py   | 14 ++++++++++++++
 3 files changed, 22 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index a840e013041..7d74e56ce4e 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -5,6 +5,7 @@
 ### Configuration
 
 - Do not format `__pypackages__` directories by default (#2836)
+- Add support for specifying stable version with `--required-version` (#2832).
 
 ## 22.1.0
 
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 6a703e45046..8c28b6ba18b 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -291,7 +291,8 @@ def validate_regex(
     type=str,
     help=(
         "Require a specific version of Black to be running (useful for unifying results"
-        " across many environments e.g. with a pyproject.toml file)."
+        " across many environments e.g. with a pyproject.toml file). It can be"
+        " either a major version number or an exact version."
     ),
 )
 @click.option(
@@ -474,7 +475,11 @@ def main(
                 out(f"Using configuration in '{config}'.", fg="blue")
 
     error_msg = "Oh no! 💥 💔 💥"
-    if required_version and required_version != __version__:
+    if (
+        required_version
+        and required_version != __version__
+        and required_version != __version__.split(".")[0]
+    ):
         err(
             f"{error_msg} The required version `{required_version}` does not match"
             f" the running version `{__version__}`!"
diff --git a/tests/test_black.py b/tests/test_black.py
index 2dd284f2cd6..b04c0a66fe9 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -1198,6 +1198,20 @@ def test_required_version_matches_version(self) -> None:
             ignore_config=True,
         )
 
+    def test_required_version_matches_partial_version(self) -> None:
+        self.invokeBlack(
+            ["--required-version", black.__version__.split(".")[0], "-c", "0"],
+            exit_code=0,
+            ignore_config=True,
+        )
+
+    def test_required_version_does_not_match_on_minor_version(self) -> None:
+        self.invokeBlack(
+            ["--required-version", black.__version__.split(".")[0] + ".999", "-c", "0"],
+            exit_code=1,
+            ignore_config=True,
+        )
+
     def test_required_version_does_not_match_version(self) -> None:
         result = BlackRunner().invoke(
             black.main,

From afc0fb05cbb1f7ea2700a7e5d240079df00f6d07 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Sun, 30 Jan 2022 14:04:06 -0800
Subject: [PATCH 0462/1034] release process: formalize the changelog template
 (#2837)

I did this manually for the last few releases and I think it's going to be
helpful in the future too. Unfortunately this adds a little more work during
the release (sorry @cooperlees).

This change will also improve the merge conflict situation a bit, because
changes to different sections won't merge conflict.

For the last release, the sections were in a kind of random order. In the
template I put highlights and "Style" first because they're most important
to users, and alphabetized the rest.
---
 CHANGES.md                           | 39 +++++++++++++++++++
 docs/contributing/release_process.md | 56 +++++++++++++++++++++++++++-
 2 files changed, 93 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 7d74e56ce4e..ba693241c19 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -2,11 +2,50 @@
 
 ## Unreleased
 
+### Highlights
+
+<!-- Include any especially major or disruptive changes here -->
+
+### Style
+
+<!-- Changes that affect Black's style -->
+
+### _Blackd_
+
+<!-- Changes to blackd -->
+
 ### Configuration
 
+<!-- Changes to how Black can be configured -->
+
 - Do not format `__pypackages__` directories by default (#2836)
 - Add support for specifying stable version with `--required-version` (#2832).
 
+### Documentation
+
+<!-- Major changes to documentation and policies. Small docs changes
+     don't need a changelog entry. -->
+
+### Integrations
+
+<!-- For example, Docker, GitHub Actions, pre-commit, editors -->
+
+### Output
+
+<!-- Changes to Black's terminal output and error messages -->
+
+### Packaging
+
+<!-- Changes to how Black is packaged, such as dependency requirements -->
+
+### Parser
+
+<!-- Changes to the parser or to version autodetection -->
+
+### Performance
+
+<!-- Changes that improve Black's performance. -->
+
 ## 22.1.0
 
 At long last, _Black_ is no longer a beta product! This is the first non-beta release
diff --git a/docs/contributing/release_process.md b/docs/contributing/release_process.md
index 9ee7dbc607c..89beb099e66 100644
--- a/docs/contributing/release_process.md
+++ b/docs/contributing/release_process.md
@@ -9,8 +9,10 @@ To cut a release, you must be a _Black_ maintainer with `GitHub Release` creatio
 access. Using this access, the release process is:
 
 1. Cut a new PR editing `CHANGES.md` and the docs to version the latest changes
-   1. Example PR: [#2616](https://github.com/psf/black/pull/2616)
-   2. Example title: `Update CHANGES.md for XX.X release`
+   1. Remove any empty sections for the current release
+   2. Add a new empty template for the next release (template below)
+   3. Example PR: [#2616](https://github.com/psf/black/pull/2616)
+   4. Example title: `Update CHANGES.md for XX.X release`
 2. Once the release PR is merged ensure all CI passes
    1. If not, ensure there is an Issue open for the cause of failing CI (generally we'd
       want this fixed before cutting a release)
@@ -32,6 +34,56 @@ access. Using this access, the release process is:
 If anything fails, please go read the respective action's log output and configuration
 file to reverse engineer your way to a fix/soluton.
 
+## Changelog template
+
+Use the following template for a clean changelog after the release:
+
+```
+## Unreleased
+
+### Highlights
+
+<!-- Include any especially major or disruptive changes here -->
+
+### Style
+
+<!-- Changes that affect Black's style -->
+
+### _Blackd_
+
+<!-- Changes to blackd -->
+
+### Configuration
+
+<!-- Changes to how Black can be configured -->
+
+### Documentation
+
+<!-- Major changes to documentation and policies. Small docs changes
+     don't need a changelog entry. -->
+
+### Integrations
+
+<!-- For example, Docker, GitHub Actions, pre-commit, editors -->
+
+### Output
+
+<!-- Changes to Black's terminal output and error messages -->
+
+### Packaging
+
+<!-- Changes to how Black is packaged, such as dependency requirements -->
+
+### Parser
+
+<!-- Changes to the parser or to version autodetection -->
+
+### Performance
+
+<!-- Changes that improve Black's performance. -->
+
+```
+
 ## Release workflows
 
 All _Blacks_'s automation workflows use GitHub Actions. All workflows are therefore

From f3f3acc4440543cd7b8bf7cb4d4cea7300a251ef Mon Sep 17 00:00:00 2001
From: "S. Co1" <sco1.git@gmail.com>
Date: Mon, 31 Jan 2022 19:06:52 -0500
Subject: [PATCH 0463/1034] Surface links to Stability Policy (GH-2848)

---
 CHANGES.md | 3 ++-
 README.md  | 4 ++++
 2 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index ba693241c19..4ad9e532808 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -49,7 +49,8 @@
 ## 22.1.0
 
 At long last, _Black_ is no longer a beta product! This is the first non-beta release
-and the first release covered by our new stability policy.
+and the first release covered by our new
+[stability policy](https://black.readthedocs.io/en/stable/the_black_code_style/index.html#stability-policy).
 
 ### Highlights
 
diff --git a/README.md b/README.md
index a00495c8858..eda07b18a68 100644
--- a/README.md
+++ b/README.md
@@ -89,6 +89,10 @@ also documented. They're both worth taking a look:
 - [The _Black_ Code Style: Current style](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html)
 - [The _Black_ Code Style: Future style](https://black.readthedocs.io/en/stable/the_black_code_style/future_style.html)
 
+Changes to the _Black_ code style are bound by the Stability Policy:
+
+- [The _Black_ Code Style: Stability Policy](https://black.readthedocs.io/en/stable/the_black_code_style/index.html#stability-policy)
+
 Please refer to this document before submitting an issue. What seems like a bug might be
 intended behaviour.
 

From fb9fe6b565ce8a9beeebb51c23f384d1865d0ee8 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Tue, 1 Feb 2022 00:29:01 -0500
Subject: [PATCH 0464/1034] Isolate command line tests from user-level config
 (#2851)

---
 tests/test_black.py | 25 +++++++++++++++----------
 1 file changed, 15 insertions(+), 10 deletions(-)

diff --git a/tests/test_black.py b/tests/test_black.py
index b04c0a66fe9..cd38d9e2c0d 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -63,6 +63,7 @@
 )
 
 THIS_FILE = Path(__file__)
+EMPTY_CONFIG = THIS_DIR / "data" / "empty_pyproject.toml"
 PY36_ARGS = [f"--target-version={version.name.lower()}" for version in PY36_VERSIONS]
 DEFAULT_EXCLUDE = black.re_compile_maybe_verbose(black.const.DEFAULT_EXCLUDES)
 DEFAULT_INCLUDE = black.re_compile_maybe_verbose(black.const.DEFAULT_INCLUDES)
@@ -159,7 +160,12 @@ def test_piping(self) -> None:
         source, expected = read_data("src/black/__init__", data=False)
         result = BlackRunner().invoke(
             black.main,
-            ["-", "--fast", f"--line-length={black.DEFAULT_LINE_LENGTH}"],
+            [
+                "-",
+                "--fast",
+                f"--line-length={black.DEFAULT_LINE_LENGTH}",
+                f"--config={EMPTY_CONFIG}",
+            ],
             input=BytesIO(source.encode("utf8")),
         )
         self.assertEqual(result.exit_code, 0)
@@ -175,13 +181,12 @@ def test_piping_diff(self) -> None:
         )
         source, _ = read_data("expression.py")
         expected, _ = read_data("expression.diff")
-        config = THIS_DIR / "data" / "empty_pyproject.toml"
         args = [
             "-",
             "--fast",
             f"--line-length={black.DEFAULT_LINE_LENGTH}",
             "--diff",
-            f"--config={config}",
+            f"--config={EMPTY_CONFIG}",
         ]
         result = BlackRunner().invoke(
             black.main, args, input=BytesIO(source.encode("utf8"))
@@ -193,14 +198,13 @@ def test_piping_diff(self) -> None:
 
     def test_piping_diff_with_color(self) -> None:
         source, _ = read_data("expression.py")
-        config = THIS_DIR / "data" / "empty_pyproject.toml"
         args = [
             "-",
             "--fast",
             f"--line-length={black.DEFAULT_LINE_LENGTH}",
             "--diff",
             "--color",
-            f"--config={config}",
+            f"--config={EMPTY_CONFIG}",
         ]
         result = BlackRunner().invoke(
             black.main, args, input=BytesIO(source.encode("utf8"))
@@ -252,7 +256,6 @@ def test_expression_ff(self) -> None:
 
     def test_expression_diff(self) -> None:
         source, _ = read_data("expression.py")
-        config = THIS_DIR / "data" / "empty_pyproject.toml"
         expected, _ = read_data("expression.diff")
         tmp_file = Path(black.dump_to_file(source))
         diff_header = re.compile(
@@ -261,7 +264,7 @@ def test_expression_diff(self) -> None:
         )
         try:
             result = BlackRunner().invoke(
-                black.main, ["--diff", str(tmp_file), f"--config={config}"]
+                black.main, ["--diff", str(tmp_file), f"--config={EMPTY_CONFIG}"]
             )
             self.assertEqual(result.exit_code, 0)
         finally:
@@ -279,12 +282,12 @@ def test_expression_diff(self) -> None:
 
     def test_expression_diff_with_color(self) -> None:
         source, _ = read_data("expression.py")
-        config = THIS_DIR / "data" / "empty_pyproject.toml"
         expected, _ = read_data("expression.diff")
         tmp_file = Path(black.dump_to_file(source))
         try:
             result = BlackRunner().invoke(
-                black.main, ["--diff", "--color", str(tmp_file), f"--config={config}"]
+                black.main,
+                ["--diff", "--color", str(tmp_file), f"--config={EMPTY_CONFIG}"],
             )
         finally:
             os.unlink(tmp_file)
@@ -325,7 +328,9 @@ def test_skip_magic_trailing_comma(self) -> None:
             r"\d\d:\d\d:\d\d\.\d\d\d\d\d\d \+\d\d\d\d"
         )
         try:
-            result = BlackRunner().invoke(black.main, ["-C", "--diff", str(tmp_file)])
+            result = BlackRunner().invoke(
+                black.main, ["-C", "--diff", str(tmp_file), f"--config={EMPTY_CONFIG}"]
+            )
             self.assertEqual(result.exit_code, 0)
         finally:
             os.unlink(tmp_file)

From 111880efc7938c618dd16c7cf8d872ca32c6a751 Mon Sep 17 00:00:00 2001
From: Peter Mescalchin <peter@magnetikonline.com>
Date: Wed, 2 Feb 2022 14:17:45 +1100
Subject: [PATCH 0465/1034] Update description for GitHub Action `options:`
 argument (GH-2858)

It was missing --diff as one of the default arguments passed.
---
 action.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/action.yml b/action.yml
index dd2de1b62ad..dbd8ef69ec2 100644
--- a/action.yml
+++ b/action.yml
@@ -5,7 +5,7 @@ inputs:
   options:
     description:
       "Options passed to Black. Use `black --help` to see available options. Default:
-      '--check'"
+      '--check --diff'"
     required: false
     default: "--check --diff"
   src:

From 31fe97e7ce1055debaa54bed9c63e252508a9a75 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Felix=20Hild=C3=A9n?= <felix.hilden@gmail.com>
Date: Wed, 2 Feb 2022 08:59:42 +0200
Subject: [PATCH 0466/1034] Create indentation FAQ entry (#2855)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 docs/faq.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/docs/faq.md b/docs/faq.md
index 264141e3f39..70f9b51394f 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -8,6 +8,18 @@ The most common questions and issues users face are aggregated to this FAQ.
 :class: this-will-duplicate-information-and-it-is-still-useful-here
 ```
 
+## Why spaces? I prefer tabs
+
+PEP 8 recommends spaces over tabs, and they are used by most of the Python community.
+_Black_ provides no options to configure the indentation style, and requests for such
+options will not be considered.
+
+However, we recognise that using tabs is an accessibility issue as well. While the
+option will never be added to _Black_, visually impaired developers may find conversion
+tools such as `expand/unexpand` (for Linux) useful when contributing to Python projects.
+A workflow might consist of e.g. setting up appropriate pre-commit and post-merge git
+hooks, and scripting `unexpand` to run after applying _Black_.
+
 ## Does Black have an API?
 
 Not yet. _Black_ is fundamentally a command line tool. Many

From 01001d5cff788c2aed17c5f0379d3ef37b95825d Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 7 Feb 2022 07:31:58 -0800
Subject: [PATCH 0467/1034] Bump sphinx-copybutton from 0.4.0 to 0.5.0 in /docs
 (#2871)

Bumps [sphinx-copybutton](https://github.com/executablebooks/sphinx-copybutton) from 0.4.0 to 0.5.0.
- [Release notes](https://github.com/executablebooks/sphinx-copybutton/releases)
- [Changelog](https://github.com/executablebooks/sphinx-copybutton/blob/master/CHANGELOG.md)
- [Commits](https://github.com/executablebooks/sphinx-copybutton/compare/v0.4.0...v0.5.0)

---
updated-dependencies:
- dependency-name: sphinx-copybutton
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 docs/requirements.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index 01fea693f07..0b685425dde 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -3,5 +3,5 @@
 myst-parser==0.16.1
 Sphinx==4.4.0
 sphinxcontrib-programoutput==0.17
-sphinx_copybutton==0.4.0
+sphinx_copybutton==0.5.0
 furo==2022.1.2

From 9b317178d62f9397b7e792d0f6dda827693df1b3 Mon Sep 17 00:00:00 2001
From: Paolo Melchiorre <paolo@melchiorre.org>
Date: Tue, 8 Feb 2022 20:38:39 +0100
Subject: [PATCH 0468/1034] Add Django in 'used by' section in Readme (#2875)

* Add Django in 'used by' section in Readme

* Fix Readme issue
---
 README.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index eda07b18a68..8ba9d6ceb98 100644
--- a/README.md
+++ b/README.md
@@ -130,10 +130,10 @@ code in compliance with many other _Black_ formatted projects.
 ## Used by
 
 The following notable open-source projects trust _Black_ with enforcing a consistent
-code style: pytest, tox, Pyramid, Django Channels, Hypothesis, attrs, SQLAlchemy,
-Poetry, PyPA applications (Warehouse, Bandersnatch, Pipenv, virtualenv), pandas, Pillow,
-Twisted, LocalStack, every Datadog Agent Integration, Home Assistant, Zulip, Kedro,
-OpenOA, FLORIS, ORBIT, WOMBAT, and many more.
+code style: pytest, tox, Pyramid, Django, Django Channels, Hypothesis, attrs,
+SQLAlchemy, Poetry, PyPA applications (Warehouse, Bandersnatch, Pipenv, virtualenv),
+pandas, Pillow, Twisted, LocalStack, every Datadog Agent Integration, Home Assistant,
+Zulip, Kedro, OpenOA, FLORIS, ORBIT, WOMBAT, and many more.
 
 The following organizations use _Black_: Facebook, Dropbox, KeepTruckin, Mozilla, Quora,
 Duolingo, QuantumBlack, Tesla.

From b4a6bb08fa704facbf3397f95b3216e13c3c964a Mon Sep 17 00:00:00 2001
From: Joachim Jablon <ewjoachim@gmail.com>
Date: Tue, 8 Feb 2022 21:13:58 +0100
Subject: [PATCH 0469/1034] Avoid crashing when the user has no homedir (#2814)

---
 CHANGES.md          |  1 +
 src/black/files.py  |  6 +++++-
 tests/test_black.py | 17 ++++++++++++++++-
 3 files changed, 22 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 4ad9e532808..e94b345e92a 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -20,6 +20,7 @@
 
 - Do not format `__pypackages__` directories by default (#2836)
 - Add support for specifying stable version with `--required-version` (#2832).
+- Avoid crashing when the user has no homedir (#2814)
 
 ### Documentation
 
diff --git a/src/black/files.py b/src/black/files.py
index 18c84237bf0..8348e0d8c28 100644
--- a/src/black/files.py
+++ b/src/black/files.py
@@ -87,7 +87,7 @@ def find_pyproject_toml(path_search_start: Tuple[str, ...]) -> Optional[str]:
             if path_user_pyproject_toml.is_file()
             else None
         )
-    except PermissionError as e:
+    except (PermissionError, RuntimeError) as e:
         # We do not have access to the user-level config directory, so ignore it.
         err(f"Ignoring user configuration directory due to {e!r}")
         return None
@@ -111,6 +111,10 @@ def find_user_pyproject_toml() -> Path:
 
     This looks for ~\.black on Windows and ~/.config/black on Linux and other
     Unix systems.
+
+    May raise:
+    - RuntimeError: if the current user has no homedir
+    - PermissionError: if the current process cannot access the user's homedir
     """
     if sys.platform == "win32":
         # Windows
diff --git a/tests/test_black.py b/tests/test_black.py
index cd38d9e2c0d..82abd47dffd 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -10,7 +10,7 @@
 import types
 import unittest
 from concurrent.futures import ThreadPoolExecutor
-from contextlib import contextmanager
+from contextlib import contextmanager, redirect_stderr
 from dataclasses import replace
 from io import BytesIO
 from pathlib import Path
@@ -1358,6 +1358,21 @@ def test_find_project_root(self) -> None:
                 (src_dir.resolve(), "pyproject.toml"),
             )
 
+    @patch(
+        "black.files.find_user_pyproject_toml",
+    )
+    def test_find_pyproject_toml(self, find_user_pyproject_toml: MagicMock) -> None:
+        find_user_pyproject_toml.side_effect = RuntimeError()
+
+        with redirect_stderr(io.StringIO()) as stderr:
+            result = black.files.find_pyproject_toml(
+                path_search_start=(str(Path.cwd().root),)
+            )
+
+        assert result is None
+        err = stderr.getvalue()
+        assert "Ignoring user configuration" in err
+
     @patch(
         "black.files.find_user_pyproject_toml",
         black.files.find_user_pyproject_toml.__wrapped__,

From 862c6f2c0c99b34731bd1e8812297fd2803e6a8b Mon Sep 17 00:00:00 2001
From: "Xuan (Sean) Hu" <i+github@huxuan.org>
Date: Fri, 11 Feb 2022 09:31:28 +0800
Subject: [PATCH 0470/1034] Order the disabled error codes for pylint (GH-2870)

Just make them alphabetical.
---
 docs/guides/using_black_with_other_tools.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/guides/using_black_with_other_tools.md b/docs/guides/using_black_with_other_tools.md
index 9938d814073..bde99f7c00c 100644
--- a/docs/guides/using_black_with_other_tools.md
+++ b/docs/guides/using_black_with_other_tools.md
@@ -210,7 +210,7 @@ mixed feelings about _Black_'s formatting style.
 #### Configuration
 
 ```
-disable = C0330, C0326
+disable = C0326, C0330
 max-line-length = 88
 ```
 
@@ -243,7 +243,7 @@ characters via `max-line-length = 88`.
 
 ```ini
 [MESSAGES CONTROL]
-disable = C0330, C0326
+disable = C0326, C0330
 
 [format]
 max-line-length = 88
@@ -259,7 +259,7 @@ max-line-length = 88
 max-line-length = 88
 
 [pylint.messages_control]
-disable = C0330, C0326
+disable = C0326, C0330
 ```
 
 </details>
@@ -269,7 +269,7 @@ disable = C0330, C0326
 
 ```toml
 [tool.pylint.messages_control]
-disable = "C0330, C0326"
+disable = "C0326, C0330"
 
 [tool.pylint.format]
 max-line-length = "88"

From 07a2e6f67810a8949b76a26c434c91d3fda7ac24 Mon Sep 17 00:00:00 2001
From: Laurent Lyaudet <Laurent.Lyaudet@gmail.com>
Date: Fri, 11 Feb 2022 02:32:55 +0100
Subject: [PATCH 0471/1034] Fix typo in file_collection_and_discovery.md
 (GH-2860)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

"you your" -> "your"

Co-authored-by: Felix Hildén <felix.hilden@gmail.com>
---
 docs/usage_and_configuration/file_collection_and_discovery.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/usage_and_configuration/file_collection_and_discovery.md b/docs/usage_and_configuration/file_collection_and_discovery.md
index bd90ccc6af8..de1d5e6c11e 100644
--- a/docs/usage_and_configuration/file_collection_and_discovery.md
+++ b/docs/usage_and_configuration/file_collection_and_discovery.md
@@ -24,8 +24,8 @@ as .pyi, and whether string normalization was omitted.
 
 To override the location of these files on all systems, set the environment variable
 `BLACK_CACHE_DIR` to the preferred location. Alternatively on macOS and Linux, set
-`XDG_CACHE_HOME` to you your preferred location. For example, if you want to put the
-cache in the directory you're running _Black_ from, set `BLACK_CACHE_DIR=.cache/black`.
+`XDG_CACHE_HOME` to your preferred location. For example, if you want to put the cache
+in the directory you're running _Black_ from, set `BLACK_CACHE_DIR=.cache/black`.
 _Black_ will then write the above files to `.cache/black`. Note that `BLACK_CACHE_DIR`
 will take precedence over `XDG_CACHE_HOME` if both are set.
 

From 50a856970d2453087662a295631d6f24a12bc3a1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fr=C3=A9d=C3=A9rik=20Paradis?= <fredy_14@live.fr>
Date: Sun, 20 Feb 2022 20:17:01 -0500
Subject: [PATCH 0472/1034] Isolate command line tests for notebooks from
 user-level config (#2854)

---
 tests/test_ipynb.py | 18 ++++++++++++++----
 1 file changed, 14 insertions(+), 4 deletions(-)

diff --git a/tests/test_ipynb.py b/tests/test_ipynb.py
index d78a68cd9a0..473047a3b32 100644
--- a/tests/test_ipynb.py
+++ b/tests/test_ipynb.py
@@ -24,6 +24,8 @@
 
 JUPYTER_MODE = Mode(is_ipynb=True)
 
+EMPTY_CONFIG = DATA_DIR / "empty_pyproject.toml"
+
 runner = CliRunner()
 
 
@@ -410,6 +412,7 @@ def test_ipynb_diff_with_change() -> None:
         [
             str(DATA_DIR / "notebook_trailing_newline.ipynb"),
             "--diff",
+            f"--config={EMPTY_CONFIG}",
         ],
     )
     expected = "@@ -1,3 +1,3 @@\n %%time\n \n-print('foo')\n" '+print("foo")\n'
@@ -422,6 +425,7 @@ def test_ipynb_diff_with_no_change() -> None:
         [
             str(DATA_DIR / "notebook_without_changes.ipynb"),
             "--diff",
+            f"--config={EMPTY_CONFIG}",
         ],
     )
     expected = "1 file would be left unchanged."
@@ -440,13 +444,17 @@ def test_cache_isnt_written_if_no_jupyter_deps_single(
     monkeypatch.setattr(
         "black.jupyter_dependencies_are_installed", lambda verbose, quiet: False
     )
-    result = runner.invoke(main, [str(tmp_path / "notebook.ipynb")])
+    result = runner.invoke(
+        main, [str(tmp_path / "notebook.ipynb"), f"--config={EMPTY_CONFIG}"]
+    )
     assert "No Python files are present to be formatted. Nothing to do" in result.output
     jupyter_dependencies_are_installed.cache_clear()
     monkeypatch.setattr(
         "black.jupyter_dependencies_are_installed", lambda verbose, quiet: True
     )
-    result = runner.invoke(main, [str(tmp_path / "notebook.ipynb")])
+    result = runner.invoke(
+        main, [str(tmp_path / "notebook.ipynb"), f"--config={EMPTY_CONFIG}"]
+    )
     assert "reformatted" in result.output
 
 
@@ -462,13 +470,13 @@ def test_cache_isnt_written_if_no_jupyter_deps_dir(
     monkeypatch.setattr(
         "black.files.jupyter_dependencies_are_installed", lambda verbose, quiet: False
     )
-    result = runner.invoke(main, [str(tmp_path)])
+    result = runner.invoke(main, [str(tmp_path), f"--config={EMPTY_CONFIG}"])
     assert "No Python files are present to be formatted. Nothing to do" in result.output
     jupyter_dependencies_are_installed.cache_clear()
     monkeypatch.setattr(
         "black.files.jupyter_dependencies_are_installed", lambda verbose, quiet: True
     )
-    result = runner.invoke(main, [str(tmp_path)])
+    result = runner.invoke(main, [str(tmp_path), f"--config={EMPTY_CONFIG}"])
     assert "reformatted" in result.output
 
 
@@ -483,6 +491,7 @@ def test_ipynb_flag(tmp_path: pathlib.Path) -> None:
             str(tmp_nb),
             "--diff",
             "--ipynb",
+            f"--config={EMPTY_CONFIG}",
         ],
     )
     expected = "@@ -1,3 +1,3 @@\n %%time\n \n-print('foo')\n" '+print("foo")\n'
@@ -498,6 +507,7 @@ def test_ipynb_and_pyi_flags() -> None:
             "--pyi",
             "--ipynb",
             "--diff",
+            f"--config={EMPTY_CONFIG}",
         ],
     )
     assert isinstance(result.exception, SystemExit)

From 8089aaad6b0116eb3a4758430129c3d8d900585b Mon Sep 17 00:00:00 2001
From: "D. Ben Knoble" <ben.knoble+github@gmail.com>
Date: Sun, 20 Feb 2022 20:37:07 -0500
Subject: [PATCH 0473/1034] correct Vim integration code (#2853)

- use `Black` directly: the commands an autocommand runs are Ex commands, so no
  execute or colon is necessary.
- use an `augroup` (best practice) to prevent duplicate autocommands from
  hindering performance.
---
 docs/integrations/editors.md | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/docs/integrations/editors.md b/docs/integrations/editors.md
index 5d2f83ace8a..1c7879b63a6 100644
--- a/docs/integrations/editors.md
+++ b/docs/integrations/editors.md
@@ -189,10 +189,13 @@ If you need to do anything special to make your virtualenv work and install _Bla
 example you want to run a version from main), create a virtualenv manually and point
 `g:black_virtualenv` to it. The plugin will use it.
 
-To run _Black_ on save, add the following line to `.vimrc` or `init.vim`:
+To run _Black_ on save, add the following lines to `.vimrc` or `init.vim`:
 
 ```
-autocmd BufWritePre *.py execute ':Black'
+augroup black_on_save
+  autocmd!
+  autocmd BufWritePre *.py Black
+augroup end
 ```
 
 To run _Black_ on a key press (e.g. F9 below), add this:

From c26c7728e883db1425f7ed7affec41da3b3200a3 Mon Sep 17 00:00:00 2001
From: Shivansh-007 <shivansh-007@outlook.com>
Date: Mon, 21 Feb 2022 07:29:36 +0530
Subject: [PATCH 0474/1034] Add special config verbose log case when black is
 using user-level config (#2861)

---
 CHANGES.md            |  2 ++
 src/black/__init__.py | 21 ++++++++++++++++++---
 2 files changed, 20 insertions(+), 3 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index e94b345e92a..de85bd8a02d 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -35,6 +35,8 @@
 
 <!-- Changes to Black's terminal output and error messages -->
 
+- In verbose, mode, log when _Black_ is using user-level config (#2861)
+
 ### Packaging
 
 <!-- Changes to how Black is packaged, such as dependency requirements -->
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 8c28b6ba18b..b7bf822ed08 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -49,7 +49,12 @@
 from black.concurrency import cancel, shutdown, maybe_install_uvloop
 from black.output import dump_to_file, ipynb_diff, diff, color_diff, out, err
 from black.report import Report, Changed, NothingChanged
-from black.files import find_project_root, find_pyproject_toml, parse_pyproject_toml
+from black.files import (
+    find_project_root,
+    find_pyproject_toml,
+    parse_pyproject_toml,
+    find_user_pyproject_toml,
+)
 from black.files import gen_python_files, get_gitignore, normalize_path_maybe_ignore
 from black.files import wrap_stream_for_windows
 from black.parsing import InvalidInput  # noqa F401
@@ -402,7 +407,7 @@ def validate_regex(
     help="Read configuration from FILE path.",
 )
 @click.pass_context
-def main(
+def main(  # noqa: C901
     ctx: click.Context,
     code: Optional[str],
     line_length: int,
@@ -469,7 +474,17 @@ def main(
 
         if config:
             config_source = ctx.get_parameter_source("config")
-            if config_source in (ParameterSource.DEFAULT, ParameterSource.DEFAULT_MAP):
+            user_level_config = str(find_user_pyproject_toml())
+            if config == user_level_config:
+                out(
+                    f"Using configuration from user-level config at "
+                    f"'{user_level_config}'.",
+                    fg="blue",
+                )
+            elif config_source in (
+                ParameterSource.DEFAULT,
+                ParameterSource.DEFAULT_MAP,
+            ):
                 out("Using configuration from project root.", fg="blue")
             else:
                 out(f"Using configuration in '{config}'.", fg="blue")

From 7e2b2d4784ef8b66b2201ac936f2f9fcab936515 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Wed, 23 Feb 2022 12:00:06 -0500
Subject: [PATCH 0475/1034] Bump furo from 2022.1.2 to 2022.2.14.1 in /docs
 (GH-2892)

Bumps [furo](https://github.com/pradyunsg/furo) from 2022.1.2 to 2022.2.14.1.
- [Release notes](https://github.com/pradyunsg/furo/releases)
- [Changelog](https://github.com/pradyunsg/furo/blob/main/docs/changelog.md)
- [Commits](https://github.com/pradyunsg/furo/compare/2022.01.02...2022.02.14.1)

---
updated-dependencies:
- dependency-name: furo
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 docs/requirements.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index 0b685425dde..ecd71f45e9e 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -4,4 +4,4 @@ myst-parser==0.16.1
 Sphinx==4.4.0
 sphinxcontrib-programoutput==0.17
 sphinx_copybutton==0.5.0
-furo==2022.1.2
+furo==2022.2.14.1

From 2918ea3b079bbb617b2f9f0d5bc0b84fde04e48e Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Wed, 23 Feb 2022 18:20:59 -0800
Subject: [PATCH 0476/1034] Format ourselves in preview mode (#2889)

---
 pyproject.toml        | 5 ++++-
 src/black/__init__.py | 8 ++++----
 tests/test_ipynb.py   | 4 ++--
 3 files changed, 10 insertions(+), 7 deletions(-)

diff --git a/pyproject.toml b/pyproject.toml
index ec617790039..d9373740a5c 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -17,7 +17,10 @@ extend-exclude = '''
   | profiling
 )/
 '''
-
+# We use preview style for formatting Black itself. If you
+# want stable formatting across releases, you should keep
+# this off.
+preview = true
 
 # Build system information below.
 # NOTE: You don't need this in your own Black configuration.
diff --git a/src/black/__init__.py b/src/black/__init__.py
index b7bf822ed08..c1b989536a7 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -1358,10 +1358,10 @@ def assert_equivalent(src: str, dst: str) -> None:
         src_ast = parse_ast(src)
     except Exception as exc:
         raise AssertionError(
-            f"cannot use --safe with this file; failed to parse source file AST: "
+            "cannot use --safe with this file; failed to parse source file AST: "
             f"{exc}\n"
-            f"This could be caused by running Black with an older Python version "
-            f"that does not support new syntax used in your source file."
+            "This could be caused by running Black with an older Python version "
+            "that does not support new syntax used in your source file."
         ) from exc
 
     try:
@@ -1380,7 +1380,7 @@ def assert_equivalent(src: str, dst: str) -> None:
         log = dump_to_file(diff(src_ast_str, dst_ast_str, "src", "dst"))
         raise AssertionError(
             "INTERNAL ERROR: Black produced code that is not equivalent to the"
-            f" source.  Please report a bug on "
+            " source.  Please report a bug on "
             f"https://github.com/psf/black/issues.  This diff might be helpful: {log}"
         ) from None
 
diff --git a/tests/test_ipynb.py b/tests/test_ipynb.py
index 473047a3b32..b534d77c22a 100644
--- a/tests/test_ipynb.py
+++ b/tests/test_ipynb.py
@@ -415,7 +415,7 @@ def test_ipynb_diff_with_change() -> None:
             f"--config={EMPTY_CONFIG}",
         ],
     )
-    expected = "@@ -1,3 +1,3 @@\n %%time\n \n-print('foo')\n" '+print("foo")\n'
+    expected = "@@ -1,3 +1,3 @@\n %%time\n \n-print('foo')\n+print(\"foo\")\n"
     assert expected in result.output
 
 
@@ -494,7 +494,7 @@ def test_ipynb_flag(tmp_path: pathlib.Path) -> None:
             f"--config={EMPTY_CONFIG}",
         ],
     )
-    expected = "@@ -1,3 +1,3 @@\n %%time\n \n-print('foo')\n" '+print("foo")\n'
+    expected = "@@ -1,3 +1,3 @@\n %%time\n \n-print('foo')\n+print(\"foo\")\n"
     assert expected in result.output
 
 

From 6cfb51871b59fcca04df24031f506d7dc2178a12 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Wed, 23 Feb 2022 18:32:00 -0800
Subject: [PATCH 0477/1034] separate CHANGELOG section for preview style
 (#2890)

---
 CHANGES.md                           | 6 +++++-
 docs/contributing/release_process.md | 6 +++++-
 2 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index de85bd8a02d..5f9341d048c 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -8,7 +8,11 @@
 
 ### Style
 
-<!-- Changes that affect Black's style -->
+<!-- Changes that affect Black's stable style -->
+
+### Preview style
+
+<!-- Changes that affect Black's preview style -->
 
 ### _Blackd_
 
diff --git a/docs/contributing/release_process.md b/docs/contributing/release_process.md
index 89beb099e66..6a4b8680808 100644
--- a/docs/contributing/release_process.md
+++ b/docs/contributing/release_process.md
@@ -47,7 +47,11 @@ Use the following template for a clean changelog after the release:
 
 ### Style
 
-<!-- Changes that affect Black's style -->
+<!-- Changes that affect Black's stable style -->
+
+### Preview style
+
+<!-- Changes that affect Black's preview style -->
 
 ### _Blackd_
 

From 9b161072c13c0ec32c9ca9bd48fad17f781a56d4 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Wed, 23 Feb 2022 19:41:42 -0800
Subject: [PATCH 0478/1034] fix new formatting issue (#2895)

Race between #2889 and another PR.
---
 src/black/__init__.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index c1b989536a7..c4ec99b441f 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -477,7 +477,7 @@ def main(  # noqa: C901
             user_level_config = str(find_user_pyproject_toml())
             if config == user_level_config:
                 out(
-                    f"Using configuration from user-level config at "
+                    "Using configuration from user-level config at "
                     f"'{user_level_config}'.",
                     fg="blue",
                 )

From 147526451a43e9296ca963ed8e6b7224db93e69b Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Mon, 28 Feb 2022 20:13:34 -0800
Subject: [PATCH 0479/1034] README: fix "Pragmatism" link target (#2901)

Fixes #2897
---
 README.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 8ba9d6ceb98..f2d06bedad2 100644
--- a/README.md
+++ b/README.md
@@ -81,7 +81,9 @@ section for details). If you're feeling confident, use `--fast`.
 
 _Black_ is a PEP 8 compliant opinionated formatter. _Black_ reformats entire files in
 place. Style configuration options are deliberately limited and rarely added. It doesn't
-take previous formatting into account (see [Pragmatism](#pragmatism) for exceptions).
+take previous formatting into account (see
+[Pragmatism](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#pragmatism)
+for exceptions).
 
 Our documentation covers the current _Black_ code style, but planned changes to it are
 also documented. They're both worth taking a look:

From 67eaf2466596394d5765ba4026d34e7b822814ab Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tom=C3=A1=C5=A1=20Jel=C3=ADnek?= <tojeline@redhat.com>
Date: Thu, 3 Mar 2022 18:29:48 +0100
Subject: [PATCH 0480/1034] replace md5 with sha256 (#2905)

MD5 is unavailable on systems with active FIPS mode. That makes black
crash when run on such systems.
---
 CHANGES.md        | 1 +
 src/black/mode.py | 4 ++--
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 5f9341d048c..b594e035b04 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -25,6 +25,7 @@
 - Do not format `__pypackages__` directories by default (#2836)
 - Add support for specifying stable version with `--required-version` (#2832).
 - Avoid crashing when the user has no homedir (#2814)
+- Avoid crashing when md5 is not available (#2905)
 
 ### Documentation
 
diff --git a/src/black/mode.py b/src/black/mode.py
index 6d45e3dc4da..455ed36e27e 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -4,7 +4,7 @@
 chosen by the user.
 """
 
-from hashlib import md5
+from hashlib import sha256
 import sys
 
 from dataclasses import dataclass, field
@@ -182,6 +182,6 @@ def get_cache_key(self) -> str:
             str(int(self.magic_trailing_comma)),
             str(int(self.experimental_string_processing)),
             str(int(self.preview)),
-            md5((",".join(sorted(self.python_cell_magics))).encode()).hexdigest(),
+            sha256((",".join(sorted(self.python_cell_magics))).encode()).hexdigest(),
         ]
         return ".".join(parts)

From 7af3abd38392588ac737bae09f6b15d80fe344b1 Mon Sep 17 00:00:00 2001
From: oncomouse <oncomouse@gmail.com>
Date: Fri, 4 Mar 2022 18:15:39 -0600
Subject: [PATCH 0481/1034] Move test for g:load_black to improve plugin
 performance (GH-2896)

If a vim/neovim user wishes to suppress loading the vim plugin by
setting g:load_black in their VIMRC (for me, Arch linux automatically
adds the plugin to Neovim's RTP, even though I'm not using it), the
current location of the test comes after a call to has('python3'). This
adds, in my tests, between 35 and 45 ms to Vim load time (which I know
isn't a lot but it's also unnecessary). Moving the call to
`exists('g:load_black')` to before the call to `has('python3')` removes
this unnecessary test and speeds up loading.

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 CHANGES.md       | 2 ++
 plugin/black.vim | 8 ++++----
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index b594e035b04..a0b87c78015 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -36,6 +36,8 @@
 
 <!-- For example, Docker, GitHub Actions, pre-commit, editors -->
 
+- Move test to disable plugin in Vim/Neovim, which speeds up loading (#2896)
+
 ### Output
 
 <!-- Changes to Black's terminal output and error messages -->
diff --git a/plugin/black.vim b/plugin/black.vim
index dbe236b5f34..3fc11fe9e8d 100644
--- a/plugin/black.vim
+++ b/plugin/black.vim
@@ -15,6 +15,10 @@
 "  1.2:
 "    - use autoload script
 
+if exists("g:load_black")
+  finish
+endif
+
 if v:version < 700 || !has('python3')
     func! __BLACK_MISSING()
         echo "The black.vim plugin requires vim7.0+ with Python 3.6 support."
@@ -25,10 +29,6 @@ if v:version < 700 || !has('python3')
     finish
 endif
 
-if exists("g:load_black")
-  finish
-endif
-
 let g:load_black = "py1.0"
 if !exists("g:black_virtualenv")
   if has("nvim")

From eb213151cec22dc3589e4a033b897b216b60fd82 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Fri, 4 Mar 2022 16:48:53 -0800
Subject: [PATCH 0482/1034] Bump furo from 2022.2.14.1 to 2022.3.4 in /docs
 (#2906)

Bumps [furo](https://github.com/pradyunsg/furo) from 2022.2.14.1 to 2022.3.4.
- [Release notes](https://github.com/pradyunsg/furo/releases)
- [Changelog](https://github.com/pradyunsg/furo/blob/main/docs/changelog.md)
- [Commits](https://github.com/pradyunsg/furo/compare/2022.02.14.1...2022.03.04)

---
updated-dependencies:
- dependency-name: furo
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 docs/requirements.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index ecd71f45e9e..5ca7a6f1cf7 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -4,4 +4,4 @@ myst-parser==0.16.1
 Sphinx==4.4.0
 sphinxcontrib-programoutput==0.17
 sphinx_copybutton==0.5.0
-furo==2022.2.14.1
+furo==2022.3.4

From 6f4976a7ace2fb5c6a5df57c4cb7dcf65eff44c9 Mon Sep 17 00:00:00 2001
From: Batuhan Taskaya <isidentical@gmail.com>
Date: Sat, 5 Mar 2022 04:37:16 +0300
Subject: [PATCH 0483/1034] Allow `for`'s target expression to be starred
 (#2879)

Fixes #2878
---
 CHANGES.md                       |  3 ++-
 src/blib2to3/Grammar.txt         |  2 +-
 tests/data/starred_for_target.py | 27 +++++++++++++++++++++++++++
 tests/test_format.py             |  1 +
 4 files changed, 31 insertions(+), 2 deletions(-)
 create mode 100644 tests/data/starred_for_target.py

diff --git a/CHANGES.md b/CHANGES.md
index a0b87c78015..ac9212e9940 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -50,7 +50,8 @@
 
 ### Parser
 
-<!-- Changes to the parser or to version autodetection -->
+- Black can now parse starred expressions in the target of `for` and `async for`
+  statements, e.g `for item in *items_1, *items_2: pass` (#2879).
 
 ### Performance
 
diff --git a/src/blib2to3/Grammar.txt b/src/blib2to3/Grammar.txt
index cf4799f8abe..0ce6cf39111 100644
--- a/src/blib2to3/Grammar.txt
+++ b/src/blib2to3/Grammar.txt
@@ -109,7 +109,7 @@ compound_stmt: if_stmt | while_stmt | for_stmt | try_stmt | with_stmt | funcdef
 async_stmt: ASYNC (funcdef | with_stmt | for_stmt)
 if_stmt: 'if' namedexpr_test ':' suite ('elif' namedexpr_test ':' suite)* ['else' ':' suite]
 while_stmt: 'while' namedexpr_test ':' suite ['else' ':' suite]
-for_stmt: 'for' exprlist 'in' testlist ':' suite ['else' ':' suite]
+for_stmt: 'for' exprlist 'in' testlist_star_expr ':' suite ['else' ':' suite]
 try_stmt: ('try' ':' suite
            ((except_clause ':' suite)+
 	    ['else' ':' suite]
diff --git a/tests/data/starred_for_target.py b/tests/data/starred_for_target.py
new file mode 100644
index 00000000000..8fc8e059ed3
--- /dev/null
+++ b/tests/data/starred_for_target.py
@@ -0,0 +1,27 @@
+for x in *a, *b:
+    print(x)
+
+for x in a, b, *c:
+    print(x)
+
+for x in *a, b, c:
+    print(x)
+
+for x in *a, b, *c:
+    print(x)
+
+async for x in *a, *b:
+    print(x)
+
+async for x in *a, b, *c:
+    print(x)
+
+async for x in a, b, *c:
+    print(x)
+
+async for x in (
+    *loooooooooooooooooooooong,
+    very,
+    *loooooooooooooooooooooooooooooooooooooooooooooooong,
+):
+    print(x)
diff --git a/tests/test_format.py b/tests/test_format.py
index 04676c1c2c5..04eda43d5cf 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -62,6 +62,7 @@
 ]
 
 PY310_CASES: List[str] = [
+    "starred_for_target",
     "pattern_matching_simple",
     "pattern_matching_complex",
     "pattern_matching_extras",

From dab1be38e670b822777ac5338b9b2dfef4c34690 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 7 Mar 2022 08:44:01 -0800
Subject: [PATCH 0484/1034] Bump actions/checkout from 2 to 3 (#2909)

Bumps [actions/checkout](https://github.com/actions/checkout) from 2 to 3.
- [Release notes](https://github.com/actions/checkout/releases)
- [Changelog](https://github.com/actions/checkout/blob/main/CHANGELOG.md)
- [Commits](https://github.com/actions/checkout/compare/v2...v3)

---
updated-dependencies:
- dependency-name: actions/checkout
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/changelog.yml           | 2 +-
 .github/workflows/diff_shades.yml         | 2 +-
 .github/workflows/diff_shades_comment.yml | 2 +-
 .github/workflows/doc.yml                 | 2 +-
 .github/workflows/docker.yml              | 2 +-
 .github/workflows/fuzz.yml                | 2 +-
 .github/workflows/lint.yml                | 2 +-
 .github/workflows/pypi_upload.yml         | 2 +-
 .github/workflows/test.yml                | 4 ++--
 .github/workflows/upload_binary.yml       | 2 +-
 .github/workflows/uvloop_test.yml         | 2 +-
 11 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/.github/workflows/changelog.yml b/.github/workflows/changelog.yml
index 476e2545ce8..3ffdb086493 100644
--- a/.github/workflows/changelog.yml
+++ b/.github/workflows/changelog.yml
@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
 
       - name: Grep CHANGES.md for PR number
         if: contains(github.event.pull_request.labels.*.name, 'skip news') != true
diff --git a/.github/workflows/diff_shades.yml b/.github/workflows/diff_shades.yml
index 68cc2383306..62cac6748fd 100644
--- a/.github/workflows/diff_shades.yml
+++ b/.github/workflows/diff_shades.yml
@@ -42,7 +42,7 @@ jobs:
 
     steps:
       - name: Checkout this repository (full clone)
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
         with:
           fetch-depth: 0
 
diff --git a/.github/workflows/diff_shades_comment.yml b/.github/workflows/diff_shades_comment.yml
index 0433bbbf85f..d09c1e3b2a3 100644
--- a/.github/workflows/diff_shades_comment.yml
+++ b/.github/workflows/diff_shades_comment.yml
@@ -12,7 +12,7 @@ jobs:
   comment:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - uses: actions/setup-python@v2
 
       - name: Install support dependencies
diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml
index 5689d2887c4..b831151afac 100644
--- a/.github/workflows/doc.yml
+++ b/.github/workflows/doc.yml
@@ -18,7 +18,7 @@ jobs:
 
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
 
       - name: Set up latest Python
         uses: actions/setup-python@v2
diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
index 0825385c6c0..b75ce2bb6f1 100644
--- a/.github/workflows/docker.yml
+++ b/.github/workflows/docker.yml
@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
 
       - name: Set up QEMU
         uses: docker/setup-qemu-action@v1
diff --git a/.github/workflows/fuzz.yml b/.github/workflows/fuzz.yml
index 146277a7312..4721a842773 100644
--- a/.github/workflows/fuzz.yml
+++ b/.github/workflows/fuzz.yml
@@ -18,7 +18,7 @@ jobs:
         python-version: ["3.6", "3.7", "3.8", "3.9", "3.10"]
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
 
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v2
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index 2f6c504d3f2..0061ebcd730 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
 
       - name: Set up Python
         uses: actions/setup-python@v2
diff --git a/.github/workflows/pypi_upload.yml b/.github/workflows/pypi_upload.yml
index 0921b624c45..d3eeaad286f 100644
--- a/.github/workflows/pypi_upload.yml
+++ b/.github/workflows/pypi_upload.yml
@@ -10,7 +10,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
 
       - name: Set up Python
         uses: actions/setup-python@v2
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 7ba2a84d049..72247d2bc9a 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -28,7 +28,7 @@ jobs:
         os: [ubuntu-latest, macOS-latest, windows-latest]
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
 
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v2
@@ -74,7 +74,7 @@ jobs:
 
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - name: Coveralls finished
         uses: AndreMiras/coveralls-python-action@v20201129
         with:
diff --git a/.github/workflows/upload_binary.yml b/.github/workflows/upload_binary.yml
index 766f37cc321..b2d6e05b74d 100644
--- a/.github/workflows/upload_binary.yml
+++ b/.github/workflows/upload_binary.yml
@@ -26,7 +26,7 @@ jobs:
             executable_mime: "application/x-mach-binary"
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
 
       - name: Set up latest Python
         uses: actions/setup-python@v2
diff --git a/.github/workflows/uvloop_test.yml b/.github/workflows/uvloop_test.yml
index a639bbd1b97..e145b16bea5 100644
--- a/.github/workflows/uvloop_test.yml
+++ b/.github/workflows/uvloop_test.yml
@@ -27,7 +27,7 @@ jobs:
         os: [ubuntu-latest, macOS-latest]
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
 
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v2

From fd6e92aa460659d26136f5f86878b47254480259 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 7 Mar 2022 12:33:25 -0800
Subject: [PATCH 0485/1034] Bump actions/setup-python from 2 to 3 (#2908)

Bumps [actions/setup-python](https://github.com/actions/setup-python) from 2 to 3.
- [Release notes](https://github.com/actions/setup-python/releases)
- [Commits](https://github.com/actions/setup-python/compare/v2...v3)

---
updated-dependencies:
- dependency-name: actions/setup-python
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Cooper Lees <me@cooperlees.com>
---
 .github/workflows/diff_shades.yml         | 2 +-
 .github/workflows/diff_shades_comment.yml | 2 +-
 .github/workflows/doc.yml                 | 2 +-
 .github/workflows/fuzz.yml                | 2 +-
 .github/workflows/lint.yml                | 2 +-
 .github/workflows/pypi_upload.yml         | 2 +-
 .github/workflows/test.yml                | 2 +-
 .github/workflows/upload_binary.yml       | 2 +-
 .github/workflows/uvloop_test.yml         | 2 +-
 9 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/.github/workflows/diff_shades.yml b/.github/workflows/diff_shades.yml
index 62cac6748fd..e9deaba0136 100644
--- a/.github/workflows/diff_shades.yml
+++ b/.github/workflows/diff_shades.yml
@@ -46,7 +46,7 @@ jobs:
         with:
           fetch-depth: 0
 
-      - uses: actions/setup-python@v2
+      - uses: actions/setup-python@v3
 
       - name: Install diff-shades and support dependencies
         run: |
diff --git a/.github/workflows/diff_shades_comment.yml b/.github/workflows/diff_shades_comment.yml
index d09c1e3b2a3..cf5d8bf9ac5 100644
--- a/.github/workflows/diff_shades_comment.yml
+++ b/.github/workflows/diff_shades_comment.yml
@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
-      - uses: actions/setup-python@v2
+      - uses: actions/setup-python@v3
 
       - name: Install support dependencies
         run: |
diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml
index b831151afac..1ad4b3a7605 100644
--- a/.github/workflows/doc.yml
+++ b/.github/workflows/doc.yml
@@ -21,7 +21,7 @@ jobs:
       - uses: actions/checkout@v3
 
       - name: Set up latest Python
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v3
 
       - name: Install dependencies
         run: |
diff --git a/.github/workflows/fuzz.yml b/.github/workflows/fuzz.yml
index 4721a842773..8fba67a5a01 100644
--- a/.github/workflows/fuzz.yml
+++ b/.github/workflows/fuzz.yml
@@ -21,7 +21,7 @@ jobs:
       - uses: actions/checkout@v3
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v3
         with:
           python-version: ${{ matrix.python-version }}
 
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index 0061ebcd730..b630114882d 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -17,7 +17,7 @@ jobs:
       - uses: actions/checkout@v3
 
       - name: Set up Python
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v3
 
       - name: Install dependencies
         run: |
diff --git a/.github/workflows/pypi_upload.yml b/.github/workflows/pypi_upload.yml
index d3eeaad286f..9d970592d98 100644
--- a/.github/workflows/pypi_upload.yml
+++ b/.github/workflows/pypi_upload.yml
@@ -13,7 +13,7 @@ jobs:
       - uses: actions/checkout@v3
 
       - name: Set up Python
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v3
 
       - name: Install latest pip, build, twine
         run: |
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 72247d2bc9a..ce481761aea 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -31,7 +31,7 @@ jobs:
       - uses: actions/checkout@v3
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v3
         with:
           python-version: ${{ matrix.python-version }}
 
diff --git a/.github/workflows/upload_binary.yml b/.github/workflows/upload_binary.yml
index b2d6e05b74d..ed8d9fdd572 100644
--- a/.github/workflows/upload_binary.yml
+++ b/.github/workflows/upload_binary.yml
@@ -29,7 +29,7 @@ jobs:
       - uses: actions/checkout@v3
 
       - name: Set up latest Python
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v3
         with:
           python-version: "*"
 
diff --git a/.github/workflows/uvloop_test.yml b/.github/workflows/uvloop_test.yml
index e145b16bea5..14b17d68424 100644
--- a/.github/workflows/uvloop_test.yml
+++ b/.github/workflows/uvloop_test.yml
@@ -30,7 +30,7 @@ jobs:
       - uses: actions/checkout@v3
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v3
 
       - name: Install latest pip
         run: |

From 24ffc54a53b52293a54d7ef9f2105c26e945cc67 Mon Sep 17 00:00:00 2001
From: yoerg <73831825+yoerg@users.noreply.github.com>
Date: Tue, 8 Mar 2022 16:28:13 +0100
Subject: [PATCH 0486/1034] Fix handling of Windows junctions in
 normalize_path_maybe_ignore (#2904)

Fixes #2569
---
 CHANGES.md          |  2 ++
 src/black/files.py  | 19 +++++++++----------
 tests/test_black.py | 45 +++++++++++++++++++--------------------------
 3 files changed, 30 insertions(+), 36 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index ac9212e9940..4264e631fab 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -53,6 +53,8 @@
 - Black can now parse starred expressions in the target of `for` and `async for`
   statements, e.g `for item in *items_1, *items_2: pass` (#2879).
 
+- Fix handling of directory junctions on Windows (#2904)
+
 ### Performance
 
 <!-- Changes that improve Black's performance. -->
diff --git a/src/black/files.py b/src/black/files.py
index 8348e0d8c28..b6c1cf3ffe1 100644
--- a/src/black/files.py
+++ b/src/black/files.py
@@ -151,23 +151,22 @@ def normalize_path_maybe_ignore(
     """
     try:
         abspath = path if path.is_absolute() else Path.cwd() / path
-        normalized_path = abspath.resolve().relative_to(root).as_posix()
-    except OSError as e:
-        if report:
-            report.path_ignored(path, f"cannot be read because {e}")
-        return None
-
-    except ValueError:
-        if path.is_symlink():
+        normalized_path = abspath.resolve()
+        try:
+            root_relative_path = normalized_path.relative_to(root).as_posix()
+        except ValueError:
             if report:
                 report.path_ignored(
                     path, f"is a symbolic link that points outside {root}"
                 )
             return None
 
-        raise
+    except OSError as e:
+        if report:
+            report.path_ignored(path, f"cannot be read because {e}")
+        return None
 
-    return normalized_path
+    return root_relative_path
 
 
 def path_is_excluded(
diff --git a/tests/test_black.py b/tests/test_black.py
index 82abd47dffd..b1bf1772550 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -1418,6 +1418,25 @@ def test_bpo_33660_workaround(self) -> None:
             normalized_path = black.normalize_path_maybe_ignore(path, root, report)
             self.assertEqual(normalized_path, "workspace/project")
 
+    def test_normalize_path_ignore_windows_junctions_outside_of_root(self) -> None:
+        if system() != "Windows":
+            return
+
+        with TemporaryDirectory() as workspace:
+            root = Path(workspace)
+            junction_dir = root / "junction"
+            junction_target_outside_of_root = root / ".."
+            os.system(f"mklink /J {junction_dir} {junction_target_outside_of_root}")
+
+            report = black.Report(verbose=True)
+            normalized_path = black.normalize_path_maybe_ignore(
+                junction_dir, root, report
+            )
+            # Manually delete for Python < 3.8
+            os.system(f"rmdir {junction_dir}")
+
+            self.assertEqual(normalized_path, None)
+
     def test_newline_comment_interaction(self) -> None:
         source = "class A:\\\r\n# type: ignore\n pass\n"
         output = black.format_str(source, mode=DEFAULT_MODE)
@@ -1994,7 +2013,6 @@ def test_symlink_out_of_root_directory(self) -> None:
         path.iterdir.return_value = [child]
         child.resolve.return_value = Path("/a/b/c")
         child.as_posix.return_value = "/a/b/c"
-        child.is_symlink.return_value = True
         try:
             list(
                 black.gen_python_files(
@@ -2014,31 +2032,6 @@ def test_symlink_out_of_root_directory(self) -> None:
             pytest.fail(f"`get_python_files_in_dir()` failed: {ve}")
         path.iterdir.assert_called_once()
         child.resolve.assert_called_once()
-        child.is_symlink.assert_called_once()
-        # `child` should behave like a strange file which resolved path is clearly
-        # outside of the `root` directory.
-        child.is_symlink.return_value = False
-        with pytest.raises(ValueError):
-            list(
-                black.gen_python_files(
-                    path.iterdir(),
-                    root,
-                    include,
-                    exclude,
-                    None,
-                    None,
-                    report,
-                    gitignore,
-                    verbose=False,
-                    quiet=False,
-                )
-            )
-        path.iterdir.assert_called()
-        assert path.iterdir.call_count == 2
-        child.resolve.assert_called()
-        assert child.resolve.call_count == 2
-        child.is_symlink.assert_called()
-        assert child.is_symlink.call_count == 2
 
     @patch("black.find_project_root", lambda *args: (THIS_DIR.resolve(), None))
     def test_get_sources_with_stdin(self) -> None:

From 71e71e5f52e5f6bdeae63cc8c11b1bee44d11c30 Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Tue, 8 Mar 2022 08:47:51 -0800
Subject: [PATCH 0487/1034] Use tomllib on Python 3.11 (#2903)

---
 CHANGES.md         |  3 +++
 setup.py           |  2 +-
 src/black/files.py | 10 +++++++---
 3 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 4264e631fab..edca0dcdad4 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -48,6 +48,9 @@
 
 <!-- Changes to how Black is packaged, such as dependency requirements -->
 
+- On Python 3.11 and newer, use the standard library's `tomllib` instead of `tomli`
+  (#2903)
+
 ### Parser
 
 - Black can now parse starred expressions in the target of `for` and `async for`
diff --git a/setup.py b/setup.py
index 466f1a9c3a6..6b5b957e96f 100644
--- a/setup.py
+++ b/setup.py
@@ -99,7 +99,7 @@ def find_python_files(base: Path) -> List[Path]:
     install_requires=[
         "click>=8.0.0",
         "platformdirs>=2",
-        "tomli>=1.1.0",
+        "tomli>=1.1.0; python_version < '3.11'",
         "typed-ast>=1.4.2; python_version < '3.8' and implementation_name == 'cpython'",
         "pathspec>=0.9.0",
         "dataclasses>=0.6; python_version < '3.7'",
diff --git a/src/black/files.py b/src/black/files.py
index b6c1cf3ffe1..52c77c63346 100644
--- a/src/black/files.py
+++ b/src/black/files.py
@@ -20,7 +20,11 @@
 from mypy_extensions import mypyc_attr
 from pathspec import PathSpec
 from pathspec.patterns.gitwildmatch import GitWildMatchPatternError
-import tomli
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
 
 from black.output import err
 from black.report import Report
@@ -97,10 +101,10 @@ def find_pyproject_toml(path_search_start: Tuple[str, ...]) -> Optional[str]:
 def parse_pyproject_toml(path_config: str) -> Dict[str, Any]:
     """Parse a pyproject toml file, pulling out relevant parts for Black
 
-    If parsing fails, will raise a tomli.TOMLDecodeError
+    If parsing fails, will raise a tomllib.TOMLDecodeError
     """
     with open(path_config, "rb") as f:
-        pyproject_toml = tomli.load(f)
+        pyproject_toml = tomllib.load(f)
     config = pyproject_toml.get("tool", {}).get("black", {})
     return {k.replace("--", "").replace("-", "_"): v for k, v in config.items()}
 

From 9ce3c806e402abdc8a5383df0f0d1f82d930bd2e Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Mon, 14 Mar 2022 19:41:46 -0400
Subject: [PATCH 0488/1034] Bump mypy, flake8, and pre-commit-hooks in
 pre-commit (GH-2922)

---
 .pre-commit-config.yaml | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index af3c5c2b96e..b96bc62fe17 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -31,8 +31,8 @@ repos:
         files: '(CHANGES\.md|the_basics\.md)$'
         additional_dependencies: *version_check_dependencies
 
-  - repo: https://gitlab.com/pycqa/flake8
-    rev: 3.9.2
+  - repo: https://github.com/pycqa/flake8
+    rev: 4.0.1
     hooks:
       - id: flake8
         additional_dependencies:
@@ -41,7 +41,7 @@ repos:
           - flake8-simplify
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v0.910-1
+    rev: v0.940
     hooks:
       - id: mypy
         exclude: ^docs/conf.py
@@ -60,7 +60,7 @@ repos:
         exclude: \.github/workflows/diff_shades\.yml
 
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.0.1
+    rev: v4.1.0
     hooks:
       - id: end-of-file-fixer
       - id: trailing-whitespace

From a57ab326b20b720518ab6f513bd0f8ba357d8d86 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Tue, 15 Mar 2022 15:57:59 -0400
Subject: [PATCH 0489/1034] Farewell black-primer, it was nice knowing you
 (#2924)

Enjoy your retirement at https://github.com/cooperlees/black-primer
---
 CHANGES.md                           |   2 +
 docs/contributing/gauging_changes.md |   6 -
 mypy.ini                             |   8 -
 setup.py                             |   4 +-
 src/black_primer/__init__.py         |   0
 src/black_primer/cli.py              | 195 ------------
 src/black_primer/lib.py              | 423 ---------------------------
 src/black_primer/primer.json         | 181 ------------
 tests/test_format.py                 |   3 -
 tests/test_primer.py                 | 291 ------------------
 10 files changed, 3 insertions(+), 1110 deletions(-)
 delete mode 100644 src/black_primer/__init__.py
 delete mode 100644 src/black_primer/cli.py
 delete mode 100644 src/black_primer/lib.py
 delete mode 100644 src/black_primer/primer.json
 delete mode 100644 tests/test_primer.py

diff --git a/CHANGES.md b/CHANGES.md
index edca0dcdad4..da51e94342c 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -50,6 +50,8 @@
 
 - On Python 3.11 and newer, use the standard library's `tomllib` instead of `tomli`
   (#2903)
+- `black-primer`, the deprecated internal devtool, has been removed and copied to a
+  [separate repository](https://github.com/cooperlees/black-primer) (#2924)
 
 ### Parser
 
diff --git a/docs/contributing/gauging_changes.md b/docs/contributing/gauging_changes.md
index 59c40eb3909..f28e81120b3 100644
--- a/docs/contributing/gauging_changes.md
+++ b/docs/contributing/gauging_changes.md
@@ -7,12 +7,6 @@ It's recommended you evaluate the quantifiable changes your _Black_ formatting
 modification causes before submitting a PR. Think about if the change seems disruptive
 enough to cause frustration to projects that are already "black formatted".
 
-## black-primer
-
-`black-primer` is an obsolete tool (now replaced with `diff-shades`) that was used to
-gauge the impact of changes in _Black_ on open-source code. It is no longer used
-internally and will be removed from the _Black_ repository in the future.
-
 ## diff-shades
 
 diff-shades is a tool that runs _Black_ across a list of Git cloneable OSS projects
diff --git a/mypy.ini b/mypy.ini
index cfceaa3ee86..3bb92a659ff 100644
--- a/mypy.ini
+++ b/mypy.ini
@@ -39,11 +39,3 @@ cache_dir=/dev/null
 # The following is because of `patch_click()`. Remove when
 # we drop Python 3.6 support.
 warn_unused_ignores=False
-
-[mypy-black_primer.*]
-# Until we're not supporting 3.6 primer needs this
-disallow_any_generics=False
-
-[mypy-tests.test_primer]
-# Until we're not supporting 3.6 primer needs this
-disallow_any_generics=False
diff --git a/setup.py b/setup.py
index 6b5b957e96f..e23a58c411c 100644
--- a/setup.py
+++ b/setup.py
@@ -58,7 +58,7 @@ def find_python_files(base: Path) -> List[Path]:
         "black/__main__.py",
     ]
     discovered = []
-    # black-primer and blackd have no good reason to be compiled.
+    # There's no good reason for blackd to be compiled.
     discovered.extend(find_python_files(src / "black"))
     discovered.extend(find_python_files(src / "blib2to3"))
     mypyc_targets = [
@@ -92,7 +92,6 @@ def find_python_files(base: Path) -> List[Path]:
     package_data={
         "blib2to3": ["*.txt"],
         "black": ["py.typed"],
-        "black_primer": ["primer.json"],
     },
     python_requires=">=3.6.2",
     zip_safe=False,
@@ -132,7 +131,6 @@ def find_python_files(base: Path) -> List[Path]:
         "console_scripts": [
             "black=black:patched_main",
             "blackd=blackd:patched_main [d]",
-            "black-primer=black_primer.cli:main",
         ]
     },
 )
diff --git a/src/black_primer/__init__.py b/src/black_primer/__init__.py
deleted file mode 100644
index e69de29bb2d..00000000000
diff --git a/src/black_primer/cli.py b/src/black_primer/cli.py
deleted file mode 100644
index 8524b59a632..00000000000
--- a/src/black_primer/cli.py
+++ /dev/null
@@ -1,195 +0,0 @@
-# coding=utf8
-
-import asyncio
-import json
-import logging
-import sys
-from datetime import datetime
-from pathlib import Path
-from shutil import rmtree, which
-from tempfile import gettempdir
-from typing import Any, List, Optional, Union
-
-import click
-
-from black_primer import lib
-
-# If our environment has uvloop installed lets use it
-try:
-    import uvloop
-
-    uvloop.install()
-except ImportError:
-    pass
-
-
-DEFAULT_CONFIG = Path(__file__).parent / "primer.json"
-_timestamp = datetime.now().strftime("%Y%m%d%H%M%S")
-DEFAULT_WORKDIR = Path(gettempdir()) / f"primer.{_timestamp}"
-LOG = logging.getLogger(__name__)
-
-
-def _handle_debug(
-    ctx: Optional[click.core.Context],
-    param: Optional[Union[click.core.Option, click.core.Parameter]],
-    debug: Union[bool, int, str],
-) -> Union[bool, int, str]:
-    """Turn on debugging if asked otherwise INFO default"""
-    log_level = logging.DEBUG if debug else logging.INFO
-    logging.basicConfig(
-        format="[%(asctime)s] %(levelname)s: %(message)s (%(filename)s:%(lineno)d)",
-        level=log_level,
-    )
-    return debug
-
-
-def load_projects(config_path: Path) -> List[str]:
-    with open(config_path) as config:
-        return sorted(json.load(config)["projects"].keys())
-
-
-# Unfortunately does import time file IO - but appears to be the only
-# way to get `black-primer --help` to show projects list
-DEFAULT_PROJECTS = load_projects(DEFAULT_CONFIG)
-
-
-def _projects_callback(
-    ctx: click.core.Context,
-    param: Optional[Union[click.core.Option, click.core.Parameter]],
-    projects: str,
-) -> List[str]:
-    requested_projects = set(projects.split(","))
-    available_projects = set(
-        DEFAULT_PROJECTS
-        if str(DEFAULT_CONFIG) == ctx.params["config"]
-        else load_projects(ctx.params["config"])
-    )
-
-    unavailable = requested_projects - available_projects
-    if unavailable:
-        LOG.error(f"Projects not found: {unavailable}. Available: {available_projects}")
-
-    return sorted(requested_projects & available_projects)
-
-
-async def async_main(
-    config: str,
-    debug: bool,
-    keep: bool,
-    long_checkouts: bool,
-    no_diff: bool,
-    projects: List[str],
-    rebase: bool,
-    workdir: str,
-    workers: int,
-) -> int:
-    work_path = Path(workdir)
-    if not work_path.exists():
-        LOG.debug(f"Creating {work_path}")
-        work_path.mkdir()
-
-    if not which("black"):
-        LOG.error("Can not find 'black' executable in PATH. No point in running")
-        return -1
-
-    try:
-        ret_val = await lib.process_queue(
-            config,
-            work_path,
-            workers,
-            projects,
-            keep,
-            long_checkouts,
-            rebase,
-            no_diff,
-        )
-        return int(ret_val)
-
-    finally:
-        if not keep and work_path.exists():
-            LOG.debug(f"Removing {work_path}")
-            rmtree(work_path, onerror=lib.handle_PermissionError)
-
-
-@click.command(context_settings={"help_option_names": ["-h", "--help"]})
-@click.option(
-    "-c",
-    "--config",
-    default=str(DEFAULT_CONFIG),
-    type=click.Path(exists=True),
-    show_default=True,
-    help="JSON config file path",
-    # Eager - because config path is used by other callback options
-    is_eager=True,
-)
-@click.option(
-    "--debug",
-    is_flag=True,
-    callback=_handle_debug,
-    show_default=True,
-    help="Turn on debug logging",
-)
-@click.option(
-    "-k",
-    "--keep",
-    is_flag=True,
-    show_default=True,
-    help="Keep workdir + repos post run",
-)
-@click.option(
-    "-L",
-    "--long-checkouts",
-    is_flag=True,
-    show_default=True,
-    help="Pull big projects to test",
-)
-@click.option(
-    "--no-diff",
-    is_flag=True,
-    show_default=True,
-    help="Disable showing source file changes in black output",
-)
-@click.option(
-    "--projects",
-    default=",".join(DEFAULT_PROJECTS),
-    callback=_projects_callback,
-    show_default=True,
-    help="Comma separated list of projects to run",
-)
-@click.option(
-    "-R",
-    "--rebase",
-    is_flag=True,
-    show_default=True,
-    help="Rebase project if already checked out",
-)
-@click.option(
-    "-w",
-    "--workdir",
-    default=str(DEFAULT_WORKDIR),
-    type=click.Path(exists=False),
-    show_default=True,
-    help="Directory path for repo checkouts",
-)
-@click.option(
-    "-W",
-    "--workers",
-    default=2,
-    type=int,
-    show_default=True,
-    help="Number of parallel worker coroutines",
-)
-@click.pass_context
-def main(ctx: click.core.Context, **kwargs: Any) -> None:
-    """primer - prime projects for blackening... 🏴"""
-    LOG.debug(f"Starting {sys.argv[0]}")
-    # TODO: Change to asyncio.run when Black >= 3.7 only
-    loop = asyncio.get_event_loop()
-    try:
-        ctx.exit(loop.run_until_complete(async_main(**kwargs)))
-    finally:
-        loop.close()
-
-
-if __name__ == "__main__":  # pragma: nocover
-    main()
diff --git a/src/black_primer/lib.py b/src/black_primer/lib.py
deleted file mode 100644
index 13724f431ce..00000000000
--- a/src/black_primer/lib.py
+++ /dev/null
@@ -1,423 +0,0 @@
-import asyncio
-import errno
-import json
-import logging
-import os
-import stat
-import sys
-from functools import partial
-from pathlib import Path
-from platform import system
-from shutil import rmtree, which
-from subprocess import CalledProcessError
-from sys import version_info
-from tempfile import TemporaryDirectory
-from typing import (
-    Any,
-    Callable,
-    Dict,
-    List,
-    NamedTuple,
-    Optional,
-    Sequence,
-    Tuple,
-    Union,
-)
-from urllib.parse import urlparse
-
-import click
-
-
-TEN_MINUTES_SECONDS = 600
-WINDOWS = system() == "Windows"
-BLACK_BINARY = "black.exe" if WINDOWS else "black"
-GIT_BINARY = "git.exe" if WINDOWS else "git"
-LOG = logging.getLogger(__name__)
-
-
-# Windows needs a ProactorEventLoop if you want to exec subprocesses
-# Starting with 3.8 this is the default - can remove when Black >= 3.8
-# mypy only respects sys.platform if directly in the evaluation
-# https://mypy.readthedocs.io/en/latest/common_issues.html#python-version-and-system-platform-checks  # noqa: B950
-if sys.platform == "win32":
-    asyncio.set_event_loop(asyncio.ProactorEventLoop())
-
-
-class Results(NamedTuple):
-    stats: Dict[str, int] = {}
-    failed_projects: Dict[str, CalledProcessError] = {}
-
-
-async def _gen_check_output(
-    cmd: Sequence[str],
-    timeout: float = TEN_MINUTES_SECONDS,
-    env: Optional[Dict[str, str]] = None,
-    cwd: Optional[Path] = None,
-    stdin: Optional[bytes] = None,
-) -> Tuple[bytes, bytes]:
-    process = await asyncio.create_subprocess_exec(
-        *cmd,
-        stdin=asyncio.subprocess.PIPE,
-        stdout=asyncio.subprocess.PIPE,
-        stderr=asyncio.subprocess.STDOUT,
-        env=env,
-        cwd=cwd,
-    )
-    try:
-        (stdout, stderr) = await asyncio.wait_for(process.communicate(stdin), timeout)
-    except asyncio.TimeoutError:
-        process.kill()
-        await process.wait()
-        raise
-
-    # A non-optional timeout was supplied to asyncio.wait_for, guaranteeing
-    # a timeout or completed process.  A terminated Python process will have a
-    # non-empty returncode value.
-    assert process.returncode is not None
-
-    if process.returncode != 0:
-        cmd_str = " ".join(cmd)
-        raise CalledProcessError(
-            process.returncode, cmd_str, output=stdout, stderr=stderr
-        )
-
-    return (stdout, stderr)
-
-
-def analyze_results(project_count: int, results: Results) -> int:
-    failed_pct = round(((results.stats["failed"] / project_count) * 100), 2)
-    success_pct = round(((results.stats["success"] / project_count) * 100), 2)
-
-    if results.failed_projects:
-        click.secho("\nFailed projects:\n", bold=True)
-
-    for project_name, project_cpe in results.failed_projects.items():
-        print(f"## {project_name}:")
-        print(f" - Returned {project_cpe.returncode}")
-        if project_cpe.stderr:
-            print(f" - stderr:\n{project_cpe.stderr.decode('utf8')}")
-        if project_cpe.stdout:
-            print(f" - stdout:\n{project_cpe.stdout.decode('utf8')}")
-        print("")
-
-    click.secho("-- primer results 📊 --\n", bold=True)
-    click.secho(
-        f"{results.stats['success']} / {project_count} succeeded ({success_pct}%) ✅",
-        bold=True,
-        fg="green",
-    )
-    click.secho(
-        f"{results.stats['failed']} / {project_count} FAILED ({failed_pct}%) 💩",
-        bold=bool(results.stats["failed"]),
-        fg="red",
-    )
-    s = "" if results.stats["disabled"] == 1 else "s"
-    click.echo(f" - {results.stats['disabled']} project{s} disabled by config")
-    s = "" if results.stats["wrong_py_ver"] == 1 else "s"
-    click.echo(
-        f" - {results.stats['wrong_py_ver']} project{s} skipped due to Python version"
-    )
-    click.echo(
-        f" - {results.stats['skipped_long_checkout']} skipped due to long checkout"
-    )
-
-    if results.failed_projects:
-        failed = ", ".join(results.failed_projects.keys())
-        click.secho(f"\nFailed projects: {failed}\n", bold=True)
-
-    return results.stats["failed"]
-
-
-def _flatten_cli_args(cli_args: List[Union[Sequence[str], str]]) -> List[str]:
-    """Allow a user to put long arguments into a list of strs
-    to make the JSON human readable"""
-    flat_args = []
-    for arg in cli_args:
-        if isinstance(arg, str):
-            flat_args.append(arg)
-            continue
-
-        args_as_str = "".join(arg)
-        flat_args.append(args_as_str)
-
-    return flat_args
-
-
-async def black_run(
-    project_name: str,
-    repo_path: Optional[Path],
-    project_config: Dict[str, Any],
-    results: Results,
-    no_diff: bool = False,
-) -> None:
-    """Run Black and record failures"""
-    if not repo_path:
-        results.stats["failed"] += 1
-        results.failed_projects[project_name] = CalledProcessError(
-            69, [], f"{project_name} has no repo_path: {repo_path}".encode(), b""
-        )
-        return
-
-    stdin_test = project_name.upper() == "STDIN"
-    cmd = [str(which(BLACK_BINARY))]
-    if "cli_arguments" in project_config and project_config["cli_arguments"]:
-        cmd.extend(_flatten_cli_args(project_config["cli_arguments"]))
-    cmd.append("--check")
-    if not no_diff:
-        cmd.append("--diff")
-
-    # Workout if we should read in a python file or search from cwd
-    stdin = None
-    if stdin_test:
-        cmd.append("-")
-        stdin = repo_path.read_bytes()
-    elif "base_path" in project_config:
-        cmd.append(project_config["base_path"])
-    else:
-        cmd.append(".")
-
-    timeout = (
-        project_config["timeout_seconds"]
-        if "timeout_seconds" in project_config
-        else TEN_MINUTES_SECONDS
-    )
-    with TemporaryDirectory() as tmp_path:
-        # Prevent reading top-level user configs by manipulating environment variables
-        env = {
-            **os.environ,
-            "XDG_CONFIG_HOME": tmp_path,  # Unix-like
-            "USERPROFILE": tmp_path,  # Windows (changes `Path.home()` output)
-        }
-
-        cwd_path = repo_path.parent if stdin_test else repo_path
-        try:
-            LOG.debug(f"Running black for {project_name}: {' '.join(cmd)}")
-            _stdout, _stderr = await _gen_check_output(
-                cmd, cwd=cwd_path, env=env, stdin=stdin, timeout=timeout
-            )
-        except asyncio.TimeoutError:
-            results.stats["failed"] += 1
-            LOG.error(f"Running black for {repo_path} timed out ({cmd})")
-        except CalledProcessError as cpe:
-            # TODO: Tune for smarter for higher signal
-            # If any other return value than 1 we raise - can disable project in config
-            if cpe.returncode == 1:
-                if not project_config["expect_formatting_changes"]:
-                    results.stats["failed"] += 1
-                    results.failed_projects[repo_path.name] = cpe
-                else:
-                    results.stats["success"] += 1
-                return
-            elif cpe.returncode > 1:
-                results.stats["failed"] += 1
-                results.failed_projects[repo_path.name] = cpe
-                return
-
-            LOG.error(f"Unknown error with {repo_path}")
-            raise
-
-    # If we get here and expect formatting changes something is up
-    if project_config["expect_formatting_changes"]:
-        results.stats["failed"] += 1
-        results.failed_projects[repo_path.name] = CalledProcessError(
-            0, cmd, b"Expected formatting changes but didn't get any!", b""
-        )
-        return
-
-    results.stats["success"] += 1
-
-
-async def git_checkout_or_rebase(
-    work_path: Path,
-    project_config: Dict[str, Any],
-    rebase: bool = False,
-    *,
-    depth: int = 1,
-) -> Optional[Path]:
-    """git Clone project or rebase"""
-    git_bin = str(which(GIT_BINARY))
-    if not git_bin:
-        LOG.error("No git binary found")
-        return None
-
-    repo_url_parts = urlparse(project_config["git_clone_url"])
-    path_parts = repo_url_parts.path[1:].split("/", maxsplit=1)
-
-    repo_path: Path = work_path / path_parts[1].replace(".git", "")
-    cmd = [git_bin, "clone", "--depth", str(depth), project_config["git_clone_url"]]
-    cwd = work_path
-    if repo_path.exists() and rebase:
-        cmd = [git_bin, "pull", "--rebase"]
-        cwd = repo_path
-    elif repo_path.exists():
-        return repo_path
-
-    try:
-        _stdout, _stderr = await _gen_check_output(cmd, cwd=cwd)
-    except (asyncio.TimeoutError, CalledProcessError) as e:
-        LOG.error(f"Unable to git clone / pull {project_config['git_clone_url']}: {e}")
-        return None
-
-    return repo_path
-
-
-def handle_PermissionError(
-    func: Callable[..., None], path: Path, exc: Tuple[Any, Any, Any]
-) -> None:
-    """
-    Handle PermissionError during shutil.rmtree.
-
-    This checks if the erroring function is either 'os.rmdir' or 'os.unlink', and that
-    the error was EACCES (i.e. Permission denied). If true, the path is set writable,
-    readable, and executable by everyone. Finally, it tries the error causing delete
-    operation again.
-
-    If the check is false, then the original error will be reraised as this function
-    can't handle it.
-    """
-    excvalue = exc[1]
-    LOG.debug(f"Handling {excvalue} from {func.__name__}... ")
-    if func in (os.rmdir, os.unlink) and excvalue.errno == errno.EACCES:
-        LOG.debug(f"Setting {path} writable, readable, and executable by everyone... ")
-        os.chmod(path, stat.S_IRWXU | stat.S_IRWXG | stat.S_IRWXO)  # chmod 0777
-        func(path)  # Try the error causing delete operation again
-    else:
-        raise
-
-
-async def load_projects_queue(
-    config_path: Path,
-    projects_to_run: List[str],
-) -> Tuple[Dict[str, Any], asyncio.Queue]:
-    """Load project config and fill queue with all the project names"""
-    with config_path.open("r") as cfp:
-        config = json.load(cfp)
-
-    # TODO: Offer more options here
-    # e.g. Run on X random packages etc.
-    queue: asyncio.Queue = asyncio.Queue(maxsize=len(projects_to_run))
-    for project in projects_to_run:
-        await queue.put(project)
-
-    return config, queue
-
-
-async def project_runner(
-    idx: int,
-    config: Dict[str, Any],
-    queue: asyncio.Queue,
-    work_path: Path,
-    results: Results,
-    long_checkouts: bool = False,
-    rebase: bool = False,
-    keep: bool = False,
-    no_diff: bool = False,
-) -> None:
-    """Check out project and run Black on it + record result"""
-    loop = asyncio.get_event_loop()
-    py_version = f"{version_info[0]}.{version_info[1]}"
-    while True:
-        try:
-            project_name = queue.get_nowait()
-        except asyncio.QueueEmpty:
-            LOG.debug(f"project_runner {idx} exiting")
-            return
-        LOG.debug(f"worker {idx} working on {project_name}")
-
-        project_config = config["projects"][project_name]
-
-        # Check if disabled by config
-        if "disabled" in project_config and project_config["disabled"]:
-            results.stats["disabled"] += 1
-            LOG.info(f"Skipping {project_name} as it's disabled via config")
-            continue
-
-        # Check if we should run on this version of Python
-        if (
-            "all" not in project_config["py_versions"]
-            and py_version not in project_config["py_versions"]
-        ):
-            results.stats["wrong_py_ver"] += 1
-            LOG.debug(f"Skipping {project_name} as it's not enabled for {py_version}")
-            continue
-
-        # Check if we're doing big projects / long checkouts
-        if not long_checkouts and project_config["long_checkout"]:
-            results.stats["skipped_long_checkout"] += 1
-            LOG.debug(f"Skipping {project_name} as it's configured as a long checkout")
-            continue
-
-        repo_path: Optional[Path] = Path(__file__)
-        stdin_project = project_name.upper() == "STDIN"
-        if not stdin_project:
-            repo_path = await git_checkout_or_rebase(work_path, project_config, rebase)
-            if not repo_path:
-                continue
-        await black_run(project_name, repo_path, project_config, results, no_diff)
-
-        if not keep and not stdin_project:
-            LOG.debug(f"Removing {repo_path}")
-            rmtree_partial = partial(
-                rmtree, path=repo_path, onerror=handle_PermissionError
-            )
-            await loop.run_in_executor(None, rmtree_partial)
-
-        LOG.info(f"Finished {project_name}")
-
-
-async def process_queue(
-    config_file: str,
-    work_path: Path,
-    workers: int,
-    projects_to_run: List[str],
-    keep: bool = False,
-    long_checkouts: bool = False,
-    rebase: bool = False,
-    no_diff: bool = False,
-) -> int:
-    """
-    Process the queue with X workers and evaluate results
-    - Success is guaged via the config "expect_formatting_changes"
-
-    Integer return equals the number of failed projects
-    """
-    results = Results()
-    results.stats["disabled"] = 0
-    results.stats["failed"] = 0
-    results.stats["skipped_long_checkout"] = 0
-    results.stats["success"] = 0
-    results.stats["wrong_py_ver"] = 0
-
-    config, queue = await load_projects_queue(Path(config_file), projects_to_run)
-    project_count = queue.qsize()
-    s = "" if project_count == 1 else "s"
-    LOG.info(f"{project_count} project{s} to run Black over")
-    if project_count < 1:
-        return -1
-
-    s = "" if workers == 1 else "s"
-    LOG.debug(f"Using {workers} parallel worker{s} to run Black")
-    # Wait until we finish running all the projects before analyzing
-    await asyncio.gather(
-        *[
-            project_runner(
-                i,
-                config,
-                queue,
-                work_path,
-                results,
-                long_checkouts,
-                rebase,
-                keep,
-                no_diff,
-            )
-            for i in range(workers)
-        ]
-    )
-
-    LOG.info("Analyzing results")
-    return analyze_results(project_count, results)
-
-
-if __name__ == "__main__":  # pragma: nocover
-    raise NotImplementedError("lib is a library, funnily enough.")
diff --git a/src/black_primer/primer.json b/src/black_primer/primer.json
deleted file mode 100644
index a6bfd4a2fec..00000000000
--- a/src/black_primer/primer.json
+++ /dev/null
@@ -1,181 +0,0 @@
-{
-  "configuration_format_version": 20210815,
-  "projects": {
-    "STDIN": {
-      "cli_arguments": ["--experimental-string-processing"],
-      "expect_formatting_changes": false,
-      "git_clone_url": "",
-      "long_checkout": false,
-      "py_versions": ["all"]
-    },
-    "aioexabgp": {
-      "cli_arguments": ["--experimental-string-processing"],
-      "expect_formatting_changes": false,
-      "git_clone_url": "https://github.com/cooperlees/aioexabgp.git",
-      "long_checkout": false,
-      "py_versions": ["all"]
-    },
-    "attrs": {
-      "cli_arguments": ["--experimental-string-processing"],
-      "expect_formatting_changes": true,
-      "git_clone_url": "https://github.com/python-attrs/attrs.git",
-      "long_checkout": false,
-      "py_versions": ["all"]
-    },
-    "bandersnatch": {
-      "cli_arguments": ["--experimental-string-processing"],
-      "expect_formatting_changes": true,
-      "git_clone_url": "https://github.com/pypa/bandersnatch.git",
-      "long_checkout": false,
-      "py_versions": ["all"]
-    },
-    "channels": {
-      "cli_arguments": ["--experimental-string-processing"],
-      "expect_formatting_changes": true,
-      "git_clone_url": "https://github.com/django/channels.git",
-      "long_checkout": false,
-      "py_versions": ["all"]
-    },
-    "cpython": {
-      "disabled": true,
-      "disabled_reason": "To big / slow for GitHub Actions but handy to keep config to use manually or in some other CI in the future",
-      "base_path": "Lib",
-      "cli_arguments": [
-        "--experimental-string-processing",
-        "--extend-exclude",
-        [
-          "Lib/lib2to3/tests/data/different_encoding.py",
-          "|Lib/lib2to3/tests/data/false_encoding.py",
-          "|Lib/lib2to3/tests/data/py2_test_grammar.py",
-          "|Lib/test/bad_coding.py",
-          "|Lib/test/bad_coding2.py",
-          "|Lib/test/badsyntax_3131.py",
-          "|Lib/test/badsyntax_pep3120.py",
-          "|Lib/test/test_base64.py",
-          "|Lib/test/test_exceptions.py",
-          "|Lib/test/test_grammar.py",
-          "|Lib/test/test_named_expressions.py",
-          "|Lib/test/test_patma.py",
-          "|Lib/test/test_tokenize.py",
-          "|Lib/test/test_xml_etree.py",
-          "|Lib/traceback.py"
-        ]
-      ],
-      "expect_formatting_changes": true,
-      "git_clone_url": "https://github.com/python/cpython.git",
-      "long_checkout": false,
-      "py_versions": ["3.9", "3.10"],
-      "timeout_seconds": 900
-    },
-    "django": {
-      "cli_arguments": [
-        "--experimental-string-processing",
-        "--skip-string-normalization",
-        "--extend-exclude",
-        "/((docs|scripts)/|django/forms/models.py|tests/gis_tests/test_spatialrefsys.py|tests/test_runner_apps/tagged/tests_syntax_error.py)"
-      ],
-      "expect_formatting_changes": true,
-      "git_clone_url": "https://github.com/django/django.git",
-      "long_checkout": false,
-      "py_versions": ["3.8", "3.9", "3.10"]
-    },
-    "flake8-bugbear": {
-      "cli_arguments": ["--experimental-string-processing"],
-      "expect_formatting_changes": true,
-      "git_clone_url": "https://github.com/PyCQA/flake8-bugbear.git",
-      "long_checkout": false,
-      "py_versions": ["all"]
-    },
-    "hypothesis": {
-      "cli_arguments": ["--experimental-string-processing"],
-      "expect_formatting_changes": true,
-      "git_clone_url": "https://github.com/HypothesisWorks/hypothesis.git",
-      "long_checkout": false,
-      "py_versions": ["3.8", "3.9", "3.10"]
-    },
-    "pandas": {
-      "cli_arguments": ["--experimental-string-processing"],
-      "expect_formatting_changes": true,
-      "git_clone_url": "https://github.com/pandas-dev/pandas.git",
-      "long_checkout": false,
-      "py_versions": ["all"]
-    },
-    "pillow": {
-      "cli_arguments": ["--experimental-string-processing"],
-      "expect_formatting_changes": true,
-      "git_clone_url": "https://github.com/python-pillow/Pillow.git",
-      "long_checkout": false,
-      "py_versions": ["all"]
-    },
-    "poetry": {
-      "cli_arguments": ["--experimental-string-processing"],
-      "expect_formatting_changes": false,
-      "git_clone_url": "https://github.com/python-poetry/poetry.git",
-      "long_checkout": false,
-      "py_versions": ["all"]
-    },
-    "pyanalyze": {
-      "cli_arguments": ["--experimental-string-processing"],
-      "expect_formatting_changes": false,
-      "git_clone_url": "https://github.com/quora/pyanalyze.git",
-      "long_checkout": false,
-      "py_versions": ["all"]
-    },
-    "pyramid": {
-      "cli_arguments": ["--experimental-string-processing"],
-      "expect_formatting_changes": true,
-      "git_clone_url": "https://github.com/Pylons/pyramid.git",
-      "long_checkout": false,
-      "py_versions": ["all"]
-    },
-    "ptr": {
-      "cli_arguments": ["--experimental-string-processing"],
-      "expect_formatting_changes": false,
-      "git_clone_url": "https://github.com/facebookincubator/ptr.git",
-      "long_checkout": false,
-      "py_versions": ["all"]
-    },
-    "pytest": {
-      "cli_arguments": ["--experimental-string-processing"],
-      "expect_formatting_changes": true,
-      "git_clone_url": "https://github.com/pytest-dev/pytest.git",
-      "long_checkout": false,
-      "py_versions": ["all"]
-    },
-    "scikit-lego": {
-      "cli_arguments": ["--experimental-string-processing"],
-      "expect_formatting_changes": true,
-      "git_clone_url": "https://github.com/koaning/scikit-lego",
-      "long_checkout": false,
-      "py_versions": ["all"]
-    },
-    "tox": {
-      "cli_arguments": ["--experimental-string-processing"],
-      "expect_formatting_changes": true,
-      "git_clone_url": "https://github.com/tox-dev/tox.git",
-      "long_checkout": false,
-      "py_versions": ["all"]
-    },
-    "typeshed": {
-      "cli_arguments": ["--experimental-string-processing"],
-      "expect_formatting_changes": true,
-      "git_clone_url": "https://github.com/python/typeshed.git",
-      "long_checkout": false,
-      "py_versions": ["all"]
-    },
-    "virtualenv": {
-      "cli_arguments": ["--experimental-string-processing"],
-      "expect_formatting_changes": true,
-      "git_clone_url": "https://github.com/pypa/virtualenv.git",
-      "long_checkout": false,
-      "py_versions": ["all"]
-    },
-    "warehouse": {
-      "cli_arguments": ["--experimental-string-processing"],
-      "expect_formatting_changes": true,
-      "git_clone_url": "https://github.com/pypa/warehouse.git",
-      "long_checkout": false,
-      "py_versions": ["all"]
-    }
-  }
-}
diff --git a/tests/test_format.py b/tests/test_format.py
index 04eda43d5cf..269bbacd249 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -103,8 +103,6 @@
     "src/black/strings.py",
     "src/black/trans.py",
     "src/blackd/__init__.py",
-    "src/black_primer/cli.py",
-    "src/black_primer/lib.py",
     "src/blib2to3/pygram.py",
     "src/blib2to3/pytree.py",
     "src/blib2to3/pgen2/conv.py",
@@ -119,7 +117,6 @@
     "tests/test_black.py",
     "tests/test_blackd.py",
     "tests/test_format.py",
-    "tests/test_primer.py",
     "tests/optional.py",
     "tests/util.py",
     "tests/conftest.py",
diff --git a/tests/test_primer.py b/tests/test_primer.py
deleted file mode 100644
index 0a9d2aec495..00000000000
--- a/tests/test_primer.py
+++ /dev/null
@@ -1,291 +0,0 @@
-#!/usr/bin/env python3
-
-import asyncio
-import sys
-import unittest
-from contextlib import contextmanager
-from copy import deepcopy
-from io import StringIO
-from os import getpid
-from pathlib import Path
-from platform import system
-from pytest import LogCaptureFixture
-from subprocess import CalledProcessError
-from tempfile import TemporaryDirectory, gettempdir
-from typing import Any, Callable, Iterator, List, Tuple, TypeVar
-from unittest.mock import Mock, patch
-
-from click.testing import CliRunner
-
-from black_primer import cli, lib
-
-
-EXPECTED_ANALYSIS_OUTPUT = """\
-
-Failed projects:
-
-## black:
- - Returned 69
- - stdout:
-Black didn't work
-
--- primer results 📊 --
-
-68 / 69 succeeded (98.55%) ✅
-1 / 69 FAILED (1.45%) 💩
- - 0 projects disabled by config
- - 0 projects skipped due to Python version
- - 0 skipped due to long checkout
-
-Failed projects: black
-
-"""
-FAKE_PROJECT_CONFIG = {
-    "cli_arguments": ["--unittest"],
-    "expect_formatting_changes": False,
-    "git_clone_url": "https://github.com/psf/black.git",
-}
-
-
-@contextmanager
-def capture_stdout(
-    command: Callable[..., Any], *args: Any, **kwargs: Any
-) -> Iterator[str]:
-    old_stdout, sys.stdout = sys.stdout, StringIO()
-    try:
-        command(*args, **kwargs)
-        sys.stdout.seek(0)
-        yield sys.stdout.read()
-    finally:
-        sys.stdout = old_stdout
-
-
-@contextmanager
-def event_loop() -> Iterator[None]:
-    policy = asyncio.get_event_loop_policy()
-    loop = policy.new_event_loop()
-    asyncio.set_event_loop(loop)
-    if sys.platform == "win32":
-        asyncio.set_event_loop(asyncio.ProactorEventLoop())
-    try:
-        yield
-    finally:
-        loop.close()
-
-
-async def raise_subprocess_error_1(*args: Any, **kwargs: Any) -> None:
-    raise CalledProcessError(1, ["unittest", "error"], b"", b"")
-
-
-async def raise_subprocess_error_123(*args: Any, **kwargs: Any) -> None:
-    raise CalledProcessError(123, ["unittest", "error"], b"", b"")
-
-
-async def return_false(*args: Any, **kwargs: Any) -> bool:
-    return False
-
-
-async def return_subproccess_output(*args: Any, **kwargs: Any) -> Tuple[bytes, bytes]:
-    return (b"stdout", b"stderr")
-
-
-async def return_zero(*args: Any, **kwargs: Any) -> int:
-    return 0
-
-
-if sys.version_info >= (3, 9):
-    T = TypeVar("T")
-    Q = asyncio.Queue[T]
-else:
-    T = Any
-    Q = asyncio.Queue
-
-
-def collect(queue: Q) -> List[T]:
-    ret = []
-    while True:
-        try:
-            item = queue.get_nowait()
-            ret.append(item)
-        except asyncio.QueueEmpty:
-            return ret
-
-
-class PrimerLibTests(unittest.TestCase):
-    def test_analyze_results(self) -> None:
-        fake_results = lib.Results(
-            {
-                "disabled": 0,
-                "failed": 1,
-                "skipped_long_checkout": 0,
-                "success": 68,
-                "wrong_py_ver": 0,
-            },
-            {"black": CalledProcessError(69, ["black"], b"Black didn't work", b"")},
-        )
-        with capture_stdout(lib.analyze_results, 69, fake_results) as analyze_stdout:
-            self.assertEqual(EXPECTED_ANALYSIS_OUTPUT, analyze_stdout)
-
-    @event_loop()
-    def test_black_run(self) -> None:
-        """Pretend to run Black to ensure we cater for all scenarios"""
-        loop = asyncio.get_event_loop()
-        project_name = "unittest"
-        repo_path = Path(gettempdir())
-        project_config = deepcopy(FAKE_PROJECT_CONFIG)
-        results = lib.Results({"failed": 0, "success": 0}, {})
-
-        # Test a successful Black run
-        with patch("black_primer.lib._gen_check_output", return_subproccess_output):
-            loop.run_until_complete(
-                lib.black_run(project_name, repo_path, project_config, results)
-            )
-        self.assertEqual(1, results.stats["success"])
-        self.assertFalse(results.failed_projects)
-
-        # Test a fail based on expecting formatting changes but not getting any
-        project_config["expect_formatting_changes"] = True
-        results = lib.Results({"failed": 0, "success": 0}, {})
-        with patch("black_primer.lib._gen_check_output", return_subproccess_output):
-            loop.run_until_complete(
-                lib.black_run(project_name, repo_path, project_config, results)
-            )
-        self.assertEqual(1, results.stats["failed"])
-        self.assertTrue(results.failed_projects)
-
-        # Test a fail based on returning 1 and not expecting formatting changes
-        project_config["expect_formatting_changes"] = False
-        results = lib.Results({"failed": 0, "success": 0}, {})
-        with patch("black_primer.lib._gen_check_output", raise_subprocess_error_1):
-            loop.run_until_complete(
-                lib.black_run(project_name, repo_path, project_config, results)
-            )
-        self.assertEqual(1, results.stats["failed"])
-        self.assertTrue(results.failed_projects)
-
-        # Test a formatting error based on returning 123
-        with patch("black_primer.lib._gen_check_output", raise_subprocess_error_123):
-            loop.run_until_complete(
-                lib.black_run(project_name, repo_path, project_config, results)
-            )
-        self.assertEqual(2, results.stats["failed"])
-
-    def test_flatten_cli_args(self) -> None:
-        fake_long_args = ["--arg", ["really/", "|long", "|regex", "|splitup"], "--done"]
-        expected = ["--arg", "really/|long|regex|splitup", "--done"]
-        self.assertEqual(expected, lib._flatten_cli_args(fake_long_args))
-
-    @event_loop()
-    def test_gen_check_output(self) -> None:
-        loop = asyncio.get_event_loop()
-        stdout, stderr = loop.run_until_complete(
-            lib._gen_check_output([lib.BLACK_BINARY, "--help"])
-        )
-        self.assertIn("The uncompromising code formatter", stdout.decode("utf8"))
-        self.assertEqual(None, stderr)
-
-        # TODO: Add a test to see failure works on Windows
-        if lib.WINDOWS:
-            return
-
-        false_bin = "/usr/bin/false" if system() == "Darwin" else "/bin/false"
-        with self.assertRaises(CalledProcessError):
-            loop.run_until_complete(lib._gen_check_output([false_bin]))
-
-        with self.assertRaises(asyncio.TimeoutError):
-            loop.run_until_complete(
-                lib._gen_check_output(["/bin/sleep", "2"], timeout=0.1)
-            )
-
-    @event_loop()
-    def test_git_checkout_or_rebase(self) -> None:
-        loop = asyncio.get_event_loop()
-        project_config = deepcopy(FAKE_PROJECT_CONFIG)
-        work_path = Path(gettempdir())
-
-        expected_repo_path = work_path / "black"
-        with patch("black_primer.lib._gen_check_output", return_subproccess_output):
-            returned_repo_path = loop.run_until_complete(
-                lib.git_checkout_or_rebase(work_path, project_config)
-            )
-        self.assertEqual(expected_repo_path, returned_repo_path)
-
-    @patch("sys.stdout", new_callable=StringIO)
-    @event_loop()
-    def test_process_queue(self, mock_stdout: Mock) -> None:
-        """Test the process queue on primer itself
-        - If you have non black conforming formatting in primer itself this can fail"""
-        loop = asyncio.get_event_loop()
-        config_path = Path(lib.__file__).parent / "primer.json"
-        with patch("black_primer.lib.git_checkout_or_rebase", return_false):
-            with TemporaryDirectory() as td:
-                return_val = loop.run_until_complete(
-                    lib.process_queue(
-                        str(config_path), Path(td), 2, ["django", "pyramid"]
-                    )
-                )
-                self.assertEqual(0, return_val)
-
-    @event_loop()
-    def test_load_projects_queue(self) -> None:
-        """Test the process queue on primer itself
-        - If you have non black conforming formatting in primer itself this can fail"""
-        loop = asyncio.get_event_loop()
-        config_path = Path(lib.__file__).parent / "primer.json"
-
-        config, projects_queue = loop.run_until_complete(
-            lib.load_projects_queue(config_path, ["django", "pyramid"])
-        )
-        projects = collect(projects_queue)
-        self.assertEqual(projects, ["django", "pyramid"])
-
-
-class PrimerCLITests(unittest.TestCase):
-    @event_loop()
-    def test_async_main(self) -> None:
-        loop = asyncio.get_event_loop()
-        work_dir = Path(gettempdir()) / f"primer_ut_{getpid()}"
-        args = {
-            "config": "/config",
-            "debug": False,
-            "keep": False,
-            "long_checkouts": False,
-            "rebase": False,
-            "workdir": str(work_dir),
-            "workers": 69,
-            "no_diff": False,
-            "projects": "",
-        }
-        with patch("black_primer.cli.lib.process_queue", return_zero):
-            return_val = loop.run_until_complete(cli.async_main(**args))  # type: ignore
-            self.assertEqual(0, return_val)
-
-    def test_handle_debug(self) -> None:
-        self.assertTrue(cli._handle_debug(None, None, True))
-
-    def test_help_output(self) -> None:
-        runner = CliRunner()
-        result = runner.invoke(cli.main, ["--help"])
-        self.assertEqual(result.exit_code, 0)
-
-
-def test_projects(caplog: LogCaptureFixture) -> None:
-    with event_loop():
-        runner = CliRunner()
-        result = runner.invoke(cli.main, ["--projects=STDIN,asdf"])
-        assert result.exit_code == 0
-        assert "1 / 1 succeeded" in result.output
-        assert "Projects not found: {'asdf'}" in caplog.text
-
-    caplog.clear()
-
-    with event_loop():
-        runner = CliRunner()
-        result = runner.invoke(cli.main, ["--projects=fdsa,STDIN"])
-        assert result.exit_code == 0
-        assert "1 / 1 succeeded" in result.output
-        assert "Projects not found: {'fdsa'}" in caplog.text
-
-
-if __name__ == "__main__":
-    unittest.main()

From 086ae68076de570b0cb1881a3c3b9da592b46ee0 Mon Sep 17 00:00:00 2001
From: Shivansh-007 <shivansh-007@outlook.com>
Date: Wed, 16 Mar 2022 08:43:56 +0530
Subject: [PATCH 0490/1034] Remove power hugging formatting from preview
 (#2928)

It is falsely placed in preview features and always formats the power operators, it was added in #2789 but there is no check for formatting added along with it.
---
 src/black/mode.py | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/src/black/mode.py b/src/black/mode.py
index 455ed36e27e..35a072c23e0 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -127,7 +127,6 @@ class Preview(Enum):
     """Individual preview style features."""
 
     string_processing = auto()
-    hug_simple_powers = auto()
 
 
 class Deprecated(UserWarning):
@@ -163,7 +162,9 @@ def __contains__(self, feature: Preview) -> bool:
         """
         if feature is Preview.string_processing:
             return self.preview or self.experimental_string_processing
-        return self.preview
+        # TODO: Remove type ignore comment once preview contains more features
+        #  than just ESP
+        return self.preview  # type: ignore
 
     def get_cache_key(self) -> str:
         if self.target_versions:

From fa7f01592b02229ff47f3bcab39a9b7d6c59f07c Mon Sep 17 00:00:00 2001
From: Joseph Young <80432516+jpy-git@users.noreply.github.com>
Date: Wed, 16 Mar 2022 17:00:30 +0000
Subject: [PATCH 0491/1034] Update pylint config docs (#2931)

---
 CHANGES.md                                    |  2 ++
 docs/compatible_configs/pylint/pylintrc       |  3 --
 docs/compatible_configs/pylint/pyproject.toml |  3 --
 docs/compatible_configs/pylint/setup.cfg      |  3 --
 docs/guides/using_black_with_other_tools.md   | 32 +++----------------
 5 files changed, 6 insertions(+), 37 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index da51e94342c..bb3ccb9ed9f 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -32,6 +32,8 @@
 <!-- Major changes to documentation and policies. Small docs changes
      don't need a changelog entry. -->
 
+- Update pylint config documentation (#2931)
+
 ### Integrations
 
 <!-- For example, Docker, GitHub Actions, pre-commit, editors -->
diff --git a/docs/compatible_configs/pylint/pylintrc b/docs/compatible_configs/pylint/pylintrc
index 7abddd2c330..e863488dfbc 100644
--- a/docs/compatible_configs/pylint/pylintrc
+++ b/docs/compatible_configs/pylint/pylintrc
@@ -1,5 +1,2 @@
-[MESSAGES CONTROL]
-disable = C0330, C0326
-
 [format]
 max-line-length = 88
diff --git a/docs/compatible_configs/pylint/pyproject.toml b/docs/compatible_configs/pylint/pyproject.toml
index 49ad7a2c771..ef51f98a966 100644
--- a/docs/compatible_configs/pylint/pyproject.toml
+++ b/docs/compatible_configs/pylint/pyproject.toml
@@ -1,5 +1,2 @@
-[tool.pylint.messages_control]
-disable = "C0330, C0326"
-
 [tool.pylint.format]
 max-line-length = "88"
diff --git a/docs/compatible_configs/pylint/setup.cfg b/docs/compatible_configs/pylint/setup.cfg
index 3ada24530ea..0b754cdc0f0 100644
--- a/docs/compatible_configs/pylint/setup.cfg
+++ b/docs/compatible_configs/pylint/setup.cfg
@@ -1,5 +1,2 @@
 [pylint]
 max-line-length = 88
-
-[pylint.messages_control]
-disable = C0330, C0326
diff --git a/docs/guides/using_black_with_other_tools.md b/docs/guides/using_black_with_other_tools.md
index bde99f7c00c..1d380bdaba7 100644
--- a/docs/guides/using_black_with_other_tools.md
+++ b/docs/guides/using_black_with_other_tools.md
@@ -210,31 +210,16 @@ mixed feelings about _Black_'s formatting style.
 #### Configuration
 
 ```
-disable = C0326, C0330
 max-line-length = 88
 ```
 
 #### Why those options above?
 
-When _Black_ is folding very long expressions, the closing brackets will
-[be dedented](../the_black_code_style/current_style.md#how-black-wraps-lines).
+Pylint should be configured to only complain about lines that surpass `88` characters
+via `max-line-length = 88`.
 
-```py3
-ImportantClass.important_method(
-    exc, limit, lookup_lines, capture_locals, callback
-)
-```
-
-Although this style is PEP 8 compliant, Pylint will raise
-`C0330: Wrong hanging indentation before block (add 4 spaces)` warnings. Since _Black_
-isn't configurable on this style, Pylint should be told to ignore these warnings via
-`disable = C0330`.
-
-Also, since _Black_ deals with whitespace around operators and brackets, Pylint's
-warning `C0326: Bad whitespace` should be disabled using `disable = C0326`.
-
-And as usual, Pylint should be configured to only complain about lines that surpass `88`
-characters via `max-line-length = 88`.
+If using `pylint<2.6.0`, also disable `C0326` and `C0330` as these are incompatible with
+_Black_ formatting and have since been removed.
 
 #### Formats
 
@@ -242,9 +227,6 @@ characters via `max-line-length = 88`.
 <summary>pylintrc</summary>
 
 ```ini
-[MESSAGES CONTROL]
-disable = C0326, C0330
-
 [format]
 max-line-length = 88
 ```
@@ -257,9 +239,6 @@ max-line-length = 88
 ```cfg
 [pylint]
 max-line-length = 88
-
-[pylint.messages_control]
-disable = C0326, C0330
 ```
 
 </details>
@@ -268,9 +247,6 @@ disable = C0326, C0330
 <summary>pyproject.toml</summary>
 
 ```toml
-[tool.pylint.messages_control]
-disable = "C0326, C0330"
-
 [tool.pylint.format]
 max-line-length = "88"
 ```

From f87df0e3c8735de416b6392ce7f21c6ba194424d Mon Sep 17 00:00:00 2001
From: Marco Edward Gorelli <marcogorelli@protonmail.com>
Date: Mon, 21 Mar 2022 21:51:07 +0000
Subject: [PATCH 0492/1034] dont skip formatting #%% (#2919)

Fixes #2588
---
 CHANGES.md              |  2 ++
 src/black/__init__.py   |  2 +-
 src/black/comments.py   | 48 ++++++++++++++++++++++++-----------------
 src/black/linegen.py    | 16 ++++++++------
 tests/data/comments8.py | 15 +++++++++++++
 tests/test_format.py    |  1 +
 6 files changed, 57 insertions(+), 27 deletions(-)
 create mode 100644 tests/data/comments8.py

diff --git a/CHANGES.md b/CHANGES.md
index bb3ccb9ed9f..d0faf7cecb9 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -14,6 +14,8 @@
 
 <!-- Changes that affect Black's preview style -->
 
+- Code cell separators `#%%` are now standardised to `# %%` (#2919)
+
 ### _Blackd_
 
 <!-- Changes to blackd -->
diff --git a/src/black/__init__.py b/src/black/__init__.py
index c4ec99b441f..51e31e9598b 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -1166,7 +1166,7 @@ def _format_str_once(src_contents: str, *, mode: Mode) -> str:
     else:
         versions = detect_target_versions(src_node, future_imports=future_imports)
 
-    normalize_fmt_off(src_node)
+    normalize_fmt_off(src_node, preview=mode.preview)
     lines = LineGenerator(mode=mode)
     elt = EmptyLineTracker(is_pyi=mode.is_pyi)
     empty_line = Line(mode=mode)
diff --git a/src/black/comments.py b/src/black/comments.py
index 28b9117101d..455326469f0 100644
--- a/src/black/comments.py
+++ b/src/black/comments.py
@@ -23,6 +23,8 @@
 FMT_PASS: Final = {*FMT_OFF, *FMT_SKIP}
 FMT_ON: Final = {"# fmt: on", "# fmt:on", "# yapf: enable"}
 
+COMMENT_EXCEPTIONS = {True: " !:#'", False: " !:#'%"}
+
 
 @dataclass
 class ProtoComment:
@@ -42,7 +44,7 @@ class ProtoComment:
     consumed: int  # how many characters of the original leaf's prefix did we consume
 
 
-def generate_comments(leaf: LN) -> Iterator[Leaf]:
+def generate_comments(leaf: LN, *, preview: bool) -> Iterator[Leaf]:
     """Clean the prefix of the `leaf` and generate comments from it, if any.
 
     Comments in lib2to3 are shoved into the whitespace prefix.  This happens
@@ -61,12 +63,16 @@ def generate_comments(leaf: LN) -> Iterator[Leaf]:
     Inline comments are emitted as regular token.COMMENT leaves.  Standalone
     are emitted with a fake STANDALONE_COMMENT token identifier.
     """
-    for pc in list_comments(leaf.prefix, is_endmarker=leaf.type == token.ENDMARKER):
+    for pc in list_comments(
+        leaf.prefix, is_endmarker=leaf.type == token.ENDMARKER, preview=preview
+    ):
         yield Leaf(pc.type, pc.value, prefix="\n" * pc.newlines)
 
 
 @lru_cache(maxsize=4096)
-def list_comments(prefix: str, *, is_endmarker: bool) -> List[ProtoComment]:
+def list_comments(
+    prefix: str, *, is_endmarker: bool, preview: bool
+) -> List[ProtoComment]:
     """Return a list of :class:`ProtoComment` objects parsed from the given `prefix`."""
     result: List[ProtoComment] = []
     if not prefix or "#" not in prefix:
@@ -92,7 +98,7 @@ def list_comments(prefix: str, *, is_endmarker: bool) -> List[ProtoComment]:
             comment_type = token.COMMENT  # simple trailing comment
         else:
             comment_type = STANDALONE_COMMENT
-        comment = make_comment(line)
+        comment = make_comment(line, preview=preview)
         result.append(
             ProtoComment(
                 type=comment_type, value=comment, newlines=nlines, consumed=consumed
@@ -102,10 +108,10 @@ def list_comments(prefix: str, *, is_endmarker: bool) -> List[ProtoComment]:
     return result
 
 
-def make_comment(content: str) -> str:
+def make_comment(content: str, *, preview: bool) -> str:
     """Return a consistently formatted comment from the given `content` string.
 
-    All comments (except for "##", "#!", "#:", '#'", "#%%") should have a single
+    All comments (except for "##", "#!", "#:", '#'") should have a single
     space between the hash sign and the content.
 
     If `content` didn't start with a hash sign, one is provided.
@@ -123,26 +129,26 @@ def make_comment(content: str) -> str:
         and not content.lstrip().startswith("type:")
     ):
         content = " " + content[1:]  # Replace NBSP by a simple space
-    if content and content[0] not in " !:#'%":
+    if content and content[0] not in COMMENT_EXCEPTIONS[preview]:
         content = " " + content
     return "#" + content
 
 
-def normalize_fmt_off(node: Node) -> None:
+def normalize_fmt_off(node: Node, *, preview: bool) -> None:
     """Convert content between `# fmt: off`/`# fmt: on` into standalone comments."""
     try_again = True
     while try_again:
-        try_again = convert_one_fmt_off_pair(node)
+        try_again = convert_one_fmt_off_pair(node, preview=preview)
 
 
-def convert_one_fmt_off_pair(node: Node) -> bool:
+def convert_one_fmt_off_pair(node: Node, *, preview: bool) -> bool:
     """Convert content of a single `# fmt: off`/`# fmt: on` into a standalone comment.
 
     Returns True if a pair was converted.
     """
     for leaf in node.leaves():
         previous_consumed = 0
-        for comment in list_comments(leaf.prefix, is_endmarker=False):
+        for comment in list_comments(leaf.prefix, is_endmarker=False, preview=preview):
             if comment.value not in FMT_PASS:
                 previous_consumed = comment.consumed
                 continue
@@ -157,7 +163,7 @@ def convert_one_fmt_off_pair(node: Node) -> bool:
                     if comment.value in FMT_SKIP and prev.type in WHITESPACE:
                         continue
 
-            ignored_nodes = list(generate_ignored_nodes(leaf, comment))
+            ignored_nodes = list(generate_ignored_nodes(leaf, comment, preview=preview))
             if not ignored_nodes:
                 continue
 
@@ -197,7 +203,9 @@ def convert_one_fmt_off_pair(node: Node) -> bool:
     return False
 
 
-def generate_ignored_nodes(leaf: Leaf, comment: ProtoComment) -> Iterator[LN]:
+def generate_ignored_nodes(
+    leaf: Leaf, comment: ProtoComment, *, preview: bool
+) -> Iterator[LN]:
     """Starting from the container of `leaf`, generate all leaves until `# fmt: on`.
 
     If comment is skip, returns leaf only.
@@ -221,13 +229,13 @@ def generate_ignored_nodes(leaf: Leaf, comment: ProtoComment) -> Iterator[LN]:
             yield leaf.parent
         return
     while container is not None and container.type != token.ENDMARKER:
-        if is_fmt_on(container):
+        if is_fmt_on(container, preview=preview):
             return
 
         # fix for fmt: on in children
-        if contains_fmt_on_at_column(container, leaf.column):
+        if contains_fmt_on_at_column(container, leaf.column, preview=preview):
             for child in container.children:
-                if contains_fmt_on_at_column(child, leaf.column):
+                if contains_fmt_on_at_column(child, leaf.column, preview=preview):
                     return
                 yield child
         else:
@@ -235,12 +243,12 @@ def generate_ignored_nodes(leaf: Leaf, comment: ProtoComment) -> Iterator[LN]:
             container = container.next_sibling
 
 
-def is_fmt_on(container: LN) -> bool:
+def is_fmt_on(container: LN, preview: bool) -> bool:
     """Determine whether formatting is switched on within a container.
     Determined by whether the last `# fmt:` comment is `on` or `off`.
     """
     fmt_on = False
-    for comment in list_comments(container.prefix, is_endmarker=False):
+    for comment in list_comments(container.prefix, is_endmarker=False, preview=preview):
         if comment.value in FMT_ON:
             fmt_on = True
         elif comment.value in FMT_OFF:
@@ -248,7 +256,7 @@ def is_fmt_on(container: LN) -> bool:
     return fmt_on
 
 
-def contains_fmt_on_at_column(container: LN, column: int) -> bool:
+def contains_fmt_on_at_column(container: LN, column: int, *, preview: bool) -> bool:
     """Determine if children at a given column have formatting switched on."""
     for child in container.children:
         if (
@@ -257,7 +265,7 @@ def contains_fmt_on_at_column(container: LN, column: int) -> bool:
             or isinstance(child, Leaf)
             and child.column == column
         ):
-            if is_fmt_on(child):
+            if is_fmt_on(child, preview=preview):
                 return True
 
     return False
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 4dc242a1dfe..79475a83f0e 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -72,7 +72,7 @@ def visit_default(self, node: LN) -> Iterator[Line]:
         """Default `visit_*()` implementation. Recurses to children of `node`."""
         if isinstance(node, Leaf):
             any_open_brackets = self.current_line.bracket_tracker.any_open_brackets()
-            for comment in generate_comments(node):
+            for comment in generate_comments(node, preview=self.mode.preview):
                 if any_open_brackets:
                     # any comment within brackets is subject to splitting
                     self.current_line.append(comment)
@@ -132,7 +132,7 @@ def visit_stmt(
         `parens` holds a set of string leaf values immediately after which
         invisible parens should be put.
         """
-        normalize_invisible_parens(node, parens_after=parens)
+        normalize_invisible_parens(node, parens_after=parens, preview=self.mode.preview)
         for child in node.children:
             if is_name_token(child) and child.value in keywords:
                 yield from self.line()
@@ -141,7 +141,7 @@ def visit_stmt(
 
     def visit_match_case(self, node: Node) -> Iterator[Line]:
         """Visit either a match or case statement."""
-        normalize_invisible_parens(node, parens_after=set())
+        normalize_invisible_parens(node, parens_after=set(), preview=self.mode.preview)
 
         yield from self.line()
         for child in node.children:
@@ -802,7 +802,9 @@ def normalize_prefix(leaf: Leaf, *, inside_brackets: bool) -> None:
     leaf.prefix = ""
 
 
-def normalize_invisible_parens(node: Node, parens_after: Set[str]) -> None:
+def normalize_invisible_parens(
+    node: Node, parens_after: Set[str], *, preview: bool
+) -> None:
     """Make existing optional parentheses invisible or create new ones.
 
     `parens_after` is a set of string leaf values immediately after which parens
@@ -811,7 +813,7 @@ def normalize_invisible_parens(node: Node, parens_after: Set[str]) -> None:
     Standardizes on visible parentheses for single-element tuples, and keeps
     existing visible parentheses for other tuples and generator expressions.
     """
-    for pc in list_comments(node.prefix, is_endmarker=False):
+    for pc in list_comments(node.prefix, is_endmarker=False, preview=preview):
         if pc.value in FMT_OFF:
             # This `node` has a prefix with `# fmt: off`, don't mess with parens.
             return
@@ -820,7 +822,9 @@ def normalize_invisible_parens(node: Node, parens_after: Set[str]) -> None:
         # Fixes a bug where invisible parens are not properly stripped from
         # assignment statements that contain type annotations.
         if isinstance(child, Node) and child.type == syms.annassign:
-            normalize_invisible_parens(child, parens_after=parens_after)
+            normalize_invisible_parens(
+                child, parens_after=parens_after, preview=preview
+            )
 
         # Add parentheses around long tuple unpacking in assignments.
         if (
diff --git a/tests/data/comments8.py b/tests/data/comments8.py
new file mode 100644
index 00000000000..a2030c2a092
--- /dev/null
+++ b/tests/data/comments8.py
@@ -0,0 +1,15 @@
+# The percent-percent comments are Spyder IDE cells.
+# Both `#%%`` and `# %%` are accepted, so `black` standardises
+# to the latter.
+
+#%%
+# %%
+
+# output
+
+# The percent-percent comments are Spyder IDE cells.
+# Both `#%%`` and `# %%` are accepted, so `black` standardises
+# to the latter.
+
+# %%
+# %%
diff --git a/tests/test_format.py b/tests/test_format.py
index 269bbacd249..667d5c110fa 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -75,6 +75,7 @@
     # string processing
     "cantfit",
     "comments7",
+    "comments8",
     "long_strings",
     "long_strings__edge_case",
     "long_strings__regression",

From 5379d4f3f460ec9b7063dd1cc10f437b0edf9ae3 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Mon, 21 Mar 2022 15:20:41 -0700
Subject: [PATCH 0493/1034] stub style: remove some possible future changes
 (#2940)

Fixes #2938.

All of these suggested future changes are out of scope for an autoformatter and should be handled by a linter instead.
---
 docs/the_black_code_style/current_style.md | 7 +------
 1 file changed, 1 insertion(+), 6 deletions(-)

diff --git a/docs/the_black_code_style/current_style.md b/docs/the_black_code_style/current_style.md
index 0bf5894abdd..d54c7abaf5d 100644
--- a/docs/the_black_code_style/current_style.md
+++ b/docs/the_black_code_style/current_style.md
@@ -399,16 +399,11 @@ recommended code style for those files is more terse than PEP 8:
 _Black_ enforces the above rules. There are additional guidelines for formatting `.pyi`
 file that are not enforced yet but might be in a future version of the formatter:
 
-- all function bodies should be empty (contain `...` instead of the body);
-- do not use docstrings;
 - prefer `...` over `pass`;
-- for arguments with a default, use `...` instead of the actual default;
 - avoid using string literals in type annotations, stub files support forward references
   natively (like Python 3.7 code with `from __future__ import annotations`);
 - use variable annotations instead of type comments, even for stubs that target older
-  versions of Python;
-- for arguments that default to `None`, use `Optional[]` explicitly;
-- use `float` instead of `Union[int, float]`.
+  versions of Python.
 
 ## Pragmatism
 

From 062b54931dc3ea35f673e755893fe28ff1f5a889 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Wed, 23 Mar 2022 13:31:13 -0400
Subject: [PATCH 0494/1034] Github now supports .git-blame-ignore-revs
 (GH-2948)

It's in beta.

https://docs.github.com/en/repositories/working-with-files/using-files/viewing-a-file#ignore-commits-in-the-blame-view
---
 docs/guides/introducing_black_to_your_project.md | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/docs/guides/introducing_black_to_your_project.md b/docs/guides/introducing_black_to_your_project.md
index 71ccf7c114c..9ae40a1928e 100644
--- a/docs/guides/introducing_black_to_your_project.md
+++ b/docs/guides/introducing_black_to_your_project.md
@@ -43,8 +43,10 @@ call to `git blame`.
 $ git config blame.ignoreRevsFile .git-blame-ignore-revs
 ```
 
-**The one caveat is that GitHub and GitLab do not yet support ignoring revisions using
-their native UI of blame.** 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) and please let GitHub
-know!)
+**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.

From 3800ebd81df6a1c31d1eac8cc15899537b9cbb61 Mon Sep 17 00:00:00 2001
From: Joe Young <80432516+jpy-git@users.noreply.github.com>
Date: Thu, 24 Mar 2022 02:16:09 +0000
Subject: [PATCH 0495/1034] Avoid magic-trailing-comma in single-element
 subscripts (#2942)

Closes #2918.
---
 CHANGES.md                          |  1 +
 src/black/linegen.py                | 11 ++++++---
 src/black/lines.py                  | 21 ++++++++++++++---
 src/black/mode.py                   |  5 ++--
 src/black/nodes.py                  | 12 +++++++---
 tests/data/one_element_subscript.py | 36 +++++++++++++++++++++++++++++
 tests/test_format.py                |  1 +
 7 files changed, 75 insertions(+), 12 deletions(-)
 create mode 100644 tests/data/one_element_subscript.py

diff --git a/CHANGES.md b/CHANGES.md
index d0faf7cecb9..d753a24ff77 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -15,6 +15,7 @@
 <!-- Changes that affect Black's preview style -->
 
 - Code cell separators `#%%` are now standardised to `# %%` (#2919)
+- Avoid magic-trailing-comma in single-element subscripts (#2942)
 
 ### _Blackd_
 
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 79475a83f0e..5d92011da9a 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -8,7 +8,12 @@
 from black.nodes import WHITESPACE, RARROW, STATEMENT, STANDALONE_COMMENT
 from black.nodes import ASSIGNMENTS, OPENING_BRACKETS, CLOSING_BRACKETS
 from black.nodes import Visitor, syms, is_arith_like, ensure_visible
-from black.nodes import is_docstring, is_empty_tuple, is_one_tuple, is_one_tuple_between
+from black.nodes import (
+    is_docstring,
+    is_empty_tuple,
+    is_one_tuple,
+    is_one_sequence_between,
+)
 from black.nodes import is_name_token, is_lpar_token, is_rpar_token
 from black.nodes import is_walrus_assignment, is_yield, is_vararg, is_multiline_string
 from black.nodes import is_stub_suite, is_stub_body, is_atom_with_invisible_parens
@@ -973,7 +978,7 @@ def generate_trailers_to_omit(line: Line, line_length: int) -> Iterator[Set[Leaf
                     prev
                     and prev.type == token.COMMA
                     and leaf.opening_bracket is not None
-                    and not is_one_tuple_between(
+                    and not is_one_sequence_between(
                         leaf.opening_bracket, leaf, line.leaves
                     )
                 ):
@@ -1001,7 +1006,7 @@ def generate_trailers_to_omit(line: Line, line_length: int) -> Iterator[Set[Leaf
                 prev
                 and prev.type == token.COMMA
                 and leaf.opening_bracket is not None
-                and not is_one_tuple_between(leaf.opening_bracket, leaf, line.leaves)
+                and not is_one_sequence_between(leaf.opening_bracket, leaf, line.leaves)
             ):
                 # Never omit bracket pairs with trailing commas.
                 # We need to explode on those.
diff --git a/src/black/lines.py b/src/black/lines.py
index f35665c8e0c..e455a507539 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -17,12 +17,12 @@
 from blib2to3.pgen2 import token
 
 from black.brackets import BracketTracker, DOT_PRIORITY
-from black.mode import Mode
+from black.mode import Mode, Preview
 from black.nodes import STANDALONE_COMMENT, TEST_DESCENDANTS
 from black.nodes import BRACKETS, OPENING_BRACKETS, CLOSING_BRACKETS
 from black.nodes import syms, whitespace, replace_child, child_towards
 from black.nodes import is_multiline_string, is_import, is_type_comment
-from black.nodes import is_one_tuple_between
+from black.nodes import is_one_sequence_between
 
 # types
 T = TypeVar("T")
@@ -254,6 +254,7 @@ def has_magic_trailing_comma(
         """Return True if we have a magic trailing comma, that is when:
         - there's a trailing comma here
         - it's not a one-tuple
+        - it's not a single-element subscript
         Additionally, if ensure_removable:
         - it's not from square bracket indexing
         """
@@ -268,6 +269,20 @@ def has_magic_trailing_comma(
             return True
 
         if closing.type == token.RSQB:
+            if (
+                Preview.one_element_subscript in self.mode
+                and closing.parent
+                and closing.parent.type == syms.trailer
+                and closing.opening_bracket
+                and is_one_sequence_between(
+                    closing.opening_bracket,
+                    closing,
+                    self.leaves,
+                    brackets=(token.LSQB, token.RSQB),
+                )
+            ):
+                return False
+
             if not ensure_removable:
                 return True
             comma = self.leaves[-1]
@@ -276,7 +291,7 @@ def has_magic_trailing_comma(
         if self.is_import:
             return True
 
-        if closing.opening_bracket is not None and not is_one_tuple_between(
+        if closing.opening_bracket is not None and not is_one_sequence_between(
             closing.opening_bracket, closing, self.leaves
         ):
             return True
diff --git a/src/black/mode.py b/src/black/mode.py
index 35a072c23e0..77b1cabfcbc 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -127,6 +127,7 @@ class Preview(Enum):
     """Individual preview style features."""
 
     string_processing = auto()
+    one_element_subscript = auto()
 
 
 class Deprecated(UserWarning):
@@ -162,9 +163,7 @@ def __contains__(self, feature: Preview) -> bool:
         """
         if feature is Preview.string_processing:
             return self.preview or self.experimental_string_processing
-        # TODO: Remove type ignore comment once preview contains more features
-        #  than just ESP
-        return self.preview  # type: ignore
+        return self.preview
 
     def get_cache_key(self) -> str:
         if self.target_versions:
diff --git a/src/black/nodes.py b/src/black/nodes.py
index f130bff990e..d18d4bde872 100644
--- a/src/black/nodes.py
+++ b/src/black/nodes.py
@@ -9,6 +9,7 @@
     List,
     Optional,
     Set,
+    Tuple,
     TypeVar,
     Union,
 )
@@ -559,9 +560,14 @@ def is_one_tuple(node: LN) -> bool:
     )
 
 
-def is_one_tuple_between(opening: Leaf, closing: Leaf, leaves: List[Leaf]) -> bool:
-    """Return True if content between `opening` and `closing` looks like a one-tuple."""
-    if opening.type != token.LPAR and closing.type != token.RPAR:
+def is_one_sequence_between(
+    opening: Leaf,
+    closing: Leaf,
+    leaves: List[Leaf],
+    brackets: Tuple[int, int] = (token.LPAR, token.RPAR),
+) -> bool:
+    """Return True if content between `opening` and `closing` is a one-sequence."""
+    if (opening.type, closing.type) != brackets:
         return False
 
     depth = closing.bracket_depth + 1
diff --git a/tests/data/one_element_subscript.py b/tests/data/one_element_subscript.py
new file mode 100644
index 00000000000..39205ba9f7a
--- /dev/null
+++ b/tests/data/one_element_subscript.py
@@ -0,0 +1,36 @@
+# We should not treat the trailing comma
+# in a single-element subscript.
+a: tuple[int,]
+b = tuple[int,]
+
+# The magic comma still applies to multi-element subscripts.
+c: tuple[int, int,]
+d = tuple[int, int,]
+
+# Magic commas still work as expected for non-subscripts.
+small_list = [1,]
+list_of_types = [tuple[int,],]
+
+# output
+# We should not treat the trailing comma
+# in a single-element subscript.
+a: tuple[int,]
+b = tuple[int,]
+
+# The magic comma still applies to multi-element subscripts.
+c: tuple[
+    int,
+    int,
+]
+d = tuple[
+    int,
+    int,
+]
+
+# Magic commas still work as expected for non-subscripts.
+small_list = [
+    1,
+]
+list_of_types = [
+    tuple[int,],
+]
diff --git a/tests/test_format.py b/tests/test_format.py
index 667d5c110fa..4de31700268 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -80,6 +80,7 @@
     "long_strings__edge_case",
     "long_strings__regression",
     "percent_precedence",
+    "one_element_subscript",
 ]
 
 SOURCES: List[str] = [

From 14e5ce5412efa53438df0180e735b3834df3b579 Mon Sep 17 00:00:00 2001
From: Joe Young <80432516+jpy-git@users.noreply.github.com>
Date: Thu, 24 Mar 2022 14:59:54 +0000
Subject: [PATCH 0496/1034] Remove unnecessary parentheses from tuple unpacking
 in `for` loops (#2945)

---
 CHANGES.md                             |  1 +
 src/black/linegen.py                   | 26 ++++++++++++++---
 src/black/mode.py                      |  1 +
 src/black/trans.py                     | 12 ++++----
 tests/data/long_strings__regression.py |  2 +-
 tests/data/remove_for_brackets.py      | 40 ++++++++++++++++++++++++++
 tests/test_format.py                   |  1 +
 7 files changed, 72 insertions(+), 11 deletions(-)
 create mode 100644 tests/data/remove_for_brackets.py

diff --git a/CHANGES.md b/CHANGES.md
index d753a24ff77..b2325b648f9 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -15,6 +15,7 @@
 <!-- Changes that affect Black's preview style -->
 
 - Code cell separators `#%%` are now standardised to `# %%` (#2919)
+- Remove unnecessary parentheses from tuple unpacking in `for` loops (#2945)
 - Avoid magic-trailing-comma in single-element subscripts (#2942)
 
 ### _Blackd_
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 5d92011da9a..cb605ee8be4 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -841,7 +841,11 @@ def normalize_invisible_parens(
 
         if check_lpar:
             if child.type == syms.atom:
-                if maybe_make_parens_invisible_in_atom(child, parent=node):
+                if maybe_make_parens_invisible_in_atom(
+                    child,
+                    parent=node,
+                    preview=preview,
+                ):
                     wrap_in_parentheses(node, child, visible=False)
             elif is_one_tuple(child):
                 wrap_in_parentheses(node, child, visible=True)
@@ -865,7 +869,11 @@ def normalize_invisible_parens(
         check_lpar = isinstance(child, Leaf) and child.value in parens_after
 
 
-def maybe_make_parens_invisible_in_atom(node: LN, parent: LN) -> bool:
+def maybe_make_parens_invisible_in_atom(
+    node: LN,
+    parent: LN,
+    preview: bool = False,
+) -> bool:
     """If it's safe, make the parens in the atom `node` invisible, recursively.
     Additionally, remove repeated, adjacent invisible parens from the atom `node`
     as they are redundant.
@@ -873,13 +881,23 @@ def maybe_make_parens_invisible_in_atom(node: LN, parent: LN) -> bool:
     Returns whether the node should itself be wrapped in invisible parentheses.
 
     """
+    if (
+        preview
+        and parent.type == syms.for_stmt
+        and isinstance(node.prev_sibling, Leaf)
+        and node.prev_sibling.type == token.NAME
+        and node.prev_sibling.value == "for"
+    ):
+        for_stmt_check = False
+    else:
+        for_stmt_check = True
 
     if (
         node.type != syms.atom
         or is_empty_tuple(node)
         or is_one_tuple(node)
         or (is_yield(node) and parent.type != syms.expr_stmt)
-        or max_delimiter_priority_in_atom(node) >= COMMA_PRIORITY
+        or (max_delimiter_priority_in_atom(node) >= COMMA_PRIORITY and for_stmt_check)
     ):
         return False
 
@@ -902,7 +920,7 @@ def maybe_make_parens_invisible_in_atom(node: LN, parent: LN) -> bool:
         # make parentheses invisible
         first.value = ""
         last.value = ""
-        maybe_make_parens_invisible_in_atom(middle, parent=parent)
+        maybe_make_parens_invisible_in_atom(middle, parent=parent, preview=preview)
 
         if is_atom_with_invisible_parens(middle):
             # Strip the invisible parens from `middle` by replacing
diff --git a/src/black/mode.py b/src/black/mode.py
index 77b1cabfcbc..6b74c14b6de 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -127,6 +127,7 @@ class Preview(Enum):
     """Individual preview style features."""
 
     string_processing = auto()
+    remove_redundant_parens = auto()
     one_element_subscript = auto()
 
 
diff --git a/src/black/trans.py b/src/black/trans.py
index 74d052fe2dc..01aa80eaaf8 100644
--- a/src/black/trans.py
+++ b/src/black/trans.py
@@ -365,7 +365,7 @@ def do_match(self, line: Line) -> TMatchResult:
 
         is_valid_index = is_valid_index_factory(LL)
 
-        for (i, leaf) in enumerate(LL):
+        for i, leaf in enumerate(LL):
             if (
                 leaf.type == token.STRING
                 and is_valid_index(i + 1)
@@ -570,7 +570,7 @@ def make_naked(string: str, string_prefix: str) -> str:
 
         # Build the final line ('new_line') that this method will later return.
         new_line = line.clone()
-        for (i, leaf) in enumerate(LL):
+        for i, leaf in enumerate(LL):
             if i == string_idx:
                 new_line.append(string_leaf)
 
@@ -691,7 +691,7 @@ def do_match(self, line: Line) -> TMatchResult:
 
         is_valid_index = is_valid_index_factory(LL)
 
-        for (idx, leaf) in enumerate(LL):
+        for idx, leaf in enumerate(LL):
             # Should be a string...
             if leaf.type != token.STRING:
                 continue
@@ -1713,7 +1713,7 @@ def _assert_match(LL: List[Leaf]) -> Optional[int]:
         if parent_type(LL[0]) == syms.assert_stmt and LL[0].value == "assert":
             is_valid_index = is_valid_index_factory(LL)
 
-            for (i, leaf) in enumerate(LL):
+            for i, leaf in enumerate(LL):
                 # We MUST find a comma...
                 if leaf.type == token.COMMA:
                     idx = i + 2 if is_empty_par(LL[i + 1]) else i + 1
@@ -1751,7 +1751,7 @@ def _assign_match(LL: List[Leaf]) -> Optional[int]:
         ):
             is_valid_index = is_valid_index_factory(LL)
 
-            for (i, leaf) in enumerate(LL):
+            for i, leaf in enumerate(LL):
                 # We MUST find either an '=' or '+=' symbol...
                 if leaf.type in [token.EQUAL, token.PLUSEQUAL]:
                     idx = i + 2 if is_empty_par(LL[i + 1]) else i + 1
@@ -1794,7 +1794,7 @@ def _dict_match(LL: List[Leaf]) -> Optional[int]:
         if syms.dictsetmaker in [parent_type(LL[0]), parent_type(LL[0].parent)]:
             is_valid_index = is_valid_index_factory(LL)
 
-            for (i, leaf) in enumerate(LL):
+            for i, leaf in enumerate(LL):
                 # We MUST find a colon...
                 if leaf.type == token.COLON:
                     idx = i + 2 if is_empty_par(LL[i + 1]) else i + 1
diff --git a/tests/data/long_strings__regression.py b/tests/data/long_strings__regression.py
index 36f323e04d6..58ccc4ac0b1 100644
--- a/tests/data/long_strings__regression.py
+++ b/tests/data/long_strings__regression.py
@@ -599,7 +599,7 @@ def foo():
 
 
 def foo(xxxx):
-    for (xxx_xxxx, _xxx_xxx, _xxx_xxxxx, xxx_xxxx) in xxxx:
+    for xxx_xxxx, _xxx_xxx, _xxx_xxxxx, xxx_xxxx in xxxx:
         for xxx in xxx_xxxx:
             assert ("x" in xxx) or (xxx in xxx_xxx_xxxxx), (
                 "{0} xxxxxxx xx {1}, xxx {1} xx xxx xx xxxx xx xxx xxxx: xxx xxxx {2}"
diff --git a/tests/data/remove_for_brackets.py b/tests/data/remove_for_brackets.py
new file mode 100644
index 00000000000..c8d88abcc50
--- /dev/null
+++ b/tests/data/remove_for_brackets.py
@@ -0,0 +1,40 @@
+# Only remove tuple brackets after `for`
+for (k, v) in d.items():
+    print(k, v)
+
+# Don't touch tuple brackets after `in`
+for module in (core, _unicodefun):
+    if hasattr(module, "_verify_python3_env"):
+        module._verify_python3_env = lambda: None
+
+# Brackets remain for long for loop lines
+for (why_would_anyone_choose_to_name_a_loop_variable_with_a_name_this_long, i_dont_know_but_we_should_still_check_the_behaviour_if_they_do) in d.items():
+    print(k, v)
+
+for (k, v) in dfkasdjfldsjflkdsjflkdsjfdslkfjldsjfgkjdshgkljjdsfldgkhsdofudsfudsofajdslkfjdslkfjldisfjdffjsdlkfjdlkjjkdflskadjldkfjsalkfjdasj.items():
+    print(k, v)
+
+# output
+# Only remove tuple brackets after `for`
+for k, v in d.items():
+    print(k, v)
+
+# Don't touch tuple brackets after `in`
+for module in (core, _unicodefun):
+    if hasattr(module, "_verify_python3_env"):
+        module._verify_python3_env = lambda: None
+
+# Brackets remain for long for loop lines
+for (
+    why_would_anyone_choose_to_name_a_loop_variable_with_a_name_this_long,
+    i_dont_know_but_we_should_still_check_the_behaviour_if_they_do,
+) in d.items():
+    print(k, v)
+
+for (
+    k,
+    v,
+) in (
+    dfkasdjfldsjflkdsjflkdsjfdslkfjldsjfgkjdshgkljjdsfldgkhsdofudsfudsofajdslkfjdslkfjldisfjdffjsdlkfjdlkjjkdflskadjldkfjsalkfjdasj.items()
+):
+    print(k, v)
diff --git a/tests/test_format.py b/tests/test_format.py
index 4de31700268..b7446853e7b 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -80,6 +80,7 @@
     "long_strings__edge_case",
     "long_strings__regression",
     "percent_precedence",
+    "remove_for_brackets",
     "one_element_subscript",
 ]
 

From 14d84ba2e96c5ca1351b8fe4d0d415cc148f4117 Mon Sep 17 00:00:00 2001
From: Joe Young <80432516+jpy-git@users.noreply.github.com>
Date: Thu, 24 Mar 2022 15:14:21 +0000
Subject: [PATCH 0497/1034] Resolve new flake8-bugbear errors (B020) (GH-2950)

Fixes a couple places where we were using the same variable name as we
are iterating over.

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 src/black/linegen.py | 6 +++---
 src/black/parsing.py | 4 ++--
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/src/black/linegen.py b/src/black/linegen.py
index cb605ee8be4..9c85e76d3e8 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -670,9 +670,9 @@ def dont_increase_indentation(split_func: Transformer) -> Transformer:
 
     @wraps(split_func)
     def split_wrapper(line: Line, features: Collection[Feature] = ()) -> Iterator[Line]:
-        for line in split_func(line, features):
-            normalize_prefix(line.leaves[0], inside_brackets=True)
-            yield line
+        for split_line in split_func(line, features):
+            normalize_prefix(split_line.leaves[0], inside_brackets=True)
+            yield split_line
 
     return split_wrapper
 
diff --git a/src/black/parsing.py b/src/black/parsing.py
index db48ae4baf5..12726567948 100644
--- a/src/black/parsing.py
+++ b/src/black/parsing.py
@@ -225,8 +225,8 @@ def stringify_ast(node: Union[ast.AST, ast3.AST], depth: int = 0) -> Iterator[st
                     and isinstance(node, (ast.Delete, ast3.Delete))
                     and isinstance(item, (ast.Tuple, ast3.Tuple))
                 ):
-                    for item in item.elts:
-                        yield from stringify_ast(item, depth + 2)
+                    for elt in item.elts:
+                        yield from stringify_ast(elt, depth + 2)
 
                 elif isinstance(item, (ast.AST, ast3.AST)):
                     yield from stringify_ast(item, depth + 2)

From bd1e98034907463f5d86f4d87e89202dc6c34dd4 Mon Sep 17 00:00:00 2001
From: Joe Young <80432516+jpy-git@users.noreply.github.com>
Date: Sat, 26 Mar 2022 16:56:50 +0000
Subject: [PATCH 0498/1034] Remove unnecessary parentheses from `except`
 clauses (#2939)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 CHANGES.md                         |  1 +
 src/black/linegen.py               |  7 ++-
 tests/data/remove_except_parens.py | 79 ++++++++++++++++++++++++++++++
 tests/test_format.py               |  1 +
 4 files changed, 87 insertions(+), 1 deletion(-)
 create mode 100644 tests/data/remove_except_parens.py

diff --git a/CHANGES.md b/CHANGES.md
index b2325b648f9..d34bd4ead58 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -15,6 +15,7 @@
 <!-- Changes that affect Black's preview style -->
 
 - Code cell separators `#%%` are now standardised to `# %%` (#2919)
+- Remove unnecessary parentheses from `except` statements (#2939)
 - Remove unnecessary parentheses from tuple unpacking in `for` loops (#2945)
 - Avoid magic-trailing-comma in single-element subscripts (#2942)
 
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 9c85e76d3e8..8a28c3901bb 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -318,7 +318,12 @@ def __post_init__(self) -> None:
         self.visit_try_stmt = partial(
             v, keywords={"try", "except", "else", "finally"}, parens=Ø
         )
-        self.visit_except_clause = partial(v, keywords={"except"}, parens=Ø)
+        if self.mode.preview:
+            self.visit_except_clause = partial(
+                v, keywords={"except"}, parens={"except"}
+            )
+        else:
+            self.visit_except_clause = partial(v, keywords={"except"}, parens=Ø)
         self.visit_with_stmt = partial(v, keywords={"with"}, parens=Ø)
         self.visit_funcdef = partial(v, keywords={"def"}, parens=Ø)
         self.visit_classdef = partial(v, keywords={"class"}, parens=Ø)
diff --git a/tests/data/remove_except_parens.py b/tests/data/remove_except_parens.py
new file mode 100644
index 00000000000..322c5b7a51b
--- /dev/null
+++ b/tests/data/remove_except_parens.py
@@ -0,0 +1,79 @@
+# These brackets are redundant, therefore remove.
+try:
+    a.something
+except (AttributeError) as err:
+    raise err
+
+# This is tuple of exceptions.
+# Although this could be replaced with just the exception,
+# we do not remove brackets to preserve AST.
+try:
+    a.something
+except (AttributeError,) as err:
+    raise err
+
+# This is a tuple of exceptions. Do not remove brackets.
+try:
+    a.something
+except (AttributeError, ValueError) as err:
+    raise err
+
+# Test long variants.
+try:
+    a.something
+except (some.really.really.really.looooooooooooooooooooooooooooooooong.module.over89.chars.Error) as err:
+    raise err
+
+try:
+    a.something
+except (some.really.really.really.looooooooooooooooooooooooooooooooong.module.over89.chars.Error,) as err:
+    raise err
+
+try:
+    a.something
+except (some.really.really.really.looooooooooooooooooooooooooooooooong.module.over89.chars.Error, some.really.really.really.looooooooooooooooooooooooooooooooong.module.over89.chars.Error) as err:
+    raise err
+
+# output
+# These brackets are redundant, therefore remove.
+try:
+    a.something
+except AttributeError as err:
+    raise err
+
+# This is tuple of exceptions.
+# Although this could be replaced with just the exception,
+# we do not remove brackets to preserve AST.
+try:
+    a.something
+except (AttributeError,) as err:
+    raise err
+
+# This is a tuple of exceptions. Do not remove brackets.
+try:
+    a.something
+except (AttributeError, ValueError) as err:
+    raise err
+
+# Test long variants.
+try:
+    a.something
+except (
+    some.really.really.really.looooooooooooooooooooooooooooooooong.module.over89.chars.Error
+) as err:
+    raise err
+
+try:
+    a.something
+except (
+    some.really.really.really.looooooooooooooooooooooooooooooooong.module.over89.chars.Error,
+) as err:
+    raise err
+
+try:
+    a.something
+except (
+    some.really.really.really.looooooooooooooooooooooooooooooooong.module.over89.chars.Error,
+    some.really.really.really.looooooooooooooooooooooooooooooooong.module.over89.chars.Error,
+) as err:
+    raise err
diff --git a/tests/test_format.py b/tests/test_format.py
index b7446853e7b..a995bd3f1f5 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -80,6 +80,7 @@
     "long_strings__edge_case",
     "long_strings__regression",
     "percent_precedence",
+    "remove_except_parens",
     "remove_for_brackets",
     "one_element_subscript",
 ]

From f239d227c003c52126239e1b9a37c36c2b2b8305 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Sat, 26 Mar 2022 17:22:38 -0400
Subject: [PATCH 0499/1034] Enforce no formatting changes for PRs via CI
 (GH-2951)

Now PRs will run two diff-shades jobs, "preview-changes" which formats
all projects with preview=True, and "assert-no-changes" which formats
all projects with preview=False. The latter also fails if any changes
were made.

Pushes to main will only run "preview-changes"

Also the workflow_dispatch feature was dropped since it was
complicating everything for little gain.
---
 .github/workflows/diff_shades.yml    | 114 ++++++++++++++-------------
 docs/contributing/gauging_changes.md |  50 ++++++------
 scripts/diff_shades_gha_helper.py    | 105 ++++++++----------------
 src/black/__init__.py                |   3 +
 4 files changed, 121 insertions(+), 151 deletions(-)

diff --git a/.github/workflows/diff_shades.yml b/.github/workflows/diff_shades.yml
index e9deaba0136..51fcebcff63 100644
--- a/.github/workflows/diff_shades.yml
+++ b/.github/workflows/diff_shades.yml
@@ -3,54 +3,61 @@ name: diff-shades
 on:
   push:
     branches: [main]
-    paths-ignore: ["docs/**", "tests/**", "**.md", "**.rst"]
+    paths: ["src/**", "setup.*", "pyproject.toml", ".github/workflows/*"]
 
   pull_request:
-    paths-ignore: ["docs/**", "tests/**", "**.md", "**.rst"]
-
-  workflow_dispatch:
-    inputs:
-      baseline:
-        description: >
-          The baseline revision. Pro-tip, use `.pypi` to use the latest version
-          on PyPI or `.XXX` to use a PR.
-        required: true
-        default: main
-      baseline-args:
-        description: "Custom Black arguments (eg. -l 79)"
-        required: false
-      target:
-        description: >
-          The target revision to compare against the baseline. Same tip applies here.
-        required: true
-      target-args:
-        description: "Custom Black arguments (eg. -S)"
-        required: false
+    paths: ["src/**", "setup.*", "pyproject.toml", ".github/workflows/*"]
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.run_id }}
   cancel-in-progress: true
 
 jobs:
+  configure:
+    runs-on: ubuntu-latest
+    outputs:
+      matrix: ${{ steps.set-config.outputs.matrix }}
+
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v3
+
+      - name: Install diff-shades and support dependencies
+        run: |
+          python -m pip install click packaging urllib3
+          python -m pip install https://github.com/ichard26/diff-shades/archive/stable.zip
+
+      - name: Calculate run configuration & metadata
+        id: set-config
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: >
+          python scripts/diff_shades_gha_helper.py config ${{ github.event_name }} ${{ matrix.mode }}
+
   analysis:
-    name: analysis / linux
+    name: analysis / ${{ matrix.mode }}
+    needs: configure
     runs-on: ubuntu-latest
     env:
       # Clang is less picky with the C code it's given than gcc (and may
       # generate faster binaries too).
       CC: clang-12
+    strategy:
+      fail-fast: false
+      matrix:
+        include: ${{ fromJson(needs.configure.outputs.matrix )}}
 
     steps:
       - name: Checkout this repository (full clone)
         uses: actions/checkout@v3
         with:
+          # The baseline revision could be rather old so a full clone is ideal.
           fetch-depth: 0
 
       - uses: actions/setup-python@v3
 
       - name: Install diff-shades and support dependencies
         run: |
-          python -m pip install pip --upgrade
           python -m pip install https://github.com/ichard26/diff-shades/archive/stable.zip
           python -m pip install click packaging urllib3
           python -m pip install -r .github/mypyc-requirements.txt
@@ -59,28 +66,19 @@ jobs:
           git config user.name "diff-shades-gha"
           git config user.email "diff-shades-gha@example.com"
 
-      - name: Calculate run configuration & metadata
-        id: config
-        env:
-          GITHUB_TOKEN: ${{ github.token }}
-        run: >
-          python helper.py config ${{ github.event_name }}
-          ${{ github.event.inputs.baseline }} ${{ github.event.inputs.target }}
-          --baseline-args "${{ github.event.inputs.baseline-args }}"
-
       - name: Attempt to use cached baseline analysis
         id: baseline-cache
         uses: actions/cache@v2.1.7
         with:
-          path: ${{ steps.config.outputs.baseline-analysis }}
-          key: ${{ steps.config.outputs.baseline-cache-key }}
+          path: ${{ matrix.baseline-analysis }}
+          key: ${{ matrix.baseline-cache-key }}
 
       - name: Build and install baseline revision
         if: steps.baseline-cache.outputs.cache-hit != 'true'
         env:
           GITHUB_TOKEN: ${{ github.token }}
         run: >
-          ${{ steps.config.outputs.baseline-setup-cmd }}
+          ${{ matrix.baseline-setup-cmd }}
           && python setup.py --use-mypyc bdist_wheel
           && python -m pip install dist/*.whl && rm build dist -r
 
@@ -88,63 +86,69 @@ jobs:
         if: steps.baseline-cache.outputs.cache-hit != 'true'
         run: >
           diff-shades analyze -v --work-dir projects-cache/
-          ${{ steps.config.outputs.baseline-analysis }} -- ${{ github.event.inputs.baseline-args }}
+          ${{ matrix.baseline-analysis }} ${{ matrix.force-flag }}
 
       - name: Build and install target revision
         env:
           GITHUB_TOKEN: ${{ github.token }}
         run: >
-          ${{ steps.config.outputs.target-setup-cmd }}
+          ${{ matrix.target-setup-cmd }}
           && python setup.py --use-mypyc bdist_wheel
           && python -m pip install dist/*.whl
 
       - name: Analyze target revision
         run: >
           diff-shades analyze -v --work-dir projects-cache/
-          ${{ steps.config.outputs.target-analysis }} --repeat-projects-from
-          ${{ steps.config.outputs.baseline-analysis }} -- ${{ github.event.inputs.target-args }}
+          ${{ matrix.target-analysis }} --repeat-projects-from
+          ${{ matrix.baseline-analysis }} ${{ matrix.force-flag }}
 
       - name: Generate HTML diff report
         run: >
-          diff-shades --dump-html diff.html compare --diff --quiet
-          ${{ steps.config.outputs.baseline-analysis }} ${{ steps.config.outputs.target-analysis }}
+          diff-shades --dump-html diff.html compare --diff
+          ${{ matrix.baseline-analysis }} ${{ matrix.target-analysis }}
 
       - name: Upload diff report
         uses: actions/upload-artifact@v2
         with:
-          name: diff.html
+          name: ${{ matrix.mode }}-diff.html
           path: diff.html
 
       - name: Upload baseline analysis
         uses: actions/upload-artifact@v2
         with:
-          name: ${{ steps.config.outputs.baseline-analysis }}
-          path: ${{ steps.config.outputs.baseline-analysis }}
+          name: ${{ matrix.baseline-analysis }}
+          path: ${{ matrix.baseline-analysis }}
 
       - name: Upload target analysis
         uses: actions/upload-artifact@v2
         with:
-          name: ${{ steps.config.outputs.target-analysis }}
-          path: ${{ steps.config.outputs.target-analysis }}
+          name: ${{ matrix.target-analysis }}
+          path: ${{ matrix.target-analysis }}
 
       - name: Generate summary file (PR only)
-        if: github.event_name == 'pull_request'
+        if: github.event_name == 'pull_request' && matrix.mode == 'preview-changes'
         run: >
           python helper.py comment-body
-          ${{ steps.config.outputs.baseline-analysis }} ${{ steps.config.outputs.target-analysis }}
-          ${{ steps.config.outputs.baseline-sha }} ${{ steps.config.outputs.target-sha }}
+          ${{ matrix.baseline-analysis }} ${{ matrix.target-analysis }}
+          ${{ matrix.baseline-sha }} ${{ matrix.target-sha }}
           ${{ github.event.pull_request.number }}
 
       - name: Upload summary file (PR only)
-        if: github.event_name == 'pull_request'
+        if: github.event_name == 'pull_request' && matrix.mode == 'preview-changes'
         uses: actions/upload-artifact@v2
         with:
           name: .pr-comment.json
           path: .pr-comment.json
 
-        # This is last so the diff-shades-comment workflow can still work even if we
-        # end up detecting failed files and failing the run.
-      - name: Check for failed files in both analyses
+      - name: Verify zero changes (PR only)
+        if: matrix.mode == 'assert-no-changes'
+        run: >
+          diff-shades compare --check ${{ matrix.baseline-analysis }} ${{ matrix.target-analysis }}
+          || (echo "Please verify you didn't change the stable code style unintentionally!" && exit 1)
+
+      - name: Check for failed files for target revision
+        # Even if the previous step failed, we should still check for failed files.
+        if: always()
         run: >
-          diff-shades show-failed --check --show-log ${{ steps.config.outputs.baseline-analysis }};
-          diff-shades show-failed --check --show-log ${{ steps.config.outputs.target-analysis }}
+          diff-shades show-failed --check --show-log ${{ matrix.target-analysis }}
+          --check-allow 'sqlalchemy:test/orm/test_relationship_criteria.py'
diff --git a/docs/contributing/gauging_changes.md b/docs/contributing/gauging_changes.md
index f28e81120b3..8562a83ed0c 100644
--- a/docs/contributing/gauging_changes.md
+++ b/docs/contributing/gauging_changes.md
@@ -9,10 +9,10 @@ enough to cause frustration to projects that are already "black formatted".
 
 ## diff-shades
 
-diff-shades is a tool that runs _Black_ across a list of Git cloneable OSS projects
-recording the results. The main highlight feature of diff-shades is being able to
-compare two revisions of _Black_. This is incredibly useful as it allows us to see what
-exact changes will occur, say merging a certain PR.
+diff-shades is a tool that runs _Black_ across a list of open-source projects recording
+the results. The main highlight feature of diff-shades is being able to compare two
+revisions of _Black_. This is incredibly useful as it allows us to see what exact
+changes will occur, say merging a certain PR.
 
 For more information, please see the [diff-shades documentation][diff-shades].
 
@@ -20,35 +20,39 @@ For more information, please see the [diff-shades documentation][diff-shades].
 
 diff-shades is also the tool behind the "diff-shades results comparing ..." /
 "diff-shades reports zero changes ..." comments on PRs. The project has a GitHub Actions
-workflow which runs diff-shades twice against two revisions of _Black_ according to
-these rules:
+workflow that analyzes and compares two revisions of _Black_ according to these rules:
 
 |                       | Baseline revision       | Target revision              |
 | --------------------- | ----------------------- | ---------------------------- |
 | On PRs                | latest commit on `main` | PR commit with `main` merged |
 | On pushes (main only) | latest PyPI version     | the pushed commit            |
 
-Once finished, a PR comment will be posted embedding a summary of the changes and links
-to further information. If there's a pre-existing diff-shades comment, it'll be updated
-instead the next time the workflow is triggered on the same PR.
+For pushes to main, there's only one analysis job named `preview-changes` where the
+preview style is used for all projects.
 
-The workflow uploads 3-4 artifacts upon completion: the two generated analyses (they
-have the .json file extension), `diff.html`, and `.pr-comment.json` if triggered by a
-PR. The last one is downloaded by the `diff-shades-comment` workflow and shouldn't be
-downloaded locally. `diff.html` comes in handy for push-based or manually triggered
-runs. And the analyses exist just in case you want to do further analysis using the
-collected data locally.
+For PRs they get one more analysis job: `assert-no-changes`. It's similar to
+`preview-changes` but runs with the stable code style. It will fail if changes were
+made. This makes sure code won't be reformatted again and again within the same year in
+accordance to Black's stability policy.
 
-Note that the workflow will only fail intentionally if while analyzing a file failed to
+Additionally for PRs, a PR comment will be posted embedding a summary of the preview
+changes and links to further information. If there's a pre-existing diff-shades comment,
+it'll be updated instead the next time the workflow is triggered on the same PR.
+
+```{note}
+The `preview-changes` job will only fail intentionally if while analyzing a file failed to
 format. Otherwise a failure indicates a bug in the workflow.
+```
 
-```{tip}
-Maintainers with write access or higher can trigger the workflow manually from the
-Actions tab using the `workflow_dispatch` event. Simply select "diff-shades"
-from the workflows list on the left, press "Run workflow", and fill in which revisions
-and command line arguments to use.
+The workflow uploads several artifacts upon completion:
 
-Once finished, check the logs or download the artifacts for local use.
-```
+- The raw analyses (.json)
+- HTML diffs (.html)
+- `.pr-comment.json` (if triggered by a PR)
+
+The last one is downloaded by the `diff-shades-comment` workflow and shouldn't be
+downloaded locally. The HTML diffs come in handy for push-based where there's no PR to
+post a comment. And the analyses exist just in case you want to do further analysis
+using the collected data locally.
 
 [diff-shades]: https://github.com/ichard26/diff-shades#readme
diff --git a/scripts/diff_shades_gha_helper.py b/scripts/diff_shades_gha_helper.py
index f1f7f2be91c..b5fea5a817d 100644
--- a/scripts/diff_shades_gha_helper.py
+++ b/scripts/diff_shades_gha_helper.py
@@ -23,7 +23,7 @@
 import zipfile
 from io import BytesIO
 from pathlib import Path
-from typing import Any, Optional, Tuple
+from typing import Any
 
 import click
 import urllib3
@@ -55,7 +55,7 @@ def set_output(name: str, value: str) -> None:
     print(f"::set-output name={name}::{value}")
 
 
-def http_get(url: str, is_json: bool = True, **kwargs: Any) -> Any:
+def http_get(url: str, *, is_json: bool = True, **kwargs: Any) -> Any:
     headers = kwargs.get("headers") or {}
     headers["User-Agent"] = USER_AGENT
     if "github" in url:
@@ -78,10 +78,10 @@ def http_get(url: str, is_json: bool = True, **kwargs: Any) -> Any:
     return data
 
 
-def get_branch_or_tag_revision(sha: str = "main") -> str:
+def get_main_revision() -> str:
     data = http_get(
         f"https://api.github.com/repos/{REPO}/commits",
-        fields={"per_page": "1", "sha": sha},
+        fields={"per_page": "1", "sha": "main"},
     )
     assert isinstance(data[0]["sha"], str)
     return data[0]["sha"]
@@ -100,53 +100,18 @@ def get_pypi_version() -> Version:
     return sorted_versions[0]
 
 
-def resolve_custom_ref(ref: str) -> Tuple[str, str]:
-    if ref == ".pypi":
-        # Special value to get latest PyPI version.
-        version = str(get_pypi_version())
-        return version, f"git checkout {version}"
-
-    if ref.startswith(".") and ref[1:].isnumeric():
-        # Special format to get a PR.
-        number = int(ref[1:])
-        revision = get_pr_revision(number)
-        return (
-            f"pr-{number}-{revision[:SHA_LENGTH]}",
-            f"gh pr checkout {number} && git merge origin/main",
-        )
-
-    # Alright, it's probably a branch, tag, or a commit SHA, let's find out!
-    revision = get_branch_or_tag_revision(ref)
-    # We're cutting the revision short as we might be operating on a short commit SHA.
-    if revision == ref or revision[: len(ref)] == ref:
-        # It's *probably* a commit as the resolved SHA isn't different from the REF.
-        return revision[:SHA_LENGTH], f"git checkout {revision}"
-
-    # It's *probably* a pre-existing branch or tag, yay!
-    return f"{ref}-{revision[:SHA_LENGTH]}", f"git checkout {revision}"
-
-
 @click.group()
 def main() -> None:
     pass
 
 
 @main.command("config", help="Acquire run configuration and metadata.")
-@click.argument(
-    "event", type=click.Choice(["push", "pull_request", "workflow_dispatch"])
-)
-@click.argument("custom_baseline", required=False)
-@click.argument("custom_target", required=False)
-@click.option("--baseline-args", default="")
-def config(
-    event: Literal["push", "pull_request", "workflow_dispatch"],
-    custom_baseline: Optional[str],
-    custom_target: Optional[str],
-    baseline_args: str,
-) -> None:
+@click.argument("event", type=click.Choice(["push", "pull_request"]))
+def config(event: Literal["push", "pull_request"]) -> None:
     import diff_shades
 
     if event == "push":
+        jobs = [{"mode": "preview-changes", "force-flag": "--force-preview-style"}]
         # Push on main, let's use PyPI Black as the baseline.
         baseline_name = str(get_pypi_version())
         baseline_cmd = f"git checkout {baseline_name}"
@@ -156,11 +121,14 @@ def config(
         target_cmd = f"git checkout {target_rev}"
 
     elif event == "pull_request":
+        jobs = [
+            {"mode": "preview-changes", "force-flag": "--force-preview-style"},
+            {"mode": "assert-no-changes", "force-flag": "--force-stable-style"},
+        ]
         # PR, let's use main as the baseline.
-        baseline_rev = get_branch_or_tag_revision()
+        baseline_rev = get_main_revision()
         baseline_name = "main-" + baseline_rev[:SHA_LENGTH]
         baseline_cmd = f"git checkout {baseline_rev}"
-
         pr_ref = os.getenv("GITHUB_REF")
         assert pr_ref is not None
         pr_num = int(pr_ref[10:-6])
@@ -168,27 +136,20 @@ def config(
         target_name = f"pr-{pr_num}-{pr_rev[:SHA_LENGTH]}"
         target_cmd = f"gh pr checkout {pr_num} && git merge origin/main"
 
-        # These are only needed for the PR comment.
-        set_output("baseline-sha", baseline_rev)
-        set_output("target-sha", pr_rev)
-    else:
-        assert custom_baseline is not None and custom_target is not None
-        baseline_name, baseline_cmd = resolve_custom_ref(custom_baseline)
-        target_name, target_cmd = resolve_custom_ref(custom_target)
-        if baseline_name == target_name:
-            # Alright we're using the same revisions but we're (hopefully) using
-            # different command line arguments, let's support that too.
-            baseline_name += "-1"
-            target_name += "-2"
-
-    set_output("baseline-analysis", baseline_name + ".json")
-    set_output("baseline-setup-cmd", baseline_cmd)
-    set_output("target-analysis", target_name + ".json")
-    set_output("target-setup-cmd", target_cmd)
+    env = f"{platform.system()}-{platform.python_version()}-{diff_shades.__version__}"
+    for entry in jobs:
+        entry["baseline-analysis"] = f"{entry['mode']}-{baseline_name}.json"
+        entry["baseline-setup-cmd"] = baseline_cmd
+        entry["target-analysis"] = f"{entry['mode']}-{target_name}.json"
+        entry["target-setup-cmd"] = target_cmd
+        entry["baseline-cache-key"] = f"{env}-{baseline_name}-{entry['mode']}"
+        if event == "pull_request":
+            # These are only needed for the PR comment.
+            entry["baseline-sha"] = baseline_rev
+            entry["target-sha"] = pr_rev
 
-    key = f"{platform.system()}-{platform.python_version()}-{diff_shades.__version__}"
-    key += f"-{baseline_name}-{baseline_args.encode('utf-8').hex()}"
-    set_output("baseline-cache-key", key)
+    set_output("matrix", json.dumps(jobs, indent=None))
+    pprint.pprint(jobs)
 
 
 @main.command("comment-body", help="Generate the body for a summary PR comment.")
@@ -238,15 +199,13 @@ def comment_details(run_id: str) -> None:
 
     set_output("needs-comment", "true")
     jobs = http_get(data["jobs_url"])["jobs"]
-    assert len(jobs) == 1, "multiple jobs not supported nor tested"
-    job = jobs[0]
-    steps = {s["name"]: s["number"] for s in job["steps"]}
-    diff_step = steps[DIFF_STEP_NAME]
-    diff_url = job["html_url"] + f"#step:{diff_step}:1"
-
-    artifacts_data = http_get(data["artifacts_url"])["artifacts"]
-    artifacts = {a["name"]: a["archive_download_url"] for a in artifacts_data}
-    comment_url = artifacts[COMMENT_FILE]
+    job = next(j for j in jobs if j["name"] == "analysis / preview-changes")
+    diff_step = next(s for s in job["steps"] if s["name"] == DIFF_STEP_NAME)
+    diff_url = job["html_url"] + f"#step:{diff_step['number']}:1"
+
+    artifacts = http_get(data["artifacts_url"])["artifacts"]
+    comment_artifact = next(a for a in artifacts if a["name"] == COMMENT_FILE)
+    comment_url = comment_artifact["archive_download_url"]
     comment_zip = BytesIO(http_get(comment_url, is_json=False))
     with zipfile.ZipFile(comment_zip) as zfile:
         with zfile.open(COMMENT_FILE) as rf:
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 51e31e9598b..a82cf6a6cd7 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -697,6 +697,9 @@ def reformat_code(
         report.failed(path, str(exc))
 
 
+# diff-shades depends on being to monkeypatch this function to operate. I know it's
+# not ideal, but this shouldn't cause any issues ... hopefully. ~ichard26
+@mypyc_attr(patchable=True)
 def reformat_one(
     src: Path, fast: bool, write_back: WriteBack, mode: Mode, report: "Report"
 ) -> None:

From ac7402cbf6a0deb5c74e9abcffc5bd7b1148fda5 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 28 Mar 2022 13:21:13 -0400
Subject: [PATCH 0500/1034] Bump sphinx from 4.4.0 to 4.5.0 in /docs (GH-2959)

Bumps [sphinx](https://github.com/sphinx-doc/sphinx) from 4.4.0 to 4.5.0.
- [Release notes](https://github.com/sphinx-doc/sphinx/releases)
- [Changelog](https://github.com/sphinx-doc/sphinx/blob/4.x/CHANGES)
- [Commits](https://github.com/sphinx-doc/sphinx/compare/v4.4.0...v4.5.0)

---
updated-dependencies:
- dependency-name: sphinx
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 docs/requirements.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index 5ca7a6f1cf7..63c9c8f9edb 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,7 +1,7 @@
 # Used by ReadTheDocs; pinned requirements for stability.
 
 myst-parser==0.16.1
-Sphinx==4.4.0
+Sphinx==4.5.0
 sphinxcontrib-programoutput==0.17
 sphinx_copybutton==0.5.0
 furo==2022.3.4

From e9681a40dcb3d38b56b301d811bb1c55201fd97e Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Mon, 28 Mar 2022 12:01:13 -0700
Subject: [PATCH 0501/1034] Fix _unicodefun patch code for Click 8.1.0 (#2966)

Fixes #2964
---
 .github/workflows/diff_shades.yml |  4 ++--
 CHANGES.md                        |  1 +
 src/black/__init__.py             | 14 +++++++++++---
 tests/test_black.py               |  2 +-
 4 files changed, 15 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/diff_shades.yml b/.github/workflows/diff_shades.yml
index 51fcebcff63..0529b137572 100644
--- a/.github/workflows/diff_shades.yml
+++ b/.github/workflows/diff_shades.yml
@@ -24,7 +24,7 @@ jobs:
 
       - name: Install diff-shades and support dependencies
         run: |
-          python -m pip install click packaging urllib3
+          python -m pip install 'click<8.1.0' packaging urllib3
           python -m pip install https://github.com/ichard26/diff-shades/archive/stable.zip
 
       - name: Calculate run configuration & metadata
@@ -59,7 +59,7 @@ jobs:
       - name: Install diff-shades and support dependencies
         run: |
           python -m pip install https://github.com/ichard26/diff-shades/archive/stable.zip
-          python -m pip install click packaging urllib3
+          python -m pip install 'click<8.1.0' packaging urllib3
           python -m pip install -r .github/mypyc-requirements.txt
           # After checking out old revisions, this might not exist so we'll use a copy.
           cat scripts/diff_shades_gha_helper.py > helper.py
diff --git a/CHANGES.md b/CHANGES.md
index d34bd4ead58..02327fcbee9 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -55,6 +55,7 @@
 
 <!-- Changes to how Black is packaged, such as dependency requirements -->
 
+- Fix Black to work with Click 8.1.0 (#2966)
 - On Python 3.11 and newer, use the standard library's `tomllib` instead of `tomli`
   (#2903)
 - `black-primer`, the deprecated internal devtool, has been removed and copied to a
diff --git a/src/black/__init__.py b/src/black/__init__.py
index a82cf6a6cd7..e9d3c1b795a 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -1427,13 +1427,21 @@ def patch_click() -> None:
     file paths is minimal since it's Python source code.  Moreover, this crash was
     spurious on Python 3.7 thanks to PEP 538 and PEP 540.
     """
+    modules: List[Any] = []
     try:
         from click import core
+    except ImportError:
+        pass
+    else:
+        modules.append(core)
+    try:
         from click import _unicodefun
-    except ModuleNotFoundError:
-        return
+    except ImportError:
+        pass
+    else:
+        modules.append(_unicodefun)
 
-    for module in (core, _unicodefun):
+    for module in modules:
         if hasattr(module, "_verify_python3_env"):
             module._verify_python3_env = lambda: None  # type: ignore
         if hasattr(module, "_verify_python_env"):
diff --git a/tests/test_black.py b/tests/test_black.py
index b1bf1772550..ce7bab2f440 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -1257,7 +1257,7 @@ def test_assert_equivalent_different_asts(self) -> None:
     def test_shhh_click(self) -> None:
         try:
             from click import _unicodefun
-        except ModuleNotFoundError:
+        except ImportError:
             self.skipTest("Incompatible Click version")
         if not hasattr(_unicodefun, "_verify_python3_env"):
             self.skipTest("Incompatible Click version")

From ae2c0758c9e61a385df9700dc9c231bf54887041 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Mon, 28 Mar 2022 12:08:29 -0700
Subject: [PATCH 0502/1034] Prepare release 22.3.0 (#2968)

---
 CHANGES.md                                  | 57 +++++++++++++--------
 docs/integrations/source_version_control.md |  2 +-
 docs/usage_and_configuration/the_basics.md  |  2 +-
 3 files changed, 39 insertions(+), 22 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 02327fcbee9..f68bc8f1a99 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -14,11 +14,6 @@
 
 <!-- Changes that affect Black's preview style -->
 
-- Code cell separators `#%%` are now standardised to `# %%` (#2919)
-- Remove unnecessary parentheses from `except` statements (#2939)
-- Remove unnecessary parentheses from tuple unpacking in `for` loops (#2945)
-- Avoid magic-trailing-comma in single-element subscripts (#2942)
-
 ### _Blackd_
 
 <!-- Changes to blackd -->
@@ -27,34 +22,62 @@
 
 <!-- Changes to how Black can be configured -->
 
+### Documentation
+
+<!-- Major changes to documentation and policies. Small docs changes
+     don't need a changelog entry. -->
+
+### Integrations
+
+<!-- For example, Docker, GitHub Actions, pre-commit, editors -->
+
+### Output
+
+<!-- Changes to Black's terminal output and error messages -->
+
+### Packaging
+
+<!-- Changes to how Black is packaged, such as dependency requirements -->
+
+### Parser
+
+<!-- Changes to the parser or to version autodetection -->
+
+### Performance
+
+<!-- Changes that improve Black's performance. -->
+
+## 22.3.0
+
+### Preview style
+
+- Code cell separators `#%%` are now standardised to `# %%` (#2919)
+- Remove unnecessary parentheses from `except` statements (#2939)
+- Remove unnecessary parentheses from tuple unpacking in `for` loops (#2945)
+- Avoid magic-trailing-comma in single-element subscripts (#2942)
+
+### Configuration
+
 - Do not format `__pypackages__` directories by default (#2836)
 - Add support for specifying stable version with `--required-version` (#2832).
 - Avoid crashing when the user has no homedir (#2814)
 - Avoid crashing when md5 is not available (#2905)
+- Fix handling of directory junctions on Windows (#2904)
 
 ### Documentation
 
-<!-- Major changes to documentation and policies. Small docs changes
-     don't need a changelog entry. -->
-
 - Update pylint config documentation (#2931)
 
 ### Integrations
 
-<!-- For example, Docker, GitHub Actions, pre-commit, editors -->
-
 - Move test to disable plugin in Vim/Neovim, which speeds up loading (#2896)
 
 ### Output
 
-<!-- Changes to Black's terminal output and error messages -->
-
 - In verbose, mode, log when _Black_ is using user-level config (#2861)
 
 ### Packaging
 
-<!-- Changes to how Black is packaged, such as dependency requirements -->
-
 - Fix Black to work with Click 8.1.0 (#2966)
 - On Python 3.11 and newer, use the standard library's `tomllib` instead of `tomli`
   (#2903)
@@ -66,12 +89,6 @@
 - Black can now parse starred expressions in the target of `for` and `async for`
   statements, e.g `for item in *items_1, *items_2: pass` (#2879).
 
-- Fix handling of directory junctions on Windows (#2904)
-
-### Performance
-
-<!-- Changes that improve Black's performance. -->
-
 ## 22.1.0
 
 At long last, _Black_ is no longer a beta product! This is the first non-beta release
diff --git a/docs/integrations/source_version_control.md b/docs/integrations/source_version_control.md
index 7215e111f5c..d7d3da47630 100644
--- a/docs/integrations/source_version_control.md
+++ b/docs/integrations/source_version_control.md
@@ -7,7 +7,7 @@ Use [pre-commit](https://pre-commit.com/). Once you
 ```yaml
 repos:
   - repo: https://github.com/psf/black
-    rev: 22.1.0
+    rev: 22.3.0
     hooks:
       - id: black
         # It is recommended to specify the latest version of Python
diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index 48dda3ba036..4c793f459a2 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -173,7 +173,7 @@ You can check the version of _Black_ you have installed using the `--version` fl
 
 ```console
 $ black --version
-black, version 22.1.0
+black, version 22.3.0
 ```
 
 An option to require a specific version to be running is also provided.

From 2d62a09e838d2df98961e6e93036abad54f28c5f Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 28 Mar 2022 21:42:53 -0400
Subject: [PATCH 0503/1034] Bump actions/cache from 2.1.7 to 3 (GH-2962)

Bumps [actions/cache](https://github.com/actions/cache) from 2.1.7 to 3.
- [Release notes](https://github.com/actions/cache/releases)
- [Commits](https://github.com/actions/cache/compare/v2.1.7...v3)

---
updated-dependencies:
- dependency-name: actions/cache
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/diff_shades.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/diff_shades.yml b/.github/workflows/diff_shades.yml
index 0529b137572..611d8bc13dd 100644
--- a/.github/workflows/diff_shades.yml
+++ b/.github/workflows/diff_shades.yml
@@ -68,7 +68,7 @@ jobs:
 
       - name: Attempt to use cached baseline analysis
         id: baseline-cache
-        uses: actions/cache@v2.1.7
+        uses: actions/cache@v3
         with:
           path: ${{ matrix.baseline-analysis }}
           key: ${{ matrix.baseline-cache-key }}

From 82e150a13ac78a1f24de27977d8a40883bc3d6e7 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Wed, 30 Mar 2022 16:40:50 -0400
Subject: [PATCH 0504/1034] Keep tests working w/ upcoming aiohttp 4.0.0
 (#2974)

aiohttp.test_utils.unittest_run_loop was deprecated since aiohttp 3.8
and aiohttp 4 (which isn't a thing quite yet) removes it. To maintain
compatibility with the full range of versions we declare to support,
test_blackd.py will now define a no-op replacement if it can't be
imported.

Also, mypy is painfully slow to use without a cache, let's reenable it.
---
 mypy.ini             |  3 ---
 tests/test_blackd.py | 15 +++++++++++----
 2 files changed, 11 insertions(+), 7 deletions(-)

diff --git a/mypy.ini b/mypy.ini
index 3bb92a659ff..8ee9068d10b 100644
--- a/mypy.ini
+++ b/mypy.ini
@@ -32,9 +32,6 @@ warn_unreachable=True
 disallow_untyped_defs=True
 check_untyped_defs=True
 
-# No incremental mode
-cache_dir=/dev/null
-
 [mypy-black]
 # The following is because of `patch_click()`. Remove when
 # we drop Python 3.6 support.
diff --git a/tests/test_blackd.py b/tests/test_blackd.py
index 37431fcad00..6174c4538b9 100644
--- a/tests/test_blackd.py
+++ b/tests/test_blackd.py
@@ -1,4 +1,5 @@
 import re
+from typing import Any
 from unittest.mock import patch
 
 from click.testing import CliRunner
@@ -8,12 +9,18 @@
 
 try:
     import blackd
-    from aiohttp.test_utils import AioHTTPTestCase, unittest_run_loop
+    from aiohttp.test_utils import AioHTTPTestCase
     from aiohttp import web
+except ImportError as e:
+    raise RuntimeError("Please install Black with the 'd' extra") from e
+
+try:
+    from aiohttp.test_utils import unittest_run_loop
 except ImportError:
-    has_blackd_deps = False
-else:
-    has_blackd_deps = True
+    # unittest_run_loop is unnecessary and a no-op since aiohttp 3.8, and aiohttp 4
+    # removed it. To maintain compatibility we can make our own no-op decorator.
+    def unittest_run_loop(func: Any, *args: Any, **kwargs: Any) -> Any:
+        return func
 
 
 @pytest.mark.blackd

From 3dea6e363562050ae032c80a648bd88fc49381bc Mon Sep 17 00:00:00 2001
From: "Gunung P. Wibisono" <55311527+gunungpw@users.noreply.github.com>
Date: Thu, 31 Mar 2022 03:43:46 +0700
Subject: [PATCH 0505/1034] Convert `index.rst` and `license.rst` to markdown
 (#2852)

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 docs/conf.py                           |   4 +
 docs/contributing/index.md             |  49 +++++++++
 docs/contributing/index.rst            |  43 --------
 docs/guides/index.md                   |  16 +++
 docs/guides/index.rst                  |  14 ---
 docs/index.md                          | 139 +++++++++++++++++++++++++
 docs/index.rst                         | 131 -----------------------
 docs/integrations/index.md             |  31 ++++++
 docs/integrations/index.rst            |  28 -----
 docs/license.md                        |   9 ++
 docs/license.rst                       |   6 --
 docs/the_black_code_style/index.md     |  47 +++++++++
 docs/the_black_code_style/index.rst    |  47 ---------
 docs/usage_and_configuration/index.md  |  28 +++++
 docs/usage_and_configuration/index.rst |  26 -----
 15 files changed, 323 insertions(+), 295 deletions(-)
 create mode 100644 docs/contributing/index.md
 delete mode 100644 docs/contributing/index.rst
 create mode 100644 docs/guides/index.md
 delete mode 100644 docs/guides/index.rst
 create mode 100644 docs/index.md
 delete mode 100644 docs/index.rst
 create mode 100644 docs/integrations/index.md
 delete mode 100644 docs/integrations/index.rst
 create mode 100644 docs/license.md
 delete mode 100644 docs/license.rst
 create mode 100644 docs/the_black_code_style/index.md
 delete mode 100644 docs/the_black_code_style/index.rst
 create mode 100644 docs/usage_and_configuration/index.md
 delete mode 100644 docs/usage_and_configuration/index.rst

diff --git a/docs/conf.py b/docs/conf.py
index 2801e0eed19..e9fdebb5546 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -105,11 +105,15 @@ def make_pypi_svg(version: str) -> None:
 # Prettier support formatting some MyST syntax but not all, so let's disable the
 # unsupported yet still enabled by default ones.
 myst_disable_syntax = [
+    "colon_fence",
     "myst_block_break",
     "myst_line_comment",
     "math_block",
 ]
 
+# Optional MyST Syntaxes
+myst_enable_extensions = []
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
diff --git a/docs/contributing/index.md b/docs/contributing/index.md
new file mode 100644
index 00000000000..f56e57c9e90
--- /dev/null
+++ b/docs/contributing/index.md
@@ -0,0 +1,49 @@
+# Contributing
+
+```{toctree}
+---
+hidden:
+---
+
+the_basics
+gauging_changes
+issue_triage
+release_process
+reference/reference_summary
+```
+
+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?
+
+```{rubric} Bird's eye view
+
+```
+
+In terms of inspiration, _Black_ is about as configurable as _gofmt_ (which is to say,
+not very). This is deliberate. _Black_ aims to provide a consistent style and take away
+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.
+
+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
+up, and so on - go for it! On the other hand, if your answer is "because I don't like a
+particular formatting" then you're not ready to embrace _Black_ yet. Such changes are
+unlikely to get accepted. You can still try but prepare to be disappointed.
+
+```{rubric} Contents
+
+```
+
+This section covers the following topics:
+
+- {doc}`the_basics`
+- {doc}`gauging_changes`
+- {doc}`release_process`
+- {doc}`reference/reference_summary`
+
+For an overview on contributing to the _Black_, please checkout {doc}`the_basics`.
+
+If you need a reference of the functions, classes, etc. available to you while
+developing _Black_, there's the {doc}`reference/reference_summary` docs.
diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst
deleted file mode 100644
index 480dbd6cd0e..00000000000
--- a/docs/contributing/index.rst
+++ /dev/null
@@ -1,43 +0,0 @@
-Contributing
-============
-
-.. toctree::
-  :hidden:
-
-  the_basics
-  gauging_changes
-  issue_triage
-  release_process
-  reference/reference_summary
-
-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?
-
-.. rubric:: Bird's eye view
-
-In terms of inspiration, *Black* is about as configurable as *gofmt* (which is to say,
-not very). This is deliberate. *Black* aims to provide a consistent style and take away
-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.
-
-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
-up, and so on - go for it! On the other hand, if your answer is "because I don't like a
-particular formatting" then you're not ready to embrace *Black* yet. Such changes are
-unlikely to get accepted. You can still try but prepare to be disappointed.
-
-.. rubric:: Contents
-
-This section covers the following topics:
-
-- :doc:`the_basics`
-- :doc:`gauging_changes`
-- :doc:`release_process`
-- :doc:`reference/reference_summary`
-
-For an overview on contributing to the *Black*, please checkout :doc:`the_basics`.
-
-If you need a reference of the functions, classes, etc. available to you while
-developing *Black*, there's the :doc:`reference/reference_summary` docs.
diff --git a/docs/guides/index.md b/docs/guides/index.md
new file mode 100644
index 00000000000..127279b5e81
--- /dev/null
+++ b/docs/guides/index.md
@@ -0,0 +1,16 @@
+# Guides
+
+```{toctree}
+---
+hidden:
+---
+
+introducing_black_to_your_project
+using_black_with_other_tools
+```
+
+Wondering how to do something specific? You've found the right place! Listed below are
+topic specific guides available:
+
+- {doc}`introducing_black_to_your_project`
+- {doc}`using_black_with_other_tools`
diff --git a/docs/guides/index.rst b/docs/guides/index.rst
deleted file mode 100644
index 717c5c4d066..00000000000
--- a/docs/guides/index.rst
+++ /dev/null
@@ -1,14 +0,0 @@
-Guides
-======
-
-.. toctree::
-  :hidden:
-
-  introducing_black_to_your_project
-  using_black_with_other_tools
-
-Wondering how to do something specific? You've found the right place! Listed below
-are topic specific guides available:
-
-- :doc:`introducing_black_to_your_project`
-- :doc:`using_black_with_other_tools`
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 00000000000..9d0db465022
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,139 @@
+<!--
+black documentation master file, created by
+sphinx-quickstart on Fri Mar 23 10:53:30 2018.
+-->
+
+# The uncompromising code formatter
+
+> “Any color you like.”
+
+By using _Black_, you agree to cede control over minutiae of hand-formatting. In return,
+_Black_ gives you speed, determinism, and freedom from `pycodestyle` nagging about
+formatting. You will save time and mental energy for more important matters.
+
+_Black_ makes code review faster by producing the smallest diffs possible. Blackened
+code looks the same regardless of the project you're reading. Formatting becomes
+transparent after a while and you can focus on the content instead.
+
+Try it out now using the [Black Playground](https://black.vercel.app).
+
+```{admonition} Note - Black is now stable!
+*Black* is [successfully used](https://github.com/psf/black#used-by) by
+many projects, small and big. *Black* has a comprehensive test suite, with efficient
+parallel tests, our own auto formatting and parallel Continuous Integration runner.
+Now that we have become stable, you should not expect large formatting to changes in
+the future. Stylistic changes will mostly be responses to bug reports and support for new Python
+syntax.
+
+Also, as a safety measure which slows down processing, *Black* will check that the
+reformatted code still produces a valid AST that is effectively equivalent to the
+original (see the
+[Pragmatism](./the_black_code_style/current_style.md#pragmatism)
+section for details). If you're feeling confident, use `--fast`.
+```
+
+```{note}
+{doc}`Black is licensed under the MIT license <license>`.
+```
+
+## Testimonials
+
+**Mike Bayer**, author of [SQLAlchemy](https://www.sqlalchemy.org/):
+
+> _I can't think of any single tool in my entire programming career that has given me a
+> bigger productivity increase by its introduction. I can now do refactorings in about
+> 1% of the keystrokes that it would have taken me previously when we had no way for
+> code to format itself._
+
+**Dusty Phillips**,
+[writer](https://smile.amazon.com/s/ref=nb_sb_noss?url=search-alias%3Daps&field-keywords=dusty+phillips):
+
+> _Black is opinionated so you don't have to be._
+
+**Hynek Schlawack**, creator of [attrs](https://www.attrs.org/), core developer of
+Twisted and CPython:
+
+> _An auto-formatter that doesn't suck is all I want for Xmas!_
+
+**Carl Meyer**, [Django](https://www.djangoproject.com/) core developer:
+
+> _At least the name is good._
+
+**Kenneth Reitz**, creator of [requests](http://python-requests.org/) and
+[pipenv](https://docs.pipenv.org/):
+
+> _This vastly improves the formatting of our code. Thanks a ton!_
+
+## Show your style
+
+Use the badge in your project's README.md:
+
+```md
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+```
+
+Using the badge in README.rst:
+
+```rst
+.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
+   :target: https://github.com/psf/black
+```
+
+Looks like this:
+
+```{image} https://img.shields.io/badge/code%20style-black-000000.svg
+:target: https://github.com/psf/black
+```
+
+## Contents
+
+```{toctree}
+---
+maxdepth: 3
+includehidden:
+---
+
+the_black_code_style/index
+```
+
+```{toctree}
+---
+maxdepth: 3
+includehidden:
+caption: User Guide
+---
+
+getting_started
+usage_and_configuration/index
+integrations/index
+guides/index
+faq
+```
+
+```{toctree}
+---
+maxdepth: 2
+includehidden:
+caption: Development
+---
+
+contributing/index
+change_log
+authors
+```
+
+```{toctree}
+---
+hidden:
+caption: Project Links
+---
+
+GitHub <https://github.com/psf/black>
+PyPI <https://pypi.org/project/black>
+Chat <https://discord.gg/RtVdv86PrH>
+```
+
+# Indices and tables
+
+- {ref}`genindex`
+- {ref}`search`
diff --git a/docs/index.rst b/docs/index.rst
deleted file mode 100644
index 8a8da0d6127..00000000000
--- a/docs/index.rst
+++ /dev/null
@@ -1,131 +0,0 @@
-.. black documentation master file, created by
-   sphinx-quickstart on Fri Mar 23 10:53:30 2018.
-
-The uncompromising code formatter
-=================================
-
-    “Any color you like.”
-
-By using *Black*, you agree to cede control over minutiae of
-hand-formatting. In return, *Black* gives you speed, determinism, and
-freedom from `pycodestyle` nagging about formatting. You will save time
-and mental energy for more important matters.
-
-*Black* makes code review faster by producing the smallest diffs
-possible. Blackened code looks the same regardless of the project
-you're reading. Formatting becomes transparent after a while and you
-can focus on the content instead.
-
-Try it out now using the `Black Playground <https://black.vercel.app>`_.
-
-.. admonition:: Note - Black is now stable!
-
-   *Black* is `successfully used <https://github.com/psf/black#used-by>`_ by
-   many projects, small and big. *Black* has a comprehensive test suite, with efficient
-   parallel tests, our own auto formatting and parallel Continuous Integration runner.
-   Now that we have become stable, you should not expect large formatting to changes in
-   the future. Stylistic changes will mostly be responses to bug reports and support for new Python
-   syntax.
-
-   Also, as a safety measure which slows down processing, *Black* will check that the
-   reformatted code still produces a valid AST that is effectively equivalent to the
-   original (see the
-   `Pragmatism <./the_black_code_style/current_style.html#pragmatism>`_
-   section for details). If you're feeling confident, use ``--fast``.
-
-.. note::
-   :doc:`Black is licensed under the MIT license <license>`.
-
-Testimonials
-------------
-
-**Mike Bayer**, author of `SQLAlchemy <https://www.sqlalchemy.org/>`_:
-
-   *I can't think of any single tool in my entire programming career that has given me a
-   bigger productivity increase by its introduction. I can now do refactorings in about
-   1% of the keystrokes that it would have taken me previously when we had no way for
-   code to format itself.*
-
-**Dusty Phillips**, `writer <https://smile.amazon.com/s/ref=nb_sb_noss?url=search-alias%3Daps&field-keywords=dusty+phillips>`_:
-
-   *Black is opinionated so you don't have to be.*
-
-**Hynek Schlawack**, creator of `attrs <https://www.attrs.org/>`_, core
-developer of Twisted and CPython:
-
-   *An auto-formatter that doesn't suck is all I want for Xmas!*
-
-**Carl Meyer**, `Django <https://www.djangoproject.com/>`_ core developer:
-
-   *At least the name is good.*
-
-**Kenneth Reitz**, creator of `requests <http://python-requests.org/>`_
-and `pipenv <https://docs.pipenv.org/>`_:
-
-   *This vastly improves the formatting of our code. Thanks a ton!*
-
-
-Show your style
----------------
-
-Use the badge in your project's README.md:
-
-.. code-block:: md
-
-   [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
-
-
-Using the badge in README.rst:
-
-.. code-block:: rst
-
-   .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
-      :target: https://github.com/psf/black
-
-Looks like this:
-
-.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
-   :target: https://github.com/psf/black
-
-Contents
---------
-
-.. toctree::
-   :maxdepth: 3
-   :includehidden:
-
-   the_black_code_style/index
-
-.. toctree::
-   :maxdepth: 3
-   :includehidden:
-   :caption: User Guide
-
-   getting_started
-   usage_and_configuration/index
-   integrations/index
-   guides/index
-   faq
-
-.. toctree::
-   :maxdepth: 2
-   :includehidden:
-   :caption: Development
-
-   contributing/index
-   change_log
-   authors
-
-.. toctree::
-   :hidden:
-   :caption: Project Links
-
-   GitHub <https://github.com/psf/black>
-   PyPI <https://pypi.org/project/black>
-   Chat <https://discord.gg/RtVdv86PrH>
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`search`
diff --git a/docs/integrations/index.md b/docs/integrations/index.md
new file mode 100644
index 00000000000..33135d08f1a
--- /dev/null
+++ b/docs/integrations/index.md
@@ -0,0 +1,31 @@
+# Integrations
+
+```{toctree}
+---
+hidden:
+---
+
+editors
+github_actions
+source_version_control
+```
+
+_Black_ can be integrated into many environments, providing a better and smoother
+experience. Documentation for integrating _Black_ with a tool can be found for the
+following areas:
+
+- {doc}`Editor / IDE <./editors>`
+- {doc}`GitHub Actions <./github_actions>`
+- {doc}`Source version control <./source_version_control>`
+
+Editors and tools not listed will require external contributions.
+
+Patches welcome! ✨ 🍰 ✨
+
+Any tool can pipe code through _Black_ using its stdio mode (just
+[use `-` as the file name](https://www.tldp.org/LDP/abs/html/special-chars.html#DASHREF2)).
+The formatted code will be returned on stdout (unless `--check` was passed). _Black_
+will still emit messages on stderr but that shouldn't affect your use case.
+
+This can be used for example with PyCharm's or IntelliJ's
+[File Watchers](https://www.jetbrains.com/help/pycharm/file-watchers.html).
diff --git a/docs/integrations/index.rst b/docs/integrations/index.rst
deleted file mode 100644
index ed62ebcf044..00000000000
--- a/docs/integrations/index.rst
+++ /dev/null
@@ -1,28 +0,0 @@
-Integrations
-============
-
-.. toctree::
-    :hidden:
-
-    editors
-    github_actions
-    source_version_control
-
-*Black* can be integrated into many environments, providing a better and smoother experience. Documentation for integrating *Black* with a tool can be found for the
-following areas:
-
-- :doc:`Editor / IDE <./editors>`
-- :doc:`GitHub Actions <./github_actions>`
-- :doc:`Source version control <./source_version_control>`
-
-Editors and tools not listed will require external contributions.
-
-Patches welcome! ✨ 🍰 ✨
-
-Any tool can pipe code through *Black* using its stdio mode (just
-`use \`-\` as the file name <https://www.tldp.org/LDP/abs/html/special-chars.html#DASHREF2>`_).
-The formatted code will be returned on stdout (unless ``--check`` was passed). *Black*
-will still emit messages on stderr but that shouldn't affect your use case.
-
-This can be used for example with PyCharm's or IntelliJ's
-`File Watchers <https://www.jetbrains.com/help/pycharm/file-watchers.html>`_.
diff --git a/docs/license.md b/docs/license.md
new file mode 100644
index 00000000000..132c95bfe2a
--- /dev/null
+++ b/docs/license.md
@@ -0,0 +1,9 @@
+---
+orphan: true
+---
+
+# License
+
+```{include} ../LICENSE
+
+```
diff --git a/docs/license.rst b/docs/license.rst
deleted file mode 100644
index 2dc20a24492..00000000000
--- a/docs/license.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-:orphan:
-
-License
-=======
-
-.. include:: ../LICENSE
diff --git a/docs/the_black_code_style/index.md b/docs/the_black_code_style/index.md
new file mode 100644
index 00000000000..d1508552fee
--- /dev/null
+++ b/docs/the_black_code_style/index.md
@@ -0,0 +1,47 @@
+# The Black Code Style
+
+```{toctree}
+---
+hidden:
+---
+
+Current style <current_style>
+Future style <future_style>
+```
+
+_Black_ is a PEP 8 compliant opinionated formatter with its own style.
+
+While keeping the style unchanged throughout releases has always been a goal, the
+_Black_ code style isn't set in stone. It evolves to accommodate for new features in the
+Python language and, occasionally, in response to user feedback. Large-scale style
+preferences presented in {doc}`current_style` are very unlikely to change, but minor
+style aspects and details might change according to the stability policy presented
+below. Ongoing style considerations are tracked on GitHub with the
+[design](https://github.com/psf/black/labels/T%3A%20design) issue label.
+
+## Stability Policy
+
+The following policy applies for the _Black_ code style, in non pre-release versions of
+_Black_:
+
+- The same code, formatted with the same options, will produce the same output for all
+  releases in a given calendar year.
+
+  This means projects can safely use `black ~= 22.0` without worrying about major
+  formatting changes disrupting their project in 2022. We may still fix bugs where
+  _Black_ crashes on some code, and make other improvements that do not affect
+  formatting.
+
+- The first release in a new calendar year _may_ contain formatting changes, although
+  these will be minimised as much as possible. This is to allow for improved formatting
+  enabled by newer Python language syntax as well as due to improvements in the
+  formatting logic.
+
+- The `--preview` flag is exempt from this policy. There are no guarantees around the
+  stability of the output with that flag passed into _Black_. This flag is intended for
+  allowing experimentation with the proposed changes to the _Black_ code style.
+
+Documentation for both the current and future styles can be found:
+
+- {doc}`current_style`
+- {doc}`future_style`
diff --git a/docs/the_black_code_style/index.rst b/docs/the_black_code_style/index.rst
deleted file mode 100644
index 511a6ecf099..00000000000
--- a/docs/the_black_code_style/index.rst
+++ /dev/null
@@ -1,47 +0,0 @@
-The Black Code Style
-====================
-
-.. toctree::
-    :hidden:
-
-    Current style <current_style>
-    Future style <future_style>
-
-*Black* is a PEP 8 compliant opinionated formatter with its own style.
-
-While keeping the style unchanged throughout releases has always been a goal,
-the *Black* code style isn't set in stone. It evolves to accommodate for new features
-in the Python language and, occasionally, in response to user feedback.
-Large-scale style preferences presented in :doc:`current_style` are very unlikely to
-change, but minor style aspects and details might change according to the stability
-policy presented below. Ongoing style considerations are tracked on GitHub with the
-`design <https://github.com/psf/black/labels/T%3A%20design>`_ issue label.
-
-Stability Policy
-----------------
-
-The following policy applies for the *Black* code style, in non pre-release
-versions of *Black*:
-
-- The same code, formatted with the same options, will produce the same
-  output for all releases in a given calendar year.
-
-  This means projects can safely use `black ~= 22.0` without worrying about
-  major formatting changes disrupting their project in 2022. We may still
-  fix bugs where *Black* crashes on some code, and make other improvements
-  that do not affect formatting.
-
-- The first release in a new calendar year *may* contain formatting changes,
-  although these will be minimised as much as possible. This is to allow for
-  improved formatting enabled by newer Python language syntax as well as due
-  to improvements in the formatting logic.
-
-- The ``--preview`` flag is exempt from this policy. There are no guarantees
-  around the stability of the output with that flag passed into *Black*. This
-  flag is intended for allowing experimentation with the proposed changes to
-  the *Black* code style.
-
-Documentation for both the current and future styles can be found:
-
-- :doc:`current_style`
-- :doc:`future_style`
diff --git a/docs/usage_and_configuration/index.md b/docs/usage_and_configuration/index.md
new file mode 100644
index 00000000000..1c86a49b686
--- /dev/null
+++ b/docs/usage_and_configuration/index.md
@@ -0,0 +1,28 @@
+# Usage and Configuration
+
+```{toctree}
+---
+hidden:
+---
+
+the_basics
+file_collection_and_discovery
+black_as_a_server
+black_docker_image
+```
+
+Sometimes, running _Black_ with its defaults and passing filepaths to it just won't cut
+it. Passing each file using paths will become burdensome, and maybe you would like
+_Black_ to not touch your files and just output diffs. And yes, you _can_ tweak certain
+parts of _Black_'s style, but please know that configurability in this area is
+purposefully limited.
+
+Using many of these more advanced features of _Black_ will require some configuration.
+Configuration that will either live on the command line or in a TOML configuration file.
+
+This section covers features of _Black_ and configuring _Black_ in detail:
+
+- {doc}`The basics <./the_basics>`
+- {doc}`File collection and discovery <file_collection_and_discovery>`
+- {doc}`Black as a server (blackd) <./black_as_a_server>`
+- {doc}`Black Docker image <./black_docker_image>`
diff --git a/docs/usage_and_configuration/index.rst b/docs/usage_and_configuration/index.rst
deleted file mode 100644
index f6152eec90c..00000000000
--- a/docs/usage_and_configuration/index.rst
+++ /dev/null
@@ -1,26 +0,0 @@
-Usage and Configuration
-=======================
-
-.. toctree::
-  :hidden:
-
-  the_basics
-  file_collection_and_discovery
-  black_as_a_server
-  black_docker_image
-
-Sometimes, running *Black* with its defaults and passing filepaths to it just won't cut
-it. Passing each file using paths will become burdensome, and maybe you would like
-*Black* to not touch your files and just output diffs. And yes, you *can* tweak certain
-parts of *Black*'s style, but please know that configurability in this area is
-purposefully limited.
-
-Using many of these more advanced features of *Black* will require some configuration.
-Configuration that will either live on the command line or in a TOML configuration file.
-
-This section covers features of *Black* and configuring *Black* in detail:
-
-- :doc:`The basics <./the_basics>`
-- :doc:`File collection and discovery <file_collection_and_discovery>`
-- :doc:`Black as a server (blackd) <./black_as_a_server>`
-- :doc:`Black Docker image <./black_docker_image>`

From a66016cb949590863d11e329e65bbb383727125e Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Wed, 30 Mar 2022 14:01:03 -0700
Subject: [PATCH 0506/1034] Add # type: ignore for click._unicodefun import
 (#2981)

---
 src/black/__init__.py | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index e9d3c1b795a..bdeb73273bc 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -1435,7 +1435,9 @@ def patch_click() -> None:
     else:
         modules.append(core)
     try:
-        from click import _unicodefun
+        # Removed in Click 8.1.0 and newer; we keep this around for users who have
+        # older versions installed.
+        from click import _unicodefun  # type: ignore
     except ImportError:
         pass
     else:

From def048356bb31474c3316f758503742773265bbf Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Wed, 30 Mar 2022 14:33:16 -0700
Subject: [PATCH 0507/1034] Remove click pin in diff-shades workflow (#2979)

Click 8.1.1 was released with a fix for pallets/click#2227.
---
 .github/workflows/diff_shades.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/diff_shades.yml b/.github/workflows/diff_shades.yml
index 611d8bc13dd..ade71e7aa8d 100644
--- a/.github/workflows/diff_shades.yml
+++ b/.github/workflows/diff_shades.yml
@@ -24,7 +24,7 @@ jobs:
 
       - name: Install diff-shades and support dependencies
         run: |
-          python -m pip install 'click<8.1.0' packaging urllib3
+          python -m pip install click packaging urllib3
           python -m pip install https://github.com/ichard26/diff-shades/archive/stable.zip
 
       - name: Calculate run configuration & metadata
@@ -59,7 +59,7 @@ jobs:
       - name: Install diff-shades and support dependencies
         run: |
           python -m pip install https://github.com/ichard26/diff-shades/archive/stable.zip
-          python -m pip install 'click<8.1.0' packaging urllib3
+          python -m pip install click packaging urllib3
           python -m pip install -r .github/mypyc-requirements.txt
           # After checking out old revisions, this might not exist so we'll use a copy.
           cat scripts/diff_shades_gha_helper.py > helper.py

From 3451502daa79746bb91fd3bd0697fb00d55d3a5f Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Sat, 2 Apr 2022 11:22:52 -0400
Subject: [PATCH 0508/1034] Bump peter-evans/find-comment from 1.3.0 to 2
 (#2960)

Bumps [peter-evans/find-comment](https://github.com/peter-evans/find-comment) from 1.3.0 to 2.
- [Release notes](https://github.com/peter-evans/find-comment/releases)
- [Commits](https://github.com/peter-evans/find-comment/compare/d2dae40ed151c634e4189471272b57e76ec19ba8...1769778a0c5bd330272d749d12c036d65e70d39d)

---
updated-dependencies:
- dependency-name: peter-evans/find-comment
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/diff_shades_comment.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/diff_shades_comment.yml b/.github/workflows/diff_shades_comment.yml
index cf5d8bf9ac5..76067ce03a0 100644
--- a/.github/workflows/diff_shades_comment.yml
+++ b/.github/workflows/diff_shades_comment.yml
@@ -31,7 +31,7 @@ jobs:
       - name: Try to find pre-existing PR comment
         if: steps.metadata.outputs.needs-comment == 'true'
         id: find-comment
-        uses: peter-evans/find-comment@d2dae40ed151c634e4189471272b57e76ec19ba8
+        uses: peter-evans/find-comment@1769778a0c5bd330272d749d12c036d65e70d39d
         with:
           issue-number: ${{ steps.metadata.outputs.pr-number }}
           comment-author: "github-actions[bot]"

From 5436810921a2649a30f42b82ff6563a1af16d40f Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Sat, 2 Apr 2022 11:23:08 -0400
Subject: [PATCH 0509/1034] Bump peter-evans/create-or-update-comment from
 1.4.5 to 2 (#2961)

Bumps [peter-evans/create-or-update-comment](https://github.com/peter-evans/create-or-update-comment) from 1.4.5 to 2.
- [Release notes](https://github.com/peter-evans/create-or-update-comment/releases)
- [Commits](https://github.com/peter-evans/create-or-update-comment/compare/a35cf36e5301d70b76f316e867e7788a55a31dae...c9fcb64660bc90ec1cc535646af190c992007c32)

---
updated-dependencies:
- dependency-name: peter-evans/create-or-update-comment
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/diff_shades_comment.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/diff_shades_comment.yml b/.github/workflows/diff_shades_comment.yml
index 76067ce03a0..94302735d0a 100644
--- a/.github/workflows/diff_shades_comment.yml
+++ b/.github/workflows/diff_shades_comment.yml
@@ -39,7 +39,7 @@ jobs:
 
       - name: Create or update PR comment
         if: steps.metadata.outputs.needs-comment == 'true'
-        uses: peter-evans/create-or-update-comment@a35cf36e5301d70b76f316e867e7788a55a31dae
+        uses: peter-evans/create-or-update-comment@c9fcb64660bc90ec1cc535646af190c992007c32
         with:
           comment-id: ${{ steps.find-comment.outputs.comment-id }}
           issue-number: ${{ steps.metadata.outputs.pr-number }}

From 1af29fbfa507daa8166e7aac659e9b2ff2b47a3c Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Sat, 2 Apr 2022 08:29:32 -0700
Subject: [PATCH 0510/1034] try-except tomllib import (#2987)

See #2965

I left the version check in place because mypy doesn't generally like try-excepted imports.
---
 CHANGES.md         | 3 +++
 setup.py           | 2 +-
 src/black/files.py | 6 +++++-
 3 files changed, 9 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index f68bc8f1a99..f2bdbd2e2b7 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -39,6 +39,9 @@
 
 <!-- Changes to how Black is packaged, such as dependency requirements -->
 
+- Use `tomli` instead of `tomllib` on Python 3.11 builds where `tomllib` is not
+  available (#2987)
+
 ### Parser
 
 <!-- Changes to the parser or to version autodetection -->
diff --git a/setup.py b/setup.py
index e23a58c411c..522a42a7ce2 100644
--- a/setup.py
+++ b/setup.py
@@ -98,7 +98,7 @@ def find_python_files(base: Path) -> List[Path]:
     install_requires=[
         "click>=8.0.0",
         "platformdirs>=2",
-        "tomli>=1.1.0; python_version < '3.11'",
+        "tomli>=1.1.0; python_full_version < '3.11.0a7'",
         "typed-ast>=1.4.2; python_version < '3.8' and implementation_name == 'cpython'",
         "pathspec>=0.9.0",
         "dataclasses>=0.6; python_version < '3.7'",
diff --git a/src/black/files.py b/src/black/files.py
index 52c77c63346..0382397e8a2 100644
--- a/src/black/files.py
+++ b/src/black/files.py
@@ -22,7 +22,11 @@
 from pathspec.patterns.gitwildmatch import GitWildMatchPatternError
 
 if sys.version_info >= (3, 11):
-    import tomllib
+    try:
+        import tomllib
+    except ImportError:
+        # Help users on older alphas
+        import tomli as tomllib
 else:
     import tomli as tomllib
 

From 4d0a4b15a935c5363563a0e0b570c4467943abb9 Mon Sep 17 00:00:00 2001
From: Joe Young <80432516+jpy-git@users.noreply.github.com>
Date: Sun, 3 Apr 2022 00:18:13 +0100
Subject: [PATCH 0511/1034] Fix broken link in README.md (#2989)

Broken when we converted some more RST docs to MyST
---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index f2d06bedad2..5b71ba72143 100644
--- a/README.md
+++ b/README.md
@@ -69,7 +69,7 @@ tests, and our own auto formatting and parallel Continuous Integration runner. N
 we have become stable, you should not expect large formatting to changes in the future.
 Stylistic changes will mostly be responses to bug reports and support for new Python
 syntax. For more information please refer to the
-[The Black Code Style](docs/the_black_code_style/index.rst).
+[The Black Code Style](https://black.readthedocs.io/en/stable/the_black_code_style/index.html).
 
 Also, as a safety measure which slows down processing, _Black_ will check that the
 reformatted code still produces a valid AST that is effectively equivalent to the

From 24c708eb374a856372284fb1a4f021fec292f713 Mon Sep 17 00:00:00 2001
From: Joe Young <80432516+jpy-git@users.noreply.github.com>
Date: Sun, 3 Apr 2022 04:27:33 +0100
Subject: [PATCH 0512/1034] Remove unnecessary parentheses from `with`
 statements (#2926)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 CHANGES.md                         |   2 +
 src/black/linegen.py               |  98 +++++++++++++++++++-----
 tests/data/remove_for_brackets.py  |   8 ++
 tests/data/remove_with_brackets.py | 119 +++++++++++++++++++++++++++++
 tests/test_format.py               |  10 +++
 5 files changed, 218 insertions(+), 19 deletions(-)
 create mode 100644 tests/data/remove_with_brackets.py

diff --git a/CHANGES.md b/CHANGES.md
index f2bdbd2e2b7..30c00566b3c 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -14,6 +14,8 @@
 
 <!-- Changes that affect Black's preview style -->
 
+- Remove unnecessary parentheses from `with` statements (#2926)
+
 ### _Blackd_
 
 <!-- Changes to blackd -->
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 8a28c3901bb..2cf9cf3130a 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -322,9 +322,10 @@ def __post_init__(self) -> None:
             self.visit_except_clause = partial(
                 v, keywords={"except"}, parens={"except"}
             )
+            self.visit_with_stmt = partial(v, keywords={"with"}, parens={"with"})
         else:
             self.visit_except_clause = partial(v, keywords={"except"}, parens=Ø)
-        self.visit_with_stmt = partial(v, keywords={"with"}, parens=Ø)
+            self.visit_with_stmt = partial(v, keywords={"with"}, parens=Ø)
         self.visit_funcdef = partial(v, keywords={"def"}, parens=Ø)
         self.visit_classdef = partial(v, keywords={"class"}, parens=Ø)
         self.visit_expr_stmt = partial(v, keywords=Ø, parens=ASSIGNMENTS)
@@ -845,11 +846,26 @@ def normalize_invisible_parens(
             check_lpar = True
 
         if check_lpar:
-            if child.type == syms.atom:
+            if (
+                preview
+                and child.type == syms.atom
+                and node.type == syms.for_stmt
+                and isinstance(child.prev_sibling, Leaf)
+                and child.prev_sibling.type == token.NAME
+                and child.prev_sibling.value == "for"
+            ):
+                if maybe_make_parens_invisible_in_atom(
+                    child,
+                    parent=node,
+                    remove_brackets_around_comma=True,
+                ):
+                    wrap_in_parentheses(node, child, visible=False)
+            elif preview and isinstance(child, Node) and node.type == syms.with_stmt:
+                remove_with_parens(child, node)
+            elif child.type == syms.atom:
                 if maybe_make_parens_invisible_in_atom(
                     child,
                     parent=node,
-                    preview=preview,
                 ):
                     wrap_in_parentheses(node, child, visible=False)
             elif is_one_tuple(child):
@@ -871,38 +887,78 @@ def normalize_invisible_parens(
             elif not (isinstance(child, Leaf) and is_multiline_string(child)):
                 wrap_in_parentheses(node, child, visible=False)
 
-        check_lpar = isinstance(child, Leaf) and child.value in parens_after
+        comma_check = child.type == token.COMMA if preview else False
+
+        check_lpar = isinstance(child, Leaf) and (
+            child.value in parens_after or comma_check
+        )
+
+
+def remove_with_parens(node: Node, parent: Node) -> None:
+    """Recursively hide optional parens in `with` statements."""
+    # Removing all unnecessary parentheses in with statements in one pass is a tad
+    # complex as different variations of bracketed statements result in pretty
+    # different parse trees:
+    #
+    # with (open("file")) as f:                       # this is an asexpr_test
+    #     ...
+    #
+    # with (open("file") as f):                       # this is an atom containing an
+    #     ...                                         # asexpr_test
+    #
+    # with (open("file")) as f, (open("file")) as f:  # this is asexpr_test, COMMA,
+    #     ...                                         # asexpr_test
+    #
+    # with (open("file") as f, open("file") as f):    # an atom containing a
+    #     ...                                         # testlist_gexp which then
+    #                                                 # contains multiple asexpr_test(s)
+    if node.type == syms.atom:
+        if maybe_make_parens_invisible_in_atom(
+            node,
+            parent=parent,
+            remove_brackets_around_comma=True,
+        ):
+            wrap_in_parentheses(parent, node, visible=False)
+        if isinstance(node.children[1], Node):
+            remove_with_parens(node.children[1], node)
+    elif node.type == syms.testlist_gexp:
+        for child in node.children:
+            if isinstance(child, Node):
+                remove_with_parens(child, node)
+    elif node.type == syms.asexpr_test and not any(
+        leaf.type == token.COLONEQUAL for leaf in node.leaves()
+    ):
+        if maybe_make_parens_invisible_in_atom(
+            node.children[0],
+            parent=node,
+            remove_brackets_around_comma=True,
+        ):
+            wrap_in_parentheses(node, node.children[0], visible=False)
 
 
 def maybe_make_parens_invisible_in_atom(
     node: LN,
     parent: LN,
-    preview: bool = False,
+    remove_brackets_around_comma: bool = False,
 ) -> bool:
     """If it's safe, make the parens in the atom `node` invisible, recursively.
     Additionally, remove repeated, adjacent invisible parens from the atom `node`
     as they are redundant.
 
     Returns whether the node should itself be wrapped in invisible parentheses.
-
     """
-    if (
-        preview
-        and parent.type == syms.for_stmt
-        and isinstance(node.prev_sibling, Leaf)
-        and node.prev_sibling.type == token.NAME
-        and node.prev_sibling.value == "for"
-    ):
-        for_stmt_check = False
-    else:
-        for_stmt_check = True
-
     if (
         node.type != syms.atom
         or is_empty_tuple(node)
         or is_one_tuple(node)
         or (is_yield(node) and parent.type != syms.expr_stmt)
-        or (max_delimiter_priority_in_atom(node) >= COMMA_PRIORITY and for_stmt_check)
+        or (
+            # This condition tries to prevent removing non-optional brackets
+            # around a tuple, however, can be a bit overzealous so we provide
+            # and option to skip this check for `for` and `with` statements.
+            not remove_brackets_around_comma
+            and max_delimiter_priority_in_atom(node) >= COMMA_PRIORITY
+        )
     ):
         return False
 
@@ -925,7 +981,11 @@ def maybe_make_parens_invisible_in_atom(
         # make parentheses invisible
         first.value = ""
         last.value = ""
-        maybe_make_parens_invisible_in_atom(middle, parent=parent, preview=preview)
+        maybe_make_parens_invisible_in_atom(
+            middle,
+            parent=parent,
+            remove_brackets_around_comma=remove_brackets_around_comma,
+        )
 
         if is_atom_with_invisible_parens(middle):
             # Strip the invisible parens from `middle` by replacing
diff --git a/tests/data/remove_for_brackets.py b/tests/data/remove_for_brackets.py
index c8d88abcc50..cd5340462da 100644
--- a/tests/data/remove_for_brackets.py
+++ b/tests/data/remove_for_brackets.py
@@ -14,6 +14,10 @@
 for (k, v) in dfkasdjfldsjflkdsjflkdsjfdslkfjldsjfgkjdshgkljjdsfldgkhsdofudsfudsofajdslkfjdslkfjldisfjdffjsdlkfjdlkjjkdflskadjldkfjsalkfjdasj.items():
     print(k, v)
 
+# Test deeply nested brackets
+for (((((k, v))))) in d.items():
+    print(k, v)
+
 # output
 # Only remove tuple brackets after `for`
 for k, v in d.items():
@@ -38,3 +42,7 @@
     dfkasdjfldsjflkdsjflkdsjfdslkfjldsjfgkjdshgkljjdsfldgkhsdofudsfudsofajdslkfjdslkfjldisfjdffjsdlkfjdlkjjkdflskadjldkfjsalkfjdasj.items()
 ):
     print(k, v)
+
+# Test deeply nested brackets
+for k, v in d.items():
+    print(k, v)
diff --git a/tests/data/remove_with_brackets.py b/tests/data/remove_with_brackets.py
new file mode 100644
index 00000000000..ea58ab93a16
--- /dev/null
+++ b/tests/data/remove_with_brackets.py
@@ -0,0 +1,119 @@
+with (open("bla.txt")):
+    pass
+
+with (open("bla.txt")), (open("bla.txt")):
+    pass
+
+with (open("bla.txt") as f):
+    pass
+
+# Remove brackets within alias expression
+with (open("bla.txt")) as f:
+    pass
+
+# Remove brackets around one-line context managers
+with (open("bla.txt") as f, (open("x"))):
+    pass
+
+with ((open("bla.txt")) as f, open("x")):
+    pass
+
+with (CtxManager1() as example1, CtxManager2() as example2):
+    ...
+
+# Brackets remain when using magic comma
+with (CtxManager1() as example1, CtxManager2() as example2,):
+    ...
+
+# Brackets remain for multi-line context managers
+with (CtxManager1() as example1, CtxManager2() as example2, CtxManager2() as example2, CtxManager2() as example2, CtxManager2() as example2):
+    ...
+
+# Don't touch assignment expressions
+with (y := open("./test.py")) as f:
+    pass
+
+# Deeply nested examples
+# N.B. Multiple brackets are only possible
+# around the context manager itself.
+# Only one brackets is allowed around the
+# alias expression or comma-delimited context managers.
+with (((open("bla.txt")))):
+    pass
+
+with (((open("bla.txt")))), (((open("bla.txt")))):
+    pass
+
+with (((open("bla.txt")))) as f:
+    pass
+
+with ((((open("bla.txt")))) as f):
+    pass
+
+with ((((CtxManager1()))) as example1, (((CtxManager2()))) as example2):
+    ...
+
+# output
+with open("bla.txt"):
+    pass
+
+with open("bla.txt"), open("bla.txt"):
+    pass
+
+with open("bla.txt") as f:
+    pass
+
+# Remove brackets within alias expression
+with open("bla.txt") as f:
+    pass
+
+# Remove brackets around one-line context managers
+with open("bla.txt") as f, open("x"):
+    pass
+
+with open("bla.txt") as f, open("x"):
+    pass
+
+with CtxManager1() as example1, CtxManager2() as example2:
+    ...
+
+# Brackets remain when using magic comma
+with (
+    CtxManager1() as example1,
+    CtxManager2() as example2,
+):
+    ...
+
+# Brackets remain for multi-line context managers
+with (
+    CtxManager1() as example1,
+    CtxManager2() as example2,
+    CtxManager2() as example2,
+    CtxManager2() as example2,
+    CtxManager2() as example2,
+):
+    ...
+
+# Don't touch assignment expressions
+with (y := open("./test.py")) as f:
+    pass
+
+# Deeply nested examples
+# N.B. Multiple brackets are only possible
+# around the context manager itself.
+# Only one brackets is allowed around the
+# alias expression or comma-delimited context managers.
+with open("bla.txt"):
+    pass
+
+with open("bla.txt"), open("bla.txt"):
+    pass
+
+with open("bla.txt") as f:
+    pass
+
+with open("bla.txt") as f:
+    pass
+
+with CtxManager1() as example1, CtxManager2() as example2:
+    ...
diff --git a/tests/test_format.py b/tests/test_format.py
index a995bd3f1f5..d80eaa730cd 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -192,6 +192,16 @@ def test_pep_570() -> None:
     assert_format(source, expected, minimum_version=(3, 8))
 
 
+def test_remove_with_brackets() -> None:
+    source, expected = read_data("remove_with_brackets")
+    assert_format(
+        source,
+        expected,
+        black.Mode(preview=True),
+        minimum_version=(3, 9),
+    )
+
+
 @pytest.mark.parametrize("filename", PY310_CASES)
 def test_python_310(filename: str) -> None:
     source, expected = read_data(filename)

From fa5fd262fffd577e3c5d573af9c2fa0af2991be1 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Mon, 4 Apr 2022 21:23:30 -0400
Subject: [PATCH 0513/1034] Update test_black.shhh_click test for click 8+
 (#2993)

The 8.0.x series renamed its "die on LANG=C" function and the 8.1.x
series straight up deleted it.

Unfortunately this makes this test type check cleanly hard, so we'll
just lint with click 8.1+ (the pre-commit hook configuration was changed
mostly to just evict any now unsupported mypy environments)
---
 .pre-commit-config.yaml |  2 +-
 tests/test_black.py     | 10 ++++++----
 2 files changed, 7 insertions(+), 5 deletions(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index b96bc62fe17..26b7fe8c791 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -50,7 +50,7 @@ repos:
           - types-PyYAML
           - tomli >= 0.2.6, < 2.0.0
           - types-typed-ast >= 1.4.1
-          - click >= 8.0.0
+          - click >= 8.1.0
           - platformdirs >= 2.1.0
 
   - repo: https://github.com/pre-commit/mirrors-prettier
diff --git a/tests/test_black.py b/tests/test_black.py
index ce7bab2f440..20cc9f7379f 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -1256,23 +1256,25 @@ def test_assert_equivalent_different_asts(self) -> None:
 
     def test_shhh_click(self) -> None:
         try:
-            from click import _unicodefun
+            from click import _unicodefun  # type: ignore
         except ImportError:
             self.skipTest("Incompatible Click version")
-        if not hasattr(_unicodefun, "_verify_python3_env"):
+
+        if not hasattr(_unicodefun, "_verify_python_env"):
             self.skipTest("Incompatible Click version")
+
         # First, let's see if Click is crashing with a preferred ASCII charset.
         with patch("locale.getpreferredencoding") as gpe:
             gpe.return_value = "ASCII"
             with self.assertRaises(RuntimeError):
-                _unicodefun._verify_python3_env()  # type: ignore
+                _unicodefun._verify_python_env()
         # Now, let's silence Click...
         black.patch_click()
         # ...and confirm it's silent.
         with patch("locale.getpreferredencoding") as gpe:
             gpe.return_value = "ASCII"
             try:
-                _unicodefun._verify_python3_env()  # type: ignore
+                _unicodefun._verify_python_env()
             except RuntimeError as re:
                 self.fail(f"`patch_click()` failed, exception still raised: {re}")
 

From 421383d5607da1191eaf3682750278750ea33d91 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jan-Hendrik=20M=C3=BCller?=
 <44469195+kolibril13@users.noreply.github.com>
Date: Tue, 5 Apr 2022 03:24:16 +0200
Subject: [PATCH 0514/1034] Update FAQ: Mention formatting of custom jupyter
 cell magic (#2982)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 docs/faq.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/faq.md b/docs/faq.md
index 70f9b51394f..a5919a39af5 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -57,7 +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`)
+- 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`.
 - multiline magics, e.g.:
 
   ```python

From 9b307405fb6d4248e1a1dd7c6c10fa02b3c347f0 Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <hugovk@users.noreply.github.com>
Date: Wed, 6 Apr 2022 15:48:50 +0300
Subject: [PATCH 0515/1034] Top PyPI Packages: Use 30-days data, 365 is no
 longer available (#2995)

---
 gallery/gallery.py | 13 +++++--------
 1 file changed, 5 insertions(+), 8 deletions(-)

diff --git a/gallery/gallery.py b/gallery/gallery.py
index 3df05c1a722..be4d81dc427 100755
--- a/gallery/gallery.py
+++ b/gallery/gallery.py
@@ -10,10 +10,9 @@
 from concurrent.futures import ThreadPoolExecutor
 from functools import lru_cache, partial
 from pathlib import Path
-from typing import (  # type: ignore # typing can't see Literal
+from typing import (
     Generator,
     List,
-    Literal,
     NamedTuple,
     Optional,
     Tuple,
@@ -24,12 +23,11 @@
 
 PYPI_INSTANCE = "https://pypi.org/pypi"
 PYPI_TOP_PACKAGES = (
-    "https://hugovk.github.io/top-pypi-packages/top-pypi-packages-{days}-days.json"
+    "https://hugovk.github.io/top-pypi-packages/top-pypi-packages-30-days.min.json"
 )
 INTERNAL_BLACK_REPO = f"{tempfile.gettempdir()}/__black"
 
 ArchiveKind = Union[tarfile.TarFile, zipfile.ZipFile]
-Days = Union[Literal[30], Literal[365]]
 
 subprocess.run = partial(subprocess.run, check=True)  # type: ignore
 # https://github.com/python/mypy/issues/1484
@@ -64,8 +62,8 @@ def get_pypi_download_url(package: str, version: Optional[str]) -> str:
     return cast(str, source["url"])
 
 
-def get_top_packages(days: Days) -> List[str]:
-    with urlopen(PYPI_TOP_PACKAGES.format(days=days)) as page:
+def get_top_packages() -> List[str]:
+    with urlopen(PYPI_TOP_PACKAGES) as page:
         result = json.load(page)
 
     return [package["project"] for package in result["rows"]]
@@ -128,13 +126,12 @@ def get_package(
 
 def download_and_extract_top_packages(
     directory: Path,
-    days: Days = 365,
     workers: int = 8,
     limit: slice = DEFAULT_SLICE,
 ) -> Generator[Path, None, None]:
     with ThreadPoolExecutor(max_workers=workers) as executor:
         bound_downloader = partial(get_package, version=None, directory=directory)
-        for package in executor.map(bound_downloader, get_top_packages(days)[limit]):
+        for package in executor.map(bound_downloader, get_top_packages()[limit]):
             if package is not None:
                 yield package
 

From f6188ce6dcde3fcad381c52ecc74374e7d0579c9 Mon Sep 17 00:00:00 2001
From: Joe Young <80432516+jpy-git@users.noreply.github.com>
Date: Wed, 6 Apr 2022 19:04:12 +0100
Subject: [PATCH 0516/1034] Output python version and implementation as part of
 `--version` flag (#2997)

Example:

black, 22.1.1.dev56+g421383d.d20220405 (compiled: no)
Python (CPython) 3.9.12

Co-authored-by: Batuhan Taskaya <isidentical@gmail.com>
---
 CHANGES.md            | 2 ++
 src/black/__init__.py | 6 +++++-
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index 30c00566b3c..3bf481fb580 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -37,6 +37,8 @@
 
 <!-- Changes to Black's terminal output and error messages -->
 
+- Output python version and implementation as part of `--version` flag (#2997)
+
 ### Packaging
 
 <!-- Changes to how Black is packaged, such as dependency requirements -->
diff --git a/src/black/__init__.py b/src/black/__init__.py
index bdeb73273bc..3a2d1cb8898 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -10,6 +10,7 @@
 import os
 from pathlib import Path
 from pathspec.patterns.gitwildmatch import GitWildMatchPatternError
+import platform
 import re
 import signal
 import sys
@@ -381,7 +382,10 @@ def validate_regex(
 )
 @click.version_option(
     version=__version__,
-    message=f"%(prog)s, %(version)s (compiled: {'yes' if COMPILED else 'no'})",
+    message=(
+        f"%(prog)s, %(version)s (compiled: {'yes' if COMPILED else 'no'})\n"
+        f"Python ({platform.python_implementation()}) {platform.python_version()}"
+    ),
 )
 @click.argument(
     "src",

From 98fcccee55acba04afdd933676f56927cfe9bbe4 Mon Sep 17 00:00:00 2001
From: Joe Young <80432516+jpy-git@users.noreply.github.com>
Date: Sat, 9 Apr 2022 15:36:05 +0100
Subject: [PATCH 0517/1034] Better manage return annotation brackets (#2990)

Allows us to better control placement of return annotations by:

a) removing redundant parens
b) moves very long type annotations onto their own line

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 CHANGES.md                               |   1 +
 src/black/linegen.py                     |  31 +++-
 src/black/mode.py                        |   1 +
 tests/data/return_annotation_brackets.py | 222 +++++++++++++++++++++++
 tests/test_format.py                     |   1 +
 5 files changed, 255 insertions(+), 1 deletion(-)
 create mode 100644 tests/data/return_annotation_brackets.py

diff --git a/CHANGES.md b/CHANGES.md
index 3bf481fb580..c631aec7a3b 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -14,6 +14,7 @@
 
 <!-- Changes that affect Black's preview style -->
 
+- Parentheses around return annotations are now managed (#2990)
 - Remove unnecessary parentheses from `with` statements (#2926)
 
 ### _Blackd_
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 2cf9cf3130a..c2b0616d02f 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -144,6 +144,33 @@ def visit_stmt(
 
             yield from self.visit(child)
 
+    def visit_funcdef(self, node: Node) -> Iterator[Line]:
+        """Visit function definition."""
+        if Preview.annotation_parens not in self.mode:
+            yield from self.visit_stmt(node, keywords={"def"}, parens=set())
+        else:
+            yield from self.line()
+
+            # Remove redundant brackets around return type annotation.
+            is_return_annotation = False
+            for child in node.children:
+                if child.type == token.RARROW:
+                    is_return_annotation = True
+                elif is_return_annotation:
+                    if child.type == syms.atom and child.children[0].type == token.LPAR:
+                        if maybe_make_parens_invisible_in_atom(
+                            child,
+                            parent=node,
+                            remove_brackets_around_comma=False,
+                        ):
+                            wrap_in_parentheses(node, child, visible=False)
+                    else:
+                        wrap_in_parentheses(node, child, visible=False)
+                    is_return_annotation = False
+
+            for child in node.children:
+                yield from self.visit(child)
+
     def visit_match_case(self, node: Node) -> Iterator[Line]:
         """Visit either a match or case statement."""
         normalize_invisible_parens(node, parens_after=set(), preview=self.mode.preview)
@@ -326,7 +353,6 @@ def __post_init__(self) -> None:
         else:
             self.visit_except_clause = partial(v, keywords={"except"}, parens=Ø)
             self.visit_with_stmt = partial(v, keywords={"with"}, parens=Ø)
-        self.visit_funcdef = partial(v, keywords={"def"}, parens=Ø)
         self.visit_classdef = partial(v, keywords={"class"}, parens=Ø)
         self.visit_expr_stmt = partial(v, keywords=Ø, parens=ASSIGNMENTS)
         self.visit_return_stmt = partial(v, keywords={"return"}, parens={"return"})
@@ -478,7 +504,10 @@ def left_hand_split(line: Line, _features: Collection[Feature] = ()) -> Iterator
             current_leaves is body_leaves
             and leaf.type in CLOSING_BRACKETS
             and leaf.opening_bracket is matching_bracket
+            and isinstance(matching_bracket, Leaf)
         ):
+            ensure_visible(leaf)
+            ensure_visible(matching_bracket)
             current_leaves = tail_leaves if body_leaves else head_leaves
         current_leaves.append(leaf)
         if current_leaves is head_leaves:
diff --git a/src/black/mode.py b/src/black/mode.py
index 6b74c14b6de..34905702a54 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -129,6 +129,7 @@ class Preview(Enum):
     string_processing = auto()
     remove_redundant_parens = auto()
     one_element_subscript = auto()
+    annotation_parens = auto()
 
 
 class Deprecated(UserWarning):
diff --git a/tests/data/return_annotation_brackets.py b/tests/data/return_annotation_brackets.py
new file mode 100644
index 00000000000..27760bd51d7
--- /dev/null
+++ b/tests/data/return_annotation_brackets.py
@@ -0,0 +1,222 @@
+# Control
+def double(a: int) -> int:
+    return 2*a
+
+# Remove the brackets
+def double(a: int) -> (int):
+    return 2*a
+
+# Some newline variations
+def double(a: int) -> (
+    int):
+    return 2*a
+
+def double(a: int) -> (int
+):
+    return 2*a
+
+def double(a: int) -> (
+    int
+):
+    return 2*a
+
+# Don't lose the comments
+def double(a: int) -> ( # Hello
+    int
+):
+    return 2*a
+
+def double(a: int) -> (
+    int # Hello
+):
+    return 2*a
+
+# Really long annotations
+def foo() -> (
+    intsdfsafafafdfdsasdfsfsdfasdfafdsafdfdsfasdskdsdsfdsafdsafsdfdasfffsfdsfdsafafhdskfhdsfjdslkfdlfsdkjhsdfjkdshfkljds
+):
+    return 2
+
+def foo() -> intsdfsafafafdfdsasdfsfsdfasdfafdsafdfdsfasdskdsdsfdsafdsafsdfdasfffsfdsfdsafafhdskfhdsfjdslkfdlfsdkjhsdfjkdshfkljds:
+    return 2
+
+def foo() -> intsdfsafafafdfdsasdfsfsdfasdfafdsafdfdsfasdskdsdsfdsafdsafsdfdasfffsfdsfdsafafhdskfhdsfjdslkfdlfsdkjhsdfjkdshfkljds | intsdfsafafafdfdsasdfsfsdfasdfafdsafdfdsfasdskdsdsfdsafdsafsdfdasfffsfdsfdsafafhdskfhdsfjdslkfdlfsdkjhsdfjkdshfkljds:
+    return 2
+
+def foo(a: int, b: int, c: int,) -> intsdfsafafafdfdsasdfsfsdfasdfafdsafdfdsfasdskdsdsfdsafdsafsdfdasfffsfdsfdsafafhdskfhdsfjdslkfdlfsdkjhsdfjkdshfkljds:
+    return 2
+
+def foo(a: int, b: int, c: int,) -> intsdfsafafafdfdsasdfsfsdfasdfafdsafdfdsfasdskdsdsfdsafdsafsdfdasfffsfdsfdsafafhdskfhdsfjdslkfdlfsdkjhsdfjkdshfkljds | intsdfsafafafdfdsasdfsfsdfasdfafdsafdfdsfasdskdsdsfdsafdsafsdfdasfffsfdsfdsafafhdskfhdsfjdslkfdlfsdkjhsdfjkdshfkljds:
+    return 2
+
+# Split args but no need to split return
+def foo(a: int, b: int, c: int,) -> int:
+    return 2
+
+# Deeply nested brackets
+# with *interesting* spacing
+def double(a: int) -> (((((int))))):
+    return 2*a
+
+def double(a: int) -> (
+    (  (
+        ((int)
+         )
+           )
+            )
+        ):
+    return 2*a
+
+def foo() -> (
+    (  (
+    intsdfsafafafdfdsasdfsfsdfasdfafdsafdfdsfasdskdsdsfdsafdsafsdfdasfffsfdsfdsafafhdskfhdsfjdslkfdlfsdkjhsdfjkdshfkljds
+)
+)):
+    return 2
+
+# Return type with commas
+def foo() -> (
+    tuple[int, int, int]
+):
+    return 2
+
+def foo() -> tuple[loooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong, loooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong, loooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong]:
+    return 2
+
+# Magic trailing comma example
+def foo() -> tuple[int, int, int,]:
+    return 2
+
+# Long string example
+def frobnicate() -> "ThisIsTrulyUnreasonablyExtremelyLongClassName | list[ThisIsTrulyUnreasonablyExtremelyLongClassName]":
+    pass
+
+# output
+# Control
+def double(a: int) -> int:
+    return 2 * a
+
+
+# Remove the brackets
+def double(a: int) -> int:
+    return 2 * a
+
+
+# Some newline variations
+def double(a: int) -> int:
+    return 2 * a
+
+
+def double(a: int) -> int:
+    return 2 * a
+
+
+def double(a: int) -> int:
+    return 2 * a
+
+
+# Don't lose the comments
+def double(a: int) -> int:  # Hello
+    return 2 * a
+
+
+def double(a: int) -> int:  # Hello
+    return 2 * a
+
+
+# Really long annotations
+def foo() -> (
+    intsdfsafafafdfdsasdfsfsdfasdfafdsafdfdsfasdskdsdsfdsafdsafsdfdasfffsfdsfdsafafhdskfhdsfjdslkfdlfsdkjhsdfjkdshfkljds
+):
+    return 2
+
+
+def foo() -> (
+    intsdfsafafafdfdsasdfsfsdfasdfafdsafdfdsfasdskdsdsfdsafdsafsdfdasfffsfdsfdsafafhdskfhdsfjdslkfdlfsdkjhsdfjkdshfkljds
+):
+    return 2
+
+
+def foo() -> (
+    intsdfsafafafdfdsasdfsfsdfasdfafdsafdfdsfasdskdsdsfdsafdsafsdfdasfffsfdsfdsafafhdskfhdsfjdslkfdlfsdkjhsdfjkdshfkljds
+    | intsdfsafafafdfdsasdfsfsdfasdfafdsafdfdsfasdskdsdsfdsafdsafsdfdasfffsfdsfdsafafhdskfhdsfjdslkfdlfsdkjhsdfjkdshfkljds
+):
+    return 2
+
+
+def foo(
+    a: int,
+    b: int,
+    c: int,
+) -> intsdfsafafafdfdsasdfsfsdfasdfafdsafdfdsfasdskdsdsfdsafdsafsdfdasfffsfdsfdsafafhdskfhdsfjdslkfdlfsdkjhsdfjkdshfkljds:
+    return 2
+
+
+def foo(
+    a: int,
+    b: int,
+    c: int,
+) -> (
+    intsdfsafafafdfdsasdfsfsdfasdfafdsafdfdsfasdskdsdsfdsafdsafsdfdasfffsfdsfdsafafhdskfhdsfjdslkfdlfsdkjhsdfjkdshfkljds
+    | intsdfsafafafdfdsasdfsfsdfasdfafdsafdfdsfasdskdsdsfdsafdsafsdfdasfffsfdsfdsafafhdskfhdsfjdslkfdlfsdkjhsdfjkdshfkljds
+):
+    return 2
+
+
+# Split args but no need to split return
+def foo(
+    a: int,
+    b: int,
+    c: int,
+) -> int:
+    return 2
+
+
+# Deeply nested brackets
+# with *interesting* spacing
+def double(a: int) -> int:
+    return 2 * a
+
+
+def double(a: int) -> int:
+    return 2 * a
+
+
+def foo() -> (
+    intsdfsafafafdfdsasdfsfsdfasdfafdsafdfdsfasdskdsdsfdsafdsafsdfdasfffsfdsfdsafafhdskfhdsfjdslkfdlfsdkjhsdfjkdshfkljds
+):
+    return 2
+
+
+# Return type with commas
+def foo() -> tuple[int, int, int]:
+    return 2
+
+
+def foo() -> (
+    tuple[
+        loooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong,
+        loooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong,
+        loooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong,
+    ]
+):
+    return 2
+
+
+# Magic trailing comma example
+def foo() -> (
+    tuple[
+        int,
+        int,
+        int,
+    ]
+):
+    return 2
+
+
+# Long string example
+def frobnicate() -> (
+    "ThisIsTrulyUnreasonablyExtremelyLongClassName |"
+    " list[ThisIsTrulyUnreasonablyExtremelyLongClassName]"
+):
+    pass
diff --git a/tests/test_format.py b/tests/test_format.py
index d80eaa730cd..6f71617eee6 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -83,6 +83,7 @@
     "remove_except_parens",
     "remove_for_brackets",
     "one_element_subscript",
+    "return_annotation_brackets",
 ]
 
 SOURCES: List[str] = [

From 75f99bded33abe962ca08bf16c77635ac9ca00a1 Mon Sep 17 00:00:00 2001
From: Joe Young <80432516+jpy-git@users.noreply.github.com>
Date: Sat, 9 Apr 2022 21:49:40 +0100
Subject: [PATCH 0518/1034] Remove redundant parentheses around awaited
 coroutines/tasks (#2991)

This is a tricky one as await is technically an expression and therefore
in certain situations requires brackets for operator precedence.
However, the vast majority of await usage is just await some_coroutine(...)
and similar in format to return statements. Therefore this PR removes
redundant parens around these await expressions.

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 CHANGES.md                        |   1 +
 src/black/linegen.py              |  41 +++++++-
 tests/data/remove_await_parens.py | 168 ++++++++++++++++++++++++++++++
 tests/test_format.py              |   1 +
 4 files changed, 210 insertions(+), 1 deletion(-)
 create mode 100644 tests/data/remove_await_parens.py

diff --git a/CHANGES.md b/CHANGES.md
index c631aec7a3b..e168e24d76e 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -14,6 +14,7 @@
 
 <!-- Changes that affect Black's preview style -->
 
+- Remove redundant parentheses around awaited objects (#2991)
 - Parentheses around return annotations are now managed (#2990)
 - Remove unnecessary parentheses from `with` statements (#2926)
 
diff --git a/src/black/linegen.py b/src/black/linegen.py
index c2b0616d02f..caffbab0cbc 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -3,7 +3,7 @@
 """
 from functools import partial, wraps
 import sys
-from typing import Collection, Iterator, List, Optional, Set, Union
+from typing import Collection, Iterator, List, Optional, Set, Union, cast
 
 from black.nodes import WHITESPACE, RARROW, STATEMENT, STANDALONE_COMMENT
 from black.nodes import ASSIGNMENTS, OPENING_BRACKETS, CLOSING_BRACKETS
@@ -253,6 +253,9 @@ def visit_power(self, node: Node) -> Iterator[Line]:
             ):
                 wrap_in_parentheses(node, leaf)
 
+        if Preview.remove_redundant_parens in self.mode:
+            remove_await_parens(node)
+
         yield from self.visit_default(node)
 
     def visit_SEMI(self, leaf: Leaf) -> Iterator[Line]:
@@ -923,6 +926,42 @@ def normalize_invisible_parens(
         )
 
 
+def remove_await_parens(node: Node) -> None:
+    if node.children[0].type == token.AWAIT and len(node.children) > 1:
+        if (
+            node.children[1].type == syms.atom
+            and node.children[1].children[0].type == token.LPAR
+        ):
+            if maybe_make_parens_invisible_in_atom(
+                node.children[1],
+                parent=node,
+                remove_brackets_around_comma=True,
+            ):
+                wrap_in_parentheses(node, node.children[1], visible=False)
+
+            # Since await is an expression we shouldn't remove
+            # brackets in cases where this would change
+            # the AST due to operator precedence.
+            # Therefore we only aim to remove brackets around
+            # power nodes that aren't also await expressions themselves.
+            # https://peps.python.org/pep-0492/#updated-operator-precedence-table
+            # N.B. We've still removed any redundant nested brackets though :)
+            opening_bracket = cast(Leaf, node.children[1].children[0])
+            closing_bracket = cast(Leaf, node.children[1].children[-1])
+            bracket_contents = cast(Node, node.children[1].children[1])
+            if bracket_contents.type != syms.power:
+                ensure_visible(opening_bracket)
+                ensure_visible(closing_bracket)
+            elif (
+                bracket_contents.type == syms.power
+                and bracket_contents.children[0].type == token.AWAIT
+            ):
+                ensure_visible(opening_bracket)
+                ensure_visible(closing_bracket)
+                # If we are in a nested await then recurse down.
+                remove_await_parens(bracket_contents)
+
+
 def remove_with_parens(node: Node, parent: Node) -> None:
     """Recursively hide optional parens in `with` statements."""
     # Removing all unnecessary parentheses in with statements in one pass is a tad
diff --git a/tests/data/remove_await_parens.py b/tests/data/remove_await_parens.py
new file mode 100644
index 00000000000..eb7dad340c3
--- /dev/null
+++ b/tests/data/remove_await_parens.py
@@ -0,0 +1,168 @@
+import asyncio
+
+# Control example
+async def main():
+    await asyncio.sleep(1)
+
+# Remove brackets for short coroutine/task
+async def main():
+    await (asyncio.sleep(1))
+
+async def main():
+    await (
+        asyncio.sleep(1)
+    )
+
+async def main():
+    await (asyncio.sleep(1)
+    )
+
+# Check comments
+async def main():
+    await (  # Hello
+        asyncio.sleep(1)
+    )
+
+async def main():
+    await (
+        asyncio.sleep(1)  # Hello
+    )
+
+async def main():
+    await (
+        asyncio.sleep(1)
+    )  # Hello
+
+# Long lines
+async def main():
+    await asyncio.gather(asyncio.sleep(1), asyncio.sleep(1), asyncio.sleep(1), asyncio.sleep(1), asyncio.sleep(1), asyncio.sleep(1), asyncio.sleep(1))
+
+# Same as above but with magic trailing comma in function
+async def main():
+    await asyncio.gather(asyncio.sleep(1), asyncio.sleep(1), asyncio.sleep(1), asyncio.sleep(1), asyncio.sleep(1), asyncio.sleep(1), asyncio.sleep(1),)
+
+# Cr@zY Br@ck3Tz
+async def main():
+    await (
+        (((((((((((((
+        (((        (((
+        (((         (((
+        (((         (((
+        (((        (((
+        ((black(1)))
+        )))        )))
+        )))         )))
+        )))         )))
+        )))        )))
+        )))))))))))))
+    )
+
+# Keep brackets around non power operations and nested awaits
+async def main():
+    await (set_of_tasks | other_set)
+
+async def main():
+    await (await asyncio.sleep(1))
+
+# It's awaits all the way down...
+async def main():
+    await (await x)
+
+async def main():
+    await (yield x)
+
+async def main():
+    await (await (asyncio.sleep(1)))
+
+async def main():
+    await (await (await (await (await (asyncio.sleep(1))))))
+
+# output
+import asyncio
+
+# Control example
+async def main():
+    await asyncio.sleep(1)
+
+
+# Remove brackets for short coroutine/task
+async def main():
+    await asyncio.sleep(1)
+
+
+async def main():
+    await asyncio.sleep(1)
+
+
+async def main():
+    await asyncio.sleep(1)
+
+
+# Check comments
+async def main():
+    await asyncio.sleep(1)  # Hello
+
+
+async def main():
+    await asyncio.sleep(1)  # Hello
+
+
+async def main():
+    await asyncio.sleep(1)  # Hello
+
+
+# Long lines
+async def main():
+    await asyncio.gather(
+        asyncio.sleep(1),
+        asyncio.sleep(1),
+        asyncio.sleep(1),
+        asyncio.sleep(1),
+        asyncio.sleep(1),
+        asyncio.sleep(1),
+        asyncio.sleep(1),
+    )
+
+
+# Same as above but with magic trailing comma in function
+async def main():
+    await asyncio.gather(
+        asyncio.sleep(1),
+        asyncio.sleep(1),
+        asyncio.sleep(1),
+        asyncio.sleep(1),
+        asyncio.sleep(1),
+        asyncio.sleep(1),
+        asyncio.sleep(1),
+    )
+
+
+# Cr@zY Br@ck3Tz
+async def main():
+    await black(1)
+
+
+# Keep brackets around non power operations and nested awaits
+async def main():
+    await (set_of_tasks | other_set)
+
+
+async def main():
+    await (await asyncio.sleep(1))
+
+
+# It's awaits all the way down...
+async def main():
+    await (await x)
+
+
+async def main():
+    await (yield x)
+
+
+async def main():
+    await (await asyncio.sleep(1))
+
+
+async def main():
+    await (await (await (await (await asyncio.sleep(1)))))
diff --git a/tests/test_format.py b/tests/test_format.py
index 6f71617eee6..51d8fb0a103 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -83,6 +83,7 @@
     "remove_except_parens",
     "remove_for_brackets",
     "one_element_subscript",
+    "remove_await_parens",
     "return_annotation_brackets",
 ]
 

From 431bd09e15247431056894bd6444dee7c22893f0 Mon Sep 17 00:00:00 2001
From: Ryan Siu <ryansiu@umich.edu>
Date: Sat, 9 Apr 2022 16:52:45 -0400
Subject: [PATCH 0519/1034] Correctly handle fmt: skip comments without
 internal spaces (#2970)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 CHANGES.md             |  3 +++
 src/black/comments.py  |  7 +++++--
 tests/data/fmtskip7.py | 11 +++++++++++
 tests/test_format.py   |  1 +
 4 files changed, 20 insertions(+), 2 deletions(-)
 create mode 100644 tests/data/fmtskip7.py

diff --git a/CHANGES.md b/CHANGES.md
index e168e24d76e..b21c319d5e0 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -10,6 +10,9 @@
 
 <!-- Changes that affect Black's stable style -->
 
+- Fix unstable formatting involving `# fmt: skip` comments without internal spaces
+  (#2970)
+
 ### Preview style
 
 <!-- Changes that affect Black's preview style -->
diff --git a/src/black/comments.py b/src/black/comments.py
index 455326469f0..23bf87fca7c 100644
--- a/src/black/comments.py
+++ b/src/black/comments.py
@@ -214,8 +214,11 @@ def generate_ignored_nodes(
     container: Optional[LN] = container_of(leaf)
     if comment.value in FMT_SKIP:
         prev_sibling = leaf.prev_sibling
-        if comment.value in leaf.prefix and prev_sibling is not None:
-            leaf.prefix = leaf.prefix.replace(comment.value, "")
+        # Need to properly format the leaf prefix to compare it to comment.value,
+        # which is also formatted
+        comments = list_comments(leaf.prefix, is_endmarker=False, preview=preview)
+        if comments and comment.value == comments[0].value and prev_sibling is not None:
+            leaf.prefix = ""
             siblings = [prev_sibling]
             while (
                 "\n" not in prev_sibling.prefix
diff --git a/tests/data/fmtskip7.py b/tests/data/fmtskip7.py
new file mode 100644
index 00000000000..15ac0ad7080
--- /dev/null
+++ b/tests/data/fmtskip7.py
@@ -0,0 +1,11 @@
+a =     "this is some code"
+b =     5  #fmt:skip
+c = 9  #fmt: skip
+d = "thisisasuperlongstringthisisasuperlongstringthisisasuperlongstringthisisasuperlongstring"  #fmt:skip
+
+# output
+
+a = "this is some code"
+b =     5  # fmt:skip
+c = 9  # fmt: skip
+d = "thisisasuperlongstringthisisasuperlongstringthisisasuperlongstringthisisasuperlongstring"  # fmt:skip
diff --git a/tests/test_format.py b/tests/test_format.py
index 51d8fb0a103..fd5f596b6d5 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -44,6 +44,7 @@
     "fmtskip4",
     "fmtskip5",
     "fmtskip6",
+    "fmtskip7",
     "fstring",
     "function",
     "function2",

From 497a72560dd3612a062cbb0d8cb2f8c3c93b74ff Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Sun, 10 Apr 2022 19:45:34 -0400
Subject: [PATCH 0520/1034] Explain our use of mypyc in the FAQ (#3002)

I realized we don't have a FAQ entry about this, let's change that so
compiled: yes/no doesn't surprise as many people :)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 docs/faq.md | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/docs/faq.md b/docs/faq.md
index a5919a39af5..b2fe42de282 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -113,3 +113,22 @@ _Black_ is an autoformatter, not a Python linter or interpreter. Detecting all s
 errors is not a goal. It can format all code accepted by CPython (if you find an example
 where that doesn't hold, please report a bug!), but it may also format some code that
 CPython doesn't accept.
+
+## What is `compiled: yes/no` all about in the version output?
+
+While _Black_ is indeed a pure Python project, we use [mypyc] to compile _Black_ into a
+C Python extension, usually doubling performance. These compiled wheels are available
+for 64-bit versions of Windows, Linux (via the manylinux standard), and macOS across all
+supported CPython versions.
+
+Platforms including musl-based and/or ARM Linux distributions, and ARM Windows are
+currently **not** supported. These platforms will fall back to the slower pure Python
+wheel available on PyPI.
+
+If you are experiencing exceptionally weird issues or even segfaults, you can try
+passing `--no-binary black` to your pip install invocation. This flag excludes all
+wheels (including the pure Python wheel), so this command will use the [sdist].
+
+[mypyc]: https://mypyc.readthedocs.io/en/latest/
+[sdist]:
+  https://packaging.python.org/en/latest/glossary/#term-Source-Distribution-or-sdist

From abdc31cd4fb6cf88339f8ade0adf9c5356a95aa3 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 11 Apr 2022 17:26:28 -0400
Subject: [PATCH 0521/1034] Bump actions/upload-artifact from 2 to 3 (#3004)

Bumps [actions/upload-artifact](https://github.com/actions/upload-artifact) from 2 to 3.
- [Release notes](https://github.com/actions/upload-artifact/releases)
- [Commits](https://github.com/actions/upload-artifact/compare/v2...v3)

---
updated-dependencies:
- dependency-name: actions/upload-artifact
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/diff_shades.yml | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/diff_shades.yml b/.github/workflows/diff_shades.yml
index ade71e7aa8d..749f87cdcdb 100644
--- a/.github/workflows/diff_shades.yml
+++ b/.github/workflows/diff_shades.yml
@@ -108,19 +108,19 @@ jobs:
           ${{ matrix.baseline-analysis }} ${{ matrix.target-analysis }}
 
       - name: Upload diff report
-        uses: actions/upload-artifact@v2
+        uses: actions/upload-artifact@v3
         with:
           name: ${{ matrix.mode }}-diff.html
           path: diff.html
 
       - name: Upload baseline analysis
-        uses: actions/upload-artifact@v2
+        uses: actions/upload-artifact@v3
         with:
           name: ${{ matrix.baseline-analysis }}
           path: ${{ matrix.baseline-analysis }}
 
       - name: Upload target analysis
-        uses: actions/upload-artifact@v2
+        uses: actions/upload-artifact@v3
         with:
           name: ${{ matrix.target-analysis }}
           path: ${{ matrix.target-analysis }}
@@ -135,7 +135,7 @@ jobs:
 
       - name: Upload summary file (PR only)
         if: github.event_name == 'pull_request' && matrix.mode == 'preview-changes'
-        uses: actions/upload-artifact@v2
+        uses: actions/upload-artifact@v3
         with:
           name: .pr-comment.json
           path: .pr-comment.json

From 40053b522ebe8f33328c1c7e29780fc37d17911e Mon Sep 17 00:00:00 2001
From: Sam Ezeh <sam.z.ezeh@gmail.com>
Date: Mon, 11 Apr 2022 23:10:46 +0100
Subject: [PATCH 0522/1034] Quote "black[jupyter]" in README.md (#3007)

---
 README.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 5b71ba72143..1ffa7ef9522 100644
--- a/README.md
+++ b/README.md
@@ -39,7 +39,8 @@ 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.6.2+ to
-run. If you want to format Jupyter Notebooks, install with `pip install black[jupyter]`.
+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:
 

From 911b59fb4f39a612f0c9e5350b78d7b37f5ed491 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 11 Apr 2022 19:24:00 -0400
Subject: [PATCH 0523/1034] Bump furo from 2022.3.4 to 2022.4.7 in /docs
 (#3003)

Bumps [furo](https://github.com/pradyunsg/furo) from 2022.3.4 to 2022.4.7.
- [Release notes](https://github.com/pradyunsg/furo/releases)
- [Changelog](https://github.com/pradyunsg/furo/blob/main/docs/changelog.md)
- [Commits](https://github.com/pradyunsg/furo/compare/2022.03.04...2022.04.07)

---
updated-dependencies:
- dependency-name: furo
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 docs/requirements.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index 63c9c8f9edb..818415c6cf8 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -4,4 +4,4 @@ myst-parser==0.16.1
 Sphinx==4.5.0
 sphinxcontrib-programoutput==0.17
 sphinx_copybutton==0.5.0
-furo==2022.3.4
+furo==2022.4.7

From 96bd428524763fc443ac1729e7254ccbe872d5ca Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Mon, 11 Apr 2022 16:25:46 -0700
Subject: [PATCH 0524/1034] Quote black[jupyter] and black[d] in installation
 docs (#3006)

We just got someone on Discord who was confused because the command as
written caused their shell to try to do command expansion.

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 docs/getting_started.md                           | 3 ++-
 docs/usage_and_configuration/black_as_a_server.md | 2 +-
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/docs/getting_started.md b/docs/getting_started.md
index 1227f653757..fca960915a8 100644
--- a/docs/getting_started.md
+++ b/docs/getting_started.md
@@ -17,7 +17,8 @@ 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.6.2+ to
-run. If you want to format Jupyter Notebooks, install with `pip install black[jupyter]`.
+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:
 
diff --git a/docs/usage_and_configuration/black_as_a_server.md b/docs/usage_and_configuration/black_as_a_server.md
index 75a4d925a54..7d07e94e6bb 100644
--- a/docs/usage_and_configuration/black_as_a_server.md
+++ b/docs/usage_and_configuration/black_as_a_server.md
@@ -7,7 +7,7 @@ process every time you want to blacken a file.
 ## Usage
 
 `blackd` is not packaged alongside _Black_ by default because it has additional
-dependencies. You will need to execute `pip install black[d]` to install it.
+dependencies. You will need to execute `pip install 'black[d]'` to install it.
 
 You can start the server on the default port, binding only to the local interface by
 running `blackd`. You will see a single line mentioning the server's version, and the

From 712f8b37fb12a40ec6ea86903f44c2d0750f56a3 Mon Sep 17 00:00:00 2001
From: Marco Edward Gorelli <marcogorelli@protonmail.com>
Date: Thu, 14 Apr 2022 00:13:33 +0100
Subject: [PATCH 0525/1034] Make ipynb tests compatible with ipython 8.3.0+
 (#3008)

---
 tests/test_ipynb.py | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/tests/test_ipynb.py b/tests/test_ipynb.py
index b534d77c22a..6f6b3090cd1 100644
--- a/tests/test_ipynb.py
+++ b/tests/test_ipynb.py
@@ -1,3 +1,4 @@
+import contextlib
 from dataclasses import replace
 import pathlib
 import re
@@ -18,6 +19,8 @@
 from _pytest.monkeypatch import MonkeyPatch
 from tests.util import DATA_DIR
 
+with contextlib.suppress(ModuleNotFoundError):
+    import IPython
 pytestmark = pytest.mark.jupyter
 pytest.importorskip("IPython", reason="IPython is an optional dependency")
 pytest.importorskip("tokenize_rt", reason="tokenize-rt is an optional dependency")
@@ -139,10 +142,15 @@ def test_non_python_magics(src: str) -> None:
         format_cell(src, fast=True, mode=JUPYTER_MODE)
 
 
+@pytest.mark.skipif(
+    IPython.version_info < (8, 3),
+    reason="Change in how TransformerManager transforms this input",
+)
 def test_set_input() -> None:
     src = "a = b??"
-    with pytest.raises(NothingChanged):
-        format_cell(src, fast=True, mode=JUPYTER_MODE)
+    expected = "??b"
+    result = format_cell(src, fast=True, mode=JUPYTER_MODE)
+    assert result == expected
 
 
 def test_input_already_contains_transformed_magic() -> None:

From 7f7673d941a947a8d392c8c0866d3d588affc174 Mon Sep 17 00:00:00 2001
From: Batuhan Taskaya <isidentical@gmail.com>
Date: Fri, 15 Apr 2022 19:25:07 +0300
Subject: [PATCH 0526/1034] Support 3.11 / PEP 654 syntax (#3016)

---
 CHANGES.md                  |   3 +
 src/black/__init__.py       |   7 +++
 src/black/linegen.py        |   9 +++
 src/black/mode.py           |  17 ++++++
 src/black/nodes.py          |   4 ++
 src/blib2to3/Grammar.txt    |   2 +-
 tests/data/pep_654.py       |  53 +++++++++++++++++
 tests/data/pep_654_style.py | 111 ++++++++++++++++++++++++++++++++++++
 tests/test_black.py         |   6 ++
 tests/test_format.py        |  12 ++++
 10 files changed, 223 insertions(+), 1 deletion(-)
 create mode 100644 tests/data/pep_654.py
 create mode 100644 tests/data/pep_654_style.py

diff --git a/CHANGES.md b/CHANGES.md
index b21c319d5e0..566077b1dbc 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -53,6 +53,9 @@
 
 ### Parser
 
+- [PEP 654](https://peps.python.org/pep-0654/#except) syntax (for example,
+  `except *ExceptionGroup:`) is now supported (#3016)
+
 <!-- Changes to the parser or to version autodetection -->
 
 ### Performance
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 3a2d1cb8898..3a1ce24f059 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -1296,6 +1296,13 @@ def get_features_used(  # noqa: C901
         ):
             features.add(Feature.ANN_ASSIGN_EXTENDED_RHS)
 
+        elif (
+            n.type == syms.except_clause
+            and len(n.children) >= 2
+            and n.children[1].type == token.STAR
+        ):
+            features.add(Feature.EXCEPT_STAR)
+
     return features
 
 
diff --git a/src/black/linegen.py b/src/black/linegen.py
index caffbab0cbc..91fdeef8f2f 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -915,6 +915,15 @@ def normalize_invisible_parens(
                     node.insert_child(index, Leaf(token.LPAR, ""))
                     node.append_child(Leaf(token.RPAR, ""))
                 break
+            elif (
+                index == 1
+                and child.type == token.STAR
+                and node.type == syms.except_clause
+            ):
+                # In except* (PEP 654), the star is actually part of
+                # of the keyword. So we need to skip the insertion of
+                # invisible parentheses to work more precisely.
+                continue
 
             elif not (isinstance(child, Leaf) and is_multiline_string(child)):
                 wrap_in_parentheses(node, child, visible=False)
diff --git a/src/black/mode.py b/src/black/mode.py
index 34905702a54..6bd4ce14421 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -30,6 +30,7 @@ class TargetVersion(Enum):
     PY38 = 8
     PY39 = 9
     PY310 = 10
+    PY311 = 11
 
 
 class Feature(Enum):
@@ -47,6 +48,7 @@ class Feature(Enum):
     PATTERN_MATCHING = 11
     UNPACKING_ON_FLOW = 12
     ANN_ASSIGN_EXTENDED_RHS = 13
+    EXCEPT_STAR = 14
     FORCE_OPTIONAL_PARENTHESES = 50
 
     # __future__ flags
@@ -116,6 +118,21 @@ class Feature(Enum):
         Feature.ANN_ASSIGN_EXTENDED_RHS,
         Feature.PATTERN_MATCHING,
     },
+    TargetVersion.PY311: {
+        Feature.F_STRINGS,
+        Feature.NUMERIC_UNDERSCORES,
+        Feature.TRAILING_COMMA_IN_CALL,
+        Feature.TRAILING_COMMA_IN_DEF,
+        Feature.ASYNC_KEYWORDS,
+        Feature.FUTURE_ANNOTATIONS,
+        Feature.ASSIGNMENT_EXPRESSIONS,
+        Feature.RELAXED_DECORATORS,
+        Feature.POS_ONLY_ARGUMENTS,
+        Feature.UNPACKING_ON_FLOW,
+        Feature.ANN_ASSIGN_EXTENDED_RHS,
+        Feature.PATTERN_MATCHING,
+        Feature.EXCEPT_STAR,
+    },
 }
 
 
diff --git a/src/black/nodes.py b/src/black/nodes.py
index d18d4bde872..37b96a498d6 100644
--- a/src/black/nodes.py
+++ b/src/black/nodes.py
@@ -401,6 +401,10 @@ def whitespace(leaf: Leaf, *, complex_subscript: bool) -> str:  # noqa: C901
     elif p.type == syms.sliceop:
         return NO
 
+    elif p.type == syms.except_clause:
+        if t == token.STAR:
+            return NO
+
     return SPACE
 
 
diff --git a/src/blib2to3/Grammar.txt b/src/blib2to3/Grammar.txt
index 0ce6cf39111..1de54165513 100644
--- a/src/blib2to3/Grammar.txt
+++ b/src/blib2to3/Grammar.txt
@@ -118,7 +118,7 @@ try_stmt: ('try' ':' suite
 with_stmt: 'with' asexpr_test (',' asexpr_test)*  ':' suite
 
 # NB compile.c makes sure that the default except clause is last
-except_clause: 'except' [test [(',' | 'as') test]]
+except_clause: 'except' ['*'] [test [(',' | 'as') test]]
 suite: simple_stmt | NEWLINE INDENT stmt+ DEDENT
 
 # Backward compatibility cruft to support:
diff --git a/tests/data/pep_654.py b/tests/data/pep_654.py
new file mode 100644
index 00000000000..387c0816f4b
--- /dev/null
+++ b/tests/data/pep_654.py
@@ -0,0 +1,53 @@
+try:
+    raise OSError("blah")
+except* ExceptionGroup as e:
+    pass
+
+
+try:
+    async with trio.open_nursery() as nursery:
+        # Make two concurrent calls to child()
+        nursery.start_soon(child)
+        nursery.start_soon(child)
+except* ValueError:
+    pass
+
+try:
+    try:
+        raise ValueError(42)
+    except:
+        try:
+            raise TypeError(int)
+        except* Exception:
+            pass
+        1 / 0
+except Exception as e:
+    exc = e
+
+try:
+    try:
+        raise FalsyEG("eg", [TypeError(1), ValueError(2)])
+    except* TypeError as e:
+        tes = e
+        raise
+    except* ValueError as e:
+        ves = e
+        pass
+except Exception as e:
+    exc = e
+
+try:
+    try:
+        raise orig
+    except* (TypeError, ValueError) as e:
+        raise SyntaxError(3) from e
+except BaseException as e:
+    exc = e
+
+try:
+    try:
+        raise orig
+    except* OSError as e:
+        raise TypeError(3) from e
+except ExceptionGroup as e:
+    exc = e
diff --git a/tests/data/pep_654_style.py b/tests/data/pep_654_style.py
new file mode 100644
index 00000000000..568e5e3efa4
--- /dev/null
+++ b/tests/data/pep_654_style.py
@@ -0,0 +1,111 @@
+try:
+    raise OSError("blah")
+except               * ExceptionGroup as e:
+    pass
+
+
+try:
+    async with trio.open_nursery() as nursery:
+        # Make two concurrent calls to child()
+        nursery.start_soon(child)
+        nursery.start_soon(child)
+except *ValueError:
+    pass
+
+try:
+    try:
+        raise ValueError(42)
+    except:
+        try:
+            raise TypeError(int)
+        except *(Exception):
+            pass
+        1 / 0
+except Exception as e:
+    exc = e
+
+try:
+    try:
+        raise FalsyEG("eg", [TypeError(1), ValueError(2)])
+    except \
+        *TypeError as e:
+        tes = e
+        raise
+    except  *  ValueError as e:
+        ves = e
+        pass
+except Exception as e:
+    exc = e
+
+try:
+    try:
+        raise orig
+    except *(TypeError, ValueError, *OTHER_EXCEPTIONS) as e:
+        raise SyntaxError(3) from e
+except BaseException as e:
+    exc = e
+
+try:
+    try:
+        raise orig
+    except\
+        * OSError as e:
+        raise TypeError(3) from e
+except ExceptionGroup as e:
+    exc = e
+
+# output
+
+try:
+    raise OSError("blah")
+except* ExceptionGroup as e:
+    pass
+
+
+try:
+    async with trio.open_nursery() as nursery:
+        # Make two concurrent calls to child()
+        nursery.start_soon(child)
+        nursery.start_soon(child)
+except* ValueError:
+    pass
+
+try:
+    try:
+        raise ValueError(42)
+    except:
+        try:
+            raise TypeError(int)
+        except* (Exception):
+            pass
+        1 / 0
+except Exception as e:
+    exc = e
+
+try:
+    try:
+        raise FalsyEG("eg", [TypeError(1), ValueError(2)])
+    except* TypeError as e:
+        tes = e
+        raise
+    except* ValueError as e:
+        ves = e
+        pass
+except Exception as e:
+    exc = e
+
+try:
+    try:
+        raise orig
+    except* (TypeError, ValueError, *OTHER_EXCEPTIONS) as e:
+        raise SyntaxError(3) from e
+except BaseException as e:
+    exc = e
+
+try:
+    try:
+        raise orig
+    except* OSError as e:
+        raise TypeError(3) from e
+except ExceptionGroup as e:
+    exc = e
diff --git a/tests/test_black.py b/tests/test_black.py
index 20cc9f7379f..f6663fa5797 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -794,6 +794,12 @@ def test_get_features_used(self) -> None:
         self.assertEqual(
             black.get_features_used(node), {Feature.ANN_ASSIGN_EXTENDED_RHS}
         )
+        node = black.lib2to3_parse("try: pass\nexcept Something: pass")
+        self.assertEqual(black.get_features_used(node), set())
+        node = black.lib2to3_parse("try: pass\nexcept (*Something,): pass")
+        self.assertEqual(black.get_features_used(node), set())
+        node = black.lib2to3_parse("try: pass\nexcept *Group: pass")
+        self.assertEqual(black.get_features_used(node), {Feature.EXCEPT_STAR})
 
     def test_get_features_used_for_future_flags(self) -> None:
         for src, features in [
diff --git a/tests/test_format.py b/tests/test_format.py
index fd5f596b6d5..1916146e84d 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -72,6 +72,11 @@
     "parenthesized_context_managers",
 ]
 
+PY311_CASES: List[str] = [
+    "pep_654",
+    "pep_654_style",
+]
+
 PREVIEW_CASES: List[str] = [
     # string processing
     "cantfit",
@@ -227,6 +232,13 @@ def test_patma_invalid() -> None:
     exc_info.match("Cannot parse: 10:11")
 
 
+@pytest.mark.parametrize("filename", PY311_CASES)
+def test_python_311(filename: str) -> None:
+    source, expected = read_data(filename)
+    mode = black.Mode(target_versions={black.TargetVersion.PY311})
+    assert_format(source, expected, mode, minimum_version=(3, 11))
+
+
 def test_python_2_hint() -> None:
     with pytest.raises(black.parsing.InvalidInput) as exc_info:
         assert_format("print 'daylily'", "print 'daylily'")

From 8ed3e3d07ea3e6d62e3e533e69f96a0ff148cd5d Mon Sep 17 00:00:00 2001
From: JiriKr <33967184+JiriKr@users.noreply.github.com>
Date: Thu, 21 Apr 2022 21:55:56 +0200
Subject: [PATCH 0527/1034] Updated Black Docker Hub link in docs (#3023)

Fixes #3022
---
 docs/usage_and_configuration/black_docker_image.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/usage_and_configuration/black_docker_image.md b/docs/usage_and_configuration/black_docker_image.md
index 0a458434871..8de566ea270 100644
--- a/docs/usage_and_configuration/black_docker_image.md
+++ b/docs/usage_and_configuration/black_docker_image.md
@@ -1,7 +1,7 @@
 # Black Docker image
 
-Official _Black_ Docker images are available on Docker Hub:
-https://hub.docker.com/r/pyfound/black
+Official _Black_ Docker images are available on
+[Docker Hub](https://hub.docker.com/r/pyfound/black).
 
 _Black_ images with the following tags are available:
 

From c6800e0c659eba5b22190bf6ae0ba563a4170661 Mon Sep 17 00:00:00 2001
From: Vadim Nikolaev <defntvdm@gmail.com>
Date: Thu, 28 Apr 2022 20:17:23 +0500
Subject: [PATCH 0528/1034] Fix strtobool function (#3025)

* Fix strtobool function for vim plugin
* Update CHANGES.md

Co-authored-by: Cooper Lees <me@cooperlees.com>
---
 CHANGES.md         | 4 ++++
 autoload/black.vim | 4 ++--
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 566077b1dbc..4cea7fceaad 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -62,6 +62,10 @@
 
 <!-- Changes that improve Black's performance. -->
 
+### Vim Plugin
+
+- Fixed strtobool function. It didn't parse true/on/false/off. (#3025)
+
 ## 22.3.0
 
 ### Preview style
diff --git a/autoload/black.vim b/autoload/black.vim
index 66c5b9c2841..6c381b431a3 100644
--- a/autoload/black.vim
+++ b/autoload/black.vim
@@ -5,9 +5,9 @@ import sys
 import vim
 
 def strtobool(text):
-  if text.lower() in ['y', 'yes', 't', 'true' 'on', '1']:
+  if text.lower() in ['y', 'yes', 't', 'true', 'on', '1']:
     return True
-  if text.lower() in ['n', 'no', 'f', 'false' 'off', '0']:
+  if text.lower() in ['n', 'no', 'f', 'false', 'off', '0']:
     return False
   raise ValueError(f"{text} is not convertable to boolean")
 

From fb8dfdeec5fd76cc0c30f881d6fc75851139d80a Mon Sep 17 00:00:00 2001
From: Cooper Lees <cooper@fb.com>
Date: Thu, 28 Apr 2022 10:27:16 -0600
Subject: [PATCH 0529/1034] Stop pinning lark-parser (#3041)

- Latest version works more

Test: `tox -e fuzz`
---
 tox.ini | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/tox.ini b/tox.ini
index 090dc522cad..258e6c5c203 100644
--- a/tox.ini
+++ b/tox.ini
@@ -55,8 +55,7 @@ skip_install = True
 deps =
     -r{toxinidir}/test_requirements.txt
     hypothesmith
-    lark-parser < 0.10.0
-; lark-parser's version is set due to a bug in hypothesis. Once it solved, that would be fixed.
+    lark-parser
 commands =
     pip install -e .[d]
     coverage erase

From 9d5edd302003285b5280e3dd209d6299feafb70e Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 2 May 2022 11:12:23 -0600
Subject: [PATCH 0530/1034] Bump myst-parser from 0.16.1 to 0.17.2 in /docs
 (#3019)

Bumps [myst-parser](https://github.com/executablebooks/MyST-Parser) from 0.16.1 to 0.17.2.
- [Release notes](https://github.com/executablebooks/MyST-Parser/releases)
- [Changelog](https://github.com/executablebooks/MyST-Parser/blob/master/CHANGELOG.md)
- [Commits](https://github.com/executablebooks/MyST-Parser/compare/v0.16.1...v0.17.2)

---
updated-dependencies:
- dependency-name: myst-parser
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 docs/requirements.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index 818415c6cf8..72cf09fb6e9 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,6 +1,6 @@
 # Used by ReadTheDocs; pinned requirements for stability.
 
-myst-parser==0.16.1
+myst-parser==0.17.2
 Sphinx==4.5.0
 sphinxcontrib-programoutput==0.17
 sphinx_copybutton==0.5.0

From c940f75d5b646777427aef1beb18a0d2c391f5e2 Mon Sep 17 00:00:00 2001
From: Naveen <172697+naveensrinivasan@users.noreply.github.com>
Date: Tue, 3 May 2022 08:08:33 -0500
Subject: [PATCH 0531/1034] chore: Set permissions for GitHub actions (#3043)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Restrict the GitHub token permissions only to the required ones; this way, even if the attackers will succeed in compromising your workflow, they won’t be able to do much.

- Included permissions for the action. https://github.com/ossf/scorecard/blob/main/docs/checks.md#token-permissions

https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#permissions

https://docs.github.com/en/actions/using-jobs/assigning-permissions-to-jobs

[Keeping your GitHub Actions and workflows secure Part 1: Preventing pwn requests](https://securitylab.github.com/research/github-actions-preventing-pwn-requests/)

Signed-off-by: naveen <172697+naveensrinivasan@users.noreply.github.com>
---
 .github/workflows/changelog.yml     | 3 +++
 .github/workflows/doc.yml           | 3 +++
 .github/workflows/docker.yml        | 3 +++
 .github/workflows/fuzz.yml          | 3 +++
 .github/workflows/pypi_upload.yml   | 3 +++
 .github/workflows/upload_binary.yml | 5 +++++
 .github/workflows/uvloop_test.yml   | 3 +++
 7 files changed, 23 insertions(+)

diff --git a/.github/workflows/changelog.yml b/.github/workflows/changelog.yml
index 3ffdb086493..b3e1f0b9024 100644
--- a/.github/workflows/changelog.yml
+++ b/.github/workflows/changelog.yml
@@ -4,6 +4,9 @@ on:
   pull_request:
     types: [opened, synchronize, labeled, unlabeled, reopened]
 
+permissions:
+  contents: read
+
 jobs:
   build:
     name: Changelog Entry Check
diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml
index 1ad4b3a7605..e2a0142cc65 100644
--- a/.github/workflows/doc.yml
+++ b/.github/workflows/doc.yml
@@ -2,6 +2,9 @@ name: Documentation Build
 
 on: [push, pull_request]
 
+permissions:
+  contents: read
+
 jobs:
   build:
     # We want to run on external PRs, but not on our own internal PRs as they'll be run
diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
index b75ce2bb6f1..0a4848faad8 100644
--- a/.github/workflows/docker.yml
+++ b/.github/workflows/docker.yml
@@ -7,6 +7,9 @@ on:
   release:
     types: [published]
 
+permissions:
+  contents: read
+
 jobs:
   docker:
     if: github.repository == 'psf/black'
diff --git a/.github/workflows/fuzz.yml b/.github/workflows/fuzz.yml
index 8fba67a5a01..d796fd50564 100644
--- a/.github/workflows/fuzz.yml
+++ b/.github/workflows/fuzz.yml
@@ -2,6 +2,9 @@ name: Fuzz
 
 on: [push, pull_request]
 
+permissions:
+  contents: read
+
 jobs:
   build:
     # We want to run on external PRs, but not on our own internal PRs as they'll be run
diff --git a/.github/workflows/pypi_upload.yml b/.github/workflows/pypi_upload.yml
index 9d970592d98..ef524a8ece6 100644
--- a/.github/workflows/pypi_upload.yml
+++ b/.github/workflows/pypi_upload.yml
@@ -4,6 +4,9 @@ on:
   release:
     types: [published]
 
+permissions:
+  contents: read
+
 jobs:
   build:
     name: PyPI Upload
diff --git a/.github/workflows/upload_binary.yml b/.github/workflows/upload_binary.yml
index ed8d9fdd572..6bb1d23306b 100644
--- a/.github/workflows/upload_binary.yml
+++ b/.github/workflows/upload_binary.yml
@@ -4,8 +4,13 @@ on:
   release:
     types: [published]
 
+permissions:
+  contents: read
+
 jobs:
   build:
+    permissions:
+      contents: write # for actions/upload-release-asset to upload release asset
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
diff --git a/.github/workflows/uvloop_test.yml b/.github/workflows/uvloop_test.yml
index 14b17d68424..bbc39935f89 100644
--- a/.github/workflows/uvloop_test.yml
+++ b/.github/workflows/uvloop_test.yml
@@ -11,6 +11,9 @@ on:
       - "docs/**"
       - "*.md"
 
+permissions:
+  contents: read
+
 jobs:
   build:
     # We want to run on external PRs, but not on our own internal PRs as they'll be run

From 9ce100ba61b6738298d86818a3d0eee7b18bfed7 Mon Sep 17 00:00:00 2001
From: Zac Hatfield-Dodds <zac.hatfield.dodds@gmail.com>
Date: Fri, 6 May 2022 07:06:27 -0700
Subject: [PATCH 0532/1034] Move imports of `ThreadPoolExecutor` into
 `reformat_many()`, allowing Black-in-the-browser (#3046)

This is a slight perf win for use-cases that don't invoke `reformat_many()`, but more importantly to me today it means I can use Black in pyscript.
---
 src/black/__init__.py | 9 +++++++--
 tests/test_black.py   | 6 +++---
 2 files changed, 10 insertions(+), 5 deletions(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index 3a1ce24f059..75321c3f35c 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -1,7 +1,6 @@
 import asyncio
 from json.decoder import JSONDecodeError
 import json
-from concurrent.futures import Executor, ThreadPoolExecutor, ProcessPoolExecutor
 from contextlib import contextmanager
 from datetime import datetime
 from enum import Enum
@@ -17,6 +16,7 @@
 import tokenize
 import traceback
 from typing import (
+    TYPE_CHECKING,
     Any,
     Dict,
     Generator,
@@ -77,6 +77,9 @@
 
 from _black_version import version as __version__
 
+if TYPE_CHECKING:
+    from concurrent.futures import Executor
+
 COMPILED = Path(__file__).suffix in (".pyd", ".so")
 
 # types
@@ -767,6 +770,8 @@ def reformat_many(
     workers: Optional[int],
 ) -> None:
     """Reformat multiple files using a ProcessPoolExecutor."""
+    from concurrent.futures import Executor, ThreadPoolExecutor, ProcessPoolExecutor
+
     executor: Executor
     loop = asyncio.get_event_loop()
     worker_count = workers if workers is not None else DEFAULT_WORKERS
@@ -808,7 +813,7 @@ async def schedule_formatting(
     mode: Mode,
     report: "Report",
     loop: asyncio.AbstractEventLoop,
-    executor: Executor,
+    executor: "Executor",
 ) -> None:
     """Run formatting of `sources` in parallel using the provided `executor`.
 
diff --git a/tests/test_black.py b/tests/test_black.py
index f6663fa5797..74334d267a1 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -922,7 +922,7 @@ def err(msg: str, **kwargs: Any) -> None:
         self.assertEqual("".join(err_lines), "")
 
     @event_loop()
-    @patch("black.ProcessPoolExecutor", MagicMock(side_effect=OSError))
+    @patch("concurrent.futures.ProcessPoolExecutor", MagicMock(side_effect=OSError))
     def test_works_in_mono_process_only_environment(self) -> None:
         with cache_dir() as workspace:
             for f in [
@@ -1683,7 +1683,7 @@ def test_cache_single_file_already_cached(self) -> None:
     def test_cache_multiple_files(self) -> None:
         mode = DEFAULT_MODE
         with cache_dir() as workspace, patch(
-            "black.ProcessPoolExecutor", new=ThreadPoolExecutor
+            "concurrent.futures.ProcessPoolExecutor", new=ThreadPoolExecutor
         ):
             one = (workspace / "one.py").resolve()
             with one.open("w") as fobj:
@@ -1792,7 +1792,7 @@ def test_write_cache_creates_directory_if_needed(self) -> None:
     def test_failed_formatting_does_not_get_cached(self) -> None:
         mode = DEFAULT_MODE
         with cache_dir() as workspace, patch(
-            "black.ProcessPoolExecutor", new=ThreadPoolExecutor
+            "concurrent.futures.ProcessPoolExecutor", new=ThreadPoolExecutor
         ):
             failing = (workspace / "failing.py").resolve()
             with failing.open("w") as fobj:

From 62c2b167bcf22683fc11add2f24a132d36e8fd19 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Felix=20Hild=C3=A9n?= <felix.hilden@gmail.com>
Date: Sun, 8 May 2022 03:58:10 +0300
Subject: [PATCH 0533/1034] Docs: clarify fmt:on/off requirements (#2985)
 (#3048)

---
 docs/the_black_code_style/current_style.md | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/docs/the_black_code_style/current_style.md b/docs/the_black_code_style/current_style.md
index d54c7abaf5d..5085b0017d9 100644
--- a/docs/the_black_code_style/current_style.md
+++ b/docs/the_black_code_style/current_style.md
@@ -8,9 +8,10 @@ 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 blocks that start with
-`# fmt: off` and end with `# fmt: on`, or lines that ends with `# fmt: skip`.
-`# fmt: on/off` have to be on the same level of indentation. It also recognizes
+_Black_ reformats entire files in place. It doesn't reformat lines that end with
+`# 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.
 

From 20d8ccb54253f8a66321f6708d53e2a05a54079b Mon Sep 17 00:00:00 2001
From: Iain Dorrington <idorrington92@users.noreply.github.com>
Date: Sun, 8 May 2022 05:34:28 +0100
Subject: [PATCH 0534/1034] Put closing quote on a separate line if docstring
 is too long (#3044)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fixes #1632

Co-authored-by: Felix Hildén <felix.hilden@gmail.com>
---
 CHANGES.md                      |  1 +
 src/black/linegen.py            | 26 +++++++++-
 src/black/mode.py               |  1 +
 tests/data/docstring.py         | 42 ++++++++++++++++
 tests/data/docstring_preview.py | 89 +++++++++++++++++++++++++++++++++
 tests/test_format.py            |  1 +
 6 files changed, 158 insertions(+), 2 deletions(-)
 create mode 100644 tests/data/docstring_preview.py

diff --git a/CHANGES.md b/CHANGES.md
index 4cea7fceaad..8f43431c842 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -17,6 +17,7 @@
 
 <!-- Changes that affect Black's preview style -->
 
+- Fixed bug where docstrings with triple quotes could exceed max line length (#3044)
 - Remove redundant parentheses around awaited objects (#2991)
 - Parentheses around return annotations are now managed (#2990)
 - Remove unnecessary parentheses from `with` statements (#2926)
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 91fdeef8f2f..ff54e05c4e6 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -305,9 +305,9 @@ def visit_STRING(self, leaf: Leaf) -> Iterator[Line]:
             quote_len = 1 if docstring[1] != quote_char else 3
             docstring = docstring[quote_len:-quote_len]
             docstring_started_empty = not docstring
+            indent = " " * 4 * self.current_line.depth
 
             if is_multiline_string(leaf):
-                indent = " " * 4 * self.current_line.depth
                 docstring = fix_docstring(docstring, indent)
             else:
                 docstring = docstring.strip()
@@ -329,7 +329,29 @@ def visit_STRING(self, leaf: Leaf) -> Iterator[Line]:
 
             # We could enforce triple quotes at this point.
             quote = quote_char * quote_len
-            leaf.value = prefix + quote + docstring + quote
+
+            if Preview.long_docstring_quotes_on_newline in self.mode:
+                # We need to find the length of the last line of the docstring
+                # to find if we can add the closing quotes to the line without
+                # exceeding the maximum line length.
+                # If docstring is one line, then we need to add the length
+                # of the indent, prefix, and starting quotes. Ending quote are
+                # handled later
+                lines = docstring.splitlines()
+                last_line_length = len(lines[-1]) if docstring else 0
+
+                if len(lines) == 1:
+                    last_line_length += len(indent) + len(prefix) + quote_len
+
+                # If adding closing quotes would cause the last line to exceed
+                # the maximum line length then put a line break before the
+                # closing quotes
+                if last_line_length + quote_len > self.mode.line_length:
+                    leaf.value = prefix + quote + docstring + "\n" + indent + quote
+                else:
+                    leaf.value = prefix + quote + docstring + quote
+            else:
+                leaf.value = prefix + quote + docstring + quote
 
         yield from self.visit_default(leaf)
 
diff --git a/src/black/mode.py b/src/black/mode.py
index 6bd4ce14421..a418e0eb665 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -147,6 +147,7 @@ class Preview(Enum):
     remove_redundant_parens = auto()
     one_element_subscript = auto()
     annotation_parens = auto()
+    long_docstring_quotes_on_newline = auto()
 
 
 class Deprecated(UserWarning):
diff --git a/tests/data/docstring.py b/tests/data/docstring.py
index 96bcf525b16..7153be468c1 100644
--- a/tests/data/docstring.py
+++ b/tests/data/docstring.py
@@ -188,6 +188,27 @@ def my_god_its_full_of_stars_2():
     "I'm sorry Dave "
 
 
+def docstring_almost_at_line_limit():
+    """long docstring................................................................."""
+
+
+def docstring_almost_at_line_limit2():
+    """long docstring.................................................................
+
+    ..................................................................................
+    """
+
+
+def docstring_at_line_limit():
+    """long docstring................................................................"""
+
+
+def multiline_docstring_at_line_limit():
+    """first line-----------------------------------------------------------------------
+
+    second line----------------------------------------------------------------------"""
+
+
 # output
 
 class MyClass:
@@ -375,3 +396,24 @@ def my_god_its_full_of_stars_1():
 # the space below is actually a \u2001, removed in output
 def my_god_its_full_of_stars_2():
     "I'm sorry Dave"
+
+
+def docstring_almost_at_line_limit():
+    """long docstring................................................................."""
+
+
+def docstring_almost_at_line_limit2():
+    """long docstring.................................................................
+
+    ..................................................................................
+    """
+
+
+def docstring_at_line_limit():
+    """long docstring................................................................"""
+
+
+def multiline_docstring_at_line_limit():
+    """first line-----------------------------------------------------------------------
+
+    second line----------------------------------------------------------------------"""
diff --git a/tests/data/docstring_preview.py b/tests/data/docstring_preview.py
new file mode 100644
index 00000000000..2da4cd1acdb
--- /dev/null
+++ b/tests/data/docstring_preview.py
@@ -0,0 +1,89 @@
+def docstring_almost_at_line_limit():
+    """long docstring.................................................................
+    """
+
+
+def docstring_almost_at_line_limit_with_prefix():
+    f"""long docstring................................................................
+    """
+
+
+def mulitline_docstring_almost_at_line_limit():
+    """long docstring.................................................................
+
+    ..................................................................................
+    """
+
+
+def mulitline_docstring_almost_at_line_limit_with_prefix():
+    f"""long docstring................................................................
+
+    ..................................................................................
+    """
+
+
+def docstring_at_line_limit():
+    """long docstring................................................................"""
+
+
+def docstring_at_line_limit_with_prefix():
+    f"""long docstring..............................................................."""
+
+
+def multiline_docstring_at_line_limit():
+    """first line-----------------------------------------------------------------------
+
+    second line----------------------------------------------------------------------"""
+
+
+def multiline_docstring_at_line_limit_with_prefix():
+    f"""first line----------------------------------------------------------------------
+
+    second line----------------------------------------------------------------------"""
+
+
+# output
+
+
+def docstring_almost_at_line_limit():
+    """long docstring.................................................................
+    """
+
+
+def docstring_almost_at_line_limit_with_prefix():
+    f"""long docstring................................................................
+    """
+
+
+def mulitline_docstring_almost_at_line_limit():
+    """long docstring.................................................................
+
+    ..................................................................................
+    """
+
+
+def mulitline_docstring_almost_at_line_limit_with_prefix():
+    f"""long docstring................................................................
+
+    ..................................................................................
+    """
+
+
+def docstring_at_line_limit():
+    """long docstring................................................................"""
+
+
+def docstring_at_line_limit_with_prefix():
+    f"""long docstring..............................................................."""
+
+
+def multiline_docstring_at_line_limit():
+    """first line-----------------------------------------------------------------------
+
+    second line----------------------------------------------------------------------"""
+
+
+def multiline_docstring_at_line_limit_with_prefix():
+    f"""first line----------------------------------------------------------------------
+
+    second line----------------------------------------------------------------------"""
diff --git a/tests/test_format.py b/tests/test_format.py
index 1916146e84d..2f08d1f273d 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -91,6 +91,7 @@
     "one_element_subscript",
     "remove_await_parens",
     "return_annotation_brackets",
+    "docstring_preview",
 ]
 
 SOURCES: List[str] = [

From fc2a16433e7da705793122dd0c66fcde83b305d5 Mon Sep 17 00:00:00 2001
From: Sagi Shadur <saroad2@gmail.com>
Date: Sun, 8 May 2022 22:27:40 +0300
Subject: [PATCH 0535/1034] Read simple data cases automatically (#3034)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Felix Hildén <felix.hilden@gmail.com>
---
 .../attribute_access_on_number_literals.py    |  0
 .../{ => simple_cases}/beginning_backslash.py |  0
 tests/data/{ => simple_cases}/bracketmatch.py |  0
 .../class_blank_parentheses.py                |  0
 .../class_methods_new_line.py                 |  0
 tests/data/{ => simple_cases}/collections.py  |  0
 .../comment_after_escaped_newline.py          |  0
 tests/data/{ => simple_cases}/comments.py     |  0
 tests/data/{ => simple_cases}/comments2.py    |  0
 tests/data/{ => simple_cases}/comments3.py    |  0
 tests/data/{ => simple_cases}/comments4.py    |  0
 tests/data/{ => simple_cases}/comments5.py    |  0
 tests/data/{ => simple_cases}/comments6.py    |  0
 .../comments_non_breaking_space.py            |  0
 tests/data/{ => simple_cases}/composition.py  |  0
 .../composition_no_trailing_comma.py          |  0
 tests/data/{ => simple_cases}/docstring.py    |  0
 tests/data/{ => simple_cases}/empty_lines.py  |  0
 tests/data/{ => simple_cases}/expression.diff |  0
 tests/data/{ => simple_cases}/expression.py   |  0
 tests/data/{ => simple_cases}/fmtonoff.py     |  0
 tests/data/{ => simple_cases}/fmtonoff2.py    |  0
 tests/data/{ => simple_cases}/fmtonoff3.py    |  0
 tests/data/{ => simple_cases}/fmtonoff4.py    |  0
 tests/data/{ => simple_cases}/fmtskip.py      |  0
 tests/data/{ => simple_cases}/fmtskip2.py     |  0
 tests/data/{ => simple_cases}/fmtskip3.py     |  0
 tests/data/{ => simple_cases}/fmtskip4.py     |  0
 tests/data/{ => simple_cases}/fmtskip5.py     |  0
 tests/data/{ => simple_cases}/fmtskip6.py     |  0
 tests/data/{ => simple_cases}/fmtskip7.py     |  0
 tests/data/{ => simple_cases}/fstring.py      |  0
 tests/data/{ => simple_cases}/function.py     |  0
 tests/data/{ => simple_cases}/function2.py    |  0
 .../function_trailing_comma.py                |  0
 .../data/{ => simple_cases}/import_spacing.py |  0
 .../{ => simple_cases}/power_op_spacing.py    |  0
 .../data/{ => simple_cases}/remove_parens.py  |  0
 tests/data/{ => simple_cases}/slices.py       |  0
 .../{ => simple_cases}/string_prefixes.py     |  0
 tests/data/{ => simple_cases}/torture.py      |  0
 .../trailing_comma_optional_parens1.py        |  0
 .../trailing_comma_optional_parens2.py        |  0
 .../trailing_comma_optional_parens3.py        |  0
 .../tricky_unicode_symbols.py                 |  0
 tests/data/{ => simple_cases}/tupleassign.py  |  0
 tests/test_black.py                           | 26 +++++-----
 tests/test_format.py                          | 51 +------------------
 tests/util.py                                 | 11 +++-
 49 files changed, 25 insertions(+), 63 deletions(-)
 rename tests/data/{ => simple_cases}/attribute_access_on_number_literals.py (100%)
 rename tests/data/{ => simple_cases}/beginning_backslash.py (100%)
 rename tests/data/{ => simple_cases}/bracketmatch.py (100%)
 rename tests/data/{ => simple_cases}/class_blank_parentheses.py (100%)
 rename tests/data/{ => simple_cases}/class_methods_new_line.py (100%)
 rename tests/data/{ => simple_cases}/collections.py (100%)
 rename tests/data/{ => simple_cases}/comment_after_escaped_newline.py (100%)
 rename tests/data/{ => simple_cases}/comments.py (100%)
 rename tests/data/{ => simple_cases}/comments2.py (100%)
 rename tests/data/{ => simple_cases}/comments3.py (100%)
 rename tests/data/{ => simple_cases}/comments4.py (100%)
 rename tests/data/{ => simple_cases}/comments5.py (100%)
 rename tests/data/{ => simple_cases}/comments6.py (100%)
 rename tests/data/{ => simple_cases}/comments_non_breaking_space.py (100%)
 rename tests/data/{ => simple_cases}/composition.py (100%)
 rename tests/data/{ => simple_cases}/composition_no_trailing_comma.py (100%)
 rename tests/data/{ => simple_cases}/docstring.py (100%)
 rename tests/data/{ => simple_cases}/empty_lines.py (100%)
 rename tests/data/{ => simple_cases}/expression.diff (100%)
 rename tests/data/{ => simple_cases}/expression.py (100%)
 rename tests/data/{ => simple_cases}/fmtonoff.py (100%)
 rename tests/data/{ => simple_cases}/fmtonoff2.py (100%)
 rename tests/data/{ => simple_cases}/fmtonoff3.py (100%)
 rename tests/data/{ => simple_cases}/fmtonoff4.py (100%)
 rename tests/data/{ => simple_cases}/fmtskip.py (100%)
 rename tests/data/{ => simple_cases}/fmtskip2.py (100%)
 rename tests/data/{ => simple_cases}/fmtskip3.py (100%)
 rename tests/data/{ => simple_cases}/fmtskip4.py (100%)
 rename tests/data/{ => simple_cases}/fmtskip5.py (100%)
 rename tests/data/{ => simple_cases}/fmtskip6.py (100%)
 rename tests/data/{ => simple_cases}/fmtskip7.py (100%)
 rename tests/data/{ => simple_cases}/fstring.py (100%)
 rename tests/data/{ => simple_cases}/function.py (100%)
 rename tests/data/{ => simple_cases}/function2.py (100%)
 rename tests/data/{ => simple_cases}/function_trailing_comma.py (100%)
 rename tests/data/{ => simple_cases}/import_spacing.py (100%)
 rename tests/data/{ => simple_cases}/power_op_spacing.py (100%)
 rename tests/data/{ => simple_cases}/remove_parens.py (100%)
 rename tests/data/{ => simple_cases}/slices.py (100%)
 rename tests/data/{ => simple_cases}/string_prefixes.py (100%)
 rename tests/data/{ => simple_cases}/torture.py (100%)
 rename tests/data/{ => simple_cases}/trailing_comma_optional_parens1.py (100%)
 rename tests/data/{ => simple_cases}/trailing_comma_optional_parens2.py (100%)
 rename tests/data/{ => simple_cases}/trailing_comma_optional_parens3.py (100%)
 rename tests/data/{ => simple_cases}/tricky_unicode_symbols.py (100%)
 rename tests/data/{ => simple_cases}/tupleassign.py (100%)

diff --git a/tests/data/attribute_access_on_number_literals.py b/tests/data/simple_cases/attribute_access_on_number_literals.py
similarity index 100%
rename from tests/data/attribute_access_on_number_literals.py
rename to tests/data/simple_cases/attribute_access_on_number_literals.py
diff --git a/tests/data/beginning_backslash.py b/tests/data/simple_cases/beginning_backslash.py
similarity index 100%
rename from tests/data/beginning_backslash.py
rename to tests/data/simple_cases/beginning_backslash.py
diff --git a/tests/data/bracketmatch.py b/tests/data/simple_cases/bracketmatch.py
similarity index 100%
rename from tests/data/bracketmatch.py
rename to tests/data/simple_cases/bracketmatch.py
diff --git a/tests/data/class_blank_parentheses.py b/tests/data/simple_cases/class_blank_parentheses.py
similarity index 100%
rename from tests/data/class_blank_parentheses.py
rename to tests/data/simple_cases/class_blank_parentheses.py
diff --git a/tests/data/class_methods_new_line.py b/tests/data/simple_cases/class_methods_new_line.py
similarity index 100%
rename from tests/data/class_methods_new_line.py
rename to tests/data/simple_cases/class_methods_new_line.py
diff --git a/tests/data/collections.py b/tests/data/simple_cases/collections.py
similarity index 100%
rename from tests/data/collections.py
rename to tests/data/simple_cases/collections.py
diff --git a/tests/data/comment_after_escaped_newline.py b/tests/data/simple_cases/comment_after_escaped_newline.py
similarity index 100%
rename from tests/data/comment_after_escaped_newline.py
rename to tests/data/simple_cases/comment_after_escaped_newline.py
diff --git a/tests/data/comments.py b/tests/data/simple_cases/comments.py
similarity index 100%
rename from tests/data/comments.py
rename to tests/data/simple_cases/comments.py
diff --git a/tests/data/comments2.py b/tests/data/simple_cases/comments2.py
similarity index 100%
rename from tests/data/comments2.py
rename to tests/data/simple_cases/comments2.py
diff --git a/tests/data/comments3.py b/tests/data/simple_cases/comments3.py
similarity index 100%
rename from tests/data/comments3.py
rename to tests/data/simple_cases/comments3.py
diff --git a/tests/data/comments4.py b/tests/data/simple_cases/comments4.py
similarity index 100%
rename from tests/data/comments4.py
rename to tests/data/simple_cases/comments4.py
diff --git a/tests/data/comments5.py b/tests/data/simple_cases/comments5.py
similarity index 100%
rename from tests/data/comments5.py
rename to tests/data/simple_cases/comments5.py
diff --git a/tests/data/comments6.py b/tests/data/simple_cases/comments6.py
similarity index 100%
rename from tests/data/comments6.py
rename to tests/data/simple_cases/comments6.py
diff --git a/tests/data/comments_non_breaking_space.py b/tests/data/simple_cases/comments_non_breaking_space.py
similarity index 100%
rename from tests/data/comments_non_breaking_space.py
rename to tests/data/simple_cases/comments_non_breaking_space.py
diff --git a/tests/data/composition.py b/tests/data/simple_cases/composition.py
similarity index 100%
rename from tests/data/composition.py
rename to tests/data/simple_cases/composition.py
diff --git a/tests/data/composition_no_trailing_comma.py b/tests/data/simple_cases/composition_no_trailing_comma.py
similarity index 100%
rename from tests/data/composition_no_trailing_comma.py
rename to tests/data/simple_cases/composition_no_trailing_comma.py
diff --git a/tests/data/docstring.py b/tests/data/simple_cases/docstring.py
similarity index 100%
rename from tests/data/docstring.py
rename to tests/data/simple_cases/docstring.py
diff --git a/tests/data/empty_lines.py b/tests/data/simple_cases/empty_lines.py
similarity index 100%
rename from tests/data/empty_lines.py
rename to tests/data/simple_cases/empty_lines.py
diff --git a/tests/data/expression.diff b/tests/data/simple_cases/expression.diff
similarity index 100%
rename from tests/data/expression.diff
rename to tests/data/simple_cases/expression.diff
diff --git a/tests/data/expression.py b/tests/data/simple_cases/expression.py
similarity index 100%
rename from tests/data/expression.py
rename to tests/data/simple_cases/expression.py
diff --git a/tests/data/fmtonoff.py b/tests/data/simple_cases/fmtonoff.py
similarity index 100%
rename from tests/data/fmtonoff.py
rename to tests/data/simple_cases/fmtonoff.py
diff --git a/tests/data/fmtonoff2.py b/tests/data/simple_cases/fmtonoff2.py
similarity index 100%
rename from tests/data/fmtonoff2.py
rename to tests/data/simple_cases/fmtonoff2.py
diff --git a/tests/data/fmtonoff3.py b/tests/data/simple_cases/fmtonoff3.py
similarity index 100%
rename from tests/data/fmtonoff3.py
rename to tests/data/simple_cases/fmtonoff3.py
diff --git a/tests/data/fmtonoff4.py b/tests/data/simple_cases/fmtonoff4.py
similarity index 100%
rename from tests/data/fmtonoff4.py
rename to tests/data/simple_cases/fmtonoff4.py
diff --git a/tests/data/fmtskip.py b/tests/data/simple_cases/fmtskip.py
similarity index 100%
rename from tests/data/fmtskip.py
rename to tests/data/simple_cases/fmtskip.py
diff --git a/tests/data/fmtskip2.py b/tests/data/simple_cases/fmtskip2.py
similarity index 100%
rename from tests/data/fmtskip2.py
rename to tests/data/simple_cases/fmtskip2.py
diff --git a/tests/data/fmtskip3.py b/tests/data/simple_cases/fmtskip3.py
similarity index 100%
rename from tests/data/fmtskip3.py
rename to tests/data/simple_cases/fmtskip3.py
diff --git a/tests/data/fmtskip4.py b/tests/data/simple_cases/fmtskip4.py
similarity index 100%
rename from tests/data/fmtskip4.py
rename to tests/data/simple_cases/fmtskip4.py
diff --git a/tests/data/fmtskip5.py b/tests/data/simple_cases/fmtskip5.py
similarity index 100%
rename from tests/data/fmtskip5.py
rename to tests/data/simple_cases/fmtskip5.py
diff --git a/tests/data/fmtskip6.py b/tests/data/simple_cases/fmtskip6.py
similarity index 100%
rename from tests/data/fmtskip6.py
rename to tests/data/simple_cases/fmtskip6.py
diff --git a/tests/data/fmtskip7.py b/tests/data/simple_cases/fmtskip7.py
similarity index 100%
rename from tests/data/fmtskip7.py
rename to tests/data/simple_cases/fmtskip7.py
diff --git a/tests/data/fstring.py b/tests/data/simple_cases/fstring.py
similarity index 100%
rename from tests/data/fstring.py
rename to tests/data/simple_cases/fstring.py
diff --git a/tests/data/function.py b/tests/data/simple_cases/function.py
similarity index 100%
rename from tests/data/function.py
rename to tests/data/simple_cases/function.py
diff --git a/tests/data/function2.py b/tests/data/simple_cases/function2.py
similarity index 100%
rename from tests/data/function2.py
rename to tests/data/simple_cases/function2.py
diff --git a/tests/data/function_trailing_comma.py b/tests/data/simple_cases/function_trailing_comma.py
similarity index 100%
rename from tests/data/function_trailing_comma.py
rename to tests/data/simple_cases/function_trailing_comma.py
diff --git a/tests/data/import_spacing.py b/tests/data/simple_cases/import_spacing.py
similarity index 100%
rename from tests/data/import_spacing.py
rename to tests/data/simple_cases/import_spacing.py
diff --git a/tests/data/power_op_spacing.py b/tests/data/simple_cases/power_op_spacing.py
similarity index 100%
rename from tests/data/power_op_spacing.py
rename to tests/data/simple_cases/power_op_spacing.py
diff --git a/tests/data/remove_parens.py b/tests/data/simple_cases/remove_parens.py
similarity index 100%
rename from tests/data/remove_parens.py
rename to tests/data/simple_cases/remove_parens.py
diff --git a/tests/data/slices.py b/tests/data/simple_cases/slices.py
similarity index 100%
rename from tests/data/slices.py
rename to tests/data/simple_cases/slices.py
diff --git a/tests/data/string_prefixes.py b/tests/data/simple_cases/string_prefixes.py
similarity index 100%
rename from tests/data/string_prefixes.py
rename to tests/data/simple_cases/string_prefixes.py
diff --git a/tests/data/torture.py b/tests/data/simple_cases/torture.py
similarity index 100%
rename from tests/data/torture.py
rename to tests/data/simple_cases/torture.py
diff --git a/tests/data/trailing_comma_optional_parens1.py b/tests/data/simple_cases/trailing_comma_optional_parens1.py
similarity index 100%
rename from tests/data/trailing_comma_optional_parens1.py
rename to tests/data/simple_cases/trailing_comma_optional_parens1.py
diff --git a/tests/data/trailing_comma_optional_parens2.py b/tests/data/simple_cases/trailing_comma_optional_parens2.py
similarity index 100%
rename from tests/data/trailing_comma_optional_parens2.py
rename to tests/data/simple_cases/trailing_comma_optional_parens2.py
diff --git a/tests/data/trailing_comma_optional_parens3.py b/tests/data/simple_cases/trailing_comma_optional_parens3.py
similarity index 100%
rename from tests/data/trailing_comma_optional_parens3.py
rename to tests/data/simple_cases/trailing_comma_optional_parens3.py
diff --git a/tests/data/tricky_unicode_symbols.py b/tests/data/simple_cases/tricky_unicode_symbols.py
similarity index 100%
rename from tests/data/tricky_unicode_symbols.py
rename to tests/data/simple_cases/tricky_unicode_symbols.py
diff --git a/tests/data/tupleassign.py b/tests/data/simple_cases/tupleassign.py
similarity index 100%
rename from tests/data/tupleassign.py
rename to tests/data/simple_cases/tupleassign.py
diff --git a/tests/test_black.py b/tests/test_black.py
index 74334d267a1..281019a0bfa 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -179,8 +179,8 @@ def test_piping_diff(self) -> None:
             r"(STDIN|STDOUT)\t\d\d\d\d-\d\d-\d\d \d\d:\d\d:\d\d\.\d\d\d\d\d\d "
             r"\+\d\d\d\d"
         )
-        source, _ = read_data("expression.py")
-        expected, _ = read_data("expression.diff")
+        source, _ = read_data("simple_cases/expression.py")
+        expected, _ = read_data("simple_cases/expression.diff")
         args = [
             "-",
             "--fast",
@@ -197,7 +197,7 @@ def test_piping_diff(self) -> None:
         self.assertEqual(expected, actual)
 
     def test_piping_diff_with_color(self) -> None:
-        source, _ = read_data("expression.py")
+        source, _ = read_data("simple_cases/expression.py")
         args = [
             "-",
             "--fast",
@@ -241,7 +241,7 @@ def test_pep_572_version_detection(self) -> None:
         self.assertIn(black.TargetVersion.PY38, versions)
 
     def test_expression_ff(self) -> None:
-        source, expected = read_data("expression")
+        source, expected = read_data("simple_cases/expression.py")
         tmp_file = Path(black.dump_to_file(source))
         try:
             self.assertTrue(ff(tmp_file, write_back=black.WriteBack.YES))
@@ -255,8 +255,8 @@ def test_expression_ff(self) -> None:
             black.assert_stable(source, actual, DEFAULT_MODE)
 
     def test_expression_diff(self) -> None:
-        source, _ = read_data("expression.py")
-        expected, _ = read_data("expression.diff")
+        source, _ = read_data("simple_cases/expression.py")
+        expected, _ = read_data("simple_cases/expression.diff")
         tmp_file = Path(black.dump_to_file(source))
         diff_header = re.compile(
             rf"{re.escape(str(tmp_file))}\t\d\d\d\d-\d\d-\d\d "
@@ -281,8 +281,8 @@ def test_expression_diff(self) -> None:
             self.assertEqual(expected, actual, msg)
 
     def test_expression_diff_with_color(self) -> None:
-        source, _ = read_data("expression.py")
-        expected, _ = read_data("expression.diff")
+        source, _ = read_data("simple_cases/expression.py")
+        expected, _ = read_data("simple_cases/expression.diff")
         tmp_file = Path(black.dump_to_file(source))
         try:
             result = BlackRunner().invoke(
@@ -320,7 +320,7 @@ def test_string_quotes(self) -> None:
         black.assert_stable(source, not_normalized, mode=mode)
 
     def test_skip_magic_trailing_comma(self) -> None:
-        source, _ = read_data("expression.py")
+        source, _ = read_data("simple_cases/expression.py")
         expected, _ = read_data("expression_skip_magic_trailing_comma.diff")
         tmp_file = Path(black.dump_to_file(source))
         diff_header = re.compile(
@@ -755,7 +755,7 @@ def test_get_features_used(self) -> None:
         self.assertEqual(black.get_features_used(node), {Feature.NUMERIC_UNDERSCORES})
         node = black.lib2to3_parse("123456\n")
         self.assertEqual(black.get_features_used(node), set())
-        source, expected = read_data("function")
+        source, expected = read_data("simple_cases/function.py")
         node = black.lib2to3_parse(source)
         expected_features = {
             Feature.TRAILING_COMMA_IN_CALL,
@@ -765,7 +765,7 @@ def test_get_features_used(self) -> None:
         self.assertEqual(black.get_features_used(node), expected_features)
         node = black.lib2to3_parse(expected)
         self.assertEqual(black.get_features_used(node), expected_features)
-        source, expected = read_data("expression")
+        source, expected = read_data("simple_cases/expression.py")
         node = black.lib2to3_parse(source)
         self.assertEqual(black.get_features_used(node), set())
         node = black.lib2to3_parse(expected)
@@ -939,7 +939,7 @@ def test_check_diff_use_together(self) -> None:
             src1 = (THIS_DIR / "data" / "string_quotes.py").resolve()
             self.invokeBlack([str(src1), "--diff", "--check"], exit_code=1)
             # Files which will not be reformatted.
-            src2 = (THIS_DIR / "data" / "composition.py").resolve()
+            src2 = (THIS_DIR / "data" / "simple_cases" / "composition.py").resolve()
             self.invokeBlack([str(src2), "--diff", "--check"])
             # Multi file command.
             self.invokeBlack([str(src1), str(src2), "--diff", "--check"], exit_code=1)
@@ -1168,7 +1168,7 @@ def test_reformat_one_with_stdin_and_existing_path(self) -> None:
             report = MagicMock()
             # Even with an existing file, since we are forcing stdin, black
             # should output to stdout and not modify the file inplace
-            p = Path(str(THIS_DIR / "data/collections.py"))
+            p = THIS_DIR / "data" / "simple_cases" / "collections.py"
             # Make sure is_file actually returns True
             self.assertTrue(p.is_file())
             path = Path(f"__BLACK_STDIN_FILENAME__{p}")
diff --git a/tests/test_format.py b/tests/test_format.py
index 2f08d1f273d..003f5bbe188 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -12,56 +12,9 @@
     assert_format,
     dump_to_stderr,
     read_data,
+    all_data_cases,
 )
 
-SIMPLE_CASES: List[str] = [
-    "attribute_access_on_number_literals",
-    "beginning_backslash",
-    "bracketmatch",
-    "class_blank_parentheses",
-    "class_methods_new_line",
-    "collections",
-    "comments",
-    "comments2",
-    "comments3",
-    "comments4",
-    "comments5",
-    "comments6",
-    "comments_non_breaking_space",
-    "comment_after_escaped_newline",
-    "composition",
-    "composition_no_trailing_comma",
-    "docstring",
-    "empty_lines",
-    "expression",
-    "fmtonoff",
-    "fmtonoff2",
-    "fmtonoff3",
-    "fmtonoff4",
-    "fmtskip",
-    "fmtskip2",
-    "fmtskip3",
-    "fmtskip4",
-    "fmtskip5",
-    "fmtskip6",
-    "fmtskip7",
-    "fstring",
-    "function",
-    "function2",
-    "function_trailing_comma",
-    "import_spacing",
-    "power_op_spacing",
-    "remove_parens",
-    "slices",
-    "string_prefixes",
-    "torture",
-    "trailing_comma_optional_parens1",
-    "trailing_comma_optional_parens2",
-    "trailing_comma_optional_parens3",
-    "tricky_unicode_symbols",
-    "tupleassign",
-]
-
 PY310_CASES: List[str] = [
     "starred_for_target",
     "pattern_matching_simple",
@@ -147,7 +100,7 @@ def check_file(filename: str, mode: black.Mode, *, data: bool = True) -> None:
     assert_format(source, expected, mode, fast=False)
 
 
-@pytest.mark.parametrize("filename", SIMPLE_CASES)
+@pytest.mark.parametrize("filename", all_data_cases("simple_cases"))
 def test_simple_format(filename: str) -> None:
     check_file(filename, DEFAULT_MODE)
 
diff --git a/tests/util.py b/tests/util.py
index 8755111f7c5..1d76681dbea 100644
--- a/tests/util.py
+++ b/tests/util.py
@@ -90,12 +90,21 @@ def assertFormatEqual(self, expected: str, actual: str) -> None:
         _assert_format_equal(expected, actual)
 
 
+def all_data_cases(dir_name: str, data: bool = True) -> List[str]:
+    base_dir = DATA_DIR if data else PROJECT_ROOT
+    cases_dir = base_dir / dir_name
+    assert cases_dir.is_dir()
+    return [f"{dir_name}/{case_path.stem}" for case_path in cases_dir.iterdir()]
+
+
 def read_data(name: str, data: bool = True) -> Tuple[str, str]:
     """read_data('test_name') -> 'input', 'output'"""
     if not name.endswith((".py", ".pyi", ".out", ".diff")):
         name += ".py"
     base_dir = DATA_DIR if data else PROJECT_ROOT
-    return read_data_from_file(base_dir / name)
+    case_path = base_dir / name
+    assert case_path.is_file(), f"{case_path} is not a file."
+    return read_data_from_file(case_path)
 
 
 def read_data_from_file(file_name: Path) -> Tuple[str, str]:

From 5d5b7316db2f001e079ba980b0a72681caac4912 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 9 May 2022 22:08:56 -0400
Subject: [PATCH 0536/1034] Bump docker/setup-qemu-action from 1 to 2 (#3056)

Bumps [docker/setup-qemu-action](https://github.com/docker/setup-qemu-action) from 1 to 2.
- [Release notes](https://github.com/docker/setup-qemu-action/releases)
- [Commits](https://github.com/docker/setup-qemu-action/compare/v1...v2)

---
updated-dependencies:
- dependency-name: docker/setup-qemu-action
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/docker.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
index 0a4848faad8..6bd13ddb313 100644
--- a/.github/workflows/docker.yml
+++ b/.github/workflows/docker.yml
@@ -19,7 +19,7 @@ jobs:
         uses: actions/checkout@v3
 
       - name: Set up QEMU
-        uses: docker/setup-qemu-action@v1
+        uses: docker/setup-qemu-action@v2
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v1

From ba21a8569977d279f14251254d57d64d47979436 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 9 May 2022 22:11:29 -0400
Subject: [PATCH 0537/1034] Bump docker/build-push-action from 2 to 3 (#3057)

Bumps [docker/build-push-action](https://github.com/docker/build-push-action) from 2 to 3.
- [Release notes](https://github.com/docker/build-push-action/releases)
- [Commits](https://github.com/docker/build-push-action/compare/v2...v3)

---
updated-dependencies:
- dependency-name: docker/build-push-action
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/docker.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
index 6bd13ddb313..60a9b77f75d 100644
--- a/.github/workflows/docker.yml
+++ b/.github/workflows/docker.yml
@@ -36,7 +36,7 @@ jobs:
           latest_non_release)" >> $GITHUB_ENV
 
       - name: Build and push
-        uses: docker/build-push-action@v2
+        uses: docker/build-push-action@v3
         with:
           context: .
           platforms: linux/amd64,linux/arm64
@@ -45,7 +45,7 @@ jobs:
 
       - name: Build and push latest_release tag
         if: ${{ github.event_name == 'release' && github.event.action == 'published' }}
-        uses: docker/build-push-action@v2
+        uses: docker/build-push-action@v3
         with:
           context: .
           platforms: linux/amd64,linux/arm64

From 4af87d8a43e2fd17045234d646dc59bfc8d77af4 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 9 May 2022 22:13:12 -0400
Subject: [PATCH 0538/1034] Bump docker/login-action from 1 to 2 (#3059)

Bumps [docker/login-action](https://github.com/docker/login-action) from 1 to 2.
- [Release notes](https://github.com/docker/login-action/releases)
- [Commits](https://github.com/docker/login-action/compare/v1...v2)

---
updated-dependencies:
- dependency-name: docker/login-action
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/docker.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
index 60a9b77f75d..dfde069ee4a 100644
--- a/.github/workflows/docker.yml
+++ b/.github/workflows/docker.yml
@@ -25,7 +25,7 @@ jobs:
         uses: docker/setup-buildx-action@v1
 
       - name: Login to DockerHub
-        uses: docker/login-action@v1
+        uses: docker/login-action@v2
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}

From 7f033136ac5e0e5bf6cf322dd60b4a92050eedc4 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 9 May 2022 22:22:01 -0400
Subject: [PATCH 0539/1034] Bump docker/setup-buildx-action from 1 to 2 (#3058)

Bumps [docker/setup-buildx-action](https://github.com/docker/setup-buildx-action) from 1 to 2.
- [Release notes](https://github.com/docker/setup-buildx-action/releases)
- [Commits](https://github.com/docker/setup-buildx-action/compare/v1...v2)

---
updated-dependencies:
- dependency-name: docker/setup-buildx-action
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/docker.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
index dfde069ee4a..a3106d04aae 100644
--- a/.github/workflows/docker.yml
+++ b/.github/workflows/docker.yml
@@ -22,7 +22,7 @@ jobs:
         uses: docker/setup-qemu-action@v2
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v1
+        uses: docker/setup-buildx-action@v2
 
       - name: Login to DockerHub
         uses: docker/login-action@v2

From 2893c42176903c8b6c28c46ff9e046861328b6a8 Mon Sep 17 00:00:00 2001
From: Sagi Shadur <saroad2@gmail.com>
Date: Wed, 18 May 2022 22:11:37 +0300
Subject: [PATCH 0540/1034] Remove hard coded test cases (#3062)

---
 .../pep_572_do_not_remove_parens.py           |   0
 .../{ => jupyter}/non_python_notebook.ipynb   |   0
 .../notebook_empty_metadata.ipynb             |   0
 .../notebook_no_trailing_newline.ipynb        |   0
 .../notebook_trailing_newline.ipynb           |   0
 .../notebook_which_cant_be_parsed.ipynb       |   0
 .../notebook_without_changes.ipynb            |   0
 .../async_as_identifier.py                    |   0
 .../data/{ => miscellaneous}/blackd_diff.diff |   0
 tests/data/{ => miscellaneous}/blackd_diff.py |   0
 .../{ => miscellaneous}/debug_visitor.out     |   0
 .../data/{ => miscellaneous}/debug_visitor.py |   0
 tests/data/{ => miscellaneous}/decorators.py  |   0
 .../docstring_no_string_normalization.py      |   0
 .../expression_skip_magic_trailing_comma.diff |   0
 tests/data/{ => miscellaneous}/force_py36.py  |   0
 tests/data/{ => miscellaneous}/force_pyi.py   |   0
 .../long_strings_flag_disabled.py             |   0
 .../missing_final_newline.diff                |   0
 .../missing_final_newline.py                  |   0
 .../pattern_matching_invalid.py               |   0
 .../{ => miscellaneous}/power_op_newline.py   |   0
 .../{ => miscellaneous}/python2_detection.py  |   0
 .../data/{ => miscellaneous}/string_quotes.py |   0
 tests/data/{ => miscellaneous}/stub.pyi       |   0
 tests/data/{ => preview}/cantfit.py           |   0
 tests/data/{ => preview}/comments7.py         |   0
 tests/data/{ => preview}/comments8.py         |   0
 tests/data/{ => preview}/docstring_preview.py |   0
 tests/data/{ => preview}/long_strings.py      |   0
 .../{ => preview}/long_strings__edge_case.py  |   0
 .../{ => preview}/long_strings__regression.py |   0
 .../{ => preview}/one_element_subscript.py    |   0
 .../data/{ => preview}/percent_precedence.py  |   0
 .../data/{ => preview}/remove_await_parens.py |   0
 .../{ => preview}/remove_except_parens.py     |   0
 .../data/{ => preview}/remove_for_brackets.py |   0
 .../return_annotation_brackets.py             |   0
 .../{ => preview_39}/remove_with_brackets.py  |   0
 .../parenthesized_context_managers.py         |   0
 .../{ => py_310}/pattern_matching_complex.py  |   0
 .../{ => py_310}/pattern_matching_extras.py   |   0
 .../{ => py_310}/pattern_matching_generic.py  |   0
 .../{ => py_310}/pattern_matching_simple.py   |   0
 .../{ => py_310}/pattern_matching_style.py    |   0
 tests/data/{ => py_310}/pep_572_py310.py      |   0
 tests/data/{ => py_310}/starred_for_target.py |   0
 tests/data/{ => py_311}/pep_654.py            |   0
 tests/data/{ => py_311}/pep_654_style.py      |   0
 tests/data/{ => py_36}/numeric_literals.py    |   0
 .../numeric_literals_skip_underscores.py      |   0
 tests/data/{ => py_37}/python37.py            |   0
 tests/data/{ => py_38}/pep_570.py             |   0
 tests/data/{ => py_38}/pep_572.py             |   0
 .../data/{ => py_38}/pep_572_remove_parens.py |   0
 tests/data/{ => py_38}/python38.py            |   0
 tests/data/{ => py_39}/pep_572_py39.py        |   0
 tests/data/{ => py_39}/python39.py            |   0
 tests/test_black.py                           |  72 ++++----
 tests/test_blackd.py                          |   6 +-
 tests/test_format.py                          | 156 ++++++------------
 tests/test_ipynb.py                           |  37 ++---
 tests/test_no_ipynb.py                        |   7 +-
 tests/util.py                                 |  46 ++++--
 64 files changed, 146 insertions(+), 178 deletions(-)
 rename tests/data/{ => fast}/pep_572_do_not_remove_parens.py (100%)
 rename tests/data/{ => jupyter}/non_python_notebook.ipynb (100%)
 rename tests/data/{ => jupyter}/notebook_empty_metadata.ipynb (100%)
 rename tests/data/{ => jupyter}/notebook_no_trailing_newline.ipynb (100%)
 rename tests/data/{ => jupyter}/notebook_trailing_newline.ipynb (100%)
 rename tests/data/{ => jupyter}/notebook_which_cant_be_parsed.ipynb (100%)
 rename tests/data/{ => jupyter}/notebook_without_changes.ipynb (100%)
 rename tests/data/{ => miscellaneous}/async_as_identifier.py (100%)
 rename tests/data/{ => miscellaneous}/blackd_diff.diff (100%)
 rename tests/data/{ => miscellaneous}/blackd_diff.py (100%)
 rename tests/data/{ => miscellaneous}/debug_visitor.out (100%)
 rename tests/data/{ => miscellaneous}/debug_visitor.py (100%)
 rename tests/data/{ => miscellaneous}/decorators.py (100%)
 rename tests/data/{ => miscellaneous}/docstring_no_string_normalization.py (100%)
 rename tests/data/{ => miscellaneous}/expression_skip_magic_trailing_comma.diff (100%)
 rename tests/data/{ => miscellaneous}/force_py36.py (100%)
 rename tests/data/{ => miscellaneous}/force_pyi.py (100%)
 rename tests/data/{ => miscellaneous}/long_strings_flag_disabled.py (100%)
 rename tests/data/{ => miscellaneous}/missing_final_newline.diff (100%)
 rename tests/data/{ => miscellaneous}/missing_final_newline.py (100%)
 rename tests/data/{ => miscellaneous}/pattern_matching_invalid.py (100%)
 rename tests/data/{ => miscellaneous}/power_op_newline.py (100%)
 rename tests/data/{ => miscellaneous}/python2_detection.py (100%)
 rename tests/data/{ => miscellaneous}/string_quotes.py (100%)
 rename tests/data/{ => miscellaneous}/stub.pyi (100%)
 rename tests/data/{ => preview}/cantfit.py (100%)
 rename tests/data/{ => preview}/comments7.py (100%)
 rename tests/data/{ => preview}/comments8.py (100%)
 rename tests/data/{ => preview}/docstring_preview.py (100%)
 rename tests/data/{ => preview}/long_strings.py (100%)
 rename tests/data/{ => preview}/long_strings__edge_case.py (100%)
 rename tests/data/{ => preview}/long_strings__regression.py (100%)
 rename tests/data/{ => preview}/one_element_subscript.py (100%)
 rename tests/data/{ => preview}/percent_precedence.py (100%)
 rename tests/data/{ => preview}/remove_await_parens.py (100%)
 rename tests/data/{ => preview}/remove_except_parens.py (100%)
 rename tests/data/{ => preview}/remove_for_brackets.py (100%)
 rename tests/data/{ => preview}/return_annotation_brackets.py (100%)
 rename tests/data/{ => preview_39}/remove_with_brackets.py (100%)
 rename tests/data/{ => py_310}/parenthesized_context_managers.py (100%)
 rename tests/data/{ => py_310}/pattern_matching_complex.py (100%)
 rename tests/data/{ => py_310}/pattern_matching_extras.py (100%)
 rename tests/data/{ => py_310}/pattern_matching_generic.py (100%)
 rename tests/data/{ => py_310}/pattern_matching_simple.py (100%)
 rename tests/data/{ => py_310}/pattern_matching_style.py (100%)
 rename tests/data/{ => py_310}/pep_572_py310.py (100%)
 rename tests/data/{ => py_310}/starred_for_target.py (100%)
 rename tests/data/{ => py_311}/pep_654.py (100%)
 rename tests/data/{ => py_311}/pep_654_style.py (100%)
 rename tests/data/{ => py_36}/numeric_literals.py (100%)
 rename tests/data/{ => py_36}/numeric_literals_skip_underscores.py (100%)
 rename tests/data/{ => py_37}/python37.py (100%)
 rename tests/data/{ => py_38}/pep_570.py (100%)
 rename tests/data/{ => py_38}/pep_572.py (100%)
 rename tests/data/{ => py_38}/pep_572_remove_parens.py (100%)
 rename tests/data/{ => py_38}/python38.py (100%)
 rename tests/data/{ => py_39}/pep_572_py39.py (100%)
 rename tests/data/{ => py_39}/python39.py (100%)

diff --git a/tests/data/pep_572_do_not_remove_parens.py b/tests/data/fast/pep_572_do_not_remove_parens.py
similarity index 100%
rename from tests/data/pep_572_do_not_remove_parens.py
rename to tests/data/fast/pep_572_do_not_remove_parens.py
diff --git a/tests/data/non_python_notebook.ipynb b/tests/data/jupyter/non_python_notebook.ipynb
similarity index 100%
rename from tests/data/non_python_notebook.ipynb
rename to tests/data/jupyter/non_python_notebook.ipynb
diff --git a/tests/data/notebook_empty_metadata.ipynb b/tests/data/jupyter/notebook_empty_metadata.ipynb
similarity index 100%
rename from tests/data/notebook_empty_metadata.ipynb
rename to tests/data/jupyter/notebook_empty_metadata.ipynb
diff --git a/tests/data/notebook_no_trailing_newline.ipynb b/tests/data/jupyter/notebook_no_trailing_newline.ipynb
similarity index 100%
rename from tests/data/notebook_no_trailing_newline.ipynb
rename to tests/data/jupyter/notebook_no_trailing_newline.ipynb
diff --git a/tests/data/notebook_trailing_newline.ipynb b/tests/data/jupyter/notebook_trailing_newline.ipynb
similarity index 100%
rename from tests/data/notebook_trailing_newline.ipynb
rename to tests/data/jupyter/notebook_trailing_newline.ipynb
diff --git a/tests/data/notebook_which_cant_be_parsed.ipynb b/tests/data/jupyter/notebook_which_cant_be_parsed.ipynb
similarity index 100%
rename from tests/data/notebook_which_cant_be_parsed.ipynb
rename to tests/data/jupyter/notebook_which_cant_be_parsed.ipynb
diff --git a/tests/data/notebook_without_changes.ipynb b/tests/data/jupyter/notebook_without_changes.ipynb
similarity index 100%
rename from tests/data/notebook_without_changes.ipynb
rename to tests/data/jupyter/notebook_without_changes.ipynb
diff --git a/tests/data/async_as_identifier.py b/tests/data/miscellaneous/async_as_identifier.py
similarity index 100%
rename from tests/data/async_as_identifier.py
rename to tests/data/miscellaneous/async_as_identifier.py
diff --git a/tests/data/blackd_diff.diff b/tests/data/miscellaneous/blackd_diff.diff
similarity index 100%
rename from tests/data/blackd_diff.diff
rename to tests/data/miscellaneous/blackd_diff.diff
diff --git a/tests/data/blackd_diff.py b/tests/data/miscellaneous/blackd_diff.py
similarity index 100%
rename from tests/data/blackd_diff.py
rename to tests/data/miscellaneous/blackd_diff.py
diff --git a/tests/data/debug_visitor.out b/tests/data/miscellaneous/debug_visitor.out
similarity index 100%
rename from tests/data/debug_visitor.out
rename to tests/data/miscellaneous/debug_visitor.out
diff --git a/tests/data/debug_visitor.py b/tests/data/miscellaneous/debug_visitor.py
similarity index 100%
rename from tests/data/debug_visitor.py
rename to tests/data/miscellaneous/debug_visitor.py
diff --git a/tests/data/decorators.py b/tests/data/miscellaneous/decorators.py
similarity index 100%
rename from tests/data/decorators.py
rename to tests/data/miscellaneous/decorators.py
diff --git a/tests/data/docstring_no_string_normalization.py b/tests/data/miscellaneous/docstring_no_string_normalization.py
similarity index 100%
rename from tests/data/docstring_no_string_normalization.py
rename to tests/data/miscellaneous/docstring_no_string_normalization.py
diff --git a/tests/data/expression_skip_magic_trailing_comma.diff b/tests/data/miscellaneous/expression_skip_magic_trailing_comma.diff
similarity index 100%
rename from tests/data/expression_skip_magic_trailing_comma.diff
rename to tests/data/miscellaneous/expression_skip_magic_trailing_comma.diff
diff --git a/tests/data/force_py36.py b/tests/data/miscellaneous/force_py36.py
similarity index 100%
rename from tests/data/force_py36.py
rename to tests/data/miscellaneous/force_py36.py
diff --git a/tests/data/force_pyi.py b/tests/data/miscellaneous/force_pyi.py
similarity index 100%
rename from tests/data/force_pyi.py
rename to tests/data/miscellaneous/force_pyi.py
diff --git a/tests/data/long_strings_flag_disabled.py b/tests/data/miscellaneous/long_strings_flag_disabled.py
similarity index 100%
rename from tests/data/long_strings_flag_disabled.py
rename to tests/data/miscellaneous/long_strings_flag_disabled.py
diff --git a/tests/data/missing_final_newline.diff b/tests/data/miscellaneous/missing_final_newline.diff
similarity index 100%
rename from tests/data/missing_final_newline.diff
rename to tests/data/miscellaneous/missing_final_newline.diff
diff --git a/tests/data/missing_final_newline.py b/tests/data/miscellaneous/missing_final_newline.py
similarity index 100%
rename from tests/data/missing_final_newline.py
rename to tests/data/miscellaneous/missing_final_newline.py
diff --git a/tests/data/pattern_matching_invalid.py b/tests/data/miscellaneous/pattern_matching_invalid.py
similarity index 100%
rename from tests/data/pattern_matching_invalid.py
rename to tests/data/miscellaneous/pattern_matching_invalid.py
diff --git a/tests/data/power_op_newline.py b/tests/data/miscellaneous/power_op_newline.py
similarity index 100%
rename from tests/data/power_op_newline.py
rename to tests/data/miscellaneous/power_op_newline.py
diff --git a/tests/data/python2_detection.py b/tests/data/miscellaneous/python2_detection.py
similarity index 100%
rename from tests/data/python2_detection.py
rename to tests/data/miscellaneous/python2_detection.py
diff --git a/tests/data/string_quotes.py b/tests/data/miscellaneous/string_quotes.py
similarity index 100%
rename from tests/data/string_quotes.py
rename to tests/data/miscellaneous/string_quotes.py
diff --git a/tests/data/stub.pyi b/tests/data/miscellaneous/stub.pyi
similarity index 100%
rename from tests/data/stub.pyi
rename to tests/data/miscellaneous/stub.pyi
diff --git a/tests/data/cantfit.py b/tests/data/preview/cantfit.py
similarity index 100%
rename from tests/data/cantfit.py
rename to tests/data/preview/cantfit.py
diff --git a/tests/data/comments7.py b/tests/data/preview/comments7.py
similarity index 100%
rename from tests/data/comments7.py
rename to tests/data/preview/comments7.py
diff --git a/tests/data/comments8.py b/tests/data/preview/comments8.py
similarity index 100%
rename from tests/data/comments8.py
rename to tests/data/preview/comments8.py
diff --git a/tests/data/docstring_preview.py b/tests/data/preview/docstring_preview.py
similarity index 100%
rename from tests/data/docstring_preview.py
rename to tests/data/preview/docstring_preview.py
diff --git a/tests/data/long_strings.py b/tests/data/preview/long_strings.py
similarity index 100%
rename from tests/data/long_strings.py
rename to tests/data/preview/long_strings.py
diff --git a/tests/data/long_strings__edge_case.py b/tests/data/preview/long_strings__edge_case.py
similarity index 100%
rename from tests/data/long_strings__edge_case.py
rename to tests/data/preview/long_strings__edge_case.py
diff --git a/tests/data/long_strings__regression.py b/tests/data/preview/long_strings__regression.py
similarity index 100%
rename from tests/data/long_strings__regression.py
rename to tests/data/preview/long_strings__regression.py
diff --git a/tests/data/one_element_subscript.py b/tests/data/preview/one_element_subscript.py
similarity index 100%
rename from tests/data/one_element_subscript.py
rename to tests/data/preview/one_element_subscript.py
diff --git a/tests/data/percent_precedence.py b/tests/data/preview/percent_precedence.py
similarity index 100%
rename from tests/data/percent_precedence.py
rename to tests/data/preview/percent_precedence.py
diff --git a/tests/data/remove_await_parens.py b/tests/data/preview/remove_await_parens.py
similarity index 100%
rename from tests/data/remove_await_parens.py
rename to tests/data/preview/remove_await_parens.py
diff --git a/tests/data/remove_except_parens.py b/tests/data/preview/remove_except_parens.py
similarity index 100%
rename from tests/data/remove_except_parens.py
rename to tests/data/preview/remove_except_parens.py
diff --git a/tests/data/remove_for_brackets.py b/tests/data/preview/remove_for_brackets.py
similarity index 100%
rename from tests/data/remove_for_brackets.py
rename to tests/data/preview/remove_for_brackets.py
diff --git a/tests/data/return_annotation_brackets.py b/tests/data/preview/return_annotation_brackets.py
similarity index 100%
rename from tests/data/return_annotation_brackets.py
rename to tests/data/preview/return_annotation_brackets.py
diff --git a/tests/data/remove_with_brackets.py b/tests/data/preview_39/remove_with_brackets.py
similarity index 100%
rename from tests/data/remove_with_brackets.py
rename to tests/data/preview_39/remove_with_brackets.py
diff --git a/tests/data/parenthesized_context_managers.py b/tests/data/py_310/parenthesized_context_managers.py
similarity index 100%
rename from tests/data/parenthesized_context_managers.py
rename to tests/data/py_310/parenthesized_context_managers.py
diff --git a/tests/data/pattern_matching_complex.py b/tests/data/py_310/pattern_matching_complex.py
similarity index 100%
rename from tests/data/pattern_matching_complex.py
rename to tests/data/py_310/pattern_matching_complex.py
diff --git a/tests/data/pattern_matching_extras.py b/tests/data/py_310/pattern_matching_extras.py
similarity index 100%
rename from tests/data/pattern_matching_extras.py
rename to tests/data/py_310/pattern_matching_extras.py
diff --git a/tests/data/pattern_matching_generic.py b/tests/data/py_310/pattern_matching_generic.py
similarity index 100%
rename from tests/data/pattern_matching_generic.py
rename to tests/data/py_310/pattern_matching_generic.py
diff --git a/tests/data/pattern_matching_simple.py b/tests/data/py_310/pattern_matching_simple.py
similarity index 100%
rename from tests/data/pattern_matching_simple.py
rename to tests/data/py_310/pattern_matching_simple.py
diff --git a/tests/data/pattern_matching_style.py b/tests/data/py_310/pattern_matching_style.py
similarity index 100%
rename from tests/data/pattern_matching_style.py
rename to tests/data/py_310/pattern_matching_style.py
diff --git a/tests/data/pep_572_py310.py b/tests/data/py_310/pep_572_py310.py
similarity index 100%
rename from tests/data/pep_572_py310.py
rename to tests/data/py_310/pep_572_py310.py
diff --git a/tests/data/starred_for_target.py b/tests/data/py_310/starred_for_target.py
similarity index 100%
rename from tests/data/starred_for_target.py
rename to tests/data/py_310/starred_for_target.py
diff --git a/tests/data/pep_654.py b/tests/data/py_311/pep_654.py
similarity index 100%
rename from tests/data/pep_654.py
rename to tests/data/py_311/pep_654.py
diff --git a/tests/data/pep_654_style.py b/tests/data/py_311/pep_654_style.py
similarity index 100%
rename from tests/data/pep_654_style.py
rename to tests/data/py_311/pep_654_style.py
diff --git a/tests/data/numeric_literals.py b/tests/data/py_36/numeric_literals.py
similarity index 100%
rename from tests/data/numeric_literals.py
rename to tests/data/py_36/numeric_literals.py
diff --git a/tests/data/numeric_literals_skip_underscores.py b/tests/data/py_36/numeric_literals_skip_underscores.py
similarity index 100%
rename from tests/data/numeric_literals_skip_underscores.py
rename to tests/data/py_36/numeric_literals_skip_underscores.py
diff --git a/tests/data/python37.py b/tests/data/py_37/python37.py
similarity index 100%
rename from tests/data/python37.py
rename to tests/data/py_37/python37.py
diff --git a/tests/data/pep_570.py b/tests/data/py_38/pep_570.py
similarity index 100%
rename from tests/data/pep_570.py
rename to tests/data/py_38/pep_570.py
diff --git a/tests/data/pep_572.py b/tests/data/py_38/pep_572.py
similarity index 100%
rename from tests/data/pep_572.py
rename to tests/data/py_38/pep_572.py
diff --git a/tests/data/pep_572_remove_parens.py b/tests/data/py_38/pep_572_remove_parens.py
similarity index 100%
rename from tests/data/pep_572_remove_parens.py
rename to tests/data/py_38/pep_572_remove_parens.py
diff --git a/tests/data/python38.py b/tests/data/py_38/python38.py
similarity index 100%
rename from tests/data/python38.py
rename to tests/data/py_38/python38.py
diff --git a/tests/data/pep_572_py39.py b/tests/data/py_39/pep_572_py39.py
similarity index 100%
rename from tests/data/pep_572_py39.py
rename to tests/data/py_39/pep_572_py39.py
diff --git a/tests/data/python39.py b/tests/data/py_39/python39.py
similarity index 100%
rename from tests/data/python39.py
rename to tests/data/py_39/python39.py
diff --git a/tests/test_black.py b/tests/test_black.py
index 281019a0bfa..a633e678dd7 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -60,6 +60,8 @@
     ff,
     fs,
     read_data,
+    get_case_path,
+    read_data_from_file,
 )
 
 THIS_FILE = Path(__file__)
@@ -157,7 +159,7 @@ def test_experimental_string_processing_warns(self) -> None:
         )
 
     def test_piping(self) -> None:
-        source, expected = read_data("src/black/__init__", data=False)
+        source, expected = read_data_from_file(PROJECT_ROOT / "src/black/__init__.py")
         result = BlackRunner().invoke(
             black.main,
             [
@@ -179,8 +181,8 @@ def test_piping_diff(self) -> None:
             r"(STDIN|STDOUT)\t\d\d\d\d-\d\d-\d\d \d\d:\d\d:\d\d\.\d\d\d\d\d\d "
             r"\+\d\d\d\d"
         )
-        source, _ = read_data("simple_cases/expression.py")
-        expected, _ = read_data("simple_cases/expression.diff")
+        source, _ = read_data("simple_cases", "expression.py")
+        expected, _ = read_data("simple_cases", "expression.diff")
         args = [
             "-",
             "--fast",
@@ -197,7 +199,7 @@ def test_piping_diff(self) -> None:
         self.assertEqual(expected, actual)
 
     def test_piping_diff_with_color(self) -> None:
-        source, _ = read_data("simple_cases/expression.py")
+        source, _ = read_data("simple_cases", "expression.py")
         args = [
             "-",
             "--fast",
@@ -219,7 +221,7 @@ def test_piping_diff_with_color(self) -> None:
 
     @patch("black.dump_to_file", dump_to_stderr)
     def _test_wip(self) -> None:
-        source, expected = read_data("wip")
+        source, expected = read_data("miscellaneous", "wip")
         sys.settrace(tracefunc)
         mode = replace(
             DEFAULT_MODE,
@@ -233,7 +235,7 @@ def _test_wip(self) -> None:
         black.assert_stable(source, actual, black.FileMode())
 
     def test_pep_572_version_detection(self) -> None:
-        source, _ = read_data("pep_572")
+        source, _ = read_data("py_38", "pep_572")
         root = black.lib2to3_parse(source)
         features = black.get_features_used(root)
         self.assertIn(black.Feature.ASSIGNMENT_EXPRESSIONS, features)
@@ -241,7 +243,7 @@ def test_pep_572_version_detection(self) -> None:
         self.assertIn(black.TargetVersion.PY38, versions)
 
     def test_expression_ff(self) -> None:
-        source, expected = read_data("simple_cases/expression.py")
+        source, expected = read_data("simple_cases", "expression.py")
         tmp_file = Path(black.dump_to_file(source))
         try:
             self.assertTrue(ff(tmp_file, write_back=black.WriteBack.YES))
@@ -255,8 +257,8 @@ def test_expression_ff(self) -> None:
             black.assert_stable(source, actual, DEFAULT_MODE)
 
     def test_expression_diff(self) -> None:
-        source, _ = read_data("simple_cases/expression.py")
-        expected, _ = read_data("simple_cases/expression.diff")
+        source, _ = read_data("simple_cases", "expression.py")
+        expected, _ = read_data("simple_cases", "expression.diff")
         tmp_file = Path(black.dump_to_file(source))
         diff_header = re.compile(
             rf"{re.escape(str(tmp_file))}\t\d\d\d\d-\d\d-\d\d "
@@ -281,8 +283,8 @@ def test_expression_diff(self) -> None:
             self.assertEqual(expected, actual, msg)
 
     def test_expression_diff_with_color(self) -> None:
-        source, _ = read_data("simple_cases/expression.py")
-        expected, _ = read_data("simple_cases/expression.diff")
+        source, _ = read_data("simple_cases", "expression.py")
+        expected, _ = read_data("simple_cases", "expression.diff")
         tmp_file = Path(black.dump_to_file(source))
         try:
             result = BlackRunner().invoke(
@@ -301,7 +303,7 @@ def test_expression_diff_with_color(self) -> None:
         self.assertIn("\033[0m", actual)
 
     def test_detect_pos_only_arguments(self) -> None:
-        source, _ = read_data("pep_570")
+        source, _ = read_data("py_38", "pep_570")
         root = black.lib2to3_parse(source)
         features = black.get_features_used(root)
         self.assertIn(black.Feature.POS_ONLY_ARGUMENTS, features)
@@ -310,7 +312,7 @@ def test_detect_pos_only_arguments(self) -> None:
 
     @patch("black.dump_to_file", dump_to_stderr)
     def test_string_quotes(self) -> None:
-        source, expected = read_data("string_quotes")
+        source, expected = read_data("miscellaneous", "string_quotes")
         mode = black.Mode(preview=True)
         assert_format(source, expected, mode)
         mode = replace(mode, string_normalization=False)
@@ -320,8 +322,10 @@ def test_string_quotes(self) -> None:
         black.assert_stable(source, not_normalized, mode=mode)
 
     def test_skip_magic_trailing_comma(self) -> None:
-        source, _ = read_data("simple_cases/expression.py")
-        expected, _ = read_data("expression_skip_magic_trailing_comma.diff")
+        source, _ = read_data("simple_cases", "expression")
+        expected, _ = read_data(
+            "miscellaneous", "expression_skip_magic_trailing_comma.diff"
+        )
         tmp_file = Path(black.dump_to_file(source))
         diff_header = re.compile(
             rf"{re.escape(str(tmp_file))}\t\d\d\d\d-\d\d-\d\d "
@@ -348,8 +352,8 @@ def test_skip_magic_trailing_comma(self) -> None:
 
     @patch("black.dump_to_file", dump_to_stderr)
     def test_async_as_identifier(self) -> None:
-        source_path = (THIS_DIR / "data" / "async_as_identifier.py").resolve()
-        source, expected = read_data("async_as_identifier")
+        source_path = get_case_path("miscellaneous", "async_as_identifier")
+        source, expected = read_data_from_file(source_path)
         actual = fs(source)
         self.assertFormatEqual(expected, actual)
         major, minor = sys.version_info[:2]
@@ -363,8 +367,8 @@ def test_async_as_identifier(self) -> None:
 
     @patch("black.dump_to_file", dump_to_stderr)
     def test_python37(self) -> None:
-        source_path = (THIS_DIR / "data" / "python37.py").resolve()
-        source, expected = read_data("python37")
+        source_path = get_case_path("py_37", "python37")
+        source, expected = read_data_from_file(source_path)
         actual = fs(source)
         self.assertFormatEqual(expected, actual)
         major, minor = sys.version_info[:2]
@@ -712,7 +716,7 @@ def test_get_features_used_decorator(self) -> None:
         # since this makes some test cases of test_get_features_used()
         # fails if it fails, this is tested first so that a useful case
         # is identified
-        simples, relaxed = read_data("decorators")
+        simples, relaxed = read_data("miscellaneous", "decorators")
         # skip explanation comments at the top of the file
         for simple_test in simples.split("##")[1:]:
             node = black.lib2to3_parse(simple_test)
@@ -755,7 +759,7 @@ def test_get_features_used(self) -> None:
         self.assertEqual(black.get_features_used(node), {Feature.NUMERIC_UNDERSCORES})
         node = black.lib2to3_parse("123456\n")
         self.assertEqual(black.get_features_used(node), set())
-        source, expected = read_data("simple_cases/function.py")
+        source, expected = read_data("simple_cases", "function")
         node = black.lib2to3_parse(source)
         expected_features = {
             Feature.TRAILING_COMMA_IN_CALL,
@@ -765,7 +769,7 @@ def test_get_features_used(self) -> None:
         self.assertEqual(black.get_features_used(node), expected_features)
         node = black.lib2to3_parse(expected)
         self.assertEqual(black.get_features_used(node), expected_features)
-        source, expected = read_data("simple_cases/expression.py")
+        source, expected = read_data("simple_cases", "expression")
         node = black.lib2to3_parse(source)
         self.assertEqual(black.get_features_used(node), set())
         node = black.lib2to3_parse(expected)
@@ -851,8 +855,8 @@ def test_get_future_imports(self) -> None:
 
     @pytest.mark.incompatible_with_mypyc
     def test_debug_visitor(self) -> None:
-        source, _ = read_data("debug_visitor.py")
-        expected, _ = read_data("debug_visitor.out")
+        source, _ = read_data("miscellaneous", "debug_visitor")
+        expected, _ = read_data("miscellaneous", "debug_visitor.out")
         out_lines = []
         err_lines = []
 
@@ -936,10 +940,10 @@ def test_works_in_mono_process_only_environment(self) -> None:
     def test_check_diff_use_together(self) -> None:
         with cache_dir():
             # Files which will be reformatted.
-            src1 = (THIS_DIR / "data" / "string_quotes.py").resolve()
+            src1 = get_case_path("miscellaneous", "string_quotes")
             self.invokeBlack([str(src1), "--diff", "--check"], exit_code=1)
             # Files which will not be reformatted.
-            src2 = (THIS_DIR / "data" / "simple_cases" / "composition.py").resolve()
+            src2 = get_case_path("simple_cases", "composition")
             self.invokeBlack([str(src2), "--diff", "--check"])
             # Multi file command.
             self.invokeBlack([str(src1), str(src2), "--diff", "--check"], exit_code=1)
@@ -963,7 +967,7 @@ def test_broken_symlink(self) -> None:
 
     def test_single_file_force_pyi(self) -> None:
         pyi_mode = replace(DEFAULT_MODE, is_pyi=True)
-        contents, expected = read_data("force_pyi")
+        contents, expected = read_data("miscellaneous", "force_pyi")
         with cache_dir() as workspace:
             path = (workspace / "file.py").resolve()
             with open(path, "w") as fh:
@@ -984,7 +988,7 @@ def test_single_file_force_pyi(self) -> None:
     def test_multi_file_force_pyi(self) -> None:
         reg_mode = DEFAULT_MODE
         pyi_mode = replace(DEFAULT_MODE, is_pyi=True)
-        contents, expected = read_data("force_pyi")
+        contents, expected = read_data("miscellaneous", "force_pyi")
         with cache_dir() as workspace:
             paths = [
                 (workspace / "file1.py").resolve(),
@@ -1006,7 +1010,7 @@ def test_multi_file_force_pyi(self) -> None:
                 self.assertNotIn(str(path), normal_cache)
 
     def test_pipe_force_pyi(self) -> None:
-        source, expected = read_data("force_pyi")
+        source, expected = read_data("miscellaneous", "force_pyi")
         result = CliRunner().invoke(
             black.main, ["-", "-q", "--pyi"], input=BytesIO(source.encode("utf8"))
         )
@@ -1017,7 +1021,7 @@ def test_pipe_force_pyi(self) -> None:
     def test_single_file_force_py36(self) -> None:
         reg_mode = DEFAULT_MODE
         py36_mode = replace(DEFAULT_MODE, target_versions=PY36_VERSIONS)
-        source, expected = read_data("force_py36")
+        source, expected = read_data("miscellaneous", "force_py36")
         with cache_dir() as workspace:
             path = (workspace / "file.py").resolve()
             with open(path, "w") as fh:
@@ -1036,7 +1040,7 @@ def test_single_file_force_py36(self) -> None:
     def test_multi_file_force_py36(self) -> None:
         reg_mode = DEFAULT_MODE
         py36_mode = replace(DEFAULT_MODE, target_versions=PY36_VERSIONS)
-        source, expected = read_data("force_py36")
+        source, expected = read_data("miscellaneous", "force_py36")
         with cache_dir() as workspace:
             paths = [
                 (workspace / "file1.py").resolve(),
@@ -1058,7 +1062,7 @@ def test_multi_file_force_py36(self) -> None:
                 self.assertNotIn(str(path), normal_cache)
 
     def test_pipe_force_py36(self) -> None:
-        source, expected = read_data("force_py36")
+        source, expected = read_data("miscellaneous", "force_py36")
         result = CliRunner().invoke(
             black.main,
             ["-", "-q", "--target-version=py36"],
@@ -1454,10 +1458,10 @@ def test_bpo_2142_workaround(self) -> None:
 
         # https://bugs.python.org/issue2142
 
-        source, _ = read_data("missing_final_newline.py")
+        source, _ = read_data("miscellaneous", "missing_final_newline")
         # read_data adds a trailing newline
         source = source.rstrip()
-        expected, _ = read_data("missing_final_newline.diff")
+        expected, _ = read_data("miscellaneous", "missing_final_newline.diff")
         tmp_file = Path(black.dump_to_file(source, ensure_final_newline=False))
         diff_header = re.compile(
             rf"{re.escape(str(tmp_file))}\t\d\d\d\d-\d\d-\d\d "
diff --git a/tests/test_blackd.py b/tests/test_blackd.py
index 6174c4538b9..75d756705be 100644
--- a/tests/test_blackd.py
+++ b/tests/test_blackd.py
@@ -95,7 +95,7 @@ async def check(header_value: str, expected_status: int = 400) -> None:
 
     @unittest_run_loop
     async def test_blackd_pyi(self) -> None:
-        source, expected = read_data("stub.pyi")
+        source, expected = read_data("miscellaneous", "stub.pyi")
         response = await self.client.post(
             "/", data=source, headers={blackd.PYTHON_VARIANT_HEADER: "pyi"}
         )
@@ -108,8 +108,8 @@ async def test_blackd_diff(self) -> None:
             r"(In|Out)\t\d\d\d\d-\d\d-\d\d \d\d:\d\d:\d\d\.\d\d\d\d\d\d \+\d\d\d\d"
         )
 
-        source, _ = read_data("blackd_diff.py")
-        expected, _ = read_data("blackd_diff.diff")
+        source, _ = read_data("miscellaneous", "blackd_diff")
+        expected, _ = read_data("miscellaneous", "blackd_diff.diff")
 
         response = await self.client.post(
             "/", data=source, headers={blackd.DIFF_HEADER: "true"}
diff --git a/tests/test_format.py b/tests/test_format.py
index 003f5bbe188..005a5771c2b 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -8,45 +8,12 @@
 from tests.util import (
     DEFAULT_MODE,
     PY36_VERSIONS,
-    THIS_DIR,
     assert_format,
     dump_to_stderr,
     read_data,
     all_data_cases,
 )
 
-PY310_CASES: List[str] = [
-    "starred_for_target",
-    "pattern_matching_simple",
-    "pattern_matching_complex",
-    "pattern_matching_extras",
-    "pattern_matching_style",
-    "pattern_matching_generic",
-    "parenthesized_context_managers",
-]
-
-PY311_CASES: List[str] = [
-    "pep_654",
-    "pep_654_style",
-]
-
-PREVIEW_CASES: List[str] = [
-    # string processing
-    "cantfit",
-    "comments7",
-    "comments8",
-    "long_strings",
-    "long_strings__edge_case",
-    "long_strings__regression",
-    "percent_precedence",
-    "remove_except_parens",
-    "remove_for_brackets",
-    "one_element_subscript",
-    "remove_await_parens",
-    "return_annotation_brackets",
-    "docstring_preview",
-]
-
 SOURCES: List[str] = [
     "src/black/__init__.py",
     "src/black/__main__.py",
@@ -95,25 +62,33 @@ def patch_dump_to_file(request: Any) -> Iterator[None]:
         yield
 
 
-def check_file(filename: str, mode: black.Mode, *, data: bool = True) -> None:
-    source, expected = read_data(filename, data=data)
+def check_file(
+    subdir: str, filename: str, mode: black.Mode, *, data: bool = True
+) -> None:
+    source, expected = read_data(subdir, filename, data=data)
     assert_format(source, expected, mode, fast=False)
 
 
 @pytest.mark.parametrize("filename", all_data_cases("simple_cases"))
 def test_simple_format(filename: str) -> None:
-    check_file(filename, DEFAULT_MODE)
+    check_file("simple_cases", filename, DEFAULT_MODE)
 
 
-@pytest.mark.parametrize("filename", PREVIEW_CASES)
+@pytest.mark.parametrize("filename", all_data_cases("preview"))
 def test_preview_format(filename: str) -> None:
-    check_file(filename, black.Mode(preview=True))
+    check_file("preview", filename, black.Mode(preview=True))
+
+
+@pytest.mark.parametrize("filename", all_data_cases("preview_39"))
+def test_preview_minimum_python_39_format(filename: str) -> None:
+    source, expected = read_data("preview_39", filename)
+    mode = black.Mode(preview=True)
+    assert_format(source, expected, mode, minimum_version=(3, 9))
 
 
 @pytest.mark.parametrize("filename", SOURCES)
 def test_source_is_formatted(filename: str) -> None:
-    path = THIS_DIR.parent / filename
-    check_file(str(path), DEFAULT_MODE, data=False)
+    check_file("", filename, DEFAULT_MODE, data=False)
 
 
 # =============== #
@@ -126,59 +101,50 @@ def test_empty() -> None:
     assert_format(source, expected)
 
 
-def test_pep_572() -> None:
-    source, expected = read_data("pep_572")
-    assert_format(source, expected, minimum_version=(3, 8))
-
-
-def test_pep_572_remove_parens() -> None:
-    source, expected = read_data("pep_572_remove_parens")
-    assert_format(source, expected, minimum_version=(3, 8))
-
-
-def test_pep_572_do_not_remove_parens() -> None:
-    source, expected = read_data("pep_572_do_not_remove_parens")
-    # the AST safety checks will fail, but that's expected, just make sure no
-    # parentheses are touched
-    assert_format(source, expected, fast=True)
+@pytest.mark.parametrize("filename", all_data_cases("py_36"))
+def test_python_36(filename: str) -> None:
+    source, expected = read_data("py_36", filename)
+    mode = black.Mode(target_versions=PY36_VERSIONS)
+    assert_format(source, expected, mode, minimum_version=(3, 6))
 
 
-@pytest.mark.parametrize("major, minor", [(3, 9), (3, 10)])
-def test_pep_572_newer_syntax(major: int, minor: int) -> None:
-    source, expected = read_data(f"pep_572_py{major}{minor}")
-    assert_format(source, expected, minimum_version=(major, minor))
+@pytest.mark.parametrize("filename", all_data_cases("py_37"))
+def test_python_37(filename: str) -> None:
+    source, expected = read_data("py_37", filename)
+    mode = black.Mode(target_versions={black.TargetVersion.PY37})
+    assert_format(source, expected, mode, minimum_version=(3, 7))
 
 
-def test_pep_570() -> None:
-    source, expected = read_data("pep_570")
-    assert_format(source, expected, minimum_version=(3, 8))
+@pytest.mark.parametrize("filename", all_data_cases("py_38"))
+def test_python_38(filename: str) -> None:
+    source, expected = read_data("py_38", filename)
+    mode = black.Mode(target_versions={black.TargetVersion.PY38})
+    assert_format(source, expected, mode, minimum_version=(3, 8))
 
 
-def test_remove_with_brackets() -> None:
-    source, expected = read_data("remove_with_brackets")
-    assert_format(
-        source,
-        expected,
-        black.Mode(preview=True),
-        minimum_version=(3, 9),
-    )
+@pytest.mark.parametrize("filename", all_data_cases("py_39"))
+def test_python_39(filename: str) -> None:
+    source, expected = read_data("py_39", filename)
+    mode = black.Mode(target_versions={black.TargetVersion.PY39})
+    assert_format(source, expected, mode, minimum_version=(3, 9))
 
 
-@pytest.mark.parametrize("filename", PY310_CASES)
+@pytest.mark.parametrize("filename", all_data_cases("py_310"))
 def test_python_310(filename: str) -> None:
-    source, expected = read_data(filename)
+    source, expected = read_data("py_310", filename)
     mode = black.Mode(target_versions={black.TargetVersion.PY310})
     assert_format(source, expected, mode, minimum_version=(3, 10))
 
 
-def test_python_310_without_target_version() -> None:
-    source, expected = read_data("pattern_matching_simple")
+@pytest.mark.parametrize("filename", all_data_cases("py_310"))
+def test_python_310_without_target_version(filename: str) -> None:
+    source, expected = read_data("py_310", filename)
     mode = black.Mode()
     assert_format(source, expected, mode, minimum_version=(3, 10))
 
 
 def test_patma_invalid() -> None:
-    source, expected = read_data("pattern_matching_invalid")
+    source, expected = read_data("miscellaneous", "pattern_matching_invalid")
     mode = black.Mode(target_versions={black.TargetVersion.PY310})
     with pytest.raises(black.parsing.InvalidInput) as exc_info:
         assert_format(source, expected, mode, minimum_version=(3, 10))
@@ -186,13 +152,19 @@ def test_patma_invalid() -> None:
     exc_info.match("Cannot parse: 10:11")
 
 
-@pytest.mark.parametrize("filename", PY311_CASES)
+@pytest.mark.parametrize("filename", all_data_cases("py_311"))
 def test_python_311(filename: str) -> None:
-    source, expected = read_data(filename)
+    source, expected = read_data("py_311", filename)
     mode = black.Mode(target_versions={black.TargetVersion.PY311})
     assert_format(source, expected, mode, minimum_version=(3, 11))
 
 
+@pytest.mark.parametrize("filename", all_data_cases("fast"))
+def test_fast_cases(filename: str) -> None:
+    source, expected = read_data("fast", filename)
+    assert_format(source, expected, fast=True)
+
+
 def test_python_2_hint() -> None:
     with pytest.raises(black.parsing.InvalidInput) as exc_info:
         assert_format("print 'daylily'", "print 'daylily'")
@@ -201,47 +173,25 @@ def test_python_2_hint() -> None:
 
 def test_docstring_no_string_normalization() -> None:
     """Like test_docstring but with string normalization off."""
-    source, expected = read_data("docstring_no_string_normalization")
+    source, expected = read_data("miscellaneous", "docstring_no_string_normalization")
     mode = replace(DEFAULT_MODE, string_normalization=False)
     assert_format(source, expected, mode)
 
 
 def test_long_strings_flag_disabled() -> None:
     """Tests for turning off the string processing logic."""
-    source, expected = read_data("long_strings_flag_disabled")
+    source, expected = read_data("miscellaneous", "long_strings_flag_disabled")
     mode = replace(DEFAULT_MODE, experimental_string_processing=False)
     assert_format(source, expected, mode)
 
 
-def test_numeric_literals() -> None:
-    source, expected = read_data("numeric_literals")
-    mode = replace(DEFAULT_MODE, target_versions=PY36_VERSIONS)
-    assert_format(source, expected, mode)
-
-
-def test_numeric_literals_ignoring_underscores() -> None:
-    source, expected = read_data("numeric_literals_skip_underscores")
-    mode = replace(DEFAULT_MODE, target_versions=PY36_VERSIONS)
-    assert_format(source, expected, mode)
-
-
 def test_stub() -> None:
     mode = replace(DEFAULT_MODE, is_pyi=True)
-    source, expected = read_data("stub.pyi")
+    source, expected = read_data("miscellaneous", "stub.pyi")
     assert_format(source, expected, mode)
 
 
-def test_python38() -> None:
-    source, expected = read_data("python38")
-    assert_format(source, expected, minimum_version=(3, 8))
-
-
-def test_python39() -> None:
-    source, expected = read_data("python39")
-    assert_format(source, expected, minimum_version=(3, 9))
-
-
 def test_power_op_newline() -> None:
     # requires line_length=0
-    source, expected = read_data("power_op_newline")
+    source, expected = read_data("miscellaneous", "power_op_newline")
     assert_format(source, expected, mode=black.Mode(line_length=0))
diff --git a/tests/test_ipynb.py b/tests/test_ipynb.py
index 6f6b3090cd1..e1d7dd88dcb 100644
--- a/tests/test_ipynb.py
+++ b/tests/test_ipynb.py
@@ -17,7 +17,7 @@
 import pytest
 from black import Mode
 from _pytest.monkeypatch import MonkeyPatch
-from tests.util import DATA_DIR
+from tests.util import DATA_DIR, read_jupyter_notebook, get_case_path
 
 with contextlib.suppress(ModuleNotFoundError):
     import IPython
@@ -252,9 +252,7 @@ def test_empty_cell() -> None:
 
 
 def test_entire_notebook_empty_metadata() -> None:
-    with open(DATA_DIR / "notebook_empty_metadata.ipynb", "rb") as fd:
-        content_bytes = fd.read()
-    content = content_bytes.decode()
+    content = read_jupyter_notebook("jupyter", "notebook_empty_metadata")
     result = format_file_contents(content, fast=True, mode=JUPYTER_MODE)
     expected = (
         "{\n"
@@ -289,9 +287,7 @@ def test_entire_notebook_empty_metadata() -> None:
 
 
 def test_entire_notebook_trailing_newline() -> None:
-    with open(DATA_DIR / "notebook_trailing_newline.ipynb", "rb") as fd:
-        content_bytes = fd.read()
-    content = content_bytes.decode()
+    content = read_jupyter_notebook("jupyter", "notebook_trailing_newline")
     result = format_file_contents(content, fast=True, mode=JUPYTER_MODE)
     expected = (
         "{\n"
@@ -338,9 +334,7 @@ def test_entire_notebook_trailing_newline() -> None:
 
 
 def test_entire_notebook_no_trailing_newline() -> None:
-    with open(DATA_DIR / "notebook_no_trailing_newline.ipynb", "rb") as fd:
-        content_bytes = fd.read()
-    content = content_bytes.decode()
+    content = read_jupyter_notebook("jupyter", "notebook_no_trailing_newline")
     result = format_file_contents(content, fast=True, mode=JUPYTER_MODE)
     expected = (
         "{\n"
@@ -387,17 +381,14 @@ def test_entire_notebook_no_trailing_newline() -> None:
 
 
 def test_entire_notebook_without_changes() -> None:
-    with open(DATA_DIR / "notebook_without_changes.ipynb", "rb") as fd:
-        content_bytes = fd.read()
-    content = content_bytes.decode()
+    content = read_jupyter_notebook("jupyter", "notebook_without_changes")
     with pytest.raises(NothingChanged):
         format_file_contents(content, fast=True, mode=JUPYTER_MODE)
 
 
 def test_non_python_notebook() -> None:
-    with open(DATA_DIR / "non_python_notebook.ipynb", "rb") as fd:
-        content_bytes = fd.read()
-    content = content_bytes.decode()
+    content = read_jupyter_notebook("jupyter", "non_python_notebook")
+
     with pytest.raises(NothingChanged):
         format_file_contents(content, fast=True, mode=JUPYTER_MODE)
 
@@ -408,7 +399,7 @@ def test_empty_string() -> None:
 
 
 def test_unparseable_notebook() -> None:
-    path = DATA_DIR / "notebook_which_cant_be_parsed.ipynb"
+    path = get_case_path("jupyter", "notebook_which_cant_be_parsed.ipynb")
     msg = rf"File '{re.escape(str(path))}' cannot be parsed as valid Jupyter notebook\."
     with pytest.raises(ValueError, match=msg):
         format_file_in_place(path, fast=True, mode=JUPYTER_MODE)
@@ -418,7 +409,7 @@ def test_ipynb_diff_with_change() -> None:
     result = runner.invoke(
         main,
         [
-            str(DATA_DIR / "notebook_trailing_newline.ipynb"),
+            str(get_case_path("jupyter", "notebook_trailing_newline.ipynb")),
             "--diff",
             f"--config={EMPTY_CONFIG}",
         ],
@@ -431,7 +422,7 @@ def test_ipynb_diff_with_no_change() -> None:
     result = runner.invoke(
         main,
         [
-            str(DATA_DIR / "notebook_without_changes.ipynb"),
+            str(get_case_path("jupyter", "notebook_without_changes.ipynb")),
             "--diff",
             f"--config={EMPTY_CONFIG}",
         ],
@@ -445,7 +436,7 @@ def test_cache_isnt_written_if_no_jupyter_deps_single(
 ) -> None:
     # Check that the cache isn't written to if Jupyter dependencies aren't installed.
     jupyter_dependencies_are_installed.cache_clear()
-    nb = DATA_DIR / "notebook_trailing_newline.ipynb"
+    nb = get_case_path("jupyter", "notebook_trailing_newline.ipynb")
     tmp_nb = tmp_path / "notebook.ipynb"
     with open(nb) as src, open(tmp_nb, "w") as dst:
         dst.write(src.read())
@@ -471,7 +462,7 @@ def test_cache_isnt_written_if_no_jupyter_deps_dir(
 ) -> None:
     # Check that the cache isn't written to if Jupyter dependencies aren't installed.
     jupyter_dependencies_are_installed.cache_clear()
-    nb = DATA_DIR / "notebook_trailing_newline.ipynb"
+    nb = get_case_path("jupyter", "notebook_trailing_newline.ipynb")
     tmp_nb = tmp_path / "notebook.ipynb"
     with open(nb) as src, open(tmp_nb, "w") as dst:
         dst.write(src.read())
@@ -489,7 +480,7 @@ def test_cache_isnt_written_if_no_jupyter_deps_dir(
 
 
 def test_ipynb_flag(tmp_path: pathlib.Path) -> None:
-    nb = DATA_DIR / "notebook_trailing_newline.ipynb"
+    nb = get_case_path("jupyter", "notebook_trailing_newline.ipynb")
     tmp_nb = tmp_path / "notebook.a_file_extension_which_is_definitely_not_ipynb"
     with open(nb) as src, open(tmp_nb, "w") as dst:
         dst.write(src.read())
@@ -507,7 +498,7 @@ def test_ipynb_flag(tmp_path: pathlib.Path) -> None:
 
 
 def test_ipynb_and_pyi_flags() -> None:
-    nb = DATA_DIR / "notebook_trailing_newline.ipynb"
+    nb = get_case_path("jupyter", "notebook_trailing_newline.ipynb")
     result = runner.invoke(
         main,
         [
diff --git a/tests/test_no_ipynb.py b/tests/test_no_ipynb.py
index b03b8e13f14..a3c897760fb 100644
--- a/tests/test_no_ipynb.py
+++ b/tests/test_no_ipynb.py
@@ -1,8 +1,7 @@
 import pytest
-import os
 import pathlib
 
-from tests.util import THIS_DIR
+from tests.util import get_case_path
 from black import main, jupyter_dependencies_are_installed
 from click.testing import CliRunner
 
@@ -13,7 +12,7 @@
 
 def test_ipynb_diff_with_no_change_single() -> None:
     jupyter_dependencies_are_installed.cache_clear()
-    path = THIS_DIR / "data/notebook_trailing_newline.ipynb"
+    path = get_case_path("jupyter", "notebook_trailing_newline.ipynb")
     result = runner.invoke(main, [str(path)])
     expected_output = (
         "Skipping .ipynb files as Jupyter dependencies are not installed.\n"
@@ -25,7 +24,7 @@ def test_ipynb_diff_with_no_change_single() -> None:
 def test_ipynb_diff_with_no_change_dir(tmp_path: pathlib.Path) -> None:
     jupyter_dependencies_are_installed.cache_clear()
     runner = CliRunner()
-    nb = os.path.join("tests", "data", "notebook_trailing_newline.ipynb")
+    nb = get_case_path("jupyter", "notebook_trailing_newline.ipynb")
     tmp_nb = tmp_path / "notebook.ipynb"
     with open(nb) as src, open(tmp_nb, "w") as dst:
         dst.write(src.read())
diff --git a/tests/util.py b/tests/util.py
index 1d76681dbea..d65c2e651ae 100644
--- a/tests/util.py
+++ b/tests/util.py
@@ -11,6 +11,9 @@
 from black.mode import TargetVersion
 from black.output import diff, err, out
 
+PYTHON_SUFFIX = ".py"
+ALLOWED_SUFFIXES = (PYTHON_SUFFIX, ".pyi", ".out", ".diff", ".ipynb")
+
 THIS_DIR = Path(__file__).parent
 DATA_DIR = THIS_DIR / "data"
 PROJECT_ROOT = THIS_DIR.parent
@@ -90,21 +93,30 @@ def assertFormatEqual(self, expected: str, actual: str) -> None:
         _assert_format_equal(expected, actual)
 
 
-def all_data_cases(dir_name: str, data: bool = True) -> List[str]:
-    base_dir = DATA_DIR if data else PROJECT_ROOT
-    cases_dir = base_dir / dir_name
+def get_base_dir(data: bool) -> Path:
+    return DATA_DIR if data else PROJECT_ROOT
+
+
+def all_data_cases(subdir_name: str, data: bool = True) -> List[str]:
+    cases_dir = get_base_dir(data) / subdir_name
     assert cases_dir.is_dir()
-    return [f"{dir_name}/{case_path.stem}" for case_path in cases_dir.iterdir()]
+    return [case_path.stem for case_path in cases_dir.iterdir()]
 
 
-def read_data(name: str, data: bool = True) -> Tuple[str, str]:
-    """read_data('test_name') -> 'input', 'output'"""
-    if not name.endswith((".py", ".pyi", ".out", ".diff")):
-        name += ".py"
-    base_dir = DATA_DIR if data else PROJECT_ROOT
-    case_path = base_dir / name
+def get_case_path(
+    subdir_name: str, name: str, data: bool = True, suffix: str = PYTHON_SUFFIX
+) -> Path:
+    """Get case path from name"""
+    case_path = get_base_dir(data) / subdir_name / name
+    if not name.endswith(ALLOWED_SUFFIXES):
+        case_path = case_path.with_suffix(suffix)
     assert case_path.is_file(), f"{case_path} is not a file."
-    return read_data_from_file(case_path)
+    return case_path
+
+
+def read_data(subdir_name: str, name: str, data: bool = True) -> Tuple[str, str]:
+    """read_data('test_name') -> 'input', 'output'"""
+    return read_data_from_file(get_case_path(subdir_name, name, data))
 
 
 def read_data_from_file(file_name: Path) -> Tuple[str, str]:
@@ -126,6 +138,18 @@ def read_data_from_file(file_name: Path) -> Tuple[str, str]:
     return "".join(_input).strip() + "\n", "".join(_output).strip() + "\n"
 
 
+def read_jupyter_notebook(subdir_name: str, name: str, data: bool = True) -> str:
+    return read_jupyter_notebook_from_file(
+        get_case_path(subdir_name, name, data, suffix=".ipynb")
+    )
+
+
+def read_jupyter_notebook_from_file(file_name: Path) -> str:
+    with open(file_name, mode="rb") as fd:
+        content_bytes = fd.read()
+    return content_bytes.decode()
+
+
 @contextmanager
 def change_directory(path: Path) -> Iterator[None]:
     """Context manager to temporarily chdir to a different directory."""

From fdb01f8622de9394fe9d8ee149985d365ca1419f Mon Sep 17 00:00:00 2001
From: laundmo <laurinschmidt2001@gmail.com>
Date: Sat, 21 May 2022 22:18:06 +0200
Subject: [PATCH 0541/1034] Document new Microsoft Black Formatter extension
 for VSCode (#3063)

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 docs/integrations/editors.md | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/docs/integrations/editors.md b/docs/integrations/editors.md
index 1c7879b63a6..02baa29511b 100644
--- a/docs/integrations/editors.md
+++ b/docs/integrations/editors.md
@@ -301,9 +301,15 @@ close and reopen your File, _Black_ will be done with its job.
 
 ## Visual Studio Code
 
-Use the
-[Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python)
-([instructions](https://code.visualstudio.com/docs/python/editing#_formatting)).
+- Use the
+  [Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python)
+  ([instructions](https://code.visualstudio.com/docs/python/editing#_formatting)).
+
+- Alternatively the pre-release
+  [Black Formatter](https://marketplace.visualstudio.com/items?itemName=ms-python.black-formatter)
+  extension can be used which runs a [Language Server Protocol](https://langserver.org/)
+  server for Black. Formatting is much more responsive using this extension, **but the
+  minimum supported version of Black is 22.3.0**.
 
 ## SublimeText 3
 

From 9fe788d8704c1d4726b30e41e181c687c02cc1cf Mon Sep 17 00:00:00 2001
From: Yusuke Nishioka <yusuke.nishioka.0713@gmail.com>
Date: Thu, 26 May 2022 23:44:26 +0900
Subject: [PATCH 0542/1034] Add more examples to exclude files in addition to
 the defaults (#3070)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 docs/usage_and_configuration/the_basics.md | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index 4c793f459a2..c7e2d4a4dde 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -259,10 +259,14 @@ expressions by Black. Use `[ ]` to denote a significant space character.
 line-length = 88
 target-version = ['py37']
 include = '\.pyi?$'
+# 'extend-exclude' excludes files or directories in addition to the defaults
 extend-exclude = '''
 # A regex preceded with ^/ will apply only to files and directories
 # in the root of the project.
-^/foo.py  # exclude a file named foo.py in the root of the project (in addition to the defaults)
+(
+  ^/foo.py    # exclude a file named foo.py in the root of the project
+  | *_pb2.py  # exclude autogenerated Protocol Buffer files anywhere in the project
+)
 '''
 ```
 

From 1e557184b0a9f43bfbff862669966bc5328517e9 Mon Sep 17 00:00:00 2001
From: Batuhan Taskaya <isidentical@gmail.com>
Date: Thu, 26 May 2022 19:45:22 +0300
Subject: [PATCH 0543/1034] Implement support for PEP 646 (#3071)

---
 CHANGES.md                   |   2 +
 src/black/__init__.py        |  12 +++
 src/black/mode.py            |   2 +
 src/black/nodes.py           |  13 ++-
 src/blib2to3/Grammar.txt     |   9 +-
 src/blib2to3/pygram.py       |   1 +
 tests/data/py_311/pep_646.py | 194 +++++++++++++++++++++++++++++++++++
 tests/test_black.py          |   6 ++
 8 files changed, 233 insertions(+), 6 deletions(-)
 create mode 100644 tests/data/py_311/pep_646.py

diff --git a/CHANGES.md b/CHANGES.md
index 8f43431c842..6bc67f9db06 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -56,6 +56,8 @@
 
 - [PEP 654](https://peps.python.org/pep-0654/#except) syntax (for example,
   `except *ExceptionGroup:`) is now supported (#3016)
+- [PEP 646](https://peps.python.org/pep-0646) syntax (for example,
+  `Array[Batch, *Shape]` or `def fn(*args: *T) -> None`) is now supported (#3071)
 
 <!-- Changes to the parser or to version autodetection -->
 
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 75321c3f35c..8872102a6ea 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -1308,6 +1308,18 @@ def get_features_used(  # noqa: C901
         ):
             features.add(Feature.EXCEPT_STAR)
 
+        elif n.type in {syms.subscriptlist, syms.trailer} and any(
+            child.type == syms.star_expr for child in n.children
+        ):
+            features.add(Feature.VARIADIC_GENERICS)
+
+        elif (
+            n.type == syms.tname_star
+            and len(n.children) == 3
+            and n.children[2].type == syms.star_expr
+        ):
+            features.add(Feature.VARIADIC_GENERICS)
+
     return features
 
 
diff --git a/src/black/mode.py b/src/black/mode.py
index a418e0eb665..bf79f6a3148 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -49,6 +49,7 @@ class Feature(Enum):
     UNPACKING_ON_FLOW = 12
     ANN_ASSIGN_EXTENDED_RHS = 13
     EXCEPT_STAR = 14
+    VARIADIC_GENERICS = 15
     FORCE_OPTIONAL_PARENTHESES = 50
 
     # __future__ flags
@@ -132,6 +133,7 @@ class Feature(Enum):
         Feature.ANN_ASSIGN_EXTENDED_RHS,
         Feature.PATTERN_MATCHING,
         Feature.EXCEPT_STAR,
+        Feature.VARIADIC_GENERICS,
     },
 }
 
diff --git a/src/black/nodes.py b/src/black/nodes.py
index 37b96a498d6..918038f69ba 100644
--- a/src/black/nodes.py
+++ b/src/black/nodes.py
@@ -120,6 +120,7 @@
     syms.term,
     syms.power,
 }
+TYPED_NAMES: Final = {syms.tname, syms.tname_star}
 ASSIGNMENTS: Final = {
     "=",
     "+=",
@@ -243,6 +244,14 @@ def whitespace(leaf: Leaf, *, complex_subscript: bool) -> str:  # noqa: C901
                     # that, too.
                     return prevp.prefix
 
+        elif (
+            prevp.type == token.STAR
+            and parent_type(prevp) == syms.star_expr
+            and parent_type(prevp.parent) == syms.subscriptlist
+        ):
+            # No space between typevar tuples.
+            return NO
+
         elif prevp.type in VARARGS_SPECIALS:
             if is_vararg(prevp, within=VARARGS_PARENTS | UNPACKING_PARENTS):
                 return NO
@@ -281,7 +290,7 @@ def whitespace(leaf: Leaf, *, complex_subscript: bool) -> str:  # noqa: C901
             return NO
 
         if t == token.EQUAL:
-            if prev.type != syms.tname:
+            if prev.type not in TYPED_NAMES:
                 return NO
 
         elif prev.type == token.EQUAL:
@@ -292,7 +301,7 @@ def whitespace(leaf: Leaf, *, complex_subscript: bool) -> str:  # noqa: C901
         elif prev.type != token.COMMA:
             return NO
 
-    elif p.type == syms.tname:
+    elif p.type in TYPED_NAMES:
         # type names
         if not prev:
             prevp = preceding_leaf(p)
diff --git a/src/blib2to3/Grammar.txt b/src/blib2to3/Grammar.txt
index 1de54165513..ac7ad7643ff 100644
--- a/src/blib2to3/Grammar.txt
+++ b/src/blib2to3/Grammar.txt
@@ -24,7 +24,7 @@ parameters: '(' [typedargslist] ')'
 #     arguments = argument (',' argument)*
 #     argument = tfpdef ['=' test]
 #     kwargs = '**' tname [',']
-#     args = '*' [tname]
+#     args = '*' [tname_star]
 #     kwonly_kwargs = (',' argument)* [',' [kwargs]]
 #     args_kwonly_kwargs = args kwonly_kwargs | kwargs
 #     poskeyword_args_kwonly_kwargs = arguments [',' [args_kwonly_kwargs]]
@@ -34,14 +34,15 @@ parameters: '(' [typedargslist] ')'
 # It needs to be fully expanded to allow our LL(1) parser to work on it.
 
 typedargslist: tfpdef ['=' test] (',' tfpdef ['=' test])* ',' '/' [
-                     ',' [((tfpdef ['=' test] ',')* ('*' [tname] (',' tname ['=' test])*
+                     ',' [((tfpdef ['=' test] ',')* ('*' [tname_star] (',' tname ['=' test])*
                             [',' ['**' tname [',']]] | '**' tname [','])
                      | tfpdef ['=' test] (',' tfpdef ['=' test])* [','])]
-                ] | ((tfpdef ['=' test] ',')* ('*' [tname] (',' tname ['=' test])*
+                ] | ((tfpdef ['=' test] ',')* ('*' [tname_star] (',' tname ['=' test])*
                      [',' ['**' tname [',']]] | '**' tname [','])
                      | tfpdef ['=' test] (',' tfpdef ['=' test])* [','])
 
 tname: NAME [':' test]
+tname_star: NAME [':' (test|star_expr)]
 tfpdef: tname | '(' tfplist ')'
 tfplist: tfpdef (',' tfpdef)* [',']
 
@@ -163,7 +164,7 @@ listmaker: (namedexpr_test|star_expr) ( old_comp_for | (',' (namedexpr_test|star
 testlist_gexp: (namedexpr_test|star_expr) ( old_comp_for | (',' (namedexpr_test|star_expr))* [','] )
 lambdef: 'lambda' [varargslist] ':' test
 trailer: '(' [arglist] ')' | '[' subscriptlist ']' | '.' NAME
-subscriptlist: subscript (',' subscript)* [',']
+subscriptlist: (subscript|star_expr) (',' (subscript|star_expr))* [',']
 subscript: test [':=' test] | [test] ':' [test] [sliceop]
 sliceop: ':' [test]
 exprlist: (expr|star_expr) (',' (expr|star_expr))* [',']
diff --git a/src/blib2to3/pygram.py b/src/blib2to3/pygram.py
index a3df9be1265..99012cdd9cb 100644
--- a/src/blib2to3/pygram.py
+++ b/src/blib2to3/pygram.py
@@ -123,6 +123,7 @@ class _python_symbols(Symbols):
     tfpdef: int
     tfplist: int
     tname: int
+    tname_star: int
     trailer: int
     try_stmt: int
     typedargslist: int
diff --git a/tests/data/py_311/pep_646.py b/tests/data/py_311/pep_646.py
new file mode 100644
index 00000000000..e843ecf39d8
--- /dev/null
+++ b/tests/data/py_311/pep_646.py
@@ -0,0 +1,194 @@
+A[*b]
+A[*b] = 1
+A
+del A[*b]
+A
+A[*b, *b]
+A[*b, *b] = 1
+A
+del A[*b, *b]
+A
+A[b, *b]
+A[b, *b] = 1
+A
+del A[b, *b]
+A
+A[*b, b]
+A[*b, b] = 1
+A
+del A[*b, b]
+A
+A[b, b, *b]
+A[b, b, *b] = 1
+A
+del A[b, b, *b]
+A
+A[*b, b, b]
+A[*b, b, b] = 1
+A
+del A[*b, b, b]
+A
+A[b, *b, b]
+A[b, *b, b] = 1
+A
+del A[b, *b, b]
+A
+A[b, b, *b, b]
+A[b, b, *b, b] = 1
+A
+del A[b, b, *b, b]
+A
+A[b, *b, b, b]
+A[b, *b, b, b] = 1
+A
+del A[b, *b, b, b]
+A
+A[A[b, *b, b]]
+A[A[b, *b, b]] = 1
+A
+del A[A[b, *b, b]]
+A
+A[*A[b, *b, b]]
+A[*A[b, *b, b]] = 1
+A
+del A[*A[b, *b, b]]
+A
+A[b, ...]
+A[b, ...] = 1
+A
+del A[b, ...]
+A
+A[*A[b, ...]]
+A[*A[b, ...]] = 1
+A
+del A[*A[b, ...]]
+A
+l = [1, 2, 3]
+A[*l]
+A[*l] = 1
+A
+del A[*l]
+A
+A[*l, 4]
+A[*l, 4] = 1
+A
+del A[*l, 4]
+A
+A[0, *l]
+A[0, *l] = 1
+A
+del A[0, *l]
+A
+A[1:2, *l]
+A[1:2, *l] = 1
+A
+del A[1:2, *l]
+A
+repr(A[1:2, *l]) == repr(A[1:2, 1, 2, 3])
+t = (1, 2, 3)
+A[*t]
+A[*t] = 1
+A
+del A[*t]
+A
+A[*t, 4]
+A[*t, 4] = 1
+A
+del A[*t, 4]
+A
+A[0, *t]
+A[0, *t] = 1
+A
+del A[0, *t]
+A
+A[1:2, *t]
+A[1:2, *t] = 1
+A
+del A[1:2, *t]
+A
+repr(A[1:2, *t]) == repr(A[1:2, 1, 2, 3])
+
+
+def returns_list():
+    return [1, 2, 3]
+
+
+A[returns_list()]
+A[returns_list()] = 1
+A
+del A[returns_list()]
+A
+A[returns_list(), 4]
+A[returns_list(), 4] = 1
+A
+del A[returns_list(), 4]
+A
+A[*returns_list()]
+A[*returns_list()] = 1
+A
+del A[*returns_list()]
+A
+A[*returns_list(), 4]
+A[*returns_list(), 4] = 1
+A
+del A[*returns_list(), 4]
+A
+A[0, *returns_list()]
+A[0, *returns_list()] = 1
+A
+del A[0, *returns_list()]
+A
+A[*returns_list(), *returns_list()]
+A[*returns_list(), *returns_list()] = 1
+A
+del A[*returns_list(), *returns_list()]
+A
+A[1:2, *b]
+A[*b, 1:2]
+A[1:2, *b, 1:2]
+A[*b, 1:2, *b]
+A[1:, *b]
+A[*b, 1:]
+A[1:, *b, 1:]
+A[*b, 1:, *b]
+A[:1, *b]
+A[*b, :1]
+A[:1, *b, :1]
+A[*b, :1, *b]
+A[:, *b]
+A[*b, :]
+A[:, *b, :]
+A[*b, :, *b]
+A[a * b()]
+A[a * b(), *c, *d(), e * f(g * h)]
+A[a * b(), :]
+A[a * b(), *c, *d(), e * f(g * h) :]
+A[[b] * len(c), :]
+
+
+def f1(*args: *b):
+    pass
+
+
+f1.__annotations__
+
+
+def f2(*args: *b, arg1):
+    pass
+
+
+f2.__annotations__
+
+
+def f3(*args: *b, arg1: int):
+    pass
+
+
+f3.__annotations__
+
+
+def f4(*args: *b, arg1: int = 2):
+    pass
+
+
+f4.__annotations__
diff --git a/tests/test_black.py b/tests/test_black.py
index a633e678dd7..02a707e8996 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -804,6 +804,12 @@ def test_get_features_used(self) -> None:
         self.assertEqual(black.get_features_used(node), set())
         node = black.lib2to3_parse("try: pass\nexcept *Group: pass")
         self.assertEqual(black.get_features_used(node), {Feature.EXCEPT_STAR})
+        node = black.lib2to3_parse("a[*b]")
+        self.assertEqual(black.get_features_used(node), {Feature.VARIADIC_GENERICS})
+        node = black.lib2to3_parse("a[x, *y(), z] = t")
+        self.assertEqual(black.get_features_used(node), {Feature.VARIADIC_GENERICS})
+        node = black.lib2to3_parse("def fn(*args: *T): pass")
+        self.assertEqual(black.get_features_used(node), {Feature.VARIADIC_GENERICS})
 
     def test_get_features_used_for_future_flags(self) -> None:
         for src, features in [

From 436e12f2904e68acb57a059b1c44f1e0321e2d3f Mon Sep 17 00:00:00 2001
From: Holger Brunn <mail@hunki-enterprises.com>
Date: Wed, 1 Jun 2022 20:20:02 +0200
Subject: [PATCH 0544/1034] Add script to ease migration to black (#3038)

* Add script to ease migration to black

* Update CHANGES.md

Co-authored-by: Cooper Lees <me@cooperlees.com>
---
 CHANGES.md               |  2 +
 scripts/migrate-black.py | 95 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 97 insertions(+)
 create mode 100755 scripts/migrate-black.py

diff --git a/CHANGES.md b/CHANGES.md
index 6bc67f9db06..a6b6594b57a 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -39,6 +39,8 @@
 
 <!-- For example, Docker, GitHub Actions, pre-commit, editors -->
 
+- Add migrate-black.py script to ease migration to black formatted git project (#3038)
+
 ### Output
 
 <!-- Changes to Black's terminal output and error messages -->
diff --git a/scripts/migrate-black.py b/scripts/migrate-black.py
new file mode 100755
index 00000000000..5a6bc424824
--- /dev/null
+++ b/scripts/migrate-black.py
@@ -0,0 +1,95 @@
+#!/usr/bin/env python3
+# check out every commit added by the current branch, blackify them,
+# and generate diffs to reconstruct the original commits, but then
+# blackified
+import logging
+import os
+import sys
+from subprocess import check_output, run, Popen, PIPE
+
+
+def git(*args: str) -> str:
+    return check_output(["git"] + list(args)).decode("utf8").strip()
+
+
+def blackify(base_branch: str, black_command: str, logger: logging.Logger) -> int:
+    current_branch = git("branch", "--show-current")
+
+    if not current_branch or base_branch == current_branch:
+        logger.error("You need to check out a feature brach to work on")
+        return 1
+
+    if not os.path.exists(".git"):
+        logger.error("Run me in the root of your repo")
+        return 1
+
+    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
+        )
+        return 1
+
+    commits = git(
+        "log", "--reverse", "--pretty=format:%H", "%s~1..HEAD" % merge_base
+    ).split()
+    for commit in commits:
+        git("checkout", commit, "-b%s-black" % commit)
+        check_output(black_command, shell=True)
+        git("commit", "-aqm", "blackify")
+
+    git("checkout", base_branch, "-b%s-black" % current_branch)
+
+    for last_commit, commit in zip(commits, commits[1:]):
+        allow_empty = (
+            b"--allow-empty" in run(["git", "apply", "-h"], stdout=PIPE).stdout
+        )
+        quiet = b"--quiet" in run(["git", "apply", "-h"], stdout=PIPE).stdout
+        git_diff = Popen(
+            [
+                "git",
+                "diff",
+                "--find-copies",
+                "%s-black..%s-black" % (last_commit, commit),
+            ],
+            stdout=PIPE,
+        )
+        git_apply = Popen(
+            [
+                "git",
+                "apply",
+            ]
+            + (["--quiet"] if quiet else [])
+            + [
+                "-3",
+                "--intent-to-add",
+            ]
+            + (["--allow-empty"] if allow_empty else [])
+            + [
+                "-",
+            ],
+            stdin=git_diff.stdout,
+        )
+        if git_diff.stdout is not None:
+            git_diff.stdout.close()
+        git_apply.communicate()
+        git("commit", "--allow-empty", "-aqC", commit)
+
+    for commit in commits:
+        git("branch", "-qD", "%s-black" % commit)
+
+    return 0
+
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser()
+    parser.add_argument("base_branch")
+    parser.add_argument("--black_command", default="black -q .")
+    parser.add_argument("--logfile", type=argparse.FileType("w"), default=sys.stdout)
+    args = parser.parse_args()
+    logger = logging.getLogger(__name__)
+    logger.addHandler(logging.StreamHandler(args.logfile))
+    logger.setLevel(logging.INFO)
+    sys.exit(blackify(args.base_branch, args.black_command, logger))

From f51e53726b39a177355a7917c91c56f390dda7ef Mon Sep 17 00:00:00 2001
From: Vivek Vashist <vivekvashist@gmail.com>
Date: Sat, 4 Jun 2022 08:29:26 +0930
Subject: [PATCH 0545/1034] Fix minor typo (#3096)

---
 scripts/migrate-black.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/migrate-black.py b/scripts/migrate-black.py
index 5a6bc424824..1183cb8a104 100755
--- a/scripts/migrate-black.py
+++ b/scripts/migrate-black.py
@@ -16,7 +16,7 @@ def blackify(base_branch: str, black_command: str, logger: logging.Logger) -> in
     current_branch = git("branch", "--show-current")
 
     if not current_branch or base_branch == current_branch:
-        logger.error("You need to check out a feature brach to work on")
+        logger.error("You need to check out a feature branch to work on")
         return 1
 
     if not os.path.exists(".git"):

From 6d32ab02c535c3d41495f62288c9c3fc57e9a9bb Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Fri, 10 Jun 2022 20:29:32 -0400
Subject: [PATCH 0546/1034] Bump pre-commit/action from 2.0.3 to 3.0.0 (#3108)

Bumps [pre-commit/action](https://github.com/pre-commit/action) from 2.0.3 to 3.0.0.
- [Release notes](https://github.com/pre-commit/action/releases)
- [Commits](https://github.com/pre-commit/action/compare/v2.0.3...v3.0.0)

---
updated-dependencies:
- dependency-name: pre-commit/action
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/lint.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index b630114882d..01cf31502b1 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -25,4 +25,4 @@ jobs:
           python -m pip install -e '.[d]'
 
       - name: Lint
-        uses: pre-commit/action@v2.0.3
+        uses: pre-commit/action@v3.0.0

From 4bb7bf2bdc95a8035ccf167023a7044e5f8e5ef6 Mon Sep 17 00:00:00 2001
From: Sagi Shadur <saroad2@gmail.com>
Date: Sat, 11 Jun 2022 09:55:01 +0300
Subject: [PATCH 0547/1034] Remove newline after code block open (#3035)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 AUTHORS.md                                    |   1 +
 CHANGES.md                                    |   1 +
 docs/the_black_code_style/future_style.md     |  25 +++
 src/black/lines.py                            |  13 ++
 src/black/mode.py                             |   1 +
 .../remove_newline_after_code_block_open.py   | 189 ++++++++++++++++++
 .../preview_310/remove_newline_after match.py |  34 ++++
 tests/test_black.py                           |   1 -
 tests/test_format.py                          |   7 +
 9 files changed, 271 insertions(+), 1 deletion(-)
 create mode 100644 tests/data/preview/remove_newline_after_code_block_open.py
 create mode 100644 tests/data/preview_310/remove_newline_after match.py

diff --git a/AUTHORS.md b/AUTHORS.md
index 8aa6263313e..faa2b05840f 100644
--- a/AUTHORS.md
+++ b/AUTHORS.md
@@ -148,6 +148,7 @@ Multiple contributions by:
 - [Rishikesh Jha](mailto:rishijha424@gmail.com)
 - [Rupert Bedford](mailto:rupert@rupertb.com)
 - Russell Davis
+- [Sagi Shadur](mailto:saroad2@gmail.com)
 - [Rémi Verschelde](mailto:rverschelde@gmail.com)
 - [Sami Salonen](mailto:sakki@iki.fi)
 - [Samuel Cormier-Iijima](mailto:samuel@cormier-iijima.com)
diff --git a/CHANGES.md b/CHANGES.md
index a6b6594b57a..7001271087a 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -21,6 +21,7 @@
 - Remove redundant parentheses around awaited objects (#2991)
 - Parentheses around return annotations are now managed (#2990)
 - Remove unnecessary parentheses from `with` statements (#2926)
+- Remove trailing newlines after code block open (#3035)
 
 ### _Blackd_
 
diff --git a/docs/the_black_code_style/future_style.md b/docs/the_black_code_style/future_style.md
index 2ec2c0333a5..8d159e9b0a2 100644
--- a/docs/the_black_code_style/future_style.md
+++ b/docs/the_black_code_style/future_style.md
@@ -49,3 +49,28 @@ plain strings. User-made splits are respected when they do not exceed the line l
 limit. Line continuation backslashes are converted into parenthesized strings.
 Unnecessary parentheses are stripped. The stability and status of this feature is
 tracked in [this issue](https://github.com/psf/black/issues/2188).
+
+### Removing trailing newlines after code block open
+
+_Black_ will remove trailing newlines after code block openings. That means that the
+following code:
+
+```python
+def my_func():
+
+    print("The line above me will be deleted!")
+
+    print("But the line above me won't!")
+```
+
+Will be changed to:
+
+```python
+def my_func():
+    print("The line above me will be deleted!")
+
+    print("But the line above me won't!")
+```
+
+This new feature will be applied to **all code blocks**: `def`, `class`, `if`, `for`,
+`while`, `with`, `case` and `match`.
diff --git a/src/black/lines.py b/src/black/lines.py
index e455a507539..8b591c324a5 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -168,6 +168,13 @@ def is_triple_quoted_string(self) -> bool:
             and self.leaves[0].value.startswith(('"""', "'''"))
         )
 
+    @property
+    def opens_block(self) -> bool:
+        """Does this line open a new level of indentation."""
+        if len(self.leaves) == 0:
+            return False
+        return self.leaves[-1].type == token.COLON
+
     def contains_standalone_comments(self, depth_limit: int = sys.maxsize) -> bool:
         """If so, needs to be split before emitting."""
         for leaf in self.leaves:
@@ -513,6 +520,12 @@ def _maybe_empty_lines(self, current_line: Line) -> Tuple[int, int]:
         ):
             return before, 1
 
+        if (
+            Preview.remove_block_trailing_newline in current_line.mode
+            and self.previous_line
+            and self.previous_line.opens_block
+        ):
+            return 0, 0
         return before, 0
 
     def _maybe_empty_lines_for_class_or_def(
diff --git a/src/black/mode.py b/src/black/mode.py
index bf79f6a3148..896c516df79 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -150,6 +150,7 @@ class Preview(Enum):
     one_element_subscript = auto()
     annotation_parens = auto()
     long_docstring_quotes_on_newline = auto()
+    remove_block_trailing_newline = auto()
 
 
 class Deprecated(UserWarning):
diff --git a/tests/data/preview/remove_newline_after_code_block_open.py b/tests/data/preview/remove_newline_after_code_block_open.py
new file mode 100644
index 00000000000..ef2e5c2f6f5
--- /dev/null
+++ b/tests/data/preview/remove_newline_after_code_block_open.py
@@ -0,0 +1,189 @@
+import random
+
+
+def foo1():
+
+    print("The newline above me should be deleted!")
+
+
+def foo2():
+
+
+
+    print("All the newlines above me should be deleted!")
+
+
+def foo3():
+
+    print("No newline above me!")
+
+    print("There is a newline above me, and that's OK!")
+
+
+def foo4():
+
+    # There is a comment here
+
+    print("The newline above me should not be deleted!")
+
+
+class Foo:
+    def bar(self):
+
+        print("The newline above me should be deleted!")
+
+
+for i in range(5):
+
+    print(f"{i}) The line above me should be removed!")
+
+
+for i in range(5):
+
+
+
+    print(f"{i}) The lines above me should be removed!")
+
+
+for i in range(5):
+
+    for j in range(7):
+
+        print(f"{i}) The lines above me should be removed!")
+
+
+if random.randint(0, 3) == 0:
+
+    print("The new line above me is about to be removed!")
+
+
+if random.randint(0, 3) == 0:
+
+
+
+
+    print("The new lines above me is about to be removed!")
+
+
+if random.randint(0, 3) == 0:
+    if random.uniform(0, 1) > 0.5:
+        print("Two lines above me are about to be removed!")
+
+
+while True:
+
+    print("The newline above me should be deleted!")
+
+
+while True:
+
+
+
+    print("The newlines above me should be deleted!")
+
+
+while True:
+
+    while False:
+
+        print("The newlines above me should be deleted!")
+
+
+with open("/path/to/file.txt", mode="w") as file:
+
+    file.write("The new line above me is about to be removed!")
+
+
+with open("/path/to/file.txt", mode="w") as file:
+
+
+
+    file.write("The new lines above me is about to be removed!")
+
+
+with open("/path/to/file.txt", mode="r") as read_file:
+
+    with open("/path/to/output_file.txt", mode="w") as write_file:
+
+        write_file.writelines(read_file.readlines())
+
+# output
+
+import random
+
+
+def foo1():
+    print("The newline above me should be deleted!")
+
+
+def foo2():
+    print("All the newlines above me should be deleted!")
+
+
+def foo3():
+    print("No newline above me!")
+
+    print("There is a newline above me, and that's OK!")
+
+
+def foo4():
+    # There is a comment here
+
+    print("The newline above me should not be deleted!")
+
+
+class Foo:
+    def bar(self):
+        print("The newline above me should be deleted!")
+
+
+for i in range(5):
+    print(f"{i}) The line above me should be removed!")
+
+
+for i in range(5):
+    print(f"{i}) The lines above me should be removed!")
+
+
+for i in range(5):
+    for j in range(7):
+        print(f"{i}) The lines above me should be removed!")
+
+
+if random.randint(0, 3) == 0:
+    print("The new line above me is about to be removed!")
+
+
+if random.randint(0, 3) == 0:
+    print("The new lines above me is about to be removed!")
+
+
+if random.randint(0, 3) == 0:
+    if random.uniform(0, 1) > 0.5:
+        print("Two lines above me are about to be removed!")
+
+
+while True:
+    print("The newline above me should be deleted!")
+
+
+while True:
+    print("The newlines above me should be deleted!")
+
+
+while True:
+    while False:
+        print("The newlines above me should be deleted!")
+
+
+with open("/path/to/file.txt", mode="w") as file:
+    file.write("The new line above me is about to be removed!")
+
+
+with open("/path/to/file.txt", mode="w") as file:
+    file.write("The new lines above me is about to be removed!")
+
+
+with open("/path/to/file.txt", mode="r") as read_file:
+    with open("/path/to/output_file.txt", mode="w") as write_file:
+        write_file.writelines(read_file.readlines())
diff --git a/tests/data/preview_310/remove_newline_after match.py b/tests/data/preview_310/remove_newline_after match.py
new file mode 100644
index 00000000000..f7bcfbf27a2
--- /dev/null
+++ b/tests/data/preview_310/remove_newline_after match.py	
@@ -0,0 +1,34 @@
+def http_status(status):
+
+    match status:
+
+        case 400:
+
+            return "Bad request"
+
+        case 401:
+
+            return "Unauthorized"
+
+        case 403:
+
+            return "Forbidden"
+
+        case 404:
+
+            return "Not found"
+
+# output
+def http_status(status):
+    match status:
+        case 400:
+            return "Bad request"
+
+        case 401:
+            return "Unauthorized"
+
+        case 403:
+            return "Forbidden"
+
+        case 404:
+            return "Not found"
\ No newline at end of file
diff --git a/tests/test_black.py b/tests/test_black.py
index 02a707e8996..8adcaed5ef8 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -1461,7 +1461,6 @@ def test_newline_comment_interaction(self) -> None:
         black.assert_stable(source, output, mode=DEFAULT_MODE)
 
     def test_bpo_2142_workaround(self) -> None:
-
         # https://bugs.python.org/issue2142
 
         source, _ = read_data("miscellaneous", "missing_final_newline")
diff --git a/tests/test_format.py b/tests/test_format.py
index 005a5771c2b..a8a922d17db 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -86,6 +86,13 @@ def test_preview_minimum_python_39_format(filename: str) -> None:
     assert_format(source, expected, mode, minimum_version=(3, 9))
 
 
+@pytest.mark.parametrize("filename", all_data_cases("preview_310"))
+def test_preview_minimum_python_310_format(filename: str) -> None:
+    source, expected = read_data("preview_310", filename)
+    mode = black.Mode(preview=True)
+    assert_format(source, expected, mode, minimum_version=(3, 10))
+
+
 @pytest.mark.parametrize("filename", SOURCES)
 def test_source_is_formatted(filename: str) -> None:
     check_file("", filename, DEFAULT_MODE, data=False)

From 8c8675c62aef4fb662c686d19ebd35dc047258f0 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Sat, 11 Jun 2022 11:44:01 -0400
Subject: [PATCH 0548/1034] Update documentation dependencies (#3118)

Furo, myst-parser, and Sphinx (had to pin docutils due to sphinx breakage)
---
 docs/conf.py          | 2 +-
 docs/requirements.txt | 8 +++++---
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py
index e9fdebb5546..8da9c39ac41 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -87,7 +87,7 @@ def make_pypi_svg(version: str) -> None:
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
diff --git a/docs/requirements.txt b/docs/requirements.txt
index 72cf09fb6e9..a3c801ba613 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,7 +1,9 @@
 # Used by ReadTheDocs; pinned requirements for stability.
 
-myst-parser==0.17.2
-Sphinx==4.5.0
+myst-parser==0.18.0
+Sphinx==5.0.1
+# Older versions break Sphinx even though they're declared to be supported.
+docutils==0.18.1
 sphinxcontrib-programoutput==0.17
 sphinx_copybutton==0.5.0
-furo==2022.4.7
+furo==2022.6.4.1

From 162ecd1d2cf9471efefb5b61c17d28b73acb79a1 Mon Sep 17 00:00:00 2001
From: Marco Edward Gorelli <marcogorelli@protonmail.com>
Date: Sat, 11 Jun 2022 17:04:09 +0100
Subject: [PATCH 0549/1034] Use is_number_token instead of assertion (#3069)

---
 src/black/__init__.py | 5 ++---
 src/black/nodes.py    | 4 ++++
 2 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index 8872102a6ea..4200066e882 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -40,7 +40,7 @@
 from black.const import DEFAULT_LINE_LENGTH, DEFAULT_INCLUDES, DEFAULT_EXCLUDES
 from black.const import STDIN_PLACEHOLDER
 from black.nodes import STARS, syms, is_simple_decorator_expression
-from black.nodes import is_string_token
+from black.nodes import is_string_token, is_number_token
 from black.lines import Line, EmptyLineTracker
 from black.linegen import transform_line, LineGenerator, LN
 from black.comments import normalize_fmt_off
@@ -1245,8 +1245,7 @@ def get_features_used(  # noqa: C901
             if value_head in {'f"', 'F"', "f'", "F'", "rf", "fr", "RF", "FR"}:
                 features.add(Feature.F_STRINGS)
 
-        elif n.type == token.NUMBER:
-            assert isinstance(n, Leaf)
+        elif is_number_token(n):
             if "_" in n.value:
                 features.add(Feature.NUMERIC_UNDERSCORES)
 
diff --git a/src/black/nodes.py b/src/black/nodes.py
index 918038f69ba..12f24b96687 100644
--- a/src/black/nodes.py
+++ b/src/black/nodes.py
@@ -854,3 +854,7 @@ def is_rpar_token(nl: NL) -> TypeGuard[Leaf]:
 
 def is_string_token(nl: NL) -> TypeGuard[Leaf]:
     return nl.type == token.STRING
+
+
+def is_number_token(nl: NL) -> TypeGuard[Leaf]:
+    return nl.type == token.NUMBER

From 799adb53239e4a1e87253d40bc1cbd34f9103c52 Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <hugovk@users.noreply.github.com>
Date: Mon, 13 Jun 2022 17:02:39 +0300
Subject: [PATCH 0550/1034] Bump actions/setup-python from 3 to 4 (#3121)

Bumps [actions/setup-python](https://github.com/actions/setup-python) from 3 to 4.
- [Release notes](https://github.com/actions/setup-python/releases)
- [Commits](https://github.com/actions/setup-python/compare/v3...v4)

---
updated-dependencies:
- dependency-name: actions/setup-python
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>
---
 .github/workflows/diff_shades.yml         | 8 ++++++--
 .github/workflows/diff_shades_comment.yml | 4 +++-
 .github/workflows/doc.yml                 | 4 +++-
 .github/workflows/fuzz.yml                | 2 +-
 .github/workflows/lint.yml                | 4 +++-
 .github/workflows/pypi_upload.yml         | 4 +++-
 .github/workflows/test.yml                | 2 +-
 .github/workflows/upload_binary.yml       | 2 +-
 .github/workflows/uvloop_test.yml         | 4 +++-
 9 files changed, 24 insertions(+), 10 deletions(-)

diff --git a/.github/workflows/diff_shades.yml b/.github/workflows/diff_shades.yml
index 749f87cdcdb..390089eca42 100644
--- a/.github/workflows/diff_shades.yml
+++ b/.github/workflows/diff_shades.yml
@@ -20,7 +20,9 @@ jobs:
 
     steps:
       - uses: actions/checkout@v3
-      - uses: actions/setup-python@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: "*"
 
       - name: Install diff-shades and support dependencies
         run: |
@@ -54,7 +56,9 @@ jobs:
           # The baseline revision could be rather old so a full clone is ideal.
           fetch-depth: 0
 
-      - uses: actions/setup-python@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: "*"
 
       - name: Install diff-shades and support dependencies
         run: |
diff --git a/.github/workflows/diff_shades_comment.yml b/.github/workflows/diff_shades_comment.yml
index 94302735d0a..a5d213875c7 100644
--- a/.github/workflows/diff_shades_comment.yml
+++ b/.github/workflows/diff_shades_comment.yml
@@ -13,7 +13,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
-      - uses: actions/setup-python@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: "*"
 
       - name: Install support dependencies
         run: |
diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml
index e2a0142cc65..97f5f01e1b5 100644
--- a/.github/workflows/doc.yml
+++ b/.github/workflows/doc.yml
@@ -24,7 +24,9 @@ jobs:
       - uses: actions/checkout@v3
 
       - name: Set up latest Python
-        uses: actions/setup-python@v3
+        uses: actions/setup-python@v4
+        with:
+          python-version: "*"
 
       - name: Install dependencies
         run: |
diff --git a/.github/workflows/fuzz.yml b/.github/workflows/fuzz.yml
index d796fd50564..4ee6c839b48 100644
--- a/.github/workflows/fuzz.yml
+++ b/.github/workflows/fuzz.yml
@@ -24,7 +24,7 @@ jobs:
       - uses: actions/checkout@v3
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v3
+        uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
 
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index 01cf31502b1..fcfaa7885b1 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -17,7 +17,9 @@ jobs:
       - uses: actions/checkout@v3
 
       - name: Set up Python
-        uses: actions/setup-python@v3
+        uses: actions/setup-python@v4
+        with:
+          python-version: "*"
 
       - name: Install dependencies
         run: |
diff --git a/.github/workflows/pypi_upload.yml b/.github/workflows/pypi_upload.yml
index ef524a8ece6..cda215aa5d6 100644
--- a/.github/workflows/pypi_upload.yml
+++ b/.github/workflows/pypi_upload.yml
@@ -16,7 +16,9 @@ jobs:
       - uses: actions/checkout@v3
 
       - name: Set up Python
-        uses: actions/setup-python@v3
+        uses: actions/setup-python@v4
+        with:
+          python-version: "*"
 
       - name: Install latest pip, build, twine
         run: |
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index ce481761aea..b99f9ddaa68 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -31,7 +31,7 @@ jobs:
       - uses: actions/checkout@v3
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v3
+        uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
 
diff --git a/.github/workflows/upload_binary.yml b/.github/workflows/upload_binary.yml
index 6bb1d23306b..ed5ed961e67 100644
--- a/.github/workflows/upload_binary.yml
+++ b/.github/workflows/upload_binary.yml
@@ -34,7 +34,7 @@ jobs:
       - uses: actions/checkout@v3
 
       - name: Set up latest Python
-        uses: actions/setup-python@v3
+        uses: actions/setup-python@v4
         with:
           python-version: "*"
 
diff --git a/.github/workflows/uvloop_test.yml b/.github/workflows/uvloop_test.yml
index bbc39935f89..9f247826969 100644
--- a/.github/workflows/uvloop_test.yml
+++ b/.github/workflows/uvloop_test.yml
@@ -33,7 +33,9 @@ jobs:
       - uses: actions/checkout@v3
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v3
+        uses: actions/setup-python@v4
+        with:
+          python-version: "*"
 
       - name: Install latest pip
         run: |

From 6c1bd08f16b636de38b92aeb2e0a1e8ebef0a0b1 Mon Sep 17 00:00:00 2001
From: Sagi Shadur <saroad2@gmail.com>
Date: Tue, 14 Jun 2022 19:08:36 +0300
Subject: [PATCH 0551/1034] Test run black on self (#3114)

* Add run_self environment in tox

* Add run_self task as part of the lint CI flow

* Remove hard coded sources list

* Remove black from pre-commit

Co-authored-by: Cooper Lees <me@cooperlees.com>
---
 .github/workflows/lint.yml |  5 ++++
 .pre-commit-config.yaml    |  8 -------
 tests/test_format.py       | 48 +-------------------------------------
 tox.ini                    |  9 ++++++-
 4 files changed, 14 insertions(+), 56 deletions(-)

diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index fcfaa7885b1..1dd5ab5d35e 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -25,6 +25,11 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           python -m pip install -e '.[d]'
+          python -m pip install tox
 
       - name: Lint
         uses: pre-commit/action@v3.0.0
+
+      - name: Run On Self
+        run: |
+          tox -e run_self
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 26b7fe8c791..a6dedc44968 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -4,14 +4,6 @@ exclude: ^(src/blib2to3/|profiling/|tests/data/)
 repos:
   - repo: local
     hooks:
-      - id: black
-        name: black
-        language: system
-        entry: black
-        minimum_pre_commit_version: 2.9.2
-        require_serial: true
-        types_or: [python, pyi]
-
       - id: check-pre-commit-rev-in-example
         name: Check pre-commit rev in example
         language: python
diff --git a/tests/test_format.py b/tests/test_format.py
index a8a922d17db..0e1059c61e4 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -1,5 +1,5 @@
 from dataclasses import replace
-from typing import Any, Iterator, List
+from typing import Any, Iterator
 from unittest.mock import patch
 
 import pytest
@@ -14,47 +14,6 @@
     all_data_cases,
 )
 
-SOURCES: List[str] = [
-    "src/black/__init__.py",
-    "src/black/__main__.py",
-    "src/black/brackets.py",
-    "src/black/cache.py",
-    "src/black/comments.py",
-    "src/black/concurrency.py",
-    "src/black/const.py",
-    "src/black/debug.py",
-    "src/black/files.py",
-    "src/black/linegen.py",
-    "src/black/lines.py",
-    "src/black/mode.py",
-    "src/black/nodes.py",
-    "src/black/numerics.py",
-    "src/black/output.py",
-    "src/black/parsing.py",
-    "src/black/report.py",
-    "src/black/rusty.py",
-    "src/black/strings.py",
-    "src/black/trans.py",
-    "src/blackd/__init__.py",
-    "src/blib2to3/pygram.py",
-    "src/blib2to3/pytree.py",
-    "src/blib2to3/pgen2/conv.py",
-    "src/blib2to3/pgen2/driver.py",
-    "src/blib2to3/pgen2/grammar.py",
-    "src/blib2to3/pgen2/literals.py",
-    "src/blib2to3/pgen2/parse.py",
-    "src/blib2to3/pgen2/pgen.py",
-    "src/blib2to3/pgen2/tokenize.py",
-    "src/blib2to3/pgen2/token.py",
-    "setup.py",
-    "tests/test_black.py",
-    "tests/test_blackd.py",
-    "tests/test_format.py",
-    "tests/optional.py",
-    "tests/util.py",
-    "tests/conftest.py",
-]
-
 
 @pytest.fixture(autouse=True)
 def patch_dump_to_file(request: Any) -> Iterator[None]:
@@ -93,11 +52,6 @@ def test_preview_minimum_python_310_format(filename: str) -> None:
     assert_format(source, expected, mode, minimum_version=(3, 10))
 
 
-@pytest.mark.parametrize("filename", SOURCES)
-def test_source_is_formatted(filename: str) -> None:
-    check_file("", filename, DEFAULT_MODE, data=False)
-
-
 # =============== #
 # Complex cases
 # ============= #
diff --git a/tox.ini b/tox.ini
index 258e6c5c203..7af9e48d6f0 100644
--- a/tox.ini
+++ b/tox.ini
@@ -1,5 +1,5 @@
 [tox]
-envlist = {,ci-}py{36,37,38,39,310,py3},fuzz
+envlist = {,ci-}py{36,37,38,39,310,py3},fuzz,run_self
 
 [testenv]
 setenv = PYTHONPATH = {toxinidir}/src
@@ -61,3 +61,10 @@ commands =
     coverage erase
     coverage run fuzz.py
     coverage report
+
+[testenv:run_self]
+setenv = PYTHONPATH = {toxinidir}/src
+skip_install = True
+commands =
+    pip install -e .[d]
+    black --check {toxinidir}/src {toxinidir}/tests {toxinidir}/setup.py

From e3c9b0430eae5de35fdbeed047f9b2f07f9b78de Mon Sep 17 00:00:00 2001
From: Nate Prewitt <nate.prewitt@gmail.com>
Date: Fri, 17 Jun 2022 13:37:33 -0600
Subject: [PATCH 0552/1034] Replace link to Requests documentation (#3125)

---
 README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 1ffa7ef9522..624d4d755eb 100644
--- a/README.md
+++ b/README.md
@@ -166,8 +166,8 @@ Twisted and CPython:
 
 > At least the name is good.
 
-**Kenneth Reitz**, creator of [`requests`](http://python-requests.org/) and
-[`pipenv`](https://readthedocs.org/projects/pipenv/):
+**Kenneth Reitz**, creator of [`requests`](https://requests.readthedocs.io/en/latest/)
+and [`pipenv`](https://readthedocs.org/projects/pipenv/):
 
 > This vastly improves the formatting of our code. Thanks a ton!
 

From 6463fb874f6fd93d9a3b857e24987d5fa6ae0d57 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 20 Jun 2022 10:22:24 -0400
Subject: [PATCH 0553/1034] Bump sphinx from 5.0.1 to 5.0.2 in /docs (#3128)

Bumps [sphinx](https://github.com/sphinx-doc/sphinx) from 5.0.1 to 5.0.2.
- [Release notes](https://github.com/sphinx-doc/sphinx/releases)
- [Changelog](https://github.com/sphinx-doc/sphinx/blob/5.x/CHANGES)
- [Commits](https://github.com/sphinx-doc/sphinx/compare/v5.0.1...v5.0.2)

---
updated-dependencies:
- dependency-name: sphinx
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 docs/requirements.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index a3c801ba613..528af3dbffd 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,7 +1,7 @@
 # Used by ReadTheDocs; pinned requirements for stability.
 
 myst-parser==0.18.0
-Sphinx==5.0.1
+Sphinx==5.0.2
 # Older versions break Sphinx even though they're declared to be supported.
 docutils==0.18.1
 sphinxcontrib-programoutput==0.17

From fa6caa6ca8489103d22d23f8f4ae4d3569bb115e Mon Sep 17 00:00:00 2001
From: "Yilei \"Dolee\" Yang" <hi@mangoumbrella.com>
Date: Thu, 23 Jun 2022 12:41:05 -0700
Subject: [PATCH 0554/1034] Only call get_future_imports when needed (#3135)

---
 src/black/__init__.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index 4200066e882..2d04cf81910 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -1172,10 +1172,10 @@ def f(
 def _format_str_once(src_contents: str, *, mode: Mode) -> str:
     src_node = lib2to3_parse(src_contents.lstrip(), mode.target_versions)
     dst_contents = []
-    future_imports = get_future_imports(src_node)
     if mode.target_versions:
         versions = mode.target_versions
     else:
+        future_imports = get_future_imports(src_node)
         versions = detect_target_versions(src_node, future_imports=future_imports)
 
     normalize_fmt_off(src_node, preview=mode.preview)

From d848209d38cadaa060a023c223495e7874984ddc Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 27 Jun 2022 09:54:49 -0400
Subject: [PATCH 0555/1034] Bump furo from 2022.6.4.1 to 2022.6.21 in /docs
 (#3138)

Bumps [furo](https://github.com/pradyunsg/furo) from 2022.6.4.1 to 2022.6.21.
- [Release notes](https://github.com/pradyunsg/furo/releases)
- [Changelog](https://github.com/pradyunsg/furo/blob/main/docs/changelog.md)
- [Commits](https://github.com/pradyunsg/furo/compare/2022.06.04.1...2022.06.21)

---
updated-dependencies:
- dependency-name: furo
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 docs/requirements.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index 528af3dbffd..65387e05e7e 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -6,4 +6,4 @@ Sphinx==5.0.2
 docutils==0.18.1
 sphinxcontrib-programoutput==0.17
 sphinx_copybutton==0.5.0
-furo==2022.6.4.1
+furo==2022.6.21

From eb5d175c9cd3c14a0731f8afd0cc5a18264353e7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Felix=20Hild=C3=A9n?= <felix.hilden@gmail.com>
Date: Mon, 27 Jun 2022 23:24:34 +0300
Subject: [PATCH 0556/1034] Update preview style docs to include recent changes
 (#3136)

Covers GH-2926, GH-2990, GH-2991, and GH-3035.

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 docs/the_black_code_style/future_style.md | 60 ++++++++++++++++++++---
 1 file changed, 52 insertions(+), 8 deletions(-)

diff --git a/docs/the_black_code_style/future_style.md b/docs/the_black_code_style/future_style.md
index 8d159e9b0a2..fab4bca120e 100644
--- a/docs/the_black_code_style/future_style.md
+++ b/docs/the_black_code_style/future_style.md
@@ -50,27 +50,71 @@ limit. Line continuation backslashes are converted into parenthesized strings.
 Unnecessary parentheses are stripped. The stability and status of this feature is
 tracked in [this issue](https://github.com/psf/black/issues/2188).
 
-### Removing trailing newlines after code block open
+### Removing newlines in the beginning of code blocks
 
-_Black_ will remove trailing newlines after code block openings. That means that the
-following code:
+_Black_ will remove newlines in the beginning of new code blocks, i.e. when the
+indentation level is increased. For example:
 
 ```python
 def my_func():
 
     print("The line above me will be deleted!")
-
-    print("But the line above me won't!")
 ```
 
-Will be changed to:
+will be changed to:
 
 ```python
 def my_func():
     print("The line above me will be deleted!")
-
-    print("But the line above me won't!")
 ```
 
 This new feature will be applied to **all code blocks**: `def`, `class`, `if`, `for`,
 `while`, `with`, `case` and `match`.
+
+### Improved parentheses management
+
+_Black_ will format parentheses around return annotations similarly to other sets of
+parentheses. For example:
+
+```python
+def foo() -> (int):
+    ...
+
+def foo() -> looooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong:
+    ...
+```
+
+will be changed to:
+
+```python
+def foo() -> int:
+    ...
+
+
+def foo() -> (
+    looooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong
+):
+    ...
+```
+
+And, extra parentheses in `await` expressions and `with` statements are removed. For
+example:
+
+```python
+with ((open("bla.txt")) as f, open("x")):
+    ...
+
+async def main():
+    await (asyncio.sleep(1))
+```
+
+will be changed to:
+
+```python
+with open("bla.txt") as f, open("x"):
+    ...
+
+
+async def main():
+    await asyncio.sleep(1)
+```

From f6c139c5215ce04fd3e73a900f1372942d58eca0 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Mon, 27 Jun 2022 20:33:35 -0400
Subject: [PATCH 0557/1034] Prepare docs for release 22.6.0 (#3139)

---
 CHANGES.md                                  | 55 +++++++++++++--------
 docs/integrations/source_version_control.md |  9 ++--
 docs/usage_and_configuration/the_basics.md  |  2 +-
 3 files changed, 42 insertions(+), 24 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 7001271087a..b33ae6d509e 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -10,19 +10,10 @@
 
 <!-- Changes that affect Black's stable style -->
 
-- Fix unstable formatting involving `# fmt: skip` comments without internal spaces
-  (#2970)
-
 ### Preview style
 
 <!-- Changes that affect Black's preview style -->
 
-- Fixed bug where docstrings with triple quotes could exceed max line length (#3044)
-- Remove redundant parentheses around awaited objects (#2991)
-- Parentheses around return annotations are now managed (#2990)
-- Remove unnecessary parentheses from `with` statements (#2926)
-- Remove trailing newlines after code block open (#3035)
-
 ### _Blackd_
 
 <!-- Changes to blackd -->
@@ -40,18 +31,48 @@
 
 <!-- For example, Docker, GitHub Actions, pre-commit, editors -->
 
-- Add migrate-black.py script to ease migration to black formatted git project (#3038)
-
 ### Output
 
 <!-- Changes to Black's terminal output and error messages -->
 
-- Output python version and implementation as part of `--version` flag (#2997)
-
 ### Packaging
 
 <!-- Changes to how Black is packaged, such as dependency requirements -->
 
+### Parser
+
+<!-- Changes to the parser or to version autodetection -->
+
+### Performance
+
+<!-- Changes that improve Black's performance. -->
+
+## 22.6.0
+
+### Style
+
+- Fix unstable formatting involving `#fmt: skip` and `# fmt:skip` comments (notice the
+  lack of spaces) (#2970)
+
+### Preview style
+
+- Docstring quotes are no longer moved if it would violate the line length limit (#3044)
+- Parentheses around return annotations are now managed (#2990)
+- Remove unnecessary parentheses around awaited objects (#2991)
+- Remove unnecessary parentheses in `with` statements (#2926)
+- Remove trailing newlines after code block open (#3035)
+
+### Integrations
+
+- Add `scripts/migrate-black.py` script to ease introduction of Black to a Git project
+  (#3038)
+
+### Output
+
+- Output Python version and implementation as part of `--version` flag (#2997)
+
+### Packaging
+
 - Use `tomli` instead of `tomllib` on Python 3.11 builds where `tomllib` is not
   available (#2987)
 
@@ -62,15 +83,9 @@
 - [PEP 646](https://peps.python.org/pep-0646) syntax (for example,
   `Array[Batch, *Shape]` or `def fn(*args: *T) -> None`) is now supported (#3071)
 
-<!-- Changes to the parser or to version autodetection -->
-
-### Performance
-
-<!-- Changes that improve Black's performance. -->
-
 ### Vim Plugin
 
-- Fixed strtobool function. It didn't parse true/on/false/off. (#3025)
+- Fix `strtobool` function. It didn't parse true/on/false/off. (#3025)
 
 ## 22.3.0
 
diff --git a/docs/integrations/source_version_control.md b/docs/integrations/source_version_control.md
index d7d3da47630..e897cf669fc 100644
--- a/docs/integrations/source_version_control.md
+++ b/docs/integrations/source_version_control.md
@@ -7,7 +7,7 @@ Use [pre-commit](https://pre-commit.com/). Once you
 ```yaml
 repos:
   - repo: https://github.com/psf/black
-    rev: 22.3.0
+    rev: 22.6.0
     hooks:
       - id: black
         # It is recommended to specify the latest version of Python
@@ -23,8 +23,11 @@ branches or other mutable refs since the hook [won't auto update as you may
 expect][pre-commit-mutable-rev].
 
 If you want support for Jupyter Notebooks as well, then replace `id: black` with
-`id: black-jupyter` (though note that it's only available from version `21.8b0`
-onwards).
+`id: black-jupyter`.
+
+```{note}
+The `black-jupyter` hook is only available from version 21.8b0 and onwards.
+```
 
 [black-tags]: https://github.com/psf/black/tags
 [pre-commit-mutable-rev]:
diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index c7e2d4a4dde..7f76c57d3e6 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -173,7 +173,7 @@ You can check the version of _Black_ you have installed using the `--version` fl
 
 ```console
 $ black --version
-black, version 22.3.0
+black, version 22.6.0
 ```
 
 An option to require a specific version to be running is also provided.

From 6debce63bc2429b1680f8838592f2e56e3df6b27 Mon Sep 17 00:00:00 2001
From: Dimitri Merejkowsky <dmerejkowsky@users.noreply.github.com>
Date: Tue, 28 Jun 2022 09:44:55 +0200
Subject: [PATCH 0558/1034] Fix typo in CHANGES.md (#3142)

---
 CHANGES.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index b33ae6d509e..1d30045f48b 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -114,7 +114,7 @@
 
 ### Output
 
-- In verbose, mode, log when _Black_ is using user-level config (#2861)
+- In verbose mode, log when _Black_ is using user-level config (#2861)
 
 ### Packaging
 

From b859a377c0bef3793fcceb0efd0086862f6a9365 Mon Sep 17 00:00:00 2001
From: Jakub Kuczys <6032823+jack1142@users.noreply.github.com>
Date: Sun, 3 Jul 2022 22:47:18 +0200
Subject: [PATCH 0559/1034] Use RTD's new build process and config (#3149)

See the deprecation notice:
https://docs.readthedocs.io/en/stable/config-file/v2.html#python-version
---
 .readthedocs.yaml | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index 24eb3eaf6d9..fff2d6ed341 100644
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -3,8 +3,12 @@ version: 2
 formats:
   - htmlzip
 
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.8"
+
 python:
-  version: 3.8
   install:
     - requirements: docs/requirements.txt
 

From 7af77d1cf1fdeb54a45ddae422e1ebc3329129fa Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Wed, 6 Jul 2022 10:33:07 -0700
Subject: [PATCH 0560/1034] Stability policy: permit exceptional changes for
 unformatted code (#3155)

---
 CHANGES.md                         |  3 +++
 docs/the_black_code_style/index.md | 15 +++++++++------
 2 files changed, 12 insertions(+), 6 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 1d30045f48b..0bfa7ccd62c 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -27,6 +27,9 @@
 <!-- Major changes to documentation and policies. Small docs changes
      don't need a changelog entry. -->
 
+- Reword the stability policy to say that we may, in rare cases, make changes that
+  affect code that was not previously formatted by _Black_ (#3155)
+
 ### Integrations
 
 <!-- For example, Docker, GitHub Actions, pre-commit, editors -->
diff --git a/docs/the_black_code_style/index.md b/docs/the_black_code_style/index.md
index d1508552fee..c7f29af6c73 100644
--- a/docs/the_black_code_style/index.md
+++ b/docs/the_black_code_style/index.md
@@ -24,13 +24,16 @@ below. Ongoing style considerations are tracked on GitHub with the
 The following policy applies for the _Black_ code style, in non pre-release versions of
 _Black_:
 
-- The same code, formatted with the same options, will produce the same output for all
-  releases in a given calendar year.
+- If code has been formatted with _Black_, it will remain unchanged when formatted with
+  the same options using any other release in the same calendar year.
 
-  This means projects can safely use `black ~= 22.0` without worrying about major
-  formatting changes disrupting their project in 2022. We may still fix bugs where
-  _Black_ crashes on some code, and make other improvements that do not affect
-  formatting.
+  This means projects can safely use `black ~= 22.0` without worrying about formatting
+  changes disrupting their project in 2022. We may still fix bugs where _Black_ crashes
+  on some code, and make other improvements that do not affect formatting.
+
+  In rare cases, we may make changes affecting code that has not been previously
+  formatted with _Black_. For example, we have had bugs where we accidentally removed
+  some comments. Such bugs can be fixed without breaking the stability policy.
 
 - The first release in a new calendar year _may_ contain formatting changes, although
   these will be minimised as much as possible. This is to allow for improved formatting

From 05b63c4bccbfb292a92d3ec962ce9b8fa4ebcfd5 Mon Sep 17 00:00:00 2001
From: Maciej Olko <maciej.olko@affirm.com>
Date: Mon, 11 Jul 2022 18:27:51 +0200
Subject: [PATCH 0561/1034] Recommend using BlackConnect in IntelliJ IDEs
 (#3150)

* Recommend using BlackConnect in IntelliJ IDEs

* IntelliJ IDEs integration docs: improve formatting

* Add changelog for recommending BlackConnect

* IntelliJ IDEs integration docs: improve formatting

* Apply suggestions from code review

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>

* Fix indentation

* Apply italic to Black name

Consequently with other places in the document

* Move CHANGELOG entry to Unreleased section

* IntelliJ IDEs integration docs: bring back a point with formatting a file

* IntelliJ IDEs integration docs: fix extra whitespace and linebreak

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 CHANGES.md                   |  1 +
 docs/integrations/editors.md | 66 ++++++++++--------------------------
 2 files changed, 19 insertions(+), 48 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 0bfa7ccd62c..a0607edefa5 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -29,6 +29,7 @@
 
 - Reword the stability policy to say that we may, in rare cases, make changes that
   affect code that was not previously formatted by _Black_ (#3155)
+- Recommend using BlackConnect in IntelliJ IDEs (#3150)
 
 ### Integrations
 
diff --git a/docs/integrations/editors.md b/docs/integrations/editors.md
index 02baa29511b..07bf672f4fd 100644
--- a/docs/integrations/editors.md
+++ b/docs/integrations/editors.md
@@ -10,71 +10,41 @@ Options include the following:
 
 ## PyCharm/IntelliJ IDEA
 
-1. Install `black`.
+1. Install _Black_ with the `d` extra.
 
    ```console
-   $ pip install black
+   $ pip install 'black[d]'
    ```
 
-1. Locate your `black` installation folder.
+1. Install
+   [BlackConnect IntelliJ IDEs plugin](https://plugins.jetbrains.com/plugin/14321-blackconnect).
 
-   On macOS / Linux / BSD:
-
-   ```console
-   $ which black
-   /usr/local/bin/black  # possible location
-   ```
-
-   On Windows:
-
-   ```console
-   $ where black
-   %LocalAppData%\Programs\Python\Python36-32\Scripts\black.exe  # possible location
-   ```
-
-   Note that if you are using a virtual environment detected by PyCharm, this is an
-   unneeded step. In this case the path to `black` is `$PyInterpreterDirectory$/black`.
-
-1. Open External tools in PyCharm/IntelliJ IDEA
+1. Open plugin configuration in PyCharm/IntelliJ IDEA
 
    On macOS:
 
-   `PyCharm -> Preferences -> Tools -> External Tools`
+   `PyCharm -> Preferences -> Tools -> BlackConnect`
 
    On Windows / Linux / BSD:
 
-   `File -> Settings -> Tools -> External Tools`
-
-1. Click the + icon to add a new external tool with the following values:
+   `File -> Settings -> Tools -> BlackConnect`
 
-   - Name: Black
-   - Description: Black is the uncompromising Python code formatter.
-   - Program: \<install_location_from_step_2>
-   - Arguments: `"$FilePath$"`
+1. In `Local Instance (shared between projects)` section:
 
-1. Format the currently opened file by selecting `Tools -> External Tools -> black`.
+   1. Check `Start local blackd instance when plugin loads`.
+   1. Press the `Detect` button near `Path` input. The plugin should detect the `blackd`
+      executable.
 
-   - Alternatively, you can set a keyboard shortcut by navigating to
-     `Preferences or Settings -> Keymap -> External Tools -> External Tools - Black`.
+1. In `Trigger Settings` section check `Trigger on code reformat` to enable code
+   reformatting with _Black_.
 
-1. Optionally, run _Black_ on every file save:
+1. Format the currently opened file by selecting `Code -> Reformat Code` or using a
+   shortcut.
 
-   1. Make sure you have the
-      [File Watchers](https://plugins.jetbrains.com/plugin/7177-file-watchers) plugin
-      installed.
-   1. Go to `Preferences or Settings -> Tools -> File Watchers` and click `+` to add a
-      new watcher:
-      - Name: Black
-      - File type: Python
-      - Scope: Project Files
-      - Program: \<install_location_from_step_2>
-      - Arguments: `$FilePath$`
-      - Output paths to refresh: `$FilePath$`
-      - Working directory: `$ProjectFileDir$`
+1. Optionally, to run _Black_ on every file save:
 
-   - In Advanced Options
-     - Uncheck "Auto-save edited files to trigger the watcher"
-     - Uncheck "Trigger the watcher on external changes"
+   - In `Trigger Settings` section of plugin configuration check
+     `Trigger when saving changed files`.
 
 ## Wing IDE
 

From 18c17bea757dc88d0b6d2be6e99a4ebcc18e288c Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Wed, 13 Jul 2022 20:02:51 -0400
Subject: [PATCH 0562/1034] Copy over comments when hugging power ops  (#2874)

Otherwise they'd be deleted which was a regression in 22.1.0 (oops! my
bad!). Also type comments are now tracked in the AST safety check on all
compatible platforms to error out if this happens again.

Overall the line rewriting code has been rewritten to do "the right
thing (tm)", I hope this fixes other potential bugs in the code (fwiw I
got to drop the bugfix in blib2to3.pytree.Leaf.clone since now bracket
metadata is properly copied over).

Fixes #2873
---
 CHANGES.md                                  |  7 ++++++
 src/black/parsing.py                        | 20 ++++++++++-----
 src/black/trans.py                          | 22 +++++++---------
 src/blib2to3/pytree.py                      |  1 -
 tests/data/simple_cases/power_op_spacing.py | 28 +++++++++++++++++++++
 5 files changed, 58 insertions(+), 20 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index a0607edefa5..249f7752bea 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -10,6 +10,9 @@
 
 <!-- Changes that affect Black's stable style -->
 
+- Comments are no longer deleted when a line had spaces removed around power operators
+  (#2874)
+
 ### Preview style
 
 <!-- Changes that affect Black's preview style -->
@@ -47,6 +50,10 @@
 
 <!-- Changes to the parser or to version autodetection -->
 
+- Type comments are now included in the AST equivalence check consistently so accidental
+  deletion raises an error. Though type comments can't be tracked when running on PyPy
+  3.7 due to standard library limitations. (#2874)
+
 ### Performance
 
 <!-- Changes that improve Black's performance. -->
diff --git a/src/black/parsing.py b/src/black/parsing.py
index 12726567948..d1ad7d2c671 100644
--- a/src/black/parsing.py
+++ b/src/black/parsing.py
@@ -152,14 +152,22 @@ def parse_single_version(
     src: str, version: Tuple[int, int]
 ) -> Union[ast.AST, ast3.AST]:
     filename = "<unknown>"
-    # typed_ast is needed because of feature version limitations in the builtin ast
+    # typed-ast is needed because of feature version limitations in the builtin ast 3.8>
     if sys.version_info >= (3, 8) and version >= (3,):
-        return ast.parse(src, filename, feature_version=version)
-    elif version >= (3,):
-        if _IS_PYPY:
-            return ast3.parse(src, filename)
+        return ast.parse(src, filename, feature_version=version, type_comments=True)
+
+    if _IS_PYPY:
+        # PyPy 3.7 doesn't support type comment tracking which is not ideal, but there's
+        # not much we can do as typed-ast won't work either.
+        if sys.version_info >= (3, 8):
+            return ast3.parse(src, filename, type_comments=True)
         else:
-            return ast3.parse(src, filename, feature_version=version[1])
+            return ast3.parse(src, filename)
+    else:
+        # Typed-ast is guaranteed to be used here and automatically tracks type
+        # comments separately.
+        return ast3.parse(src, filename, feature_version=version[1])
+
     raise AssertionError("INTERNAL ERROR: Tried parsing unsupported Python version!")
 
 
diff --git a/src/black/trans.py b/src/black/trans.py
index 01aa80eaaf8..28d9250adc1 100644
--- a/src/black/trans.py
+++ b/src/black/trans.py
@@ -121,7 +121,7 @@ def is_simple_operand(index: int, kind: Literal["base", "exponent"]) -> bool:
 
         return False
 
-    leaves: List[Leaf] = []
+    new_line = line.clone()
     should_hug = False
     for idx, leaf in enumerate(line.leaves):
         new_leaf = leaf.clone()
@@ -139,18 +139,14 @@ def is_simple_operand(index: int, kind: Literal["base", "exponent"]) -> bool:
         if should_hug:
             new_leaf.prefix = ""
 
-        leaves.append(new_leaf)
-
-    yield Line(
-        mode=line.mode,
-        depth=line.depth,
-        leaves=leaves,
-        comments=line.comments,
-        bracket_tracker=line.bracket_tracker,
-        inside_brackets=line.inside_brackets,
-        should_split_rhs=line.should_split_rhs,
-        magic_trailing_comma=line.magic_trailing_comma,
-    )
+        # We have to be careful to make a new line properly:
+        # - bracket related metadata must be maintained (handled by Line.append)
+        # - comments need to copied over, updating the leaf IDs they're attached to
+        new_line.append(new_leaf, preformatted=True)
+        for comment_leaf in line.comments_after(leaf):
+            new_line.append(comment_leaf, preformatted=True)
+
+    yield new_line
 
 
 class StringTransformer(ABC):
diff --git a/src/blib2to3/pytree.py b/src/blib2to3/pytree.py
index b203ce5b2ac..10b4690218e 100644
--- a/src/blib2to3/pytree.py
+++ b/src/blib2to3/pytree.py
@@ -451,7 +451,6 @@ def clone(self) -> "Leaf":
             self.value,
             (self.prefix, (self.lineno, self.column)),
             fixers_applied=self.fixers_applied,
-            opening_bracket=self.opening_bracket,
         )
 
     def leaves(self) -> Iterator["Leaf"]:
diff --git a/tests/data/simple_cases/power_op_spacing.py b/tests/data/simple_cases/power_op_spacing.py
index 87dde7f39dc..c95fa788fc3 100644
--- a/tests/data/simple_cases/power_op_spacing.py
+++ b/tests/data/simple_cases/power_op_spacing.py
@@ -49,6 +49,20 @@ def function_dont_replace_spaces():
 q = [10.5**i for i in range(6)]
 
 
+# WE SHOULD DEFINITELY NOT EAT THESE COMMENTS (https://github.com/psf/black/issues/2873)
+if hasattr(view, "sum_of_weights"):
+    return np.divide(  # type: ignore[no-any-return]
+        view.variance,  # type: ignore[union-attr]
+        view.sum_of_weights,  # type: ignore[union-attr]
+        out=np.full(view.sum_of_weights.shape, np.nan),  # type: ignore[union-attr]
+        where=view.sum_of_weights**2 > view.sum_of_weights_squared,  # type: ignore[union-attr]
+    )
+
+return np.divide(
+    where=view.sum_of_weights_of_weight_long**2 > view.sum_of_weights_squared,  # type: ignore
+)
+
+
 # output
 
 
@@ -101,3 +115,17 @@ def function_dont_replace_spaces():
 o = settings(max_examples=10**6.0)
 p = {(k, k**2): v**2.0 for k, v in pairs}
 q = [10.5**i for i in range(6)]
+
+
+# WE SHOULD DEFINITELY NOT EAT THESE COMMENTS (https://github.com/psf/black/issues/2873)
+if hasattr(view, "sum_of_weights"):
+    return np.divide(  # type: ignore[no-any-return]
+        view.variance,  # type: ignore[union-attr]
+        view.sum_of_weights,  # type: ignore[union-attr]
+        out=np.full(view.sum_of_weights.shape, np.nan),  # type: ignore[union-attr]
+        where=view.sum_of_weights**2 > view.sum_of_weights_squared,  # type: ignore[union-attr]
+    )
+
+return np.divide(
+    where=view.sum_of_weights_of_weight_long**2 > view.sum_of_weights_squared,  # type: ignore
+)

From 4f0532d6f0d030799223453195069a282e111c8b Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Wed, 13 Jul 2022 22:26:05 -0400
Subject: [PATCH 0563/1034] Don't (ever) put a single-char closing docstring
 quote on a new line (#3166)

Doing so is invalid. Note this only fixes the preview style since the
logic putting closing docstring quotes on their own line if they violate
the line length limit is quite new.

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 CHANGES.md                              |  3 +++
 src/black/linegen.py                    |  7 ++++---
 tests/data/preview/docstring_preview.py | 16 ++++++++++++++++
 3 files changed, 23 insertions(+), 3 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 249f7752bea..09954f2b738 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -17,6 +17,9 @@
 
 <!-- Changes that affect Black's preview style -->
 
+- Single-character closing docstring quotes are no longer moved to their own line as
+  this is invalid. This was a bug introduced in version 22.6.0. (#3166)
+
 ### _Blackd_
 
 <!-- Changes to blackd -->
diff --git a/src/black/linegen.py b/src/black/linegen.py
index ff54e05c4e6..20f3ac6fffb 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -330,13 +330,14 @@ def visit_STRING(self, leaf: Leaf) -> Iterator[Line]:
             # We could enforce triple quotes at this point.
             quote = quote_char * quote_len
 
-            if Preview.long_docstring_quotes_on_newline in self.mode:
+            # It's invalid to put closing single-character quotes on a new line.
+            if Preview.long_docstring_quotes_on_newline in self.mode and quote_len == 3:
                 # We need to find the length of the last line of the docstring
                 # to find if we can add the closing quotes to the line without
                 # exceeding the maximum line length.
                 # If docstring is one line, then we need to add the length
-                # of the indent, prefix, and starting quotes. Ending quote are
-                # handled later
+                # of the indent, prefix, and starting quotes. Ending quotes are
+                # handled later.
                 lines = docstring.splitlines()
                 last_line_length = len(lines[-1]) if docstring else 0
 
diff --git a/tests/data/preview/docstring_preview.py b/tests/data/preview/docstring_preview.py
index 2da4cd1acdb..292352c82f3 100644
--- a/tests/data/preview/docstring_preview.py
+++ b/tests/data/preview/docstring_preview.py
@@ -42,6 +42,14 @@ def multiline_docstring_at_line_limit_with_prefix():
     second line----------------------------------------------------------------------"""
 
 
+def single_quote_docstring_over_line_limit():
+    "We do not want to put the closing quote on a new line as that is invalid (see GH-3141)."
+
+
+def single_quote_docstring_over_line_limit2():
+    'We do not want to put the closing quote on a new line as that is invalid (see GH-3141).'
+
+
 # output
 
 
@@ -87,3 +95,11 @@ def multiline_docstring_at_line_limit_with_prefix():
     f"""first line----------------------------------------------------------------------
 
     second line----------------------------------------------------------------------"""
+
+
+def single_quote_docstring_over_line_limit():
+    "We do not want to put the closing quote on a new line as that is invalid (see GH-3141)."
+
+
+def single_quote_docstring_over_line_limit2():
+    "We do not want to put the closing quote on a new line as that is invalid (see GH-3141)."

From 8900e3ac8a8f610d4c1b3fbe7bdf4f0358efc28d Mon Sep 17 00:00:00 2001
From: Nimrod <87605179+Panther-12@users.noreply.github.com>
Date: Thu, 14 Jul 2022 22:22:29 +0300
Subject: [PATCH 0564/1034] Add warning to not run blackd publicly in docs
 (#3167)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 docs/usage_and_configuration/black_as_a_server.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/docs/usage_and_configuration/black_as_a_server.md b/docs/usage_and_configuration/black_as_a_server.md
index 7d07e94e6bb..fc9d1cab716 100644
--- a/docs/usage_and_configuration/black_as_a_server.md
+++ b/docs/usage_and_configuration/black_as_a_server.md
@@ -4,6 +4,11 @@
 protocol. The main benefit of using it is to avoid the cost of starting up a new _Black_
 process every time you want to blacken a file.
 
+```{warning}
+`blackd` should not be run as a publicly accessible server as there are no security
+precautions in place to prevent abuse. **It is intended for local use only**.
+```
+
 ## Usage
 
 `blackd` is not packaged alongside _Black_ by default because it has additional

From 9aa33f467bafce081635ce88807d42b10b0a3105 Mon Sep 17 00:00:00 2001
From: Cooper Lees <cooper@fb.com>
Date: Thu, 14 Jul 2022 15:24:34 -0700
Subject: [PATCH 0565/1034] Move to explicitly creating a new loop (#3164)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Move to explicitly creating a new loop

- >= 3.10 add a warning that `get_event_loop` will not automatically create a loop
- Move to explicit API

Test:
- `python3.11 -m venv --upgrade-deps /tmp/tb`
  - `/tmp/tb/bin/pip install -e .`
  - Install deps and no blackd as aiohttp + yarl can't build still with 3.11
  - https://github.com/aio-libs/aiohttp/issues/6600
- `export PYTHONWARNINGS=error`
```
cooper@l33t:~/repos/black$ /tmp/tb/bin/black .
All done! ✨ 🍰 ✨
44 files left unchanged.
```

Fixes #3110

* Add to CHANGES.md

* Fix a cooper typo yet again

* Set default asyncio loop to our explicitly created one + unset on exit

* Update CHANGES.md

Fix my silly typo.

Co-authored-by: Thomas Grainger <tagrain@gmail.com>

Co-authored-by: Cooper Ry Lees <me@wcooperlees.com>
Co-authored-by: Thomas Grainger <tagrain@gmail.com>
---
 CHANGES.md            | 3 +++
 src/black/__init__.py | 8 ++++++--
 2 files changed, 9 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 09954f2b738..7d2e0bc09d1 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -45,6 +45,9 @@
 
 <!-- Changes to Black's terminal output and error messages -->
 
+- Change from deprecated `asyncio.get_event_loop()` to create our event loop which
+  removes DeprecationWarning (#3164)
+
 ### Packaging
 
 <!-- Changes to how Black is packaged, such as dependency requirements -->
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 2d04cf81910..d2df1cbee7c 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -773,7 +773,6 @@ def reformat_many(
     from concurrent.futures import Executor, ThreadPoolExecutor, ProcessPoolExecutor
 
     executor: Executor
-    loop = asyncio.get_event_loop()
     worker_count = workers if workers is not None else DEFAULT_WORKERS
     if sys.platform == "win32":
         # Work around https://bugs.python.org/issue26903
@@ -788,6 +787,8 @@ def reformat_many(
         # any good due to the Global Interpreter Lock)
         executor = ThreadPoolExecutor(max_workers=1)
 
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
     try:
         loop.run_until_complete(
             schedule_formatting(
@@ -801,7 +802,10 @@ def reformat_many(
             )
         )
     finally:
-        shutdown(loop)
+        try:
+            shutdown(loop)
+        finally:
+            asyncio.set_event_loop(None)
         if executor is not None:
             executor.shutdown()
 

From ad5c315ddad26a3c41f22d3b73c493fb7d7b86b8 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Thu, 14 Jul 2022 19:47:33 -0400
Subject: [PATCH 0566/1034] Actually disable docstring prefix normalization
 with -S + fix instability (#3168)

The former was a regression I introduced a long time ago. To avoid
changing the stable style too much, the regression is only fixed if
--preview is enabled

Annoyingly enough, as we currently always enforce a second format pass if
changes were made, there's no good way to prove the existence of the
docstring quote normalization instability issue. For posterity, here's
one failing example:

    --- source
    +++ first pass
    @@ -1,7 +1,7 @@
     def some_function(self):
    -    ''''<text here>
    +    """ '<text here>

         <text here, since without another non-empty line black is stable>

    -    '''
    +    """
         pass
    --- first pass
    +++ second pass
    @@ -1,7 +1,7 @@
     def some_function(self):
    -    """ '<text here>
    +    """'<text here>

         <text here, since without another non-empty line black is stable>

         """
         pass

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 CHANGES.md                                    |  2 ++
 src/black/linegen.py                          | 19 ++++++++++++++++++-
 src/black/mode.py                             |  7 ++++---
 ...cstring_preview_no_string_normalization.py | 10 ++++++++++
 tests/data/simple_cases/docstring.py          | 14 ++++++++++++++
 tests/test_format.py                          | 12 ++++++++++++
 6 files changed, 60 insertions(+), 4 deletions(-)
 create mode 100644 tests/data/miscellaneous/docstring_preview_no_string_normalization.py

diff --git a/CHANGES.md b/CHANGES.md
index 7d2e0bc09d1..8543a8dbfe0 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -19,6 +19,8 @@
 
 - Single-character closing docstring quotes are no longer moved to their own line as
   this is invalid. This was a bug introduced in version 22.6.0. (#3166)
+- `--skip-string-normalization` / `-S` now prevents docstring prefixes from being
+  normalized as expected (#3168)
 
 ### _Blackd_
 
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 20f3ac6fffb..1f132b7888f 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -293,7 +293,24 @@ def visit_STRING(self, leaf: Leaf) -> Iterator[Line]:
         if is_docstring(leaf) and "\\\n" not in leaf.value:
             # We're ignoring docstrings with backslash newline escapes because changing
             # indentation of those changes the AST representation of the code.
-            docstring = normalize_string_prefix(leaf.value)
+            if Preview.normalize_docstring_quotes_and_prefixes_properly in self.mode:
+                # There was a bug where --skip-string-normalization wouldn't stop us
+                # from normalizing docstring prefixes. To maintain stability, we can
+                # only address this buggy behaviour while the preview style is enabled.
+                if self.mode.string_normalization:
+                    docstring = normalize_string_prefix(leaf.value)
+                    # visit_default() does handle string normalization for us, but
+                    # since this method acts differently depending on quote style (ex.
+                    # see padding logic below), there's a possibility for unstable
+                    # formatting as visit_default() is called *after*. To avoid a
+                    # situation where this function formats a docstring differently on
+                    # the second pass, normalize it early.
+                    docstring = normalize_string_quotes(docstring)
+                else:
+                    docstring = leaf.value
+            else:
+                # ... otherwise, we'll keep the buggy behaviour >.<
+                docstring = normalize_string_prefix(leaf.value)
             prefix = get_string_prefix(docstring)
             docstring = docstring[len(prefix) :]  # Remove the prefix
             quote_char = docstring[0]
diff --git a/src/black/mode.py b/src/black/mode.py
index 896c516df79..b7359fab213 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -145,12 +145,13 @@ def supports_feature(target_versions: Set[TargetVersion], feature: Feature) -> b
 class Preview(Enum):
     """Individual preview style features."""
 
-    string_processing = auto()
-    remove_redundant_parens = auto()
-    one_element_subscript = auto()
     annotation_parens = auto()
     long_docstring_quotes_on_newline = auto()
+    normalize_docstring_quotes_and_prefixes_properly = auto()
+    one_element_subscript = auto()
     remove_block_trailing_newline = auto()
+    remove_redundant_parens = auto()
+    string_processing = auto()
 
 
 class Deprecated(UserWarning):
diff --git a/tests/data/miscellaneous/docstring_preview_no_string_normalization.py b/tests/data/miscellaneous/docstring_preview_no_string_normalization.py
new file mode 100644
index 00000000000..0957231eb9c
--- /dev/null
+++ b/tests/data/miscellaneous/docstring_preview_no_string_normalization.py
@@ -0,0 +1,10 @@
+def do_not_touch_this_prefix():
+    R"""There was a bug where docstring prefixes would be normalized even with -S."""
+
+
+def do_not_touch_this_prefix2():
+    F'There was a bug where docstring prefixes would be normalized even with -S.'
+
+
+def do_not_touch_this_prefix3():
+    uR'''There was a bug where docstring prefixes would be normalized even with -S.'''
diff --git a/tests/data/simple_cases/docstring.py b/tests/data/simple_cases/docstring.py
index 7153be468c1..f08bba575fe 100644
--- a/tests/data/simple_cases/docstring.py
+++ b/tests/data/simple_cases/docstring.py
@@ -209,6 +209,13 @@ def multiline_docstring_at_line_limit():
     second line----------------------------------------------------------------------"""
 
 
+def stable_quote_normalization_with_immediate_inner_single_quote(self):
+    ''''<text here>
+
+    <text here, since without another non-empty line black is stable>
+    '''
+
+
 # output
 
 class MyClass:
@@ -417,3 +424,10 @@ def multiline_docstring_at_line_limit():
     """first line-----------------------------------------------------------------------
 
     second line----------------------------------------------------------------------"""
+
+
+def stable_quote_normalization_with_immediate_inner_single_quote(self):
+    """'<text here>
+
+    <text here, since without another non-empty line black is stable>
+    """
diff --git a/tests/test_format.py b/tests/test_format.py
index 0e1059c61e4..86339f24b86 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -139,6 +139,18 @@ def test_docstring_no_string_normalization() -> None:
     assert_format(source, expected, mode)
 
 
+def test_preview_docstring_no_string_normalization() -> None:
+    """
+    Like test_docstring but with string normalization off *and* the preview style
+    enabled.
+    """
+    source, expected = read_data(
+        "miscellaneous", "docstring_preview_no_string_normalization"
+    )
+    mode = replace(DEFAULT_MODE, string_normalization=False, preview=True)
+    assert_format(source, expected, mode)
+
+
 def test_long_strings_flag_disabled() -> None:
     """Tests for turning off the string processing logic."""
     source, expected = read_data("miscellaneous", "long_strings_flag_disabled")

From b0eed7c6bd5f04f0ea6b6592d8a3ab63d8a01252 Mon Sep 17 00:00:00 2001
From: onescriptkid <onescriptkid@gmail.com>
Date: Thu, 14 Jul 2022 16:51:18 -0700
Subject: [PATCH 0567/1034] Fix typo in config docs for --extend-exclude
 (#3170)

The old regex in the example was invalid and caused an error on startup.
---
 docs/usage_and_configuration/the_basics.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index 7f76c57d3e6..4c358742674 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -265,7 +265,7 @@ extend-exclude = '''
 # in the root of the project.
 (
   ^/foo.py    # exclude a file named foo.py in the root of the project
-  | *_pb2.py  # exclude autogenerated Protocol Buffer files anywhere in the project
+  | .*_pb2.py  # exclude autogenerated Protocol Buffer files anywhere in the project
 )
 '''
 ```

From df5a87d93bd81c719a9c3f21da84133eaceef7b3 Mon Sep 17 00:00:00 2001
From: Thomas Grainger <tagrain@gmail.com>
Date: Sat, 16 Jul 2022 13:18:55 +0100
Subject: [PATCH 0568/1034] configure strict pytest and
 filterwarnings=['error', ... (#3173)

* configure strict pytest

* ignore current warnings
---
 pyproject.toml | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/pyproject.toml b/pyproject.toml
index d9373740a5c..8b4b4ba7c0c 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -31,6 +31,7 @@ build-backend = "setuptools.build_meta"
 
 [tool.pytest.ini_options]
 # Option below requires `tests/optional.py`
+addopts = "--strict-config --strict-markers"
 optional-tests = [
   "no_blackd: run when `d` extra NOT installed",
   "no_jupyter: run when `jupyter` extra NOT installed",
@@ -38,3 +39,10 @@ optional-tests = [
 markers = [
   "incompatible_with_mypyc: run when testing mypyc compiled black"
 ]
+xfail_strict = true
+filterwarnings = [
+    "error",
+    '''ignore:Decorator `@unittest_run_loop` is no longer needed in aiohttp 3\.8\+:DeprecationWarning''',
+    '''ignore:Bare functions are deprecated, use async ones:DeprecationWarning''',
+    '''ignore:invalid escape sequence.*:DeprecationWarning''',
+]

From 33f0d9e79a098442135478b07b182a966f60375e Mon Sep 17 00:00:00 2001
From: Thomas Grainger <tagrain@gmail.com>
Date: Sun, 17 Jul 2022 02:55:46 +0100
Subject: [PATCH 0569/1034] Add pypy-3.8 to test matrix (#3174)

---
 .github/workflows/test.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index b99f9ddaa68..7b4716c5493 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -24,7 +24,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.6", "3.7", "3.8", "3.9", "3.10", "pypy-3.7"]
+        python-version: ["3.6", "3.7", "3.8", "3.9", "3.10", "pypy-3.7", "pypy-3.8"]
         os: [ubuntu-latest, macOS-latest, windows-latest]
 
     steps:

From 1b6de7b0a33b568f71ff86e0e5fef6d4c479c2b7 Mon Sep 17 00:00:00 2001
From: Thomas Grainger <tagrain@gmail.com>
Date: Tue, 19 Jul 2022 03:17:13 +0100
Subject: [PATCH 0570/1034] Improve warning filtering in tests (#3175)

---
 pyproject.toml       | 5 ++++-
 tests/test_format.py | 2 ++
 2 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/pyproject.toml b/pyproject.toml
index 8b4b4ba7c0c..6df037c8a39 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -42,7 +42,10 @@ markers = [
 xfail_strict = true
 filterwarnings = [
     "error",
+    # this is mitigated by a try/catch in https://github.com/psf/black/pull/2974/
+    # this ignore can be removed when support for aiohttp 3.7 is dropped.
     '''ignore:Decorator `@unittest_run_loop` is no longer needed in aiohttp 3\.8\+:DeprecationWarning''',
+    # this is mitigated by https://github.com/python/cpython/issues/79071 in python 3.8+
+    # this ignore can be removed when support for 3.7 is dropped.
     '''ignore:Bare functions are deprecated, use async ones:DeprecationWarning''',
-    '''ignore:invalid escape sequence.*:DeprecationWarning''',
 ]
diff --git a/tests/test_format.py b/tests/test_format.py
index 86339f24b86..7a099fb9f33 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -28,6 +28,7 @@ def check_file(
     assert_format(source, expected, mode, fast=False)
 
 
+@pytest.mark.filterwarnings("ignore:invalid escape sequence.*:DeprecationWarning")
 @pytest.mark.parametrize("filename", all_data_cases("simple_cases"))
 def test_simple_format(filename: str) -> None:
     check_file("simple_cases", filename, DEFAULT_MODE)
@@ -132,6 +133,7 @@ def test_python_2_hint() -> None:
     exc_info.match(black.parsing.PY2_HINT)
 
 
+@pytest.mark.filterwarnings("ignore:invalid escape sequence.*:DeprecationWarning")
 def test_docstring_no_string_normalization() -> None:
     """Like test_docstring but with string normalization off."""
     source, expected = read_data("miscellaneous", "docstring_no_string_normalization")

From 6ea4eddf936e88c24a6757c0c858812d5ca1a9c6 Mon Sep 17 00:00:00 2001
From: "Yilei \"Dolee\" Yang" <yileiyang@google.com>
Date: Tue, 19 Jul 2022 14:26:11 -0700
Subject: [PATCH 0571/1034] Fix the handling of `# fmt: skip` when it's at a
 colon line (#3148)

When the Leaf node with `# fmt: skip` is a NEWLINE inside a `suite`
Node, the nodes to ignore should be from the siblings of the parent
`suite` Node.

There is a also a special case for the ASYNC token, where it expands
to the grandparent Node where the ASYNC token is.

This fixes GH-2646, GH-3126, GH-2680, GH-2421, GH-2339, and GH-2138.
---
 CHANGES.md                          |  1 +
 src/black/comments.py               | 74 +++++++++++++++++++++--------
 src/black/linegen.py                |  4 +-
 tests/data/simple_cases/fmtskip8.py | 62 ++++++++++++++++++++++++
 4 files changed, 120 insertions(+), 21 deletions(-)
 create mode 100644 tests/data/simple_cases/fmtskip8.py

diff --git a/CHANGES.md b/CHANGES.md
index 8543a8dbfe0..90c62de6b98 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -10,6 +10,7 @@
 
 <!-- Changes that affect Black's stable style -->
 
+- Fix incorrect handling of `# fmt: skip` on colon `:` lines. (#3148)
 - Comments are no longer deleted when a line had spaces removed around power operators
   (#2874)
 
diff --git a/src/black/comments.py b/src/black/comments.py
index 23bf87fca7c..522c1a7b88c 100644
--- a/src/black/comments.py
+++ b/src/black/comments.py
@@ -9,7 +9,7 @@
 else:
     from typing_extensions import Final
 
-from blib2to3.pytree import Node, Leaf
+from blib2to3.pytree import Node, Leaf, type_repr
 from blib2to3.pgen2 import token
 
 from black.nodes import first_leaf_column, preceding_leaf, container_of
@@ -174,6 +174,11 @@ def convert_one_fmt_off_pair(node: Node, *, preview: bool) -> bool:
                 first.prefix = prefix[comment.consumed :]
             if comment.value in FMT_SKIP:
                 first.prefix = ""
+                standalone_comment_prefix = prefix
+            else:
+                standalone_comment_prefix = (
+                    prefix[:previous_consumed] + "\n" * comment.newlines
+                )
             hidden_value = "".join(str(n) for n in ignored_nodes)
             if comment.value in FMT_OFF:
                 hidden_value = comment.value + "\n" + hidden_value
@@ -195,7 +200,7 @@ def convert_one_fmt_off_pair(node: Node, *, preview: bool) -> bool:
                 Leaf(
                     STANDALONE_COMMENT,
                     hidden_value,
-                    prefix=prefix[:previous_consumed] + "\n" * comment.newlines,
+                    prefix=standalone_comment_prefix,
                 ),
             )
             return True
@@ -211,26 +216,10 @@ def generate_ignored_nodes(
     If comment is skip, returns leaf only.
     Stops at the end of the block.
     """
-    container: Optional[LN] = container_of(leaf)
     if comment.value in FMT_SKIP:
-        prev_sibling = leaf.prev_sibling
-        # Need to properly format the leaf prefix to compare it to comment.value,
-        # which is also formatted
-        comments = list_comments(leaf.prefix, is_endmarker=False, preview=preview)
-        if comments and comment.value == comments[0].value and prev_sibling is not None:
-            leaf.prefix = ""
-            siblings = [prev_sibling]
-            while (
-                "\n" not in prev_sibling.prefix
-                and prev_sibling.prev_sibling is not None
-            ):
-                prev_sibling = prev_sibling.prev_sibling
-                siblings.insert(0, prev_sibling)
-            for sibling in siblings:
-                yield sibling
-        elif leaf.parent is not None:
-            yield leaf.parent
+        yield from _generate_ignored_nodes_from_fmt_skip(leaf, comment, preview=preview)
         return
+    container: Optional[LN] = container_of(leaf)
     while container is not None and container.type != token.ENDMARKER:
         if is_fmt_on(container, preview=preview):
             return
@@ -246,6 +235,51 @@ def generate_ignored_nodes(
             container = container.next_sibling
 
 
+def _generate_ignored_nodes_from_fmt_skip(
+    leaf: Leaf, comment: ProtoComment, *, preview: bool
+) -> Iterator[LN]:
+    """Generate all leaves that should be ignored by the `# fmt: skip` from `leaf`."""
+    prev_sibling = leaf.prev_sibling
+    parent = leaf.parent
+    # Need to properly format the leaf prefix to compare it to comment.value,
+    # which is also formatted
+    comments = list_comments(leaf.prefix, is_endmarker=False, preview=preview)
+    if not comments or comment.value != comments[0].value:
+        return
+    if prev_sibling is not None:
+        leaf.prefix = ""
+        siblings = [prev_sibling]
+        while "\n" not in prev_sibling.prefix and prev_sibling.prev_sibling is not None:
+            prev_sibling = prev_sibling.prev_sibling
+            siblings.insert(0, prev_sibling)
+        for sibling in siblings:
+            yield sibling
+    elif (
+        parent is not None
+        and type_repr(parent.type) == "suite"
+        and leaf.type == token.NEWLINE
+    ):
+        # The `# fmt: skip` is on the colon line of the if/while/def/class/...
+        # statements. The ignored nodes should be previous siblings of the
+        # parent suite node.
+        leaf.prefix = ""
+        ignored_nodes: List[LN] = []
+        parent_sibling = parent.prev_sibling
+        while parent_sibling is not None and type_repr(parent_sibling.type) != "suite":
+            ignored_nodes.insert(0, parent_sibling)
+            parent_sibling = parent_sibling.prev_sibling
+        # Special case for `async_stmt` where the ASYNC token is on the
+        # grandparent node.
+        grandparent = parent.parent
+        if (
+            grandparent is not None
+            and grandparent.prev_sibling is not None
+            and grandparent.prev_sibling.type == token.ASYNC
+        ):
+            ignored_nodes.insert(0, grandparent.prev_sibling)
+        yield from iter(ignored_nodes)
+
+
 def is_fmt_on(container: LN, preview: bool) -> bool:
     """Determine whether formatting is switched on within a container.
     Determined by whether the last `# fmt:` comment is `on` or `off`.
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 1f132b7888f..8e8d41e239a 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -220,7 +220,9 @@ def visit_async_stmt(self, node: Node) -> Iterator[Line]:
         for child in children:
             yield from self.visit(child)
 
-            if child.type == token.ASYNC:
+            if child.type == token.ASYNC or child.type == STANDALONE_COMMENT:
+                # STANDALONE_COMMENT happens when `# fmt: skip` is applied on the async
+                # line.
                 break
 
         internal_stmt = next(children)
diff --git a/tests/data/simple_cases/fmtskip8.py b/tests/data/simple_cases/fmtskip8.py
new file mode 100644
index 00000000000..38e9c2a9f47
--- /dev/null
+++ b/tests/data/simple_cases/fmtskip8.py
@@ -0,0 +1,62 @@
+# Make sure a leading comment is not removed.
+def some_func(  unformatted,  args  ):  # fmt: skip
+    print("I am some_func")
+    return 0
+    # Make sure this comment is not removed.
+
+
+# Make sure a leading comment is not removed.
+async def some_async_func(  unformatted,   args):  # fmt: skip
+    print("I am some_async_func")
+    await asyncio.sleep(1)
+
+
+# Make sure a leading comment is not removed.
+class SomeClass(  Unformatted,  SuperClasses  ):  # fmt: skip
+    def some_method(  self,  unformatted,  args  ):  # fmt: skip
+        print("I am some_method")
+        return 0
+
+    async def some_async_method(  self,  unformatted,  args  ):  # fmt: skip
+        print("I am some_async_method")
+        await asyncio.sleep(1)
+
+
+# Make sure a leading comment is not removed.
+if  unformatted_call(  args  ):  # fmt: skip
+    print("First branch")
+    # Make sure this is not removed.
+elif  another_unformatted_call(  args  ):  # fmt: skip
+    print("Second branch")
+else  :  # fmt: skip
+    print("Last branch")
+
+
+while  some_condition(  unformatted,  args  ):  # fmt: skip
+    print("Do something")
+
+
+for  i  in  some_iter(  unformatted,  args  ):  # fmt: skip
+    print("Do something")
+
+
+async def test_async_for():
+    async  for  i  in  some_async_iter(  unformatted,  args  ):  # fmt: skip
+        print("Do something")
+
+
+try  :  # fmt: skip
+    some_call()
+except  UnformattedError  as  ex:  # fmt: skip
+    handle_exception()
+finally  :  # fmt: skip
+    finally_call()
+
+
+with  give_me_context(  unformatted,  args  ):  # fmt: skip
+    print("Do something")
+
+
+async def test_async_with():
+    async  with  give_me_async_context(  unformatted,  args  ):  # fmt: skip
+        print("Do something")

From 249c6536c4dff50773f30f222d1f81f0afe41f4c Mon Sep 17 00:00:00 2001
From: "Yilei \"Dolee\" Yang" <yileiyang@google.com>
Date: Tue, 19 Jul 2022 17:57:23 -0700
Subject: [PATCH 0572/1034] Fix an infinite loop when using `# fmt: on/off` ...
 (#3158)

... in the middle of an expression or code block by adding a missing return.

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 CHANGES.md                           |  2 ++
 src/black/comments.py                | 10 +++++++-
 tests/data/simple_cases/fmtonoff5.py | 36 ++++++++++++++++++++++++++++
 3 files changed, 47 insertions(+), 1 deletion(-)
 create mode 100644 tests/data/simple_cases/fmtonoff5.py

diff --git a/CHANGES.md b/CHANGES.md
index 90c62de6b98..94c3bdda68e 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -10,6 +10,8 @@
 
 <!-- Changes that affect Black's stable style -->
 
+- Fix an infinite loop when using `# fmt: on/off` in the middle of an expression or code
+  block (#3158)
 - Fix incorrect handling of `# fmt: skip` on colon `:` lines. (#3148)
 - Comments are no longer deleted when a line had spaces removed around power operators
   (#2874)
diff --git a/src/black/comments.py b/src/black/comments.py
index 522c1a7b88c..7069da16528 100644
--- a/src/black/comments.py
+++ b/src/black/comments.py
@@ -13,7 +13,7 @@
 from blib2to3.pgen2 import token
 
 from black.nodes import first_leaf_column, preceding_leaf, container_of
-from black.nodes import STANDALONE_COMMENT, WHITESPACE
+from black.nodes import CLOSING_BRACKETS, STANDALONE_COMMENT, WHITESPACE
 
 # types
 LN = Union[Leaf, Node]
@@ -227,6 +227,14 @@ def generate_ignored_nodes(
         # fix for fmt: on in children
         if contains_fmt_on_at_column(container, leaf.column, preview=preview):
             for child in container.children:
+                if isinstance(child, Leaf) and is_fmt_on(child, preview=preview):
+                    if child.type in CLOSING_BRACKETS:
+                        # This means `# fmt: on` is placed at a different bracket level
+                        # than `# fmt: off`. This is an invalid use, but as a courtesy,
+                        # we include this closing bracket in the ignored nodes.
+                        # The alternative is to fail the formatting.
+                        yield child
+                    return
                 if contains_fmt_on_at_column(child, leaf.column, preview=preview):
                     return
                 yield child
diff --git a/tests/data/simple_cases/fmtonoff5.py b/tests/data/simple_cases/fmtonoff5.py
new file mode 100644
index 00000000000..746aa41f4e4
--- /dev/null
+++ b/tests/data/simple_cases/fmtonoff5.py
@@ -0,0 +1,36 @@
+# Regression test for https://github.com/psf/black/issues/3129.
+setup(
+    entry_points={
+        # fmt: off
+        "console_scripts": [
+            "foo-bar"
+            "=foo.bar.:main",
+        # fmt: on
+            ]  # Includes an formatted indentation.
+    },
+)
+
+
+# Regression test for https://github.com/psf/black/issues/2015.
+run(
+    # fmt: off
+    [
+        "ls",
+        "-la",
+    ]
+    # fmt: on
+    + path,
+    check=True,
+)
+
+
+# Regression test for https://github.com/psf/black/issues/3026.
+def test_func():
+    # yapf: disable
+    if  unformatted(  args  ):
+        return True
+    # yapf: enable
+    elif b:
+        return True
+
+    return False

From b4dc40bf7aab4cd8914c3a2046c8ffc71bba2ff9 Mon Sep 17 00:00:00 2001
From: "Yilei \"Dolee\" Yang" <yileiyang@google.com>
Date: Tue, 19 Jul 2022 18:33:00 -0700
Subject: [PATCH 0573/1034] Use underscores instead of a space in a test file's
 name (#3180)

... for *consistency*
---
 ...emove_newline_after match.py => remove_newline_after_match.py} | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename tests/data/preview_310/{remove_newline_after match.py => remove_newline_after_match.py} (100%)

diff --git a/tests/data/preview_310/remove_newline_after match.py b/tests/data/preview_310/remove_newline_after_match.py
similarity index 100%
rename from tests/data/preview_310/remove_newline_after match.py
rename to tests/data/preview_310/remove_newline_after_match.py

From e9e756da7a68890fe36b79f711f93630758fd99d Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Tue, 26 Jul 2022 20:51:32 -0400
Subject: [PATCH 0574/1034] Bump sphinx from 5.0.2 to 5.1.0 in /docs (#3183)

Bumps [sphinx](https://github.com/sphinx-doc/sphinx) from 5.0.2 to 5.1.0.
- [Release notes](https://github.com/sphinx-doc/sphinx/releases)
- [Changelog](https://github.com/sphinx-doc/sphinx/blob/5.x/CHANGES)
- [Commits](https://github.com/sphinx-doc/sphinx/compare/v5.0.2...v5.1.0)

---
updated-dependencies:
- dependency-name: sphinx
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 docs/requirements.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index 65387e05e7e..e843a68566a 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,7 +1,7 @@
 # Used by ReadTheDocs; pinned requirements for stability.
 
 myst-parser==0.18.0
-Sphinx==5.0.2
+Sphinx==5.1.0
 # Older versions break Sphinx even though they're declared to be supported.
 docutils==0.18.1
 sphinxcontrib-programoutput==0.17

From e0a780a5056f1039edcf12c7a44198be902afbbc Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Tue, 26 Jul 2022 21:32:31 -0400
Subject: [PATCH 0575/1034] Add isort to linting toolchain

Co-authored-by: Shivansh-007 <shivansh-007@outlook.com>
---
 .pre-commit-config.yaml |  5 +++++
 pyproject.toml          | 10 +++++++++-
 2 files changed, 14 insertions(+), 1 deletion(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index a6dedc44968..3a9c0ceda85 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -23,6 +23,11 @@ repos:
         files: '(CHANGES\.md|the_basics\.md)$'
         additional_dependencies: *version_check_dependencies
 
+  - repo: https://github.com/pycqa/isort
+    rev: 5.10.1
+    hooks:
+      - id: isort
+
   - repo: https://github.com/pycqa/flake8
     rev: 4.0.1
     hooks:
diff --git a/pyproject.toml b/pyproject.toml
index 6df037c8a39..36765072056 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -22,13 +22,21 @@ extend-exclude = '''
 # this off.
 preview = true
 
-# Build system information below.
+# Build system information and other project-specific configuration below.
 # NOTE: You don't need this in your own Black configuration.
 
 [build-system]
 requires = ["setuptools>=45.0", "setuptools_scm[toml]>=6.3.1", "wheel"]
 build-backend = "setuptools.build_meta"
 
+[tool.isort]
+atomic = true
+profile = "black"
+line_length = 88
+skip_gitignore = true
+skip_glob = ["src/blib2to3", "tests/data", "profiling"]
+known_first_party = ["black", "blib2to3", "blackd", "_black_version"]
+
 [tool.pytest.ini_options]
 # Option below requires `tests/optional.py`
 addopts = "--strict-config --strict-markers"

From 44d5da00b520a05cd56e58b3998660f64ea59ebd Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Tue, 26 Jul 2022 21:33:08 -0400
Subject: [PATCH 0576/1034] Reformat codebase with isort

---
 action/main.py                   |  2 +-
 fuzz.py                          |  4 +-
 gallery/gallery.py               | 10 +---
 scripts/migrate-black.py         |  2 +-
 setup.py                         |  5 +-
 src/black/__init__.py            | 89 ++++++++++++++++++--------------
 src/black/brackets.py            | 20 ++++---
 src/black/cache.py               |  6 +--
 src/black/comments.py            | 15 ++++--
 src/black/debug.py               |  5 +-
 src/black/files.py               |  8 +--
 src/black/handle_ipynb_magics.py | 20 +++----
 src/black/linegen.py             | 73 ++++++++++++++++++--------
 src/black/lines.py               | 29 +++++++----
 src/black/mode.py                |  3 +-
 src/black/nodes.py               | 20 ++-----
 src/black/output.py              |  4 +-
 src/black/parsing.py             |  8 ++-
 src/black/report.py              |  2 +-
 src/black/rusty.py               |  1 -
 src/black/trans.py               | 38 +++++++++-----
 src/blackd/__init__.py           |  5 +-
 src/blackd/middlewares.py        |  7 +--
 tests/optional.py                |  6 +--
 tests/test_black.py              |  4 +-
 tests/test_blackd.py             |  9 ++--
 tests/test_format.py             |  2 +-
 tests/test_ipynb.py              | 15 +++---
 tests/test_no_ipynb.py           |  7 +--
 tests/test_trans.py              |  1 +
 30 files changed, 235 insertions(+), 185 deletions(-)

diff --git a/action/main.py b/action/main.py
index d14b10f421d..cd920f5fe0d 100644
--- a/action/main.py
+++ b/action/main.py
@@ -2,7 +2,7 @@
 import shlex
 import sys
 from pathlib import Path
-from subprocess import run, PIPE, STDOUT
+from subprocess import PIPE, STDOUT, run
 
 ACTION_PATH = Path(os.environ["GITHUB_ACTION_PATH"])
 ENV_PATH = ACTION_PATH / ".black-env"
diff --git a/fuzz.py b/fuzz.py
index f5f655ea279..83e02f45152 100644
--- a/fuzz.py
+++ b/fuzz.py
@@ -8,7 +8,8 @@
 import re
 
 import hypothesmith
-from hypothesis import HealthCheck, given, settings, strategies as st
+from hypothesis import HealthCheck, given, settings
+from hypothesis import strategies as st
 
 import black
 from blib2to3.pgen2.tokenize import TokenError
@@ -78,6 +79,7 @@ def test_idempotent_any_syntatically_valid_python(
     # (if you want only bounded fuzzing, just use `pytest fuzz.py`)
     try:
         import sys
+
         import atheris
     except ImportError:
         pass
diff --git a/gallery/gallery.py b/gallery/gallery.py
index be4d81dc427..38e52e34795 100755
--- a/gallery/gallery.py
+++ b/gallery/gallery.py
@@ -10,15 +10,7 @@
 from concurrent.futures import ThreadPoolExecutor
 from functools import lru_cache, partial
 from pathlib import Path
-from typing import (
-    Generator,
-    List,
-    NamedTuple,
-    Optional,
-    Tuple,
-    Union,
-    cast,
-)
+from typing import Generator, List, NamedTuple, Optional, Tuple, Union, cast
 from urllib.request import urlopen, urlretrieve
 
 PYPI_INSTANCE = "https://pypi.org/pypi"
diff --git a/scripts/migrate-black.py b/scripts/migrate-black.py
index 1183cb8a104..63cc5096a93 100755
--- a/scripts/migrate-black.py
+++ b/scripts/migrate-black.py
@@ -5,7 +5,7 @@
 import logging
 import os
 import sys
-from subprocess import check_output, run, Popen, PIPE
+from subprocess import PIPE, Popen, check_output, run
 
 
 def git(*args: str) -> str:
diff --git a/setup.py b/setup.py
index 522a42a7ce2..3accdf433bc 100644
--- a/setup.py
+++ b/setup.py
@@ -1,7 +1,8 @@
 # Copyright (C) 2020 Łukasz Langa
-from setuptools import setup, find_packages
-import sys
 import os
+import sys
+
+from setuptools import find_packages, setup
 
 assert sys.version_info >= (3, 6, 2), "black requires Python 3.6.2+"
 from pathlib import Path  # noqa E402
diff --git a/src/black/__init__.py b/src/black/__init__.py
index d2df1cbee7c..2a5c750a583 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -1,20 +1,20 @@
 import asyncio
-from json.decoder import JSONDecodeError
-import json
-from contextlib import contextmanager
-from datetime import datetime
-from enum import Enum
 import io
-from multiprocessing import Manager, freeze_support
+import json
 import os
-from pathlib import Path
-from pathspec.patterns.gitwildmatch import GitWildMatchPatternError
 import platform
 import re
 import signal
 import sys
 import tokenize
 import traceback
+from contextlib import contextmanager
+from dataclasses import replace
+from datetime import datetime
+from enum import Enum
+from json.decoder import JSONDecodeError
+from multiprocessing import Manager, freeze_support
+from pathlib import Path
 from typing import (
     TYPE_CHECKING,
     Any,
@@ -34,48 +34,61 @@
 
 import click
 from click.core import ParameterSource
-from dataclasses import replace
 from mypy_extensions import mypyc_attr
+from pathspec.patterns.gitwildmatch import GitWildMatchPatternError
 
-from black.const import DEFAULT_LINE_LENGTH, DEFAULT_INCLUDES, DEFAULT_EXCLUDES
-from black.const import STDIN_PLACEHOLDER
-from black.nodes import STARS, syms, is_simple_decorator_expression
-from black.nodes import is_string_token, is_number_token
-from black.lines import Line, EmptyLineTracker
-from black.linegen import transform_line, LineGenerator, LN
+from _black_version import version as __version__
+from black.cache import Cache, filter_cached, get_cache_info, read_cache, write_cache
 from black.comments import normalize_fmt_off
-from black.mode import FUTURE_FLAG_TO_FEATURE, Mode, TargetVersion
-from black.mode import Feature, supports_feature, VERSION_TO_FEATURES
-from black.cache import read_cache, write_cache, get_cache_info, filter_cached, Cache
-from black.concurrency import cancel, shutdown, maybe_install_uvloop
-from black.output import dump_to_file, ipynb_diff, diff, color_diff, out, err
-from black.report import Report, Changed, NothingChanged
+from black.concurrency import cancel, maybe_install_uvloop, shutdown
+from black.const import (
+    DEFAULT_EXCLUDES,
+    DEFAULT_INCLUDES,
+    DEFAULT_LINE_LENGTH,
+    STDIN_PLACEHOLDER,
+)
 from black.files import (
     find_project_root,
     find_pyproject_toml,
-    parse_pyproject_toml,
     find_user_pyproject_toml,
+    gen_python_files,
+    get_gitignore,
+    normalize_path_maybe_ignore,
+    parse_pyproject_toml,
+    wrap_stream_for_windows,
 )
-from black.files import gen_python_files, get_gitignore, normalize_path_maybe_ignore
-from black.files import wrap_stream_for_windows
-from black.parsing import InvalidInput  # noqa F401
-from black.parsing import lib2to3_parse, parse_ast, stringify_ast
 from black.handle_ipynb_magics import (
-    mask_cell,
-    unmask_cell,
-    remove_trailing_semicolon,
-    put_trailing_semicolon_back,
-    TRANSFORMED_MAGICS,
     PYTHON_CELL_MAGICS,
+    TRANSFORMED_MAGICS,
     jupyter_dependencies_are_installed,
+    mask_cell,
+    put_trailing_semicolon_back,
+    remove_trailing_semicolon,
+    unmask_cell,
 )
-
-
-# lib2to3 fork
-from blib2to3.pytree import Node, Leaf
+from black.linegen import LN, LineGenerator, transform_line
+from black.lines import EmptyLineTracker, Line
+from black.mode import (
+    FUTURE_FLAG_TO_FEATURE,
+    VERSION_TO_FEATURES,
+    Feature,
+    Mode,
+    TargetVersion,
+    supports_feature,
+)
+from black.nodes import (
+    STARS,
+    is_number_token,
+    is_simple_decorator_expression,
+    is_string_token,
+    syms,
+)
+from black.output import color_diff, diff, dump_to_file, err, ipynb_diff, out
+from black.parsing import InvalidInput  # noqa F401
+from black.parsing import lib2to3_parse, parse_ast, stringify_ast
+from black.report import Changed, NothingChanged, Report
 from blib2to3.pgen2 import token
-
-from _black_version import version as __version__
+from blib2to3.pytree import Leaf, Node
 
 if TYPE_CHECKING:
     from concurrent.futures import Executor
@@ -770,7 +783,7 @@ def reformat_many(
     workers: Optional[int],
 ) -> None:
     """Reformat multiple files using a ProcessPoolExecutor."""
-    from concurrent.futures import Executor, ThreadPoolExecutor, ProcessPoolExecutor
+    from concurrent.futures import Executor, ProcessPoolExecutor, ThreadPoolExecutor
 
     executor: Executor
     worker_count = workers if workers is not None else DEFAULT_WORKERS
diff --git a/src/black/brackets.py b/src/black/brackets.py
index c5ed4bf5b9f..3566f5b6c37 100644
--- a/src/black/brackets.py
+++ b/src/black/brackets.py
@@ -1,7 +1,7 @@
 """Builds on top of nodes.py to track brackets."""
 
-from dataclasses import dataclass, field
 import sys
+from dataclasses import dataclass, field
 from typing import Dict, Iterable, List, Optional, Tuple, Union
 
 if sys.version_info < (3, 8):
@@ -9,12 +9,20 @@
 else:
     from typing import Final
 
-from blib2to3.pytree import Leaf, Node
+from black.nodes import (
+    BRACKET,
+    CLOSING_BRACKETS,
+    COMPARATORS,
+    LOGIC_OPERATORS,
+    MATH_OPERATORS,
+    OPENING_BRACKETS,
+    UNPACKING_PARENTS,
+    VARARGS_PARENTS,
+    is_vararg,
+    syms,
+)
 from blib2to3.pgen2 import token
-
-from black.nodes import syms, is_vararg, VARARGS_PARENTS, UNPACKING_PARENTS
-from black.nodes import BRACKET, OPENING_BRACKETS, CLOSING_BRACKETS
-from black.nodes import MATH_OPERATORS, COMPARATORS, LOGIC_OPERATORS
+from blib2to3.pytree import Leaf, Node
 
 # types
 LN = Union[Leaf, Node]
diff --git a/src/black/cache.py b/src/black/cache.py
index 552c248d2ad..9455ff44772 100644
--- a/src/black/cache.py
+++ b/src/black/cache.py
@@ -2,16 +2,14 @@
 
 import os
 import pickle
-from pathlib import Path
 import tempfile
+from pathlib import Path
 from typing import Dict, Iterable, Set, Tuple
 
 from platformdirs import user_cache_dir
 
-from black.mode import Mode
-
 from _black_version import version as __version__
-
+from black.mode import Mode
 
 # types
 Timestamp = float
diff --git a/src/black/comments.py b/src/black/comments.py
index 7069da16528..dc58934f9d3 100644
--- a/src/black/comments.py
+++ b/src/black/comments.py
@@ -1,7 +1,7 @@
+import re
 import sys
 from dataclasses import dataclass
 from functools import lru_cache
-import re
 from typing import Iterator, List, Optional, Union
 
 if sys.version_info >= (3, 8):
@@ -9,11 +9,16 @@
 else:
     from typing_extensions import Final
 
-from blib2to3.pytree import Node, Leaf, type_repr
+from black.nodes import (
+    CLOSING_BRACKETS,
+    STANDALONE_COMMENT,
+    WHITESPACE,
+    container_of,
+    first_leaf_column,
+    preceding_leaf,
+)
 from blib2to3.pgen2 import token
-
-from black.nodes import first_leaf_column, preceding_leaf, container_of
-from black.nodes import CLOSING_BRACKETS, STANDALONE_COMMENT, WHITESPACE
+from blib2to3.pytree import Leaf, Node, type_repr
 
 # types
 LN = Union[Leaf, Node]
diff --git a/src/black/debug.py b/src/black/debug.py
index 5143076ab35..150b44842dd 100644
--- a/src/black/debug.py
+++ b/src/black/debug.py
@@ -1,12 +1,11 @@
 from dataclasses import dataclass
 from typing import Iterator, TypeVar, Union
 
-from blib2to3.pytree import Node, Leaf, type_repr
-from blib2to3.pgen2 import token
-
 from black.nodes import Visitor
 from black.output import out
 from black.parsing import lib2to3_parse
+from blib2to3.pgen2 import token
+from blib2to3.pytree import Leaf, Node, type_repr
 
 LN = Union[Leaf, Node]
 T = TypeVar("T")
diff --git a/src/black/files.py b/src/black/files.py
index 0382397e8a2..17515d52b57 100644
--- a/src/black/files.py
+++ b/src/black/files.py
@@ -1,9 +1,10 @@
-from functools import lru_cache
 import io
 import os
-from pathlib import Path
 import sys
+from functools import lru_cache
+from pathlib import Path
 from typing import (
+    TYPE_CHECKING,
     Any,
     Dict,
     Iterable,
@@ -14,7 +15,6 @@
     Sequence,
     Tuple,
     Union,
-    TYPE_CHECKING,
 )
 
 from mypy_extensions import mypyc_attr
@@ -30,9 +30,9 @@
 else:
     import tomli as tomllib
 
+from black.handle_ipynb_magics import jupyter_dependencies_are_installed
 from black.output import err
 from black.report import Report
-from black.handle_ipynb_magics import jupyter_dependencies_are_installed
 
 if TYPE_CHECKING:
     import colorama  # noqa: F401
diff --git a/src/black/handle_ipynb_magics.py b/src/black/handle_ipynb_magics.py
index a0ed56baafc..693f1a68bd4 100644
--- a/src/black/handle_ipynb_magics.py
+++ b/src/black/handle_ipynb_magics.py
@@ -1,22 +1,20 @@
 """Functions to process IPython magics with."""
 
-from functools import lru_cache
-import dataclasses
 import ast
-from typing import Dict, List, Tuple, Optional
-
+import collections
+import dataclasses
 import secrets
 import sys
-import collections
+from functools import lru_cache
+from typing import Dict, List, Optional, Tuple
 
 if sys.version_info >= (3, 10):
     from typing import TypeGuard
 else:
     from typing_extensions import TypeGuard
 
-from black.report import NothingChanged
 from black.output import out
-
+from black.report import NothingChanged
 
 TRANSFORMED_MAGICS = frozenset(
     (
@@ -90,11 +88,7 @@ def remove_trailing_semicolon(src: str) -> Tuple[str, bool]:
     Mirrors the logic in `quiet` from `IPython.core.displayhook`, but uses
     ``tokenize_rt`` so that round-tripping works fine.
     """
-    from tokenize_rt import (
-        src_to_tokens,
-        tokens_to_src,
-        reversed_enumerate,
-    )
+    from tokenize_rt import reversed_enumerate, src_to_tokens, tokens_to_src
 
     tokens = src_to_tokens(src)
     trailing_semicolon = False
@@ -118,7 +112,7 @@ def put_trailing_semicolon_back(src: str, has_trailing_semicolon: bool) -> str:
     """
     if not has_trailing_semicolon:
         return src
-    from tokenize_rt import src_to_tokens, tokens_to_src, reversed_enumerate
+    from tokenize_rt import reversed_enumerate, src_to_tokens, tokens_to_src
 
     tokens = src_to_tokens(src)
     for idx, token in reversed_enumerate(tokens):
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 8e8d41e239a..a2e41bf5912 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -1,38 +1,67 @@
 """
 Generating lines of code.
 """
-from functools import partial, wraps
 import sys
+from functools import partial, wraps
 from typing import Collection, Iterator, List, Optional, Set, Union, cast
 
-from black.nodes import WHITESPACE, RARROW, STATEMENT, STANDALONE_COMMENT
-from black.nodes import ASSIGNMENTS, OPENING_BRACKETS, CLOSING_BRACKETS
-from black.nodes import Visitor, syms, is_arith_like, ensure_visible
+from black.brackets import COMMA_PRIORITY, DOT_PRIORITY, max_delimiter_priority_in_atom
+from black.comments import FMT_OFF, generate_comments, list_comments
+from black.lines import (
+    Line,
+    append_leaves,
+    can_be_split,
+    can_omit_invisible_parens,
+    is_line_short_enough,
+    line_to_string,
+)
+from black.mode import Feature, Mode, Preview
 from black.nodes import (
+    ASSIGNMENTS,
+    CLOSING_BRACKETS,
+    OPENING_BRACKETS,
+    RARROW,
+    STANDALONE_COMMENT,
+    STATEMENT,
+    WHITESPACE,
+    Visitor,
+    ensure_visible,
+    is_arith_like,
+    is_atom_with_invisible_parens,
     is_docstring,
     is_empty_tuple,
-    is_one_tuple,
+    is_lpar_token,
+    is_multiline_string,
+    is_name_token,
     is_one_sequence_between,
+    is_one_tuple,
+    is_rpar_token,
+    is_stub_body,
+    is_stub_suite,
+    is_vararg,
+    is_walrus_assignment,
+    is_yield,
+    syms,
+    wrap_in_parentheses,
 )
-from black.nodes import is_name_token, is_lpar_token, is_rpar_token
-from black.nodes import is_walrus_assignment, is_yield, is_vararg, is_multiline_string
-from black.nodes import is_stub_suite, is_stub_body, is_atom_with_invisible_parens
-from black.nodes import wrap_in_parentheses
-from black.brackets import max_delimiter_priority_in_atom
-from black.brackets import DOT_PRIORITY, COMMA_PRIORITY
-from black.lines import Line, line_to_string, is_line_short_enough
-from black.lines import can_omit_invisible_parens, can_be_split, append_leaves
-from black.comments import generate_comments, list_comments, FMT_OFF
 from black.numerics import normalize_numeric_literal
-from black.strings import get_string_prefix, fix_docstring
-from black.strings import normalize_string_prefix, normalize_string_quotes
-from black.trans import Transformer, CannotTransform, StringMerger, StringSplitter
-from black.trans import StringParenWrapper, StringParenStripper, hug_power_op
-from black.mode import Mode, Feature, Preview
-
-from blib2to3.pytree import Node, Leaf
+from black.strings import (
+    fix_docstring,
+    get_string_prefix,
+    normalize_string_prefix,
+    normalize_string_quotes,
+)
+from black.trans import (
+    CannotTransform,
+    StringMerger,
+    StringParenStripper,
+    StringParenWrapper,
+    StringSplitter,
+    Transformer,
+    hug_power_op,
+)
 from blib2to3.pgen2 import token
-
+from blib2to3.pytree import Leaf, Node
 
 # types
 LeafID = int
diff --git a/src/black/lines.py b/src/black/lines.py
index 8b591c324a5..1ebc7808901 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -1,6 +1,6 @@
-from dataclasses import dataclass, field
 import itertools
 import sys
+from dataclasses import dataclass, field
 from typing import (
     Callable,
     Dict,
@@ -13,16 +13,25 @@
     cast,
 )
 
-from blib2to3.pytree import Node, Leaf
-from blib2to3.pgen2 import token
-
-from black.brackets import BracketTracker, DOT_PRIORITY
+from black.brackets import DOT_PRIORITY, BracketTracker
 from black.mode import Mode, Preview
-from black.nodes import STANDALONE_COMMENT, TEST_DESCENDANTS
-from black.nodes import BRACKETS, OPENING_BRACKETS, CLOSING_BRACKETS
-from black.nodes import syms, whitespace, replace_child, child_towards
-from black.nodes import is_multiline_string, is_import, is_type_comment
-from black.nodes import is_one_sequence_between
+from black.nodes import (
+    BRACKETS,
+    CLOSING_BRACKETS,
+    OPENING_BRACKETS,
+    STANDALONE_COMMENT,
+    TEST_DESCENDANTS,
+    child_towards,
+    is_import,
+    is_multiline_string,
+    is_one_sequence_between,
+    is_type_comment,
+    replace_child,
+    syms,
+    whitespace,
+)
+from blib2to3.pgen2 import token
+from blib2to3.pytree import Leaf, Node
 
 # types
 T = TypeVar("T")
diff --git a/src/black/mode.py b/src/black/mode.py
index b7359fab213..32b65d16ca5 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -4,11 +4,10 @@
 chosen by the user.
 """
 
-from hashlib import sha256
 import sys
-
 from dataclasses import dataclass, field
 from enum import Enum, auto
+from hashlib import sha256
 from operator import attrgetter
 from typing import Dict, Set
 from warnings import warn
diff --git a/src/black/nodes.py b/src/black/nodes.py
index 12f24b96687..8f341ab35d6 100644
--- a/src/black/nodes.py
+++ b/src/black/nodes.py
@@ -3,16 +3,7 @@
 """
 
 import sys
-from typing import (
-    Generic,
-    Iterator,
-    List,
-    Optional,
-    Set,
-    Tuple,
-    TypeVar,
-    Union,
-)
+from typing import Generic, Iterator, List, Optional, Set, Tuple, TypeVar, Union
 
 if sys.version_info >= (3, 8):
     from typing import Final
@@ -25,14 +16,11 @@
 
 from mypy_extensions import mypyc_attr
 
-# lib2to3 fork
-from blib2to3.pytree import Node, Leaf, type_repr, NL
-from blib2to3 import pygram
-from blib2to3.pgen2 import token
-
 from black.cache import CACHE_DIR
 from black.strings import has_triple_quotes
-
+from blib2to3 import pygram
+from blib2to3.pgen2 import token
+from blib2to3.pytree import NL, Leaf, Node, type_repr
 
 pygram.initialize(CACHE_DIR)
 syms: Final = pygram.python_symbols
diff --git a/src/black/output.py b/src/black/output.py
index 9561d4b57d2..f4c17f28ea4 100644
--- a/src/black/output.py
+++ b/src/black/output.py
@@ -4,11 +4,11 @@
 """
 
 import json
-from typing import Any, Optional
-from mypy_extensions import mypyc_attr
 import tempfile
+from typing import Any, Optional
 
 from click import echo, style
+from mypy_extensions import mypyc_attr
 
 
 @mypyc_attr(patchable=True)
diff --git a/src/black/parsing.py b/src/black/parsing.py
index d1ad7d2c671..64c0b1e3018 100644
--- a/src/black/parsing.py
+++ b/src/black/parsing.py
@@ -11,16 +11,14 @@
 else:
     from typing import Final
 
-# lib2to3 fork
-from blib2to3.pytree import Node, Leaf
+from black.mode import Feature, TargetVersion, supports_feature
+from black.nodes import syms
 from blib2to3 import pygram
 from blib2to3.pgen2 import driver
 from blib2to3.pgen2.grammar import Grammar
 from blib2to3.pgen2.parse import ParseError
 from blib2to3.pgen2.tokenize import TokenError
-
-from black.mode import TargetVersion, Feature, supports_feature
-from black.nodes import syms
+from blib2to3.pytree import Leaf, Node
 
 ast3: Any
 
diff --git a/src/black/report.py b/src/black/report.py
index 43b942c9e3c..a507671e4c0 100644
--- a/src/black/report.py
+++ b/src/black/report.py
@@ -7,7 +7,7 @@
 
 from click import style
 
-from black.output import out, err
+from black.output import err, out
 
 
 class Changed(Enum):
diff --git a/src/black/rusty.py b/src/black/rusty.py
index 822e3d7858a..84a80b5a2c2 100644
--- a/src/black/rusty.py
+++ b/src/black/rusty.py
@@ -4,7 +4,6 @@
 """
 from typing import Generic, TypeVar, Union
 
-
 T = TypeVar("T")
 E = TypeVar("E", bound=Exception)
 
diff --git a/src/black/trans.py b/src/black/trans.py
index 28d9250adc1..dc9c5520d5b 100644
--- a/src/black/trans.py
+++ b/src/black/trans.py
@@ -1,10 +1,11 @@
 """
 String transformers that can split and merge strings.
 """
+import re
+import sys
 from abc import ABC, abstractmethod
 from collections import defaultdict
 from dataclasses import dataclass
-import re
 from typing import (
     Any,
     Callable,
@@ -21,29 +22,38 @@
     TypeVar,
     Union,
 )
-import sys
 
 if sys.version_info < (3, 8):
-    from typing_extensions import Literal, Final
+    from typing_extensions import Final, Literal
 else:
     from typing import Literal, Final
 
 from mypy_extensions import trait
 
-from black.rusty import Result, Ok, Err
-
-from black.mode import Feature
-from black.nodes import syms, replace_child, parent_type
-from black.nodes import is_empty_par, is_empty_lpar, is_empty_rpar
-from black.nodes import OPENING_BRACKETS, CLOSING_BRACKETS, STANDALONE_COMMENT
-from black.lines import Line, append_leaves
 from black.brackets import BracketMatchError
 from black.comments import contains_pragma_comment
-from black.strings import has_triple_quotes, get_string_prefix, assert_is_leaf_string
-from black.strings import normalize_string_quotes
-
-from blib2to3.pytree import Leaf, Node
+from black.lines import Line, append_leaves
+from black.mode import Feature
+from black.nodes import (
+    CLOSING_BRACKETS,
+    OPENING_BRACKETS,
+    STANDALONE_COMMENT,
+    is_empty_lpar,
+    is_empty_par,
+    is_empty_rpar,
+    parent_type,
+    replace_child,
+    syms,
+)
+from black.rusty import Err, Ok, Result
+from black.strings import (
+    assert_is_leaf_string,
+    get_string_prefix,
+    has_triple_quotes,
+    normalize_string_quotes,
+)
 from blib2to3.pgen2 import token
+from blib2to3.pytree import Leaf, Node
 
 
 class CannotTransform(Exception):
diff --git a/src/blackd/__init__.py b/src/blackd/__init__.py
index 0463f169e19..a6de79fbeaa 100644
--- a/src/blackd/__init__.py
+++ b/src/blackd/__init__.py
@@ -8,6 +8,7 @@
 
 try:
     from aiohttp import web
+
     from .middlewares import cors
 except ImportError as ie:
     raise ImportError(
@@ -16,11 +17,11 @@
         + "to obtain aiohttp_cors: `pip install black[d]`"
     ) from None
 
-import black
-from black.concurrency import maybe_install_uvloop
 import click
 
+import black
 from _black_version import version as __version__
+from black.concurrency import maybe_install_uvloop
 
 # This is used internally by tests to shut down the server prematurely
 _stop_signal = asyncio.Event()
diff --git a/src/blackd/middlewares.py b/src/blackd/middlewares.py
index 97994ecc1df..7abde525bfd 100644
--- a/src/blackd/middlewares.py
+++ b/src/blackd/middlewares.py
@@ -1,7 +1,8 @@
-from typing import Iterable, Awaitable, Callable
-from aiohttp.web_response import StreamResponse
-from aiohttp.web_request import Request
+from typing import Awaitable, Callable, Iterable
+
 from aiohttp.web_middlewares import middleware
+from aiohttp.web_request import Request
+from aiohttp.web_response import StreamResponse
 
 Handler = Callable[[Request], Awaitable[StreamResponse]]
 Middleware = Callable[[Request, Handler], Awaitable[StreamResponse]]
diff --git a/tests/optional.py b/tests/optional.py
index a4e9441ef1c..853ecaa2a43 100644
--- a/tests/optional.py
+++ b/tests/optional.py
@@ -14,11 +14,11 @@
 Adapted from https://pypi.org/project/pytest-optional-tests/, (c) 2019 Reece Hart
 """
 
-from functools import lru_cache
 import itertools
 import logging
 import re
-from typing import FrozenSet, List, Set, TYPE_CHECKING
+from functools import lru_cache
+from typing import TYPE_CHECKING, FrozenSet, List, Set
 
 import pytest
 
@@ -32,8 +32,8 @@
 
 
 if TYPE_CHECKING:
-    from _pytest.config.argparsing import Parser
     from _pytest.config import Config
+    from _pytest.config.argparsing import Parser
     from _pytest.mark.structures import MarkDecorator
     from _pytest.nodes import Node
 
diff --git a/tests/test_black.py b/tests/test_black.py
index 8adcaed5ef8..bb7784d5478 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -6,6 +6,7 @@
 import logging
 import multiprocessing
 import os
+import re
 import sys
 import types
 import unittest
@@ -31,7 +32,6 @@
 
 import click
 import pytest
-import re
 from click import unstyle
 from click.testing import CliRunner
 from pathspec import PathSpec
@@ -59,8 +59,8 @@
     dump_to_stderr,
     ff,
     fs,
-    read_data,
     get_case_path,
+    read_data,
     read_data_from_file,
 )
 
diff --git a/tests/test_blackd.py b/tests/test_blackd.py
index 75d756705be..18b2c98ac1f 100644
--- a/tests/test_blackd.py
+++ b/tests/test_blackd.py
@@ -2,15 +2,16 @@
 from typing import Any
 from unittest.mock import patch
 
-from click.testing import CliRunner
 import pytest
+from click.testing import CliRunner
 
-from tests.util import read_data, DETERMINISTIC_HEADER
+from tests.util import DETERMINISTIC_HEADER, read_data
 
 try:
-    import blackd
-    from aiohttp.test_utils import AioHTTPTestCase
     from aiohttp import web
+    from aiohttp.test_utils import AioHTTPTestCase
+
+    import blackd
 except ImportError as e:
     raise RuntimeError("Please install Black with the 'd' extra") from e
 
diff --git a/tests/test_format.py b/tests/test_format.py
index 7a099fb9f33..3645934721f 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -8,10 +8,10 @@
 from tests.util import (
     DEFAULT_MODE,
     PY36_VERSIONS,
+    all_data_cases,
     assert_format,
     dump_to_stderr,
     read_data,
-    all_data_cases,
 )
 
 
diff --git a/tests/test_ipynb.py b/tests/test_ipynb.py
index e1d7dd88dcb..7aa2e91dd00 100644
--- a/tests/test_ipynb.py
+++ b/tests/test_ipynb.py
@@ -1,23 +1,24 @@
 import contextlib
-from dataclasses import replace
 import pathlib
 import re
 from contextlib import ExitStack as does_not_raise
+from dataclasses import replace
 from typing import ContextManager
 
+import pytest
+from _pytest.monkeypatch import MonkeyPatch
 from click.testing import CliRunner
-from black.handle_ipynb_magics import jupyter_dependencies_are_installed
+
 from black import (
-    main,
+    Mode,
     NothingChanged,
     format_cell,
     format_file_contents,
     format_file_in_place,
+    main,
 )
-import pytest
-from black import Mode
-from _pytest.monkeypatch import MonkeyPatch
-from tests.util import DATA_DIR, read_jupyter_notebook, get_case_path
+from black.handle_ipynb_magics import jupyter_dependencies_are_installed
+from tests.util import DATA_DIR, get_case_path, read_jupyter_notebook
 
 with contextlib.suppress(ModuleNotFoundError):
     import IPython
diff --git a/tests/test_no_ipynb.py b/tests/test_no_ipynb.py
index a3c897760fb..3e0b1593bf0 100644
--- a/tests/test_no_ipynb.py
+++ b/tests/test_no_ipynb.py
@@ -1,10 +1,11 @@
-import pytest
 import pathlib
 
-from tests.util import get_case_path
-from black import main, jupyter_dependencies_are_installed
+import pytest
 from click.testing import CliRunner
 
+from black import jupyter_dependencies_are_installed, main
+from tests.util import get_case_path
+
 pytestmark = pytest.mark.no_jupyter
 
 runner = CliRunner()
diff --git a/tests/test_trans.py b/tests/test_trans.py
index a1666a9c166..dce8a939677 100644
--- a/tests/test_trans.py
+++ b/tests/test_trans.py
@@ -1,4 +1,5 @@
 from typing import List, Tuple
+
 from black.trans import iter_fexpr_spans
 
 

From 411ed778d53244a9d0b9c1913266fd03aee89123 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Wed, 27 Jul 2022 22:04:14 -0400
Subject: [PATCH 0577/1034] Bump pre-commit hooks (#3191)

---
 .pre-commit-config.yaml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 3a9c0ceda85..87bb6e62987 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -38,7 +38,7 @@ repos:
           - flake8-simplify
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v0.940
+    rev: v0.971
     hooks:
       - id: mypy
         exclude: ^docs/conf.py
@@ -51,13 +51,13 @@ repos:
           - platformdirs >= 2.1.0
 
   - repo: https://github.com/pre-commit/mirrors-prettier
-    rev: v2.5.1
+    rev: v2.7.1
     hooks:
       - id: prettier
         exclude: \.github/workflows/diff_shades\.yml
 
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.1.0
+    rev: v4.3.0
     hooks:
       - id: end-of-file-fixer
       - id: trailing-whitespace

From ef8deb6d4a729192d7b7818d91530d462e769b7d Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Thu, 28 Jul 2022 16:55:36 -0400
Subject: [PATCH 0578/1034] Consolidate test CI and add concurrency limits
 (#3189)

---
 .github/workflows/doc.yml         |  2 +-
 .github/workflows/fuzz.yml        |  4 ++
 .github/workflows/lint.yml        |  6 +--
 .github/workflows/test.yml        | 64 +++++++++++++++++++++----------
 .github/workflows/uvloop_test.yml | 50 ------------------------
 5 files changed, 52 insertions(+), 74 deletions(-)
 delete mode 100644 .github/workflows/uvloop_test.yml

diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml
index 97f5f01e1b5..fc94dea62d9 100644
--- a/.github/workflows/doc.yml
+++ b/.github/workflows/doc.yml
@@ -1,4 +1,4 @@
-name: Documentation Build
+name: Documentation
 
 on: [push, pull_request]
 
diff --git a/.github/workflows/fuzz.yml b/.github/workflows/fuzz.yml
index 4ee6c839b48..a2810e25f77 100644
--- a/.github/workflows/fuzz.yml
+++ b/.github/workflows/fuzz.yml
@@ -2,6 +2,10 @@ name: Fuzz
 
 on: [push, pull_request]
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
+  cancel-in-progress: true
+
 permissions:
   contents: read
 
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index 1dd5ab5d35e..90c48013080 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -16,7 +16,7 @@ jobs:
     steps:
       - uses: actions/checkout@v3
 
-      - name: Set up Python
+      - name: Set up latest Python
         uses: actions/setup-python@v4
         with:
           python-version: "*"
@@ -27,9 +27,9 @@ jobs:
           python -m pip install -e '.[d]'
           python -m pip install tox
 
-      - name: Lint
+      - name: Run pre-commit hooks
         uses: pre-commit/action@v3.0.0
 
-      - name: Run On Self
+      - name: Format ourselves
         run: |
           tox -e run_self
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 7b4716c5493..7cc55d1bf76 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -11,8 +11,15 @@ on:
       - "docs/**"
       - "*.md"
 
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.run_id }}
+  cancel-in-progress: true
+
 jobs:
-  build:
+  main:
     # We want to run on external PRs, but not on our own internal PRs as they'll be run
     # by the push to the branch. Without this if check, checks are duplicated since
     # internal PRs match both the push and pull_request events.
@@ -35,29 +42,23 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
 
-      - name: Install dependencies
+      - name: Install tox
         run: |
           python -m pip install --upgrade pip
           python -m pip install --upgrade tox
 
       - name: Unit tests
         if: "!startsWith(matrix.python-version, 'pypy')"
-        run: |
-          tox -e ci-py -- -v --color=yes
+        run: tox -e ci-py -- -v --color=yes
 
-      - name: Unit tests pypy
+      - name: Unit tests (pypy)
         if: "startsWith(matrix.python-version, 'pypy')"
-        run: |
-          tox -e ci-pypy3 -- -v --color=yes
+        run: tox -e ci-pypy3 -- -v --color=yes
 
-      - name: Publish coverage to Coveralls
-        # If pushed / is a pull request against main repo AND
+      - name: Upload coverage to Coveralls
+        # Upload coverage if we are on the main repository and
         # we're running on Linux (this action only supports Linux)
-        if:
-          ((github.event_name == 'push' && github.repository == 'psf/black') ||
-          github.event.pull_request.base.repo.full_name == 'psf/black') && matrix.os ==
-          'ubuntu-latest'
-
+        if: github.repository == 'psf/black' && matrix.os == 'ubuntu-latest'
         uses: AndreMiras/coveralls-python-action@v20201129
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -66,17 +67,40 @@ jobs:
           debug: true
 
   coveralls-finish:
-    needs: build
-    # If pushed / is a pull request against main repo
-    if:
-      (github.event_name == 'push' && github.repository == 'psf/black') ||
-      github.event.pull_request.base.repo.full_name == 'psf/black'
+    needs: main
+    if: github.repository == 'psf/black'
 
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
-      - name: Coveralls finished
+      - name: Send finished signal to Coveralls
         uses: AndreMiras/coveralls-python-action@v20201129
         with:
           parallel-finished: true
           debug: true
+
+  uvloop:
+    if:
+      github.event_name == 'push' || github.event.pull_request.head.repo.full_name !=
+      github.repository
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macOS-latest]
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Set up latest Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "*"
+
+      - name: Install black with uvloop
+        run: |
+          python -m pip install pip --upgrade --disable-pip-version-check
+          python -m pip install -e ".[uvloop]"
+
+      - name: Format ourselves
+        run: python -m black --check src/
diff --git a/.github/workflows/uvloop_test.yml b/.github/workflows/uvloop_test.yml
deleted file mode 100644
index 9f247826969..00000000000
--- a/.github/workflows/uvloop_test.yml
+++ /dev/null
@@ -1,50 +0,0 @@
-name: test uvloop
-
-on:
-  push:
-    paths-ignore:
-      - "docs/**"
-      - "*.md"
-
-  pull_request:
-    paths-ignore:
-      - "docs/**"
-      - "*.md"
-
-permissions:
-  contents: read
-
-jobs:
-  build:
-    # We want to run on external PRs, but not on our own internal PRs as they'll be run
-    # by the push to the branch. Without this if check, checks are duplicated since
-    # internal PRs match both the push and pull_request events.
-    if:
-      github.event_name == 'push' || github.event.pull_request.head.repo.full_name !=
-      github.repository
-
-    runs-on: ${{ matrix.os }}
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [ubuntu-latest, macOS-latest]
-
-    steps:
-      - uses: actions/checkout@v3
-
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
-        with:
-          python-version: "*"
-
-      - name: Install latest pip
-        run: |
-          python -m pip install --upgrade pip
-
-      - name: Test uvloop Extra Install
-        run: |
-          python -m pip install -e ".[uvloop]"
-
-      - name: Format ourselves
-        run: |
-          python -m black --check src/

From 4f1772e2aed8356e57b923eacf45f813ec3324a0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Th=C3=A9ophile=20Bastian?= <contact@tobast.fr>
Date: Fri, 29 Jul 2022 01:49:00 +0200
Subject: [PATCH 0579/1034] Vim plugin: prefix messages with "Black: " (#3194)

As mentioned in GH-3185, when using Black as a Vim plugin, especially
automatically on save, the plugin's messages can be confusing, as
nothing indicates that they come from Black.
---
 CHANGES.md         | 2 ++
 autoload/black.vim | 6 +++---
 2 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 94c3bdda68e..e027b2cae71 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -46,6 +46,8 @@
 
 <!-- For example, Docker, GitHub Actions, pre-commit, editors -->
 
+- Vim plugin: prefix messages with `Black: ` so it's clear they come from Black (#3194)
+
 ### Output
 
 <!-- Changes to Black's terminal output and error messages -->
diff --git a/autoload/black.vim b/autoload/black.vim
index 6c381b431a3..ed657be7bd3 100644
--- a/autoload/black.vim
+++ b/autoload/black.vim
@@ -158,9 +158,9 @@ def Black(**kwargs):
     )
   except black.NothingChanged:
     if not quiet:
-      print(f'Already well formatted, good job. (took {time.time() - start:.4f}s)')
+      print(f'Black: already well formatted, good job. (took {time.time() - start:.4f}s)')
   except Exception as exc:
-    print(exc)
+    print(f'Black: {exc}')
   else:
     current_buffer = vim.current.window.buffer
     cursors = []
@@ -177,7 +177,7 @@ def Black(**kwargs):
       except vim.error:
         window.cursor = (len(window.buffer), 0)
     if not quiet:
-      print(f'Reformatted in {time.time() - start:.4f}s.')
+      print(f'Black: reformatted in {time.time() - start:.4f}s.')
 
 def get_configs():
   filename = vim.eval("@%")

From d85cf00ee80f00b25a819afef7f466dc871fa68d Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Fri, 29 Jul 2022 23:28:43 -0400
Subject: [PATCH 0580/1034] Remove blib2to3 grammar cache logging (#3193)

As error logs are emitted often (they happen when Black's cache
directory is created after blib2to3 tries to write its cache) and cause
issues to be filed by users who think Black isn't working correctly.

These errors are expected for now and aren't a cause for concern so
let's remove them to stop worrying users (and new issues from being
opened). We can improve the blib2to3 caching mechanism to write its
cache at the end of a successful command line invocation later.
---
 CHANGES.md                   | 2 ++
 src/blib2to3/pgen2/driver.py | 7 +++----
 2 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index e027b2cae71..a30ac7f25e1 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -54,6 +54,8 @@
 
 - Change from deprecated `asyncio.get_event_loop()` to create our event loop which
   removes DeprecationWarning (#3164)
+- Remove logging from internal `blib2to3` library since it regularily emits error logs
+  about failed caching that can and should be ignored (#3193)
 
 ### Packaging
 
diff --git a/src/blib2to3/pgen2/driver.py b/src/blib2to3/pgen2/driver.py
index 8fe820651da..daf271dfa9a 100644
--- a/src/blib2to3/pgen2/driver.py
+++ b/src/blib2to3/pgen2/driver.py
@@ -263,14 +263,13 @@ def load_grammar(
         logger = logging.getLogger(__name__)
     gp = _generate_pickle_name(gt) if gp is None else gp
     if force or not _newer(gp, gt):
-        logger.info("Generating grammar tables from %s", gt)
         g: grammar.Grammar = pgen.generate_grammar(gt)
         if save:
-            logger.info("Writing grammar tables to %s", gp)
             try:
                 g.dump(gp)
-            except OSError as e:
-                logger.info("Writing failed: %s", e)
+            except OSError:
+                # Ignore error, caching is not vital.
+                pass
     else:
         g = grammar.Grammar()
         g.load(gp)

From eaa048925e4443cc0e2b57b795f2852bedb4287f Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Fri, 29 Jul 2022 23:38:39 -0400
Subject: [PATCH 0581/1034] Add sanity check to executable CD + more (#3190)

Building executables without any testing is quite sketchy, let's at
least verify they won't crash on startup and format Black's own
codebase.

Also replaced "binaries" with "executables" since it's clearer and
won't be confused with mypyc.

Finally, I added colorama so all Windows users can get colour.
---
 .github/workflows/upload_binary.yml | 22 +++++++++++++---------
 1 file changed, 13 insertions(+), 9 deletions(-)

diff --git a/.github/workflows/upload_binary.yml b/.github/workflows/upload_binary.yml
index ed5ed961e67..22535a64c67 100644
--- a/.github/workflows/upload_binary.yml
+++ b/.github/workflows/upload_binary.yml
@@ -1,16 +1,14 @@
-name: Upload self-contained binaries
+name: Publish executables
 
 on:
   release:
     types: [published]
 
 permissions:
-  contents: read
+  contents: write # actions/upload-release-asset needs this.
 
 jobs:
   build:
-    permissions:
-      contents: write # for actions/upload-release-asset to upload release asset
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
@@ -38,15 +36,21 @@ jobs:
         with:
           python-version: "*"
 
-      - name: Install dependencies
+      - name: Install Black and PyInstaller
         run: |
-          python -m pip install --upgrade pip wheel setuptools
-          python -m pip install .
+          python -m pip install --upgrade pip wheel
+          python -m pip install .[colorama]
           python -m pip install pyinstaller
 
-      - name: Build binary
+      - name: Build executable with PyInstaller
+        run: >
+          python -m PyInstaller -F --name ${{ matrix.asset_name }} --add-data
+          'src/blib2to3${{ matrix.pathsep }}blib2to3' src/black/__main__.py
+
+      - name: Quickly test executable
         run: |
-          python -m PyInstaller -F --name ${{ matrix.asset_name }} --add-data 'src/blib2to3${{ matrix.pathsep }}blib2to3' src/black/__main__.py
+          ./dist/${{ matrix.asset_name }} --version
+          ./dist/${{ matrix.asset_name }} src --verbose
 
       - name: Upload binary as release asset
         uses: actions/upload-release-asset@v1

From ca0dbb8fa6cca8c1fc2650cde9e71402c03a3324 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Sun, 31 Jul 2022 10:34:29 -0400
Subject: [PATCH 0582/1034] Move fuzz.py to scripts/ (#3199)

---
 fuzz.py => scripts/fuzz.py | 0
 tox.ini                    | 2 +-
 2 files changed, 1 insertion(+), 1 deletion(-)
 rename fuzz.py => scripts/fuzz.py (100%)

diff --git a/fuzz.py b/scripts/fuzz.py
similarity index 100%
rename from fuzz.py
rename to scripts/fuzz.py
diff --git a/tox.ini b/tox.ini
index 7af9e48d6f0..51ff4872db0 100644
--- a/tox.ini
+++ b/tox.ini
@@ -59,7 +59,7 @@ deps =
 commands =
     pip install -e .[d]
     coverage erase
-    coverage run fuzz.py
+    coverage run {toxinidir}/scripts/fuzz.py
     coverage report
 
 [testenv:run_self]

From b776bf92adb7f47cd92f550e33c2db445d226f78 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 1 Aug 2022 13:51:46 -0400
Subject: [PATCH 0583/1034] Bump sphinx from 5.1.0 to 5.1.1 in /docs (#3201)

Bumps [sphinx](https://github.com/sphinx-doc/sphinx) from 5.1.0 to 5.1.1.
- [Release notes](https://github.com/sphinx-doc/sphinx/releases)
- [Changelog](https://github.com/sphinx-doc/sphinx/blob/5.x/CHANGES)
- [Commits](https://github.com/sphinx-doc/sphinx/compare/v5.1.0...v5.1.1)

---
updated-dependencies:
- dependency-name: sphinx
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 docs/requirements.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index e843a68566a..121df45e6c2 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,7 +1,7 @@
 # Used by ReadTheDocs; pinned requirements for stability.
 
 myst-parser==0.18.0
-Sphinx==5.1.0
+Sphinx==5.1.1
 # Older versions break Sphinx even though they're declared to be supported.
 docutils==0.18.1
 sphinxcontrib-programoutput==0.17

From f066e3fcae49554118962d2bbd9ec92a9958acf3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Nicol=C3=B2=20Intrieri?=
 <81313286+n-borges@users.noreply.github.com>
Date: Tue, 2 Aug 2022 18:01:15 +0200
Subject: [PATCH 0584/1034] makes install available for all users in docker
 image (#3202)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* makes install available for all users in docker image

moves the installation path from /root/.local to a
virtualenv. this way we still get the lightweight
multistage build without excluding non-root users.

* adds changelog entry for docker-image fix

A changelog entry has been added under the Integration
subheader

* changes dockerfile to use the venv activate script

we are now using the inbuilt venv activate script, as well
as explicitly mentioning the binary location in the entrypoint
cmd.

Co-authored-by: Nicolò <nicolo.intrieri@spinforward.it>
Co-authored-by: Cooper Lees <me@cooperlees.com>
---
 CHANGES.md |  2 ++
 Dockerfile | 12 +++++++-----
 2 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index a30ac7f25e1..5b29f20bfff 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -47,6 +47,8 @@
 <!-- For example, Docker, GitHub Actions, pre-commit, editors -->
 
 - Vim plugin: prefix messages with `Black: ` so it's clear they come from Black (#3194)
+- Docker: changed to a /opt/venv installation + added to PATH to be available to
+  non-root users (#3202)
 
 ### Output
 
diff --git a/Dockerfile b/Dockerfile
index c393e29f632..4e8f12f9798 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -2,16 +2,18 @@ FROM python:3-slim AS builder
 
 RUN mkdir /src
 COPY . /src/
-RUN pip install --no-cache-dir --upgrade pip setuptools wheel \
+ENV VIRTUAL_ENV=/opt/venv
+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 --user --no-cache-dir .[colorama,d]
+    && pip install --no-cache-dir .[colorama,d]
 
 FROM python:3-slim
 
 # copy only Python packages to limit the image size
-COPY --from=builder /root/.local /root/.local
-ENV PATH=/root/.local/bin:$PATH
+COPY --from=builder /opt/venv /opt/venv
+ENV PATH="/opt/venv/bin:$PATH"
 
-CMD ["black"]
+CMD ["/opt/venv/bin/black"]

From 507234c47d39f5b1d8289cdd49994e03dd97bcb4 Mon Sep 17 00:00:00 2001
From: Tom Fryers <61272761+TomFryers@users.noreply.github.com>
Date: Tue, 2 Aug 2022 22:22:04 +0100
Subject: [PATCH 0585/1034] Remove invalid syntax in docstrings -S --preview
 test (#3205)

uR is not a legal string prefix, so this test breaks (AssertionError:
cannot use --safe with this file; failed to parse source file AST:
invalid syntax) if changed to one in which the file is changed. I've
changed the last test to have u alone, and added an R to the test above
instead.
---
 .../docstring_preview_no_string_normalization.py              | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/tests/data/miscellaneous/docstring_preview_no_string_normalization.py b/tests/data/miscellaneous/docstring_preview_no_string_normalization.py
index 0957231eb9c..338cc01d33e 100644
--- a/tests/data/miscellaneous/docstring_preview_no_string_normalization.py
+++ b/tests/data/miscellaneous/docstring_preview_no_string_normalization.py
@@ -3,8 +3,8 @@ def do_not_touch_this_prefix():
 
 
 def do_not_touch_this_prefix2():
-    F'There was a bug where docstring prefixes would be normalized even with -S.'
+    FR'There was a bug where docstring prefixes would be normalized even with -S.'
 
 
 def do_not_touch_this_prefix3():
-    uR'''There was a bug where docstring prefixes would be normalized even with -S.'''
+    u'''There was a bug where docstring prefixes would be normalized even with -S.'''

From 6064a435453cdba47c43d71f3d0ea1aa19a29206 Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Wed, 10 Aug 2022 14:29:47 -0700
Subject: [PATCH 0586/1034] Use debug f-strings for feature detection (#3215)

Fixes GH-2907.
---
 CHANGES.md            |  2 ++
 src/black/__init__.py |  7 +++++++
 src/black/mode.py     |  5 +++++
 tests/test_black.py   | 20 ++++++++++++++++++++
 4 files changed, 34 insertions(+)

diff --git a/CHANGES.md b/CHANGES.md
index 5b29f20bfff..1fc8c65d6d8 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -33,6 +33,8 @@
 
 <!-- Changes to how Black can be configured -->
 
+- Black now uses the presence of debug f-strings to detect target version. (#3215)
+
 ### Documentation
 
 <!-- Major changes to documentation and policies. Small docs changes
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 2a5c750a583..b8a9d031896 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -87,6 +87,7 @@
 from black.parsing import InvalidInput  # noqa F401
 from black.parsing import lib2to3_parse, parse_ast, stringify_ast
 from black.report import Changed, NothingChanged, Report
+from black.trans import iter_fexpr_spans
 from blib2to3.pgen2 import token
 from blib2to3.pytree import Leaf, Node
 
@@ -1240,6 +1241,7 @@ def get_features_used(  # noqa: C901
 
     Currently looking for:
     - f-strings;
+    - self-documenting expressions in f-strings (f"{x=}");
     - underscores in numeric literals;
     - trailing commas after * or ** in function signatures and calls;
     - positional only arguments in function signatures and lambdas;
@@ -1261,6 +1263,11 @@ def get_features_used(  # noqa: C901
             value_head = n.value[:2]
             if value_head in {'f"', 'F"', "f'", "F'", "rf", "fr", "RF", "FR"}:
                 features.add(Feature.F_STRINGS)
+                if Feature.DEBUG_F_STRINGS not in features:
+                    for span_beg, span_end in iter_fexpr_spans(n.value):
+                        if n.value[span_beg : span_end - 1].rstrip().endswith("="):
+                            features.add(Feature.DEBUG_F_STRINGS)
+                            break
 
         elif is_number_token(n):
             if "_" in n.value:
diff --git a/src/black/mode.py b/src/black/mode.py
index 32b65d16ca5..f6d0cbf62bd 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -49,6 +49,7 @@ class Feature(Enum):
     ANN_ASSIGN_EXTENDED_RHS = 13
     EXCEPT_STAR = 14
     VARIADIC_GENERICS = 15
+    DEBUG_F_STRINGS = 16
     FORCE_OPTIONAL_PARENTHESES = 50
 
     # __future__ flags
@@ -81,6 +82,7 @@ class Feature(Enum):
     },
     TargetVersion.PY38: {
         Feature.F_STRINGS,
+        Feature.DEBUG_F_STRINGS,
         Feature.NUMERIC_UNDERSCORES,
         Feature.TRAILING_COMMA_IN_CALL,
         Feature.TRAILING_COMMA_IN_DEF,
@@ -93,6 +95,7 @@ class Feature(Enum):
     },
     TargetVersion.PY39: {
         Feature.F_STRINGS,
+        Feature.DEBUG_F_STRINGS,
         Feature.NUMERIC_UNDERSCORES,
         Feature.TRAILING_COMMA_IN_CALL,
         Feature.TRAILING_COMMA_IN_DEF,
@@ -106,6 +109,7 @@ class Feature(Enum):
     },
     TargetVersion.PY310: {
         Feature.F_STRINGS,
+        Feature.DEBUG_F_STRINGS,
         Feature.NUMERIC_UNDERSCORES,
         Feature.TRAILING_COMMA_IN_CALL,
         Feature.TRAILING_COMMA_IN_DEF,
@@ -120,6 +124,7 @@ class Feature(Enum):
     },
     TargetVersion.PY311: {
         Feature.F_STRINGS,
+        Feature.DEBUG_F_STRINGS,
         Feature.NUMERIC_UNDERSCORES,
         Feature.TRAILING_COMMA_IN_CALL,
         Feature.TRAILING_COMMA_IN_DEF,
diff --git a/tests/test_black.py b/tests/test_black.py
index bb7784d5478..81e7a9a7d0d 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -310,6 +310,26 @@ def test_detect_pos_only_arguments(self) -> None:
         versions = black.detect_target_versions(root)
         self.assertIn(black.TargetVersion.PY38, versions)
 
+    def test_detect_debug_f_strings(self) -> None:
+        root = black.lib2to3_parse("""f"{x=}" """)
+        features = black.get_features_used(root)
+        self.assertIn(black.Feature.DEBUG_F_STRINGS, features)
+        versions = black.detect_target_versions(root)
+        self.assertIn(black.TargetVersion.PY38, versions)
+
+        root = black.lib2to3_parse(
+            """f"{x}"\nf'{"="}'\nf'{(x:=5)}'\nf'{f(a="3=")}'\nf'{x:=10}'\n"""
+        )
+        features = black.get_features_used(root)
+        self.assertNotIn(black.Feature.DEBUG_F_STRINGS, features)
+
+        # We don't yet support feature version detection in nested f-strings
+        root = black.lib2to3_parse(
+            """f"heard a rumour that { f'{1+1=}' } ... seems like it could be true" """
+        )
+        features = black.get_features_used(root)
+        self.assertNotIn(black.Feature.DEBUG_F_STRINGS, features)
+
     @patch("black.dump_to_file", dump_to_stderr)
     def test_string_quotes(self) -> None:
         source, expected = read_data("miscellaneous", "string_quotes")

From 680cbe3a4fef175e3b4cac32641134de79c5c0ce Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Fri, 12 Aug 2022 19:28:47 -0700
Subject: [PATCH 0587/1034] Use --no-implicit-optional for type checking
 (#3220)

This makes type checking PEP 484 compliant (as of 2018).
mypy will change its defaults soon.

See:
https://github.com/python/mypy/issues/9091
https://github.com/python/mypy/pull/13401
---
 mypy.ini                    | 1 +
 src/blib2to3/pgen2/parse.py | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/mypy.ini b/mypy.ini
index 8ee9068d10b..244e8ae92f5 100644
--- a/mypy.ini
+++ b/mypy.ini
@@ -22,6 +22,7 @@ warn_no_return=True
 warn_redundant_casts=True
 warn_unused_ignores=True
 disallow_any_generics=True
+no_implicit_optional=True
 
 # Unreachable blocks have been an issue when compiling mypyc, let's try
 # to avoid 'em in the first place.
diff --git a/src/blib2to3/pgen2/parse.py b/src/blib2to3/pgen2/parse.py
index a9dc11f39ce..d6deaac6964 100644
--- a/src/blib2to3/pgen2/parse.py
+++ b/src/blib2to3/pgen2/parse.py
@@ -114,7 +114,7 @@ def add_token(self, tok_type: int, tok_val: Text, raw: bool = False) -> None:
                     args.insert(0, ilabel)
                 func(*args)
 
-    def determine_route(self, value: Text = None, force: bool = False) -> Optional[int]:
+    def determine_route(self, value: Optional[Text] = None, force: bool = False) -> Optional[int]:
         alive_ilabels = self.ilabels
         if len(alive_ilabels) == 0:
             *_, most_successful_ilabel = self._dead_ilabels

From 07b68e2425d2caadc2edf8fe021f60a32c6f44a7 Mon Sep 17 00:00:00 2001
From: Alexandr Artemyev <mogost@gmail.com>
Date: Sat, 13 Aug 2022 09:23:02 +0600
Subject: [PATCH 0588/1034] add preview option support for blackd (#3217)

Fixes #3195

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 AUTHORS.md                                        | 1 +
 CHANGES.md                                        | 2 ++
 docs/usage_and_configuration/black_as_a_server.md | 5 ++++-
 src/blackd/__init__.py                            | 4 ++++
 tests/test_blackd.py                              | 7 +++++++
 5 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/AUTHORS.md b/AUTHORS.md
index faa2b05840f..f30cd55a08b 100644
--- a/AUTHORS.md
+++ b/AUTHORS.md
@@ -20,6 +20,7 @@ Multiple contributions by:
 - [Adam Johnson](mailto:me@adamj.eu)
 - [Adam Williamson](mailto:adamw@happyassassin.net)
 - [Alexander Huynh](mailto:github@grande.coffee)
+- [Alexandr Artemyev](mailto:mogost@gmail.com)
 - [Alex Vandiver](mailto:github@chmrr.net)
 - [Allan Simon](mailto:allan.simon@supinfo.com)
 - Anders-Petter Ljungquist
diff --git a/CHANGES.md b/CHANGES.md
index 1fc8c65d6d8..79f4ce59187 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -29,6 +29,8 @@
 
 <!-- Changes to blackd -->
 
+- `blackd` now supports preview style via `X-Preview` header (#3217)
+
 ### Configuration
 
 <!-- Changes to how Black can be configured -->
diff --git a/docs/usage_and_configuration/black_as_a_server.md b/docs/usage_and_configuration/black_as_a_server.md
index fc9d1cab716..a2d4252109a 100644
--- a/docs/usage_and_configuration/black_as_a_server.md
+++ b/docs/usage_and_configuration/black_as_a_server.md
@@ -54,8 +54,11 @@ The headers controlling how source code is formatted are:
   command line flag. If present and its value is not the empty string, no string
   normalization will be performed.
 - `X-Skip-Magic-Trailing-Comma`: corresponds to the `--skip-magic-trailing-comma`
-  command line flag. If present and its value is not the empty string, trailing commas
+  command line flag. If present and its value is not an empty string, trailing commas
   will not be used as a reason to split lines.
+- `X-Preview`: corresponds to the `--preview` command line flag. If present and its
+  value is not an empty string, experimental and potentially disruptive style changes
+  will be used.
 - `X-Fast-Or-Safe`: if set to `fast`, `blackd` will act as _Black_ does when passed the
   `--fast` command line flag.
 - `X-Python-Variant`: if set to `pyi`, `blackd` will act as _Black_ does when passed the
diff --git a/src/blackd/__init__.py b/src/blackd/__init__.py
index a6de79fbeaa..e52a9917cf3 100644
--- a/src/blackd/__init__.py
+++ b/src/blackd/__init__.py
@@ -32,6 +32,7 @@
 PYTHON_VARIANT_HEADER = "X-Python-Variant"
 SKIP_STRING_NORMALIZATION_HEADER = "X-Skip-String-Normalization"
 SKIP_MAGIC_TRAILING_COMMA = "X-Skip-Magic-Trailing-Comma"
+PREVIEW = "X-Preview"
 FAST_OR_SAFE_HEADER = "X-Fast-Or-Safe"
 DIFF_HEADER = "X-Diff"
 
@@ -41,6 +42,7 @@
     PYTHON_VARIANT_HEADER,
     SKIP_STRING_NORMALIZATION_HEADER,
     SKIP_MAGIC_TRAILING_COMMA,
+    PREVIEW,
     FAST_OR_SAFE_HEADER,
     DIFF_HEADER,
 ]
@@ -109,6 +111,7 @@ async def handle(request: web.Request, executor: Executor) -> web.Response:
         skip_magic_trailing_comma = bool(
             request.headers.get(SKIP_MAGIC_TRAILING_COMMA, False)
         )
+        preview = bool(request.headers.get(PREVIEW, False))
         fast = False
         if request.headers.get(FAST_OR_SAFE_HEADER, "safe") == "fast":
             fast = True
@@ -118,6 +121,7 @@ async def handle(request: web.Request, executor: Executor) -> web.Response:
             line_length=line_length,
             string_normalization=not skip_string_normalization,
             magic_trailing_comma=not skip_magic_trailing_comma,
+            preview=preview,
         )
         req_bytes = await request.content.read()
         charset = request.charset if request.charset is not None else "utf8"
diff --git a/tests/test_blackd.py b/tests/test_blackd.py
index 18b2c98ac1f..1d12113a3f3 100644
--- a/tests/test_blackd.py
+++ b/tests/test_blackd.py
@@ -167,6 +167,13 @@ async def test_blackd_invalid_line_length(self) -> None:
         )
         self.assertEqual(response.status, 400)
 
+    @unittest_run_loop
+    async def test_blackd_preview(self) -> None:
+        response = await self.client.post(
+            "/", data=b'print("hello")\n', headers={blackd.PREVIEW: "true"}
+        )
+        self.assertEqual(response.status, 204)
+
     @unittest_run_loop
     async def test_blackd_response_black_version_header(self) -> None:
         response = await self.client.post("/")

From e7b967132fdbb9e2e4c4e9916530d238848ab183 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Fri, 12 Aug 2022 23:33:17 -0400
Subject: [PATCH 0589/1034] Port & upstream mypyc wheel build workflow  (#3197)

---
 .github/mypyc-requirements.txt    |  2 +-
 .github/workflows/pypi_upload.yml | 56 ++++++++++++++++++++++++++-----
 pyproject.toml                    | 52 ++++++++++++++++++++++++++++
 setup.py                          |  5 ++-
 4 files changed, 105 insertions(+), 10 deletions(-)

diff --git a/.github/mypyc-requirements.txt b/.github/mypyc-requirements.txt
index 4542673174c..352d36c0070 100644
--- a/.github/mypyc-requirements.txt
+++ b/.github/mypyc-requirements.txt
@@ -1,4 +1,4 @@
-mypy == 0.920
+mypy == 0.971
 
 # A bunch of packages for type information
 mypy-extensions >= 0.4.3
diff --git a/.github/workflows/pypi_upload.yml b/.github/workflows/pypi_upload.yml
index cda215aa5d6..31a83266345 100644
--- a/.github/workflows/pypi_upload.yml
+++ b/.github/workflows/pypi_upload.yml
@@ -1,4 +1,4 @@
-name: pypi_upload
+name: Publish to PyPI
 
 on:
   release:
@@ -8,14 +8,14 @@ permissions:
   contents: read
 
 jobs:
-  build:
-    name: PyPI Upload
+  main:
+    name: sdist + pure wheel
     runs-on: ubuntu-latest
 
     steps:
       - uses: actions/checkout@v3
 
-      - name: Set up Python
+      - name: Set up latest Python
         uses: actions/setup-python@v4
         with:
           python-version: "*"
@@ -26,11 +26,51 @@ jobs:
           python -m pip install --upgrade build twine
 
       - name: Build wheel and source distributions
-        run: |
-          python -m build
+        run: python -m build
 
       - name: Upload to PyPI via Twine
         env:
           TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
-        run: |
-          twine upload --verbose -u '__token__' dist/*
+        run: twine upload --verbose -u '__token__' dist/*
+
+  mypyc:
+    name: mypyc wheels (${{ matrix.name }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            name: linux-x86_64
+          - os: windows-2019
+            name: windows-amd64
+          - os: macos-11
+            name: macos-x86_64
+            macos_arch: "x86_64"
+          - os: macos-11
+            name: macos-arm64
+            macos_arch: "arm64"
+          - os: macos-11
+            name: macos-universal2
+            macos_arch: "universal2"
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Build wheels via cibuildwheel
+        uses: pypa/cibuildwheel@v2.8.1
+        env:
+          CIBW_ARCHS_MACOS: "${{ matrix.macos_arch }}"
+          # This isn't supported in pyproject.toml which makes sense (but is annoying).
+          CIBW_PROJECT_REQUIRES_PYTHON: ">=3.6.2"
+
+      - name: Upload wheels as workflow artifacts
+        uses: actions/upload-artifact@v2
+        with:
+          name: ${{ matrix.name }}-mypyc-wheels
+          path: ./wheelhouse/*.whl
+
+      - name: Upload wheels to PyPI via Twine
+        env:
+          TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
+        run: pipx run twine upload --verbose -u '__token__' wheelhouse/*.whl
diff --git a/pyproject.toml b/pyproject.toml
index 36765072056..813e86b2e93 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -29,6 +29,58 @@ preview = true
 requires = ["setuptools>=45.0", "setuptools_scm[toml]>=6.3.1", "wheel"]
 build-backend = "setuptools.build_meta"
 
+[tool.cibuildwheel]
+build-verbosity = 1
+# So these are the environments we target:
+# - Python: CPython 3.6+ only
+# - Architecture (64-bit only): amd64 / x86_64, universal2, and arm64
+# - OS: Linux (no musl), Windows, and macOS
+build = "cp3*-*"
+skip = ["*-manylinux_i686", "*-musllinux_*", "*-win32", "pp-*"]
+before-build = ["pip install -r .github/mypyc-requirements.txt"]
+# This is the bare minimum needed to run the test suite. Pulling in the full
+# test_requirements.txt would download a bunch of other packages not necessary
+# here and would slow down the testing step a fair bit.
+test-requires = ["pytest>=6.1.1"]
+test-command = 'pytest {project} -k "not incompatible_with_mypyc"'
+test-extras = ["d"," jupyter"]
+# Skip trying to test arm64 builds on Intel Macs. (so cross-compilation doesn't
+# straight up crash)
+test-skip = ["*-macosx_arm64", "*-macosx_universal2:arm64"]
+
+[tool.cibuildwheel.environment]
+BLACK_USE_MYPYC = "1"
+MYPYC_OPT_LEVEL = "3"
+MYPYC_DEBUG_LEVEL = "0"
+# The dependencies required to build wheels with mypyc aren't specified in
+# [build-system].requires so we'll have to manage the build environment ourselves.
+PIP_NO_BUILD_ISOLATION = "no"
+
+[tool.cibuildwheel.linux]
+before-build = [
+    "pip install -r .github/mypyc-requirements.txt",
+    "yum install -y clang",
+]
+# Newer images break the builds, not sure why. We'll need to investigate more later.
+manylinux-x86_64-image = "quay.io/pypa/manylinux2014_x86_64:2021-11-20-f410d11"
+
+[tool.cibuildwheel.linux.environment]
+BLACK_USE_MYPYC = "1"
+MYPYC_OPT_LEVEL = "3"
+MYPYC_DEBUG_LEVEL = "0"
+PIP_NO_BUILD_ISOLATION = "no"
+# Black needs Clang to compile successfully on Linux.
+CC = "clang"
+
+[tool.cibuildwheel.windows]
+# For some reason, (compiled) mypyc is failing to start up with "ImportError: DLL load
+# failed: A dynamic link library (DLL) initialization routine failed." on Windows for
+# at least 3.6. Let's just use interpreted mypy[c].
+# See also: https://github.com/mypyc/mypyc/issues/819.
+before-build = [
+    "pip install -r .github/mypyc-requirements.txt --no-binary mypy"
+]
+
 [tool.isort]
 atomic = true
 profile = "black"
diff --git a/setup.py b/setup.py
index 3accdf433bc..bc0cc32352e 100644
--- a/setup.py
+++ b/setup.py
@@ -67,7 +67,10 @@ def find_python_files(base: Path) -> List[Path]:
     ]
 
     opt_level = os.getenv("MYPYC_OPT_LEVEL", "3")
-    ext_modules = mypycify(mypyc_targets, opt_level=opt_level, verbose=True)
+    debug_level = os.getenv("MYPYC_DEBUG_LEVEL", "3")
+    ext_modules = mypycify(
+        mypyc_targets, opt_level=opt_level, debug_level=debug_level, verbose=True
+    )
 else:
     ext_modules = []
 

From 4ebf14d17ed544be893be5706c02116fd8b83b4c Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Sat, 13 Aug 2022 06:41:34 -0700
Subject: [PATCH 0590/1034] Strip trailing commas in subscripts with -C (#3209)

Fixes #2296, #3204
---
 CHANGES.md                                    |  2 ++
 src/black/lines.py                            | 18 +++++++++-
 src/black/mode.py                             |  1 +
 .../data/preview/skip_magic_trailing_comma.py | 34 +++++++++++++++++++
 tests/test_format.py                          |  7 +++-
 5 files changed, 60 insertions(+), 2 deletions(-)
 create mode 100644 tests/data/preview/skip_magic_trailing_comma.py

diff --git a/CHANGES.md b/CHANGES.md
index 79f4ce59187..fb7a2723b67 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -24,6 +24,8 @@
   this is invalid. This was a bug introduced in version 22.6.0. (#3166)
 - `--skip-string-normalization` / `-S` now prevents docstring prefixes from being
   normalized as expected (#3168)
+- When using `--skip-magic-trailing-comma` or `-C`, trailing commas are stripped from
+  subscript expressions with more than 1 element (#3209)
 
 ### _Blackd_
 
diff --git a/src/black/lines.py b/src/black/lines.py
index 1ebc7808901..30622650d53 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -273,6 +273,8 @@ def has_magic_trailing_comma(
         - it's not a single-element subscript
         Additionally, if ensure_removable:
         - it's not from square bracket indexing
+        (specifically, single-element square bracket indexing with
+        Preview.skip_magic_trailing_comma_in_subscript)
         """
         if not (
             closing.type in CLOSING_BRACKETS
@@ -301,8 +303,22 @@ def has_magic_trailing_comma(
 
             if not ensure_removable:
                 return True
+
             comma = self.leaves[-1]
-            return bool(comma.parent and comma.parent.type == syms.listmaker)
+            if comma.parent is None:
+                return False
+            if Preview.skip_magic_trailing_comma_in_subscript in self.mode:
+                return (
+                    comma.parent.type != syms.subscriptlist
+                    or closing.opening_bracket is None
+                    or not is_one_sequence_between(
+                        closing.opening_bracket,
+                        closing,
+                        self.leaves,
+                        brackets=(token.LSQB, token.RSQB),
+                    )
+                )
+            return comma.parent.type == syms.listmaker
 
         if self.is_import:
             return True
diff --git a/src/black/mode.py b/src/black/mode.py
index f6d0cbf62bd..6c0847e8bcc 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -156,6 +156,7 @@ class Preview(Enum):
     remove_block_trailing_newline = auto()
     remove_redundant_parens = auto()
     string_processing = auto()
+    skip_magic_trailing_comma_in_subscript = auto()
 
 
 class Deprecated(UserWarning):
diff --git a/tests/data/preview/skip_magic_trailing_comma.py b/tests/data/preview/skip_magic_trailing_comma.py
new file mode 100644
index 00000000000..e98174af427
--- /dev/null
+++ b/tests/data/preview/skip_magic_trailing_comma.py
@@ -0,0 +1,34 @@
+# We should not remove the trailing comma in a single-element subscript.
+a: tuple[int,]
+b = tuple[int,]
+
+# But commas in multiple element subscripts should be removed.
+c: tuple[int, int,]
+d = tuple[int, int,]
+
+# Remove commas for non-subscripts.
+small_list = [1,]
+list_of_types = [tuple[int,],]
+small_set = {1,}
+set_of_types = {tuple[int,],}
+
+# Except single element tuples
+small_tuple = (1,)
+
+# output
+# We should not remove the trailing comma in a single-element subscript.
+a: tuple[int,]
+b = tuple[int,]
+
+# But commas in multiple element subscripts should be removed.
+c: tuple[int, int]
+d = tuple[int, int]
+
+# Remove commas for non-subscripts.
+small_list = [1]
+list_of_types = [tuple[int,]]
+small_set = {1}
+set_of_types = {tuple[int,]}
+
+# Except single element tuples
+small_tuple = (1,)
diff --git a/tests/test_format.py b/tests/test_format.py
index 3645934721f..01cd61eef63 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -36,7 +36,12 @@ def test_simple_format(filename: str) -> None:
 
 @pytest.mark.parametrize("filename", all_data_cases("preview"))
 def test_preview_format(filename: str) -> None:
-    check_file("preview", filename, black.Mode(preview=True))
+    magic_trailing_comma = filename != "skip_magic_trailing_comma"
+    check_file(
+        "preview",
+        filename,
+        black.Mode(preview=True, magic_trailing_comma=magic_trailing_comma),
+    )
 
 
 @pytest.mark.parametrize("filename", all_data_cases("preview_39"))

From 6e0ad52e7a30771d0056fa60bfe5e368f2bc2417 Mon Sep 17 00:00:00 2001
From: Alexander Huynh <git-46f1a0bd5592a2f9244ca321b129902a06b53e03@e.sc>
Date: Sat, 20 Aug 2022 13:45:20 -0400
Subject: [PATCH 0591/1034] Update email (#3235)

This file gets scraped a lot, so create a distinct email for potential
spam.
---
 AUTHORS.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/AUTHORS.md b/AUTHORS.md
index f30cd55a08b..c81bc024e1d 100644
--- a/AUTHORS.md
+++ b/AUTHORS.md
@@ -19,7 +19,7 @@ Multiple contributions by:
 - [Abdur-Rahmaan Janhangeer](mailto:arj.python@gmail.com)
 - [Adam Johnson](mailto:me@adamj.eu)
 - [Adam Williamson](mailto:adamw@happyassassin.net)
-- [Alexander Huynh](mailto:github@grande.coffee)
+- [Alexander Huynh](mailto:ahrex-gh-psf-black@e.sc)
 - [Alexandr Artemyev](mailto:mogost@gmail.com)
 - [Alex Vandiver](mailto:github@chmrr.net)
 - [Allan Simon](mailto:allan.simon@supinfo.com)

From 59acf8af38a72e57b26d739adb5d5e7f350e8f2c Mon Sep 17 00:00:00 2001
From: Cooper Lees <cooper@fb.com>
Date: Mon, 22 Aug 2022 20:39:48 -0700
Subject: [PATCH 0592/1034] Add passing 3.11 CI by exempting blackd tests
 (#3234)

- Had to exempt blackd tests for now due to aiohttp
  - Skip by using `sys.version_info` tuple
  - aiohttp does not compile in 3.11 yet - refer to #3230
- Add a deadsnakes ubuntu workflow to run 3.11-dev to ensure we don't regress
  - Have it also format ourselves

Test:
- `tox -e 311`

Co-authored-by: Cooper Ry Lees <me@wcooperlees.com>
Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 .github/workflows/test-311.yml |  57 +++++
 CHANGES.md                     |   2 +
 setup.py                       |   1 +
 tests/test_blackd.py           | 379 +++++++++++++++++----------------
 tox.ini                        |  27 ++-
 5 files changed, 279 insertions(+), 187 deletions(-)
 create mode 100644 .github/workflows/test-311.yml

diff --git a/.github/workflows/test-311.yml b/.github/workflows/test-311.yml
new file mode 100644
index 00000000000..e23a67e89eb
--- /dev/null
+++ b/.github/workflows/test-311.yml
@@ -0,0 +1,57 @@
+name: Partially test 3.11 dev
+
+on:
+  push:
+    paths-ignore:
+      - "docs/**"
+      - "*.md"
+
+  pull_request:
+    paths-ignore:
+      - "docs/**"
+      - "*.md"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  main:
+    # We want to run on external PRs, but not on our own internal PRs as they'll be run
+    # by the push to the branch. Without this if check, checks are duplicated since
+    # internal PRs match both the push and pull_request events.
+    if:
+      github.event_name == 'push' || github.event.pull_request.head.repo.full_name !=
+      github.repository
+
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11.0-rc - 3.11"]
+        os: [ubuntu-latest, macOS-latest, windows-latest]
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install tox
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install --upgrade tox
+
+      - name: Run tests via tox
+        run: |
+          python -m tox -e 311
+
+      - name: Format ourselves
+        run: |
+          python -m pip install .
+          python -m black --check src/
diff --git a/CHANGES.md b/CHANGES.md
index fb7a2723b67..cae232684bd 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -69,6 +69,8 @@
 
 <!-- Changes to how Black is packaged, such as dependency requirements -->
 
+- Python 3.11 is now supported, except for `blackd` (#3234)
+
 ### Parser
 
 <!-- Changes to the parser or to version autodetection -->
diff --git a/setup.py b/setup.py
index bc0cc32352e..2cf455573c9 100644
--- a/setup.py
+++ b/setup.py
@@ -127,6 +127,7 @@ def find_python_files(base: Path) -> List[Path]:
         "Programming Language :: Python :: 3.8",
         "Programming Language :: Python :: 3.9",
         "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
         "Programming Language :: Python :: 3 :: Only",
         "Topic :: Software Development :: Libraries :: Python Modules",
         "Topic :: Software Development :: Quality Assurance",
diff --git a/tests/test_blackd.py b/tests/test_blackd.py
index 1d12113a3f3..8e739063f6e 100644
--- a/tests/test_blackd.py
+++ b/tests/test_blackd.py
@@ -1,4 +1,5 @@
 import re
+import sys
 from typing import Any
 from unittest.mock import patch
 
@@ -7,195 +8,201 @@
 
 from tests.util import DETERMINISTIC_HEADER, read_data
 
-try:
-    from aiohttp import web
-    from aiohttp.test_utils import AioHTTPTestCase
-
-    import blackd
-except ImportError as e:
-    raise RuntimeError("Please install Black with the 'd' extra") from e
-
-try:
-    from aiohttp.test_utils import unittest_run_loop
-except ImportError:
-    # unittest_run_loop is unnecessary and a no-op since aiohttp 3.8, and aiohttp 4
-    # removed it. To maintain compatibility we can make our own no-op decorator.
-    def unittest_run_loop(func: Any, *args: Any, **kwargs: Any) -> Any:
-        return func
-
-
-@pytest.mark.blackd
-class BlackDTestCase(AioHTTPTestCase):
-    def test_blackd_main(self) -> None:
-        with patch("blackd.web.run_app"):
-            result = CliRunner().invoke(blackd.main, [])
-            if result.exception is not None:
-                raise result.exception
-            self.assertEqual(result.exit_code, 0)
-
-    async def get_application(self) -> web.Application:
-        return blackd.make_app()
-
-    @unittest_run_loop
-    async def test_blackd_request_needs_formatting(self) -> None:
-        response = await self.client.post("/", data=b"print('hello world')")
-        self.assertEqual(response.status, 200)
-        self.assertEqual(response.charset, "utf8")
-        self.assertEqual(await response.read(), b'print("hello world")\n')
-
-    @unittest_run_loop
-    async def test_blackd_request_no_change(self) -> None:
-        response = await self.client.post("/", data=b'print("hello world")\n')
-        self.assertEqual(response.status, 204)
-        self.assertEqual(await response.read(), b"")
-
-    @unittest_run_loop
-    async def test_blackd_request_syntax_error(self) -> None:
-        response = await self.client.post("/", data=b"what even ( is")
-        self.assertEqual(response.status, 400)
-        content = await response.text()
-        self.assertTrue(
-            content.startswith("Cannot parse"),
-            msg=f"Expected error to start with 'Cannot parse', got {repr(content)}",
-        )
-
-    @unittest_run_loop
-    async def test_blackd_unsupported_version(self) -> None:
-        response = await self.client.post(
-            "/", data=b"what", headers={blackd.PROTOCOL_VERSION_HEADER: "2"}
-        )
-        self.assertEqual(response.status, 501)
-
-    @unittest_run_loop
-    async def test_blackd_supported_version(self) -> None:
-        response = await self.client.post(
-            "/", data=b"what", headers={blackd.PROTOCOL_VERSION_HEADER: "1"}
-        )
-        self.assertEqual(response.status, 200)
-
-    @unittest_run_loop
-    async def test_blackd_invalid_python_variant(self) -> None:
-        async def check(header_value: str, expected_status: int = 400) -> None:
+LESS_THAN_311 = sys.version_info < (3, 11)
+
+if LESS_THAN_311:  # noqa: C901
+    try:
+        from aiohttp import web
+        from aiohttp.test_utils import AioHTTPTestCase
+
+        import blackd
+    except ImportError as e:
+        raise RuntimeError("Please install Black with the 'd' extra") from e
+
+    try:
+        from aiohttp.test_utils import unittest_run_loop
+    except ImportError:
+        # unittest_run_loop is unnecessary and a no-op since aiohttp 3.8, and aiohttp 4
+        # removed it. To maintain compatibility we can make our own no-op decorator.
+        def unittest_run_loop(func: Any, *args: Any, **kwargs: Any) -> Any:
+            return func
+
+    @pytest.mark.blackd
+    class BlackDTestCase(AioHTTPTestCase):
+        def test_blackd_main(self) -> None:
+            with patch("blackd.web.run_app"):
+                result = CliRunner().invoke(blackd.main, [])
+                if result.exception is not None:
+                    raise result.exception
+                self.assertEqual(result.exit_code, 0)
+
+        async def get_application(self) -> web.Application:
+            return blackd.make_app()
+
+        @unittest_run_loop
+        async def test_blackd_request_needs_formatting(self) -> None:
+            response = await self.client.post("/", data=b"print('hello world')")
+            self.assertEqual(response.status, 200)
+            self.assertEqual(response.charset, "utf8")
+            self.assertEqual(await response.read(), b'print("hello world")\n')
+
+        @unittest_run_loop
+        async def test_blackd_request_no_change(self) -> None:
+            response = await self.client.post("/", data=b'print("hello world")\n')
+            self.assertEqual(response.status, 204)
+            self.assertEqual(await response.read(), b"")
+
+        @unittest_run_loop
+        async def test_blackd_request_syntax_error(self) -> None:
+            response = await self.client.post("/", data=b"what even ( is")
+            self.assertEqual(response.status, 400)
+            content = await response.text()
+            self.assertTrue(
+                content.startswith("Cannot parse"),
+                msg=f"Expected error to start with 'Cannot parse', got {repr(content)}",
+            )
+
+        @unittest_run_loop
+        async def test_blackd_unsupported_version(self) -> None:
+            response = await self.client.post(
+                "/", data=b"what", headers={blackd.PROTOCOL_VERSION_HEADER: "2"}
+            )
+            self.assertEqual(response.status, 501)
+
+        @unittest_run_loop
+        async def test_blackd_supported_version(self) -> None:
+            response = await self.client.post(
+                "/", data=b"what", headers={blackd.PROTOCOL_VERSION_HEADER: "1"}
+            )
+            self.assertEqual(response.status, 200)
+
+        @unittest_run_loop
+        async def test_blackd_invalid_python_variant(self) -> None:
+            async def check(header_value: str, expected_status: int = 400) -> None:
+                response = await self.client.post(
+                    "/",
+                    data=b"what",
+                    headers={blackd.PYTHON_VARIANT_HEADER: header_value},
+                )
+                self.assertEqual(response.status, expected_status)
+
+            await check("lol")
+            await check("ruby3.5")
+            await check("pyi3.6")
+            await check("py1.5")
+            await check("2")
+            await check("2.7")
+            await check("py2.7")
+            await check("2.8")
+            await check("py2.8")
+            await check("3.0")
+            await check("pypy3.0")
+            await check("jython3.4")
+
+        @unittest_run_loop
+        async def test_blackd_pyi(self) -> None:
+            source, expected = read_data("miscellaneous", "stub.pyi")
+            response = await self.client.post(
+                "/", data=source, headers={blackd.PYTHON_VARIANT_HEADER: "pyi"}
+            )
+            self.assertEqual(response.status, 200)
+            self.assertEqual(await response.text(), expected)
+
+        @unittest_run_loop
+        async def test_blackd_diff(self) -> None:
+            diff_header = re.compile(
+                r"(In|Out)\t\d\d\d\d-\d\d-\d\d \d\d:\d\d:\d\d\.\d\d\d\d\d\d \+\d\d\d\d"
+            )
+
+            source, _ = read_data("miscellaneous", "blackd_diff")
+            expected, _ = read_data("miscellaneous", "blackd_diff.diff")
+
             response = await self.client.post(
-                "/", data=b"what", headers={blackd.PYTHON_VARIANT_HEADER: header_value}
+                "/", data=source, headers={blackd.DIFF_HEADER: "true"}
             )
-            self.assertEqual(response.status, expected_status)
-
-        await check("lol")
-        await check("ruby3.5")
-        await check("pyi3.6")
-        await check("py1.5")
-        await check("2")
-        await check("2.7")
-        await check("py2.7")
-        await check("2.8")
-        await check("py2.8")
-        await check("3.0")
-        await check("pypy3.0")
-        await check("jython3.4")
-
-    @unittest_run_loop
-    async def test_blackd_pyi(self) -> None:
-        source, expected = read_data("miscellaneous", "stub.pyi")
-        response = await self.client.post(
-            "/", data=source, headers={blackd.PYTHON_VARIANT_HEADER: "pyi"}
-        )
-        self.assertEqual(response.status, 200)
-        self.assertEqual(await response.text(), expected)
-
-    @unittest_run_loop
-    async def test_blackd_diff(self) -> None:
-        diff_header = re.compile(
-            r"(In|Out)\t\d\d\d\d-\d\d-\d\d \d\d:\d\d:\d\d\.\d\d\d\d\d\d \+\d\d\d\d"
-        )
-
-        source, _ = read_data("miscellaneous", "blackd_diff")
-        expected, _ = read_data("miscellaneous", "blackd_diff.diff")
-
-        response = await self.client.post(
-            "/", data=source, headers={blackd.DIFF_HEADER: "true"}
-        )
-        self.assertEqual(response.status, 200)
-
-        actual = await response.text()
-        actual = diff_header.sub(DETERMINISTIC_HEADER, actual)
-        self.assertEqual(actual, expected)
-
-    @unittest_run_loop
-    async def test_blackd_python_variant(self) -> None:
-        code = (
-            "def f(\n"
-            "    and_has_a_bunch_of,\n"
-            "    very_long_arguments_too,\n"
-            "    and_lots_of_them_as_well_lol,\n"
-            "    **and_very_long_keyword_arguments\n"
-            "):\n"
-            "    pass\n"
-        )
-
-        async def check(header_value: str, expected_status: int) -> None:
+            self.assertEqual(response.status, 200)
+
+            actual = await response.text()
+            actual = diff_header.sub(DETERMINISTIC_HEADER, actual)
+            self.assertEqual(actual, expected)
+
+        @unittest_run_loop
+        async def test_blackd_python_variant(self) -> None:
+            code = (
+                "def f(\n"
+                "    and_has_a_bunch_of,\n"
+                "    very_long_arguments_too,\n"
+                "    and_lots_of_them_as_well_lol,\n"
+                "    **and_very_long_keyword_arguments\n"
+                "):\n"
+                "    pass\n"
+            )
+
+            async def check(header_value: str, expected_status: int) -> None:
+                response = await self.client.post(
+                    "/", data=code, headers={blackd.PYTHON_VARIANT_HEADER: header_value}
+                )
+                self.assertEqual(
+                    response.status, expected_status, msg=await response.text()
+                )
+
+            await check("3.6", 200)
+            await check("py3.6", 200)
+            await check("3.6,3.7", 200)
+            await check("3.6,py3.7", 200)
+            await check("py36,py37", 200)
+            await check("36", 200)
+            await check("3.6.4", 200)
+            await check("3.4", 204)
+            await check("py3.4", 204)
+            await check("py34,py36", 204)
+            await check("34", 204)
+
+        @unittest_run_loop
+        async def test_blackd_line_length(self) -> None:
             response = await self.client.post(
-                "/", data=code, headers={blackd.PYTHON_VARIANT_HEADER: header_value}
+                "/", data=b'print("hello")\n', headers={blackd.LINE_LENGTH_HEADER: "7"}
             )
-            self.assertEqual(
-                response.status, expected_status, msg=await response.text()
+            self.assertEqual(response.status, 200)
+
+        @unittest_run_loop
+        async def test_blackd_invalid_line_length(self) -> None:
+            response = await self.client.post(
+                "/",
+                data=b'print("hello")\n',
+                headers={blackd.LINE_LENGTH_HEADER: "NaN"},
             )
+            self.assertEqual(response.status, 400)
 
-        await check("3.6", 200)
-        await check("py3.6", 200)
-        await check("3.6,3.7", 200)
-        await check("3.6,py3.7", 200)
-        await check("py36,py37", 200)
-        await check("36", 200)
-        await check("3.6.4", 200)
-        await check("3.4", 204)
-        await check("py3.4", 204)
-        await check("py34,py36", 204)
-        await check("34", 204)
-
-    @unittest_run_loop
-    async def test_blackd_line_length(self) -> None:
-        response = await self.client.post(
-            "/", data=b'print("hello")\n', headers={blackd.LINE_LENGTH_HEADER: "7"}
-        )
-        self.assertEqual(response.status, 200)
-
-    @unittest_run_loop
-    async def test_blackd_invalid_line_length(self) -> None:
-        response = await self.client.post(
-            "/", data=b'print("hello")\n', headers={blackd.LINE_LENGTH_HEADER: "NaN"}
-        )
-        self.assertEqual(response.status, 400)
-
-    @unittest_run_loop
-    async def test_blackd_preview(self) -> None:
-        response = await self.client.post(
-            "/", data=b'print("hello")\n', headers={blackd.PREVIEW: "true"}
-        )
-        self.assertEqual(response.status, 204)
-
-    @unittest_run_loop
-    async def test_blackd_response_black_version_header(self) -> None:
-        response = await self.client.post("/")
-        self.assertIsNotNone(response.headers.get(blackd.BLACK_VERSION_HEADER))
-
-    @unittest_run_loop
-    async def test_cors_preflight(self) -> None:
-        response = await self.client.options(
-            "/",
-            headers={
-                "Access-Control-Request-Method": "POST",
-                "Origin": "*",
-                "Access-Control-Request-Headers": "Content-Type",
-            },
-        )
-        self.assertEqual(response.status, 200)
-        self.assertIsNotNone(response.headers.get("Access-Control-Allow-Origin"))
-        self.assertIsNotNone(response.headers.get("Access-Control-Allow-Headers"))
-        self.assertIsNotNone(response.headers.get("Access-Control-Allow-Methods"))
-
-    @unittest_run_loop
-    async def test_cors_headers_present(self) -> None:
-        response = await self.client.post("/", headers={"Origin": "*"})
-        self.assertIsNotNone(response.headers.get("Access-Control-Allow-Origin"))
-        self.assertIsNotNone(response.headers.get("Access-Control-Expose-Headers"))
+        @unittest_run_loop
+        async def test_blackd_preview(self) -> None:
+            response = await self.client.post(
+                "/", data=b'print("hello")\n', headers={blackd.PREVIEW: "true"}
+            )
+            self.assertEqual(response.status, 204)
+
+        @unittest_run_loop
+        async def test_blackd_response_black_version_header(self) -> None:
+            response = await self.client.post("/")
+            self.assertIsNotNone(response.headers.get(blackd.BLACK_VERSION_HEADER))
+
+        @unittest_run_loop
+        async def test_cors_preflight(self) -> None:
+            response = await self.client.options(
+                "/",
+                headers={
+                    "Access-Control-Request-Method": "POST",
+                    "Origin": "*",
+                    "Access-Control-Request-Headers": "Content-Type",
+                },
+            )
+            self.assertEqual(response.status, 200)
+            self.assertIsNotNone(response.headers.get("Access-Control-Allow-Origin"))
+            self.assertIsNotNone(response.headers.get("Access-Control-Allow-Headers"))
+            self.assertIsNotNone(response.headers.get("Access-Control-Allow-Methods"))
+
+        @unittest_run_loop
+        async def test_cors_headers_present(self) -> None:
+            response = await self.client.post("/", headers={"Origin": "*"})
+            self.assertIsNotNone(response.headers.get("Access-Control-Allow-Origin"))
+            self.assertIsNotNone(response.headers.get("Access-Control-Expose-Headers"))
diff --git a/tox.ini b/tox.ini
index 51ff4872db0..5f3874c23b4 100644
--- a/tox.ini
+++ b/tox.ini
@@ -1,5 +1,5 @@
 [tox]
-envlist = {,ci-}py{36,37,38,39,310,py3},fuzz,run_self
+envlist = {,ci-}py{36,37,38,39,310,311,py3},fuzz,run_self
 
 [testenv]
 setenv = PYTHONPATH = {toxinidir}/src
@@ -50,6 +50,31 @@ commands =
         --cov --cov-append {posargs}
     coverage report
 
+[testenv:{,ci-}311]
+setenv = PYTHONPATH = {toxinidir}/src
+skip_install = True
+recreate = True
+deps =
+    -r{toxinidir}/test_requirements.txt
+; a separate worker is required in ci due to https://foss.heptapod.net/pypy/pypy/-/issues/3317
+; this seems to cause tox to wait forever
+; remove this when pypy releases the bugfix
+commands =
+    pip install -e .
+    coverage erase
+    pytest tests \
+        --run-optional no_jupyter \
+        !ci: --numprocesses auto \
+        ci: --numprocesses 1 \
+        --cov {posargs}
+    pip install -e .[jupyter]
+    pytest tests --run-optional jupyter \
+        -m jupyter \
+        !ci: --numprocesses auto \
+        ci: --numprocesses 1 \
+        --cov --cov-append {posargs}
+    coverage report
+
 [testenv:fuzz]
 skip_install = True
 deps =

From 21218b666aeafd1c089cbe998e730f97605d25b2 Mon Sep 17 00:00:00 2001
From: "Yilei \"Dolee\" Yang" <yileiyang@google.com>
Date: Mon, 22 Aug 2022 20:40:38 -0700
Subject: [PATCH 0593/1034] Fix a string merging/split issue caused by
 standalone comments. (#3227)

Fixes #2734: a standalone comment causes strings to be merged into one far too long (and requiring two passes to do so).

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 .github/workflows/diff_shades.yml  |  1 -
 CHANGES.md                         |  2 ++
 src/black/trans.py                 | 16 +++++++++++++-
 tests/data/preview/long_strings.py | 35 ++++++++++++++++++++++++++++++
 4 files changed, 52 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/diff_shades.yml b/.github/workflows/diff_shades.yml
index 390089eca42..fef9637c92f 100644
--- a/.github/workflows/diff_shades.yml
+++ b/.github/workflows/diff_shades.yml
@@ -155,4 +155,3 @@ jobs:
         if: always()
         run: >
           diff-shades show-failed --check --show-log ${{ matrix.target-analysis }}
-          --check-allow 'sqlalchemy:test/orm/test_relationship_criteria.py'
diff --git a/CHANGES.md b/CHANGES.md
index cae232684bd..39db0fb95b8 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -26,6 +26,8 @@
   normalized as expected (#3168)
 - When using `--skip-magic-trailing-comma` or `-C`, trailing commas are stripped from
   subscript expressions with more than 1 element (#3209)
+- Fix a string merging/split issue when a comment is present in the middle of implicitly
+  concatenated strings on its own line (#3227)
 
 ### _Blackd_
 
diff --git a/src/black/trans.py b/src/black/trans.py
index dc9c5520d5b..9e0284cefe3 100644
--- a/src/black/trans.py
+++ b/src/black/trans.py
@@ -553,6 +553,9 @@ def make_naked(string: str, string_prefix: str) -> str:
 
             next_str_idx += 1
 
+        # Take a note on the index of the non-STRING leaf.
+        non_string_idx = next_str_idx
+
         S_leaf = Leaf(token.STRING, S)
         if self.normalize_strings:
             S_leaf.value = normalize_string_quotes(S_leaf.value)
@@ -572,7 +575,18 @@ def make_naked(string: str, string_prefix: str) -> str:
         string_leaf = Leaf(token.STRING, S_leaf.value.replace(BREAK_MARK, ""))
 
         if atom_node is not None:
-            replace_child(atom_node, string_leaf)
+            # If not all children of the atom node are merged (this can happen
+            # when there is a standalone comment in the middle) ...
+            if non_string_idx - string_idx < len(atom_node.children):
+                # We need to replace the old STRING leaves with the new string leaf.
+                first_child_idx = LL[string_idx].remove()
+                for idx in range(string_idx + 1, non_string_idx):
+                    LL[idx].remove()
+                if first_child_idx is not None:
+                    atom_node.insert_child(first_child_idx, string_leaf)
+            else:
+                # Else replace the atom node with the new string leaf.
+                replace_child(atom_node, string_leaf)
 
         # Build the final line ('new_line') that this method will later return.
         new_line = line.clone()
diff --git a/tests/data/preview/long_strings.py b/tests/data/preview/long_strings.py
index 430f760cf0b..26400eea450 100644
--- a/tests/data/preview/long_strings.py
+++ b/tests/data/preview/long_strings.py
@@ -72,6 +72,25 @@
     zzz,
 )
 
+inline_comments_func1(
+    "if there are inline "
+    "comments in the middle "
+    # Here is the standard alone comment.
+    "of the implicitly concatenated "
+    "string, we should handle "
+    "them correctly",
+    xxx,
+)
+
+inline_comments_func2(
+    "what if the string is very very very very very very very very very very long and this part does "
+    "not fit into a single line? "
+    # Here is the standard alone comment.
+    "then the string should still be properly handled by merging and splitting "
+    "it into parts that fit in line length.",
+    xxx,
+)
+
 raw_string = r"This is a long raw string. When re-formatting this string, black needs to make sure it prepends the 'r' onto the new string."
 
 fmt_string1 = "We also need to be sure to preserve any and all {} which may or may not be attached to the string in question.".format("method calls")
@@ -395,6 +414,22 @@ def foo():
     zzz,
 )
 
+inline_comments_func1(
+    "if there are inline comments in the middle "
+    # Here is the standard alone comment.
+    "of the implicitly concatenated string, we should handle them correctly",
+    xxx,
+)
+
+inline_comments_func2(
+    "what if the string is very very very very very very very very very very long and"
+    " this part does not fit into a single line? "
+    # Here is the standard alone comment.
+    "then the string should still be properly handled by merging and splitting "
+    "it into parts that fit in line length.",
+    xxx,
+)
+
 raw_string = (
     r"This is a long raw string. When re-formatting this string, black needs to make"
     r" sure it prepends the 'r' onto the new string."

From a5fde8ab9be26221d01bdd0a426db07cdb6f0f04 Mon Sep 17 00:00:00 2001
From: Ionite <dev@ionite.io>
Date: Fri, 26 Aug 2022 15:45:31 -0400
Subject: [PATCH 0594/1034] Remove hacky subprocess call in action.yml (#3226)

Updates action.yml to use the alternative $GITHUB_ACTION_PATH variable
instead of the original ${{ github.action_path }} which caused issues
with bash on the Windows runners. This removes the need for a Python
subprocess to call the main.py script.
---
 AUTHORS.md |  1 +
 action.yml | 19 ++-----------------
 2 files changed, 3 insertions(+), 17 deletions(-)

diff --git a/AUTHORS.md b/AUTHORS.md
index c81bc024e1d..533606240d3 100644
--- a/AUTHORS.md
+++ b/AUTHORS.md
@@ -79,6 +79,7 @@ Multiple contributions by:
 - [Hugo Barrera](mailto::hugo@barrera.io)
 - Hugo van Kemenade
 - [Hynek Schlawack](mailto:hs@ox.cx)
+- [Ionite](mailto:dev@ionite.io)
 - [Ivan Katanić](mailto:ivan.katanic@gmail.com)
 - [Jakub Kadlubiec](mailto:jakub.kadlubiec@skyscanner.net)
 - [Jakub Warczarek](mailto:jakub.warczarek@gmail.com)
diff --git a/action.yml b/action.yml
index dbd8ef69ec2..cfa6ef9fb7e 100644
--- a/action.yml
+++ b/action.yml
@@ -29,25 +29,10 @@ runs:
   using: composite
   steps:
     - run: |
-        # Exists since using github.action_path + path to main script doesn't work because bash
-        # interprets the backslashes in github.action_path (which are used when the runner OS
-        # is Windows) destroying the path to the target file.
-        #
-        # Also semicolons are necessary because I can't get the newlines to work
-        entrypoint="import sys;
-        import subprocess;
-        from pathlib import Path;
-
-        MAIN_SCRIPT = Path(r'${GITHUB_ACTION_PATH}') / 'action' / 'main.py';
-
-        proc = subprocess.run([sys.executable, str(MAIN_SCRIPT)]);
-        sys.exit(proc.returncode)
-        "
-
         if [ "$RUNNER_OS" == "Windows" ]; then
-          echo $entrypoint | python
+          python $GITHUB_ACTION_PATH/action/main.py
         else
-          echo $entrypoint | python3
+          python3 $GITHUB_ACTION_PATH/action/main.py
         fi
       env:
         # TODO: Remove once https://github.com/actions/runner/issues/665 is fixed.

From c47b91f513052cd39b818ea7c19716423c85c04e Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Fri, 26 Aug 2022 14:07:25 -0700
Subject: [PATCH 0595/1034] Fix misdetection of project root with
 `--stdin-filename` (#3216)

There are a number of places this behaviour could be patched, for
instance, it's quite tempting to patch it in `get_sources`. However
I believe we generally have the invariant that project root contains all
files we want to format, in which case it seems prudent to keep that
invariant.

This also improves the accuracy of the "sources to be formatted" log
message with --stdin-filename.

Fixes GH-3207.
---
 CHANGES.md            | 2 ++
 src/black/__init__.py | 8 ++++++--
 src/black/files.py    | 6 +++++-
 tests/test_black.py   | 6 ++++++
 4 files changed, 19 insertions(+), 3 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 39db0fb95b8..17659522fd1 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -40,6 +40,8 @@
 <!-- Changes to how Black can be configured -->
 
 - Black now uses the presence of debug f-strings to detect target version. (#3215)
+- Fix misdetection of project root and verbose logging of sources in cases involving
+  `--stdin-filename` (#3216)
 
 ### Documentation
 
diff --git a/src/black/__init__.py b/src/black/__init__.py
index b8a9d031896..a0c1ad4b416 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -469,7 +469,9 @@ def main(  # noqa: C901
         out(main.get_usage(ctx) + "\n\nOne of 'SRC' or 'code' is required.")
         ctx.exit(1)
 
-    root, method = find_project_root(src) if code is None else (None, None)
+    root, method = (
+        find_project_root(src, stdin_filename) if code is None else (None, None)
+    )
     ctx.obj["root"] = root
 
     if verbose:
@@ -480,7 +482,9 @@ def main(  # noqa: C901
             )
 
             normalized = [
-                (normalize_path_maybe_ignore(Path(source), root), source)
+                (source, source)
+                if source == "-"
+                else (normalize_path_maybe_ignore(Path(source), root), source)
                 for source in src
             ]
             srcs_string = ", ".join(
diff --git a/src/black/files.py b/src/black/files.py
index 17515d52b57..d51c1bc7a90 100644
--- a/src/black/files.py
+++ b/src/black/files.py
@@ -39,7 +39,9 @@
 
 
 @lru_cache()
-def find_project_root(srcs: Sequence[str]) -> Tuple[Path, str]:
+def find_project_root(
+    srcs: Sequence[str], stdin_filename: Optional[str] = None
+) -> Tuple[Path, str]:
     """Return a directory containing .git, .hg, or pyproject.toml.
 
     That directory will be a common parent of all files and directories
@@ -52,6 +54,8 @@ def find_project_root(srcs: Sequence[str]) -> Tuple[Path, str]:
     the second element as a string describing the method by which the
     project root was discovered.
     """
+    if stdin_filename is not None:
+        srcs = tuple(stdin_filename if s == "-" else s for s in srcs)
     if not srcs:
         srcs = [str(Path.cwd().resolve())]
 
diff --git a/tests/test_black.py b/tests/test_black.py
index 81e7a9a7d0d..c76b3faddf5 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -1396,6 +1396,12 @@ def test_find_project_root(self) -> None:
                 (src_dir.resolve(), "pyproject.toml"),
             )
 
+            with change_directory(test_dir):
+                self.assertEqual(
+                    black.find_project_root(("-",), stdin_filename="../src/a.py"),
+                    (src_dir.resolve(), "pyproject.toml"),
+                )
+
     @patch(
         "black.files.find_user_pyproject_toml",
     )

From e269f44b25737360e0dc65379f889dfa931dc68a Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Wed, 3 Aug 2022 20:18:33 -0400
Subject: [PATCH 0596/1034] Lazily import parallelized format modules

`black.reformat_many` depends on a lot of slow-to-import modules. When
formatting simply a single file, the time paid to import those modules
is totally wasted. So I moved `black.reformat_many` and its helpers
to `black.concurrency` which is now *only* imported if there's more
than one file to reformat. This way, running Black over a single file
is snappier

Here are the numbers before and after this patch running `python -m
black --version`:

- interpreted: 411 ms +- 9 ms -> 342 ms +- 7 ms: 1.20x faster
- compiled: 365 ms +- 15 ms -> 304 ms +- 7 ms: 1.20x faster

Co-authored-by: Fabio Zadrozny <fabiofz@gmail.com>
---
 CHANGES.md                                    |   2 +
 .../reference/reference_functions.rst         |   4 +-
 src/black/__init__.py                         | 153 ++----------------
 src/black/concurrency.py                      | 145 ++++++++++++++++-
 tests/test_black.py                           |   6 +-
 5 files changed, 165 insertions(+), 145 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 17659522fd1..34c54710775 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -87,6 +87,8 @@
 
 <!-- Changes that improve Black's performance. -->
 
+- Reduce Black's startup time when formatting a single file by 15-30% (#3211)
+
 ## 22.6.0
 
 ### Style
diff --git a/docs/contributing/reference/reference_functions.rst b/docs/contributing/reference/reference_functions.rst
index 01ffe44ef53..50eaeb31e15 100644
--- a/docs/contributing/reference/reference_functions.rst
+++ b/docs/contributing/reference/reference_functions.rst
@@ -52,7 +52,7 @@ Formatting
 
 .. autofunction:: black.reformat_one
 
-.. autofunction:: black.schedule_formatting
+.. autofunction:: black.concurrency.schedule_formatting
 
 File operations
 ---------------
@@ -173,7 +173,7 @@ Utilities
 
 .. autofunction:: black.linegen.should_split_line
 
-.. autofunction:: black.shutdown
+.. autofunction:: black.concurrency.shutdown
 
 .. autofunction:: black.strings.sub_twice
 
diff --git a/src/black/__init__.py b/src/black/__init__.py
index a0c1ad4b416..afc76e1fa0c 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -1,10 +1,8 @@
-import asyncio
 import io
 import json
 import os
 import platform
 import re
-import signal
 import sys
 import tokenize
 import traceback
@@ -13,10 +11,8 @@
 from datetime import datetime
 from enum import Enum
 from json.decoder import JSONDecodeError
-from multiprocessing import Manager, freeze_support
 from pathlib import Path
 from typing import (
-    TYPE_CHECKING,
     Any,
     Dict,
     Generator,
@@ -32,15 +28,19 @@
     Union,
 )
 
+if sys.version_info >= (3, 8):
+    from typing import Final
+else:
+    from typing_extensions import Final
+
 import click
 from click.core import ParameterSource
 from mypy_extensions import mypyc_attr
 from pathspec.patterns.gitwildmatch import GitWildMatchPatternError
 
 from _black_version import version as __version__
-from black.cache import Cache, filter_cached, get_cache_info, read_cache, write_cache
+from black.cache import Cache, get_cache_info, read_cache, write_cache
 from black.comments import normalize_fmt_off
-from black.concurrency import cancel, maybe_install_uvloop, shutdown
 from black.const import (
     DEFAULT_EXCLUDES,
     DEFAULT_INCLUDES,
@@ -91,10 +91,8 @@
 from blib2to3.pgen2 import token
 from blib2to3.pytree import Leaf, Node
 
-if TYPE_CHECKING:
-    from concurrent.futures import Executor
-
 COMPILED = Path(__file__).suffix in (".pyd", ".so")
+DEFAULT_WORKERS: Final = os.cpu_count()
 
 # types
 FileContent = str
@@ -125,8 +123,6 @@ def from_configuration(
 # Legacy name, left for integrations.
 FileMode = Mode
 
-DEFAULT_WORKERS = os.cpu_count()
-
 
 def read_pyproject_toml(
     ctx: click.Context, param: click.Parameter, value: Optional[str]
@@ -592,6 +588,8 @@ def main(  # noqa: C901
                 report=report,
             )
         else:
+            from black.concurrency import reformat_many
+
             reformat_many(
                 sources=sources,
                 fast=fast,
@@ -776,132 +774,6 @@ def reformat_one(
         report.failed(src, str(exc))
 
 
-# diff-shades depends on being to monkeypatch this function to operate. I know it's
-# not ideal, but this shouldn't cause any issues ... hopefully. ~ichard26
-@mypyc_attr(patchable=True)
-def reformat_many(
-    sources: Set[Path],
-    fast: bool,
-    write_back: WriteBack,
-    mode: Mode,
-    report: "Report",
-    workers: Optional[int],
-) -> None:
-    """Reformat multiple files using a ProcessPoolExecutor."""
-    from concurrent.futures import Executor, ProcessPoolExecutor, ThreadPoolExecutor
-
-    executor: Executor
-    worker_count = workers if workers is not None else DEFAULT_WORKERS
-    if sys.platform == "win32":
-        # Work around https://bugs.python.org/issue26903
-        assert worker_count is not None
-        worker_count = min(worker_count, 60)
-    try:
-        executor = ProcessPoolExecutor(max_workers=worker_count)
-    except (ImportError, NotImplementedError, OSError):
-        # we arrive here if the underlying system does not support multi-processing
-        # like in AWS Lambda or Termux, in which case we gracefully fallback to
-        # a ThreadPoolExecutor with just a single worker (more workers would not do us
-        # any good due to the Global Interpreter Lock)
-        executor = ThreadPoolExecutor(max_workers=1)
-
-    loop = asyncio.new_event_loop()
-    asyncio.set_event_loop(loop)
-    try:
-        loop.run_until_complete(
-            schedule_formatting(
-                sources=sources,
-                fast=fast,
-                write_back=write_back,
-                mode=mode,
-                report=report,
-                loop=loop,
-                executor=executor,
-            )
-        )
-    finally:
-        try:
-            shutdown(loop)
-        finally:
-            asyncio.set_event_loop(None)
-        if executor is not None:
-            executor.shutdown()
-
-
-async def schedule_formatting(
-    sources: Set[Path],
-    fast: bool,
-    write_back: WriteBack,
-    mode: Mode,
-    report: "Report",
-    loop: asyncio.AbstractEventLoop,
-    executor: "Executor",
-) -> None:
-    """Run formatting of `sources` in parallel using the provided `executor`.
-
-    (Use ProcessPoolExecutors for actual parallelism.)
-
-    `write_back`, `fast`, and `mode` options are passed to
-    :func:`format_file_in_place`.
-    """
-    cache: Cache = {}
-    if write_back not in (WriteBack.DIFF, WriteBack.COLOR_DIFF):
-        cache = read_cache(mode)
-        sources, cached = filter_cached(cache, sources)
-        for src in sorted(cached):
-            report.done(src, Changed.CACHED)
-    if not sources:
-        return
-
-    cancelled = []
-    sources_to_cache = []
-    lock = None
-    if write_back in (WriteBack.DIFF, WriteBack.COLOR_DIFF):
-        # For diff output, we need locks to ensure we don't interleave output
-        # from different processes.
-        manager = Manager()
-        lock = manager.Lock()
-    tasks = {
-        asyncio.ensure_future(
-            loop.run_in_executor(
-                executor, format_file_in_place, src, fast, mode, write_back, lock
-            )
-        ): src
-        for src in sorted(sources)
-    }
-    pending = tasks.keys()
-    try:
-        loop.add_signal_handler(signal.SIGINT, cancel, pending)
-        loop.add_signal_handler(signal.SIGTERM, cancel, pending)
-    except NotImplementedError:
-        # There are no good alternatives for these on Windows.
-        pass
-    while pending:
-        done, _ = await asyncio.wait(pending, return_when=asyncio.FIRST_COMPLETED)
-        for task in done:
-            src = tasks.pop(task)
-            if task.cancelled():
-                cancelled.append(task)
-            elif task.exception():
-                report.failed(src, str(task.exception()))
-            else:
-                changed = Changed.YES if task.result() else Changed.NO
-                # If the file was written back or was successfully checked as
-                # well-formatted, store this information in the cache.
-                if write_back is WriteBack.YES or (
-                    write_back is WriteBack.CHECK and changed is Changed.NO
-                ):
-                    sources_to_cache.append(src)
-                report.done(src, changed)
-    if cancelled:
-        if sys.version_info >= (3, 7):
-            await asyncio.gather(*cancelled, return_exceptions=True)
-        else:
-            await asyncio.gather(*cancelled, loop=loop, return_exceptions=True)
-    if sources_to_cache:
-        write_cache(cache, sources_to_cache, mode)
-
-
 def format_file_in_place(
     src: Path,
     fast: bool,
@@ -1506,8 +1378,11 @@ def patch_click() -> None:
 
 
 def patched_main() -> None:
-    maybe_install_uvloop()
-    freeze_support()
+    if sys.platform == "win32" and getattr(sys, "frozen", False):
+        from multiprocessing import freeze_support
+
+        freeze_support()
+
     patch_click()
     main()
 
diff --git a/src/black/concurrency.py b/src/black/concurrency.py
index 24f67b62f06..d77ea40bd46 100644
--- a/src/black/concurrency.py
+++ b/src/black/concurrency.py
@@ -1,9 +1,25 @@
+"""
+Formatting many files at once via multiprocessing. Contains entrypoint and utilities.
+
+NOTE: this module is only imported if we need to format several files at once.
+"""
+
 import asyncio
 import logging
+import signal
 import sys
-from typing import Any, Iterable
+from concurrent.futures import Executor, ProcessPoolExecutor, ThreadPoolExecutor
+from multiprocessing import Manager
+from pathlib import Path
+from typing import Any, Iterable, Optional, Set
+
+from mypy_extensions import mypyc_attr
 
+from black import DEFAULT_WORKERS, WriteBack, format_file_in_place
+from black.cache import Cache, filter_cached, read_cache, write_cache
+from black.mode import Mode
 from black.output import err
+from black.report import Changed, Report
 
 
 def maybe_install_uvloop() -> None:
@@ -11,7 +27,6 @@ def maybe_install_uvloop() -> None:
 
     This is called only from command-line entry points to avoid
     interfering with the parent process if Black is used as a library.
-
     """
     try:
         import uvloop
@@ -55,3 +70,129 @@ def shutdown(loop: asyncio.AbstractEventLoop) -> None:
         cf_logger = logging.getLogger("concurrent.futures")
         cf_logger.setLevel(logging.CRITICAL)
         loop.close()
+
+
+# diff-shades depends on being to monkeypatch this function to operate. I know it's
+# not ideal, but this shouldn't cause any issues ... hopefully. ~ichard26
+@mypyc_attr(patchable=True)
+def reformat_many(
+    sources: Set[Path],
+    fast: bool,
+    write_back: WriteBack,
+    mode: Mode,
+    report: Report,
+    workers: Optional[int],
+) -> None:
+    """Reformat multiple files using a ProcessPoolExecutor."""
+    maybe_install_uvloop()
+
+    executor: Executor
+    worker_count = workers if workers is not None else DEFAULT_WORKERS
+    if sys.platform == "win32":
+        # Work around https://bugs.python.org/issue26903
+        assert worker_count is not None
+        worker_count = min(worker_count, 60)
+    try:
+        executor = ProcessPoolExecutor(max_workers=worker_count)
+    except (ImportError, NotImplementedError, OSError):
+        # we arrive here if the underlying system does not support multi-processing
+        # like in AWS Lambda or Termux, in which case we gracefully fallback to
+        # a ThreadPoolExecutor with just a single worker (more workers would not do us
+        # any good due to the Global Interpreter Lock)
+        executor = ThreadPoolExecutor(max_workers=1)
+
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+    try:
+        loop.run_until_complete(
+            schedule_formatting(
+                sources=sources,
+                fast=fast,
+                write_back=write_back,
+                mode=mode,
+                report=report,
+                loop=loop,
+                executor=executor,
+            )
+        )
+    finally:
+        try:
+            shutdown(loop)
+        finally:
+            asyncio.set_event_loop(None)
+        if executor is not None:
+            executor.shutdown()
+
+
+async def schedule_formatting(
+    sources: Set[Path],
+    fast: bool,
+    write_back: WriteBack,
+    mode: Mode,
+    report: "Report",
+    loop: asyncio.AbstractEventLoop,
+    executor: "Executor",
+) -> None:
+    """Run formatting of `sources` in parallel using the provided `executor`.
+
+    (Use ProcessPoolExecutors for actual parallelism.)
+
+    `write_back`, `fast`, and `mode` options are passed to
+    :func:`format_file_in_place`.
+    """
+    cache: Cache = {}
+    if write_back not in (WriteBack.DIFF, WriteBack.COLOR_DIFF):
+        cache = read_cache(mode)
+        sources, cached = filter_cached(cache, sources)
+        for src in sorted(cached):
+            report.done(src, Changed.CACHED)
+    if not sources:
+        return
+
+    cancelled = []
+    sources_to_cache = []
+    lock = None
+    if write_back in (WriteBack.DIFF, WriteBack.COLOR_DIFF):
+        # For diff output, we need locks to ensure we don't interleave output
+        # from different processes.
+        manager = Manager()
+        lock = manager.Lock()
+    tasks = {
+        asyncio.ensure_future(
+            loop.run_in_executor(
+                executor, format_file_in_place, src, fast, mode, write_back, lock
+            )
+        ): src
+        for src in sorted(sources)
+    }
+    pending = tasks.keys()
+    try:
+        loop.add_signal_handler(signal.SIGINT, cancel, pending)
+        loop.add_signal_handler(signal.SIGTERM, cancel, pending)
+    except NotImplementedError:
+        # There are no good alternatives for these on Windows.
+        pass
+    while pending:
+        done, _ = await asyncio.wait(pending, return_when=asyncio.FIRST_COMPLETED)
+        for task in done:
+            src = tasks.pop(task)
+            if task.cancelled():
+                cancelled.append(task)
+            elif task.exception():
+                report.failed(src, str(task.exception()))
+            else:
+                changed = Changed.YES if task.result() else Changed.NO
+                # If the file was written back or was successfully checked as
+                # well-formatted, store this information in the cache.
+                if write_back is WriteBack.YES or (
+                    write_back is WriteBack.CHECK and changed is Changed.NO
+                ):
+                    sources_to_cache.append(src)
+                report.done(src, changed)
+    if cancelled:
+        if sys.version_info >= (3, 7):
+            await asyncio.gather(*cancelled, return_exceptions=True)
+        else:
+            await asyncio.gather(*cancelled, loop=loop, return_exceptions=True)
+    if sources_to_cache:
+        write_cache(cache, sources_to_cache, mode)
diff --git a/tests/test_black.py b/tests/test_black.py
index c76b3faddf5..5da247b71b0 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -1763,7 +1763,9 @@ def test_output_locking_when_writeback_diff(self, color: bool) -> None:
                 src = (workspace / f"test{tag}.py").resolve()
                 with src.open("w") as fobj:
                     fobj.write("print('hello')")
-            with patch("black.Manager", wraps=multiprocessing.Manager) as mgr:
+            with patch(
+                "black.concurrency.Manager", wraps=multiprocessing.Manager
+            ) as mgr:
                 cmd = ["--diff", str(workspace)]
                 if color:
                     cmd.append("--color")
@@ -1810,7 +1812,7 @@ def test_filter_cached(self) -> None:
                 str(cached): black.get_cache_info(cached),
                 str(cached_but_changed): (0.0, 0),
             }
-            todo, done = black.filter_cached(
+            todo, done = black.cache.filter_cached(
                 cache, {uncached, cached, cached_but_changed}
             )
             assert todo == {uncached, cached_but_changed}

From afed2c01903465f9a486ac481a66aa3413cc1b01 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Fri, 5 Aug 2022 14:04:43 -0400
Subject: [PATCH 0597/1034] Load .gitignore and exclude regex at time of use

Loading .gitignore and compiling the exclude regex can take more than
15ms. We shouldn't and don't need to pay this cost if we're simply
formatting files given on the command line directly.

I would've loved to lazily import pathspec, but the patch won't be clean
until the file collection and discovery logic is refactored first.

Co-authored-by: Fabio Zadrozny <fabiofz@gmail.com>
---
 src/black/__init__.py | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index afc76e1fa0c..117dc832c98 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -623,12 +623,7 @@ def get_sources(
 ) -> Set[Path]:
     """Compute the set of files to be formatted."""
     sources: Set[Path] = set()
-
-    if exclude is None:
-        exclude = re_compile_maybe_verbose(DEFAULT_EXCLUDES)
-        gitignore = get_gitignore(ctx.obj["root"])
-    else:
-        gitignore = None
+    root = ctx.obj["root"]
 
     for s in src:
         if s == "-" and stdin_filename:
@@ -663,6 +658,11 @@ def get_sources(
 
             sources.add(p)
         elif p.is_dir():
+            if exclude is None:
+                exclude = re_compile_maybe_verbose(DEFAULT_EXCLUDES)
+                gitignore = get_gitignore(root)
+            else:
+                gitignore = None
             sources.update(
                 gen_python_files(
                     p.iterdir(),

From c0cc19b5b3371842d696875897bebefebd5e1596 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Sat, 13 Aug 2022 13:46:52 -0400
Subject: [PATCH 0598/1034] Delay worker count determination

os.cpu_count() can return None (sounds like a super arcane edge case
though) so the type annotation for the `workers` parameter of
`black.main` is wrong. This *could* technically cause a runtime
TypeError since it'd trip one of mypyc's runtime type checks so we
might as well fix it.

Reading the documentation (and cross-checking with the source code),
you are actually allowed to pass None as `max_workers` to
`concurrent.futures.ProcessPoolExecutor`. If it is None, the pool
initializer will simply call os.cpu_count() [^1] (defaulting to 1 if it
returns None [^2]). It'll even round down the worker count to a level
that's safe for Windows.

... so theoretically we don't even need to call os.cpu_count()
ourselves, but our Windows limit is 60 (unlike the stdlib's 61) and I'd
prefer not accidentally reintroducing a crash on machines with many,
many CPU cores.

[^1]: https://docs.python.org/3/library/concurrent.futures.html#concurrent.futures.ProcessPoolExecutor
[^2]: https://github.com/python/cpython/blob/a372a7d65320396d44e8beb976e3a6c382963d4e/Lib/concurrent/futures/process.py#L600
---
 src/black/__init__.py    | 14 +++-----------
 src/black/concurrency.py | 11 ++++++-----
 2 files changed, 9 insertions(+), 16 deletions(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index 117dc832c98..86a0b637442 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -1,6 +1,5 @@
 import io
 import json
-import os
 import platform
 import re
 import sys
@@ -28,11 +27,6 @@
     Union,
 )
 
-if sys.version_info >= (3, 8):
-    from typing import Final
-else:
-    from typing_extensions import Final
-
 import click
 from click.core import ParameterSource
 from mypy_extensions import mypyc_attr
@@ -92,7 +86,6 @@
 from blib2to3.pytree import Leaf, Node
 
 COMPILED = Path(__file__).suffix in (".pyd", ".so")
-DEFAULT_WORKERS: Final = os.cpu_count()
 
 # types
 FileContent = str
@@ -371,9 +364,8 @@ def validate_regex(
     "-W",
     "--workers",
     type=click.IntRange(min=1),
-    default=DEFAULT_WORKERS,
-    show_default=True,
-    help="Number of parallel workers",
+    default=None,
+    help="Number of parallel workers [default: number of CPUs in the system]",
 )
 @click.option(
     "-q",
@@ -448,7 +440,7 @@ def main(  # noqa: C901
     extend_exclude: Optional[Pattern[str]],
     force_exclude: Optional[Pattern[str]],
     stdin_filename: Optional[str],
-    workers: int,
+    workers: Optional[int],
     src: Tuple[str, ...],
     config: Optional[str],
 ) -> None:
diff --git a/src/black/concurrency.py b/src/black/concurrency.py
index d77ea40bd46..bdc368d5add 100644
--- a/src/black/concurrency.py
+++ b/src/black/concurrency.py
@@ -6,6 +6,7 @@
 
 import asyncio
 import logging
+import os
 import signal
 import sys
 from concurrent.futures import Executor, ProcessPoolExecutor, ThreadPoolExecutor
@@ -15,7 +16,7 @@
 
 from mypy_extensions import mypyc_attr
 
-from black import DEFAULT_WORKERS, WriteBack, format_file_in_place
+from black import WriteBack, format_file_in_place
 from black.cache import Cache, filter_cached, read_cache, write_cache
 from black.mode import Mode
 from black.output import err
@@ -87,13 +88,13 @@ def reformat_many(
     maybe_install_uvloop()
 
     executor: Executor
-    worker_count = workers if workers is not None else DEFAULT_WORKERS
+    if workers is None:
+        workers = os.cpu_count() or 1
     if sys.platform == "win32":
         # Work around https://bugs.python.org/issue26903
-        assert worker_count is not None
-        worker_count = min(worker_count, 60)
+        workers = min(workers, 60)
     try:
-        executor = ProcessPoolExecutor(max_workers=worker_count)
+        executor = ProcessPoolExecutor(max_workers=workers)
     except (ImportError, NotImplementedError, OSError):
         # we arrive here if the underlying system does not support multi-processing
         # like in AWS Lambda or Termux, in which case we gracefully fallback to

From ba618a307a30a119b4fafe526ebf7d5f092ba981 Mon Sep 17 00:00:00 2001
From: "Yilei \"Dolee\" Yang" <yileiyang@google.com>
Date: Tue, 30 Aug 2022 19:52:00 -0700
Subject: [PATCH 0599/1034] Add parens around implicit string concatenations
 where it increases readability (#3162)

Adds parentheses around implicit string concatenations when it's inside
a list, set, or tuple. Except when it's only element and there's no trailing
comma.

Looking at the order of the transformers here, we need to "wrap in
parens" before string_split runs. So my solution is to introduce a
"collaboration" between StringSplitter and StringParenWrapper where the
splitter "skips" the split until the wrapper adds the parens (and then
the line after the paren is split by StringSplitter) in another pass.

I have also considered an alternative approach, where I tried to add a
different "string paren wrapper" class, and it runs before string_split.
Then I found out it requires a different do_transform implementation
than StringParenWrapper.do_transform, since the later assumes it runs
after the delimiter_split transform. So I stopped researching that
route.

Originally function calls were also included in this change, but given
missing commas should usually result in a runtime error and the scary
amount of changes this cause on downstream code, they were removed in
later revisions.
---
 CHANGES.md                                    |  2 +
 src/black/trans.py                            | 50 +++++++++++-
 tests/data/preview/comments7.py               | 46 +++++++----
 tests/data/preview/long_strings.py            | 81 ++++++++++++++++++-
 .../data/preview/long_strings__regression.py  | 32 +++++---
 tests/test_black.py                           | 24 +++---
 6 files changed, 191 insertions(+), 44 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 34c54710775..a5ce3b1fbe2 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -26,6 +26,8 @@
   normalized as expected (#3168)
 - When using `--skip-magic-trailing-comma` or `-C`, trailing commas are stripped from
   subscript expressions with more than 1 element (#3209)
+- Implicitly concatenated strings inside a list, set, or tuple are now wrapped inside
+  parentheses (#3162)
 - Fix a string merging/split issue when a comment is present in the middle of implicitly
   concatenated strings on its own line (#3227)
 
diff --git a/src/black/trans.py b/src/black/trans.py
index 9e0284cefe3..7ecfcef703d 100644
--- a/src/black/trans.py
+++ b/src/black/trans.py
@@ -1043,6 +1043,41 @@ def _get_max_string_length(self, line: Line, string_idx: int) -> int:
         max_string_length = self.line_length - offset
         return max_string_length
 
+    @staticmethod
+    def _prefer_paren_wrap_match(LL: List[Leaf]) -> Optional[int]:
+        """
+        Returns:
+            string_idx such that @LL[string_idx] is equal to our target (i.e.
+            matched) string, if this line matches the "prefer paren wrap" statement
+            requirements listed in the 'Requirements' section of the StringParenWrapper
+            class's docstring.
+                OR
+            None, otherwise.
+        """
+        # The line must start with a string.
+        if LL[0].type != token.STRING:
+            return None
+
+        matching_nodes = [
+            syms.listmaker,
+            syms.dictsetmaker,
+            syms.testlist_gexp,
+        ]
+        # If the string is an immediate child of a list/set/tuple literal...
+        if (
+            parent_type(LL[0]) in matching_nodes
+            or parent_type(LL[0].parent) in matching_nodes
+        ):
+            # And the string is surrounded by commas (or is the first/last child)...
+            prev_sibling = LL[0].prev_sibling
+            next_sibling = LL[0].next_sibling
+            if (not prev_sibling or prev_sibling.type == token.COMMA) and (
+                not next_sibling or next_sibling.type == token.COMMA
+            ):
+                return 0
+
+        return None
+
 
 def iter_fexpr_spans(s: str) -> Iterator[Tuple[int, int]]:
     """
@@ -1138,6 +1173,9 @@ class StringSplitter(BaseStringSplitter, CustomSplitMapMixin):
     def do_splitter_match(self, line: Line) -> TMatchResult:
         LL = line.leaves
 
+        if self._prefer_paren_wrap_match(LL) is not None:
+            return TErr("Line needs to be wrapped in parens first.")
+
         is_valid_index = is_valid_index_factory(LL)
 
         idx = 0
@@ -1583,8 +1621,7 @@ def _get_string_operator_leaves(self, leaves: Iterable[Leaf]) -> List[Leaf]:
 
 class StringParenWrapper(BaseStringSplitter, CustomSplitMapMixin):
     """
-    StringTransformer that splits non-"atom" strings (i.e. strings that do not
-    exist on lines by themselves).
+    StringTransformer that wraps strings in parens and then splits at the LPAR.
 
     Requirements:
         All of the requirements listed in BaseStringSplitter's docstring in
@@ -1604,6 +1641,11 @@ class StringParenWrapper(BaseStringSplitter, CustomSplitMapMixin):
             OR
         * The line is a dictionary key assignment where some valid key is being
         assigned the value of some string.
+            OR
+        * The line starts with an "atom" string that prefers to be wrapped in
+        parens. It's preferred to be wrapped when it's is an immediate child of
+        a list/set/tuple literal, AND the string is surrounded by commas (or is
+        the first/last child).
 
     Transformations:
         The chosen string is wrapped in parentheses and then split at the LPAR.
@@ -1628,6 +1670,9 @@ class StringParenWrapper(BaseStringSplitter, CustomSplitMapMixin):
         changed such that it no longer needs to be given its own line,
         StringParenWrapper relies on StringParenStripper to clean up the
         parentheses it created.
+
+        For "atom" strings that prefers to be wrapped in parens, it requires
+        StringSplitter to hold the split until the string is wrapped in parens.
     """
 
     def do_splitter_match(self, line: Line) -> TMatchResult:
@@ -1644,6 +1689,7 @@ def do_splitter_match(self, line: Line) -> TMatchResult:
             or self._assert_match(LL)
             or self._assign_match(LL)
             or self._dict_match(LL)
+            or self._prefer_paren_wrap_match(LL)
         )
 
         if string_idx is not None:
diff --git a/tests/data/preview/comments7.py b/tests/data/preview/comments7.py
index ca9d7c62b21..ec2dc501d8e 100644
--- a/tests/data/preview/comments7.py
+++ b/tests/data/preview/comments7.py
@@ -226,39 +226,53 @@ class C:
             # metadata_version errors.
             (
                 {},
-                "None is an invalid value for Metadata-Version. Error: This field is"
-                " required. see"
-                " https://packaging.python.org/specifications/core-metadata",
+                (
+                    "None is an invalid value for Metadata-Version. Error: This field"
+                    " is required. see"
+                    " https://packaging.python.org/specifications/core-metadata"
+                ),
             ),
             (
                 {"metadata_version": "-1"},
-                "'-1' is an invalid value for Metadata-Version. Error: Unknown Metadata"
-                " Version see"
-                " https://packaging.python.org/specifications/core-metadata",
+                (
+                    "'-1' is an invalid value for Metadata-Version. Error: Unknown"
+                    " Metadata Version see"
+                    " https://packaging.python.org/specifications/core-metadata"
+                ),
             ),
             # name errors.
             (
                 {"metadata_version": "1.2"},
-                "'' is an invalid value for Name. Error: This field is required. see"
-                " https://packaging.python.org/specifications/core-metadata",
+                (
+                    "'' is an invalid value for Name. Error: This field is required."
+                    " see https://packaging.python.org/specifications/core-metadata"
+                ),
             ),
             (
                 {"metadata_version": "1.2", "name": "foo-"},
-                "'foo-' is an invalid value for Name. Error: Must start and end with a"
-                " letter or numeral and contain only ascii numeric and '.', '_' and"
-                " '-'. see https://packaging.python.org/specifications/core-metadata",
+                (
+                    "'foo-' is an invalid value for Name. Error: Must start and end"
+                    " with a letter or numeral and contain only ascii numeric and '.',"
+                    " '_' and '-'. see"
+                    " https://packaging.python.org/specifications/core-metadata"
+                ),
             ),
             # version errors.
             (
                 {"metadata_version": "1.2", "name": "example"},
-                "'' is an invalid value for Version. Error: This field is required. see"
-                " https://packaging.python.org/specifications/core-metadata",
+                (
+                    "'' is an invalid value for Version. Error: This field is required."
+                    " see https://packaging.python.org/specifications/core-metadata"
+                ),
             ),
             (
                 {"metadata_version": "1.2", "name": "example", "version": "dog"},
-                "'dog' is an invalid value for Version. Error: Must start and end with"
-                " a letter or numeral and contain only ascii numeric and '.', '_' and"
-                " '-'. see https://packaging.python.org/specifications/core-metadata",
+                (
+                    "'dog' is an invalid value for Version. Error: Must start and end"
+                    " with a letter or numeral and contain only ascii numeric and '.',"
+                    " '_' and '-'. see"
+                    " https://packaging.python.org/specifications/core-metadata"
+                ),
             ),
         ],
     )
diff --git a/tests/data/preview/long_strings.py b/tests/data/preview/long_strings.py
index 26400eea450..3ad5f355e33 100644
--- a/tests/data/preview/long_strings.py
+++ b/tests/data/preview/long_strings.py
@@ -18,6 +18,18 @@
 
 D4 = {"A long and ridiculous {}".format(string_key): "This is a really really really long string that has to go i,side of a dictionary. It is soooo bad.", some_func("calling", "some", "stuff"): "This is a really really really long string that has to go inside of a dictionary. It is {soooo} bad (#{x}).".format(sooo="soooo", x=2), "A %s %s" % ("formatted", "string"): "This is a really really really long string that has to go inside of a dictionary. It is %s bad (#%d)." % ("soooo", 2)}
 
+L1 = ["The is a short string", "This is a really long string that can't possibly be expected to fit all together on one line. Also it is inside a list literal, so it's expected to be wrapped in parens when spliting to avoid implicit str concatenation.", short_call("arg", {"key": "value"}), "This is another really really (not really) long string that also can't be expected to fit on one line and is, like the other string, inside a list literal.", ("parens should be stripped for short string in list")]
+
+L2 = ["This is a really long string that can't be expected to fit in one line and is the only child of a list literal."]
+
+S1 = {"The is a short string", "This is a really long string that can't possibly be expected to fit all together on one line. Also it is inside a set literal, so it's expected to be wrapped in parens when spliting to avoid implicit str concatenation.", short_call("arg", {"key": "value"}), "This is another really really (not really) long string that also can't be expected to fit on one line and is, like the other string, inside a set literal.", ("parens should be stripped for short string in set")}
+
+S2 = {"This is a really long string that can't be expected to fit in one line and is the only child of a set literal."}
+
+T1 = ("The is a short string", "This is a really long string that can't possibly be expected to fit all together on one line. Also it is inside a tuple literal, so it's expected to be wrapped in parens when spliting to avoid implicit str concatenation.", short_call("arg", {"key": "value"}), "This is another really really (not really) long string that also can't be expected to fit on one line and is, like the other string, inside a tuple literal.", ("parens should be stripped for short string in list"))
+
+T2 = ("This is a really long string that can't be expected to fit in one line and is the only child of a tuple literal.",)
+
 func_with_keywords(my_arg, my_kwarg="Long keyword strings also need to be wrapped, but they will probably need to be handled a little bit differently.")
 
 bad_split1 = (
@@ -109,7 +121,7 @@
 
 comment_string = "Long lines with inline comments should have their comments appended to the reformatted string's enclosing right parentheses."  # This comment gets thrown to the top.
 
-arg_comment_string = print("Long lines with inline comments which are apart of (and not the only member of) an argument list should have their comments appended to the reformatted string's enclosing left parentheses.",  # This comment stays on the bottom.
+arg_comment_string = print("Long lines with inline comments which are apart of (and not the only member of) an argument list should have their comments appended to the reformatted string's enclosing left parentheses.",  # This comment gets thrown to the top.
     "Arg #2", "Arg #3", "Arg #4", "Arg #5")
 
 pragma_comment_string1 = "Lines which end with an inline pragma comment of the form `# <pragma>: <...>` should be left alone."  # noqa: E501
@@ -345,6 +357,71 @@ def foo():
     % ("soooo", 2),
 }
 
+L1 = [
+    "The is a short string",
+    (
+        "This is a really long string that can't possibly be expected to fit all"
+        " together on one line. Also it is inside a list literal, so it's expected to"
+        " be wrapped in parens when spliting to avoid implicit str concatenation."
+    ),
+    short_call("arg", {"key": "value"}),
+    (
+        "This is another really really (not really) long string that also can't be"
+        " expected to fit on one line and is, like the other string, inside a list"
+        " literal."
+    ),
+    "parens should be stripped for short string in list",
+]
+
+L2 = [
+    "This is a really long string that can't be expected to fit in one line and is the"
+    " only child of a list literal."
+]
+
+S1 = {
+    "The is a short string",
+    (
+        "This is a really long string that can't possibly be expected to fit all"
+        " together on one line. Also it is inside a set literal, so it's expected to be"
+        " wrapped in parens when spliting to avoid implicit str concatenation."
+    ),
+    short_call("arg", {"key": "value"}),
+    (
+        "This is another really really (not really) long string that also can't be"
+        " expected to fit on one line and is, like the other string, inside a set"
+        " literal."
+    ),
+    "parens should be stripped for short string in set",
+}
+
+S2 = {
+    "This is a really long string that can't be expected to fit in one line and is the"
+    " only child of a set literal."
+}
+
+T1 = (
+    "The is a short string",
+    (
+        "This is a really long string that can't possibly be expected to fit all"
+        " together on one line. Also it is inside a tuple literal, so it's expected to"
+        " be wrapped in parens when spliting to avoid implicit str concatenation."
+    ),
+    short_call("arg", {"key": "value"}),
+    (
+        "This is another really really (not really) long string that also can't be"
+        " expected to fit on one line and is, like the other string, inside a tuple"
+        " literal."
+    ),
+    "parens should be stripped for short string in list",
+)
+
+T2 = (
+    (
+        "This is a really long string that can't be expected to fit in one line and is"
+        " the only child of a tuple literal."
+    ),
+)
+
 func_with_keywords(
     my_arg,
     my_kwarg=(
@@ -487,7 +564,7 @@ def foo():
 arg_comment_string = print(
     "Long lines with inline comments which are apart of (and not the only member of) an"
     " argument list should have their comments appended to the reformatted string's"
-    " enclosing left parentheses.",  # This comment stays on the bottom.
+    " enclosing left parentheses.",  # This comment gets thrown to the top.
     "Arg #2",
     "Arg #3",
     "Arg #4",
diff --git a/tests/data/preview/long_strings__regression.py b/tests/data/preview/long_strings__regression.py
index 58ccc4ac0b1..634db46a5e0 100644
--- a/tests/data/preview/long_strings__regression.py
+++ b/tests/data/preview/long_strings__regression.py
@@ -763,20 +763,28 @@ def xxxx_xxx_xx_xxxxxxxxxx_xxxx_xxxxxxxxx(xxxx):
 
 some_dictionary = {
     "xxxxx006": [
-        "xxx-xxx"
-        " xxxxx3xxxx1xx2xxxxxxxxxxxxxx0xx6xxxxxxxxxx2xxxxxx9xxxxxxxxxx0xxxxx1xxx2x/xx9xx6+x+xxxxxxxxxxxxxx4xxxxxxxxxxxxxxxxxxxxx43xxx2xx2x4x++xxx6xxxxxxxxx+xxxxx/xx9x+xxxxxxxxxxxxxx8x15xxxxxxxxxxxxxxxxx82xx/xxxxxxxxxxxxxx/x5xxxxxxxxxxxxxx6xxxxxx74x4/xxx4x+xxxxxxxxx2xxxxxxxx87xxxxx4xxxxxxxx3xx0xxxxx4xxx1xx9xx5xxxxxxx/xxxxx5xx6xx4xxxx1x/x2xxxxxxxxxxxx64xxxxxxx1x0xx5xxxxxxxxxxxxxx=="
-        " xxxxx000 xxxxxxxxxx\n",
-        "xxx-xxx"
-        " xxxxx3xxxx1xx2xxxxxxxxxxxxxx6xxxxxxxxxxxxxx9xxxxxxxxxxxxx3xxx9xxxxxxxxxxxxxxxx0xxxxxxxxxxxxxxxxx2xxxx2xxx6xxxxx/xx54xxxxxxxxx4xxx3xxxxxx9xx3xxxxx39xxxxxxxxx5xx91xxxx7xxxxxx8xxxxxxxxxxxxxxxx9xxx93xxxxxxxxxxxxxxxxx7xxx8xx8xx4/x1xxxxx1x3xxxxxxxxxxxxx3xxxxxx9xx4xx4x7xxxxxxxxxxxxx1xxxxxxxxx7xxxxxxxxxxxxxx4xx6xxxxxxxxx9xxx7xxxx2xxxxxxxxxxxxxxxxxxxxxx8xxxxxxxxxxxxxxxxxxxx6xx=="
-        " xxxxx010 xxxxxxxxxx\n",
+        (
+            "xxx-xxx"
+            " xxxxx3xxxx1xx2xxxxxxxxxxxxxx0xx6xxxxxxxxxx2xxxxxx9xxxxxxxxxx0xxxxx1xxx2x/xx9xx6+x+xxxxxxxxxxxxxx4xxxxxxxxxxxxxxxxxxxxx43xxx2xx2x4x++xxx6xxxxxxxxx+xxxxx/xx9x+xxxxxxxxxxxxxx8x15xxxxxxxxxxxxxxxxx82xx/xxxxxxxxxxxxxx/x5xxxxxxxxxxxxxx6xxxxxx74x4/xxx4x+xxxxxxxxx2xxxxxxxx87xxxxx4xxxxxxxx3xx0xxxxx4xxx1xx9xx5xxxxxxx/xxxxx5xx6xx4xxxx1x/x2xxxxxxxxxxxx64xxxxxxx1x0xx5xxxxxxxxxxxxxx=="
+            " xxxxx000 xxxxxxxxxx\n"
+        ),
+        (
+            "xxx-xxx"
+            " xxxxx3xxxx1xx2xxxxxxxxxxxxxx6xxxxxxxxxxxxxx9xxxxxxxxxxxxx3xxx9xxxxxxxxxxxxxxxx0xxxxxxxxxxxxxxxxx2xxxx2xxx6xxxxx/xx54xxxxxxxxx4xxx3xxxxxx9xx3xxxxx39xxxxxxxxx5xx91xxxx7xxxxxx8xxxxxxxxxxxxxxxx9xxx93xxxxxxxxxxxxxxxxx7xxx8xx8xx4/x1xxxxx1x3xxxxxxxxxxxxx3xxxxxx9xx4xx4x7xxxxxxxxxxxxx1xxxxxxxxx7xxxxxxxxxxxxxx4xx6xxxxxxxxx9xxx7xxxx2xxxxxxxxxxxxxxxxxxxxxx8xxxxxxxxxxxxxxxxxxxx6xx=="
+            " xxxxx010 xxxxxxxxxx\n"
+        ),
     ],
     "xxxxx016": [
-        "xxx-xxx"
-        " xxxxx3xxxx1xx2xxxxxxxxxxxxxx0xx6xxxxxxxxxx2xxxxxx9xxxxxxxxxx0xxxxx1xxx2x/xx9xx6+x+xxxxxxxxxxxxxx4xxxxxxxxxxxxxxxxxxxxx43xxx2xx2x4x++xxx6xxxxxxxxx+xxxxx/xx9x+xxxxxxxxxxxxxx8x15xxxxxxxxxxxxxxxxx82xx/xxxxxxxxxxxxxx/x5xxxxxxxxxxxxxx6xxxxxx74x4/xxx4x+xxxxxxxxx2xxxxxxxx87xxxxx4xxxxxxxx3xx0xxxxx4xxx1xx9xx5xxxxxxx/xxxxx5xx6xx4xxxx1x/x2xxxxxxxxxxxx64xxxxxxx1x0xx5xxxxxxxxxxxxxx=="
-        " xxxxx000 xxxxxxxxxx\n",
-        "xxx-xxx"
-        " xxxxx3xxxx1xx2xxxxxxxxxxxxxx6xxxxxxxxxxxxxx9xxxxxxxxxxxxx3xxx9xxxxxxxxxxxxxxxx0xxxxxxxxxxxxxxxxx2xxxx2xxx6xxxxx/xx54xxxxxxxxx4xxx3xxxxxx9xx3xxxxx39xxxxxxxxx5xx91xxxx7xxxxxx8xxxxxxxxxxxxxxxx9xxx93xxxxxxxxxxxxxxxxx7xxx8xx8xx4/x1xxxxx1x3xxxxxxxxxxxxx3xxxxxx9xx4xx4x7xxxxxxxxxxxxx1xxxxxxxxx7xxxxxxxxxxxxxx4xx6xxxxxxxxx9xxx7xxxx2xxxxxxxxxxxxxxxxxxxxxx8xxxxxxxxxxxxxxxxxxxx6xx=="
-        " xxxxx010 xxxxxxxxxx\n",
+        (
+            "xxx-xxx"
+            " xxxxx3xxxx1xx2xxxxxxxxxxxxxx0xx6xxxxxxxxxx2xxxxxx9xxxxxxxxxx0xxxxx1xxx2x/xx9xx6+x+xxxxxxxxxxxxxx4xxxxxxxxxxxxxxxxxxxxx43xxx2xx2x4x++xxx6xxxxxxxxx+xxxxx/xx9x+xxxxxxxxxxxxxx8x15xxxxxxxxxxxxxxxxx82xx/xxxxxxxxxxxxxx/x5xxxxxxxxxxxxxx6xxxxxx74x4/xxx4x+xxxxxxxxx2xxxxxxxx87xxxxx4xxxxxxxx3xx0xxxxx4xxx1xx9xx5xxxxxxx/xxxxx5xx6xx4xxxx1x/x2xxxxxxxxxxxx64xxxxxxx1x0xx5xxxxxxxxxxxxxx=="
+            " xxxxx000 xxxxxxxxxx\n"
+        ),
+        (
+            "xxx-xxx"
+            " xxxxx3xxxx1xx2xxxxxxxxxxxxxx6xxxxxxxxxxxxxx9xxxxxxxxxxxxx3xxx9xxxxxxxxxxxxxxxx0xxxxxxxxxxxxxxxxx2xxxx2xxx6xxxxx/xx54xxxxxxxxx4xxx3xxxxxx9xx3xxxxx39xxxxxxxxx5xx91xxxx7xxxxxx8xxxxxxxxxxxxxxxx9xxx93xxxxxxxxxxxxxxxxx7xxx8xx8xx4/x1xxxxx1x3xxxxxxxxxxxxx3xxxxxx9xx4xx4x7xxxxxxxxxxxxx1xxxxxxxxx7xxxxxxxxxxxxxx4xx6xxxxxxxxx9xxx7xxxx2xxxxxxxxxxxxxxxxxxxxxx8xxxxxxxxxxxxxxxxxxxx6xx=="
+            " xxxxx010 xxxxxxxxxx\n"
+        ),
     ],
 }
 
diff --git a/tests/test_black.py b/tests/test_black.py
index 5da247b71b0..089e043d639 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -513,15 +513,15 @@ def err(msg: str, **kwargs: Any) -> None:
             report.check = True
             self.assertEqual(
                 unstyle(str(report)),
-                "2 files would be reformatted, 3 files would be left unchanged, 2 files"
-                " would fail to reformat.",
+                "2 files would be reformatted, 3 files would be left unchanged, 2"
+                " files would fail to reformat.",
             )
             report.check = False
             report.diff = True
             self.assertEqual(
                 unstyle(str(report)),
-                "2 files would be reformatted, 3 files would be left unchanged, 2 files"
-                " would fail to reformat.",
+                "2 files would be reformatted, 3 files would be left unchanged, 2"
+                " files would fail to reformat.",
             )
 
     def test_report_quiet(self) -> None:
@@ -607,15 +607,15 @@ def err(msg: str, **kwargs: Any) -> None:
             report.check = True
             self.assertEqual(
                 unstyle(str(report)),
-                "2 files would be reformatted, 3 files would be left unchanged, 2 files"
-                " would fail to reformat.",
+                "2 files would be reformatted, 3 files would be left unchanged, 2"
+                " files would fail to reformat.",
             )
             report.check = False
             report.diff = True
             self.assertEqual(
                 unstyle(str(report)),
-                "2 files would be reformatted, 3 files would be left unchanged, 2 files"
-                " would fail to reformat.",
+                "2 files would be reformatted, 3 files would be left unchanged, 2"
+                " files would fail to reformat.",
             )
 
     def test_report_normal(self) -> None:
@@ -704,15 +704,15 @@ def err(msg: str, **kwargs: Any) -> None:
             report.check = True
             self.assertEqual(
                 unstyle(str(report)),
-                "2 files would be reformatted, 3 files would be left unchanged, 2 files"
-                " would fail to reformat.",
+                "2 files would be reformatted, 3 files would be left unchanged, 2"
+                " files would fail to reformat.",
             )
             report.check = False
             report.diff = True
             self.assertEqual(
                 unstyle(str(report)),
-                "2 files would be reformatted, 3 files would be left unchanged, 2 files"
-                " would fail to reformat.",
+                "2 files would be reformatted, 3 files would be left unchanged, 2"
+                " files would fail to reformat.",
             )
 
     def test_lib2to3_parse(self) -> None:

From 2c90480e1a102ab0fac57737d2ba5143d82abed7 Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Tue, 30 Aug 2022 20:46:46 -0700
Subject: [PATCH 0600/1034] Use strict mypy checking (#3222)

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 .pre-commit-config.yaml   |  2 ++
 mypy.ini                  | 45 ++++++++++++++++++++++-----------------
 scripts/fuzz.py           |  5 ++++-
 src/blackd/middlewares.py |  4 ++--
 src/blib2to3/pytree.py    | 18 ++++++++--------
 tests/optional.py         |  2 +-
 tests/test_blackd.py      | 24 +++++++++++++--------
 7 files changed, 59 insertions(+), 41 deletions(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 87bb6e62987..0be8dc42890 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -49,6 +49,8 @@ repos:
           - types-typed-ast >= 1.4.1
           - click >= 8.1.0
           - platformdirs >= 2.1.0
+          - pytest
+          - hypothesis
 
   - repo: https://github.com/pre-commit/mirrors-prettier
     rev: v2.7.1
diff --git a/mypy.ini b/mypy.ini
index 244e8ae92f5..4811cc0be76 100644
--- a/mypy.ini
+++ b/mypy.ini
@@ -7,33 +7,40 @@ python_version=3.6
 mypy_path=src
 
 show_column_numbers=True
-
-# show error messages from unrelated files
-follow_imports=normal
-
-# suppress errors about unsatisfied imports
-ignore_missing_imports=True
+show_error_codes=True
 
 # be strict
-disallow_untyped_calls=True
-warn_return_any=True
-strict_optional=True
-warn_no_return=True
-warn_redundant_casts=True
-warn_unused_ignores=True
-disallow_any_generics=True
-no_implicit_optional=True
+strict=True
+
+# except for...
+no_implicit_reexport = False
 
 # Unreachable blocks have been an issue when compiling mypyc, let's try
 # to avoid 'em in the first place.
 warn_unreachable=True
 
-# The following are off by default.  Flip them on if you feel
-# adventurous.
-disallow_untyped_defs=True
-check_untyped_defs=True
-
 [mypy-black]
 # The following is because of `patch_click()`. Remove when
 # we drop Python 3.6 support.
 warn_unused_ignores=False
+
+[mypy-blib2to3.driver.*]
+ignore_missing_imports = True
+
+[mypy-IPython.*]
+ignore_missing_imports = True
+
+[mypy-colorama.*]
+ignore_missing_imports = True
+
+[mypy-pathspec.*]
+ignore_missing_imports = True
+
+[mypy-tokenize_rt.*]
+ignore_missing_imports = True
+
+[mypy-uvloop.*]
+ignore_missing_imports = True
+
+[mypy-_black_version.*]
+ignore_missing_imports = True
diff --git a/scripts/fuzz.py b/scripts/fuzz.py
index 83e02f45152..25362c927d4 100644
--- a/scripts/fuzz.py
+++ b/scripts/fuzz.py
@@ -85,5 +85,8 @@ def test_idempotent_any_syntatically_valid_python(
         pass
     else:
         test = test_idempotent_any_syntatically_valid_python
-        atheris.Setup(sys.argv, test.hypothesis.fuzz_one_input)
+        atheris.Setup(
+            sys.argv,
+            test.hypothesis.fuzz_one_input,  # type: ignore[attr-defined]
+        )
         atheris.Fuzz()
diff --git a/src/blackd/middlewares.py b/src/blackd/middlewares.py
index 7abde525bfd..e71f5082686 100644
--- a/src/blackd/middlewares.py
+++ b/src/blackd/middlewares.py
@@ -9,7 +9,7 @@
 
 
 def cors(allow_headers: Iterable[str]) -> Middleware:
-    @middleware
+    @middleware  # type: ignore[misc]
     async def impl(request: Request, handler: Handler) -> StreamResponse:
         is_options = request.method == "OPTIONS"
         is_preflight = is_options and "Access-Control-Request-Method" in request.headers
@@ -32,4 +32,4 @@ async def impl(request: Request, handler: Handler) -> StreamResponse:
 
         return resp
 
-    return impl  # type: ignore
+    return impl  # type: ignore[no-any-return]
diff --git a/src/blib2to3/pytree.py b/src/blib2to3/pytree.py
index 10b4690218e..15a1420ef7d 100644
--- a/src/blib2to3/pytree.py
+++ b/src/blib2to3/pytree.py
@@ -10,7 +10,7 @@
 There's also a pattern matching implementation here.
 """
 
-# mypy: allow-untyped-defs
+# mypy: allow-untyped-defs, allow-incomplete-defs
 
 from typing import (
     Any,
@@ -291,7 +291,7 @@ def __str__(self) -> Text:
         """
         return "".join(map(str, self.children))
 
-    def _eq(self, other) -> bool:
+    def _eq(self, other: Base) -> bool:
         """Compare two nodes for equality."""
         return (self.type, self.children) == (other.type, other.children)
 
@@ -326,7 +326,7 @@ def prefix(self) -> Text:
         return self.children[0].prefix
 
     @prefix.setter
-    def prefix(self, prefix) -> None:
+    def prefix(self, prefix: Text) -> None:
         if self.children:
             self.children[0].prefix = prefix
 
@@ -439,7 +439,7 @@ def __str__(self) -> Text:
         """
         return self._prefix + str(self.value)
 
-    def _eq(self, other) -> bool:
+    def _eq(self, other: "Leaf") -> bool:
         """Compare two nodes for equality."""
         return (self.type, self.value) == (other.type, other.value)
 
@@ -472,7 +472,7 @@ def prefix(self) -> Text:
         return self._prefix
 
     @prefix.setter
-    def prefix(self, prefix) -> None:
+    def prefix(self, prefix: Text) -> None:
         self.changed()
         self._prefix = prefix
 
@@ -618,7 +618,7 @@ def __init__(
         self.content = content
         self.name = name
 
-    def match(self, node: NL, results=None):
+    def match(self, node: NL, results=None) -> bool:
         """Override match() to insist on a leaf node."""
         if not isinstance(node, Leaf):
             return False
@@ -678,7 +678,7 @@ def __init__(
                 if isinstance(item, WildcardPattern):  # type: ignore[unreachable]
                     self.wildcards = True  # type: ignore[unreachable]
         self.type = type
-        self.content = newcontent
+        self.content = newcontent  # TODO: this is unbound when content is None
         self.name = name
 
     def _submatch(self, node, results=None) -> bool:
@@ -920,7 +920,7 @@ def _recursive_matches(self, nodes, count) -> Iterator[Tuple[int, _Results]]:
 
 
 class NegatedPattern(BasePattern):
-    def __init__(self, content: Optional[Any] = None) -> None:
+    def __init__(self, content: Optional[BasePattern] = None) -> None:
         """
         Initializer.
 
@@ -941,7 +941,7 @@ def match_seq(self, nodes, results=None) -> bool:
         # We only match an empty sequence of nodes in its entirety
         return len(nodes) == 0
 
-    def generate_matches(self, nodes) -> Iterator[Tuple[int, _Results]]:
+    def generate_matches(self, nodes: List[NL]) -> Iterator[Tuple[int, _Results]]:
         if self.content is None:
             # Return a match if there is an empty sequence
             if len(nodes) == 0:
diff --git a/tests/optional.py b/tests/optional.py
index 853ecaa2a43..8a39cc440a6 100644
--- a/tests/optional.py
+++ b/tests/optional.py
@@ -26,7 +26,7 @@
     from pytest import StashKey
 except ImportError:
     # pytest < 7
-    from _pytest.store import StoreKey as StashKey
+    from _pytest.store import StoreKey as StashKey  # type: ignore[no-redef]
 
 log = logging.getLogger(__name__)
 
diff --git a/tests/test_blackd.py b/tests/test_blackd.py
index 8e739063f6e..1da4ab702d2 100644
--- a/tests/test_blackd.py
+++ b/tests/test_blackd.py
@@ -1,6 +1,6 @@
 import re
 import sys
-from typing import Any
+from typing import TYPE_CHECKING, Any, Callable, TypeVar
 from unittest.mock import patch
 
 import pytest
@@ -19,16 +19,22 @@
     except ImportError as e:
         raise RuntimeError("Please install Black with the 'd' extra") from e
 
-    try:
-        from aiohttp.test_utils import unittest_run_loop
-    except ImportError:
-        # unittest_run_loop is unnecessary and a no-op since aiohttp 3.8, and aiohttp 4
-        # removed it. To maintain compatibility we can make our own no-op decorator.
-        def unittest_run_loop(func: Any, *args: Any, **kwargs: Any) -> Any:
-            return func
+    if TYPE_CHECKING:
+        F = TypeVar("F", bound=Callable[..., Any])
+
+        unittest_run_loop: Callable[[F], F] = lambda x: x
+    else:
+        try:
+            from aiohttp.test_utils import unittest_run_loop
+        except ImportError:
+            # unittest_run_loop is unnecessary and a no-op since aiohttp 3.8, and
+            # aiohttp 4 removed it. To maintain compatibility we can make our own
+            # no-op decorator.
+            def unittest_run_loop(func, *args, **kwargs):
+                return func
 
     @pytest.mark.blackd
-    class BlackDTestCase(AioHTTPTestCase):
+    class BlackDTestCase(AioHTTPTestCase):  # type: ignore[misc]
         def test_blackd_main(self) -> None:
             with patch("blackd.web.run_app"):
                 result = CliRunner().invoke(blackd.main, [])

From 767604e03f5e454ae5b5c268cd5831c672f46de8 Mon Sep 17 00:00:00 2001
From: Martin de La Gorce <martin.delagorce@gmail.com>
Date: Wed, 31 Aug 2022 20:47:42 +0100
Subject: [PATCH 0601/1034] Use .gitignore files in the initial source
 directories (#3237)

Solves https://github.com/psf/black/issues/2598 where Black wouldn't
use .gitignore at folder/.gitignore if you ran `black folder` for
example.

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 CHANGES.md            | 3 +++
 src/black/__init__.py | 5 +++++
 tests/test_black.py   | 7 +++++++
 3 files changed, 15 insertions(+)

diff --git a/CHANGES.md b/CHANGES.md
index a5ce3b1fbe2..6aa81a8f5c2 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -44,6 +44,9 @@
 - Black now uses the presence of debug f-strings to detect target version. (#3215)
 - Fix misdetection of project root and verbose logging of sources in cases involving
   `--stdin-filename` (#3216)
+- Immediate `.gitignore` files in source directories given on the command line are now
+  also respected, previously only `.gitignore` files in the project root and
+  automatically discovered directories were respected (#3237)
 
 ### Documentation
 
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 86a0b637442..ded4a736822 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -653,6 +653,11 @@ def get_sources(
             if exclude is None:
                 exclude = re_compile_maybe_verbose(DEFAULT_EXCLUDES)
                 gitignore = get_gitignore(root)
+                p_gitignore = get_gitignore(p)
+                # No need to use p's gitignore if it is identical to root's gitignore
+                # (i.e. root and p point to the same directory).
+                if gitignore != p_gitignore:
+                    gitignore += p_gitignore
             else:
                 gitignore = None
             sources.update(
diff --git a/tests/test_black.py b/tests/test_black.py
index 089e043d639..abd4d00b8e8 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -1990,6 +1990,13 @@ def test_nested_gitignore(self) -> None:
         )
         assert sorted(expected) == sorted(sources)
 
+    def test_nested_gitignore_directly_in_source_directory(self) -> None:
+        # https://github.com/psf/black/issues/2598
+        path = Path(DATA_DIR / "nested_gitignore_tests")
+        src = Path(path / "root" / "child")
+        expected = [src / "a.py", src / "c.py"]
+        assert_collected_sources([src], expected)
+
     def test_invalid_gitignore(self) -> None:
         path = THIS_DIR / "data" / "invalid_gitignore_tests"
         empty_config = path / "pyproject.toml"

From 7757078ecd84d349bb24ab61e79062ba50162ef9 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Wed, 31 Aug 2022 17:46:48 -0400
Subject: [PATCH 0602/1034] Improve & update release process to reflect recent
 changes (#3242)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Formalise release cadence guidelines
- Overhaul release steps to be easier to follow and more thorough
- Reorder changelog template to something more sensible
- Update release automation docs to reflect recent improvements (notably
  the addition of in-repo mypyc wheel builds)

Co-authored-by: Felix Hildén <felix.hilden@gmail.com>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 docs/contributing/release_process.md | 237 +++++++++++++++++----------
 docs/faq.md                          |   2 +
 docs/the_black_code_style/index.md   |   2 +
 3 files changed, 156 insertions(+), 85 deletions(-)

diff --git a/docs/contributing/release_process.md b/docs/contributing/release_process.md
index 6a4b8680808..be9b08a6c82 100644
--- a/docs/contributing/release_process.md
+++ b/docs/contributing/release_process.md
@@ -1,40 +1,85 @@
 # Release process
 
-_Black_ has had a lot of work automating its release process. This document sets out to
-explain what everything does and how to release _Black_ using said automation.
-
-## Cutting a Release
-
-To cut a release, you must be a _Black_ maintainer with `GitHub Release` creation
-access. Using this access, the release process is:
-
-1. Cut a new PR editing `CHANGES.md` and the docs to version the latest changes
+_Black_ has had a lot of work done into standardizing and automating its release
+process. This document sets out to explain how everything works and how to release
+_Black_ using said automation.
+
+## Release cadence
+
+**We aim to release whatever is on `main` every 1-2 months.** This ensures merged
+improvements and bugfixes are shipped to users reasonably quickly, while not massively
+fracturing the user-base with too many versions. This also keeps the workload on
+maintainers consistent and predictable.
+
+If there's not much new on `main` to justify a release, it's acceptable to skip a
+month's release. Ideally January releases should not be skipped because as per our
+[stability policy](labels/stability-policy), the first release in a new calendar year
+may make changes to the _stable_ style. While the policy applies to the first release
+(instead of only January releases), confining changes to the stable style to January
+will keep things predictable (and nicer) for users.
+
+Unless there is a serious regression or bug that requires immediate patching, **there
+should not be more than one release per month**. While version numbers are cheap,
+releases require a maintainer to both commit to do the actual cutting of a release, but
+also to be able to deal with the potential fallout post-release. Releasing more
+frequently than monthly nets rapidly diminishing returns.
+
+## Cutting a release
+
+**You must have `write` permissions for the _Black_ repository to cut a release.**
+
+The 10,000 foot view of the release process is that you prepare a release PR and then
+publish a [GitHub Release]. This triggers [release automation](#release-workflows) that
+builds all release artifacts and publishes them to the various platforms we publish to.
+
+To cut a release:
+
+1. Determine the release's version number
+   - **_Black_ follows the [CalVer] versioning standard using the `YY.M.N` format**
+     - So unless there already has been a release during this month, `N` should be `0`
+   - Example: the first release in January, 2022 → `22.1.0`
+1. File a PR editing `CHANGES.md` and the docs to version the latest changes
+   1. Replace the `## Unreleased` header with the version number
    1. Remove any empty sections for the current release
-   2. Add a new empty template for the next release (template below)
-   3. Example PR: [#2616](https://github.com/psf/black/pull/2616)
-   4. Example title: `Update CHANGES.md for XX.X release`
-2. Once the release PR is merged ensure all CI passes
-   1. If not, ensure there is an Issue open for the cause of failing CI (generally we'd
-      want this fixed before cutting a release)
-3. Open `CHANGES.md` and copy the _raw markdown_ of the latest changes to use in the
-   description of the GitHub Release.
-4. Go and [cut a release](https://github.com/psf/black/releases) using the GitHub UI so
-   that all workflows noted below are triggered.
-   1. The release version and tag should be the [CalVer](https://calver.org) version
-      _Black_ used for the current release e.g. `21.6` / `21.5b1`
-   2. _Black_ uses [setuptools scm](https://pypi.org/project/setuptools-scm/) to pull
-      the current version for the package builds and release.
-5. Once the release is cut, you're basically done. It's a good practice to go and watch
-   to make sure all the [GitHub Actions](https://github.com/psf/black/actions) pass,
-   although you should receive an email to your registered GitHub email address should
-   one fail.
-   1. You should see all the release workflows and lint/unittests workflows running on
-      the new tag in the Actions UI
-
-If anything fails, please go read the respective action's log output and configuration
-file to reverse engineer your way to a fix/soluton.
-
-## Changelog template
+   1. (_optional_) Read through and copy-edit the changelog (eg. by moving entries,
+      fixing typos, or rephrasing entries)
+   1. Add a new empty template for the next release above
+      ([template below](#changelog-template))
+   1. Update references to the latest version in
+      {doc}`/integrations/source_version_control` and
+      {doc}`/usage_and_configuration/the_basics`
+   - Example PR: [GH-3139]
+1. Once the release PR is merged, wait until all CI passes
+   - If CI does not pass, **stop** and investigate the failure(s) as generally we'd want
+     to fix failing CI before cutting a release
+1. [Draft a new GitHub Release][new-release]
+   1. Click `Choose a tag` and type in the version number, then select the
+      `Create new tag: YY.M.N on publish` option that appears
+   1. Verify that the new tag targets the `main` branch
+   1. You can leave the release title blank, GitHub will default to the tag name
+   1. Copy and paste the _raw changelog Markdown_ for the current release into the
+      description box
+1. Publish the GitHub Release, triggering [release automation](#release-workflows) that
+   will handle the rest
+1. At this point, you're basically done. It's good practice to go and [watch and verify
+   that all the release workflows pass][black-actions], although you will receive a
+   GitHub notification should something fail.
+   - If something fails, don't panic. Please go read the respective workflow's logs and
+     configuration file to reverse-engineer your way to a fix/solution.
+
+Congratulations! You've successfully cut a new release of _Black_. Go and stand up and
+take a break, you deserve it.
+
+```{important}
+Once the release artifacts reach PyPI, you may see new issues being filed indicating
+regressions. While regressions are not great, they don't automatically mean a hotfix
+release is warranted. Unless the regressions are serious and impact many users, a hotfix
+release is probably unnecessary.
+
+In the end, use your best judgement and ask other maintainers for their thoughts.
+```
+
+### Changelog template
 
 Use the following template for a clean changelog after the release:
 
@@ -45,7 +90,7 @@ Use the following template for a clean changelog after the release:
 
 <!-- Include any especially major or disruptive changes here -->
 
-### Style
+### Stable style
 
 <!-- Changes that affect Black's stable style -->
 
@@ -53,93 +98,115 @@ Use the following template for a clean changelog after the release:
 
 <!-- Changes that affect Black's preview style -->
 
-### _Blackd_
-
-<!-- Changes to blackd -->
-
 ### Configuration
 
 <!-- Changes to how Black can be configured -->
 
-### Documentation
+### Packaging
 
-<!-- Major changes to documentation and policies. Small docs changes
-     don't need a changelog entry. -->
+<!-- Changes to how Black is packaged, such as dependency requirements -->
 
-### Integrations
+### Parser
 
-<!-- For example, Docker, GitHub Actions, pre-commit, editors -->
+<!-- Changes to the parser or to version autodetection -->
+
+### Performance
+
+<!-- Changes that improve Black's performance. -->
 
 ### Output
 
 <!-- Changes to Black's terminal output and error messages -->
 
-### Packaging
-
-<!-- Changes to how Black is packaged, such as dependency requirements -->
+### _Blackd_
 
-### Parser
+<!-- Changes to blackd -->
 
-<!-- Changes to the parser or to version autodetection -->
+### Integrations
 
-### Performance
+<!-- For example, Docker, GitHub Actions, pre-commit, editors -->
 
-<!-- Changes that improve Black's performance. -->
+### Documentation
 
+<!-- Major changes to documentation and policies. Small docs changes
+     don't need a changelog entry. -->
 ```
 
 ## Release workflows
 
-All _Blacks_'s automation workflows use GitHub Actions. All workflows are therefore
-configured using `.yml` files in the `.github/workflows` directory of the _Black_
+All of _Black_'s release automation uses [GitHub Actions]. All workflows are therefore
+configured using YAML files in the `.github/workflows` directory of the _Black_
 repository.
 
+They are triggered by the publication of a [GitHub Release].
+
 Below are descriptions of our release workflows.
 
-### Docker
+### Publish to PyPI
+
+This is our main workflow. It builds an [sdist] and [wheels] to upload to PyPI where the
+vast majority of users will download Black from. It's divided into three job groups:
+
+#### sdist + pure wheel
 
-This workflow uses the QEMU powered `buildx` feature of docker to upload a `arm64` and
-`amd64`/`x86_64` build of the official _Black_ docker image™.
+This single job builds the sdist and pure Python wheel (i.e., a wheel that only contains
+Python code) using [build] and then uploads them to PyPI using [twine]. These artifacts
+are general-purpose and can be used on basically any platform supported by Python.
 
-- Currently this workflow uses an API Token associated with @cooperlees account
+#### mypyc wheels (…)
 
-### pypi_upload
+We use [mypyc] to compile _Black_ into a CPython C extension for significantly improved
+performance. Wheels built with mypyc are platform and Python version specific.
+[Supported platforms are documented in the FAQ](labels/mypyc-support).
 
-This workflow builds a Python
-[sdist](https://docs.python.org/3/distutils/sourcedist.html) and
-[wheel](https://pythonwheels.com) using the latest
-[setuptools](https://pypi.org/project/setuptools/) and
-[wheel](https://pypi.org/project/wheel/) modules.
+These matrix jobs use [cibuildwheel] which handles the complicated task of building C
+extensions for many environments for us. Since building these wheels is slow, there are
+multiple mypyc wheels jobs (hence the term "matrix") that build for a specific platform
+(as noted in the job name in parentheses).
 
-It will then use [twine](https://pypi.org/project/twine/) to upload both release formats
-to PyPI for general downloading of the _Black_ Python package. This is where
-[pip](https://pypi.org/project/pip/) looks by default.
+Like the previous job group, the built wheels are uploaded to PyPI using [twine].
 
-- Currently this workflow uses an API token associated with @ambv's PyPI account
+#### Update stable branch
 
-### Upload self-contained binaries
+So this job doesn't _really_ belong here, but updating the `stable` branch after the
+other PyPI jobs pass (they must pass for this job to start) makes the most sense. This
+saves us from remembering to update the branch sometime after cutting the release.
 
-This workflow builds self-contained binaries for multiple platforms. This allows people
-to download the executable for their platform and run _Black_ without a
-[Python Runtime](https://wiki.python.org/moin/PythonImplementations) installed.
+- _Currently this workflow uses an API token associated with @ambv's PyPI account_
 
-The created binaries are attached/stored on the associated
-[GitHub Release](https://github.com/psf/black/releases) for download over _IPv4 only_
-(GitHub still does not have IPv6 access 😢).
+### Publish executables
 
-## Moving the `stable` tag
+This workflow builds native executables for multiple platforms using [PyInstaller]. This
+allows people to download the executable for their platform and run _Black_ without a
+[Python runtime](https://wiki.python.org/moin/PythonImplementations) installed.
 
-_Black_ provides a stable tag for people who want to move along as _Black_ developers
-deem the newest version reliable. Here the _Black_ developers will move once the release
-has been problem free for at least ~24 hours from release. Given the large _Black_
-userbase we hear about bad bugs quickly. We do strive to continually improve our CI too.
+The created binaries are stored on the associated GitHub Release for download over _IPv4
+only_ (GitHub still does not have IPv6 access 😢).
 
-### Tag moving process
+### docker
 
-#### stable
+This workflow uses the QEMU powered `buildx` feature of Docker to upload an `arm64` and
+`amd64`/`x86_64` build of the official _Black_ Docker image™.
 
-From a rebased `main` checkout:
+- _Currently this workflow uses an API Token associated with @cooperlees account_
+
+```{note}
+This also runs on each push to `main`.
+```
 
-1. `git tag -f stable VERSION_TAG`
-   1. e.g. `git tag -f stable 21.5b1`
-1. `git push --tags -f`
+[black-actions]: https://github.com/psf/black/actions
+[build]: https://pypa-build.readthedocs.io/
+[calver]: https://calver.org
+[cibuildwheel]: https://cibuildwheel.readthedocs.io/
+[gh-3139]: https://github.com/psf/black/pull/3139
+[github actions]: https://github.com/features/actions
+[github release]: https://github.com/psf/black/releases
+[new-release]: https://github.com/psf/black/releases/new
+[mypyc]: https://mypyc.readthedocs.io/
+[mypyc-platform-support]:
+  /faq.html#what-is-compiled-yes-no-all-about-in-the-version-output
+[pyinstaller]: https://www.pyinstaller.org/
+[sdist]:
+  https://packaging.python.org/en/latest/glossary/#term-Source-Distribution-or-sdist
+[twine]: https://github.com/features/actions
+[wheels]: https://packaging.python.org/en/latest/glossary/#term-Wheel
diff --git a/docs/faq.md b/docs/faq.md
index b2fe42de282..aeb9634789f 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -114,6 +114,8 @@ errors is not a goal. It can format all code accepted by CPython (if you find an
 where that doesn't hold, please report a bug!), but it may also format some code that
 CPython doesn't accept.
 
+(labels/mypyc-support)=
+
 ## What is `compiled: yes/no` all about in the version output?
 
 While _Black_ is indeed a pure Python project, we use [mypyc] to compile _Black_ into a
diff --git a/docs/the_black_code_style/index.md b/docs/the_black_code_style/index.md
index c7f29af6c73..e5967be2db4 100644
--- a/docs/the_black_code_style/index.md
+++ b/docs/the_black_code_style/index.md
@@ -19,6 +19,8 @@ style aspects and details might change according to the stability policy present
 below. Ongoing style considerations are tracked on GitHub with the
 [design](https://github.com/psf/black/labels/T%3A%20design) issue label.
 
+(labels/stability-policy)=
+
 ## Stability Policy
 
 The following policy applies for the _Black_ code style, in non pre-release versions of

From 0019261abcf6d9e564ba32d3cc15534b9026f29e Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Wed, 31 Aug 2022 17:56:47 -0400
Subject: [PATCH 0603/1034] Update stable branch after publishing to PyPI
 (#3223)

We've decided to a) convert stable back into a branch and b) to update
it immediately as part of the release process. We may as well automate
it. And about going back to a branch ...

Git tags are not the right tool, at all[^1]. They come with the
expectation that they will never change. Things will not work as
expected if they do change, doubly so if they change regularly. Once
you pull stable from the remote and it's copied in your local
repository, no matter how many times you run git pull you'll never see
it get updated automatically. Your only recourse is to delete the tag
via `git tag -d stable` before pulling.

This gets annoying really quickly since stable is supposed to be the
solution for folks "who want to move along as Black developers deem
the newest version reliable."[^2] See this comment for how this impacts
users using our Vim plugin[^3]. It also affects us developers[^4]. If
you have stable locally, once we cut a new release and update the stable
tag, a simple `git pull` / `git fetch` will not pull down the updated
stable tag. Unless you remember to delete stable before pulling, stable
will become stale and useless.

You can argue this is a good thing ("people should explicitly opt into
updating stable"), but IMO it does not match user expectations nor
developer expectations[^5]. Especially since not all our integrations
that use stable are bound by this security measure, for example our
GitHub Action (since it does a clean fetch of the repository every time
it's used). I believe consistency would be good here.

Finally, ever since we switched to a tag, we've been facing issues with
ReadTheDocs not picking up updates to stable unless we force a rebuild.
The initial rebuild on the stable update just pulls the commit the tag
previously pointed to. I'm not sure if switching back to a branch will
fix this, but I'd wager it will.

[^1]: https://git-scm.com/docs/git-tag#_on_re_tagging

[^2]: https://black.readthedocs.io/en/stable/contributing/release_process.html#moving-the-stable-tag

[^3]: https://github.com/psf/black/issues/2503#issuecomment-1196357379

[^4]: In fairness, most folks working on Black probably don't use the
      `stable` ref anyway, especially us maintainers who'd know what is
      the latest version by heart, but it'd still be nice to make it
      usable for local dev though.

[^5]: Also what benefit does a `stable` ref have over explicit version
      tags like `22.6.0`? If you're going to opt into some odd pin
      mechanism, might as well use explicit version tags for clarity
      and consistency.
---
 .github/workflows/pypi_upload.yml | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/.github/workflows/pypi_upload.yml b/.github/workflows/pypi_upload.yml
index 31a83266345..d52f41a4939 100644
--- a/.github/workflows/pypi_upload.yml
+++ b/.github/workflows/pypi_upload.yml
@@ -74,3 +74,22 @@ jobs:
         env:
           TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
         run: pipx run twine upload --verbose -u '__token__' wheelhouse/*.whl
+
+  update-stable-branch:
+    name: Update stable branch
+    needs: [main, mypyc]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout stable branch
+        uses: actions/checkout@v3
+        with:
+          ref: stable
+          fetch-depth: 0
+
+      - name: Update stable branch to release tag & push
+        run: |
+          git reset --hard ${{ github.event.release.tag_name }}
+          git push

From 2018e667a6a36ee3fbfa8041cd36512f92f60d49 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Wed, 31 Aug 2022 18:39:54 -0400
Subject: [PATCH 0604/1034] Prepare docs for release 22.8.0 (#3248)

---
 CHANGES.md                                  | 85 +++++++++++++--------
 docs/integrations/source_version_control.md |  2 +-
 docs/usage_and_configuration/the_basics.md  |  2 +-
 3 files changed, 57 insertions(+), 32 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 6aa81a8f5c2..7c7be98f716 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -6,20 +6,68 @@
 
 <!-- Include any especially major or disruptive changes here -->
 
-### Style
+### Stable style
 
 <!-- Changes that affect Black's stable style -->
 
+### Preview style
+
+<!-- Changes that affect Black's preview style -->
+
+### Configuration
+
+<!-- Changes to how Black can be configured -->
+
+### Packaging
+
+<!-- Changes to how Black is packaged, such as dependency requirements -->
+
+### Parser
+
+<!-- Changes to the parser or to version autodetection -->
+
+### Performance
+
+<!-- Changes that improve Black's performance. -->
+
+### Output
+
+<!-- Changes to Black's terminal output and error messages -->
+
+### _Blackd_
+
+<!-- Changes to blackd -->
+
+### Integrations
+
+<!-- For example, Docker, GitHub Actions, pre-commit, editors -->
+
+### Documentation
+
+<!-- Major changes to documentation and policies. Small docs changes
+     don't need a changelog entry. -->
+
+## 22.8.0
+
+### Highlights
+
+- Python 3.11 is now supported, except for _blackd_ as aiohttp does not support 3.11 as
+  of publishing (#3234)
+- This is the last release that supports running _Black_ on Python 3.6 (formatting 3.6
+  code will continue to be supported until further notice)
+- Reword the stability policy to say that we may, in rare cases, make changes that
+  affect code that was not previously formatted by _Black_ (#3155)
+
+### Stable style
+
 - Fix an infinite loop when using `# fmt: on/off` in the middle of an expression or code
   block (#3158)
-- Fix incorrect handling of `# fmt: skip` on colon `:` lines. (#3148)
+- Fix incorrect handling of `# fmt: skip` on colon (`:`) lines (#3148)
 - Comments are no longer deleted when a line had spaces removed around power operators
   (#2874)
 
 ### Preview style
 
-<!-- Changes that affect Black's preview style -->
-
 - Single-character closing docstring quotes are no longer moved to their own line as
   this is invalid. This was a bug introduced in version 22.6.0. (#3166)
 - `--skip-string-normalization` / `-S` now prevents docstring prefixes from being
@@ -33,15 +81,11 @@
 
 ### _Blackd_
 
-<!-- Changes to blackd -->
-
-- `blackd` now supports preview style via `X-Preview` header (#3217)
+- `blackd` now supports enabling the preview style via the `X-Preview` header (#3217)
 
 ### Configuration
 
-<!-- Changes to how Black can be configured -->
-
-- Black now uses the presence of debug f-strings to detect target version. (#3215)
+- Black now uses the presence of debug f-strings to detect target version (#3215)
 - Fix misdetection of project root and verbose logging of sources in cases involving
   `--stdin-filename` (#3216)
 - Immediate `.gitignore` files in source directories given on the command line are now
@@ -50,48 +94,29 @@
 
 ### Documentation
 
-<!-- Major changes to documentation and policies. Small docs changes
-     don't need a changelog entry. -->
-
-- Reword the stability policy to say that we may, in rare cases, make changes that
-  affect code that was not previously formatted by _Black_ (#3155)
 - Recommend using BlackConnect in IntelliJ IDEs (#3150)
 
 ### Integrations
 
-<!-- For example, Docker, GitHub Actions, pre-commit, editors -->
-
 - Vim plugin: prefix messages with `Black: ` so it's clear they come from Black (#3194)
 - Docker: changed to a /opt/venv installation + added to PATH to be available to
   non-root users (#3202)
 
 ### Output
 
-<!-- Changes to Black's terminal output and error messages -->
-
 - Change from deprecated `asyncio.get_event_loop()` to create our event loop which
   removes DeprecationWarning (#3164)
-- Remove logging from internal `blib2to3` library since it regularily emits error logs
+- Remove logging from internal `blib2to3` library since it regularly emits error logs
   about failed caching that can and should be ignored (#3193)
 
-### Packaging
-
-<!-- Changes to how Black is packaged, such as dependency requirements -->
-
-- Python 3.11 is now supported, except for `blackd` (#3234)
-
 ### Parser
 
-<!-- Changes to the parser or to version autodetection -->
-
 - Type comments are now included in the AST equivalence check consistently so accidental
   deletion raises an error. Though type comments can't be tracked when running on PyPy
   3.7 due to standard library limitations. (#2874)
 
 ### Performance
 
-<!-- Changes that improve Black's performance. -->
-
 - Reduce Black's startup time when formatting a single file by 15-30% (#3211)
 
 ## 22.6.0
diff --git a/docs/integrations/source_version_control.md b/docs/integrations/source_version_control.md
index e897cf669fc..31d0df27273 100644
--- a/docs/integrations/source_version_control.md
+++ b/docs/integrations/source_version_control.md
@@ -7,7 +7,7 @@ Use [pre-commit](https://pre-commit.com/). Once you
 ```yaml
 repos:
   - repo: https://github.com/psf/black
-    rev: 22.6.0
+    rev: 22.8.0
     hooks:
       - id: black
         # It is recommended to specify the latest version of Python
diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index 4c358742674..2dc2a14f91a 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -173,7 +173,7 @@ You can check the version of _Black_ you have installed using the `--version` fl
 
 ```console
 $ black --version
-black, version 22.6.0
+black, version 22.8.0
 ```
 
 An option to require a specific version to be running is also provided.

From 095fe0d649541636d7011e779214a146b4f32895 Mon Sep 17 00:00:00 2001
From: James Salvatore <james.c.salvatore.services@gmail.com>
Date: Wed, 31 Aug 2022 23:25:13 -0500
Subject: [PATCH 0605/1034] docs: adds ExitStack alternative to future_style.md
 (#3247)

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 docs/conf.py                              |  2 +-
 docs/the_black_code_style/future_style.md | 13 +++++++++++++
 2 files changed, 14 insertions(+), 1 deletion(-)

diff --git a/docs/conf.py b/docs/conf.py
index 8da9c39ac41..7fc4f8f589e 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -55,7 +55,7 @@ def make_pypi_svg(version: str) -> None:
 # -- General configuration ---------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
-needs_sphinx = "3.0"
+needs_sphinx = "4.4"
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
diff --git a/docs/the_black_code_style/future_style.md b/docs/the_black_code_style/future_style.md
index fab4bca120e..a17d9a10673 100644
--- a/docs/the_black_code_style/future_style.md
+++ b/docs/the_black_code_style/future_style.md
@@ -34,6 +34,19 @@ with \
 Although when the target version is Python 3.9 or higher, _Black_ will use parentheses
 instead since they're allowed in Python 3.9 and higher.
 
+An alternative to consider if the backslashes in the above formatting are undesirable is
+to use {external:py:obj}`contextlib.ExitStack` to combine context managers in the
+following way:
+
+```python
+with contextlib.ExitStack() as exit_stack:
+    cm1 = exit_stack.enter_context(make_context_manager(1))
+    cm2 = exit_stack.enter_context(make_context_manager(2))
+    cm3 = exit_stack.enter_context(make_context_manager(3))
+    cm4 = exit_stack.enter_context(make_context_manager(4))
+    ...
+```
+
 ## Preview style
 
 Experimental, potentially disruptive style changes are gathered under the `--preview`

From 92c93a278036870a76740d5b0b8f06504925e7dc Mon Sep 17 00:00:00 2001
From: PeterGrossmann <peter.grossmann@synoptics.de>
Date: Thu, 1 Sep 2022 18:39:47 +0200
Subject: [PATCH 0606/1034] Add preview flag to Vim plugin (#3246)

This allows the configuration of the --preview flag in the Vim plugin.
---
 CHANGES.md                   | 1 +
 autoload/black.vim           | 2 ++
 docs/integrations/editors.md | 1 +
 plugin/black.vim             | 3 +++
 4 files changed, 7 insertions(+)

diff --git a/CHANGES.md b/CHANGES.md
index 7c7be98f716..25c3d4889a0 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -101,6 +101,7 @@
 - Vim plugin: prefix messages with `Black: ` so it's clear they come from Black (#3194)
 - Docker: changed to a /opt/venv installation + added to PATH to be available to
   non-root users (#3202)
+- Vim plugin: add flag (`g:black_preview`) to enable/disable the preview style (#3246)
 
 ### Output
 
diff --git a/autoload/black.vim b/autoload/black.vim
index ed657be7bd3..e87a1e4edfa 100644
--- a/autoload/black.vim
+++ b/autoload/black.vim
@@ -30,6 +30,7 @@ FLAGS = [
   Flag(name="skip_string_normalization", cast=strtobool),
   Flag(name="quiet", cast=strtobool),
   Flag(name="skip_magic_trailing_comma", cast=strtobool),
+  Flag(name="preview", cast=strtobool),
 ]
 
 
@@ -145,6 +146,7 @@ def Black(**kwargs):
     string_normalization=not configs["skip_string_normalization"],
     is_pyi=vim.current.buffer.name.endswith('.pyi'),
     magic_trailing_comma=not configs["skip_magic_trailing_comma"],
+    preview=configs["preview"],
     **black_kwargs,
   )
   quiet = configs["quiet"]
diff --git a/docs/integrations/editors.md b/docs/integrations/editors.md
index 07bf672f4fd..318e0e295d0 100644
--- a/docs/integrations/editors.md
+++ b/docs/integrations/editors.md
@@ -113,6 +113,7 @@ Configuration:
 - `g:black_skip_string_normalization` (defaults to `0`)
 - `g:black_virtualenv` (defaults to `~/.vim/black` or `~/.local/share/nvim/black`)
 - `g:black_quiet` (defaults to `0`)
+- `g:black_preview` (defaults to `0`)
 
 To install with [vim-plug](https://github.com/junegunn/vim-plug):
 
diff --git a/plugin/black.vim b/plugin/black.vim
index 3fc11fe9e8d..fb70424b0ef 100644
--- a/plugin/black.vim
+++ b/plugin/black.vim
@@ -63,6 +63,9 @@ endif
 if !exists("g:black_target_version")
   let g:black_target_version = ""
 endif
+if !exists("g:black_preview")
+  let g:black_preview = 0
+endif
 
 function BlackComplete(ArgLead, CmdLine, CursorPos)
   return [

From 062e644aae4299a320aeac59085df4c020ba6c81 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Mon, 5 Sep 2022 16:27:05 -0400
Subject: [PATCH 0607/1034] Mitigate deprecation of aiohttp's `@middleware`
 decorator (#3259)

This is deprecated since aiohttp 4.0. If it doesn't exist just define a
no-op decorator that does nothing (after the other aiohttp imports
though!). By doing this, it's safe to ignore the DeprecationWarning
without needing to require the latest aiohttp once they remove
`@middleware`.
---
 pyproject.toml            |  3 +++
 src/blackd/middlewares.py | 18 ++++++++++++++----
 2 files changed, 17 insertions(+), 4 deletions(-)

diff --git a/pyproject.toml b/pyproject.toml
index 813e86b2e93..849891f8798 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -105,6 +105,9 @@ filterwarnings = [
     # this is mitigated by a try/catch in https://github.com/psf/black/pull/2974/
     # this ignore can be removed when support for aiohttp 3.7 is dropped.
     '''ignore:Decorator `@unittest_run_loop` is no longer needed in aiohttp 3\.8\+:DeprecationWarning''',
+    # this is mitigated by a try/catch in https://github.com/psf/black/pull/3198/
+    # this ignore can be removed when support for aiohttp 3.x is dropped.
+    '''ignore:Middleware decorator is deprecated since 4\.0 and its behaviour is default, you can simply remove this decorator:DeprecationWarning''',
     # this is mitigated by https://github.com/python/cpython/issues/79071 in python 3.8+
     # this ignore can be removed when support for 3.7 is dropped.
     '''ignore:Bare functions are deprecated, use async ones:DeprecationWarning''',
diff --git a/src/blackd/middlewares.py b/src/blackd/middlewares.py
index e71f5082686..370e0ae222e 100644
--- a/src/blackd/middlewares.py
+++ b/src/blackd/middlewares.py
@@ -1,15 +1,25 @@
-from typing import Awaitable, Callable, Iterable
+from typing import TYPE_CHECKING, Any, Awaitable, Callable, Iterable, TypeVar
 
-from aiohttp.web_middlewares import middleware
 from aiohttp.web_request import Request
 from aiohttp.web_response import StreamResponse
 
+if TYPE_CHECKING:
+    F = TypeVar("F", bound=Callable[..., Any])
+    middleware: Callable[[F], F]
+else:
+    try:
+        from aiohttp.web_middlewares import middleware
+    except ImportError:
+        # @middleware is deprecated and its behaviour is the default since aiohttp 4.0
+        # so if it doesn't exist anymore, define a no-op for forward compatibility.
+        middleware = lambda x: x  # noqa: E731
+
 Handler = Callable[[Request], Awaitable[StreamResponse]]
 Middleware = Callable[[Request, Handler], Awaitable[StreamResponse]]
 
 
 def cors(allow_headers: Iterable[str]) -> Middleware:
-    @middleware  # type: ignore[misc]
+    @middleware
     async def impl(request: Request, handler: Handler) -> StreamResponse:
         is_options = request.method == "OPTIONS"
         is_preflight = is_options and "Access-Control-Request-Method" in request.headers
@@ -32,4 +42,4 @@ async def impl(request: Request, handler: Handler) -> StreamResponse:
 
         return resp
 
-    return impl  # type: ignore[no-any-return]
+    return impl

From 383b228a1690d9c15ce97bd2e01874596fbf1288 Mon Sep 17 00:00:00 2001
From: Cooper Lees <cooper@fb.com>
Date: Tue, 6 Sep 2022 08:27:39 +1000
Subject: [PATCH 0608/1034] Move 3.11 tests to install aiohttp without C
 extensions (#3258)

* Move 311 tests to install aiohttp without C extensions

- Configure tox to install aiohttp without extensions
  - i.e. use `AIOHTTP_NO_EXTENSIONS=1` for pip install
  - This allows us to reenable blackd tests that use aiohttp testing helpers etc.
- Had to ignore `cgi` module deprecation warning
  - Filed issue for aiohttp to fix: https://github.com/aio-libs/aiohttp/issues/6905

Test:
- `/tmp/tb/bin/tox -e 311`

* Fix formatting + linting

* Add latest aiohttp for loop fix + Try to exempt deprecation warning but failed - will ask for help

* Remove unnecessary warning ignore

Co-authored-by: Cooper Ry Lees <me@wcooperlees.com>
Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 .github/workflows/test-311.yml |   2 +-
 pyproject.toml                 |   3 +
 tests/test_blackd.py           | 389 ++++++++++++++++-----------------
 tox.ini                        |   8 +-
 4 files changed, 203 insertions(+), 199 deletions(-)

diff --git a/.github/workflows/test-311.yml b/.github/workflows/test-311.yml
index e23a67e89eb..c2da2465ad5 100644
--- a/.github/workflows/test-311.yml
+++ b/.github/workflows/test-311.yml
@@ -1,4 +1,4 @@
-name: Partially test 3.11 dev
+name: Test 3.11 without aiohttp extensions
 
 on:
   push:
diff --git a/pyproject.toml b/pyproject.toml
index 849891f8798..566462c9b36 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -111,4 +111,7 @@ filterwarnings = [
     # this is mitigated by https://github.com/python/cpython/issues/79071 in python 3.8+
     # this ignore can be removed when support for 3.7 is dropped.
     '''ignore:Bare functions are deprecated, use async ones:DeprecationWarning''',
+    # aiohttp is using deprecated cgi modules - Safe to remove when fixed:
+    # https://github.com/aio-libs/aiohttp/issues/6905
+    '''ignore:'cgi' is deprecated and slated for removal in Python 3.13:DeprecationWarning''',
 ]
diff --git a/tests/test_blackd.py b/tests/test_blackd.py
index 1da4ab702d2..511bd86441d 100644
--- a/tests/test_blackd.py
+++ b/tests/test_blackd.py
@@ -1,5 +1,4 @@
 import re
-import sys
 from typing import TYPE_CHECKING, Any, Callable, TypeVar
 from unittest.mock import patch
 
@@ -8,207 +7,205 @@
 
 from tests.util import DETERMINISTIC_HEADER, read_data
 
-LESS_THAN_311 = sys.version_info < (3, 11)
+try:
+    from aiohttp import web
+    from aiohttp.test_utils import AioHTTPTestCase
 
-if LESS_THAN_311:  # noqa: C901
-    try:
-        from aiohttp import web
-        from aiohttp.test_utils import AioHTTPTestCase
-
-        import blackd
-    except ImportError as e:
-        raise RuntimeError("Please install Black with the 'd' extra") from e
-
-    if TYPE_CHECKING:
-        F = TypeVar("F", bound=Callable[..., Any])
-
-        unittest_run_loop: Callable[[F], F] = lambda x: x
-    else:
-        try:
-            from aiohttp.test_utils import unittest_run_loop
-        except ImportError:
-            # unittest_run_loop is unnecessary and a no-op since aiohttp 3.8, and
-            # aiohttp 4 removed it. To maintain compatibility we can make our own
-            # no-op decorator.
-            def unittest_run_loop(func, *args, **kwargs):
-                return func
-
-    @pytest.mark.blackd
-    class BlackDTestCase(AioHTTPTestCase):  # type: ignore[misc]
-        def test_blackd_main(self) -> None:
-            with patch("blackd.web.run_app"):
-                result = CliRunner().invoke(blackd.main, [])
-                if result.exception is not None:
-                    raise result.exception
-                self.assertEqual(result.exit_code, 0)
-
-        async def get_application(self) -> web.Application:
-            return blackd.make_app()
-
-        @unittest_run_loop
-        async def test_blackd_request_needs_formatting(self) -> None:
-            response = await self.client.post("/", data=b"print('hello world')")
-            self.assertEqual(response.status, 200)
-            self.assertEqual(response.charset, "utf8")
-            self.assertEqual(await response.read(), b'print("hello world")\n')
-
-        @unittest_run_loop
-        async def test_blackd_request_no_change(self) -> None:
-            response = await self.client.post("/", data=b'print("hello world")\n')
-            self.assertEqual(response.status, 204)
-            self.assertEqual(await response.read(), b"")
-
-        @unittest_run_loop
-        async def test_blackd_request_syntax_error(self) -> None:
-            response = await self.client.post("/", data=b"what even ( is")
-            self.assertEqual(response.status, 400)
-            content = await response.text()
-            self.assertTrue(
-                content.startswith("Cannot parse"),
-                msg=f"Expected error to start with 'Cannot parse', got {repr(content)}",
-            )
+    import blackd
+except ImportError as e:
+    raise RuntimeError("Please install Black with the 'd' extra") from e
 
-        @unittest_run_loop
-        async def test_blackd_unsupported_version(self) -> None:
-            response = await self.client.post(
-                "/", data=b"what", headers={blackd.PROTOCOL_VERSION_HEADER: "2"}
-            )
-            self.assertEqual(response.status, 501)
+if TYPE_CHECKING:
+    F = TypeVar("F", bound=Callable[..., Any])
 
-        @unittest_run_loop
-        async def test_blackd_supported_version(self) -> None:
-            response = await self.client.post(
-                "/", data=b"what", headers={blackd.PROTOCOL_VERSION_HEADER: "1"}
-            )
-            self.assertEqual(response.status, 200)
-
-        @unittest_run_loop
-        async def test_blackd_invalid_python_variant(self) -> None:
-            async def check(header_value: str, expected_status: int = 400) -> None:
-                response = await self.client.post(
-                    "/",
-                    data=b"what",
-                    headers={blackd.PYTHON_VARIANT_HEADER: header_value},
-                )
-                self.assertEqual(response.status, expected_status)
-
-            await check("lol")
-            await check("ruby3.5")
-            await check("pyi3.6")
-            await check("py1.5")
-            await check("2")
-            await check("2.7")
-            await check("py2.7")
-            await check("2.8")
-            await check("py2.8")
-            await check("3.0")
-            await check("pypy3.0")
-            await check("jython3.4")
-
-        @unittest_run_loop
-        async def test_blackd_pyi(self) -> None:
-            source, expected = read_data("miscellaneous", "stub.pyi")
-            response = await self.client.post(
-                "/", data=source, headers={blackd.PYTHON_VARIANT_HEADER: "pyi"}
-            )
-            self.assertEqual(response.status, 200)
-            self.assertEqual(await response.text(), expected)
-
-        @unittest_run_loop
-        async def test_blackd_diff(self) -> None:
-            diff_header = re.compile(
-                r"(In|Out)\t\d\d\d\d-\d\d-\d\d \d\d:\d\d:\d\d\.\d\d\d\d\d\d \+\d\d\d\d"
-            )
-
-            source, _ = read_data("miscellaneous", "blackd_diff")
-            expected, _ = read_data("miscellaneous", "blackd_diff.diff")
-
-            response = await self.client.post(
-                "/", data=source, headers={blackd.DIFF_HEADER: "true"}
-            )
-            self.assertEqual(response.status, 200)
-
-            actual = await response.text()
-            actual = diff_header.sub(DETERMINISTIC_HEADER, actual)
-            self.assertEqual(actual, expected)
-
-        @unittest_run_loop
-        async def test_blackd_python_variant(self) -> None:
-            code = (
-                "def f(\n"
-                "    and_has_a_bunch_of,\n"
-                "    very_long_arguments_too,\n"
-                "    and_lots_of_them_as_well_lol,\n"
-                "    **and_very_long_keyword_arguments\n"
-                "):\n"
-                "    pass\n"
-            )
-
-            async def check(header_value: str, expected_status: int) -> None:
-                response = await self.client.post(
-                    "/", data=code, headers={blackd.PYTHON_VARIANT_HEADER: header_value}
-                )
-                self.assertEqual(
-                    response.status, expected_status, msg=await response.text()
-                )
-
-            await check("3.6", 200)
-            await check("py3.6", 200)
-            await check("3.6,3.7", 200)
-            await check("3.6,py3.7", 200)
-            await check("py36,py37", 200)
-            await check("36", 200)
-            await check("3.6.4", 200)
-            await check("3.4", 204)
-            await check("py3.4", 204)
-            await check("py34,py36", 204)
-            await check("34", 204)
-
-        @unittest_run_loop
-        async def test_blackd_line_length(self) -> None:
-            response = await self.client.post(
-                "/", data=b'print("hello")\n', headers={blackd.LINE_LENGTH_HEADER: "7"}
-            )
-            self.assertEqual(response.status, 200)
-
-        @unittest_run_loop
-        async def test_blackd_invalid_line_length(self) -> None:
+    unittest_run_loop: Callable[[F], F] = lambda x: x
+else:
+    try:
+        from aiohttp.test_utils import unittest_run_loop
+    except ImportError:
+        # unittest_run_loop is unnecessary and a no-op since aiohttp 3.8, and
+        # aiohttp 4 removed it. To maintain compatibility we can make our own
+        # no-op decorator.
+        def unittest_run_loop(func, *args, **kwargs):
+            return func
+
+
+@pytest.mark.blackd
+class BlackDTestCase(AioHTTPTestCase):  # type: ignore[misc]
+    def test_blackd_main(self) -> None:
+        with patch("blackd.web.run_app"):
+            result = CliRunner().invoke(blackd.main, [])
+            if result.exception is not None:
+                raise result.exception
+            self.assertEqual(result.exit_code, 0)
+
+    async def get_application(self) -> web.Application:
+        return blackd.make_app()
+
+    @unittest_run_loop
+    async def test_blackd_request_needs_formatting(self) -> None:
+        response = await self.client.post("/", data=b"print('hello world')")
+        self.assertEqual(response.status, 200)
+        self.assertEqual(response.charset, "utf8")
+        self.assertEqual(await response.read(), b'print("hello world")\n')
+
+    @unittest_run_loop
+    async def test_blackd_request_no_change(self) -> None:
+        response = await self.client.post("/", data=b'print("hello world")\n')
+        self.assertEqual(response.status, 204)
+        self.assertEqual(await response.read(), b"")
+
+    @unittest_run_loop
+    async def test_blackd_request_syntax_error(self) -> None:
+        response = await self.client.post("/", data=b"what even ( is")
+        self.assertEqual(response.status, 400)
+        content = await response.text()
+        self.assertTrue(
+            content.startswith("Cannot parse"),
+            msg=f"Expected error to start with 'Cannot parse', got {repr(content)}",
+        )
+
+    @unittest_run_loop
+    async def test_blackd_unsupported_version(self) -> None:
+        response = await self.client.post(
+            "/", data=b"what", headers={blackd.PROTOCOL_VERSION_HEADER: "2"}
+        )
+        self.assertEqual(response.status, 501)
+
+    @unittest_run_loop
+    async def test_blackd_supported_version(self) -> None:
+        response = await self.client.post(
+            "/", data=b"what", headers={blackd.PROTOCOL_VERSION_HEADER: "1"}
+        )
+        self.assertEqual(response.status, 200)
+
+    @unittest_run_loop
+    async def test_blackd_invalid_python_variant(self) -> None:
+        async def check(header_value: str, expected_status: int = 400) -> None:
             response = await self.client.post(
                 "/",
-                data=b'print("hello")\n',
-                headers={blackd.LINE_LENGTH_HEADER: "NaN"},
+                data=b"what",
+                headers={blackd.PYTHON_VARIANT_HEADER: header_value},
             )
-            self.assertEqual(response.status, 400)
-
-        @unittest_run_loop
-        async def test_blackd_preview(self) -> None:
+            self.assertEqual(response.status, expected_status)
+
+        await check("lol")
+        await check("ruby3.5")
+        await check("pyi3.6")
+        await check("py1.5")
+        await check("2")
+        await check("2.7")
+        await check("py2.7")
+        await check("2.8")
+        await check("py2.8")
+        await check("3.0")
+        await check("pypy3.0")
+        await check("jython3.4")
+
+    @unittest_run_loop
+    async def test_blackd_pyi(self) -> None:
+        source, expected = read_data("miscellaneous", "stub.pyi")
+        response = await self.client.post(
+            "/", data=source, headers={blackd.PYTHON_VARIANT_HEADER: "pyi"}
+        )
+        self.assertEqual(response.status, 200)
+        self.assertEqual(await response.text(), expected)
+
+    @unittest_run_loop
+    async def test_blackd_diff(self) -> None:
+        diff_header = re.compile(
+            r"(In|Out)\t\d\d\d\d-\d\d-\d\d \d\d:\d\d:\d\d\.\d\d\d\d\d\d \+\d\d\d\d"
+        )
+
+        source, _ = read_data("miscellaneous", "blackd_diff")
+        expected, _ = read_data("miscellaneous", "blackd_diff.diff")
+
+        response = await self.client.post(
+            "/", data=source, headers={blackd.DIFF_HEADER: "true"}
+        )
+        self.assertEqual(response.status, 200)
+
+        actual = await response.text()
+        actual = diff_header.sub(DETERMINISTIC_HEADER, actual)
+        self.assertEqual(actual, expected)
+
+    @unittest_run_loop
+    async def test_blackd_python_variant(self) -> None:
+        code = (
+            "def f(\n"
+            "    and_has_a_bunch_of,\n"
+            "    very_long_arguments_too,\n"
+            "    and_lots_of_them_as_well_lol,\n"
+            "    **and_very_long_keyword_arguments\n"
+            "):\n"
+            "    pass\n"
+        )
+
+        async def check(header_value: str, expected_status: int) -> None:
             response = await self.client.post(
-                "/", data=b'print("hello")\n', headers={blackd.PREVIEW: "true"}
+                "/", data=code, headers={blackd.PYTHON_VARIANT_HEADER: header_value}
             )
-            self.assertEqual(response.status, 204)
-
-        @unittest_run_loop
-        async def test_blackd_response_black_version_header(self) -> None:
-            response = await self.client.post("/")
-            self.assertIsNotNone(response.headers.get(blackd.BLACK_VERSION_HEADER))
-
-        @unittest_run_loop
-        async def test_cors_preflight(self) -> None:
-            response = await self.client.options(
-                "/",
-                headers={
-                    "Access-Control-Request-Method": "POST",
-                    "Origin": "*",
-                    "Access-Control-Request-Headers": "Content-Type",
-                },
+            self.assertEqual(
+                response.status, expected_status, msg=await response.text()
             )
-            self.assertEqual(response.status, 200)
-            self.assertIsNotNone(response.headers.get("Access-Control-Allow-Origin"))
-            self.assertIsNotNone(response.headers.get("Access-Control-Allow-Headers"))
-            self.assertIsNotNone(response.headers.get("Access-Control-Allow-Methods"))
-
-        @unittest_run_loop
-        async def test_cors_headers_present(self) -> None:
-            response = await self.client.post("/", headers={"Origin": "*"})
-            self.assertIsNotNone(response.headers.get("Access-Control-Allow-Origin"))
-            self.assertIsNotNone(response.headers.get("Access-Control-Expose-Headers"))
+
+        await check("3.6", 200)
+        await check("py3.6", 200)
+        await check("3.6,3.7", 200)
+        await check("3.6,py3.7", 200)
+        await check("py36,py37", 200)
+        await check("36", 200)
+        await check("3.6.4", 200)
+        await check("3.4", 204)
+        await check("py3.4", 204)
+        await check("py34,py36", 204)
+        await check("34", 204)
+
+    @unittest_run_loop
+    async def test_blackd_line_length(self) -> None:
+        response = await self.client.post(
+            "/", data=b'print("hello")\n', headers={blackd.LINE_LENGTH_HEADER: "7"}
+        )
+        self.assertEqual(response.status, 200)
+
+    @unittest_run_loop
+    async def test_blackd_invalid_line_length(self) -> None:
+        response = await self.client.post(
+            "/",
+            data=b'print("hello")\n',
+            headers={blackd.LINE_LENGTH_HEADER: "NaN"},
+        )
+        self.assertEqual(response.status, 400)
+
+    @unittest_run_loop
+    async def test_blackd_preview(self) -> None:
+        response = await self.client.post(
+            "/", data=b'print("hello")\n', headers={blackd.PREVIEW: "true"}
+        )
+        self.assertEqual(response.status, 204)
+
+    @unittest_run_loop
+    async def test_blackd_response_black_version_header(self) -> None:
+        response = await self.client.post("/")
+        self.assertIsNotNone(response.headers.get(blackd.BLACK_VERSION_HEADER))
+
+    @unittest_run_loop
+    async def test_cors_preflight(self) -> None:
+        response = await self.client.options(
+            "/",
+            headers={
+                "Access-Control-Request-Method": "POST",
+                "Origin": "*",
+                "Access-Control-Request-Headers": "Content-Type",
+            },
+        )
+        self.assertEqual(response.status, 200)
+        self.assertIsNotNone(response.headers.get("Access-Control-Allow-Origin"))
+        self.assertIsNotNone(response.headers.get("Access-Control-Allow-Headers"))
+        self.assertIsNotNone(response.headers.get("Access-Control-Allow-Methods"))
+
+    @unittest_run_loop
+    async def test_cors_headers_present(self) -> None:
+        response = await self.client.post("/", headers={"Origin": "*"})
+        self.assertIsNotNone(response.headers.get("Access-Control-Allow-Origin"))
+        self.assertIsNotNone(response.headers.get("Access-Control-Expose-Headers"))
diff --git a/tox.ini b/tox.ini
index 5f3874c23b4..098f06c9828 100644
--- a/tox.ini
+++ b/tox.ini
@@ -51,16 +51,20 @@ commands =
     coverage report
 
 [testenv:{,ci-}311]
-setenv = PYTHONPATH = {toxinidir}/src
+setenv =
+  PYTHONPATH = {toxinidir}/src
+  AIOHTTP_NO_EXTENSIONS = 1
 skip_install = True
 recreate = True
 deps =
+; We currently need > aiohttp 3.8.1 that is on PyPI for 3.11
+    git+https://github.com/aio-libs/aiohttp
     -r{toxinidir}/test_requirements.txt
 ; a separate worker is required in ci due to https://foss.heptapod.net/pypy/pypy/-/issues/3317
 ; this seems to cause tox to wait forever
 ; remove this when pypy releases the bugfix
 commands =
-    pip install -e .
+    pip install -e .[d]
     coverage erase
     pytest tests \
         --run-optional no_jupyter \

From 72a25591b04b40d1c9b67844120457297c93ecb8 Mon Sep 17 00:00:00 2001
From: Holger Brunn <mail@hunki-enterprises.com>
Date: Wed, 14 Sep 2022 05:06:54 +0200
Subject: [PATCH 0609/1034] [FIX] migrate-black.py: don't fail on binary files
 (#3266)

---
 scripts/migrate-black.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/scripts/migrate-black.py b/scripts/migrate-black.py
index 63cc5096a93..ff52939460c 100755
--- a/scripts/migrate-black.py
+++ b/scripts/migrate-black.py
@@ -49,6 +49,7 @@ def blackify(base_branch: str, black_command: str, logger: logging.Logger) -> in
             [
                 "git",
                 "diff",
+                "--binary",
                 "--find-copies",
                 "%s-black..%s-black" % (last_commit, commit),
             ],

From e2adcd7de10eb570987bb894d95f2ff8c8693b9f Mon Sep 17 00:00:00 2001
From: "Yilei \"Dolee\" Yang" <yileiyang@google.com>
Date: Tue, 13 Sep 2022 20:23:51 -0700
Subject: [PATCH 0610/1034] Fix a crash on dicts with paren-wrapped long string
 keys (#3262)

Fix a crash when formatting some dicts with parenthesis-wrapped long
string keys. When LL[0] is an atom string, we need to check the atom
node's siblings instead of LL[0] itself, e.g.:

    dictsetmaker
      atom
        STRING '"This is a really long string that can\'t be expected to fit in one line and is used as a nested dict\'s key"'
      /atom
      COLON ':'
      atom
        LSQB ' ' '['
        listmaker
          STRING '"value"'
          COMMA ','
          STRING ' ' '"value"'
        /listmaker
        RSQB ']'
      /atom
      COMMA ','
    /dictsetmaker
---
 CHANGES.md                         |  3 +++
 src/black/trans.py                 | 10 ++++++++++
 tests/data/preview/long_strings.py | 21 +++++++++++++++++++++
 3 files changed, 34 insertions(+)

diff --git a/CHANGES.md b/CHANGES.md
index 25c3d4889a0..147100c3012 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -14,6 +14,9 @@
 
 <!-- Changes that affect Black's preview style -->
 
+- Fix a crash when formatting some dicts with parenthesis-wrapped long string keys
+  (#3262)
+
 ### Configuration
 
 <!-- Changes to how Black can be configured -->
diff --git a/src/black/trans.py b/src/black/trans.py
index 7ecfcef703d..74b932bb422 100644
--- a/src/black/trans.py
+++ b/src/black/trans.py
@@ -1071,6 +1071,16 @@ def _prefer_paren_wrap_match(LL: List[Leaf]) -> Optional[int]:
             # And the string is surrounded by commas (or is the first/last child)...
             prev_sibling = LL[0].prev_sibling
             next_sibling = LL[0].next_sibling
+            if (
+                not prev_sibling
+                and not next_sibling
+                and parent_type(LL[0]) == syms.atom
+            ):
+                # If it's an atom string, we need to check the parent atom's siblings.
+                parent = LL[0].parent
+                assert parent is not None  # For type checkers.
+                prev_sibling = parent.prev_sibling
+                next_sibling = parent.next_sibling
             if (not prev_sibling or prev_sibling.type == token.COMMA) and (
                 not next_sibling or next_sibling.type == token.COMMA
             ):
diff --git a/tests/data/preview/long_strings.py b/tests/data/preview/long_strings.py
index 3ad5f355e33..6db3cfed9a9 100644
--- a/tests/data/preview/long_strings.py
+++ b/tests/data/preview/long_strings.py
@@ -18,6 +18,14 @@
 
 D4 = {"A long and ridiculous {}".format(string_key): "This is a really really really long string that has to go i,side of a dictionary. It is soooo bad.", some_func("calling", "some", "stuff"): "This is a really really really long string that has to go inside of a dictionary. It is {soooo} bad (#{x}).".format(sooo="soooo", x=2), "A %s %s" % ("formatted", "string"): "This is a really really really long string that has to go inside of a dictionary. It is %s bad (#%d)." % ("soooo", 2)}
 
+D5 = {  # Test for https://github.com/psf/black/issues/3261
+    ("This is a really long string that can't be expected to fit in one line and is used as a nested dict's key"): {"inner": "value"},
+}
+
+D6 = {  # Test for https://github.com/psf/black/issues/3261
+    ("This is a really long string that can't be expected to fit in one line and is used as a dict's key"): ["value1", "value2"],
+}
+
 L1 = ["The is a short string", "This is a really long string that can't possibly be expected to fit all together on one line. Also it is inside a list literal, so it's expected to be wrapped in parens when spliting to avoid implicit str concatenation.", short_call("arg", {"key": "value"}), "This is another really really (not really) long string that also can't be expected to fit on one line and is, like the other string, inside a list literal.", ("parens should be stripped for short string in list")]
 
 L2 = ["This is a really long string that can't be expected to fit in one line and is the only child of a list literal."]
@@ -357,6 +365,19 @@ def foo():
     % ("soooo", 2),
 }
 
+D5 = {  # Test for https://github.com/psf/black/issues/3261
+    "This is a really long string that can't be expected to fit in one line and is used as a nested dict's key": {
+        "inner": "value"
+    },
+}
+
+D6 = {  # Test for https://github.com/psf/black/issues/3261
+    "This is a really long string that can't be expected to fit in one line and is used as a dict's key": [
+        "value1",
+        "value2",
+    ],
+}
+
 L1 = [
     "The is a short string",
     (

From 04bce6ad2ecf38656149fd261f01f84699cf0b6a Mon Sep 17 00:00:00 2001
From: Tom Fryers <61272761+TomFryers@users.noreply.github.com>
Date: Thu, 15 Sep 2022 03:31:26 +0100
Subject: [PATCH 0611/1034] Improve order of paragraphs on line splitting
 (#3270)

These two paragraphs were tucked away at the end of the section, after
the diversion on backslashes. I nearly missed the first paragraph and
opened a nonsense issue, and I think the second belongs higher up with
it too.
---
 docs/the_black_code_style/current_style.md | 26 +++++++++++-----------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/docs/the_black_code_style/current_style.md b/docs/the_black_code_style/current_style.md
index 5085b0017d9..3db49e2ba01 100644
--- a/docs/the_black_code_style/current_style.md
+++ b/docs/the_black_code_style/current_style.md
@@ -85,6 +85,19 @@ def very_important_function(
         ...
 ```
 
+If a data structure literal (tuple, list, set, dict) or a line of "from" imports cannot
+fit in the allotted length, it's always split into one element per line. This minimizes
+diffs as well as enables readers of code to find which commit introduced a particular
+entry. This also makes _Black_ compatible with
+[isort](../guides/using_black_with_other_tools.md#isort) with the ready-made `black`
+profile or manual configuration.
+
+You might have noticed that closing brackets are always dedented and that a trailing
+comma is always added. Such formatting produces smaller diffs; when you add or remove an
+element, it's always just one line. Also, having the closing bracket dedented provides a
+clear delimiter between two distinct sections of the code that otherwise share the same
+indentation level (like the arguments list and the docstring in the example above).
+
 (labels/why-no-backslashes)=
 
 _Black_ prefers parentheses over backslashes, and will remove backslashes if found.
@@ -127,19 +140,6 @@ If you're reaching for backslashes, that's a clear signal that you can do better
 slightly refactor your code. I hope some of the examples above show you that there are
 many ways in which you can do it.
 
-You might have noticed that closing brackets are always dedented and that a trailing
-comma is always added. Such formatting produces smaller diffs; when you add or remove an
-element, it's always just one line. Also, having the closing bracket dedented provides a
-clear delimiter between two distinct sections of the code that otherwise share the same
-indentation level (like the arguments list and the docstring in the example above).
-
-If a data structure literal (tuple, list, set, dict) or a line of "from" imports cannot
-fit in the allotted length, it's always split into one element per line. This minimizes
-diffs as well as enables readers of code to find which commit introduced a particular
-entry. This also makes _Black_ compatible with
-[isort](../guides/using_black_with_other_tools.md#isort) with the ready-made `black`
-profile or manual configuration.
-
 ### Line length
 
 You probably noticed the peculiar default line length. _Black_ defaults to 88 characters

From d852af71672ce22646017e4ca7a8878ca7bdfe39 Mon Sep 17 00:00:00 2001
From: Zsolt Dollenstein <zsol.zsol@gmail.com>
Date: Thu, 15 Sep 2022 21:08:26 +0100
Subject: [PATCH 0612/1034] Fix mypyc build errors on newer
 manylinux2014_x86_64 images (#3272)

Make sure `gcc` is installed in the build env

The mypyc build requires `gcc` to be installed even if it's being built with `clang`, otherwise `clang` fails to find `libgcc`.
---
 pyproject.toml | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/pyproject.toml b/pyproject.toml
index 566462c9b36..a4c9c692085 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -59,10 +59,8 @@ PIP_NO_BUILD_ISOLATION = "no"
 [tool.cibuildwheel.linux]
 before-build = [
     "pip install -r .github/mypyc-requirements.txt",
-    "yum install -y clang",
+    "yum install -y clang gcc",
 ]
-# Newer images break the builds, not sure why. We'll need to investigate more later.
-manylinux-x86_64-image = "quay.io/pypa/manylinux2014_x86_64:2021-11-20-f410d11"
 
 [tool.cibuildwheel.linux.environment]
 BLACK_USE_MYPYC = "1"

From 6ae8457a8628345c59fed22c58728ffa258a3e76 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 19 Sep 2022 19:35:46 -0400
Subject: [PATCH 0613/1034] Bump furo from 2022.6.21 to 2022.9.15 in /docs
 (#3277)

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 docs/requirements.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index 121df45e6c2..f4b59fd3cd9 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -6,4 +6,4 @@ Sphinx==5.1.1
 docutils==0.18.1
 sphinxcontrib-programoutput==0.17
 sphinx_copybutton==0.5.0
-furo==2022.6.21
+furo==2022.9.15

From 75d5c0e3fbf5de67b995c80e12229b7525ff6bb9 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Thu, 22 Sep 2022 23:11:56 -0400
Subject: [PATCH 0614/1034] Build mypyc wheels for CPython 3.11 (#3276)

Bumps cibuildwheel from 2.8.1 to 2.10.0 which has 3.11 building enabled
by default. Unfortunately mypyc errors out on 3.11:

src/black/files.py:29:9: error: Name "tomllib" already defined (by an import)  [no-redef]

... so we have to also hide the fallback import of tomli on older 3.11
alphas from mypy[c].
---
 .github/workflows/pypi_upload.yml | 2 +-
 CHANGES.md                        | 2 ++
 pyproject.toml                    | 4 ++++
 src/black/files.py                | 3 ++-
 4 files changed, 9 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/pypi_upload.yml b/.github/workflows/pypi_upload.yml
index d52f41a4939..ae26a814c9e 100644
--- a/.github/workflows/pypi_upload.yml
+++ b/.github/workflows/pypi_upload.yml
@@ -58,7 +58,7 @@ jobs:
       - uses: actions/checkout@v3
 
       - name: Build wheels via cibuildwheel
-        uses: pypa/cibuildwheel@v2.8.1
+        uses: pypa/cibuildwheel@v2.10.0
         env:
           CIBW_ARCHS_MACOS: "${{ matrix.macos_arch }}"
           # This isn't supported in pyproject.toml which makes sense (but is annoying).
diff --git a/CHANGES.md b/CHANGES.md
index 147100c3012..0fa80ad8124 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -25,6 +25,8 @@
 
 <!-- Changes to how Black is packaged, such as dependency requirements -->
 
+- Faster compiled wheels are now available for CPython 3.11 (#3276)
+
 ### Parser
 
 <!-- Changes to the parser or to version autodetection -->
diff --git a/pyproject.toml b/pyproject.toml
index a4c9c692085..122a49e004b 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -55,6 +55,9 @@ MYPYC_DEBUG_LEVEL = "0"
 # The dependencies required to build wheels with mypyc aren't specified in
 # [build-system].requires so we'll have to manage the build environment ourselves.
 PIP_NO_BUILD_ISOLATION = "no"
+# CPython 3.11 wheels aren't available for aiohttp and building a Cython extension
+# from source also doesn't work.
+AIOHTTP_NO_EXTENSIONS = "1"
 
 [tool.cibuildwheel.linux]
 before-build = [
@@ -69,6 +72,7 @@ MYPYC_DEBUG_LEVEL = "0"
 PIP_NO_BUILD_ISOLATION = "no"
 # Black needs Clang to compile successfully on Linux.
 CC = "clang"
+AIOHTTP_NO_EXTENSIONS = "1"
 
 [tool.cibuildwheel.windows]
 # For some reason, (compiled) mypyc is failing to start up with "ImportError: DLL load
diff --git a/src/black/files.py b/src/black/files.py
index d51c1bc7a90..ed503f5fec7 100644
--- a/src/black/files.py
+++ b/src/black/files.py
@@ -26,7 +26,8 @@
         import tomllib
     except ImportError:
         # Help users on older alphas
-        import tomli as tomllib
+        if not TYPE_CHECKING:
+            import tomli as tomllib
 else:
     import tomli as tomllib
 

From 4c9990023635ece68671324124801f6b75dab2a8 Mon Sep 17 00:00:00 2001
From: Blandes22 <96037855+Blandes22@users.noreply.github.com>
Date: Thu, 22 Sep 2022 22:19:31 -0500
Subject: [PATCH 0615/1034] Make context manager examples in future style docs
 consistent (#3274)

---
 docs/the_black_code_style/future_style.md | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/docs/the_black_code_style/future_style.md b/docs/the_black_code_style/future_style.md
index a17d9a10673..a028a2888ed 100644
--- a/docs/the_black_code_style/future_style.md
+++ b/docs/the_black_code_style/future_style.md
@@ -23,10 +23,10 @@ So _Black_ will eventually format it like this:
 
 ```py3
 with \
-     make_context_manager(1) as cm1, \
-     make_context_manager(2) as cm2, \
-     make_context_manager(3) as cm3, \
-     make_context_manager(4) as cm4 \
+     make_context_manager1() as cm1, \
+     make_context_manager2() as cm2, \
+     make_context_manager3() as cm3, \
+     make_context_manager4() as cm4 \
 :
     ...  # backslashes and an ugly stranded colon
 ```
@@ -40,10 +40,10 @@ following way:
 
 ```python
 with contextlib.ExitStack() as exit_stack:
-    cm1 = exit_stack.enter_context(make_context_manager(1))
-    cm2 = exit_stack.enter_context(make_context_manager(2))
-    cm3 = exit_stack.enter_context(make_context_manager(3))
-    cm4 = exit_stack.enter_context(make_context_manager(4))
+    cm1 = exit_stack.enter_context(make_context_manager1())
+    cm2 = exit_stack.enter_context(make_context_manager2())
+    cm3 = exit_stack.enter_context(make_context_manager3())
+    cm4 = exit_stack.enter_context(make_context_manager4())
     ...
 ```
 

From bfc013ab93d0993a6e24235291dddd4c4ecd64ee Mon Sep 17 00:00:00 2001
From: Jakub Kuczys <me@jacken.men>
Date: Fri, 23 Sep 2022 05:23:35 +0200
Subject: [PATCH 0616/1034] Support version specifiers in GH action (#3265)

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 CHANGES.md                          |  3 +++
 action/main.py                      |  7 ++++---
 docs/integrations/github_actions.md | 21 ++++++++++++++++++---
 3 files changed, 25 insertions(+), 6 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 0fa80ad8124..67d007c21ae 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -47,6 +47,9 @@
 
 <!-- For example, Docker, GitHub Actions, pre-commit, editors -->
 
+- Update GitHub Action to support use of version specifiers (e.g. `<23`) for Black
+  version (#3265)
+
 ### Documentation
 
 <!-- Major changes to documentation and policies. Small docs changes
diff --git a/action/main.py b/action/main.py
index cd920f5fe0d..03228cb13e8 100644
--- a/action/main.py
+++ b/action/main.py
@@ -14,9 +14,10 @@
 
 run([sys.executable, "-m", "venv", str(ENV_PATH)], check=True)
 
-req = "black[colorama]"
-if VERSION:
-    req += f"=={VERSION}"
+version_specifier = VERSION
+if VERSION and VERSION[0] in "0123456789":
+    version_specifier = f"=={VERSION}"
+req = f"black[colorama]{version_specifier}"
 pip_proc = run(
     [str(ENV_BIN / "python"), "-m", "pip", "install", req],
     stdout=PIPE,
diff --git a/docs/integrations/github_actions.md b/docs/integrations/github_actions.md
index c9697cc05de..d77b9693678 100644
--- a/docs/integrations/github_actions.md
+++ b/docs/integrations/github_actions.md
@@ -32,9 +32,12 @@ We recommend the use of the `@stable` tag, but per version tags also exist if yo
 that. Note that the action's version you select is independent of the version of _Black_
 the action will use.
 
-The version of _Black_ the action will use can be configured via `version`. The action
-defaults to the latest release available on PyPI. Only versions available from PyPI are
-supported, so no commit SHAs or branch names.
+The version of _Black_ the action will use can be configured via `version`. This can be
+any
+[valid version specifier](https://packaging.python.org/en/latest/glossary/#term-Version-Specifier)
+or just the version number if you want an exact version. The action defaults to the
+latest release available on PyPI. Only versions available from PyPI are supported, so no
+commit SHAs or branch names.
 
 You can also configure the arguments passed to _Black_ via `options` (defaults to
 `'--check --diff'`) and `src` (default is `'.'`)
@@ -48,3 +51,15 @@ Here's an example configuration:
     src: "./src"
     version: "21.5b1"
 ```
+
+If you want to match versions covered by Black's
+[stability policy](labels/stability-policy), you can use the compatible release operator
+(`~=`):
+
+```yaml
+- uses: psf/black@stable
+  with:
+    options: "--check --verbose"
+    src: "./src"
+    version: "~= 22.0"
+```

From 55db05519ebfc502680aa55d289b7e47f6b2c6af Mon Sep 17 00:00:00 2001
From: "Yilei \"Dolee\" Yang" <yileiyang@google.com>
Date: Fri, 23 Sep 2022 20:37:22 -0700
Subject: [PATCH 0617/1034] Fix a crash when `# fmt: on` is used on a different
 block level than `# fmt: off` (#3281)

Previously _Black_ produces invalid code because the `# fmt: on` is used on a different block level.

While _Black_ requires `# fmt: off` and `# fmt: on` to be used at the same block level, incorrect usage shouldn't cause crashes.

The formatting behavior this PR introduces is, the code below the initial `# fmt: off` block level will be turned off for formatting, when `# fmt: on` is used on a different level or there is no `# fmt: on`. This also matches the current behavior when `# fmt: off` is used at the top-level without a matching `# fmt: on`, it turns off formatting for everything below `# fmt: off`.

- Fixes #2567
- Fixes #3184
- Fixes #2985
- Fixes #2882
- Fixes #2232
- Fixes #2140
- Fixes #1817
- Fixes #569
---
 CHANGES.md                                    |   3 +
 .../reference/reference_functions.rst         |   4 +-
 src/black/comments.py                         |  34 +++--
 src/black/nodes.py                            |  14 +-
 tests/data/simple_cases/fmtonoff5.py          | 122 ++++++++++++++++++
 5 files changed, 151 insertions(+), 26 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 67d007c21ae..48f5035c133 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -10,6 +10,9 @@
 
 <!-- Changes that affect Black's stable style -->
 
+- Fix a crash when `# fmt: on` is used on a different block level than `# fmt: off`
+  (#3281)
+
 ### Preview style
 
 <!-- Changes that affect Black's preview style -->
diff --git a/docs/contributing/reference/reference_functions.rst b/docs/contributing/reference/reference_functions.rst
index 50eaeb31e15..3bda5de1774 100644
--- a/docs/contributing/reference/reference_functions.rst
+++ b/docs/contributing/reference/reference_functions.rst
@@ -137,9 +137,9 @@ Utilities
 
 .. autofunction:: black.comments.is_fmt_on
 
-.. autofunction:: black.comments.contains_fmt_on_at_column
+.. autofunction:: black.comments.children_contains_fmt_on
 
-.. autofunction:: black.nodes.first_leaf_column
+.. autofunction:: black.nodes.first_leaf_of
 
 .. autofunction:: black.linegen.generate_trailers_to_omit
 
diff --git a/src/black/comments.py b/src/black/comments.py
index dc58934f9d3..2a4c254ecd9 100644
--- a/src/black/comments.py
+++ b/src/black/comments.py
@@ -14,11 +14,12 @@
     STANDALONE_COMMENT,
     WHITESPACE,
     container_of,
-    first_leaf_column,
+    first_leaf_of,
     preceding_leaf,
+    syms,
 )
 from blib2to3.pgen2 import token
-from blib2to3.pytree import Leaf, Node, type_repr
+from blib2to3.pytree import Leaf, Node
 
 # types
 LN = Union[Leaf, Node]
@@ -230,7 +231,7 @@ def generate_ignored_nodes(
             return
 
         # fix for fmt: on in children
-        if contains_fmt_on_at_column(container, leaf.column, preview=preview):
+        if children_contains_fmt_on(container, preview=preview):
             for child in container.children:
                 if isinstance(child, Leaf) and is_fmt_on(child, preview=preview):
                     if child.type in CLOSING_BRACKETS:
@@ -240,10 +241,14 @@ def generate_ignored_nodes(
                         # The alternative is to fail the formatting.
                         yield child
                     return
-                if contains_fmt_on_at_column(child, leaf.column, preview=preview):
+                if children_contains_fmt_on(child, preview=preview):
                     return
                 yield child
         else:
+            if container.type == token.DEDENT and container.next_sibling is None:
+                # This can happen when there is no matching `# fmt: on` comment at the
+                # same level as `# fmt: on`. We need to keep this DEDENT.
+                return
             yield container
             container = container.next_sibling
 
@@ -268,9 +273,7 @@ def _generate_ignored_nodes_from_fmt_skip(
         for sibling in siblings:
             yield sibling
     elif (
-        parent is not None
-        and type_repr(parent.type) == "suite"
-        and leaf.type == token.NEWLINE
+        parent is not None and parent.type == syms.suite and leaf.type == token.NEWLINE
     ):
         # The `# fmt: skip` is on the colon line of the if/while/def/class/...
         # statements. The ignored nodes should be previous siblings of the
@@ -278,7 +281,7 @@ def _generate_ignored_nodes_from_fmt_skip(
         leaf.prefix = ""
         ignored_nodes: List[LN] = []
         parent_sibling = parent.prev_sibling
-        while parent_sibling is not None and type_repr(parent_sibling.type) != "suite":
+        while parent_sibling is not None and parent_sibling.type != syms.suite:
             ignored_nodes.insert(0, parent_sibling)
             parent_sibling = parent_sibling.prev_sibling
         # Special case for `async_stmt` where the ASYNC token is on the
@@ -306,17 +309,12 @@ def is_fmt_on(container: LN, preview: bool) -> bool:
     return fmt_on
 
 
-def contains_fmt_on_at_column(container: LN, column: int, *, preview: bool) -> bool:
-    """Determine if children at a given column have formatting switched on."""
+def children_contains_fmt_on(container: LN, *, preview: bool) -> bool:
+    """Determine if children have formatting switched on."""
     for child in container.children:
-        if (
-            isinstance(child, Node)
-            and first_leaf_column(child) == column
-            or isinstance(child, Leaf)
-            and child.column == column
-        ):
-            if is_fmt_on(child, preview=preview):
-                return True
+        leaf = first_leaf_of(child)
+        if leaf is not None and is_fmt_on(leaf, preview=preview):
+            return True
 
     return False
 
diff --git a/src/black/nodes.py b/src/black/nodes.py
index 8f341ab35d6..aeb2be389c8 100644
--- a/src/black/nodes.py
+++ b/src/black/nodes.py
@@ -502,12 +502,14 @@ def container_of(leaf: Leaf) -> LN:
     return container
 
 
-def first_leaf_column(node: Node) -> Optional[int]:
-    """Returns the column of the first leaf child of a node."""
-    for child in node.children:
-        if isinstance(child, Leaf):
-            return child.column
-    return None
+def first_leaf_of(node: LN) -> Optional[Leaf]:
+    """Returns the first leaf of the node tree."""
+    if isinstance(node, Leaf):
+        return node
+    if node.children:
+        return first_leaf_of(node.children[0])
+    else:
+        return None
 
 
 def is_arith_like(node: LN) -> bool:
diff --git a/tests/data/simple_cases/fmtonoff5.py b/tests/data/simple_cases/fmtonoff5.py
index 746aa41f4e4..71b1381ed0d 100644
--- a/tests/data/simple_cases/fmtonoff5.py
+++ b/tests/data/simple_cases/fmtonoff5.py
@@ -34,3 +34,125 @@ def test_func():
         return True
 
     return False
+
+
+# Regression test for https://github.com/psf/black/issues/2567.
+if True:
+    # fmt: off
+    for _ in range( 1 ):
+    # fmt: on
+        print ( "This won't be formatted" )
+    print ( "This won't be formatted either" )
+else:
+    print ( "This will be formatted" )
+
+
+# Regression test for https://github.com/psf/black/issues/3184.
+class A:
+    async def call(param):
+        if param:
+            # fmt: off
+            if param[0:4] in (
+                "ABCD", "EFGH"
+            )  :
+                # fmt: on
+                print ( "This won't be formatted" )
+
+            elif param[0:4] in ("ZZZZ",):
+                print ( "This won't be formatted either" )
+
+        print ( "This will be formatted" )
+
+
+# Regression test for https://github.com/psf/black/issues/2985
+class Named(t.Protocol):
+    # fmt: off
+    @property
+    def  this_wont_be_formatted ( self ) -> str: ...
+
+class Factory(t.Protocol):
+    def  this_will_be_formatted ( self, **kwargs ) -> Named: ...
+    # fmt: on
+
+
+# output
+
+
+# Regression test for https://github.com/psf/black/issues/3129.
+setup(
+    entry_points={
+        # fmt: off
+        "console_scripts": [
+            "foo-bar"
+            "=foo.bar.:main",
+        # fmt: on
+            ]  # Includes an formatted indentation.
+    },
+)
+
+
+# Regression test for https://github.com/psf/black/issues/2015.
+run(
+    # fmt: off
+    [
+        "ls",
+        "-la",
+    ]
+    # fmt: on
+    + path,
+    check=True,
+)
+
+
+# Regression test for https://github.com/psf/black/issues/3026.
+def test_func():
+    # yapf: disable
+    if  unformatted(  args  ):
+        return True
+    # yapf: enable
+    elif b:
+        return True
+
+    return False
+
+
+# Regression test for https://github.com/psf/black/issues/2567.
+if True:
+    # fmt: off
+    for _ in range( 1 ):
+    # fmt: on
+        print ( "This won't be formatted" )
+    print ( "This won't be formatted either" )
+else:
+    print("This will be formatted")
+
+
+# Regression test for https://github.com/psf/black/issues/3184.
+class A:
+    async def call(param):
+        if param:
+            # fmt: off
+            if param[0:4] in (
+                "ABCD", "EFGH"
+            )  :
+                # fmt: on
+                print ( "This won't be formatted" )
+
+            elif param[0:4] in ("ZZZZ",):
+                print ( "This won't be formatted either" )
+
+        print("This will be formatted")
+
+
+# Regression test for https://github.com/psf/black/issues/2985
+class Named(t.Protocol):
+    # fmt: off
+    @property
+    def  this_wont_be_formatted ( self ) -> str: ...
+
+
+class Factory(t.Protocol):
+    def this_will_be_formatted(self, **kwargs) -> Named:
+        ...
+
+    # fmt: on

From 4b4680a0a9e06ae926abfbf0d209725de44860a8 Mon Sep 17 00:00:00 2001
From: Stijn de Gooijer <stijn@degooijer.io>
Date: Sun, 25 Sep 2022 11:28:43 +0200
Subject: [PATCH 0618/1034] Make README logo link to docs (#3285)

docs: Make README logo link to docs
---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 624d4d755eb..4c761606514 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-![Black Logo](https://raw.githubusercontent.com/psf/black/main/docs/_static/logo2-readme.png)
+[![Black Logo](https://raw.githubusercontent.com/psf/black/main/docs/_static/logo2-readme.png)](https://black.readthedocs.io/en/stable/)
 
 <h2 align="center">The Uncompromising Code Formatter</h2>
 

From 468ceafca571454fd279f3b428076631fdaffd3d Mon Sep 17 00:00:00 2001
From: Ofek Lev <ofekmeister@gmail.com>
Date: Sun, 25 Sep 2022 14:54:33 -0700
Subject: [PATCH 0619/1034] Switch build backend to Hatchling (#3233)

This implements PEP 621, obviating the need for `setup.py`, `setup.cfg`,
and `MANIFEST.in`. The build backend Hatchling (of which I am a
maintainer in the PyPA) is now used as that is the default in the
official Python packaging tutorial. Hatchling is available on all the
major distribution channels such as Debian, Fedora, and many more.

## Python support

The earliest supported Python 3 version of Hatchling is 3.7, therefore
I've also set that as the minimum here. Python 3.6 is EOL and other
build backends like flit-core and setuptools also dropped support.
Python 3.6 accounted for 3-4% of downloads in the last month.

## Plugins

Configuration is now completely static with the help of 3 plugins:

### Readme

hynek's hatch-fancy-pypi-readme allows for the dynamic construction of
the readme which was previously coded up in `setup.py`. Now it's simply:

```toml
[tool.hatch.metadata.hooks.fancy-pypi-readme]
content-type = "text/markdown"
fragments = [
  { path = "README.md" },
  { path = "CHANGES.md" },
]
```

### Versioning

hatch-vcs is currently just a wrapper around setuptools-scm (which
despite the legacy naming is actually now decoupled from setuptools):

```toml
[tool.hatch.version]
source = "vcs"

[tool.hatch.build.hooks.vcs]
version-file = "src/_black_version.py"
template = '''
version = "{version}"
'''
```

### mypyc

hatch-mypyc offers many benefits over the existing approach:

- No need to manually select files for inclusion
- Avoids the need for the current CI workaround for https://github.com/mypyc/mypyc/issues/946
- Intermediate artifacts (like `build/`) from setuptools and mypyc
  itself no longer clutter the project directory
- Runtime dependencies required at build time no longer need to be
  manually redeclared as this is a built-in option of Hatchling

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 .github/mypyc-requirements.txt             |  14 --
 .github/workflows/diff_shades.yml          |  12 +-
 .github/workflows/fuzz.yml                 |   2 +-
 .github/workflows/pypi_upload.yml          |   2 -
 .github/workflows/test.yml                 |   2 +-
 CHANGES.md                                 |   5 +
 MANIFEST.in                                |   1 -
 docs/faq.md                                |   6 +-
 docs/usage_and_configuration/the_basics.md |   7 +-
 pyproject.toml                             | 135 +++++++++++++++++---
 setup.cfg                                  |   3 -
 setup.py                                   | 141 ---------------------
 tox.ini                                    |   5 +-
 13 files changed, 140 insertions(+), 195 deletions(-)
 delete mode 100644 .github/mypyc-requirements.txt
 delete mode 100644 MANIFEST.in
 delete mode 100644 setup.cfg
 delete mode 100644 setup.py

diff --git a/.github/mypyc-requirements.txt b/.github/mypyc-requirements.txt
deleted file mode 100644
index 352d36c0070..00000000000
--- a/.github/mypyc-requirements.txt
+++ /dev/null
@@ -1,14 +0,0 @@
-mypy == 0.971
-
-# A bunch of packages for type information
-mypy-extensions >= 0.4.3
-tomli >= 0.10.2
-types-typed-ast >= 1.4.2
-types-dataclasses >= 0.1.3
-typing-extensions > 3.10.0.1
-click >= 8.0.0
-platformdirs >= 2.1.0
-
-# And because build isolation is disabled, we'll need to pull this too
-setuptools-scm[toml] >= 6.3.1
-wheel
diff --git a/.github/workflows/diff_shades.yml b/.github/workflows/diff_shades.yml
index fef9637c92f..a126756f102 100644
--- a/.github/workflows/diff_shades.yml
+++ b/.github/workflows/diff_shades.yml
@@ -3,10 +3,10 @@ name: diff-shades
 on:
   push:
     branches: [main]
-    paths: ["src/**", "setup.*", "pyproject.toml", ".github/workflows/*"]
+    paths: ["src/**", "pyproject.toml", ".github/workflows/*"]
 
   pull_request:
-    paths: ["src/**", "setup.*", "pyproject.toml", ".github/workflows/*"]
+    paths: ["src/**", "pyproject.toml", ".github/workflows/*"]
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.run_id }}
@@ -41,6 +41,7 @@ jobs:
     needs: configure
     runs-on: ubuntu-latest
     env:
+      HATCH_BUILD_HOOKS_ENABLE: "1"
       # Clang is less picky with the C code it's given than gcc (and may
       # generate faster binaries too).
       CC: clang-12
@@ -64,7 +65,6 @@ jobs:
         run: |
           python -m pip install https://github.com/ichard26/diff-shades/archive/stable.zip
           python -m pip install click packaging urllib3
-          python -m pip install -r .github/mypyc-requirements.txt
           # After checking out old revisions, this might not exist so we'll use a copy.
           cat scripts/diff_shades_gha_helper.py > helper.py
           git config user.name "diff-shades-gha"
@@ -83,8 +83,7 @@ jobs:
           GITHUB_TOKEN: ${{ github.token }}
         run: >
           ${{ matrix.baseline-setup-cmd }}
-          && python setup.py --use-mypyc bdist_wheel
-          && python -m pip install dist/*.whl && rm build dist -r
+          && python -m pip install .
 
       - name: Analyze baseline revision
         if: steps.baseline-cache.outputs.cache-hit != 'true'
@@ -97,8 +96,7 @@ jobs:
           GITHUB_TOKEN: ${{ github.token }}
         run: >
           ${{ matrix.target-setup-cmd }}
-          && python setup.py --use-mypyc bdist_wheel
-          && python -m pip install dist/*.whl
+          && python -m pip install .
 
       - name: Analyze target revision
         run: >
diff --git a/.github/workflows/fuzz.yml b/.github/workflows/fuzz.yml
index a2810e25f77..ebb8a9fda9e 100644
--- a/.github/workflows/fuzz.yml
+++ b/.github/workflows/fuzz.yml
@@ -22,7 +22,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.6", "3.7", "3.8", "3.9", "3.10"]
+        python-version: ["3.7", "3.8", "3.9", "3.10"]
 
     steps:
       - uses: actions/checkout@v3
diff --git a/.github/workflows/pypi_upload.yml b/.github/workflows/pypi_upload.yml
index ae26a814c9e..2c288284444 100644
--- a/.github/workflows/pypi_upload.yml
+++ b/.github/workflows/pypi_upload.yml
@@ -61,8 +61,6 @@ jobs:
         uses: pypa/cibuildwheel@v2.10.0
         env:
           CIBW_ARCHS_MACOS: "${{ matrix.macos_arch }}"
-          # This isn't supported in pyproject.toml which makes sense (but is annoying).
-          CIBW_PROJECT_REQUIRES_PYTHON: ">=3.6.2"
 
       - name: Upload wheels as workflow artifacts
         uses: actions/upload-artifact@v2
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 7cc55d1bf76..372d1fd5d38 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -31,7 +31,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.6", "3.7", "3.8", "3.9", "3.10", "pypy-3.7", "pypy-3.8"]
+        python-version: ["3.7", "3.8", "3.9", "3.10", "pypy-3.7", "pypy-3.8"]
         os: [ubuntu-latest, macOS-latest, windows-latest]
 
     steps:
diff --git a/CHANGES.md b/CHANGES.md
index 48f5035c133..a775c76e4a5 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -6,6 +6,9 @@
 
 <!-- Include any especially major or disruptive changes here -->
 
+- Runtime support for Python 3.6 has been removed. Formatting 3.6 code will still be
+  supported until further notice.
+
 ### Stable style
 
 <!-- Changes that affect Black's stable style -->
@@ -28,6 +31,8 @@
 
 <!-- Changes to how Black is packaged, such as dependency requirements -->
 
+- Hatchling is now used as the build backend. This will not have any effect for users
+  who install Black with its wheels from PyPI. (#3233)
 - Faster compiled wheels are now available for CPython 3.11 (#3276)
 
 ### Parser
diff --git a/MANIFEST.in b/MANIFEST.in
deleted file mode 100644
index 5e53af336e2..00000000000
--- a/MANIFEST.in
+++ /dev/null
@@ -1 +0,0 @@
-prune profiling
diff --git a/docs/faq.md b/docs/faq.md
index aeb9634789f..8b9ffb0202e 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -86,8 +86,8 @@ disabled-by-default counterpart W504. E203 should be disabled while changes are
 
 ## Which Python versions does Black support?
 
-Currently the runtime requires Python 3.6-3.10. Formatting is supported for files
-containing syntax from Python 3.3 to 3.10. We promise to support at least all Python
+Currently the runtime requires Python 3.7-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.
 
@@ -95,6 +95,8 @@ Support for formatting Python 2 code was removed in version 22.0. While we've ma
 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.6 was removed in version 22.9.0.
+
 ## Why does my linter or typechecker complain after I format my code?
 
 Some linters and other tools use magical comments (e.g., `# noqa`, `# type: ignore`) to
diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index 2dc2a14f91a..aa176c4ba3f 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -204,9 +204,10 @@ code in compliance with many other _Black_ formatted projects.
 
 [PEP 518](https://www.python.org/dev/peps/pep-0518/) defines `pyproject.toml` as a
 configuration file to store build system requirements for Python projects. With the help
-of tools like [Poetry](https://python-poetry.org/) or
-[Flit](https://flit.readthedocs.io/en/latest/) it can fully replace the need for
-`setup.py` and `setup.cfg` files.
+of tools like [Poetry](https://python-poetry.org/),
+[Flit](https://flit.readthedocs.io/en/latest/), or
+[Hatch](https://hatch.pypa.io/latest/) it can fully replace the need for `setup.py` and
+`setup.cfg` files.
 
 ### Where _Black_ looks for the file
 
diff --git a/pyproject.toml b/pyproject.toml
index 122a49e004b..c37702616fc 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -7,7 +7,7 @@
 
 [tool.black]
 line-length = 88
-target-version = ['py36', 'py37', 'py38']
+target-version = ['py37', 'py38']
 include = '\.pyi?$'
 extend-exclude = '''
 /(
@@ -26,18 +26,128 @@ preview = true
 # NOTE: You don't need this in your own Black configuration.
 
 [build-system]
-requires = ["setuptools>=45.0", "setuptools_scm[toml]>=6.3.1", "wheel"]
-build-backend = "setuptools.build_meta"
+requires = ["hatchling>=1.8.0", "hatch-vcs", "hatch-fancy-pypi-readme"]
+build-backend = "hatchling.build"
+
+[project]
+name = "black"
+description = "The uncompromising code formatter."
+license = "MIT"
+requires-python = ">=3.7"
+authors = [
+  { name = "Łukasz Langa", email = "lukasz@langa.pl" },
+]
+keywords = [
+  "automation",
+  "autopep8",
+  "formatter",
+  "gofmt",
+  "pyfmt",
+  "rustfmt",
+  "yapf",
+]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.7",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = [
+  "click>=8.0.0",
+  "mypy_extensions>=0.4.3",
+  "pathspec>=0.9.0",
+  "platformdirs>=2",
+  "tomli>=1.1.0; python_full_version < '3.11.0a7'",
+  "typed-ast>=1.4.2; python_version < '3.8' and implementation_name == 'cpython'",
+  "typing_extensions>=3.10.0.0; python_version < '3.10'",
+]
+dynamic = ["readme", "version"]
+
+[project.optional-dependencies]
+colorama = ["colorama>=0.4.3"]
+uvloop = ["uvloop>=0.15.2"]
+d = [
+  "aiohttp>=3.7.4",
+]
+jupyter = [
+  "ipython>=7.8.0",
+  "tokenize-rt>=3.2.0",
+]
+
+[project.scripts]
+black = "black:patched_main"
+blackd = "blackd:patched_main [d]"
+
+[project.urls]
+Changelog = "https://github.com/psf/black/blob/main/CHANGES.md"
+Homepage = "https://github.com/psf/black"
+
+[tool.hatch.metadata.hooks.fancy-pypi-readme]
+content-type = "text/markdown"
+fragments = [
+  { path = "README.md" },
+  { path = "CHANGES.md" },
+]
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "src/_black_version.py"
+template = '''
+version = "{version}"
+'''
+
+[tool.hatch.build.targets.sdist]
+exclude = ["/profiling"]
+
+[tool.hatch.build.targets.wheel]
+only-include = ["src"]
+sources = ["src"]
+
+[tool.hatch.build.targets.wheel.hooks.mypyc]
+enable-by-default = false
+dependencies = [
+  "hatch-mypyc>=0.13.0",
+  "mypy==0.971",
+  # Required stubs to be removed when the packages support PEP 561 themselves
+  "types-typed-ast>=1.4.2",
+]
+require-runtime-dependencies = true
+exclude = [
+  # There's no good reason for blackd to be compiled.
+  "/src/blackd",
+  # Not performance sensitive, so save bytes + compilation time:
+  "/src/blib2to3/__init__.py",
+  "/src/blib2to3/pgen2/__init__.py",
+  "/src/black/output.py",
+  "/src/black/concurrency.py",
+  "/src/black/files.py",
+  "/src/black/report.py",
+  # Breaks the test suite when compiled (and is also useless):
+  "/src/black/debug.py",
+  # Compiled modules can't be run directly and that's a problem here:
+  "/src/black/__main__.py",
+]
+options = { debug_level = "0" }
 
 [tool.cibuildwheel]
 build-verbosity = 1
 # So these are the environments we target:
-# - Python: CPython 3.6+ only
+# - Python: CPython 3.7+ only
 # - Architecture (64-bit only): amd64 / x86_64, universal2, and arm64
 # - OS: Linux (no musl), Windows, and macOS
 build = "cp3*-*"
 skip = ["*-manylinux_i686", "*-musllinux_*", "*-win32", "pp-*"]
-before-build = ["pip install -r .github/mypyc-requirements.txt"]
 # This is the bare minimum needed to run the test suite. Pulling in the full
 # test_requirements.txt would download a bunch of other packages not necessary
 # here and would slow down the testing step a fair bit.
@@ -49,7 +159,7 @@ test-extras = ["d"," jupyter"]
 test-skip = ["*-macosx_arm64", "*-macosx_universal2:arm64"]
 
 [tool.cibuildwheel.environment]
-BLACK_USE_MYPYC = "1"
+HATCH_BUILD_HOOKS_ENABLE = "1"
 MYPYC_OPT_LEVEL = "3"
 MYPYC_DEBUG_LEVEL = "0"
 # The dependencies required to build wheels with mypyc aren't specified in
@@ -61,28 +171,17 @@ AIOHTTP_NO_EXTENSIONS = "1"
 
 [tool.cibuildwheel.linux]
 before-build = [
-    "pip install -r .github/mypyc-requirements.txt",
     "yum install -y clang gcc",
 ]
 
 [tool.cibuildwheel.linux.environment]
-BLACK_USE_MYPYC = "1"
+HATCH_BUILD_HOOKS_ENABLE = "1"
 MYPYC_OPT_LEVEL = "3"
 MYPYC_DEBUG_LEVEL = "0"
-PIP_NO_BUILD_ISOLATION = "no"
 # Black needs Clang to compile successfully on Linux.
 CC = "clang"
 AIOHTTP_NO_EXTENSIONS = "1"
 
-[tool.cibuildwheel.windows]
-# For some reason, (compiled) mypyc is failing to start up with "ImportError: DLL load
-# failed: A dynamic link library (DLL) initialization routine failed." on Windows for
-# at least 3.6. Let's just use interpreted mypy[c].
-# See also: https://github.com/mypyc/mypyc/issues/819.
-before-build = [
-    "pip install -r .github/mypyc-requirements.txt --no-binary mypy"
-]
-
 [tool.isort]
 atomic = true
 profile = "black"
diff --git a/setup.cfg b/setup.cfg
deleted file mode 100644
index 1a0a217eb91..00000000000
--- a/setup.cfg
+++ /dev/null
@@ -1,3 +0,0 @@
-[options]
-setup_requires =
-  setuptools_scm[toml]>=6.3.1
diff --git a/setup.py b/setup.py
deleted file mode 100644
index 2cf455573c9..00000000000
--- a/setup.py
+++ /dev/null
@@ -1,141 +0,0 @@
-# Copyright (C) 2020 Łukasz Langa
-import os
-import sys
-
-from setuptools import find_packages, setup
-
-assert sys.version_info >= (3, 6, 2), "black requires Python 3.6.2+"
-from pathlib import Path  # noqa E402
-from typing import List  # noqa: E402
-
-CURRENT_DIR = Path(__file__).parent
-sys.path.insert(0, str(CURRENT_DIR))  # for setuptools.build_meta
-
-
-def get_long_description() -> str:
-    return (
-        (CURRENT_DIR / "README.md").read_text(encoding="utf8")
-        + "\n\n"
-        + (CURRENT_DIR / "CHANGES.md").read_text(encoding="utf8")
-    )
-
-
-def find_python_files(base: Path) -> List[Path]:
-    files = []
-    for entry in base.iterdir():
-        if entry.is_file() and entry.suffix == ".py":
-            files.append(entry)
-        elif entry.is_dir():
-            files.extend(find_python_files(entry))
-
-    return files
-
-
-USE_MYPYC = False
-# To compile with mypyc, a mypyc checkout must be present on the PYTHONPATH
-if len(sys.argv) > 1 and sys.argv[1] == "--use-mypyc":
-    sys.argv.pop(1)
-    USE_MYPYC = True
-if os.getenv("BLACK_USE_MYPYC", None) == "1":
-    USE_MYPYC = True
-
-if USE_MYPYC:
-    from mypyc.build import mypycify
-
-    src = CURRENT_DIR / "src"
-    # TIP: filepaths are normalized to use forward slashes and are relative to ./src/
-    # before being checked against.
-    blocklist = [
-        # Not performance sensitive, so save bytes + compilation time:
-        "blib2to3/__init__.py",
-        "blib2to3/pgen2/__init__.py",
-        "black/output.py",
-        "black/concurrency.py",
-        "black/files.py",
-        "black/report.py",
-        # Breaks the test suite when compiled (and is also useless):
-        "black/debug.py",
-        # Compiled modules can't be run directly and that's a problem here:
-        "black/__main__.py",
-    ]
-    discovered = []
-    # There's no good reason for blackd to be compiled.
-    discovered.extend(find_python_files(src / "black"))
-    discovered.extend(find_python_files(src / "blib2to3"))
-    mypyc_targets = [
-        str(p) for p in discovered if p.relative_to(src).as_posix() not in blocklist
-    ]
-
-    opt_level = os.getenv("MYPYC_OPT_LEVEL", "3")
-    debug_level = os.getenv("MYPYC_DEBUG_LEVEL", "3")
-    ext_modules = mypycify(
-        mypyc_targets, opt_level=opt_level, debug_level=debug_level, verbose=True
-    )
-else:
-    ext_modules = []
-
-setup(
-    name="black",
-    use_scm_version={
-        "write_to": "src/_black_version.py",
-        "write_to_template": 'version = "{version}"\n',
-    },
-    description="The uncompromising code formatter.",
-    long_description=get_long_description(),
-    long_description_content_type="text/markdown",
-    keywords="automation formatter yapf autopep8 pyfmt gofmt rustfmt",
-    author="Łukasz Langa",
-    author_email="lukasz@langa.pl",
-    url="https://github.com/psf/black",
-    project_urls={"Changelog": "https://github.com/psf/black/blob/main/CHANGES.md"},
-    license="MIT",
-    py_modules=["_black_version"],
-    ext_modules=ext_modules,
-    packages=find_packages(where="src"),
-    package_dir={"": "src"},
-    package_data={
-        "blib2to3": ["*.txt"],
-        "black": ["py.typed"],
-    },
-    python_requires=">=3.6.2",
-    zip_safe=False,
-    install_requires=[
-        "click>=8.0.0",
-        "platformdirs>=2",
-        "tomli>=1.1.0; python_full_version < '3.11.0a7'",
-        "typed-ast>=1.4.2; python_version < '3.8' and implementation_name == 'cpython'",
-        "pathspec>=0.9.0",
-        "dataclasses>=0.6; python_version < '3.7'",
-        "typing_extensions>=3.10.0.0; python_version < '3.10'",
-        "mypy_extensions>=0.4.3",
-    ],
-    extras_require={
-        "d": ["aiohttp>=3.7.4"],
-        "colorama": ["colorama>=0.4.3"],
-        "uvloop": ["uvloop>=0.15.2"],
-        "jupyter": ["ipython>=7.8.0", "tokenize-rt>=3.2.0"],
-    },
-    classifiers=[
-        "Development Status :: 5 - Production/Stable",
-        "Environment :: Console",
-        "Intended Audience :: Developers",
-        "License :: OSI Approved :: MIT License",
-        "Operating System :: OS Independent",
-        "Programming Language :: Python",
-        "Programming Language :: Python :: 3.6",
-        "Programming Language :: Python :: 3.7",
-        "Programming Language :: Python :: 3.8",
-        "Programming Language :: Python :: 3.9",
-        "Programming Language :: Python :: 3.10",
-        "Programming Language :: Python :: 3.11",
-        "Programming Language :: Python :: 3 :: Only",
-        "Topic :: Software Development :: Libraries :: Python Modules",
-        "Topic :: Software Development :: Quality Assurance",
-    ],
-    entry_points={
-        "console_scripts": [
-            "black=black:patched_main",
-            "blackd=blackd:patched_main [d]",
-        ]
-    },
-)
diff --git a/tox.ini b/tox.ini
index 098f06c9828..4934514264b 100644
--- a/tox.ini
+++ b/tox.ini
@@ -1,5 +1,6 @@
 [tox]
-envlist = {,ci-}py{36,37,38,39,310,311,py3},fuzz,run_self
+isolated_build = true
+envlist = {,ci-}py{37,38,39,310,311,py3},fuzz,run_self
 
 [testenv]
 setenv = PYTHONPATH = {toxinidir}/src
@@ -96,4 +97,4 @@ setenv = PYTHONPATH = {toxinidir}/src
 skip_install = True
 commands =
     pip install -e .[d]
-    black --check {toxinidir}/src {toxinidir}/tests {toxinidir}/setup.py
+    black --check {toxinidir}/src {toxinidir}/tests

From 2189bcaac01d9b6289411a75557a23cf4a06b783 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Sun, 25 Sep 2022 20:24:18 -0400
Subject: [PATCH 0620/1034] Fix outdated references to 3.6 and run pyupgrade
 (#3286)

I also missed the accidental removal of the 3.11 classifier in the PR.
---
 README.md                    |  5 ++---
 docs/getting_started.md      |  5 ++---
 docs/integrations/editors.md |  2 +-
 pyproject.toml               |  1 +
 src/black/comments.py        |  3 +--
 src/black/concurrency.py     | 12 ++----------
 src/black/trans.py           |  2 +-
 7 files changed, 10 insertions(+), 20 deletions(-)

diff --git a/README.md b/README.md
index 4c761606514..b2593024676 100644
--- a/README.md
+++ b/README.md
@@ -38,9 +38,8 @@ 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.6.2+ to
-run. If you want to format Jupyter Notebooks, install with
-`pip install 'black[jupyter]'`.
+_Black_ can be installed by running `pip install black`. It requires Python 3.7+ 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:
 
diff --git a/docs/getting_started.md b/docs/getting_started.md
index fca960915a8..1825f3b5aa3 100644
--- a/docs/getting_started.md
+++ b/docs/getting_started.md
@@ -16,9 +16,8 @@ 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.6.2+ to
-run. If you want to format Jupyter Notebooks, install with
-`pip install 'black[jupyter]'`.
+_Black_ can be installed by running `pip install black`. It requires Python 3.7+ 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:
 
diff --git a/docs/integrations/editors.md b/docs/integrations/editors.md
index 318e0e295d0..28c9f48a09f 100644
--- a/docs/integrations/editors.md
+++ b/docs/integrations/editors.md
@@ -148,7 +148,7 @@ curl https://raw.githubusercontent.com/psf/black/stable/autoload/black.vim -o ~/
 Let me know if this requires any changes to work with Vim 8's builtin `packadd`, or
 Pathogen, and so on.
 
-This plugin **requires Vim 7.0+ built with Python 3.6+ support**. It needs Python 3.6 to
+This plugin **requires Vim 7.0+ built with Python 3.7+ support**. It needs Python 3.7 to
 be able to run _Black_ inside the Vim process which is much faster than calling an
 external command.
 
diff --git a/pyproject.toml b/pyproject.toml
index c37702616fc..412e46cbc05 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -58,6 +58,7 @@ classifiers = [
   "Programming Language :: Python :: 3.8",
   "Programming Language :: Python :: 3.9",
   "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
   "Topic :: Software Development :: Libraries :: Python Modules",
   "Topic :: Software Development :: Quality Assurance",
 ]
diff --git a/src/black/comments.py b/src/black/comments.py
index 2a4c254ecd9..dce83abf1bb 100644
--- a/src/black/comments.py
+++ b/src/black/comments.py
@@ -270,8 +270,7 @@ def _generate_ignored_nodes_from_fmt_skip(
         while "\n" not in prev_sibling.prefix and prev_sibling.prev_sibling is not None:
             prev_sibling = prev_sibling.prev_sibling
             siblings.insert(0, prev_sibling)
-        for sibling in siblings:
-            yield sibling
+        yield from siblings
     elif (
         parent is not None and parent.type == syms.suite and leaf.type == token.NEWLINE
     ):
diff --git a/src/black/concurrency.py b/src/black/concurrency.py
index bdc368d5add..10e288f4f93 100644
--- a/src/black/concurrency.py
+++ b/src/black/concurrency.py
@@ -58,12 +58,7 @@ def shutdown(loop: asyncio.AbstractEventLoop) -> None:
 
         for task in to_cancel:
             task.cancel()
-        if sys.version_info >= (3, 7):
-            loop.run_until_complete(asyncio.gather(*to_cancel, return_exceptions=True))
-        else:
-            loop.run_until_complete(
-                asyncio.gather(*to_cancel, loop=loop, return_exceptions=True)
-            )
+        loop.run_until_complete(asyncio.gather(*to_cancel, return_exceptions=True))
     finally:
         # `concurrent.futures.Future` objects cannot be cancelled once they
         # are already running. There might be some when the `shutdown()` happened.
@@ -191,9 +186,6 @@ async def schedule_formatting(
                     sources_to_cache.append(src)
                 report.done(src, changed)
     if cancelled:
-        if sys.version_info >= (3, 7):
-            await asyncio.gather(*cancelled, return_exceptions=True)
-        else:
-            await asyncio.gather(*cancelled, loop=loop, return_exceptions=True)
+        await asyncio.gather(*cancelled, return_exceptions=True)
     if sources_to_cache:
         write_cache(cache, sources_to_cache, mode)
diff --git a/src/black/trans.py b/src/black/trans.py
index 74b932bb422..7e2d8e67c1a 100644
--- a/src/black/trans.py
+++ b/src/black/trans.py
@@ -1256,7 +1256,7 @@ def do_transform(self, line: Line, string_idx: int) -> Iterator[TResult[Line]]:
 
         string_op_leaves = self._get_string_operator_leaves(LL)
         string_op_leaves_length = (
-            sum([len(str(prefix_leaf)) for prefix_leaf in string_op_leaves]) + 1
+            sum(len(str(prefix_leaf)) for prefix_leaf in string_op_leaves) + 1
             if string_op_leaves
             else 0
         )

From af3de081542f66dfb1482dcf2a654b7e1668783c Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Sun, 25 Sep 2022 20:55:52 -0400
Subject: [PATCH 0621/1034] Always call freeze_support() if sys.frozen is True
 (#3275)

---
 CHANGES.md            | 3 +++
 src/black/__init__.py | 4 +++-
 2 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index a775c76e4a5..6fb099040b3 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -31,6 +31,9 @@
 
 <!-- Changes to how Black is packaged, such as dependency requirements -->
 
+- Executables made with PyInstaller will no longer crash when formatting several files
+  at once on macOS. Native x86-64 executables for macOS are available once again.
+  (#3275)
 - Hatchling is now used as the build backend. This will not have any effect for users
   who install Black with its wheels from PyPI. (#3233)
 - Faster compiled wheels are now available for CPython 3.11 (#3276)
diff --git a/src/black/__init__.py b/src/black/__init__.py
index ded4a736822..5b8c9749119 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -1375,7 +1375,9 @@ def patch_click() -> None:
 
 
 def patched_main() -> None:
-    if sys.platform == "win32" and getattr(sys, "frozen", False):
+    # PyInstaller patches multiprocessing to need freeze_support() even in non-Windows
+    # environments so just assume we always need to call it if frozen.
+    if getattr(sys, "frozen", False):
         from multiprocessing import freeze_support
 
         freeze_support()

From 42fdd1b91f87a92e39ad2676c863328dbf7d194d Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 26 Sep 2022 08:35:23 -0400
Subject: [PATCH 0622/1034] Bump actions/upload-artifact from 2 to 3 (#3289)

updated-dependencies:
- dependency-name: actions/upload-artifact
  dependency-type: direct:production
  update-type: version-update:semver-major

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/pypi_upload.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/pypi_upload.yml b/.github/workflows/pypi_upload.yml
index 2c288284444..b9da8b0cfce 100644
--- a/.github/workflows/pypi_upload.yml
+++ b/.github/workflows/pypi_upload.yml
@@ -63,7 +63,7 @@ jobs:
           CIBW_ARCHS_MACOS: "${{ matrix.macos_arch }}"
 
       - name: Upload wheels as workflow artifacts
-        uses: actions/upload-artifact@v2
+        uses: actions/upload-artifact@v3
         with:
           name: ${{ matrix.name }}-mypyc-wheels
           path: ./wheelhouse/*.whl

From 1f2ad77505337ee68ed5236fc5621cf0690e783c Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 26 Sep 2022 09:48:50 -0700
Subject: [PATCH 0623/1034] Bump sphinx from 5.1.1 to 5.2.1 in /docs (#3288)

Bumps [sphinx](https://github.com/sphinx-doc/sphinx) from 5.1.1 to 5.2.1.
- [Release notes](https://github.com/sphinx-doc/sphinx/releases)
- [Changelog](https://github.com/sphinx-doc/sphinx/blob/5.x/CHANGES)
- [Commits](https://github.com/sphinx-doc/sphinx/compare/v5.1.1...v5.2.1)

---
updated-dependencies:
- dependency-name: sphinx
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 docs/requirements.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index f4b59fd3cd9..efe5cf85b18 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,7 +1,7 @@
 # Used by ReadTheDocs; pinned requirements for stability.
 
 myst-parser==0.18.0
-Sphinx==5.1.1
+Sphinx==5.2.1
 # Older versions break Sphinx even though they're declared to be supported.
 docutils==0.18.1
 sphinxcontrib-programoutput==0.17

From 6b42c2b8c9f9bd666120a2c19b8da509fe477f27 Mon Sep 17 00:00:00 2001
From: Antonio Ossa-Guerra <aaossa@uc.cl>
Date: Mon, 26 Sep 2022 18:45:34 -0300
Subject: [PATCH 0624/1034] Add option to format Jupyter Notebooks in GitHub
 Action (#3282)

To run the formatter on Jupyter Notebooks, Black must be installed
with an extra dependency (`black[jupyter]`). This commit adds an
optional argument to install Black with this dependency when using the
official GitHub Action [1]. To enable the formatter on Jupyter
Notebooks, just add `jupyter: true` as an argument. Feature requested
at [2].

[1]: https://black.readthedocs.io/en/stable/integrations/github_actions.html
[2]: https://github.com/psf/black/issues/3280

Signed-off-by: Antonio Ossa Guerra <aaossa@uc.cl>
---
 AUTHORS.md                          | 1 +
 CHANGES.md                          | 2 ++
 action.yml                          | 6 ++++++
 action/main.py                      | 7 ++++++-
 docs/integrations/github_actions.md | 5 +++++
 5 files changed, 20 insertions(+), 1 deletion(-)

diff --git a/AUTHORS.md b/AUTHORS.md
index 533606240d3..f2d599dd878 100644
--- a/AUTHORS.md
+++ b/AUTHORS.md
@@ -29,6 +29,7 @@ Multiple contributions by:
 - [Andrey](mailto:dyuuus@yandex.ru)
 - [Andy Freeland](mailto:andy@andyfreeland.net)
 - [Anthony Sottile](mailto:asottile@umich.edu)
+- [Antonio Ossa Guerra](mailto:aaossa+black@uc.cl)
 - [Arjaan Buijk](mailto:arjaan.buijk@gmail.com)
 - [Arnav Borbornah](mailto:arnavborborah11@gmail.com)
 - [Artem Malyshev](mailto:proofit404@gmail.com)
diff --git a/CHANGES.md b/CHANGES.md
index 6fb099040b3..c96d9a6e492 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -58,6 +58,8 @@
 
 <!-- For example, Docker, GitHub Actions, pre-commit, editors -->
 
+- Update GitHub Action to support formatting of Jupyter Notebook files via a `jupyter`
+  option (#3282)
 - Update GitHub Action to support use of version specifiers (e.g. `<23`) for Black
   version (#3265)
 
diff --git a/action.yml b/action.yml
index cfa6ef9fb7e..35705e99414 100644
--- a/action.yml
+++ b/action.yml
@@ -12,6 +12,11 @@ inputs:
     description: "Source to run Black. Default: '.'"
     required: false
     default: "."
+  jupyter:
+    description:
+      "Set this option to true to include Jupyter Notebook files. Default: false"
+    required: false
+    default: false
   black_args:
     description: "[DEPRECATED] Black input arguments."
     required: false
@@ -38,6 +43,7 @@ runs:
         # TODO: Remove once https://github.com/actions/runner/issues/665 is fixed.
         INPUT_OPTIONS: ${{ inputs.options }}
         INPUT_SRC: ${{ inputs.src }}
+        INPUT_JUPYTER: ${{ inputs.jupyter }}
         INPUT_BLACK_ARGS: ${{ inputs.black_args }}
         INPUT_VERSION: ${{ inputs.version }}
         pythonioencoding: utf-8
diff --git a/action/main.py b/action/main.py
index 03228cb13e8..ff9d4112aed 100644
--- a/action/main.py
+++ b/action/main.py
@@ -9,6 +9,7 @@
 ENV_BIN = ENV_PATH / ("Scripts" if sys.platform == "win32" else "bin")
 OPTIONS = os.getenv("INPUT_OPTIONS", default="")
 SRC = os.getenv("INPUT_SRC", default="")
+JUPYTER = os.getenv("INPUT_JUPYTER") == "true"
 BLACK_ARGS = os.getenv("INPUT_BLACK_ARGS", default="")
 VERSION = os.getenv("INPUT_VERSION", default="")
 
@@ -17,7 +18,11 @@
 version_specifier = VERSION
 if VERSION and VERSION[0] in "0123456789":
     version_specifier = f"=={VERSION}"
-req = f"black[colorama]{version_specifier}"
+if JUPYTER:
+    extra_deps = "[colorama,jupyter]"
+else:
+    extra_deps = "[colorama]"
+req = f"black{extra_deps}{version_specifier}"
 pip_proc = run(
     [str(ENV_BIN / "python"), "-m", "pip", "install", req],
     stdout=PIPE,
diff --git a/docs/integrations/github_actions.md b/docs/integrations/github_actions.md
index d77b9693678..12bcb21fee6 100644
--- a/docs/integrations/github_actions.md
+++ b/docs/integrations/github_actions.md
@@ -39,6 +39,10 @@ or just the version number if you want an exact version. The action defaults to
 latest release available on PyPI. Only versions available from PyPI are supported, so no
 commit SHAs or branch names.
 
+If you want to include Jupyter Notebooks, _Black_ must be installed with the `jupyter`
+extra. Installing the extra and including Jupyter Notebook files can be configured via
+`jupyter` (default is `false`).
+
 You can also configure the arguments passed to _Black_ via `options` (defaults to
 `'--check --diff'`) and `src` (default is `'.'`)
 
@@ -49,6 +53,7 @@ Here's an example configuration:
   with:
     options: "--check --verbose"
     src: "./src"
+    jupyter: true
     version: "21.5b1"
 ```
 

From 096806ee269bb6823860e6fb3a33f25d79c6b6aa Mon Sep 17 00:00:00 2001
From: Ray Bell <rayjohnbell0@gmail.com>
Date: Wed, 28 Sep 2022 21:44:16 -0400
Subject: [PATCH 0625/1034] Mention CHANGES.md in PR template explicitly
 (#3295)

This makes the location more explicit which hopefully makes the PR
process smoother for other first time contributors.

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 .github/PULL_REQUEST_TEMPLATE.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 833cd164134..a039718cd70 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -18,7 +18,7 @@
     Tests are required for bugfixes and new features. Documentation changes
     are necessary for formatting and most enhancement changes. -->
 
-- [ ] Add a CHANGELOG entry if necessary?
+- [ ] Add an entry in `CHANGES.md` if necessary?
 - [ ] Add / update tests if necessary?
 - [ ] Add new / update outdated documentation?
 

From ddb99241b583f45e01df622c0d8f119aecd0188e Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Wed, 28 Sep 2022 22:19:08 -0400
Subject: [PATCH 0626/1034] Bump pypa/cibuildwheel from 2.10.0 to 2.10.2
 (#3290)

updated-dependencies:
- dependency-name: pypa/cibuildwheel
  dependency-type: direct:production
  update-type: version-update:semver-patch

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/pypi_upload.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/pypi_upload.yml b/.github/workflows/pypi_upload.yml
index b9da8b0cfce..76bcd33b55e 100644
--- a/.github/workflows/pypi_upload.yml
+++ b/.github/workflows/pypi_upload.yml
@@ -58,7 +58,7 @@ jobs:
       - uses: actions/checkout@v3
 
       - name: Build wheels via cibuildwheel
-        uses: pypa/cibuildwheel@v2.10.0
+        uses: pypa/cibuildwheel@v2.10.2
         env:
           CIBW_ARCHS_MACOS: "${{ matrix.macos_arch }}"
 

From 141291a1d86d43158da89d0254b7c2cc79609679 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Wed, 28 Sep 2022 22:56:28 -0400
Subject: [PATCH 0627/1034] Enable build isolation under CIWB (#3297)

No idea how this is still here after the Hatchling PR, but it is no
longer useful and is breaking the build.
---
 pyproject.toml | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/pyproject.toml b/pyproject.toml
index 412e46cbc05..554d7d07bf3 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -163,9 +163,6 @@ test-skip = ["*-macosx_arm64", "*-macosx_universal2:arm64"]
 HATCH_BUILD_HOOKS_ENABLE = "1"
 MYPYC_OPT_LEVEL = "3"
 MYPYC_DEBUG_LEVEL = "0"
-# The dependencies required to build wheels with mypyc aren't specified in
-# [build-system].requires so we'll have to manage the build environment ourselves.
-PIP_NO_BUILD_ISOLATION = "no"
 # CPython 3.11 wheels aren't available for aiohttp and building a Cython extension
 # from source also doesn't work.
 AIOHTTP_NO_EXTENSIONS = "1"

From 956bf3962edff284d05ad42576bac7e74ae8788d Mon Sep 17 00:00:00 2001
From: Ray Bell <rayjohnbell0@gmail.com>
Date: Sun, 2 Oct 2022 12:26:45 -0400
Subject: [PATCH 0628/1034] Add .ipynb_checkpoints to DEFAULT_EXCLUDES (#3293)

Jupyter creates a checkpoint file every single time you create an .ipynb
file, and then it updates the checkpoint file every single time you
manually save your progress for the initial .ipynb. These checkpoints
are stored in a directory named `.ipynb_checkpoints`.

Co-authored-by: Batuhan Taskaya <isidentical@gmail.com>
---
 CHANGES.md         | 2 ++
 src/black/const.py | 2 +-
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index c96d9a6e492..d3ba53fd05f 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -27,6 +27,8 @@
 
 <!-- Changes to how Black can be configured -->
 
+- `.ipynb_checkpoints` directories are now excluded by default (#3293)
+
 ### Packaging
 
 <!-- Changes to how Black is packaged, such as dependency requirements -->
diff --git a/src/black/const.py b/src/black/const.py
index 03afc96e8d6..0e13f31517d 100644
--- a/src/black/const.py
+++ b/src/black/const.py
@@ -1,4 +1,4 @@
 DEFAULT_LINE_LENGTH = 88
-DEFAULT_EXCLUDES = r"/(\.direnv|\.eggs|\.git|\.hg|\.mypy_cache|\.nox|\.tox|\.venv|venv|\.svn|_build|buck-out|build|dist|__pypackages__)/"  # noqa: B950
+DEFAULT_EXCLUDES = r"/(\.direnv|\.eggs|\.git|\.hg|\.mypy_cache|\.nox|\.tox|\.venv|venv|\.svn|\.ipynb_checkpoints|_build|buck-out|build|dist|__pypackages__)/"  # noqa: B950
 DEFAULT_INCLUDES = r"(\.pyi?|\.ipynb)$"
 STDIN_PLACEHOLDER = "__BLACK_STDIN_FILENAME__"

From b1077aa14ee6afc90aac15549a1f5d0aff4fd524 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 3 Oct 2022 02:06:06 -0500
Subject: [PATCH 0629/1034] Bump myst-parser from 0.18.0 to 0.18.1 in /docs
 (#3303)

Bumps [myst-parser](https://github.com/executablebooks/MyST-Parser) from 0.18.0 to 0.18.1.
- [Release notes](https://github.com/executablebooks/MyST-Parser/releases)
- [Changelog](https://github.com/executablebooks/MyST-Parser/blob/master/CHANGELOG.md)
- [Commits](https://github.com/executablebooks/MyST-Parser/compare/v0.18.0...v0.18.1)

---
updated-dependencies:
- dependency-name: myst-parser
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 docs/requirements.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index efe5cf85b18..4facf38f94f 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,6 +1,6 @@
 # Used by ReadTheDocs; pinned requirements for stability.
 
-myst-parser==0.18.0
+myst-parser==0.18.1
 Sphinx==5.2.1
 # Older versions break Sphinx even though they're declared to be supported.
 docutils==0.18.1

From 980997f215d25deb27e03ea704258f62199b8a5f Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 3 Oct 2022 02:08:20 -0500
Subject: [PATCH 0630/1034] Bump furo from 2022.9.15 to 2022.9.29 in /docs
 (#3304)

Bumps [furo](https://github.com/pradyunsg/furo) from 2022.9.15 to 2022.9.29.
- [Release notes](https://github.com/pradyunsg/furo/releases)
- [Changelog](https://github.com/pradyunsg/furo/blob/main/docs/changelog.md)
- [Commits](https://github.com/pradyunsg/furo/compare/2022.09.15...2022.09.29)

---
updated-dependencies:
- dependency-name: furo
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Cooper Lees <cooper@fb.com>
---
 docs/requirements.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index 4facf38f94f..b2e4a654752 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -6,4 +6,4 @@ Sphinx==5.2.1
 docutils==0.18.1
 sphinxcontrib-programoutput==0.17
 sphinx_copybutton==0.5.0
-furo==2022.9.15
+furo==2022.9.29

From 1a20c4d4874f912822f6a42cb61816330a4f6508 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 3 Oct 2022 02:15:59 -0500
Subject: [PATCH 0631/1034] Bump sphinx from 5.2.1 to 5.2.3 in /docs (#3305)

Bumps [sphinx](https://github.com/sphinx-doc/sphinx) from 5.2.1 to 5.2.3.
- [Release notes](https://github.com/sphinx-doc/sphinx/releases)
- [Changelog](https://github.com/sphinx-doc/sphinx/blob/5.x/CHANGES)
- [Commits](https://github.com/sphinx-doc/sphinx/compare/v5.2.1...v5.2.3)

---
updated-dependencies:
- dependency-name: sphinx
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 docs/requirements.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index b2e4a654752..a3c6da0fb44 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,7 +1,7 @@
 # Used by ReadTheDocs; pinned requirements for stability.
 
 myst-parser==0.18.1
-Sphinx==5.2.1
+Sphinx==5.2.3
 # Older versions break Sphinx even though they're declared to be supported.
 docutils==0.18.1
 sphinxcontrib-programoutput==0.17

From 27d7ea43eb127cc5189a724a7d194d94ba312861 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 3 Oct 2022 09:36:44 -0700
Subject: [PATCH 0632/1034] Bump docutils from 0.18.1 to 0.19 in /docs (#3161)

Bumps [docutils](https://docutils.sourceforge.io/) from 0.18.1 to 0.19.

---
updated-dependencies:
- dependency-name: docutils
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>
---
 docs/requirements.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index a3c6da0fb44..3c4b43511f6 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -3,7 +3,7 @@
 myst-parser==0.18.1
 Sphinx==5.2.3
 # Older versions break Sphinx even though they're declared to be supported.
-docutils==0.18.1
+docutils==0.19
 sphinxcontrib-programoutput==0.17
 sphinx_copybutton==0.5.0
 furo==2022.9.29

From 0359b85b5800dd77f8f1cfaa88ca8ab8215df685 Mon Sep 17 00:00:00 2001
From: KotlinIsland <65446343+KotlinIsland@users.noreply.github.com>
Date: Wed, 5 Oct 2022 06:10:11 +1000
Subject: [PATCH 0633/1034] Preserve crlf line endings in blackd (#3257)

Co-authored-by: KotlinIsland <kotlinisland@users.noreply.github.com>
---
 CHANGES.md                                 |  2 +-
 docs/the_black_code_style/current_style.md |  5 +++++
 src/blackd/__init__.py                     |  7 +++++++
 tests/test_black.py                        | 11 +++++++++++
 tests/test_blackd.py                       | 17 +++++++++++++++++
 5 files changed, 41 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index d3ba53fd05f..4ff181674b1 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -54,7 +54,7 @@
 
 ### _Blackd_
 
-<!-- Changes to blackd -->
+- Windows style (CRLF) newlines will be preserved (#3257).
 
 ### Integrations
 
diff --git a/docs/the_black_code_style/current_style.md b/docs/the_black_code_style/current_style.md
index 3db49e2ba01..59d79c4cd0e 100644
--- a/docs/the_black_code_style/current_style.md
+++ b/docs/the_black_code_style/current_style.md
@@ -406,6 +406,11 @@ file that are not enforced yet but might be in a future version of the formatter
 - use variable annotations instead of type comments, even for stubs that target older
   versions of Python.
 
+### Line endings
+
+_Black_ will normalize line endings (`\n` or `\r\n`) based on the first line ending of
+the file.
+
 ## Pragmatism
 
 Early versions of _Black_ used to be absolutist in some respects. They took after its
diff --git a/src/blackd/__init__.py b/src/blackd/__init__.py
index e52a9917cf3..6bbc7c52086 100644
--- a/src/blackd/__init__.py
+++ b/src/blackd/__init__.py
@@ -133,6 +133,13 @@ async def handle(request: web.Request, executor: Executor) -> web.Response:
             executor, partial(black.format_file_contents, req_str, fast=fast, mode=mode)
         )
 
+        # Preserve CRLF line endings
+        if req_str[req_str.find("\n") - 1] == "\r":
+            formatted_str = formatted_str.replace("\n", "\r\n")
+            # If, after swapping line endings, nothing changed, then say so
+            if formatted_str == req_str:
+                raise black.NothingChanged
+
         # Only output the diff in the HTTP response
         only_diff = bool(request.headers.get(DIFF_HEADER, False))
         if only_diff:
diff --git a/tests/test_black.py b/tests/test_black.py
index abd4d00b8e8..96e6f1e6945 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -1286,6 +1286,17 @@ def test_preserves_line_endings_via_stdin(self) -> None:
             if nl == "\n":
                 self.assertNotIn(b"\r\n", output)
 
+    def test_normalize_line_endings(self) -> None:
+        with TemporaryDirectory() as workspace:
+            test_file = Path(workspace) / "test.py"
+            for data, expected in (
+                (b"c\r\nc\n ", b"c\r\nc\r\n"),
+                (b"l\nl\r\n ", b"l\nl\n"),
+            ):
+                test_file.write_bytes(data)
+                ff(test_file, write_back=black.WriteBack.YES)
+                self.assertEqual(test_file.read_bytes(), expected)
+
     def test_assert_equivalent_different_asts(self) -> None:
         with self.assertRaises(AssertionError):
             black.assert_equivalent("{}", "None")
diff --git a/tests/test_blackd.py b/tests/test_blackd.py
index 511bd86441d..db9a1652f8c 100644
--- a/tests/test_blackd.py
+++ b/tests/test_blackd.py
@@ -209,3 +209,20 @@ async def test_cors_headers_present(self) -> None:
         response = await self.client.post("/", headers={"Origin": "*"})
         self.assertIsNotNone(response.headers.get("Access-Control-Allow-Origin"))
         self.assertIsNotNone(response.headers.get("Access-Control-Expose-Headers"))
+
+    @unittest_run_loop
+    async def test_preserves_line_endings(self) -> None:
+        for data in (b"c\r\nc\r\n", b"l\nl\n"):
+            # test preserved newlines when reformatted
+            response = await self.client.post("/", data=data + b" ")
+            self.assertEqual(await response.text(), data.decode())
+            # test 204 when no change
+            response = await self.client.post("/", data=data)
+            self.assertEqual(response.status, 204)
+
+    @unittest_run_loop
+    async def test_normalizes_line_endings(self) -> None:
+        for data, expected in ((b"c\r\nc\n", "c\r\nc\r\n"), (b"l\nl\r\n", "l\nl\n")):
+            response = await self.client.post("/", data=data)
+            self.assertEqual(await response.text(), expected)
+            self.assertEqual(response.status, 200)

From 4da0851809e024760d3861ff43309125de34157a Mon Sep 17 00:00:00 2001
From: Antonio Ossa-Guerra <aaossa@uc.cl>
Date: Thu, 6 Oct 2022 19:17:32 -0300
Subject: [PATCH 0634/1034] Add option to skip the first line of source code
 (#3299)

* Add option to skip the first line in source file

This commit adds a CLi option to skip the first line in the source
files, just like the Cpython command line allows [1]. By enabling the
flag, using `-x` or `--skip-source-first-line`, the first line is
removed temporarilly while the remaining contents are formatted. The
first line is added back before returning the formatted output.

[1]: https://docs.python.org/dev/using/cmdline.html#cmdoption-x

Signed-off-by: Antonio Ossa Guerra <aaossa@uc.cl>

* Add tests for `--skip-source-first-line` option

When the flag is disabled (default), black formats the entire source
file, as in every line. In the other hand, if the flag is enabled, by
using `-x` or `--skip-source-first-line`, the first line is retained
while the rest of the source is formatted and then is added back.

These tests use an empty Python file that contains invalid syntax in
its first line (`invalid_header.py`, at `miscellaneous/`). First,
Black is invoked without enabling the flag which should result in an
exit code different than 0. When the flag is enabled, Black is
expected to return a successful exit code and the header is expected
to be retained (even if its not valid Python syntax).

Signed-off-by: Antonio Ossa Guerra <aaossa@uc.cl>

* Support skip source first line option for blackd

The recently added option can be added as an acceptable header for
blackd. The arguments are passed in such a way that using the new
header will activate the skip source first line behaviour as expected

Signed-off-by: Antonio Ossa Guerra <aaossa@uc.cl>

* Add skip source first line option to blackd docs

The new option can be passed to blackd as a header. This commit
updates the blackd docs to include the new header.

Signed-off-by: Antonio Ossa Guerra <aaossa@uc.cl>

* Update CHANGES.md

Include the new Black option to skip the first line of source code in
the configuration section

Signed-off-by: Antonio Ossa Guerra <aaossa@uc.cl>

* Update skip first line test including valid syntax

Including valid Python syntax help us make sure that the file is still
actually valid after skipping the first line of the source file (which
contains invalid Python syntax)

Signed-off-by: Antonio Ossa Guerra <aaossa@uc.cl>

* Skip first source line at `format_file_in_place`

Instead of skipping the first source line at `format_file_contents`,
do it before. This allow us to find the correct newline and encoding
on the actual source code (everything that's after the header).

This change is also applied at Blackd: take the header before passing
the source to `format_file_contents` and put the header back once we
get the formatted result.

Signed-off-by: Antonio Ossa Guerra <aaossa@uc.cl>

* Test output newlines when skipping first line

When skipping the first line of source code, the reference newline must
be taken from the second line of the file instead of the first one, in
case that the file mixes more than one kind of newline character

Signed-off-by: Antonio Ossa Guerra <aaossa@uc.cl>

* Test that Blackd also skips first line correctly

Simliarly to the Black tests, we first compare that Blackd fails when
the first line is invalid Python syntax and then check that the result
is the expected when tha flag is activated

Signed-off-by: Antonio Ossa Guerra <aaossa@uc.cl>

* Use the content encoding to decode the header

When decoding the header to put it back at the top of the contents of
the file, use the same encoding used in the content. This should be a
better "guess" that using the default value

Signed-off-by: Antonio Ossa Guerra <aaossa@uc.cl>
---
 CHANGES.md                                    |  2 ++
 .../black_as_a_server.md                      |  3 +++
 src/black/__init__.py                         | 13 ++++++++++
 src/black/mode.py                             |  2 ++
 src/blackd/__init__.py                        | 16 +++++++++++++
 tests/data/miscellaneous/invalid_header.py    |  2 ++
 tests/test_black.py                           | 24 +++++++++++++++++++
 tests/test_blackd.py                          | 14 +++++++++++
 8 files changed, 76 insertions(+)
 create mode 100644 tests/data/miscellaneous/invalid_header.py

diff --git a/CHANGES.md b/CHANGES.md
index 4ff181674b1..ffdbd9c7aff 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -28,6 +28,8 @@
 <!-- Changes to how Black can be configured -->
 
 - `.ipynb_checkpoints` directories are now excluded by default (#3293)
+- Add `--skip-source-first-line` / `-x` option to ignore the first line of source code
+  while formatting (#3299)
 
 ### Packaging
 
diff --git a/docs/usage_and_configuration/black_as_a_server.md b/docs/usage_and_configuration/black_as_a_server.md
index a2d4252109a..f24fb34d915 100644
--- a/docs/usage_and_configuration/black_as_a_server.md
+++ b/docs/usage_and_configuration/black_as_a_server.md
@@ -50,6 +50,9 @@ is rejected with `HTTP 501` (Not Implemented).
 The headers controlling how source code is formatted are:
 
 - `X-Line-Length`: corresponds to the `--line-length` command line flag.
+- `X-Skip-Source-First-Line`: corresponds to the `--skip-source-first-line` command line
+  flag. If present and its value is not an empty string, the first line of the source
+  code will be ignored.
 - `X-Skip-String-Normalization`: corresponds to the `--skip-string-normalization`
   command line flag. If present and its value is not the empty string, no string
   normalization will be performed.
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 5b8c9749119..afd71e51916 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -248,6 +248,12 @@ def validate_regex(
     ),
     default=[],
 )
+@click.option(
+    "-x",
+    "--skip-source-first-line",
+    is_flag=True,
+    help="Skip the first line of the source code.",
+)
 @click.option(
     "-S",
     "--skip-string-normalization",
@@ -428,6 +434,7 @@ def main(  # noqa: C901
     pyi: bool,
     ipynb: bool,
     python_cell_magics: Sequence[str],
+    skip_source_first_line: bool,
     skip_string_normalization: bool,
     skip_magic_trailing_comma: bool,
     experimental_string_processing: bool,
@@ -528,6 +535,7 @@ def main(  # noqa: C901
         line_length=line_length,
         is_pyi=pyi,
         is_ipynb=ipynb,
+        skip_source_first_line=skip_source_first_line,
         string_normalization=not skip_string_normalization,
         magic_trailing_comma=not skip_magic_trailing_comma,
         experimental_string_processing=experimental_string_processing,
@@ -790,7 +798,10 @@ def format_file_in_place(
         mode = replace(mode, is_ipynb=True)
 
     then = datetime.utcfromtimestamp(src.stat().st_mtime)
+    header = b""
     with open(src, "rb") as buf:
+        if mode.skip_source_first_line:
+            header = buf.readline()
         src_contents, encoding, newline = decode_bytes(buf.read())
     try:
         dst_contents = format_file_contents(src_contents, fast=fast, mode=mode)
@@ -800,6 +811,8 @@ def format_file_in_place(
         raise ValueError(
             f"File '{src}' cannot be parsed as valid Jupyter notebook."
         ) from None
+    src_contents = header.decode(encoding) + src_contents
+    dst_contents = header.decode(encoding) + dst_contents
 
     if write_back == WriteBack.YES:
         with open(src, "w", encoding=encoding, newline=newline) as f:
diff --git a/src/black/mode.py b/src/black/mode.py
index 6c0847e8bcc..e3c36450ed1 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -170,6 +170,7 @@ class Mode:
     string_normalization: bool = True
     is_pyi: bool = False
     is_ipynb: bool = False
+    skip_source_first_line: bool = False
     magic_trailing_comma: bool = True
     experimental_string_processing: bool = False
     python_cell_magics: Set[str] = field(default_factory=set)
@@ -208,6 +209,7 @@ def get_cache_key(self) -> str:
             str(int(self.string_normalization)),
             str(int(self.is_pyi)),
             str(int(self.is_ipynb)),
+            str(int(self.skip_source_first_line)),
             str(int(self.magic_trailing_comma)),
             str(int(self.experimental_string_processing)),
             str(int(self.preview)),
diff --git a/src/blackd/__init__.py b/src/blackd/__init__.py
index 6bbc7c52086..ba4750b8298 100644
--- a/src/blackd/__init__.py
+++ b/src/blackd/__init__.py
@@ -30,6 +30,7 @@
 PROTOCOL_VERSION_HEADER = "X-Protocol-Version"
 LINE_LENGTH_HEADER = "X-Line-Length"
 PYTHON_VARIANT_HEADER = "X-Python-Variant"
+SKIP_SOURCE_FIRST_LINE = "X-Skip-Source-First-Line"
 SKIP_STRING_NORMALIZATION_HEADER = "X-Skip-String-Normalization"
 SKIP_MAGIC_TRAILING_COMMA = "X-Skip-Magic-Trailing-Comma"
 PREVIEW = "X-Preview"
@@ -40,6 +41,7 @@
     PROTOCOL_VERSION_HEADER,
     LINE_LENGTH_HEADER,
     PYTHON_VARIANT_HEADER,
+    SKIP_SOURCE_FIRST_LINE,
     SKIP_STRING_NORMALIZATION_HEADER,
     SKIP_MAGIC_TRAILING_COMMA,
     PREVIEW,
@@ -111,6 +113,9 @@ async def handle(request: web.Request, executor: Executor) -> web.Response:
         skip_magic_trailing_comma = bool(
             request.headers.get(SKIP_MAGIC_TRAILING_COMMA, False)
         )
+        skip_source_first_line = bool(
+            request.headers.get(SKIP_SOURCE_FIRST_LINE, False)
+        )
         preview = bool(request.headers.get(PREVIEW, False))
         fast = False
         if request.headers.get(FAST_OR_SAFE_HEADER, "safe") == "fast":
@@ -119,6 +124,7 @@ async def handle(request: web.Request, executor: Executor) -> web.Response:
             target_versions=versions,
             is_pyi=pyi,
             line_length=line_length,
+            skip_source_first_line=skip_source_first_line,
             string_normalization=not skip_string_normalization,
             magic_trailing_comma=not skip_magic_trailing_comma,
             preview=preview,
@@ -128,6 +134,12 @@ async def handle(request: web.Request, executor: Executor) -> web.Response:
         req_str = req_bytes.decode(charset)
         then = datetime.utcnow()
 
+        header = ""
+        if skip_source_first_line:
+            first_newline_position: int = req_str.find("\n") + 1
+            header = req_str[:first_newline_position]
+            req_str = req_str[first_newline_position:]
+
         loop = asyncio.get_event_loop()
         formatted_str = await loop.run_in_executor(
             executor, partial(black.format_file_contents, req_str, fast=fast, mode=mode)
@@ -140,6 +152,10 @@ async def handle(request: web.Request, executor: Executor) -> web.Response:
             if formatted_str == req_str:
                 raise black.NothingChanged
 
+        # Put the source first line back
+        req_str = header + req_str
+        formatted_str = header + formatted_str
+
         # Only output the diff in the HTTP response
         only_diff = bool(request.headers.get(DIFF_HEADER, False))
         if only_diff:
diff --git a/tests/data/miscellaneous/invalid_header.py b/tests/data/miscellaneous/invalid_header.py
new file mode 100644
index 00000000000..fb49e2f93e7
--- /dev/null
+++ b/tests/data/miscellaneous/invalid_header.py
@@ -0,0 +1,2 @@
+This is not valid Python syntax
+y = "This is valid syntax"
diff --git a/tests/test_black.py b/tests/test_black.py
index 96e6f1e6945..5d0175d9d66 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -341,6 +341,30 @@ def test_string_quotes(self) -> None:
         black.assert_equivalent(source, not_normalized)
         black.assert_stable(source, not_normalized, mode=mode)
 
+    def test_skip_source_first_line(self) -> None:
+        source, _ = read_data("miscellaneous", "invalid_header")
+        tmp_file = Path(black.dump_to_file(source))
+        # Full source should fail (invalid syntax at header)
+        self.invokeBlack([str(tmp_file), "--diff", "--check"], exit_code=123)
+        # So, skipping the first line should work
+        result = BlackRunner().invoke(
+            black.main, [str(tmp_file), "-x", f"--config={EMPTY_CONFIG}"]
+        )
+        self.assertEqual(result.exit_code, 0)
+        with open(tmp_file, encoding="utf8") as f:
+            actual = f.read()
+        self.assertFormatEqual(source, actual)
+
+    def test_skip_source_first_line_when_mixing_newlines(self) -> None:
+        code_mixing_newlines = b"Header will be skipped\r\ni = [1,2,3]\nj = [1,2,3]\n"
+        expected = b"Header will be skipped\r\ni = [1, 2, 3]\nj = [1, 2, 3]\n"
+        with TemporaryDirectory() as workspace:
+            test_file = Path(workspace) / "skip_header.py"
+            test_file.write_bytes(code_mixing_newlines)
+            mode = replace(DEFAULT_MODE, skip_source_first_line=True)
+            ff(test_file, mode=mode, write_back=black.WriteBack.YES)
+            self.assertEqual(test_file.read_bytes(), expected)
+
     def test_skip_magic_trailing_comma(self) -> None:
         source, _ = read_data("simple_cases", "expression")
         expected, _ = read_data(
diff --git a/tests/test_blackd.py b/tests/test_blackd.py
index db9a1652f8c..5b6461f7685 100644
--- a/tests/test_blackd.py
+++ b/tests/test_blackd.py
@@ -177,6 +177,20 @@ async def test_blackd_invalid_line_length(self) -> None:
         )
         self.assertEqual(response.status, 400)
 
+    @unittest_run_loop
+    async def test_blackd_skip_first_source_line(self) -> None:
+        invalid_first_line = b"Header will be skipped\r\ni = [1,2,3]\nj = [1,2,3]\n"
+        expected_result = b"Header will be skipped\r\ni = [1, 2, 3]\nj = [1, 2, 3]\n"
+        response = await self.client.post("/", data=invalid_first_line)
+        self.assertEqual(response.status, 400)
+        response = await self.client.post(
+            "/",
+            data=invalid_first_line,
+            headers={blackd.SKIP_SOURCE_FIRST_LINE: "true"},
+        )
+        self.assertEqual(response.status, 200)
+        self.assertEqual(await response.read(), expected_result)
+
     @unittest_run_loop
     async def test_blackd_preview(self) -> None:
         response = await self.client.post(

From 27d20144a7517594e24a1649451177b2a11284be Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Thu, 6 Oct 2022 15:33:51 -0700
Subject: [PATCH 0635/1034] Prepare release 22.10.0 (#3311)

---
 CHANGES.md                                  | 72 +++++++++++++--------
 docs/faq.md                                 |  2 +-
 docs/integrations/source_version_control.md |  2 +-
 docs/usage_and_configuration/the_basics.md  |  2 +-
 4 files changed, 48 insertions(+), 30 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index ffdbd9c7aff..3a8cf4d6af5 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -6,42 +6,22 @@
 
 <!-- Include any especially major or disruptive changes here -->
 
-- Runtime support for Python 3.6 has been removed. Formatting 3.6 code will still be
-  supported until further notice.
-
 ### Stable style
 
 <!-- Changes that affect Black's stable style -->
 
-- Fix a crash when `# fmt: on` is used on a different block level than `# fmt: off`
-  (#3281)
-
 ### Preview style
 
 <!-- Changes that affect Black's preview style -->
 
-- Fix a crash when formatting some dicts with parenthesis-wrapped long string keys
-  (#3262)
-
 ### Configuration
 
 <!-- Changes to how Black can be configured -->
 
-- `.ipynb_checkpoints` directories are now excluded by default (#3293)
-- Add `--skip-source-first-line` / `-x` option to ignore the first line of source code
-  while formatting (#3299)
-
 ### Packaging
 
 <!-- Changes to how Black is packaged, such as dependency requirements -->
 
-- Executables made with PyInstaller will no longer crash when formatting several files
-  at once on macOS. Native x86-64 executables for macOS are available once again.
-  (#3275)
-- Hatchling is now used as the build backend. This will not have any effect for users
-  who install Black with its wheels from PyPI. (#3233)
-- Faster compiled wheels are now available for CPython 3.11 (#3276)
-
 ### Parser
 
 <!-- Changes to the parser or to version autodetection -->
@@ -56,22 +36,61 @@
 
 ### _Blackd_
 
-- Windows style (CRLF) newlines will be preserved (#3257).
+<!-- Changes to blackd -->
 
 ### Integrations
 
 <!-- For example, Docker, GitHub Actions, pre-commit, editors -->
 
-- Update GitHub Action to support formatting of Jupyter Notebook files via a `jupyter`
-  option (#3282)
-- Update GitHub Action to support use of version specifiers (e.g. `<23`) for Black
-  version (#3265)
-
 ### Documentation
 
 <!-- Major changes to documentation and policies. Small docs changes
      don't need a changelog entry. -->
 
+## 22.10.0
+
+### Highlights
+
+- Runtime support for Python 3.6 has been removed. Formatting 3.6 code will still be
+  supported until further notice.
+
+### Stable style
+
+- Fix a crash when `# fmt: on` is used on a different block level than `# fmt: off`
+  (#3281)
+
+### Preview style
+
+- Fix a crash when formatting some dicts with parenthesis-wrapped long string keys
+  (#3262)
+
+### Configuration
+
+- `.ipynb_checkpoints` directories are now excluded by default (#3293)
+- Add `--skip-source-first-line` / `-x` option to ignore the first line of source code
+  while formatting (#3299)
+
+### Packaging
+
+- Executables made with PyInstaller will no longer crash when formatting several files
+  at once on macOS. Native x86-64 executables for macOS are available once again.
+  (#3275)
+- Hatchling is now used as the build backend. This will not have any effect for users
+  who install Black with its wheels from PyPI. (#3233)
+- Faster compiled wheels are now available for CPython 3.11 (#3276)
+
+### _Blackd_
+
+- Windows style (CRLF) newlines will be preserved (#3257).
+
+### Integrations
+
+- Vim plugin: add flag (`g:black_preview`) to enable/disable the preview style (#3246)
+- Update GitHub Action to support formatting of Jupyter Notebook files via a `jupyter`
+  option (#3282)
+- Update GitHub Action to support use of version specifiers (e.g. `<23`) for Black
+  version (#3265)
+
 ## 22.8.0
 
 ### Highlights
@@ -126,7 +145,6 @@
 - Vim plugin: prefix messages with `Black: ` so it's clear they come from Black (#3194)
 - Docker: changed to a /opt/venv installation + added to PATH to be available to
   non-root users (#3202)
-- Vim plugin: add flag (`g:black_preview`) to enable/disable the preview style (#3246)
 
 ### Output
 
diff --git a/docs/faq.md b/docs/faq.md
index 8b9ffb0202e..bc9deccb756 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -95,7 +95,7 @@ Support for formatting Python 2 code was removed in version 22.0. While we've ma
 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.6 was removed in version 22.9.0.
+Runtime support for 3.6 was removed in version 22.10.0.
 
 ## Why does my linter or typechecker complain after I format my code?
 
diff --git a/docs/integrations/source_version_control.md b/docs/integrations/source_version_control.md
index 31d0df27273..4189b5c4b06 100644
--- a/docs/integrations/source_version_control.md
+++ b/docs/integrations/source_version_control.md
@@ -7,7 +7,7 @@ Use [pre-commit](https://pre-commit.com/). Once you
 ```yaml
 repos:
   - repo: https://github.com/psf/black
-    rev: 22.8.0
+    rev: 22.10.0
     hooks:
       - id: black
         # It is recommended to specify the latest version of Python
diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index aa176c4ba3f..20aa956dd85 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -173,7 +173,7 @@ You can check the version of _Black_ you have installed using the `--version` fl
 
 ```console
 $ black --version
-black, version 22.8.0
+black, version 22.10.0
 ```
 
 An option to require a specific version to be running is also provided.

From b60b85b234d6a575f636d0a125478115f993c90c Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <hugovk@users.noreply.github.com>
Date: Thu, 6 Oct 2022 17:37:37 -0700
Subject: [PATCH 0636/1034] Remove redundant 3.6 code and bump mypy's
 python_version to 3.7 (#3313)

---
 autoload/black.vim       | 4 ++--
 mypy.ini                 | 7 +------
 src/black/__init__.py    | 4 ++--
 src/black/concurrency.py | 6 +-----
 src/black/parsing.py     | 3 +--
 5 files changed, 7 insertions(+), 17 deletions(-)

diff --git a/autoload/black.vim b/autoload/black.vim
index e87a1e4edfa..eec44637950 100644
--- a/autoload/black.vim
+++ b/autoload/black.vim
@@ -57,8 +57,8 @@ def _get_virtualenv_site_packages(venv_path, pyver):
 
 def _initialize_black_env(upgrade=False):
   pyver = sys.version_info[:3]
-  if pyver < (3, 6, 2):
-    print("Sorry, Black requires Python 3.6.2+ to run.")
+  if pyver < (3, 7):
+    print("Sorry, Black requires Python 3.7+ to run.")
     return False
 
   from pathlib import Path
diff --git a/mypy.ini b/mypy.ini
index 4811cc0be76..58bb7536173 100644
--- a/mypy.ini
+++ b/mypy.ini
@@ -2,7 +2,7 @@
 # Specify the target platform details in config, so your developers are
 # free to run mypy on Windows, Linux, or macOS and get consistent
 # results.
-python_version=3.6
+python_version=3.7
 
 mypy_path=src
 
@@ -19,11 +19,6 @@ no_implicit_reexport = False
 # to avoid 'em in the first place.
 warn_unreachable=True
 
-[mypy-black]
-# The following is because of `patch_click()`. Remove when
-# we drop Python 3.6 support.
-warn_unused_ignores=False
-
 [mypy-blib2to3.driver.*]
 ignore_missing_imports = True
 
diff --git a/src/black/__init__.py b/src/black/__init__.py
index afd71e51916..5293796aea1 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -1382,9 +1382,9 @@ def patch_click() -> None:
 
     for module in modules:
         if hasattr(module, "_verify_python3_env"):
-            module._verify_python3_env = lambda: None  # type: ignore
+            module._verify_python3_env = lambda: None
         if hasattr(module, "_verify_python_env"):
-            module._verify_python_env = lambda: None  # type: ignore
+            module._verify_python_env = lambda: None
 
 
 def patched_main() -> None:
diff --git a/src/black/concurrency.py b/src/black/concurrency.py
index 10e288f4f93..1598f51e43f 100644
--- a/src/black/concurrency.py
+++ b/src/black/concurrency.py
@@ -47,12 +47,8 @@ def cancel(tasks: Iterable["asyncio.Task[Any]"]) -> None:
 def shutdown(loop: asyncio.AbstractEventLoop) -> None:
     """Cancel all pending tasks on `loop`, wait for them, and close the loop."""
     try:
-        if sys.version_info[:2] >= (3, 7):
-            all_tasks = asyncio.all_tasks
-        else:
-            all_tasks = asyncio.Task.all_tasks
         # This part is borrowed from asyncio/runners.py in Python 3.7b2.
-        to_cancel = [task for task in all_tasks(loop) if not task.done()]
+        to_cancel = [task for task in asyncio.all_tasks(loop) if not task.done()]
         if not to_cancel:
             return
 
diff --git a/src/black/parsing.py b/src/black/parsing.py
index 64c0b1e3018..f7d9fdc2f13 100644
--- a/src/black/parsing.py
+++ b/src/black/parsing.py
@@ -27,8 +27,7 @@
 try:
     from typed_ast import ast3
 except ImportError:
-    # Either our python version is too low, or we're on pypy
-    if sys.version_info < (3, 7) or (sys.version_info < (3, 8) and not _IS_PYPY):
+    if sys.version_info < (3, 8) and not _IS_PYPY:
         print(
             "The typed_ast package is required but not installed.\n"
             "You can upgrade to Python 3.8+ or install typed_ast with\n"

From 1c786ee6273377ac68a98483c1e6e7cd81bde332 Mon Sep 17 00:00:00 2001
From: Batuhan Taskaya <isidentical@gmail.com>
Date: Tue, 11 Oct 2022 02:54:09 +0300
Subject: [PATCH 0637/1034] Add support for named exprs inside function calls
 as gen-exps (#3327)

---
 CHANGES.md                         |  4 ++++
 src/blib2to3/Grammar.txt           |  2 +-
 tests/data/py_310/pep_572_py310.py | 11 +++++++++++
 3 files changed, 16 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index 3a8cf4d6af5..ba9f4c06f28 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -26,6 +26,10 @@
 
 <!-- Changes to the parser or to version autodetection -->
 
+- Parsing support has been added for walruses inside generator expression that are
+  passed as function args (for example,
+  `any(match := my_re.match(text) for text in texts)`) (#3327).
+
 ### Performance
 
 <!-- Changes that improve Black's performance. -->
diff --git a/src/blib2to3/Grammar.txt b/src/blib2to3/Grammar.txt
index ac7ad7643ff..bd8a452a386 100644
--- a/src/blib2to3/Grammar.txt
+++ b/src/blib2to3/Grammar.txt
@@ -186,7 +186,7 @@ arglist: argument (',' argument)* [',']
 # multiple (test comp_for) arguments are blocked; keyword unpackings
 # that precede iterable unpackings are blocked; etc.
 argument: ( test [comp_for] |
-            test ':=' test |
+            test ':=' test [comp_for] |
             test 'as' test |
             test '=' asexpr_test |
 	    '**' test |
diff --git a/tests/data/py_310/pep_572_py310.py b/tests/data/py_310/pep_572_py310.py
index 2aef589ce8d..cb82b2d23f8 100644
--- a/tests/data/py_310/pep_572_py310.py
+++ b/tests/data/py_310/pep_572_py310.py
@@ -2,3 +2,14 @@
 x[a:=0]
 x[a:=0, b:=1]
 x[5, b:=0]
+
+# Walruses are allowed inside generator expressions on function calls since 3.10.
+if any(match := pattern_error.match(s) for s in buffer):
+    if match.group(2) == data_not_available:
+        # Error OK to ignore.
+        pass
+
+f(a := b + c for c in range(10))
+f((a := b + c for c in range(10)), x)
+f(y=(a := b + c for c in range(10)))
+f(x, (a := b + c for c in range(10)), y=z, **q)

From d923945513d8f679f43aec44aa8b777e5f9aab14 Mon Sep 17 00:00:00 2001
From: Amethyst Reese <amy@n7.gg>
Date: Mon, 10 Oct 2022 16:54:49 -0700
Subject: [PATCH 0638/1034] Fix license metadata to follow PEP 621 (#3326)

---
 AUTHORS.md     | 1 +
 pyproject.toml | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/AUTHORS.md b/AUTHORS.md
index f2d599dd878..a635e8c3c92 100644
--- a/AUTHORS.md
+++ b/AUTHORS.md
@@ -24,6 +24,7 @@ Multiple contributions by:
 - [Alex Vandiver](mailto:github@chmrr.net)
 - [Allan Simon](mailto:allan.simon@supinfo.com)
 - Anders-Petter Ljungquist
+- [Amethyst Reese](mailto:amy@n7.gg)
 - [Andrew Thorp](mailto:andrew.thorp.dev@gmail.com)
 - [Andrew Zhou](mailto:andrewfzhou@gmail.com)
 - [Andrey](mailto:dyuuus@yandex.ru)
diff --git a/pyproject.toml b/pyproject.toml
index 554d7d07bf3..329adaa65d8 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -32,7 +32,7 @@ build-backend = "hatchling.build"
 [project]
 name = "black"
 description = "The uncompromising code formatter."
-license = "MIT"
+license = { text = "MIT" }
 requires-python = ">=3.7"
 authors = [
   { name = "Łukasz Langa", email = "lukasz@langa.pl" },

From f16333e78ba77ab29ab0b75e10891e6c65c6da7e Mon Sep 17 00:00:00 2001
From: nn <45516943+NNRepos@users.noreply.github.com>
Date: Wed, 12 Oct 2022 00:34:37 +0300
Subject: [PATCH 0639/1034] remove unreachable code (#3328)

fixes #3321
---
 src/black/parsing.py | 2 --
 1 file changed, 2 deletions(-)

diff --git a/src/black/parsing.py b/src/black/parsing.py
index f7d9fdc2f13..762934b8869 100644
--- a/src/black/parsing.py
+++ b/src/black/parsing.py
@@ -165,8 +165,6 @@ def parse_single_version(
         # comments separately.
         return ast3.parse(src, filename, feature_version=version[1])
 
-    raise AssertionError("INTERNAL ERROR: Tried parsing unsupported Python version!")
-
 
 def parse_ast(src: str) -> Union[ast.AST, ast3.AST]:
     # TODO: support Python 4+ ;)

From 575220f460fc3a5eeb05673e9cc7d8e80b6b7147 Mon Sep 17 00:00:00 2001
From: jlplenio <ubtown@gmail.com>
Date: Sat, 15 Oct 2022 20:44:02 +0200
Subject: [PATCH 0640/1034] Clarify check argument is needed for github action
 workflow (#3325)

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 docs/integrations/github_actions.md        | 4 +++-
 docs/usage_and_configuration/the_basics.md | 2 ++
 2 files changed, 5 insertions(+), 1 deletion(-)

diff --git a/docs/integrations/github_actions.md b/docs/integrations/github_actions.md
index 12bcb21fee6..ebfcc2d95a2 100644
--- a/docs/integrations/github_actions.md
+++ b/docs/integrations/github_actions.md
@@ -44,7 +44,9 @@ extra. Installing the extra and including Jupyter Notebook files can be configur
 `jupyter` (default is `false`).
 
 You can also configure the arguments passed to _Black_ via `options` (defaults to
-`'--check --diff'`) and `src` (default is `'.'`)
+`'--check --diff'`) and `src` (default is `'.'`). Please note that the
+[`--check` flag](labels/exit-code) is required so that the workflow fails if _Black_
+finds files that need to be formatted.
 
 Here's an example configuration:
 
diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index 20aa956dd85..80897532a68 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -76,6 +76,8 @@ _Black_ to just tell you what it _would_ do without actually rewriting the Pytho
 There's two variations to this mode that are independently enabled by their respective
 flags. Both variations can be enabled at once.
 
+(labels/exit-code)=
+
 #### Exit code
 
 Passing `--check` will make _Black_ exit with:

From f22273a72b3f1c15085f2d4a43e8d785bf48c822 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 17 Oct 2022 21:12:41 -0400
Subject: [PATCH 0641/1034] Bump sphinx from 5.2.3 to 5.3.0 in /docs (#3333)

updated-dependencies:
- dependency-name: sphinx
  dependency-type: direct:production
  update-type: version-update:semver-minor

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 docs/requirements.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index 3c4b43511f6..c2342a35d7b 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,7 +1,7 @@
 # Used by ReadTheDocs; pinned requirements for stability.
 
 myst-parser==0.18.1
-Sphinx==5.2.3
+Sphinx==5.3.0
 # Older versions break Sphinx even though they're declared to be supported.
 docutils==0.19
 sphinxcontrib-programoutput==0.17

From 26de5f91c37b825214f4ee0a9096f1cd34212e76 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 24 Oct 2022 09:50:14 -0700
Subject: [PATCH 0642/1034] Bump peter-evans/find-comment from 2.0.0 to 2.0.1
 (#3353)

Bumps [peter-evans/find-comment](https://github.com/peter-evans/find-comment) from 2.0.0 to 2.0.1.
- [Release notes](https://github.com/peter-evans/find-comment/releases)
- [Commits](https://github.com/peter-evans/find-comment/compare/1769778a0c5bd330272d749d12c036d65e70d39d...b657a70ff16d17651703a84bee1cb9ad9d2be2ea)

---
updated-dependencies:
- dependency-name: peter-evans/find-comment
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/diff_shades_comment.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/diff_shades_comment.yml b/.github/workflows/diff_shades_comment.yml
index a5d213875c7..f06541b45d5 100644
--- a/.github/workflows/diff_shades_comment.yml
+++ b/.github/workflows/diff_shades_comment.yml
@@ -33,7 +33,7 @@ jobs:
       - name: Try to find pre-existing PR comment
         if: steps.metadata.outputs.needs-comment == 'true'
         id: find-comment
-        uses: peter-evans/find-comment@1769778a0c5bd330272d749d12c036d65e70d39d
+        uses: peter-evans/find-comment@b657a70ff16d17651703a84bee1cb9ad9d2be2ea
         with:
           issue-number: ${{ steps.metadata.outputs.pr-number }}
           comment-author: "github-actions[bot]"

From fbc5136aa003d806c3af177de770bd58544fe463 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 24 Oct 2022 11:40:19 -0700
Subject: [PATCH 0643/1034] Bump peter-evans/create-or-update-comment from
 2.0.0 to 2.0.1 (#3354)

Bumps [peter-evans/create-or-update-comment](https://github.com/peter-evans/create-or-update-comment) from 2.0.0 to 2.0.1.
- [Release notes](https://github.com/peter-evans/create-or-update-comment/releases)
- [Commits](https://github.com/peter-evans/create-or-update-comment/compare/c9fcb64660bc90ec1cc535646af190c992007c32...2b2c85d0bf1b8a7b4e7e344bd5c71dc4b9196e9f)

---
updated-dependencies:
- dependency-name: peter-evans/create-or-update-comment
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/diff_shades_comment.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/diff_shades_comment.yml b/.github/workflows/diff_shades_comment.yml
index f06541b45d5..9a22ec5f0c3 100644
--- a/.github/workflows/diff_shades_comment.yml
+++ b/.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@c9fcb64660bc90ec1cc535646af190c992007c32
+        uses: peter-evans/create-or-update-comment@2b2c85d0bf1b8a7b4e7e344bd5c71dc4b9196e9f
         with:
           comment-id: ${{ steps.find-comment.outputs.comment-id }}
           issue-number: ${{ steps.metadata.outputs.pr-number }}

From 4abc0399b527c50369c448e00d6e204af74026e5 Mon Sep 17 00:00:00 2001
From: "Yilei \"Dolee\" Yang" <yileiyang@google.com>
Date: Tue, 25 Oct 2022 18:03:24 -0700
Subject: [PATCH 0644/1034] Enforce empty lines before classes/functions with
 sticky leading comments. (#3302)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 CHANGES.md                                    |   2 +
 .../reference/reference_classes.rst           |  22 +-
 docs/the_black_code_style/future_style.md     |  49 +++-
 src/black/__init__.py                         |  21 +-
 src/black/lines.py                            |  86 +++++-
 src/black/mode.py                             |   1 +
 tests/data/preview/comments9.py               | 254 ++++++++++++++++++
 tests/data/preview/remove_await_parens.py     |   1 +
 tests/data/simple_cases/comments5.py          |   6 +-
 ...ocstring_no_extra_empty_line_before_eof.py |   4 +
 10 files changed, 401 insertions(+), 45 deletions(-)
 create mode 100644 tests/data/preview/comments9.py
 create mode 100644 tests/data/simple_cases/docstring_no_extra_empty_line_before_eof.py

diff --git a/CHANGES.md b/CHANGES.md
index ba9f4c06f28..67451f7caf5 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -14,6 +14,8 @@
 
 <!-- Changes that affect Black's preview style -->
 
+- Enforce empty lines before classes and functions with sticky leading comments (#3302)
+
 ### Configuration
 
 <!-- Changes to how Black can be configured -->
diff --git a/docs/contributing/reference/reference_classes.rst b/docs/contributing/reference/reference_classes.rst
index fa765961e69..3931e0e0072 100644
--- a/docs/contributing/reference/reference_classes.rst
+++ b/docs/contributing/reference/reference_classes.rst
@@ -11,23 +11,29 @@
 .. autoclass:: black.brackets.BracketTracker
     :members:
 
-:class:`EmptyLineTracker`
+:class:`Line`
+-------------
+
+.. autoclass:: black.lines.Line
+    :members:
+    :special-members: __str__, __bool__
+
+:class:`LinesBlock`
 -------------------------
 
-.. autoclass:: black.EmptyLineTracker
+.. autoclass:: black.lines.LinesBlock
     :members:
 
-:class:`Line`
--------------
+:class:`EmptyLineTracker`
+-------------------------
 
-.. autoclass:: black.Line
+.. autoclass:: black.lines.EmptyLineTracker
     :members:
-    :special-members: __str__, __bool__
 
 :class:`LineGenerator`
 ----------------------
 
-.. autoclass:: black.LineGenerator
+.. autoclass:: black.linegen.LineGenerator
     :show-inheritance:
     :members:
 
@@ -40,7 +46,7 @@
 :class:`Report`
 ---------------
 
-.. autoclass:: black.Report
+.. autoclass:: black.report.Report
     :members:
     :special-members: __str__
 
diff --git a/docs/the_black_code_style/future_style.md b/docs/the_black_code_style/future_style.md
index a028a2888ed..17b7eef092f 100644
--- a/docs/the_black_code_style/future_style.md
+++ b/docs/the_black_code_style/future_style.md
@@ -63,26 +63,47 @@ limit. Line continuation backslashes are converted into parenthesized strings.
 Unnecessary parentheses are stripped. The stability and status of this feature is
 tracked in [this issue](https://github.com/psf/black/issues/2188).
 
-### Removing newlines in the beginning of code blocks
+### Improved empty line management
 
-_Black_ will remove newlines in the beginning of new code blocks, i.e. when the
-indentation level is increased. For example:
+1.  _Black_ will remove newlines in the beginning of new code blocks, i.e. when the
+    indentation level is increased. For example:
 
-```python
-def my_func():
+    ```python
+    def my_func():
 
-    print("The line above me will be deleted!")
-```
+        print("The line above me will be deleted!")
+    ```
 
-will be changed to:
+    will be changed to:
+
+    ```python
+    def my_func():
+        print("The line above me will be deleted!")
+    ```
+
+    This new feature will be applied to **all code blocks**: `def`, `class`, `if`,
+    `for`, `while`, `with`, `case` and `match`.
+
+2.  _Black_ will enforce empty lines before classes and functions with leading comments.
+    For example:
+
+    ```python
+    some_var = 1
+    # Leading sticky comment
+    def my_func():
+        ...
+    ```
+
+    will be changed to:
+
+    ```python
+    some_var = 1
 
-```python
-def my_func():
-    print("The line above me will be deleted!")
-```
 
-This new feature will be applied to **all code blocks**: `def`, `class`, `if`, `for`,
-`while`, `with`, `case` and `match`.
+    # Leading sticky comment
+    def my_func():
+        ...
+    ```
 
 ### Improved parentheses management
 
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 5293796aea1..d9fba41ebd3 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -61,7 +61,7 @@
     unmask_cell,
 )
 from black.linegen import LN, LineGenerator, transform_line
-from black.lines import EmptyLineTracker, Line
+from black.lines import EmptyLineTracker, LinesBlock
 from black.mode import (
     FUTURE_FLAG_TO_FEATURE,
     VERSION_TO_FEATURES,
@@ -1075,7 +1075,7 @@ def f(
 
 def _format_str_once(src_contents: str, *, mode: Mode) -> str:
     src_node = lib2to3_parse(src_contents.lstrip(), mode.target_versions)
-    dst_contents = []
+    dst_blocks: List[LinesBlock] = []
     if mode.target_versions:
         versions = mode.target_versions
     else:
@@ -1084,22 +1084,25 @@ def _format_str_once(src_contents: str, *, mode: Mode) -> str:
 
     normalize_fmt_off(src_node, preview=mode.preview)
     lines = LineGenerator(mode=mode)
-    elt = EmptyLineTracker(is_pyi=mode.is_pyi)
-    empty_line = Line(mode=mode)
-    after = 0
+    elt = EmptyLineTracker(mode=mode)
     split_line_features = {
         feature
         for feature in {Feature.TRAILING_COMMA_IN_CALL, Feature.TRAILING_COMMA_IN_DEF}
         if supports_feature(versions, feature)
     }
+    block: Optional[LinesBlock] = None
     for current_line in lines.visit(src_node):
-        dst_contents.append(str(empty_line) * after)
-        before, after = elt.maybe_empty_lines(current_line)
-        dst_contents.append(str(empty_line) * before)
+        block = elt.maybe_empty_lines(current_line)
+        dst_blocks.append(block)
         for line in transform_line(
             current_line, mode=mode, features=split_line_features
         ):
-            dst_contents.append(str(line))
+            block.content_lines.append(str(line))
+    if dst_blocks:
+        dst_blocks[-1].after = 0
+    dst_contents = []
+    for block in dst_blocks:
+        dst_contents.extend(block.all_lines())
     return "".join(dst_contents)
 
 
diff --git a/src/black/lines.py b/src/black/lines.py
index 30622650d53..0d074534def 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -448,6 +448,28 @@ def __bool__(self) -> bool:
         return bool(self.leaves or self.comments)
 
 
+@dataclass
+class LinesBlock:
+    """Class that holds information about a block of formatted lines.
+
+    This is introduced so that the EmptyLineTracker can look behind the standalone
+    comments and adjust their empty lines for class or def lines.
+    """
+
+    mode: Mode
+    previous_block: Optional["LinesBlock"]
+    original_line: Line
+    before: int = 0
+    content_lines: List[str] = field(default_factory=list)
+    after: int = 0
+
+    def all_lines(self) -> List[str]:
+        empty_line = str(Line(mode=self.mode))
+        return (
+            [empty_line * self.before] + self.content_lines + [empty_line * self.after]
+        )
+
+
 @dataclass
 class EmptyLineTracker:
     """Provides a stateful method that returns the number of potential extra
@@ -458,33 +480,55 @@ class EmptyLineTracker:
     are consumed by `maybe_empty_lines()` and included in the computation.
     """
 
-    is_pyi: bool = False
+    mode: Mode
     previous_line: Optional[Line] = None
-    previous_after: int = 0
+    previous_block: Optional[LinesBlock] = None
     previous_defs: List[int] = field(default_factory=list)
+    semantic_leading_comment: Optional[LinesBlock] = None
 
-    def maybe_empty_lines(self, current_line: Line) -> Tuple[int, int]:
+    def maybe_empty_lines(self, current_line: Line) -> LinesBlock:
         """Return the number of extra empty lines before and after the `current_line`.
 
         This is for separating `def`, `async def` and `class` with extra empty
         lines (two on module-level).
         """
         before, after = self._maybe_empty_lines(current_line)
+        previous_after = self.previous_block.after if self.previous_block else 0
         before = (
             # Black should not insert empty lines at the beginning
             # of the file
             0
             if self.previous_line is None
-            else before - self.previous_after
+            else before - previous_after
         )
-        self.previous_after = after
+        block = LinesBlock(
+            mode=self.mode,
+            previous_block=self.previous_block,
+            original_line=current_line,
+            before=before,
+            after=after,
+        )
+
+        # Maintain the semantic_leading_comment state.
+        if current_line.is_comment:
+            if self.previous_line is None or (
+                not self.previous_line.is_decorator
+                # `or before` means this comment already has an empty line before
+                and (not self.previous_line.is_comment or before)
+                and (self.semantic_leading_comment is None or before)
+            ):
+                self.semantic_leading_comment = block
+        elif not current_line.is_decorator:
+            self.semantic_leading_comment = None
+
         self.previous_line = current_line
-        return before, after
+        self.previous_block = block
+        return block
 
     def _maybe_empty_lines(self, current_line: Line) -> Tuple[int, int]:
         max_allowed = 1
         if current_line.depth == 0:
-            max_allowed = 1 if self.is_pyi else 2
+            max_allowed = 1 if self.mode.is_pyi else 2
         if current_line.leaves:
             # Consume the first leaf's extra newlines.
             first_leaf = current_line.leaves[0]
@@ -495,7 +539,7 @@ def _maybe_empty_lines(self, current_line: Line) -> Tuple[int, int]:
             before = 0
         depth = current_line.depth
         while self.previous_defs and self.previous_defs[-1] >= depth:
-            if self.is_pyi:
+            if self.mode.is_pyi:
                 assert self.previous_line is not None
                 if depth and not current_line.is_def and self.previous_line.is_def:
                     # Empty lines between attributes and methods should be preserved.
@@ -563,7 +607,7 @@ def _maybe_empty_lines_for_class_or_def(
             return 0, 0
 
         if self.previous_line.is_decorator:
-            if self.is_pyi and current_line.is_stub_class:
+            if self.mode.is_pyi and current_line.is_stub_class:
                 # Insert an empty line after a decorated stub class
                 return 0, 1
 
@@ -574,14 +618,27 @@ def _maybe_empty_lines_for_class_or_def(
         ):
             return 0, 0
 
+        comment_to_add_newlines: Optional[LinesBlock] = None
         if (
             self.previous_line.is_comment
             and self.previous_line.depth == current_line.depth
             and before == 0
         ):
-            return 0, 0
+            slc = self.semantic_leading_comment
+            if (
+                Preview.empty_lines_before_class_or_def_with_leading_comments
+                in current_line.mode
+                and slc is not None
+                and slc.previous_block is not None
+                and not slc.previous_block.original_line.is_class
+                and not slc.previous_block.original_line.opens_block
+                and slc.before <= 1
+            ):
+                comment_to_add_newlines = slc
+            else:
+                return 0, 0
 
-        if self.is_pyi:
+        if self.mode.is_pyi:
             if current_line.is_class or self.previous_line.is_class:
                 if self.previous_line.depth < current_line.depth:
                     newlines = 0
@@ -609,6 +666,13 @@ def _maybe_empty_lines_for_class_or_def(
                 newlines = 0
         else:
             newlines = 1 if current_line.depth else 2
+        if comment_to_add_newlines is not None:
+            previous_block = comment_to_add_newlines.previous_block
+            if previous_block is not None:
+                comment_to_add_newlines.before = (
+                    max(comment_to_add_newlines.before, newlines) - previous_block.after
+                )
+                newlines = 0
         return newlines, 0
 
 
diff --git a/src/black/mode.py b/src/black/mode.py
index e3c36450ed1..1e83f2a9c6d 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -150,6 +150,7 @@ class Preview(Enum):
     """Individual preview style features."""
 
     annotation_parens = auto()
+    empty_lines_before_class_or_def_with_leading_comments = auto()
     long_docstring_quotes_on_newline = auto()
     normalize_docstring_quotes_and_prefixes_properly = auto()
     one_element_subscript = auto()
diff --git a/tests/data/preview/comments9.py b/tests/data/preview/comments9.py
new file mode 100644
index 00000000000..449612c037a
--- /dev/null
+++ b/tests/data/preview/comments9.py
@@ -0,0 +1,254 @@
+# Test for https://github.com/psf/black/issues/246.
+
+some = statement
+# This comment should be split from the statement above by two lines.
+def function():
+    pass
+
+
+some = statement
+# This multiline comments section
+# should be split from the statement
+# above by two lines.
+def function():
+    pass
+
+
+some = statement
+# This comment should be split from the statement above by two lines.
+async def async_function():
+    pass
+
+
+some = statement
+# This comment should be split from the statement above by two lines.
+class MyClass:
+    pass
+
+
+some = statement
+# This should be stick to the statement above
+
+# This should be split from the above by two lines
+class MyClassWithComplexLeadingComments:
+    pass
+
+
+class ClassWithDocstring:
+    """A docstring."""
+# Leading comment after a class with just a docstring
+class MyClassAfterAnotherClassWithDocstring:
+    pass
+
+
+some = statement
+# leading 1
+@deco1
+# leading 2
+# leading 2 extra
+@deco2(with_args=True)
+# leading 3
+@deco3
+# leading 4
+def decorated():
+    pass
+
+
+some = statement
+# leading 1
+@deco1
+# leading 2
+@deco2(with_args=True)
+
+# leading 3 that already has an empty line
+@deco3
+# leading 4
+def decorated_with_split_leading_comments():
+    pass
+
+
+some = statement
+# leading 1
+@deco1
+# leading 2
+@deco2(with_args=True)
+# leading 3
+@deco3
+
+# leading 4 that already has an empty line
+def decorated_with_split_leading_comments():
+    pass
+
+
+def main():
+    if a:
+        # Leading comment before inline function
+        def inline():
+            pass
+        # Another leading comment
+        def another_inline():
+            pass
+    else:
+        # More leading comments
+        def inline_after_else():
+            pass
+
+
+if a:
+    # Leading comment before "top-level inline" function
+    def top_level_quote_inline():
+        pass
+    # Another leading comment
+    def another_top_level_quote_inline_inline():
+        pass
+else:
+    # More leading comments
+    def top_level_quote_inline_after_else():
+        pass
+
+
+class MyClass:
+    # First method has no empty lines between bare class def.
+    # More comments.
+    def first_method(self):
+        pass
+
+
+# output
+
+
+# Test for https://github.com/psf/black/issues/246.
+
+some = statement
+
+
+# This comment should be split from the statement above by two lines.
+def function():
+    pass
+
+
+some = statement
+
+
+# This multiline comments section
+# should be split from the statement
+# above by two lines.
+def function():
+    pass
+
+
+some = statement
+
+
+# This comment should be split from the statement above by two lines.
+async def async_function():
+    pass
+
+
+some = statement
+
+
+# This comment should be split from the statement above by two lines.
+class MyClass:
+    pass
+
+
+some = statement
+# This should be stick to the statement above
+
+
+# This should be split from the above by two lines
+class MyClassWithComplexLeadingComments:
+    pass
+
+
+class ClassWithDocstring:
+    """A docstring."""
+
+
+# Leading comment after a class with just a docstring
+class MyClassAfterAnotherClassWithDocstring:
+    pass
+
+
+some = statement
+
+
+# leading 1
+@deco1
+# leading 2
+# leading 2 extra
+@deco2(with_args=True)
+# leading 3
+@deco3
+# leading 4
+def decorated():
+    pass
+
+
+some = statement
+
+
+# leading 1
+@deco1
+# leading 2
+@deco2(with_args=True)
+
+# leading 3 that already has an empty line
+@deco3
+# leading 4
+def decorated_with_split_leading_comments():
+    pass
+
+
+some = statement
+
+
+# leading 1
+@deco1
+# leading 2
+@deco2(with_args=True)
+# leading 3
+@deco3
+
+# leading 4 that already has an empty line
+def decorated_with_split_leading_comments():
+    pass
+
+
+def main():
+    if a:
+        # Leading comment before inline function
+        def inline():
+            pass
+
+        # Another leading comment
+        def another_inline():
+            pass
+
+    else:
+        # More leading comments
+        def inline_after_else():
+            pass
+
+
+if a:
+    # Leading comment before "top-level inline" function
+    def top_level_quote_inline():
+        pass
+
+    # Another leading comment
+    def another_top_level_quote_inline_inline():
+        pass
+
+else:
+    # More leading comments
+    def top_level_quote_inline_after_else():
+        pass
+
+
+class MyClass:
+    # First method has no empty lines between bare class def.
+    # More comments.
+    def first_method(self):
+        pass
diff --git a/tests/data/preview/remove_await_parens.py b/tests/data/preview/remove_await_parens.py
index eb7dad340c3..571210a2d80 100644
--- a/tests/data/preview/remove_await_parens.py
+++ b/tests/data/preview/remove_await_parens.py
@@ -80,6 +80,7 @@ async def main():
 # output
 import asyncio
 
+
 # Control example
 async def main():
     await asyncio.sleep(1)
diff --git a/tests/data/simple_cases/comments5.py b/tests/data/simple_cases/comments5.py
index d83b6b8ff47..c8c38813d55 100644
--- a/tests/data/simple_cases/comments5.py
+++ b/tests/data/simple_cases/comments5.py
@@ -58,9 +58,9 @@ def decorated1():
     ...
 
 
-# Note: crappy but inevitable.  The current design of EmptyLineTracker doesn't
-# allow this to work correctly.  The user will have to split those lines by
-# hand.
+# Note: this is fixed in
+# Preview.empty_lines_before_class_or_def_with_leading_comments.
+# In the current style, the user will have to split those lines by hand.
 some_instruction
 # This comment should be split from `some_instruction` by two lines but isn't.
 def g():
diff --git a/tests/data/simple_cases/docstring_no_extra_empty_line_before_eof.py b/tests/data/simple_cases/docstring_no_extra_empty_line_before_eof.py
new file mode 100644
index 00000000000..6fea860adf6
--- /dev/null
+++ b/tests/data/simple_cases/docstring_no_extra_empty_line_before_eof.py
@@ -0,0 +1,4 @@
+# Make sure when the file ends with class's docstring,
+# It doesn't add extra blank lines.
+class ClassWithDocstring:
+    """A docstring."""

From 527248b3893ea117963ffa74859bb303c0f4c4ba Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Tue, 25 Oct 2022 19:03:24 -0700
Subject: [PATCH 0645/1034] Exclude pytest-xdist 3.0.2 (#3356)

We're getting warnings like https://github.com/psf/black/actions/runs/3325521041/jobs/5498291478 and I'm not sure how to fix them. I'll open an issue for a long-term solution, but for now avoid 3.0.2 to unbreak CI.
---
 test_requirements.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/test_requirements.txt b/test_requirements.txt
index 5bc494d5999..ef61a1210ee 100644
--- a/test_requirements.txt
+++ b/test_requirements.txt
@@ -1,6 +1,6 @@
 coverage >= 5.3
 pre-commit
 pytest >= 6.1.1
-pytest-xdist >= 2.2.1
+pytest-xdist >= 2.2.1, < 3.0.2
 pytest-cov >= 2.11.1
 tox

From 09d4acdcb79e473276a50c5e5be9dc46fa2634d9 Mon Sep 17 00:00:00 2001
From: Ned Western <ned.western@gmail.com>
Date: Wed, 26 Oct 2022 13:04:31 +1100
Subject: [PATCH 0646/1034] Update README.md (#3284)

Minor typo
---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index b2593024676..6b72a9b9a23 100644
--- a/README.md
+++ b/README.md
@@ -66,7 +66,7 @@ Further information can be found in our docs:
 _Black_ is already [successfully used](https://github.com/psf/black#used-by) by many
 projects, small and big. _Black_ has a comprehensive test suite, with efficient parallel
 tests, and our own auto formatting and parallel Continuous Integration runner. Now that
-we have become stable, you should not expect large formatting to changes in the future.
+we have become stable, you should not expect large formatting changes in the future.
 Stylistic changes will mostly be responses to bug reports and support for new Python
 syntax. For more information please refer to the
 [The Black Code Style](https://black.readthedocs.io/en/stable/the_black_code_style/index.html).

From b73b77a9b039d5afa6ab32202bff2b2232258d45 Mon Sep 17 00:00:00 2001
From: "Yilei \"Dolee\" Yang" <yileiyang@google.com>
Date: Wed, 26 Oct 2022 18:03:10 -0700
Subject: [PATCH 0647/1034] Wrap concatenated strings used as function args in
 parens (#3307)

Fixes #3292
---
 CHANGES.md                                    |   2 +
 src/black/__init__.py                         |   6 +-
 src/black/mode.py                             |   6 +-
 src/black/parsing.py                          |   8 +-
 src/black/trans.py                            |  43 ++----
 tests/data/preview/cantfit.py                 |  12 +-
 tests/data/preview/long_strings.py            |  54 +++++---
 .../data/preview/long_strings__regression.py  |  22 +--
 tests/test_black.py                           | 126 ++++++++++++------
 9 files changed, 169 insertions(+), 110 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 67451f7caf5..4db961149bf 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -15,6 +15,8 @@
 <!-- Changes that affect Black's preview style -->
 
 - Enforce empty lines before classes and functions with sticky leading comments (#3302)
+- Implicitly concatenated strings used as function args are now wrapped inside
+  parentheses (#3307)
 
 ### Configuration
 
diff --git a/src/black/__init__.py b/src/black/__init__.py
index d9fba41ebd3..94592278c31 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -497,8 +497,10 @@ def main(  # noqa: C901
             user_level_config = str(find_user_pyproject_toml())
             if config == user_level_config:
                 out(
-                    "Using configuration from user-level config at "
-                    f"'{user_level_config}'.",
+                    (
+                        "Using configuration from user-level config at "
+                        f"'{user_level_config}'."
+                    ),
                     fg="blue",
                 )
             elif config_source in (
diff --git a/src/black/mode.py b/src/black/mode.py
index 1e83f2a9c6d..e2eff2391b1 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -180,8 +180,10 @@ class Mode:
     def __post_init__(self) -> None:
         if self.experimental_string_processing:
             warn(
-                "`experimental string processing` has been included in `preview`"
-                " and deprecated. Use `preview` instead.",
+                (
+                    "`experimental string processing` has been included in `preview`"
+                    " and deprecated. Use `preview` instead."
+                ),
                 Deprecated,
             )
 
diff --git a/src/black/parsing.py b/src/black/parsing.py
index 762934b8869..c37c12b868d 100644
--- a/src/black/parsing.py
+++ b/src/black/parsing.py
@@ -29,9 +29,11 @@
 except ImportError:
     if sys.version_info < (3, 8) and not _IS_PYPY:
         print(
-            "The typed_ast package is required but not installed.\n"
-            "You can upgrade to Python 3.8+ or install typed_ast with\n"
-            "`python3 -m pip install typed-ast`.",
+            (
+                "The typed_ast package is required but not installed.\n"
+                "You can upgrade to Python 3.8+ or install typed_ast with\n"
+                "`python3 -m pip install typed-ast`."
+            ),
             file=sys.stderr,
         )
         sys.exit(1)
diff --git a/src/black/trans.py b/src/black/trans.py
index 7e2d8e67c1a..8893ab02aab 100644
--- a/src/black/trans.py
+++ b/src/black/trans.py
@@ -1058,33 +1058,19 @@ def _prefer_paren_wrap_match(LL: List[Leaf]) -> Optional[int]:
         if LL[0].type != token.STRING:
             return None
 
-        matching_nodes = [
-            syms.listmaker,
-            syms.dictsetmaker,
-            syms.testlist_gexp,
-        ]
-        # If the string is an immediate child of a list/set/tuple literal...
-        if (
-            parent_type(LL[0]) in matching_nodes
-            or parent_type(LL[0].parent) in matching_nodes
+        # If the string is surrounded by commas (or is the first/last child)...
+        prev_sibling = LL[0].prev_sibling
+        next_sibling = LL[0].next_sibling
+        if not prev_sibling and not next_sibling and parent_type(LL[0]) == syms.atom:
+            # If it's an atom string, we need to check the parent atom's siblings.
+            parent = LL[0].parent
+            assert parent is not None  # For type checkers.
+            prev_sibling = parent.prev_sibling
+            next_sibling = parent.next_sibling
+        if (not prev_sibling or prev_sibling.type == token.COMMA) and (
+            not next_sibling or next_sibling.type == token.COMMA
         ):
-            # And the string is surrounded by commas (or is the first/last child)...
-            prev_sibling = LL[0].prev_sibling
-            next_sibling = LL[0].next_sibling
-            if (
-                not prev_sibling
-                and not next_sibling
-                and parent_type(LL[0]) == syms.atom
-            ):
-                # If it's an atom string, we need to check the parent atom's siblings.
-                parent = LL[0].parent
-                assert parent is not None  # For type checkers.
-                prev_sibling = parent.prev_sibling
-                next_sibling = parent.next_sibling
-            if (not prev_sibling or prev_sibling.type == token.COMMA) and (
-                not next_sibling or next_sibling.type == token.COMMA
-            ):
-                return 0
+            return 0
 
         return None
 
@@ -1653,9 +1639,8 @@ class StringParenWrapper(BaseStringSplitter, CustomSplitMapMixin):
         assigned the value of some string.
             OR
         * The line starts with an "atom" string that prefers to be wrapped in
-        parens. It's preferred to be wrapped when it's is an immediate child of
-        a list/set/tuple literal, AND the string is surrounded by commas (or is
-        the first/last child).
+        parens. It's preferred to be wrapped when the string is surrounded by
+        commas (or is the first/last child).
 
     Transformations:
         The chosen string is wrapped in parentheses and then split at the LPAR.
diff --git a/tests/data/preview/cantfit.py b/tests/data/preview/cantfit.py
index 0849374f776..cade382e30d 100644
--- a/tests/data/preview/cantfit.py
+++ b/tests/data/preview/cantfit.py
@@ -79,10 +79,14 @@
 )
 # long arguments
 normal_name = normal_function_name(
-    "but with super long string arguments that on their own exceed the line limit so"
-    " there's no way it can ever fit",
-    "eggs with spam and eggs and spam with eggs with spam and eggs and spam with eggs"
-    " with spam and eggs and spam with eggs",
+    (
+        "but with super long string arguments that on their own exceed the line limit"
+        " so there's no way it can ever fit"
+    ),
+    (
+        "eggs with spam and eggs and spam with eggs with spam and eggs and spam with"
+        " eggs with spam and eggs and spam with eggs"
+    ),
     this_is_a_ridiculously_long_name_and_nobody_in_their_right_mind_would_use_one_like_it=0,
 )
 string_variable_name = "a string that is waaaaaaaayyyyyyyy too long, even in parens, there's nothing you can do"  # noqa
diff --git a/tests/data/preview/long_strings.py b/tests/data/preview/long_strings.py
index 6db3cfed9a9..9288b253b60 100644
--- a/tests/data/preview/long_strings.py
+++ b/tests/data/preview/long_strings.py
@@ -297,8 +297,10 @@ def foo():
 y = "Short string"
 
 print(
-    "This is a really long string inside of a print statement with extra arguments"
-    " attached at the end of it.",
+    (
+        "This is a really long string inside of a print statement with extra arguments"
+        " attached at the end of it."
+    ),
     x,
     y,
     z,
@@ -474,13 +476,15 @@ def foo():
 )
 
 bad_split_func1(
-    "But what should happen when code has already "
-    "been formatted but in the wrong way? Like "
-    "with a space at the end instead of the "
-    "beginning. Or what about when it is split too "
-    "soon? In the case of a split that is too "
-    "short, black will try to honer the custom "
-    "split.",
+    (
+        "But what should happen when code has already "
+        "been formatted but in the wrong way? Like "
+        "with a space at the end instead of the "
+        "beginning. Or what about when it is split too "
+        "soon? In the case of a split that is too "
+        "short, black will try to honer the custom "
+        "split."
+    ),
     xxx,
     yyy,
     zzz,
@@ -583,9 +587,11 @@ def foo():
 )
 
 arg_comment_string = print(
-    "Long lines with inline comments which are apart of (and not the only member of) an"
-    " argument list should have their comments appended to the reformatted string's"
-    " enclosing left parentheses.",  # This comment gets thrown to the top.
+    (  # This comment gets thrown to the top.
+        "Long lines with inline comments which are apart of (and not the only member"
+        " of) an argument list should have their comments appended to the reformatted"
+        " string's enclosing left parentheses."
+    ),
     "Arg #2",
     "Arg #3",
     "Arg #4",
@@ -645,23 +651,31 @@ def foo():
 )
 
 func_with_bad_comma(
-    "This is a really long string argument to a function that has a trailing comma"
-    " which should NOT be there.",
+    (
+        "This is a really long string argument to a function that has a trailing comma"
+        " which should NOT be there."
+    ),
 )
 
 func_with_bad_comma(
-    "This is a really long string argument to a function that has a trailing comma"
-    " which should NOT be there.",  # comment after comma
+    (  # comment after comma
+        "This is a really long string argument to a function that has a trailing comma"
+        " which should NOT be there."
+    ),
 )
 
 func_with_bad_comma(
-    "This is a really long string argument to a function that has a trailing comma"
-    " which should NOT be there.",
+    (
+        "This is a really long string argument to a function that has a trailing comma"
+        " which should NOT be there."
+    ),
 )
 
 func_with_bad_comma(
-    "This is a really long string argument to a function that has a trailing comma"
-    " which should NOT be there.",  # comment after comma
+    (  # comment after comma
+        "This is a really long string argument to a function that has a trailing comma"
+        " which should NOT be there."
+    ),
 )
 
 func_with_bad_parens_that_wont_fit_in_one_line(
diff --git a/tests/data/preview/long_strings__regression.py b/tests/data/preview/long_strings__regression.py
index 634db46a5e0..8b00e76f40e 100644
--- a/tests/data/preview/long_strings__regression.py
+++ b/tests/data/preview/long_strings__regression.py
@@ -679,9 +679,11 @@ class A:
     def foo():
         some_func_call(
             "xxxxxxxxxx",
-            "xx {xxxxxxxxxxx}/xxxxxxxxxxx.xxx xxxx.xxx && xxxxxx -x "
-            '"xxxx xxxxxxx xxxxxx xxxx; xxxx xxxxxx_xxxxx xxxxxx xxxx; '
-            "xxxx.xxxx_xxxxxx(['xxxx.xxx'], xxxx.xxxxxxx().xxxxxxxxxx)\" ",
+            (
+                "xx {xxxxxxxxxxx}/xxxxxxxxxxx.xxx xxxx.xxx && xxxxxx -x "
+                '"xxxx xxxxxxx xxxxxx xxxx; xxxx xxxxxx_xxxxx xxxxxx xxxx; '
+                "xxxx.xxxx_xxxxxx(['xxxx.xxx'], xxxx.xxxxxxx().xxxxxxxxxx)\" "
+            ),
             None,
             ("xxxxxxxxxxx",),
         ),
@@ -690,9 +692,11 @@ def foo():
 class A:
     def foo():
         some_func_call(
-            "xx {xxxxxxxxxxx}/xxxxxxxxxxx.xxx xxxx.xxx && xxxxxx -x "
-            "xxxx, ('xxxxxxx xxxxxx xxxx, xxxx') xxxxxx_xxxxx xxxxxx xxxx; "
-            "xxxx.xxxx_xxxxxx(['xxxx.xxx'], xxxx.xxxxxxx().xxxxxxxxxx)\" ",
+            (
+                "xx {xxxxxxxxxxx}/xxxxxxxxxxx.xxx xxxx.xxx && xxxxxx -x "
+                "xxxx, ('xxxxxxx xxxxxx xxxx, xxxx') xxxxxx_xxxxx xxxxxx xxxx; "
+                "xxxx.xxxx_xxxxxx(['xxxx.xxx'], xxxx.xxxxxxx().xxxxxxxxxx)\" "
+            ),
             None,
             ("xxxxxxxxxxx",),
         ),
@@ -810,8 +814,10 @@ def foo():
 )
 
 lpar_and_rpar_have_comments = func_call(  # LPAR Comment
-    "Long really ridiculous type of string that shouldn't really even exist at all. I"
-    " mean commmme onnn!!!",  # Comma Comment
+    (  # Comma Comment
+        "Long really ridiculous type of string that shouldn't really even exist at all."
+        " I mean commmme onnn!!!"
+    ),
 )  # RPAR Comment
 
 cmd_fstring = (
diff --git a/tests/test_black.py b/tests/test_black.py
index 5d0175d9d66..9256698ea27 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -490,8 +490,10 @@ def err(msg: str, **kwargs: Any) -> None:
             self.assertEqual(err_lines[-1], "error: cannot format e1: boom")
             self.assertEqual(
                 unstyle(str(report)),
-                "1 file reformatted, 2 files left unchanged, 1 file failed to"
-                " reformat.",
+                (
+                    "1 file reformatted, 2 files left unchanged, 1 file failed to"
+                    " reformat."
+                ),
             )
             self.assertEqual(report.return_code, 123)
             report.done(Path("f3"), black.Changed.YES)
@@ -500,8 +502,10 @@ def err(msg: str, **kwargs: Any) -> None:
             self.assertEqual(out_lines[-1], "reformatted f3")
             self.assertEqual(
                 unstyle(str(report)),
-                "2 files reformatted, 2 files left unchanged, 1 file failed to"
-                " reformat.",
+                (
+                    "2 files reformatted, 2 files left unchanged, 1 file failed to"
+                    " reformat."
+                ),
             )
             self.assertEqual(report.return_code, 123)
             report.failed(Path("e2"), "boom")
@@ -510,8 +514,10 @@ def err(msg: str, **kwargs: Any) -> None:
             self.assertEqual(err_lines[-1], "error: cannot format e2: boom")
             self.assertEqual(
                 unstyle(str(report)),
-                "2 files reformatted, 2 files left unchanged, 2 files failed to"
-                " reformat.",
+                (
+                    "2 files reformatted, 2 files left unchanged, 2 files failed to"
+                    " reformat."
+                ),
             )
             self.assertEqual(report.return_code, 123)
             report.path_ignored(Path("wat"), "no match")
@@ -520,8 +526,10 @@ def err(msg: str, **kwargs: Any) -> None:
             self.assertEqual(out_lines[-1], "wat ignored: no match")
             self.assertEqual(
                 unstyle(str(report)),
-                "2 files reformatted, 2 files left unchanged, 2 files failed to"
-                " reformat.",
+                (
+                    "2 files reformatted, 2 files left unchanged, 2 files failed to"
+                    " reformat."
+                ),
             )
             self.assertEqual(report.return_code, 123)
             report.done(Path("f4"), black.Changed.NO)
@@ -530,22 +538,28 @@ def err(msg: str, **kwargs: Any) -> None:
             self.assertEqual(out_lines[-1], "f4 already well formatted, good job.")
             self.assertEqual(
                 unstyle(str(report)),
-                "2 files reformatted, 3 files left unchanged, 2 files failed to"
-                " reformat.",
+                (
+                    "2 files reformatted, 3 files left unchanged, 2 files failed to"
+                    " reformat."
+                ),
             )
             self.assertEqual(report.return_code, 123)
             report.check = True
             self.assertEqual(
                 unstyle(str(report)),
-                "2 files would be reformatted, 3 files would be left unchanged, 2"
-                " files would fail to reformat.",
+                (
+                    "2 files would be reformatted, 3 files would be left unchanged, 2"
+                    " files would fail to reformat."
+                ),
             )
             report.check = False
             report.diff = True
             self.assertEqual(
                 unstyle(str(report)),
-                "2 files would be reformatted, 3 files would be left unchanged, 2"
-                " files would fail to reformat.",
+                (
+                    "2 files would be reformatted, 3 files would be left unchanged, 2"
+                    " files would fail to reformat."
+                ),
             )
 
     def test_report_quiet(self) -> None:
@@ -587,8 +601,10 @@ def err(msg: str, **kwargs: Any) -> None:
             self.assertEqual(err_lines[-1], "error: cannot format e1: boom")
             self.assertEqual(
                 unstyle(str(report)),
-                "1 file reformatted, 2 files left unchanged, 1 file failed to"
-                " reformat.",
+                (
+                    "1 file reformatted, 2 files left unchanged, 1 file failed to"
+                    " reformat."
+                ),
             )
             self.assertEqual(report.return_code, 123)
             report.done(Path("f3"), black.Changed.YES)
@@ -596,8 +612,10 @@ def err(msg: str, **kwargs: Any) -> None:
             self.assertEqual(len(err_lines), 1)
             self.assertEqual(
                 unstyle(str(report)),
-                "2 files reformatted, 2 files left unchanged, 1 file failed to"
-                " reformat.",
+                (
+                    "2 files reformatted, 2 files left unchanged, 1 file failed to"
+                    " reformat."
+                ),
             )
             self.assertEqual(report.return_code, 123)
             report.failed(Path("e2"), "boom")
@@ -606,8 +624,10 @@ def err(msg: str, **kwargs: Any) -> None:
             self.assertEqual(err_lines[-1], "error: cannot format e2: boom")
             self.assertEqual(
                 unstyle(str(report)),
-                "2 files reformatted, 2 files left unchanged, 2 files failed to"
-                " reformat.",
+                (
+                    "2 files reformatted, 2 files left unchanged, 2 files failed to"
+                    " reformat."
+                ),
             )
             self.assertEqual(report.return_code, 123)
             report.path_ignored(Path("wat"), "no match")
@@ -615,8 +635,10 @@ def err(msg: str, **kwargs: Any) -> None:
             self.assertEqual(len(err_lines), 2)
             self.assertEqual(
                 unstyle(str(report)),
-                "2 files reformatted, 2 files left unchanged, 2 files failed to"
-                " reformat.",
+                (
+                    "2 files reformatted, 2 files left unchanged, 2 files failed to"
+                    " reformat."
+                ),
             )
             self.assertEqual(report.return_code, 123)
             report.done(Path("f4"), black.Changed.NO)
@@ -624,22 +646,28 @@ def err(msg: str, **kwargs: Any) -> None:
             self.assertEqual(len(err_lines), 2)
             self.assertEqual(
                 unstyle(str(report)),
-                "2 files reformatted, 3 files left unchanged, 2 files failed to"
-                " reformat.",
+                (
+                    "2 files reformatted, 3 files left unchanged, 2 files failed to"
+                    " reformat."
+                ),
             )
             self.assertEqual(report.return_code, 123)
             report.check = True
             self.assertEqual(
                 unstyle(str(report)),
-                "2 files would be reformatted, 3 files would be left unchanged, 2"
-                " files would fail to reformat.",
+                (
+                    "2 files would be reformatted, 3 files would be left unchanged, 2"
+                    " files would fail to reformat."
+                ),
             )
             report.check = False
             report.diff = True
             self.assertEqual(
                 unstyle(str(report)),
-                "2 files would be reformatted, 3 files would be left unchanged, 2"
-                " files would fail to reformat.",
+                (
+                    "2 files would be reformatted, 3 files would be left unchanged, 2"
+                    " files would fail to reformat."
+                ),
             )
 
     def test_report_normal(self) -> None:
@@ -683,8 +711,10 @@ def err(msg: str, **kwargs: Any) -> None:
             self.assertEqual(err_lines[-1], "error: cannot format e1: boom")
             self.assertEqual(
                 unstyle(str(report)),
-                "1 file reformatted, 2 files left unchanged, 1 file failed to"
-                " reformat.",
+                (
+                    "1 file reformatted, 2 files left unchanged, 1 file failed to"
+                    " reformat."
+                ),
             )
             self.assertEqual(report.return_code, 123)
             report.done(Path("f3"), black.Changed.YES)
@@ -693,8 +723,10 @@ def err(msg: str, **kwargs: Any) -> None:
             self.assertEqual(out_lines[-1], "reformatted f3")
             self.assertEqual(
                 unstyle(str(report)),
-                "2 files reformatted, 2 files left unchanged, 1 file failed to"
-                " reformat.",
+                (
+                    "2 files reformatted, 2 files left unchanged, 1 file failed to"
+                    " reformat."
+                ),
             )
             self.assertEqual(report.return_code, 123)
             report.failed(Path("e2"), "boom")
@@ -703,8 +735,10 @@ def err(msg: str, **kwargs: Any) -> None:
             self.assertEqual(err_lines[-1], "error: cannot format e2: boom")
             self.assertEqual(
                 unstyle(str(report)),
-                "2 files reformatted, 2 files left unchanged, 2 files failed to"
-                " reformat.",
+                (
+                    "2 files reformatted, 2 files left unchanged, 2 files failed to"
+                    " reformat."
+                ),
             )
             self.assertEqual(report.return_code, 123)
             report.path_ignored(Path("wat"), "no match")
@@ -712,8 +746,10 @@ def err(msg: str, **kwargs: Any) -> None:
             self.assertEqual(len(err_lines), 2)
             self.assertEqual(
                 unstyle(str(report)),
-                "2 files reformatted, 2 files left unchanged, 2 files failed to"
-                " reformat.",
+                (
+                    "2 files reformatted, 2 files left unchanged, 2 files failed to"
+                    " reformat."
+                ),
             )
             self.assertEqual(report.return_code, 123)
             report.done(Path("f4"), black.Changed.NO)
@@ -721,22 +757,28 @@ def err(msg: str, **kwargs: Any) -> None:
             self.assertEqual(len(err_lines), 2)
             self.assertEqual(
                 unstyle(str(report)),
-                "2 files reformatted, 3 files left unchanged, 2 files failed to"
-                " reformat.",
+                (
+                    "2 files reformatted, 3 files left unchanged, 2 files failed to"
+                    " reformat."
+                ),
             )
             self.assertEqual(report.return_code, 123)
             report.check = True
             self.assertEqual(
                 unstyle(str(report)),
-                "2 files would be reformatted, 3 files would be left unchanged, 2"
-                " files would fail to reformat.",
+                (
+                    "2 files would be reformatted, 3 files would be left unchanged, 2"
+                    " files would fail to reformat."
+                ),
             )
             report.check = False
             report.diff = True
             self.assertEqual(
                 unstyle(str(report)),
-                "2 files would be reformatted, 3 files would be left unchanged, 2"
-                " files would fail to reformat.",
+                (
+                    "2 files would be reformatted, 3 files would be left unchanged, 2"
+                    " files would fail to reformat."
+                ),
             )
 
     def test_lib2to3_parse(self) -> None:

From d338de7f687e90e292d949d2acd301f59fe5cdf8 Mon Sep 17 00:00:00 2001
From: Hongbo Miao <Hongbo.Miao@outlook.com>
Date: Thu, 27 Oct 2022 14:22:44 -0700
Subject: [PATCH 0648/1034] Add Archer Aviation to organizations in readme
 (#3361)

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 6b72a9b9a23..c2dd9e6b17d 100644
--- a/README.md
+++ b/README.md
@@ -138,7 +138,7 @@ pandas, Pillow, Twisted, LocalStack, every Datadog Agent Integration, Home Assis
 Zulip, Kedro, OpenOA, FLORIS, ORBIT, WOMBAT, and many more.
 
 The following organizations use _Black_: Facebook, Dropbox, KeepTruckin, Mozilla, Quora,
-Duolingo, QuantumBlack, Tesla.
+Duolingo, QuantumBlack, Tesla, Archer Aviation.
 
 Are we missing anyone? Let us know.
 

From 4bb6e4f64ab3820ab9fae6716cd59479d34b7edf Mon Sep 17 00:00:00 2001
From: Corey Hickey <bugfood-c@fatooh.org>
Date: Thu, 27 Oct 2022 16:55:33 -0700
Subject: [PATCH 0649/1034] Vim plugin: allow using system black rather than
 virtualenv (#3309)

Provide a configuration parameter to the Vim plugin which will allow the
plugin to skip setting up a virtualenv. This is useful when there is a
system installation of black (e.g. from a Linux distribution) which the
user prefers to use.

Using a virtualenv remains the default.

- Fixes #3308
---
 CHANGES.md                   |  3 +++
 autoload/black.vim           | 10 ++++++++++
 docs/integrations/editors.md | 14 +++++++++++++-
 plugin/black.vim             |  3 +++
 4 files changed, 29 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index 4db961149bf..1dcd7f09b3c 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -50,6 +50,9 @@
 
 <!-- For example, Docker, GitHub Actions, pre-commit, editors -->
 
+- Vim plugin: Optionally allow using the system installation of Black via
+  `let g:black_use_virtualenv = 0`(#3309)
+
 ### Documentation
 
 <!-- Major changes to documentation and policies. Small docs changes
diff --git a/autoload/black.vim b/autoload/black.vim
index eec44637950..5aec8725bd0 100644
--- a/autoload/black.vim
+++ b/autoload/black.vim
@@ -56,6 +56,16 @@ def _get_virtualenv_site_packages(venv_path, pyver):
   return venv_path / 'lib' / f'python{pyver[0]}.{pyver[1]}' / 'site-packages'
 
 def _initialize_black_env(upgrade=False):
+  if vim.eval("g:black_use_virtualenv ? 'true' : 'false'") == "false":
+    if upgrade:
+      print("Upgrade disabled due to g:black_use_virtualenv being disabled.")
+      print("Either use your system package manager (or pip) to upgrade black separately,")
+      print("or modify your vimrc to have 'let g:black_use_virtualenv = 1'.")
+      return False
+    else:
+      # Nothing needed to be done.
+      return True
+
   pyver = sys.version_info[:3]
   if pyver < (3, 7):
     print("Sorry, Black requires Python 3.7+ to run.")
diff --git a/docs/integrations/editors.md b/docs/integrations/editors.md
index 28c9f48a09f..0778c6a72f1 100644
--- a/docs/integrations/editors.md
+++ b/docs/integrations/editors.md
@@ -104,7 +104,7 @@ Commands and shortcuts:
   - you can optionally pass `target_version=<version>` with the same values as in the
     command line.
 - `:BlackUpgrade` to upgrade _Black_ inside the virtualenv;
-- `:BlackVersion` to get the current version of _Black_ inside the virtualenv.
+- `:BlackVersion` to get the current version of _Black_ in use.
 
 Configuration:
 
@@ -160,6 +160,18 @@ If you need to do anything special to make your virtualenv work and install _Bla
 example you want to run a version from main), create a virtualenv manually and point
 `g:black_virtualenv` to it. The plugin will use it.
 
+If you would prefer to use the system installation of _Black_ rather than a virtualenv,
+then add this to your vimrc:
+
+```
+let g:black_use_virtualenv = 0
+```
+
+Note that the `:BlackUpgrade` command is only usable and useful with a virtualenv, so
+when the virtualenv is not in use, `:BlackUpgrade` is disabled. If you need to upgrade
+the system installation of _Black_, then use your system package manager or pip--
+whatever tool you used to install _Black_ originally.
+
 To run _Black_ on save, add the following lines to `.vimrc` or `init.vim`:
 
 ```
diff --git a/plugin/black.vim b/plugin/black.vim
index fb70424b0ef..543184e1cd4 100644
--- a/plugin/black.vim
+++ b/plugin/black.vim
@@ -63,6 +63,9 @@ endif
 if !exists("g:black_target_version")
   let g:black_target_version = ""
 endif
+if !exists("g:black_use_virtualenv")
+  let g:black_use_virtualenv = 1
+endif
 if !exists("g:black_preview")
   let g:black_preview = 0
 endif

From 3179a442afe12244406f0ef5024c6bdc12d87cf4 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 31 Oct 2022 06:49:52 -0700
Subject: [PATCH 0650/1034] Bump peter-evans/create-or-update-comment from
 2.0.1 to 2.1.0 (#3366)

Bumps [peter-evans/create-or-update-comment](https://github.com/peter-evans/create-or-update-comment) from 2.0.1 to 2.1.0.
- [Release notes](https://github.com/peter-evans/create-or-update-comment/releases)
- [Commits](https://github.com/peter-evans/create-or-update-comment/compare/2b2c85d0bf1b8a7b4e7e344bd5c71dc4b9196e9f...5adcb0bb0f9fb3f95ef05400558bdb3f329ee808)

---
updated-dependencies:
- dependency-name: peter-evans/create-or-update-comment
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/diff_shades_comment.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/diff_shades_comment.yml b/.github/workflows/diff_shades_comment.yml
index 9a22ec5f0c3..1d35432a295 100644
--- a/.github/workflows/diff_shades_comment.yml
+++ b/.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@2b2c85d0bf1b8a7b4e7e344bd5c71dc4b9196e9f
+        uses: peter-evans/create-or-update-comment@5adcb0bb0f9fb3f95ef05400558bdb3f329ee808
         with:
           comment-id: ${{ steps.find-comment.outputs.comment-id }}
           issue-number: ${{ steps.metadata.outputs.pr-number }}

From f67791427d2d10c4bc9e4932a51ebc51080871f9 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 31 Oct 2022 06:50:42 -0700
Subject: [PATCH 0651/1034] Bump pypa/cibuildwheel from 2.10.2 to 2.11.2
 (#3367)

Bumps [pypa/cibuildwheel](https://github.com/pypa/cibuildwheel) from 2.10.2 to 2.11.2.
- [Release notes](https://github.com/pypa/cibuildwheel/releases)
- [Changelog](https://github.com/pypa/cibuildwheel/blob/main/docs/changelog.md)
- [Commits](https://github.com/pypa/cibuildwheel/compare/v2.10.2...v2.11.2)

---
updated-dependencies:
- dependency-name: pypa/cibuildwheel
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/pypi_upload.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/pypi_upload.yml b/.github/workflows/pypi_upload.yml
index 76bcd33b55e..a5b4af37915 100644
--- a/.github/workflows/pypi_upload.yml
+++ b/.github/workflows/pypi_upload.yml
@@ -58,7 +58,7 @@ jobs:
       - uses: actions/checkout@v3
 
       - name: Build wheels via cibuildwheel
-        uses: pypa/cibuildwheel@v2.10.2
+        uses: pypa/cibuildwheel@v2.11.2
         env:
           CIBW_ARCHS_MACOS: "${{ matrix.macos_arch }}"
 

From 2704dc796b49b4c5d348c92ba14ef1cfd908e7f1 Mon Sep 17 00:00:00 2001
From: Gerhard van Andel <10352022+GerhardOfRivia@users.noreply.github.com>
Date: Tue, 1 Nov 2022 12:42:48 -0600
Subject: [PATCH 0652/1034] Update docs to include pycodestyle (#3369)

* Add pycodestyle to using_black_with_other_tools.md
---
 docs/guides/using_black_with_other_tools.md | 32 +++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/docs/guides/using_black_with_other_tools.md b/docs/guides/using_black_with_other_tools.md
index 1d380bdaba7..7bc0726dc27 100644
--- a/docs/guides/using_black_with_other_tools.md
+++ b/docs/guides/using_black_with_other_tools.md
@@ -252,3 +252,35 @@ max-line-length = "88"
 ```
 
 </details>
+
+### pycodestyle
+
+[pycodestyle](https://pycodestyle.pycqa.org/) is also a code linter like Flake8.
+
+#### Configuration
+
+```
+max_line_length = 88
+ignore = E203
+```
+
+#### Why those options above?
+
+pycodestyle should be configured to only complain about lines that surpass `88`
+characters via `max_line_length = 88`.
+
+See
+[Why are Flake8’s E203 and W503 violated?](https://black.readthedocs.io/en/stable/faq.html#why-are-flake8-s-e203-and-w503-violated)
+
+#### Formats
+
+<details>
+<summary>setup.cfg</summary>
+
+```cfg
+[pycodestyle]
+ignore = E203
+max_line_length = 88
+```
+
+</details>

From 0e9d29ab73d608a79028e22a713ee717b5dcca96 Mon Sep 17 00:00:00 2001
From: Antonio Ossa-Guerra <aaossa@uc.cl>
Date: Sat, 5 Nov 2022 02:09:59 -0300
Subject: [PATCH 0653/1034] Apply .gitignore correctly in every source entry
 (#3336)

When passing multiple src directories, the root gitignore was only
applied to the first processed source. The reason is that, in the
first source, exclude is `None`, but then the value gets overridden by
`re_compile_maybe_verbose(DEFAULT_EXCLUDES)`, so in the next iteration
where the source is a directory, the condition is not met and sets the
value of `gitignore` to `None`.

To fix this problem, we store a boolean indicating if `exclude` is
`None` and set the value of `exclude` to its default value if that's
the case. This makes sure that the flow enters the correct condition on
following iterations and also keeps the original value if the condition
is not met.

Also, the value of `gitignore` is initialized as `None` and overriden
if necessary. The value of `root_gitignore` is always calculated to
avoid using additional variables (at the small cost of additional
computations).

Signed-off-by: Antonio Ossa Guerra <aaossa@uc.cl>
---
 CHANGES.md                                     |  3 +++
 src/black/__init__.py                          | 18 +++++++++++-------
 .../.gitignore                                 |  1 +
 .../dir1/a.py                                  |  0
 .../dir1/b.py                                  |  0
 .../dir2/a.py                                  |  0
 .../dir2/b.py                                  |  0
 tests/test_black.py                            | 11 +++++++++++
 8 files changed, 26 insertions(+), 7 deletions(-)
 create mode 100644 tests/data/gitignore_used_on_multiple_sources/.gitignore
 create mode 100644 tests/data/gitignore_used_on_multiple_sources/dir1/a.py
 create mode 100644 tests/data/gitignore_used_on_multiple_sources/dir1/b.py
 create mode 100644 tests/data/gitignore_used_on_multiple_sources/dir2/a.py
 create mode 100644 tests/data/gitignore_used_on_multiple_sources/dir2/b.py

diff --git a/CHANGES.md b/CHANGES.md
index 1dcd7f09b3c..a1071a8ec7c 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -22,6 +22,9 @@
 
 <!-- Changes to how Black can be configured -->
 
+- Fix incorrectly ignoring .gitignore presence when more than one source directory is
+  specified (#3336)
+
 ### Packaging
 
 <!-- Changes to how Black is packaged, such as dependency requirements -->
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 94592278c31..6c8d3468583 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -30,6 +30,7 @@
 import click
 from click.core import ParameterSource
 from mypy_extensions import mypyc_attr
+from pathspec import PathSpec
 from pathspec.patterns.gitwildmatch import GitWildMatchPatternError
 
 from _black_version import version as __version__
@@ -627,6 +628,11 @@ def get_sources(
     sources: Set[Path] = set()
     root = ctx.obj["root"]
 
+    exclude_is_None = exclude is None
+    exclude = re_compile_maybe_verbose(DEFAULT_EXCLUDES) if exclude is None else exclude
+    gitignore = None  # type: Optional[PathSpec]
+    root_gitignore = get_gitignore(root)
+
     for s in src:
         if s == "-" and stdin_filename:
             p = Path(stdin_filename)
@@ -660,16 +666,14 @@ def get_sources(
 
             sources.add(p)
         elif p.is_dir():
-            if exclude is None:
-                exclude = re_compile_maybe_verbose(DEFAULT_EXCLUDES)
-                gitignore = get_gitignore(root)
+            if exclude_is_None:
                 p_gitignore = get_gitignore(p)
                 # No need to use p's gitignore if it is identical to root's gitignore
                 # (i.e. root and p point to the same directory).
-                if gitignore != p_gitignore:
-                    gitignore += p_gitignore
-            else:
-                gitignore = None
+                if root_gitignore == p_gitignore:
+                    gitignore = root_gitignore
+                else:
+                    gitignore = root_gitignore + p_gitignore
             sources.update(
                 gen_python_files(
                     p.iterdir(),
diff --git a/tests/data/gitignore_used_on_multiple_sources/.gitignore b/tests/data/gitignore_used_on_multiple_sources/.gitignore
new file mode 100644
index 00000000000..2987e7bb646
--- /dev/null
+++ b/tests/data/gitignore_used_on_multiple_sources/.gitignore
@@ -0,0 +1 @@
+a.py
diff --git a/tests/data/gitignore_used_on_multiple_sources/dir1/a.py b/tests/data/gitignore_used_on_multiple_sources/dir1/a.py
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/tests/data/gitignore_used_on_multiple_sources/dir1/b.py b/tests/data/gitignore_used_on_multiple_sources/dir1/b.py
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/tests/data/gitignore_used_on_multiple_sources/dir2/a.py b/tests/data/gitignore_used_on_multiple_sources/dir2/a.py
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/tests/data/gitignore_used_on_multiple_sources/dir2/b.py b/tests/data/gitignore_used_on_multiple_sources/dir2/b.py
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/tests/test_black.py b/tests/test_black.py
index 9256698ea27..784eb0dc9ad 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -1998,6 +1998,17 @@ def test_gitignore_used_as_default(self) -> None:
         ctx.obj["root"] = base
         assert_collected_sources(src, expected, ctx=ctx, extend_exclude=r"/exclude/")
 
+    def test_gitignore_used_on_multiple_sources(self) -> None:
+        root = Path(DATA_DIR / "gitignore_used_on_multiple_sources")
+        expected = [
+            root / "dir1" / "b.py",
+            root / "dir2" / "b.py",
+        ]
+        ctx = FakeContext()
+        ctx.obj["root"] = root
+        src = [root / "dir1", root / "dir2"]
+        assert_collected_sources(src, expected, ctx=ctx)
+
     @patch("black.find_project_root", lambda *args: (THIS_DIR.resolve(), None))
     def test_exclude_for_issue_1572(self) -> None:
         # Exclude shouldn't touch files that were explicitly given to Black through the

From ffaaf4838228c922b586a87f717ed402031fcc0a Mon Sep 17 00:00:00 2001
From: Antonio Ossa-Guerra <aaossa@uc.cl>
Date: Tue, 8 Nov 2022 12:50:04 -0300
Subject: [PATCH 0654/1034] Compare each .gitignore found with an appropiate
 relative path (#3338)

* Apply .gitignore files considering their location

When a .gitignore file contains the special rule to ignore every
subfolder content (`*/*`) and the file is located in a subfolder
relative to where the command is executed (root), the rule is
incorrectly applied and ignores every file at the same level of the
.gitignore file.

The reason for this is that the `gitignore` variable accumulates the
rules found in each .gitignore while traversing files and directories
recursively. This makes sense and, in general, works as expected. The
problem is that the gitignore rules are applied using as the relative
path from root to target directory as a reference. This is the cause
of the bug.

The implemented solution keeps track of every .gitignore file found
while traversing the targets and the absolute location of each
.gitignore file. Then, when matching files to the .gitignore rules,
compare each set of rules with the appropiate relative path to the
candidate target file.

To make this possible, we changed the single `gitignore` object with a
dictionary of similar objects, where the corresponding key is the
absolute path to the folder that contains that .gitignore file. This
required changing the signature of the `get_sources` function. Also, we
introduce a `is_ignored` function that compares a file with every set
of rules. Finally, some tests required an update to pass the gitignore
object in the new format.

Signed-off-by: Antonio Ossa Guerra <aaossa@uc.cl>

* Test .gitignore with `*/*` is applied correctly

The test contains three cases: 1) when the .gitignore with the special
rule to ignore every subfolder and its contents (*/*) is in the root,
2) when the file is inside a subfolder relative to root (nested), and
3) when the target folder contains the .gitignore and root is a parent
folder of the target. In all of these cases, we compare the files that
are visible by Black with a known list of paths containing the
expected values.

Before the fix introduced in the previous commit, these tests failed
when the .gitignore file was nested (second case). Now, the test is
passed for all cases.

Signed-off-by: Antonio Ossa Guerra <aaossa@uc.cl>

* Update CHANGES.md

Add entry about fixed bug and changes introduced: ignore files by
considering the location of each .gitignore file and the relative path
of each target

Signed-off-by: Antonio Ossa Guerra <aaossa@uc.cl>

* Small refactor to improve code readability

These changes are small improvements to improve code readability:
rename a variable to a more descriptive name (from `exclude_is_None`
to `using_default_exclude`), use a better syntax to include the type
annotation for `gitignore` variable (from typing comment to
Python-style typing annotation), and replace an if-else block with a
single dictionary definition (in this case, we need to compare keys
instead of values, meaning that the change works)

Signed-off-by: Antonio Ossa Guerra <aaossa@uc.cl>

* Make nested function a top-level function

The function to match a given path with every discovered .gitignore
file does not need to be a nested function and can be a top-level
function. The arguments did not change, but the naming of local
variables was improved for readability.

Signed-off-by: Antonio Ossa Guerra <aaossa@uc.cl>

Signed-off-by: Antonio Ossa Guerra <aaossa@uc.cl>
---
 CHANGES.md                                    |  2 ++
 src/black/__init__.py                         | 17 ++++------
 src/black/files.py                            | 28 +++++++++++++---
 .../ignore_subfolders_gitignore_tests/a.py    |  0
 .../subdir/.gitignore                         |  1 +
 .../subdir/b.py                               |  0
 .../subdir/subdir/c.py                        |  0
 tests/test_black.py                           | 32 +++++++++++++++++--
 8 files changed, 63 insertions(+), 17 deletions(-)
 create mode 100644 tests/data/ignore_subfolders_gitignore_tests/a.py
 create mode 100644 tests/data/ignore_subfolders_gitignore_tests/subdir/.gitignore
 create mode 100644 tests/data/ignore_subfolders_gitignore_tests/subdir/b.py
 create mode 100644 tests/data/ignore_subfolders_gitignore_tests/subdir/subdir/c.py

diff --git a/CHANGES.md b/CHANGES.md
index a1071a8ec7c..a9a1b279ddc 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -22,6 +22,8 @@
 
 <!-- Changes to how Black can be configured -->
 
+- Fix incorrectly applied .gitignore rules by considering the .gitignore location and
+  the relative path to the target file (#3338)
 - Fix incorrectly ignoring .gitignore presence when more than one source directory is
   specified (#3336)
 
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 6c8d3468583..2786861e9e0 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -628,9 +628,9 @@ def get_sources(
     sources: Set[Path] = set()
     root = ctx.obj["root"]
 
-    exclude_is_None = exclude is None
+    using_default_exclude = exclude is None
     exclude = re_compile_maybe_verbose(DEFAULT_EXCLUDES) if exclude is None else exclude
-    gitignore = None  # type: Optional[PathSpec]
+    gitignore: Optional[PathSpec] = None
     root_gitignore = get_gitignore(root)
 
     for s in src:
@@ -666,14 +666,11 @@ def get_sources(
 
             sources.add(p)
         elif p.is_dir():
-            if exclude_is_None:
-                p_gitignore = get_gitignore(p)
-                # No need to use p's gitignore if it is identical to root's gitignore
-                # (i.e. root and p point to the same directory).
-                if root_gitignore == p_gitignore:
-                    gitignore = root_gitignore
-                else:
-                    gitignore = root_gitignore + p_gitignore
+            if using_default_exclude:
+                gitignore = {
+                    root: root_gitignore,
+                    root / p: get_gitignore(p),
+                }
             sources.update(
                 gen_python_files(
                     p.iterdir(),
diff --git a/src/black/files.py b/src/black/files.py
index ed503f5fec7..ea517f4ece9 100644
--- a/src/black/files.py
+++ b/src/black/files.py
@@ -182,6 +182,19 @@ def normalize_path_maybe_ignore(
     return root_relative_path
 
 
+def path_is_ignored(
+    path: Path, gitignore_dict: Dict[Path, PathSpec], report: Report
+) -> bool:
+    for gitignore_path, pattern in gitignore_dict.items():
+        relative_path = normalize_path_maybe_ignore(path, gitignore_path, report)
+        if relative_path is None:
+            break
+        if pattern.match_file(relative_path):
+            report.path_ignored(path, "matches a .gitignore file content")
+            return True
+    return False
+
+
 def path_is_excluded(
     normalized_path: str,
     pattern: Optional[Pattern[str]],
@@ -198,7 +211,7 @@ def gen_python_files(
     extend_exclude: Optional[Pattern[str]],
     force_exclude: Optional[Pattern[str]],
     report: Report,
-    gitignore: Optional[PathSpec],
+    gitignore_dict: Optional[Dict[Path, PathSpec]],
     *,
     verbose: bool,
     quiet: bool,
@@ -211,6 +224,7 @@ def gen_python_files(
 
     `report` is where output about exclusions goes.
     """
+
     assert root.is_absolute(), f"INTERNAL ERROR: `root` must be absolute but is {root}"
     for child in paths:
         normalized_path = normalize_path_maybe_ignore(child, root, report)
@@ -218,8 +232,7 @@ def gen_python_files(
             continue
 
         # First ignore files matching .gitignore, if passed
-        if gitignore is not None and gitignore.match_file(normalized_path):
-            report.path_ignored(child, "matches the .gitignore file content")
+        if gitignore_dict and path_is_ignored(child, gitignore_dict, report):
             continue
 
         # Then ignore with `--exclude` `--extend-exclude` and `--force-exclude` options.
@@ -244,6 +257,13 @@ def gen_python_files(
         if child.is_dir():
             # If gitignore is None, gitignore usage is disabled, while a Falsey
             # gitignore is when the directory doesn't have a .gitignore file.
+            if gitignore_dict is not None:
+                new_gitignore_dict = {
+                    **gitignore_dict,
+                    root / child: get_gitignore(child),
+                }
+            else:
+                new_gitignore_dict = None
             yield from gen_python_files(
                 child.iterdir(),
                 root,
@@ -252,7 +272,7 @@ def gen_python_files(
                 extend_exclude,
                 force_exclude,
                 report,
-                gitignore + get_gitignore(child) if gitignore is not None else None,
+                new_gitignore_dict,
                 verbose=verbose,
                 quiet=quiet,
             )
diff --git a/tests/data/ignore_subfolders_gitignore_tests/a.py b/tests/data/ignore_subfolders_gitignore_tests/a.py
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/tests/data/ignore_subfolders_gitignore_tests/subdir/.gitignore b/tests/data/ignore_subfolders_gitignore_tests/subdir/.gitignore
new file mode 100644
index 00000000000..150f68c80f5
--- /dev/null
+++ b/tests/data/ignore_subfolders_gitignore_tests/subdir/.gitignore
@@ -0,0 +1 @@
+*/*
diff --git a/tests/data/ignore_subfolders_gitignore_tests/subdir/b.py b/tests/data/ignore_subfolders_gitignore_tests/subdir/b.py
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/tests/data/ignore_subfolders_gitignore_tests/subdir/subdir/c.py b/tests/data/ignore_subfolders_gitignore_tests/subdir/subdir/c.py
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/tests/test_black.py b/tests/test_black.py
index 784eb0dc9ad..a43f05e083b 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -2042,7 +2042,7 @@ def test_gitignore_exclude(self) -> None:
                 None,
                 None,
                 report,
-                gitignore,
+                {path: gitignore},
                 verbose=False,
                 quiet=False,
             )
@@ -2071,7 +2071,7 @@ def test_nested_gitignore(self) -> None:
                 None,
                 None,
                 report,
-                root_gitignore,
+                {path: root_gitignore},
                 verbose=False,
                 quiet=False,
             )
@@ -2109,6 +2109,32 @@ def test_invalid_nested_gitignore(self) -> None:
         gitignore = path / "a" / ".gitignore"
         assert f"Could not parse {gitignore}" in result.stderr_bytes.decode()
 
+    def test_gitignore_that_ignores_subfolders(self) -> None:
+        # If gitignore with */* is in root
+        root = Path(DATA_DIR / "ignore_subfolders_gitignore_tests" / "subdir")
+        expected = [root / "b.py"]
+        ctx = FakeContext()
+        ctx.obj["root"] = root
+        assert_collected_sources([root], expected, ctx=ctx)
+
+        # If .gitignore with */* is nested
+        root = Path(DATA_DIR / "ignore_subfolders_gitignore_tests")
+        expected = [
+            root / "a.py",
+            root / "subdir" / "b.py",
+        ]
+        ctx = FakeContext()
+        ctx.obj["root"] = root
+        assert_collected_sources([root], expected, ctx=ctx)
+
+        # If command is executed from outer dir
+        root = Path(DATA_DIR / "ignore_subfolders_gitignore_tests")
+        target = root / "subdir"
+        expected = [target / "b.py"]
+        ctx = FakeContext()
+        ctx.obj["root"] = root
+        assert_collected_sources([target], expected, ctx=ctx)
+
     def test_empty_include(self) -> None:
         path = DATA_DIR / "include_exclude_tests"
         src = [path]
@@ -2163,7 +2189,7 @@ def test_symlink_out_of_root_directory(self) -> None:
                     None,
                     None,
                     report,
-                    gitignore,
+                    {path: gitignore},
                     verbose=False,
                     quiet=False,
                 )

From 8091b2503d12dd0110e0f1a9ed1e6b830aa668ed Mon Sep 17 00:00:00 2001
From: "Yilei \"Dolee\" Yang" <yileiyang@google.com>
Date: Wed, 9 Nov 2022 15:08:51 -0800
Subject: [PATCH 0655/1034] Correctly handle trailing commas that are inside a
 line's leading non-nested parens (#3370)

- Fixes #1671
- Fixes #3229
---
 CHANGES.md                                    |  2 +
 src/black/brackets.py                         | 34 ++++++++-
 src/black/linegen.py                          | 70 ++++++++++++++----
 src/black/lines.py                            |  6 +-
 src/black/mode.py                             |  1 +
 .../data/preview/skip_magic_trailing_comma.py | 40 ++++++++++
 .../trailing_commas_in_leading_parts.py       | 74 +++++++++++++++++++
 .../simple_cases/function_trailing_comma.py   | 29 ++++++++
 8 files changed, 240 insertions(+), 16 deletions(-)
 create mode 100644 tests/data/preview/trailing_commas_in_leading_parts.py

diff --git a/CHANGES.md b/CHANGES.md
index a9a1b279ddc..4d1887f2842 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -17,6 +17,8 @@
 - Enforce empty lines before classes and functions with sticky leading comments (#3302)
 - Implicitly concatenated strings used as function args are now wrapped inside
   parentheses (#3307)
+- Correctly handle trailing commas that are inside a line's leading non-nested parens
+  (#3370)
 
 ### Configuration
 
diff --git a/src/black/brackets.py b/src/black/brackets.py
index 3566f5b6c37..0a5317f6773 100644
--- a/src/black/brackets.py
+++ b/src/black/brackets.py
@@ -2,7 +2,7 @@
 
 import sys
 from dataclasses import dataclass, field
-from typing import Dict, Iterable, List, Optional, Tuple, Union
+from typing import Dict, Iterable, List, Optional, Sequence, Set, Tuple, Union
 
 if sys.version_info < (3, 8):
     from typing_extensions import Final
@@ -340,3 +340,35 @@ def max_delimiter_priority_in_atom(node: LN) -> Priority:
 
     except ValueError:
         return 0
+
+
+def get_leaves_inside_matching_brackets(leaves: Sequence[Leaf]) -> Set[LeafID]:
+    """Return leaves that are inside matching brackets.
+
+    The input `leaves` can have non-matching brackets at the head or tail parts.
+    Matching brackets are included.
+    """
+    try:
+        # Only track brackets from the first opening bracket to the last closing
+        # bracket.
+        start_index = next(
+            i for i, l in enumerate(leaves) if l.type in OPENING_BRACKETS
+        )
+        end_index = next(
+            len(leaves) - i
+            for i, l in enumerate(reversed(leaves))
+            if l.type in CLOSING_BRACKETS
+        )
+    except StopIteration:
+        return set()
+    ids = set()
+    depth = 0
+    for i in range(end_index, start_index - 1, -1):
+        leaf = leaves[i]
+        if leaf.type in CLOSING_BRACKETS:
+            depth += 1
+        if depth > 0:
+            ids.add(id(leaf))
+        if leaf.type in OPENING_BRACKETS:
+            depth -= 1
+    return ids
diff --git a/src/black/linegen.py b/src/black/linegen.py
index a2e41bf5912..219495e9a5e 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -2,10 +2,16 @@
 Generating lines of code.
 """
 import sys
+from enum import Enum, auto
 from functools import partial, wraps
 from typing import Collection, Iterator, List, Optional, Set, Union, cast
 
-from black.brackets import COMMA_PRIORITY, DOT_PRIORITY, max_delimiter_priority_in_atom
+from black.brackets import (
+    COMMA_PRIORITY,
+    DOT_PRIORITY,
+    get_leaves_inside_matching_brackets,
+    max_delimiter_priority_in_atom,
+)
 from black.comments import FMT_OFF, generate_comments, list_comments
 from black.lines import (
     Line,
@@ -561,6 +567,12 @@ def _rhs(
         yield line
 
 
+class _BracketSplitComponent(Enum):
+    head = auto()
+    body = auto()
+    tail = auto()
+
+
 def left_hand_split(line: Line, _features: Collection[Feature] = ()) -> Iterator[Line]:
     """Split line into many lines, starting with the first matching bracket pair.
 
@@ -591,9 +603,15 @@ def left_hand_split(line: Line, _features: Collection[Feature] = ()) -> Iterator
     if not matching_bracket:
         raise CannotSplit("No brackets found")
 
-    head = bracket_split_build_line(head_leaves, line, matching_bracket)
-    body = bracket_split_build_line(body_leaves, line, matching_bracket, is_body=True)
-    tail = bracket_split_build_line(tail_leaves, line, matching_bracket)
+    head = bracket_split_build_line(
+        head_leaves, line, matching_bracket, component=_BracketSplitComponent.head
+    )
+    body = bracket_split_build_line(
+        body_leaves, line, matching_bracket, component=_BracketSplitComponent.body
+    )
+    tail = bracket_split_build_line(
+        tail_leaves, line, matching_bracket, component=_BracketSplitComponent.tail
+    )
     bracket_split_succeeded_or_raise(head, body, tail)
     for result in (head, body, tail):
         if result:
@@ -639,9 +657,15 @@ def right_hand_split(
     tail_leaves.reverse()
     body_leaves.reverse()
     head_leaves.reverse()
-    head = bracket_split_build_line(head_leaves, line, opening_bracket)
-    body = bracket_split_build_line(body_leaves, line, opening_bracket, is_body=True)
-    tail = bracket_split_build_line(tail_leaves, line, opening_bracket)
+    head = bracket_split_build_line(
+        head_leaves, line, opening_bracket, component=_BracketSplitComponent.head
+    )
+    body = bracket_split_build_line(
+        body_leaves, line, opening_bracket, component=_BracketSplitComponent.body
+    )
+    tail = bracket_split_build_line(
+        tail_leaves, line, opening_bracket, component=_BracketSplitComponent.tail
+    )
     bracket_split_succeeded_or_raise(head, body, tail)
     if (
         Feature.FORCE_OPTIONAL_PARENTHESES not in features
@@ -715,15 +739,23 @@ def bracket_split_succeeded_or_raise(head: Line, body: Line, tail: Line) -> None
 
 
 def bracket_split_build_line(
-    leaves: List[Leaf], original: Line, opening_bracket: Leaf, *, is_body: bool = False
+    leaves: List[Leaf],
+    original: Line,
+    opening_bracket: Leaf,
+    *,
+    component: _BracketSplitComponent,
 ) -> Line:
     """Return a new line with given `leaves` and respective comments from `original`.
 
-    If `is_body` is True, the result line is one-indented inside brackets and as such
-    has its first leaf's prefix normalized and a trailing comma added when expected.
+    If it's the head component, brackets will be tracked so trailing commas are
+    respected.
+
+    If it's the body component, the result line is one-indented inside brackets and as
+    such has its first leaf's prefix normalized and a trailing comma added when
+    expected.
     """
     result = Line(mode=original.mode, depth=original.depth)
-    if is_body:
+    if component is _BracketSplitComponent.body:
         result.inside_brackets = True
         result.depth += 1
         if leaves:
@@ -761,12 +793,24 @@ def bracket_split_build_line(
                         leaves.insert(i + 1, new_comma)
                     break
 
+    leaves_to_track: Set[LeafID] = set()
+    if (
+        Preview.handle_trailing_commas_in_head in original.mode
+        and component is _BracketSplitComponent.head
+    ):
+        leaves_to_track = get_leaves_inside_matching_brackets(leaves)
     # Populate the line
     for leaf in leaves:
-        result.append(leaf, preformatted=True)
+        result.append(
+            leaf,
+            preformatted=True,
+            track_bracket=id(leaf) in leaves_to_track,
+        )
         for comment_after in original.comments_after(leaf):
             result.append(comment_after, preformatted=True)
-    if is_body and should_split_line(result, opening_bracket):
+    if component is _BracketSplitComponent.body and should_split_line(
+        result, opening_bracket
+    ):
         result.should_split_rhs = True
     return result
 
diff --git a/src/black/lines.py b/src/black/lines.py
index 0d074534def..08281bcf370 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -53,7 +53,9 @@ class Line:
     should_split_rhs: bool = False
     magic_trailing_comma: Optional[Leaf] = None
 
-    def append(self, leaf: Leaf, preformatted: bool = False) -> None:
+    def append(
+        self, leaf: Leaf, preformatted: bool = False, track_bracket: bool = False
+    ) -> None:
         """Add a new `leaf` to the end of the line.
 
         Unless `preformatted` is True, the `leaf` will receive a new consistent
@@ -75,7 +77,7 @@ def append(self, leaf: Leaf, preformatted: bool = False) -> None:
             leaf.prefix += whitespace(
                 leaf, complex_subscript=self.is_complex_subscript(leaf)
             )
-        if self.inside_brackets or not preformatted:
+        if self.inside_brackets or not preformatted or track_bracket:
             self.bracket_tracker.mark(leaf)
             if self.mode.magic_trailing_comma:
                 if self.has_magic_trailing_comma(leaf):
diff --git a/src/black/mode.py b/src/black/mode.py
index e2eff2391b1..a3ce20b8619 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -151,6 +151,7 @@ class Preview(Enum):
 
     annotation_parens = auto()
     empty_lines_before_class_or_def_with_leading_comments = auto()
+    handle_trailing_commas_in_head = auto()
     long_docstring_quotes_on_newline = auto()
     normalize_docstring_quotes_and_prefixes_properly = auto()
     one_element_subscript = auto()
diff --git a/tests/data/preview/skip_magic_trailing_comma.py b/tests/data/preview/skip_magic_trailing_comma.py
index e98174af427..c020db79864 100644
--- a/tests/data/preview/skip_magic_trailing_comma.py
+++ b/tests/data/preview/skip_magic_trailing_comma.py
@@ -15,6 +15,37 @@
 # Except single element tuples
 small_tuple = (1,)
 
+# Trailing commas in multiple chained non-nested parens.
+zero(
+    one,
+).two(
+    three,
+).four(
+    five,
+)
+
+func1(arg1).func2(arg2,).func3(arg3).func4(arg4,).func5(arg5)
+
+(
+    a,
+    b,
+    c,
+    d,
+) = func1(
+    arg1
+) and func2(arg2)
+
+func(
+    argument1,
+    (
+        one,
+        two,
+    ),
+    argument4,
+    argument5,
+    argument6,
+)
+
 # output
 # We should not remove the trailing comma in a single-element subscript.
 a: tuple[int,]
@@ -32,3 +63,12 @@
 
 # Except single element tuples
 small_tuple = (1,)
+
+# Trailing commas in multiple chained non-nested parens.
+zero(one).two(three).four(five)
+
+func1(arg1).func2(arg2).func3(arg3).func4(arg4).func5(arg5)
+
+(a, b, c, d) = func1(arg1) and func2(arg2)
+
+func(argument1, (one, two), argument4, argument5, argument6)
diff --git a/tests/data/preview/trailing_commas_in_leading_parts.py b/tests/data/preview/trailing_commas_in_leading_parts.py
new file mode 100644
index 00000000000..676725c12a3
--- /dev/null
+++ b/tests/data/preview/trailing_commas_in_leading_parts.py
@@ -0,0 +1,74 @@
+zero(one,).two(three,).four(five,)
+
+func1(arg1).func2(arg2,).func3(arg3).func4(arg4,).func5(arg5)
+
+# Inner one-element tuple shouldn't explode
+func1(arg1).func2(arg1, (one_tuple,)).func3(arg3)
+
+(a, b, c, d,) = func1(arg1) and func2(arg2)
+
+
+# Example from https://github.com/psf/black/issues/3229
+def refresh_token(self, device_family, refresh_token, api_key):
+    return self.orchestration.refresh_token(
+        data={
+            "refreshToken": refresh_token,
+        },
+        api_key=api_key,
+    )["extensions"]["sdk"]["token"]
+
+
+# Edge case where a bug in a working-in-progress version of
+# https://github.com/psf/black/pull/3370 causes an infinite recursion.
+assert (
+    long_module.long_class.long_func().another_func()
+    == long_module.long_class.long_func()["some_key"].another_func(arg1)
+)
+
+
+# output
+
+
+zero(
+    one,
+).two(
+    three,
+).four(
+    five,
+)
+
+func1(arg1).func2(
+    arg2,
+).func3(arg3).func4(
+    arg4,
+).func5(arg5)
+
+# Inner one-element tuple shouldn't explode
+func1(arg1).func2(arg1, (one_tuple,)).func3(arg3)
+
+(
+    a,
+    b,
+    c,
+    d,
+) = func1(
+    arg1
+) and func2(arg2)
+
+
+# Example from https://github.com/psf/black/issues/3229
+def refresh_token(self, device_family, refresh_token, api_key):
+    return self.orchestration.refresh_token(
+        data={
+            "refreshToken": refresh_token,
+        },
+        api_key=api_key,
+    )["extensions"]["sdk"]["token"]
+
+
+# Edge case where a bug in a working-in-progress version of
+# https://github.com/psf/black/pull/3370 causes an infinite recursion.
+assert (
+    long_module.long_class.long_func().another_func()
+    == long_module.long_class.long_func()["some_key"].another_func(arg1)
+)
diff --git a/tests/data/simple_cases/function_trailing_comma.py b/tests/data/simple_cases/function_trailing_comma.py
index 429eb0e330f..abe9617c0e9 100644
--- a/tests/data/simple_cases/function_trailing_comma.py
+++ b/tests/data/simple_cases/function_trailing_comma.py
@@ -49,6 +49,17 @@ def func() -> ((also_super_long_type_annotation_that_may_cause_an_AST_related_cr
 ):
     pass
 
+
+# Make sure inner one-element tuple won't explode
+some_module.some_function(
+    argument1, (one_element_tuple,), argument4, argument5, argument6
+)
+
+# Inner trailing comma causes outer to explode
+some_module.some_function(
+    argument1, (one, two,), argument4, argument5, argument6
+)
+
 # output
 
 def f(
@@ -151,3 +162,21 @@ def func() -> (
     )
 ):
     pass
+
+
+# Make sure inner one-element tuple won't explode
+some_module.some_function(
+    argument1, (one_element_tuple,), argument4, argument5, argument6
+)
+
+# Inner trailing comma causes outer to explode
+some_module.some_function(
+    argument1,
+    (
+        one,
+        two,
+    ),
+    argument4,
+    argument5,
+    argument6,
+)

From c23a5c15aac963b460fdb1327ae875aafafafd41 Mon Sep 17 00:00:00 2001
From: Maximilian Cosmo Sitter <48606431+mcsitter@users.noreply.github.com>
Date: Thu, 10 Nov 2022 16:03:19 +0100
Subject: [PATCH 0656/1034] Clarify that Black runs with --safe by default
 (#3378)

---
 docs/the_black_code_style/current_style.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/the_black_code_style/current_style.md b/docs/the_black_code_style/current_style.md
index 59d79c4cd0e..0f166fe2bd4 100644
--- a/docs/the_black_code_style/current_style.md
+++ b/docs/the_black_code_style/current_style.md
@@ -457,9 +457,9 @@ the latter are treated as true raw strings with no special semantics.
 
 ### AST before and after formatting
 
-When run with `--safe`, _Black_ checks that the code before and after is semantically
-equivalent. This check is done by comparing the AST of the source with the AST of the
-target. There are three limited cases in which the AST does differ:
+When run with `--safe` (the default), _Black_ checks that the code before and after is
+semantically equivalent. This check is done by comparing the AST of the source with the
+AST of the target. There are three limited cases in which the AST does differ:
 
 1. _Black_ cleans up leading and trailing whitespace of docstrings, re-indenting them if
    needed. It's been one of the most popular user-reported features for the formatter to

From d97b7898b34b67eb3c6839998920e17ac8c77908 Mon Sep 17 00:00:00 2001
From: Antonio Ossa-Guerra <aaossa@uc.cl>
Date: Fri, 11 Nov 2022 22:05:36 -0300
Subject: [PATCH 0657/1034] Remove whitespaces of whitespace-only files (#3348)

Currently, empty and whitespace-only (with or without newlines) are
not modified. In some discussions (issues and pull requests) consensus
was to reformat whitespace-only files to empty or single-character
files, preserving line endings when possible. With that said, this
commit introduces the following behaviors:

* Empty files are left as is
* Whitespace-only files (no newline) reformat into empty files
* Whitespace-only files (1 or more newlines) reformat into a single
newline character

To implement these changes, we moved the initial check at
`format_file_contents` that raises `NothingChanged` if the source
(with no whitespaces) is an empty string. In the case of *.ipynb
files, `format_ipynb_string` checks a similar condition and removed
whitespaces. In the case of Python files, `format_str_once` includes a
check on the output that returns the correct newline character if
possible or an empty string otherwise.

Signed-off-by: Antonio Ossa Guerra <aaossa@uc.cl>
---
 CHANGES.md                       |  2 +
 src/black/__init__.py            | 12 ++++-
 tests/data/preview/whitespace.py |  6 +++
 tests/test_black.py              | 87 +++++++++++++++++++++++++++++++-
 4 files changed, 104 insertions(+), 3 deletions(-)
 create mode 100644 tests/data/preview/whitespace.py

diff --git a/CHANGES.md b/CHANGES.md
index 4d1887f2842..992b3800405 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -15,6 +15,8 @@
 <!-- Changes that affect Black's preview style -->
 
 - Enforce empty lines before classes and functions with sticky leading comments (#3302)
+- Reformat empty and whitespace-only files as either an empty file (if no newline is
+  present) or as a single newline character (if a newline is present) (#3348)
 - Implicitly concatenated strings used as function args are now wrapped inside
   parentheses (#3307)
 - Correctly handle trailing commas that are inside a line's leading non-nested parens
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 2786861e9e0..7d7ddbe0930 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -917,7 +917,7 @@ def format_file_contents(src_contents: str, *, fast: bool, mode: Mode) -> FileCo
     valid by calling :func:`assert_equivalent` and :func:`assert_stable` on it.
     `mode` is passed to :func:`format_str`.
     """
-    if not src_contents.strip():
+    if not mode.preview and not src_contents.strip():
         raise NothingChanged
 
     if mode.is_ipynb:
@@ -1014,6 +1014,9 @@ def format_ipynb_string(src_contents: str, *, fast: bool, mode: Mode) -> FileCon
     Operate cell-by-cell, only on code cells, only for Python notebooks.
     If the ``.ipynb`` originally had a trailing newline, it'll be preserved.
     """
+    if mode.preview and not src_contents:
+        raise NothingChanged
+
     trailing_newline = src_contents[-1] == "\n"
     modified = False
     nb = json.loads(src_contents)
@@ -1106,6 +1109,13 @@ def _format_str_once(src_contents: str, *, mode: Mode) -> str:
     dst_contents = []
     for block in dst_blocks:
         dst_contents.extend(block.all_lines())
+    if mode.preview and not dst_contents:
+        # Use decode_bytes to retrieve the correct source newline (CRLF or LF),
+        # and check if normalized_content has more than one line
+        normalized_content, _, newline = decode_bytes(src_contents.encode("utf-8"))
+        if "\n" in normalized_content:
+            return newline
+        return ""
     return "".join(dst_contents)
 
 
diff --git a/tests/data/preview/whitespace.py b/tests/data/preview/whitespace.py
new file mode 100644
index 00000000000..a319c0117b1
--- /dev/null
+++ b/tests/data/preview/whitespace.py
@@ -0,0 +1,6 @@
+
+		
+
+           
+
+# output
diff --git a/tests/test_black.py b/tests/test_black.py
index a43f05e083b..dda10555c97 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -25,6 +25,7 @@
     List,
     Optional,
     Sequence,
+    Type,
     TypeVar,
     Union,
 )
@@ -153,6 +154,34 @@ def test_empty_ff(self) -> None:
             os.unlink(tmp_file)
         self.assertFormatEqual(expected, actual)
 
+    @patch("black.dump_to_file", dump_to_stderr)
+    def test_one_empty_line(self) -> None:
+        mode = black.Mode(preview=True)
+        for nl in ["\n", "\r\n"]:
+            source = expected = nl
+            assert_format(source, expected, mode=mode)
+
+    def test_one_empty_line_ff(self) -> None:
+        mode = black.Mode(preview=True)
+        for nl in ["\n", "\r\n"]:
+            expected = nl
+            tmp_file = Path(black.dump_to_file(nl))
+            if system() == "Windows":
+                # Writing files in text mode automatically uses the system newline,
+                # but in this case we don't want this for testing reasons. See:
+                # https://github.com/psf/black/pull/3348
+                with open(tmp_file, "wb") as f:
+                    f.write(nl.encode("utf-8"))
+            try:
+                self.assertFalse(
+                    ff(tmp_file, mode=mode, write_back=black.WriteBack.YES)
+                )
+                with open(tmp_file, "rb") as f:
+                    actual = f.read().decode("utf8")
+            finally:
+                os.unlink(tmp_file)
+            self.assertFormatEqual(expected, actual)
+
     def test_experimental_string_processing_warns(self) -> None:
         self.assertWarns(
             black.mode.Deprecated, black.Mode, experimental_string_processing=True
@@ -971,8 +1000,8 @@ def err(msg: str, **kwargs: Any) -> None:
         )
 
     def test_format_file_contents(self) -> None:
-        empty = ""
         mode = DEFAULT_MODE
+        empty = ""
         with self.assertRaises(black.NothingChanged):
             black.format_file_contents(empty, mode=mode, fast=False)
         just_nl = "\n"
@@ -990,6 +1019,17 @@ def test_format_file_contents(self) -> None:
             black.format_file_contents(invalid, mode=mode, fast=False)
         self.assertEqual(str(e.exception), "Cannot parse: 1:7: return if you can")
 
+        mode = black.Mode(preview=True)
+        just_crlf = "\r\n"
+        with self.assertRaises(black.NothingChanged):
+            black.format_file_contents(just_crlf, mode=mode, fast=False)
+        just_whitespace_nl = "\n\t\n \n\t \n \t\n\n"
+        actual = black.format_file_contents(just_whitespace_nl, mode=mode, fast=False)
+        self.assertEqual("\n", actual)
+        just_whitespace_crlf = "\r\n\t\r\n \r\n\t \r\n \t\r\n\r\n"
+        actual = black.format_file_contents(just_whitespace_crlf, mode=mode, fast=False)
+        self.assertEqual("\r\n", actual)
+
     def test_endmarker(self) -> None:
         n = black.lib2to3_parse("\n")
         self.assertEqual(n.type, black.syms.file_input)
@@ -1281,8 +1321,51 @@ def test_reformat_one_with_stdin_and_existing_path(self) -> None:
             report.done.assert_called_with(expected, black.Changed.YES)
 
     def test_reformat_one_with_stdin_empty(self) -> None:
+        cases = [
+            ("", ""),
+            ("\n", "\n"),
+            ("\r\n", "\r\n"),
+            (" \t", ""),
+            (" \t\n\t ", "\n"),
+            (" \t\r\n\t ", "\r\n"),
+        ]
+
+        def _new_wrapper(
+            output: io.StringIO, io_TextIOWrapper: Type[io.TextIOWrapper]
+        ) -> Callable[[Any, Any], io.TextIOWrapper]:
+            def get_output(*args: Any, **kwargs: Any) -> io.TextIOWrapper:
+                if args == (sys.stdout.buffer,):
+                    # It's `format_stdin_to_stdout()` calling `io.TextIOWrapper()`,
+                    # return our mock object.
+                    return output
+                # It's something else (i.e. `decode_bytes()`) calling
+                # `io.TextIOWrapper()`, pass through to the original implementation.
+                # See discussion in https://github.com/psf/black/pull/2489
+                return io_TextIOWrapper(*args, **kwargs)
+
+            return get_output
+
+        mode = black.Mode(preview=True)
+        for content, expected in cases:
+            output = io.StringIO()
+            io_TextIOWrapper = io.TextIOWrapper
+
+            with patch("io.TextIOWrapper", _new_wrapper(output, io_TextIOWrapper)):
+                try:
+                    black.format_stdin_to_stdout(
+                        fast=True,
+                        content=content,
+                        write_back=black.WriteBack.YES,
+                        mode=mode,
+                    )
+                except io.UnsupportedOperation:
+                    pass  # StringIO does not support detach
+                assert output.getvalue() == expected
+
+        # An empty string is the only test case for `preview=False`
         output = io.StringIO()
-        with patch("io.TextIOWrapper", lambda *args, **kwargs: output):
+        io_TextIOWrapper = io.TextIOWrapper
+        with patch("io.TextIOWrapper", _new_wrapper(output, io_TextIOWrapper)):
             try:
                 black.format_stdin_to_stdout(
                     fast=True,

From 27932494bcefac03497dd92dcf0c59a04c10d757 Mon Sep 17 00:00:00 2001
From: sckarlin <github@karlin-online.com>
Date: Mon, 14 Nov 2022 10:31:43 -0500
Subject: [PATCH 0658/1034] Wordsmith current_style.md (#3383)

"realtime" doesn't make sense in this context.
---
 docs/the_black_code_style/current_style.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/the_black_code_style/current_style.md b/docs/the_black_code_style/current_style.md
index 0f166fe2bd4..56b92529d70 100644
--- a/docs/the_black_code_style/current_style.md
+++ b/docs/the_black_code_style/current_style.md
@@ -464,8 +464,8 @@ AST of the target. There are three limited cases in which the AST does differ:
 1. _Black_ cleans up leading and trailing whitespace of docstrings, re-indenting them if
    needed. It's been one of the most popular user-reported features for the formatter to
    fix whitespace issues with docstrings. While the result is technically an AST
-   difference, due to the various possibilities of forming docstrings, all realtime use
-   of docstrings that we're aware of sanitizes indentation and leading/trailing
+   difference, due to the various possibilities of forming docstrings, all real-world
+   uses of docstrings that we're aware of sanitize indentation and leading/trailing
    whitespace anyway.
 
 1. _Black_ manages optional parentheses for some statements. In the case of the `del`

From d4a85643a465f5fae2113d07d22d021d4af4795a Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 21 Nov 2022 08:24:46 -0800
Subject: [PATCH 0659/1034] Bump sphinx-copybutton from 0.5.0 to 0.5.1 in /docs
 (#3390)

Bumps [sphinx-copybutton](https://github.com/executablebooks/sphinx-copybutton) from 0.5.0 to 0.5.1.
- [Release notes](https://github.com/executablebooks/sphinx-copybutton/releases)
- [Changelog](https://github.com/executablebooks/sphinx-copybutton/blob/master/CHANGELOG.md)
- [Commits](https://github.com/executablebooks/sphinx-copybutton/compare/v0.5.0...v0.5.1)

---
updated-dependencies:
- dependency-name: sphinx-copybutton
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 docs/requirements.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index c2342a35d7b..426a78a7abf 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -5,5 +5,5 @@ Sphinx==5.3.0
 # Older versions break Sphinx even though they're declared to be supported.
 docutils==0.19
 sphinxcontrib-programoutput==0.17
-sphinx_copybutton==0.5.0
+sphinx_copybutton==0.5.1
 furo==2022.9.29

From 19c5fe429e355a53ff320065d22e661785040b4c Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Thu, 8 Dec 2022 20:11:07 -0800
Subject: [PATCH 0660/1034] Fix CI with latest flake8-bugbear (#3412)

---
 .flake8 | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/.flake8 b/.flake8
index ae11a13347c..eddaaba81fd 100644
--- a/.flake8
+++ b/.flake8
@@ -1,5 +1,6 @@
 [flake8]
-ignore = E203, E266, E501, W503
+# B905 should be enabled when we drop support for 3.9
+ignore = E203, E266, E501, W503, B905
 # line length is intentionally set to 80 here because black uses Bugbear
 # See https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#line-length for more details
 max-line-length = 80

From 9ace064d85e1fb0497db635e485fdab1e174e737 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Thu, 8 Dec 2022 23:28:29 -0500
Subject: [PATCH 0661/1034] Bump peter-evans/find-comment from 2.0.1 to 2.1.0
 (#3404)

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/diff_shades_comment.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/diff_shades_comment.yml b/.github/workflows/diff_shades_comment.yml
index 1d35432a295..1375be9788d 100644
--- a/.github/workflows/diff_shades_comment.yml
+++ b/.github/workflows/diff_shades_comment.yml
@@ -33,7 +33,7 @@ jobs:
       - name: Try to find pre-existing PR comment
         if: steps.metadata.outputs.needs-comment == 'true'
         id: find-comment
-        uses: peter-evans/find-comment@b657a70ff16d17651703a84bee1cb9ad9d2be2ea
+        uses: peter-evans/find-comment@f4499a714d59013c74a08789b48abe4b704364a0
         with:
           issue-number: ${{ steps.metadata.outputs.pr-number }}
           comment-author: "github-actions[bot]"

From 5b1443aefd9ad2bbaa20a76997183225dbfcc0fb Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Thu, 8 Dec 2022 20:36:39 -0800
Subject: [PATCH 0662/1034] release: skip bad macos wheels for now (#3411)

Workaround for #3312
---
 .github/workflows/pypi_upload.yml | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/pypi_upload.yml b/.github/workflows/pypi_upload.yml
index a5b4af37915..16cf90bd206 100644
--- a/.github/workflows/pypi_upload.yml
+++ b/.github/workflows/pypi_upload.yml
@@ -47,12 +47,13 @@ jobs:
           - os: macos-11
             name: macos-x86_64
             macos_arch: "x86_64"
-          - os: macos-11
-            name: macos-arm64
-            macos_arch: "arm64"
-          - os: macos-11
-            name: macos-universal2
-            macos_arch: "universal2"
+          # Only build x86_64 wheels on macos until #3312 is fixed
+          # - os: macos-11
+          #   name: macos-arm64
+          #   macos_arch: "arm64"
+          # - os: macos-11
+          #   name: macos-universal2
+          #   macos_arch: "universal2"
 
     steps:
       - uses: actions/checkout@v3

From 2ddea293a88919650266472186620a98a4a8bb37 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Fri, 9 Dec 2022 07:49:43 -0800
Subject: [PATCH 0663/1034] Prepare release 22.12.0 (#3413)

---
 CHANGES.md                                  | 58 ++++++++++++++-------
 docs/integrations/source_version_control.md |  2 +-
 docs/usage_and_configuration/the_basics.md  |  2 +-
 3 files changed, 40 insertions(+), 22 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 992b3800405..20ae65d36f3 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -14,23 +14,10 @@
 
 <!-- Changes that affect Black's preview style -->
 
-- Enforce empty lines before classes and functions with sticky leading comments (#3302)
-- Reformat empty and whitespace-only files as either an empty file (if no newline is
-  present) or as a single newline character (if a newline is present) (#3348)
-- Implicitly concatenated strings used as function args are now wrapped inside
-  parentheses (#3307)
-- Correctly handle trailing commas that are inside a line's leading non-nested parens
-  (#3370)
-
 ### Configuration
 
 <!-- Changes to how Black can be configured -->
 
-- Fix incorrectly applied .gitignore rules by considering the .gitignore location and
-  the relative path to the target file (#3338)
-- Fix incorrectly ignoring .gitignore presence when more than one source directory is
-  specified (#3336)
-
 ### Packaging
 
 <!-- Changes to how Black is packaged, such as dependency requirements -->
@@ -39,10 +26,6 @@
 
 <!-- Changes to the parser or to version autodetection -->
 
-- Parsing support has been added for walruses inside generator expression that are
-  passed as function args (for example,
-  `any(match := my_re.match(text) for text in texts)`) (#3327).
-
 ### Performance
 
 <!-- Changes that improve Black's performance. -->
@@ -59,14 +42,49 @@
 
 <!-- For example, Docker, GitHub Actions, pre-commit, editors -->
 
-- Vim plugin: Optionally allow using the system installation of Black via
-  `let g:black_use_virtualenv = 0`(#3309)
-
 ### Documentation
 
 <!-- Major changes to documentation and policies. Small docs changes
      don't need a changelog entry. -->
 
+## 22.12.0
+
+### Preview style
+
+<!-- Changes that affect Black's preview style -->
+
+- Enforce empty lines before classes and functions with sticky leading comments (#3302)
+- Reformat empty and whitespace-only files as either an empty file (if no newline is
+  present) or as a single newline character (if a newline is present) (#3348)
+- Implicitly concatenated strings used as function args are now wrapped inside
+  parentheses (#3307)
+- Correctly handle trailing commas that are inside a line's leading non-nested parens
+  (#3370)
+
+### Configuration
+
+<!-- Changes to how Black can be configured -->
+
+- Fix incorrectly applied `.gitignore` rules by considering the `.gitignore` location
+  and the relative path to the target file (#3338)
+- Fix incorrectly ignoring `.gitignore` presence when more than one source directory is
+  specified (#3336)
+
+### Parser
+
+<!-- Changes to the parser or to version autodetection -->
+
+- Parsing support has been added for walruses inside generator expression that are
+  passed as function args (for example,
+  `any(match := my_re.match(text) for text in texts)`) (#3327).
+
+### Integrations
+
+<!-- For example, Docker, GitHub Actions, pre-commit, editors -->
+
+- Vim plugin: Optionally allow using the system installation of Black via
+  `let g:black_use_virtualenv = 0`(#3309)
+
 ## 22.10.0
 
 ### Highlights
diff --git a/docs/integrations/source_version_control.md b/docs/integrations/source_version_control.md
index 4189b5c4b06..712b9a688d1 100644
--- a/docs/integrations/source_version_control.md
+++ b/docs/integrations/source_version_control.md
@@ -7,7 +7,7 @@ Use [pre-commit](https://pre-commit.com/). Once you
 ```yaml
 repos:
   - repo: https://github.com/psf/black
-    rev: 22.10.0
+    rev: 22.12.0
     hooks:
       - id: black
         # It is recommended to specify the latest version of Python
diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index 80897532a68..3dab644f2c8 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -175,7 +175,7 @@ You can check the version of _Black_ you have installed using the `--version` fl
 
 ```console
 $ black --version
-black, version 22.10.0
+black, version 22.12.0
 ```
 
 An option to require a specific version to be running is also provided.

From 1f7f6de4aba4e1e42cb2f947204f8256f7370cb0 Mon Sep 17 00:00:00 2001
From: Isac Byeonghoon Yoo <bhyoo@bhyoo.com>
Date: Sun, 11 Dec 2022 00:08:05 +0900
Subject: [PATCH 0664/1034] Fix type annotation for gitignore pathspec (#3416)

---
 src/black/__init__.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index 7d7ddbe0930..39d12968c4b 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -630,7 +630,7 @@ def get_sources(
 
     using_default_exclude = exclude is None
     exclude = re_compile_maybe_verbose(DEFAULT_EXCLUDES) if exclude is None else exclude
-    gitignore: Optional[PathSpec] = None
+    gitignore: Optional[Dict[Path, PathSpec]] = None
     root_gitignore = get_gitignore(root)
 
     for s in src:

From 96e62c57e3023977de177a8ba34678007a63f1fe Mon Sep 17 00:00:00 2001
From: "Yilei \"Dolee\" Yang" <yileiyang@google.com>
Date: Sat, 10 Dec 2022 07:58:45 -0800
Subject: [PATCH 0665/1034] Fix a crash in preview style with assert +
 parenthesized string. (#3415)

The bug is in the `get_leaves_inside_matching_brackets` on the third line below:

```python
assert xxxxxxxxx.xxxxxxxxx.xxxxxxxxx(
    xxxxxxxxx
).xxxxxxxxxxxxxxxxxx(), (
    "xxx {xxxxxxxxx} xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
)
```

Including the invisible paren, third line is `).xxxxxxxxxxxxxxxxxx()), (`, that it has a matched pair then an unmatched closing paren afterwards. This PR ensures the returned leaves are actually matched.

Fixes #3414.
---
 CHANGES.md                                    |  2 ++
 src/black/brackets.py                         | 25 ++++++++-----------
 .../trailing_commas_in_leading_parts.py       | 14 +++++++++++
 3 files changed, 27 insertions(+), 14 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 20ae65d36f3..c84feb04934 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -14,6 +14,8 @@
 
 <!-- Changes that affect Black's preview style -->
 
+- Fix a crash in preview style with assert + parenthesized string (#3415)
+
 ### Configuration
 
 <!-- Changes to how Black can be configured -->
diff --git a/src/black/brackets.py b/src/black/brackets.py
index 0a5317f6773..ec9708cb08a 100644
--- a/src/black/brackets.py
+++ b/src/black/brackets.py
@@ -349,26 +349,23 @@ def get_leaves_inside_matching_brackets(leaves: Sequence[Leaf]) -> Set[LeafID]:
     Matching brackets are included.
     """
     try:
-        # Only track brackets from the first opening bracket to the last closing
-        # bracket.
+        # Start with the first opening bracket and ignore closing brackets before.
         start_index = next(
             i for i, l in enumerate(leaves) if l.type in OPENING_BRACKETS
         )
-        end_index = next(
-            len(leaves) - i
-            for i, l in enumerate(reversed(leaves))
-            if l.type in CLOSING_BRACKETS
-        )
     except StopIteration:
         return set()
+    bracket_stack = []
     ids = set()
-    depth = 0
-    for i in range(end_index, start_index - 1, -1):
+    for i in range(start_index, len(leaves)):
         leaf = leaves[i]
-        if leaf.type in CLOSING_BRACKETS:
-            depth += 1
-        if depth > 0:
-            ids.add(id(leaf))
         if leaf.type in OPENING_BRACKETS:
-            depth -= 1
+            bracket_stack.append((BRACKET[leaf.type], i))
+        if leaf.type in CLOSING_BRACKETS:
+            if bracket_stack and leaf.type == bracket_stack[-1][0]:
+                _, start = bracket_stack.pop()
+                for j in range(start, i + 1):
+                    ids.add(id(leaves[j]))
+            else:
+                break
     return ids
diff --git a/tests/data/preview/trailing_commas_in_leading_parts.py b/tests/data/preview/trailing_commas_in_leading_parts.py
index 676725c12a3..99d82a677f8 100644
--- a/tests/data/preview/trailing_commas_in_leading_parts.py
+++ b/tests/data/preview/trailing_commas_in_leading_parts.py
@@ -25,6 +25,13 @@ def refresh_token(self, device_family, refresh_token, api_key):
     == long_module.long_class.long_func()["some_key"].another_func(arg1)
 )
 
+# Regression test for https://github.com/psf/black/issues/3414.
+assert xxxxxxxxx.xxxxxxxxx.xxxxxxxxx(
+    xxxxxxxxx
+).xxxxxxxxxxxxxxxxxx(), (
+    "xxx {xxxxxxxxx} xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+)
+
 
 # output
 
@@ -72,3 +79,10 @@ def refresh_token(self, device_family, refresh_token, api_key):
     long_module.long_class.long_func().another_func()
     == long_module.long_class.long_func()["some_key"].another_func(arg1)
 )
+
+# Regression test for https://github.com/psf/black/issues/3414.
+assert xxxxxxxxx.xxxxxxxxx.xxxxxxxxx(
+    xxxxxxxxx
+).xxxxxxxxxxxxxxxxxx(), (
+    "xxx {xxxxxxxxx} xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+)

From 16b98abca94343770aad561ea659380c97d473b4 Mon Sep 17 00:00:00 2001
From: Marco Edward Gorelli <33491632+MarcoGorelli@users.noreply.github.com>
Date: Sat, 10 Dec 2022 19:49:33 +0000
Subject: [PATCH 0666/1034] make black[jupyter] installation cross-shell
 (#3394)

---
 README.md                        | 2 +-
 docs/getting_started.md          | 2 +-
 src/black/handle_ipynb_magics.py | 2 +-
 tests/test_no_ipynb.py           | 4 ++--
 4 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index c2dd9e6b17d..b12ddfb1290 100644
--- a/README.md
+++ b/README.md
@@ -39,7 +39,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.7+ to run.
-If you want to format Jupyter Notebooks, install with `pip install 'black[jupyter]'`.
+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:
 
diff --git a/docs/getting_started.md b/docs/getting_started.md
index 1825f3b5aa3..33fb2f978bb 100644
--- a/docs/getting_started.md
+++ b/docs/getting_started.md
@@ -17,7 +17,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.7+ to run.
-If you want to format Jupyter Notebooks, install with `pip install 'black[jupyter]'`.
+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:
 
diff --git a/src/black/handle_ipynb_magics.py b/src/black/handle_ipynb_magics.py
index 693f1a68bd4..9e1af757c32 100644
--- a/src/black/handle_ipynb_magics.py
+++ b/src/black/handle_ipynb_magics.py
@@ -64,7 +64,7 @@ def jupyter_dependencies_are_installed(*, verbose: bool, quiet: bool) -> bool:
         if verbose or not quiet:
             msg = (
                 "Skipping .ipynb files as Jupyter dependencies are not installed.\n"
-                "You can fix this by running ``pip install black[jupyter]``"
+                'You can fix this by running ``pip install "black[jupyter]"``'
             )
             out(msg)
         return False
diff --git a/tests/test_no_ipynb.py b/tests/test_no_ipynb.py
index 3e0b1593bf0..b63ecde8896 100644
--- a/tests/test_no_ipynb.py
+++ b/tests/test_no_ipynb.py
@@ -17,7 +17,7 @@ def test_ipynb_diff_with_no_change_single() -> None:
     result = runner.invoke(main, [str(path)])
     expected_output = (
         "Skipping .ipynb files as Jupyter dependencies are not installed.\n"
-        "You can fix this by running ``pip install black[jupyter]``\n"
+        'You can fix this by running ``pip install "black[jupyter]"``\n'
     )
     assert expected_output in result.output
 
@@ -32,6 +32,6 @@ def test_ipynb_diff_with_no_change_dir(tmp_path: pathlib.Path) -> None:
     result = runner.invoke(main, [str(tmp_path)])
     expected_output = (
         "Skipping .ipynb files as Jupyter dependencies are not installed.\n"
-        "You can fix this by running ``pip install black[jupyter]``\n"
+        'You can fix this by running ``pip install "black[jupyter]"``\n'
     )
     assert expected_output in result.output

From 5f0dc862f5bbfc8abed3f29d76325404eb4f99c0 Mon Sep 17 00:00:00 2001
From: mainj12 <118842653+mainj12@users.noreply.github.com>
Date: Sat, 10 Dec 2022 20:56:14 +0000
Subject: [PATCH 0667/1034] Adding pyproject.toml configuration output to
 verbose logging (#3392)

---
 CHANGES.md            | 3 +++
 src/black/__init__.py | 3 +++
 2 files changed, 6 insertions(+)

diff --git a/CHANGES.md b/CHANGES.md
index c84feb04934..e781cbd523e 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -36,6 +36,9 @@
 
 <!-- Changes to Black's terminal output and error messages -->
 
+- Verbose logging now shows the values of `pyproject.toml` configuration variables
+  (#3392)
+
 ### _Blackd_
 
 <!-- Changes to blackd -->
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 39d12968c4b..f00749aaed8 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -511,6 +511,9 @@ def main(  # noqa: C901
                 out("Using configuration from project root.", fg="blue")
             else:
                 out(f"Using configuration in '{config}'.", fg="blue")
+            if ctx.default_map:
+                for param, value in ctx.default_map.items():
+                    out(f"{param}: {value}")
 
     error_msg = "Oh no! 💥 💔 💥"
     if (

From 80de2372e4ec385c082c38f365414ac3622a4010 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Sat, 10 Dec 2022 15:56:34 -0500
Subject: [PATCH 0668/1034] Bump mypy[c] from 0.971 to 0.991 (#3380)

---
 .pre-commit-config.yaml | 2 +-
 CHANGES.md              | 3 +++
 pyproject.toml          | 2 +-
 3 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 0be8dc42890..2d5ac26b629 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -38,7 +38,7 @@ repos:
           - flake8-simplify
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v0.971
+    rev: v0.991
     hooks:
       - id: mypy
         exclude: ^docs/conf.py
diff --git a/CHANGES.md b/CHANGES.md
index e781cbd523e..86d44f033b8 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -24,6 +24,9 @@
 
 <!-- Changes to how Black is packaged, such as dependency requirements -->
 
+- Upgrade mypyc from `0.971` to `0.991` so mypycified _Black_ can be built on armv7
+  (#3380)
+
 ### Parser
 
 <!-- Changes to the parser or to version autodetection -->
diff --git a/pyproject.toml b/pyproject.toml
index 329adaa65d8..aede497e2af 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -119,7 +119,7 @@ sources = ["src"]
 enable-by-default = false
 dependencies = [
   "hatch-mypyc>=0.13.0",
-  "mypy==0.971",
+  "mypy==0.991",
   # Required stubs to be removed when the packages support PEP 561 themselves
   "types-typed-ast>=1.4.2",
 ]

From 9bbe11dd7baf7aea23a5b51d7daf9e12acb3b28c Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 12 Dec 2022 06:27:18 -0800
Subject: [PATCH 0669/1034] Bump pypa/cibuildwheel from 2.11.2 to 2.11.3
 (#3434)

Bumps [pypa/cibuildwheel](https://github.com/pypa/cibuildwheel) from 2.11.2 to 2.11.3.
- [Release notes](https://github.com/pypa/cibuildwheel/releases)
- [Changelog](https://github.com/pypa/cibuildwheel/blob/main/docs/changelog.md)
- [Commits](https://github.com/pypa/cibuildwheel/compare/v2.11.2...v2.11.3)

---
updated-dependencies:
- dependency-name: pypa/cibuildwheel
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/pypi_upload.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/pypi_upload.yml b/.github/workflows/pypi_upload.yml
index 16cf90bd206..7fd760ef727 100644
--- a/.github/workflows/pypi_upload.yml
+++ b/.github/workflows/pypi_upload.yml
@@ -59,7 +59,7 @@ jobs:
       - uses: actions/checkout@v3
 
       - name: Build wheels via cibuildwheel
-        uses: pypa/cibuildwheel@v2.11.2
+        uses: pypa/cibuildwheel@v2.11.3
         env:
           CIBW_ARCHS_MACOS: "${{ matrix.macos_arch }}"
 

From abd2b2556a8f9d8efe8914c23520eef7223e2a99 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 12 Dec 2022 06:28:12 -0800
Subject: [PATCH 0670/1034] Bump furo from 2022.9.29 to 2022.12.7 in /docs
 (#3433)

Bumps [furo](https://github.com/pradyunsg/furo) from 2022.9.29 to 2022.12.7.
- [Release notes](https://github.com/pradyunsg/furo/releases)
- [Changelog](https://github.com/pradyunsg/furo/blob/main/docs/changelog.md)
- [Commits](https://github.com/pradyunsg/furo/compare/2022.09.29...2022.12.07)

---
updated-dependencies:
- dependency-name: furo
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 docs/requirements.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index 426a78a7abf..9a269d02a75 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -6,4 +6,4 @@ Sphinx==5.3.0
 docutils==0.19
 sphinxcontrib-programoutput==0.17
 sphinx_copybutton==0.5.1
-furo==2022.9.29
+furo==2022.12.7

From 7d062ecd5f14124a99daf452c46054ada656ad8b Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Mon, 12 Dec 2022 20:56:38 -0800
Subject: [PATCH 0671/1034] Do not put the closing quotes in a docstring on a
 separate line (#3430)

Fixes #3320. Followup from #3044.
---
 CHANGES.md                              |  2 ++
 src/black/linegen.py                    | 13 ++++++-------
 tests/data/preview/docstring_preview.py |  6 ++----
 3 files changed, 10 insertions(+), 11 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 86d44f033b8..f6040359623 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -15,6 +15,8 @@
 <!-- Changes that affect Black's preview style -->
 
 - Fix a crash in preview style with assert + parenthesized string (#3415)
+- Do not put the closing quotes in a docstring on a separate line, even if the line is
+  too long (#3430)
 
 ### Configuration
 
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 219495e9a5e..644824a3c86 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -389,19 +389,18 @@ def visit_STRING(self, leaf: Leaf) -> Iterator[Line]:
                 # We need to find the length of the last line of the docstring
                 # to find if we can add the closing quotes to the line without
                 # exceeding the maximum line length.
-                # If docstring is one line, then we need to add the length
-                # of the indent, prefix, and starting quotes. Ending quotes are
-                # handled later.
+                # If docstring is one line, we don't put the closing quotes on a
+                # separate line because it looks ugly (#3320).
                 lines = docstring.splitlines()
                 last_line_length = len(lines[-1]) if docstring else 0
 
-                if len(lines) == 1:
-                    last_line_length += len(indent) + len(prefix) + quote_len
-
                 # If adding closing quotes would cause the last line to exceed
                 # the maximum line length then put a line break before the
                 # closing quotes
-                if last_line_length + quote_len > self.mode.line_length:
+                if (
+                    len(lines) > 1
+                    and last_line_length + quote_len > self.mode.line_length
+                ):
                     leaf.value = prefix + quote + docstring + "\n" + indent + quote
                 else:
                     leaf.value = prefix + quote + docstring + quote
diff --git a/tests/data/preview/docstring_preview.py b/tests/data/preview/docstring_preview.py
index 292352c82f3..ff4819acb67 100644
--- a/tests/data/preview/docstring_preview.py
+++ b/tests/data/preview/docstring_preview.py
@@ -54,13 +54,11 @@ def single_quote_docstring_over_line_limit2():
 
 
 def docstring_almost_at_line_limit():
-    """long docstring.................................................................
-    """
+    """long docstring................................................................."""
 
 
 def docstring_almost_at_line_limit_with_prefix():
-    f"""long docstring................................................................
-    """
+    f"""long docstring................................................................"""
 
 
 def mulitline_docstring_almost_at_line_limit():

From a2821815af5f5a706c673279d6405e286d6e95b8 Mon Sep 17 00:00:00 2001
From: "Yilei \"Dolee\" Yang" <yileiyang@google.com>
Date: Wed, 14 Dec 2022 17:56:14 -0800
Subject: [PATCH 0672/1034] Fix a crash when a colon line is marked between `#
 fmt: off` and `# fmt: on` (#3439)

---
 CHANGES.md                           |  2 ++
 src/black/comments.py                | 12 +++++++++++-
 tests/data/simple_cases/fmtonoff5.py | 22 ++++++++++++++++++++--
 3 files changed, 33 insertions(+), 3 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index f6040359623..1a7c320baf8 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -10,6 +10,8 @@
 
 <!-- Changes that affect Black's stable style -->
 
+- Fix a crash when a colon line is marked between `# fmt: off` and `# fmt: on` (#3439)
+
 ### Preview style
 
 <!-- Changes that affect Black's preview style -->
diff --git a/src/black/comments.py b/src/black/comments.py
index dce83abf1bb..e733dccd844 100644
--- a/src/black/comments.py
+++ b/src/black/comments.py
@@ -232,7 +232,7 @@ def generate_ignored_nodes(
 
         # fix for fmt: on in children
         if children_contains_fmt_on(container, preview=preview):
-            for child in container.children:
+            for index, child in enumerate(container.children):
                 if isinstance(child, Leaf) and is_fmt_on(child, preview=preview):
                     if child.type in CLOSING_BRACKETS:
                         # This means `# fmt: on` is placed at a different bracket level
@@ -241,6 +241,16 @@ def generate_ignored_nodes(
                         # The alternative is to fail the formatting.
                         yield child
                     return
+                if (
+                    child.type == token.INDENT
+                    and index < len(container.children) - 1
+                    and children_contains_fmt_on(
+                        container.children[index + 1], preview=preview
+                    )
+                ):
+                    # This means `# fmt: on` is placed right after an indentation
+                    # level, and we shouldn't swallow the previous INDENT token.
+                    return
                 if children_contains_fmt_on(child, preview=preview):
                     return
                 yield child
diff --git a/tests/data/simple_cases/fmtonoff5.py b/tests/data/simple_cases/fmtonoff5.py
index 71b1381ed0d..181151b6bd6 100644
--- a/tests/data/simple_cases/fmtonoff5.py
+++ b/tests/data/simple_cases/fmtonoff5.py
@@ -64,7 +64,7 @@ async def call(param):
         print ( "This will be formatted" )
 
 
-# Regression test for https://github.com/psf/black/issues/2985
+# Regression test for https://github.com/psf/black/issues/2985.
 class Named(t.Protocol):
     # fmt: off
     @property
@@ -75,6 +75,15 @@ def  this_will_be_formatted ( self, **kwargs ) -> Named: ...
     # fmt: on
 
 
+# Regression test for https://github.com/psf/black/issues/3436.
+if x:
+    return x
+# fmt: off
+elif   unformatted:
+# fmt: on
+    will_be_formatted  ()
+
+
 # output
 
 
@@ -144,7 +153,7 @@ async def call(param):
         print("This will be formatted")
 
 
-# Regression test for https://github.com/psf/black/issues/2985
+# Regression test for https://github.com/psf/black/issues/2985.
 class Named(t.Protocol):
     # fmt: off
     @property
@@ -156,3 +165,12 @@ def this_will_be_formatted(self, **kwargs) -> Named:
         ...
 
     # fmt: on
+
+
+# Regression test for https://github.com/psf/black/issues/3436.
+if x:
+    return x
+# fmt: off
+elif   unformatted:
+    # fmt: on
+    will_be_formatted()

From 658c8d8d96047c5ba77be4aecc2545a22d5e35b9 Mon Sep 17 00:00:00 2001
From: "Yilei \"Dolee\" Yang" <hi@mangoumbrella.com>
Date: Thu, 15 Dec 2022 08:25:28 -0800
Subject: [PATCH 0673/1034] Improve long values in dict literals (#3440)

---
 CHANGES.md                                    |  3 ++
 src/black/linegen.py                          | 17 ++++++
 src/black/mode.py                             |  3 ++
 src/black/trans.py                            | 36 ++++++++++---
 tests/data/preview/long_dict_values.py        | 53 +++++++++++++++++++
 tests/data/preview/long_strings.py            | 28 ++++++++--
 .../data/preview/long_strings__regression.py  | 15 ++++++
 7 files changed, 145 insertions(+), 10 deletions(-)
 create mode 100644 tests/data/preview/long_dict_values.py

diff --git a/CHANGES.md b/CHANGES.md
index 1a7c320baf8..03c7a286771 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -19,6 +19,9 @@
 - Fix a crash in preview style with assert + parenthesized string (#3415)
 - Do not put the closing quotes in a docstring on a separate line, even if the line is
   too long (#3430)
+- Long values in dict literals are now wrapped in parentheses; correspondingly
+  unnecessary parentheses around short values in dict literals are now removed; long
+  string lambda values are now wrapped in parentheses (#3440)
 
 ### Configuration
 
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 644824a3c86..244dbe77eb5 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -179,6 +179,23 @@ def visit_stmt(
 
             yield from self.visit(child)
 
+    def visit_dictsetmaker(self, node: Node) -> Iterator[Line]:
+        if Preview.wrap_long_dict_values_in_parens in self.mode:
+            for i, child in enumerate(node.children):
+                if i == 0:
+                    continue
+                if node.children[i - 1].type == token.COLON:
+                    if child.type == syms.atom and child.children[0].type == token.LPAR:
+                        if maybe_make_parens_invisible_in_atom(
+                            child,
+                            parent=node,
+                            remove_brackets_around_comma=False,
+                        ):
+                            wrap_in_parentheses(node, child, visible=False)
+                    else:
+                        wrap_in_parentheses(node, child, visible=False)
+        yield from self.visit_default(node)
+
     def visit_funcdef(self, node: Node) -> Iterator[Line]:
         """Visit function definition."""
         if Preview.annotation_parens not in self.mode:
diff --git a/src/black/mode.py b/src/black/mode.py
index a3ce20b8619..bcd35b4d4be 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -157,8 +157,11 @@ class Preview(Enum):
     one_element_subscript = auto()
     remove_block_trailing_newline = auto()
     remove_redundant_parens = auto()
+    # NOTE: string_processing requires wrap_long_dict_values_in_parens
+    # for https://github.com/psf/black/issues/3117 to be fixed.
     string_processing = auto()
     skip_magic_trailing_comma_in_subscript = auto()
+    wrap_long_dict_values_in_parens = auto()
 
 
 class Deprecated(UserWarning):
diff --git a/src/black/trans.py b/src/black/trans.py
index 8893ab02aab..b08a6d243d8 100644
--- a/src/black/trans.py
+++ b/src/black/trans.py
@@ -1638,6 +1638,8 @@ class StringParenWrapper(BaseStringSplitter, CustomSplitMapMixin):
         * The line is a dictionary key assignment where some valid key is being
         assigned the value of some string.
             OR
+        * The line is an lambda expression and the value is a string.
+            OR
         * The line starts with an "atom" string that prefers to be wrapped in
         parens. It's preferred to be wrapped when the string is surrounded by
         commas (or is the first/last child).
@@ -1683,7 +1685,7 @@ def do_splitter_match(self, line: Line) -> TMatchResult:
             or self._else_match(LL)
             or self._assert_match(LL)
             or self._assign_match(LL)
-            or self._dict_match(LL)
+            or self._dict_or_lambda_match(LL)
             or self._prefer_paren_wrap_match(LL)
         )
 
@@ -1841,22 +1843,23 @@ def _assign_match(LL: List[Leaf]) -> Optional[int]:
         return None
 
     @staticmethod
-    def _dict_match(LL: List[Leaf]) -> Optional[int]:
+    def _dict_or_lambda_match(LL: List[Leaf]) -> Optional[int]:
         """
         Returns:
             string_idx such that @LL[string_idx] is equal to our target (i.e.
             matched) string, if this line matches the dictionary key assignment
-            statement requirements listed in the 'Requirements' section of this
-            classes' docstring.
+            statement or lambda expression requirements listed in the
+            'Requirements' section of this classes' docstring.
                 OR
             None, otherwise.
         """
-        # If this line is apart of a dictionary key assignment...
-        if syms.dictsetmaker in [parent_type(LL[0]), parent_type(LL[0].parent)]:
+        # If this line is a part of a dictionary key assignment or lambda expression...
+        parent_types = [parent_type(LL[0]), parent_type(LL[0].parent)]
+        if syms.dictsetmaker in parent_types or syms.lambdef in parent_types:
             is_valid_index = is_valid_index_factory(LL)
 
             for i, leaf in enumerate(LL):
-                # We MUST find a colon...
+                # We MUST find a colon, it can either be dict's or lambda's colon...
                 if leaf.type == token.COLON:
                     idx = i + 2 if is_empty_par(LL[i + 1]) else i + 1
 
@@ -1951,6 +1954,25 @@ def do_transform(self, line: Line, string_idx: int) -> Iterator[TResult[Line]]:
                     f" (left_leaves={left_leaves}, right_leaves={right_leaves})"
                 )
                 old_rpar_leaf = right_leaves.pop()
+            elif right_leaves and right_leaves[-1].type == token.RPAR:
+                # Special case for lambda expressions as dict's value, e.g.:
+                #     my_dict = {
+                #        "key": lambda x: f"formatted: {x},
+                #     }
+                # After wrapping the dict's value with parentheses, the string is
+                # followed by a RPAR but its opening bracket is lambda's, not
+                # the string's:
+                #        "key": (lambda x: f"formatted: {x}),
+                opening_bracket = right_leaves[-1].opening_bracket
+                if opening_bracket is not None and opening_bracket in left_leaves:
+                    index = left_leaves.index(opening_bracket)
+                    if (
+                        index > 0
+                        and index < len(left_leaves) - 1
+                        and left_leaves[index - 1].type == token.COLON
+                        and left_leaves[index + 1].value == "lambda"
+                    ):
+                        right_leaves.pop()
 
             append_leaves(string_line, line, right_leaves)
 
diff --git a/tests/data/preview/long_dict_values.py b/tests/data/preview/long_dict_values.py
new file mode 100644
index 00000000000..f23c5d3dad1
--- /dev/null
+++ b/tests/data/preview/long_dict_values.py
@@ -0,0 +1,53 @@
+my_dict = {
+    "something_something":
+        r"Lorem ipsum dolor sit amet, an sed convenire eloquentiam \t"
+        r"signiferumque, duo ea vocibus consetetur scriptorem. Facer \t"
+        r"signiferumque, duo ea vocibus consetetur scriptorem. Facer \t",
+}
+
+my_dict = {
+    "a key in my dict": a_very_long_variable * and_a_very_long_function_call() / 100000.0
+}
+
+my_dict = {
+    "a key in my dict": a_very_long_variable * and_a_very_long_function_call() * and_another_long_func() / 100000.0
+}
+
+my_dict = {
+    "a key in my dict": MyClass.some_attribute.first_call().second_call().third_call(some_args="some value")
+}
+
+
+# output
+
+
+my_dict = {
+    "something_something": (
+        r"Lorem ipsum dolor sit amet, an sed convenire eloquentiam \t"
+        r"signiferumque, duo ea vocibus consetetur scriptorem. Facer \t"
+        r"signiferumque, duo ea vocibus consetetur scriptorem. Facer \t"
+    ),
+}
+
+my_dict = {
+    "a key in my dict": (
+        a_very_long_variable * and_a_very_long_function_call() / 100000.0
+    )
+}
+
+my_dict = {
+    "a key in my dict": (
+        a_very_long_variable
+        * and_a_very_long_function_call()
+        * and_another_long_func()
+        / 100000.0
+    )
+}
+
+my_dict = {
+    "a key in my dict": (
+        MyClass.some_attribute.first_call()
+        .second_call()
+        .third_call(some_args="some value")
+    )
+}
diff --git a/tests/data/preview/long_strings.py b/tests/data/preview/long_strings.py
index 9288b253b60..9c78f675b8f 100644
--- a/tests/data/preview/long_strings.py
+++ b/tests/data/preview/long_strings.py
@@ -278,6 +278,15 @@ def foo():
     "........................................................................... \\N{LAO KO LA}"
 )
 
+msg = lambda x: f"this is a very very very long lambda value {x} that doesn't fit on a single line"
+
+dict_with_lambda_values = {
+    "join": lambda j: (
+        f"{j.__class__.__name__}({some_function_call(j.left)}, "
+        f"{some_function_call(j.right)})"
+    ),
+}
+
 
 # output
 
@@ -362,9 +371,8 @@ def foo():
     "A %s %s"
     % ("formatted", "string"): (
         "This is a really really really long string that has to go inside of a"
-        " dictionary. It is %s bad (#%d)."
-    )
-    % ("soooo", 2),
+        " dictionary. It is %s bad (#%d)." % ("soooo", 2)
+    ),
 }
 
 D5 = {  # Test for https://github.com/psf/black/issues/3261
@@ -806,3 +814,17 @@ def foo():
     "..........................................................................."
     " \\N{LAO KO LA}"
 )
+
+msg = (
+    lambda x: (
+        f"this is a very very very long lambda value {x} that doesn't fit on a single"
+        " line"
+    )
+)
+
+dict_with_lambda_values = {
+    "join": lambda j: (
+        f"{j.__class__.__name__}({some_function_call(j.left)}, "
+        f"{some_function_call(j.right)})"
+    ),
+}
diff --git a/tests/data/preview/long_strings__regression.py b/tests/data/preview/long_strings__regression.py
index 8b00e76f40e..6d56dcc635d 100644
--- a/tests/data/preview/long_strings__regression.py
+++ b/tests/data/preview/long_strings__regression.py
@@ -524,6 +524,13 @@ async def foo(self):
     },
 )
 
+# Regression test for https://github.com/psf/black/issues/3117.
+some_dict = {
+    "something_something":
+        r"Lorem ipsum dolor sit amet, an sed convenire eloquentiam \t"
+        r"signiferumque, duo ea vocibus consetetur scriptorem. Facer \t",
+}
+
 
 # output
 
@@ -1178,3 +1185,11 @@ async def foo(self):
         ),
     },
 )
+
+# Regression test for https://github.com/psf/black/issues/3117.
+some_dict = {
+    "something_something": (
+        r"Lorem ipsum dolor sit amet, an sed convenire eloquentiam \t"
+        r"signiferumque, duo ea vocibus consetetur scriptorem. Facer \t"
+    ),
+}

From aafc21aa77f5c4d2ebcb833aa60faba6c2138b94 Mon Sep 17 00:00:00 2001
From: "Yilei \"Dolee\" Yang" <hi@mangoumbrella.com>
Date: Thu, 15 Dec 2022 15:58:51 -0800
Subject: [PATCH 0674/1034] Prefer splitting right hand side of assignment
 statements. (#3368)

---
 CHANGES.md                                    |   2 +
 src/black/linegen.py                          | 122 +++++++++++++++---
 src/black/mode.py                             |   1 +
 .../data/preview/long_strings__regression.py  |   6 +-
 tests/data/preview/prefer_rhs_split.py        |  85 ++++++++++++
 .../preview/prefer_rhs_split_reformatted.py   |  38 ++++++
 6 files changed, 236 insertions(+), 18 deletions(-)
 create mode 100644 tests/data/preview/prefer_rhs_split.py
 create mode 100644 tests/data/preview/prefer_rhs_split_reformatted.py

diff --git a/CHANGES.md b/CHANGES.md
index 03c7a286771..e1ad5e1f1cc 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -73,6 +73,8 @@
   present) or as a single newline character (if a newline is present) (#3348)
 - Implicitly concatenated strings used as function args are now wrapped inside
   parentheses (#3307)
+- For assignment statements, prefer splitting the right hand side if the left hand side
+  fits on a single line (#3368)
 - Correctly handle trailing commas that are inside a line's leading non-nested parens
   (#3370)
 
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 244dbe77eb5..91223747618 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -2,6 +2,7 @@
 Generating lines of code.
 """
 import sys
+from dataclasses import dataclass
 from enum import Enum, auto
 from functools import partial, wraps
 from typing import Collection, Iterator, List, Optional, Set, Union, cast
@@ -24,6 +25,7 @@
 from black.mode import Feature, Mode, Preview
 from black.nodes import (
     ASSIGNMENTS,
+    BRACKETS,
     CLOSING_BRACKETS,
     OPENING_BRACKETS,
     RARROW,
@@ -634,6 +636,17 @@ def left_hand_split(line: Line, _features: Collection[Feature] = ()) -> Iterator
             yield result
 
 
+@dataclass
+class _RHSResult:
+    """Intermediate split result from a right hand split."""
+
+    head: Line
+    body: Line
+    tail: Line
+    opening_bracket: Leaf
+    closing_bracket: Leaf
+
+
 def right_hand_split(
     line: Line,
     line_length: int,
@@ -648,6 +661,22 @@ def right_hand_split(
 
     Note: running this function modifies `bracket_depth` on the leaves of `line`.
     """
+    rhs_result = _first_right_hand_split(line, omit=omit)
+    yield from _maybe_split_omitting_optional_parens(
+        rhs_result, line, line_length, features=features, omit=omit
+    )
+
+
+def _first_right_hand_split(
+    line: Line,
+    omit: Collection[LeafID] = (),
+) -> _RHSResult:
+    """Split the line into head, body, tail starting with the last bracket pair.
+
+    Note: this function should not have side effects. It's relied upon by
+    _maybe_split_omitting_optional_parens to get an opinion whether to prefer
+    splitting on the right side of an assignment statement.
+    """
     tail_leaves: List[Leaf] = []
     body_leaves: List[Leaf] = []
     head_leaves: List[Leaf] = []
@@ -683,37 +712,71 @@ def right_hand_split(
         tail_leaves, line, opening_bracket, component=_BracketSplitComponent.tail
     )
     bracket_split_succeeded_or_raise(head, body, tail)
+    return _RHSResult(head, body, tail, opening_bracket, closing_bracket)
+
+
+def _maybe_split_omitting_optional_parens(
+    rhs: _RHSResult,
+    line: Line,
+    line_length: int,
+    features: Collection[Feature] = (),
+    omit: Collection[LeafID] = (),
+) -> Iterator[Line]:
     if (
         Feature.FORCE_OPTIONAL_PARENTHESES not in features
         # the opening bracket is an optional paren
-        and opening_bracket.type == token.LPAR
-        and not opening_bracket.value
+        and rhs.opening_bracket.type == token.LPAR
+        and not rhs.opening_bracket.value
         # the closing bracket is an optional paren
-        and closing_bracket.type == token.RPAR
-        and not closing_bracket.value
+        and rhs.closing_bracket.type == token.RPAR
+        and not rhs.closing_bracket.value
         # it's not an import (optional parens are the only thing we can split on
         # in this case; attempting a split without them is a waste of time)
         and not line.is_import
         # there are no standalone comments in the body
-        and not body.contains_standalone_comments(0)
+        and not rhs.body.contains_standalone_comments(0)
         # and we can actually remove the parens
-        and can_omit_invisible_parens(body, line_length)
+        and can_omit_invisible_parens(rhs.body, line_length)
     ):
-        omit = {id(closing_bracket), *omit}
+        omit = {id(rhs.closing_bracket), *omit}
         try:
-            yield from right_hand_split(line, line_length, features=features, omit=omit)
-            return
+            # The _RHSResult Omitting Optional Parens.
+            rhs_oop = _first_right_hand_split(line, omit=omit)
+            if not (
+                Preview.prefer_splitting_right_hand_side_of_assignments in line.mode
+                # the split is right after `=`
+                and len(rhs.head.leaves) >= 2
+                and rhs.head.leaves[-2].type == token.EQUAL
+                # the left side of assignement contains brackets
+                and any(leaf.type in BRACKETS for leaf in rhs.head.leaves[:-1])
+                # the left side of assignment is short enough (the -1 is for the ending
+                # optional paren)
+                and is_line_short_enough(rhs.head, line_length=line_length - 1)
+                # the left side of assignment won't explode further because of magic
+                # trailing comma
+                and rhs.head.magic_trailing_comma is None
+                # the split by omitting optional parens isn't preferred by some other
+                # reason
+                and not _prefer_split_rhs_oop(rhs_oop, line_length=line_length)
+            ):
+                yield from _maybe_split_omitting_optional_parens(
+                    rhs_oop, line, line_length, features=features, omit=omit
+                )
+                return
 
         except CannotSplit as e:
             if not (
-                can_be_split(body)
-                or is_line_short_enough(body, line_length=line_length)
+                can_be_split(rhs.body)
+                or is_line_short_enough(rhs.body, line_length=line_length)
             ):
                 raise CannotSplit(
                     "Splitting failed, body is still too long and can't be split."
                 ) from e
 
-            elif head.contains_multiline_strings() or tail.contains_multiline_strings():
+            elif (
+                rhs.head.contains_multiline_strings()
+                or rhs.tail.contains_multiline_strings()
+            ):
                 raise CannotSplit(
                     "The current optional pair of parentheses is bound to fail to"
                     " satisfy the splitting algorithm because the head or the tail"
@@ -721,13 +784,42 @@ def right_hand_split(
                     " line."
                 ) from e
 
-    ensure_visible(opening_bracket)
-    ensure_visible(closing_bracket)
-    for result in (head, body, tail):
+    ensure_visible(rhs.opening_bracket)
+    ensure_visible(rhs.closing_bracket)
+    for result in (rhs.head, rhs.body, rhs.tail):
         if result:
             yield result
 
 
+def _prefer_split_rhs_oop(rhs_oop: _RHSResult, line_length: int) -> bool:
+    """
+    Returns whether we should prefer the result from a split omitting optional parens.
+    """
+    has_closing_bracket_after_assign = False
+    for leaf in reversed(rhs_oop.head.leaves):
+        if leaf.type == token.EQUAL:
+            break
+        if leaf.type in CLOSING_BRACKETS:
+            has_closing_bracket_after_assign = True
+            break
+    return (
+        # contains matching brackets after the `=` (done by checking there is a
+        # closing bracket)
+        has_closing_bracket_after_assign
+        or (
+            # the split is actually from inside the optional parens (done by checking
+            # the first line still contains the `=`)
+            any(leaf.type == token.EQUAL for leaf in rhs_oop.head.leaves)
+            # the first line is short enough
+            and is_line_short_enough(rhs_oop.head, line_length=line_length)
+        )
+        # contains unsplittable type ignore
+        or rhs_oop.head.contains_unsplittable_type_ignore()
+        or rhs_oop.body.contains_unsplittable_type_ignore()
+        or rhs_oop.tail.contains_unsplittable_type_ignore()
+    )
+
+
 def bracket_split_succeeded_or_raise(head: Line, body: Line, tail: Line) -> None:
     """Raise :exc:`CannotSplit` if the last left- or right-hand split failed.
 
diff --git a/src/black/mode.py b/src/black/mode.py
index bcd35b4d4be..a104d1b9862 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -155,6 +155,7 @@ class Preview(Enum):
     long_docstring_quotes_on_newline = auto()
     normalize_docstring_quotes_and_prefixes_properly = auto()
     one_element_subscript = auto()
+    prefer_splitting_right_hand_side_of_assignments = auto()
     remove_block_trailing_newline = auto()
     remove_redundant_parens = auto()
     # NOTE: string_processing requires wrap_long_dict_values_in_parens
diff --git a/tests/data/preview/long_strings__regression.py b/tests/data/preview/long_strings__regression.py
index 6d56dcc635d..8b8fc179147 100644
--- a/tests/data/preview/long_strings__regression.py
+++ b/tests/data/preview/long_strings__regression.py
@@ -983,9 +983,9 @@ def xxxxxxx_xxxxxx(xxxx):
         )
 
 
-value.__dict__[
-    key
-] = "test"  # set some Thrift field to non-None in the struct aa bb cc dd ee
+value.__dict__[key] = (
+    "test"  # set some Thrift field to non-None in the struct aa bb cc dd ee
+)
 
 RE_ONE_BACKSLASH = {
     "asdf_hjkl_jkl": re.compile(
diff --git a/tests/data/preview/prefer_rhs_split.py b/tests/data/preview/prefer_rhs_split.py
new file mode 100644
index 00000000000..5b89113e618
--- /dev/null
+++ b/tests/data/preview/prefer_rhs_split.py
@@ -0,0 +1,85 @@
+first_item, second_item = (
+    some_looooooooong_module.some_looooooooooooooong_function_name(
+        first_argument, second_argument, third_argument
+    )
+)
+
+some_dict["with_a_long_key"] = (
+    some_looooooooong_module.some_looooooooooooooong_function_name(
+        first_argument, second_argument, third_argument
+    )
+)
+
+# Make sure it works when the RHS only has one pair of (optional) parens.
+first_item, second_item = (
+    some_looooooooong_module.SomeClass.some_looooooooooooooong_variable_name
+)
+
+some_dict["with_a_long_key"] = (
+    some_looooooooong_module.SomeClass.some_looooooooooooooong_variable_name
+)
+
+# Make sure chaining assignments work.
+first_item, second_item, third_item, forth_item = m["everything"] = (
+    some_looooooooong_module.some_looooooooooooooong_function_name(
+        first_argument, second_argument, third_argument
+    )
+)
+
+# Make sure when the RHS's first split at the non-optional paren fits,
+# we split there instead of the outer RHS optional paren.
+first_item, second_item = some_looooooooong_module.some_loooooog_function_name(
+    first_argument, second_argument, third_argument
+)
+
+(
+    first_item,
+    second_item,
+    third_item,
+    forth_item,
+    fifth_item,
+    last_item_very_loooooong,
+) = some_looooooooong_module.some_looooooooooooooong_function_name(
+    first_argument, second_argument, third_argument
+)
+
+(
+    first_item,
+    second_item,
+    third_item,
+    forth_item,
+    fifth_item,
+    last_item_very_loooooong,
+) = everyting = some_loooooog_function_name(
+    first_argument, second_argument, third_argument
+)
+
+
+# Make sure unsplittable type ignore won't be moved.
+some_kind_of_table[some_key] = util.some_function(  # type: ignore  # noqa: E501
+    some_arg
+).intersection(pk_cols)
+
+some_kind_of_table[
+    some_key
+] = lambda obj: obj.some_long_named_method()  # type: ignore  # noqa: E501
+
+some_kind_of_table[
+    some_key  # type: ignore  # noqa: E501
+] = lambda obj: obj.some_long_named_method()
+
+
+# Make when when the left side of assignement plus the opening paren "... = (" is
+# exactly line length limit + 1, it won't be split like that.
+xxxxxxxxx_yyy_zzzzzzzz[
+    xx.xxxxxx(x_yyy_zzzzzz.xxxxx[0]), x_yyy_zzzzzz.xxxxxx(xxxx=1)
+] = 1
+
+
+# Right side of assignment contains un-nested pairs of inner parens.
+some_kind_of_instance.some_kind_of_map[a_key] = (
+    isinstance(some_var, SomeClass)
+    and table.something_and_something != table.something_else
+) or (
+    isinstance(some_other_var, BaseClass) and table.something != table.some_other_thing
+)
diff --git a/tests/data/preview/prefer_rhs_split_reformatted.py b/tests/data/preview/prefer_rhs_split_reformatted.py
new file mode 100644
index 00000000000..781e75be0aa
--- /dev/null
+++ b/tests/data/preview/prefer_rhs_split_reformatted.py
@@ -0,0 +1,38 @@
+# Test cases separate from `prefer_rhs_split.py` that contains unformatted source.
+
+# Left hand side fits in a single line but will still be exploded by the
+# magic trailing comma.
+first_value, (m1, m2,), third_value = xxxxxx_yyyyyy_zzzzzz_wwwwww_uuuuuuu_vvvvvvvvvvv(
+    arg1,
+    arg2,
+)
+
+# Make when when the left side of assignement plus the opening paren "... = (" is
+# exactly line length limit + 1, it won't be split like that.
+xxxxxxxxx_yyy_zzzzzzzz[xx.xxxxxx(x_yyy_zzzzzz.xxxxx[0]), x_yyy_zzzzzz.xxxxxx(xxxx=1)] = 1
+
+
+# output
+
+
+# Test cases separate from `prefer_rhs_split.py` that contains unformatted source.
+
+# Left hand side fits in a single line but will still be exploded by the
+# magic trailing comma.
+(
+    first_value,
+    (
+        m1,
+        m2,
+    ),
+    third_value,
+) = xxxxxx_yyyyyy_zzzzzz_wwwwww_uuuuuuu_vvvvvvvvvvv(
+    arg1,
+    arg2,
+)
+
+# Make when when the left side of assignement plus the opening paren "... = (" is
+# exactly line length limit + 1, it won't be split like that.
+xxxxxxxxx_yyy_zzzzzzzz[
+    xx.xxxxxx(x_yyy_zzzzzz.xxxxx[0]), x_yyy_zzzzzz.xxxxxx(xxxx=1)
+] = 1

From 78163939f157d9e18a8c0528fc5e1c58b1c1e69c Mon Sep 17 00:00:00 2001
From: "Yilei \"Dolee\" Yang" <yileiyang@google.com>
Date: Fri, 16 Dec 2022 05:02:41 -0800
Subject: [PATCH 0675/1034] Fix an infinite recursion error exposed by #3440
 (#3444)

---
 src/black/linegen.py                   |  6 +++--
 tests/data/preview/long_dict_values.py | 37 ++++++++++++++++++++++++++
 2 files changed, 41 insertions(+), 2 deletions(-)

diff --git a/src/black/linegen.py b/src/black/linegen.py
index 91223747618..fe6ea11c501 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -1417,8 +1417,10 @@ def run_transformer(
 
         result.extend(transform_line(transformed_line, mode=mode, features=features))
 
+    features_set = set(features)
     if (
-        transform.__class__.__name__ != "rhs"
+        Feature.FORCE_OPTIONAL_PARENTHESES in features_set
+        or transform.__class__.__name__ != "rhs"
         or not line.bracket_tracker.invisible
         or any(bracket.value for bracket in line.bracket_tracker.invisible)
         or line.contains_multiline_strings()
@@ -1435,7 +1437,7 @@ def run_transformer(
 
     line_copy = line.clone()
     append_leaves(line_copy, line, line.leaves)
-    features_fop = set(features) | {Feature.FORCE_OPTIONAL_PARENTHESES}
+    features_fop = features_set | {Feature.FORCE_OPTIONAL_PARENTHESES}
     second_opinion = run_transformer(
         line_copy, transform, mode, features_fop, line_str=line_str
     )
diff --git a/tests/data/preview/long_dict_values.py b/tests/data/preview/long_dict_values.py
index f23c5d3dad1..4c515180028 100644
--- a/tests/data/preview/long_dict_values.py
+++ b/tests/data/preview/long_dict_values.py
@@ -17,6 +17,24 @@
     "a key in my dict": MyClass.some_attribute.first_call().second_call().third_call(some_args="some value")
 }
 
+{
+    'xxxxxx':
+        xxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxx(
+            xxxxxxxxxxxxxx={
+                'x':
+                    xxxxxxxxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxx(
+                        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=(
+                            xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+                            .xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx(
+                                xxxxxxxxxxxxx=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+                                .xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx(
+                                    xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx={
+                                        'x': x.xx,
+                                        'x': x.x,
+                                    }))))
+            }),
+}
+
 
 # output
 
@@ -51,3 +69,22 @@
         .third_call(some_args="some value")
     )
 }
+
+{
+    "xxxxxx": xxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxx(
+        xxxxxxxxxxxxxx={
+            "x": xxxxxxxxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxx(
+                xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=(
+                    xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx(
+                        xxxxxxxxxxxxx=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx(
+                            xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx={
+                                "x": x.xx,
+                                "x": x.x,
+                            }
+                        )
+                    )
+                )
+            )
+        }
+    ),
+}

From c0089ef19dd12f872c581f106b1236c46d609955 Mon Sep 17 00:00:00 2001
From: Cooper Lees <cooper@fb.com>
Date: Sat, 17 Dec 2022 09:19:45 -0800
Subject: [PATCH 0676/1034] Remove separate 3.11 CI now deps support 3.11
 (#3446)

* Remove separate 3.11 CI now deps support 3.11

- We can run everything now like all other stable versions of Python
- test in a 3.11 vent: `/tmp/tb/bin/tox -e py311,ci-py311`

```
  py311: OK (28.99=setup[7.90]+cmd[5.29,0.66,6.94,6.08,1.89,0.24] seconds)
  ci-py311: OK (30.33=setup[3.20]+cmd[3.66,0.31,17.43,4.60,0.90,0.23] seconds)
  congratulations :) (59.35 seconds)
```

* Add to CHANGES.md

* Add fuzz run in 3.11
---
 .github/workflows/fuzz.yml     |  2 +-
 .github/workflows/test-311.yml | 57 ----------------------------------
 .github/workflows/test.yml     |  2 +-
 CHANGES.md                     |  2 ++
 4 files changed, 4 insertions(+), 59 deletions(-)
 delete mode 100644 .github/workflows/test-311.yml

diff --git a/.github/workflows/fuzz.yml b/.github/workflows/fuzz.yml
index ebb8a9fda9e..373e1500ee9 100644
--- a/.github/workflows/fuzz.yml
+++ b/.github/workflows/fuzz.yml
@@ -22,7 +22,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.7", "3.8", "3.9", "3.10"]
+        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11"]
 
     steps:
       - uses: actions/checkout@v3
diff --git a/.github/workflows/test-311.yml b/.github/workflows/test-311.yml
deleted file mode 100644
index c2da2465ad5..00000000000
--- a/.github/workflows/test-311.yml
+++ /dev/null
@@ -1,57 +0,0 @@
-name: Test 3.11 without aiohttp extensions
-
-on:
-  push:
-    paths-ignore:
-      - "docs/**"
-      - "*.md"
-
-  pull_request:
-    paths-ignore:
-      - "docs/**"
-      - "*.md"
-
-permissions:
-  contents: read
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.run_id }}
-  cancel-in-progress: true
-
-jobs:
-  main:
-    # We want to run on external PRs, but not on our own internal PRs as they'll be run
-    # by the push to the branch. Without this if check, checks are duplicated since
-    # internal PRs match both the push and pull_request events.
-    if:
-      github.event_name == 'push' || github.event.pull_request.head.repo.full_name !=
-      github.repository
-
-    runs-on: ${{ matrix.os }}
-    strategy:
-      fail-fast: false
-      matrix:
-        python-version: ["3.11.0-rc - 3.11"]
-        os: [ubuntu-latest, macOS-latest, windows-latest]
-
-    steps:
-      - uses: actions/checkout@v3
-
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
-        with:
-          python-version: ${{ matrix.python-version }}
-
-      - name: Install tox
-        run: |
-          python -m pip install --upgrade pip
-          python -m pip install --upgrade tox
-
-      - name: Run tests via tox
-        run: |
-          python -m tox -e 311
-
-      - name: Format ourselves
-        run: |
-          python -m pip install .
-          python -m black --check src/
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 372d1fd5d38..3ca2a469147 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -31,7 +31,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.7", "3.8", "3.9", "3.10", "pypy-3.7", "pypy-3.8"]
+        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11", "pypy-3.7", "pypy-3.8"]
         os: [ubuntu-latest, macOS-latest, windows-latest]
 
     steps:
diff --git a/CHANGES.md b/CHANGES.md
index e1ad5e1f1cc..ba71ee6c99d 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -57,6 +57,8 @@
 
 <!-- For example, Docker, GitHub Actions, pre-commit, editors -->
 
+- Move 3.11 CI to normal flow now all dependencies support 3.11 (#3446)
+
 ### Documentation
 
 <!-- Major changes to documentation and policies. Small docs changes

From 159984a7351bfc4789bc0fc85b5f408112efca85 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Sat, 17 Dec 2022 10:31:47 -0800
Subject: [PATCH 0677/1034] Check stability for both preview and non-preview
 styles (#3423)

And fix parens-related test failures this found.

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 CHANGES.md                                   |  2 +
 src/black/linegen.py                         |  2 +
 tests/data/py_310/pattern_matching_extras.py |  2 +-
 tests/util.py                                | 54 +++++++++++++++++++-
 4 files changed, 57 insertions(+), 3 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index ba71ee6c99d..50c0f5df050 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -17,6 +17,8 @@
 <!-- Changes that affect Black's preview style -->
 
 - Fix a crash in preview style with assert + parenthesized string (#3415)
+- Fix crashes in preview style with walrus operators used in function return annotations
+  and except clauses (#3423)
 - Do not put the closing quotes in a docstring on a separate line, even if the line is
   too long (#3430)
 - Long values in dict literals are now wrapped in parentheses; correspondingly
diff --git a/src/black/linegen.py b/src/black/linegen.py
index fe6ea11c501..2e75bc94506 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -1268,6 +1268,8 @@ def maybe_make_parens_invisible_in_atom(
             syms.expr_stmt,
             syms.assert_stmt,
             syms.return_stmt,
+            syms.except_clause,
+            syms.funcdef,
             # these ones aren't useful to end users, but they do please fuzzers
             syms.for_stmt,
             syms.del_stmt,
diff --git a/tests/data/py_310/pattern_matching_extras.py b/tests/data/py_310/pattern_matching_extras.py
index 9f6907f7575..0242d264e5b 100644
--- a/tests/data/py_310/pattern_matching_extras.py
+++ b/tests/data/py_310/pattern_matching_extras.py
@@ -114,6 +114,6 @@ def func(match: case, case: match) -> case:
 
 match bar1:
     case Foo(
-        normal=x, perhaps=[list, {an: d, dict: 1.0}] as y, otherwise=something, q=t as u
+        normal=x, perhaps=[list, {"x": d, "y": 1.0}] as y, otherwise=something, q=t as u
     ):
         pass
diff --git a/tests/util.py b/tests/util.py
index d65c2e651ae..967d576fafe 100644
--- a/tests/util.py
+++ b/tests/util.py
@@ -2,6 +2,7 @@
 import sys
 import unittest
 from contextlib import contextmanager
+from dataclasses import replace
 from functools import partial
 from pathlib import Path
 from typing import Any, Iterator, List, Optional, Tuple
@@ -56,6 +57,10 @@ def _assert_format_equal(expected: str, actual: str) -> None:
     assert actual == expected
 
 
+class FormatFailure(Exception):
+    """Used to wrap failures when assert_format() runs in an extra mode."""
+
+
 def assert_format(
     source: str,
     expected: str,
@@ -70,12 +75,57 @@ def assert_format(
     safety guards so they don't just crash with a SyntaxError. Please note this is
     separate from TargetVerson Mode configuration.
     """
+    _assert_format_inner(
+        source, expected, mode, fast=fast, minimum_version=minimum_version
+    )
+
+    # For both preview and non-preview tests, ensure that Black doesn't crash on
+    # this code, but don't pass "expected" because the precise output may differ.
+    try:
+        _assert_format_inner(
+            source,
+            None,
+            replace(mode, preview=not mode.preview),
+            fast=fast,
+            minimum_version=minimum_version,
+        )
+    except Exception as e:
+        text = "non-preview" if mode.preview else "preview"
+        raise FormatFailure(
+            f"Black crashed formatting this case in {text} mode."
+        ) from e
+    # Similarly, setting line length to 1 is a good way to catch
+    # stability bugs. But only in non-preview mode because preview mode
+    # currently has a lot of line length 1 bugs.
+    try:
+        _assert_format_inner(
+            source,
+            None,
+            replace(mode, preview=False, line_length=1),
+            fast=fast,
+            minimum_version=minimum_version,
+        )
+    except Exception as e:
+        raise FormatFailure(
+            "Black crashed formatting this case with line-length set to 1."
+        ) from e
+
+
+def _assert_format_inner(
+    source: str,
+    expected: Optional[str] = None,
+    mode: black.Mode = DEFAULT_MODE,
+    *,
+    fast: bool = False,
+    minimum_version: Optional[Tuple[int, int]] = None,
+) -> None:
     actual = black.format_str(source, mode=mode)
-    _assert_format_equal(expected, actual)
+    if expected is not None:
+        _assert_format_equal(expected, actual)
     # It's not useful to run safety checks if we're expecting no changes anyway. The
     # assertion right above will raise if reality does actually make changes. This just
     # avoids wasted CPU cycles.
-    if not fast and source != expected:
+    if not fast and source != actual:
         # Unfortunately the AST equivalence check relies on the built-in ast module
         # being able to parse the code being formatted. This doesn't always work out
         # when checking modern code on older versions.

From 23b92b48a5e6b39d507c84839ecc0decb7f01a34 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Sat, 17 Dec 2022 14:51:10 -0800
Subject: [PATCH 0678/1034] Fix syntax error in match test (#3426)


From cd9fef8bab3a39dfba494f1917e4158faba439f9 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Sat, 17 Dec 2022 19:02:01 -0800
Subject: [PATCH 0679/1034] tomli: Don't worry about specific alpha releases
 (#3448)

This prevents bugs due to pypa/packaging#522.

Fixes #3447.
---
 CHANGES.md     | 3 +++
 pyproject.toml | 2 +-
 2 files changed, 4 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index 50c0f5df050..f786f1a1fed 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -35,6 +35,9 @@
 
 - Upgrade mypyc from `0.971` to `0.991` so mypycified _Black_ can be built on armv7
   (#3380)
+- Drop specific support for the `tomli` requirement on 3.11 alpha releases, working
+  around a bug that would cause the requirement not to be installed on any non-final
+  Python releases (#3448)
 
 ### Parser
 
diff --git a/pyproject.toml b/pyproject.toml
index aede497e2af..ab38908ba15 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -67,7 +67,7 @@ dependencies = [
   "mypy_extensions>=0.4.3",
   "pathspec>=0.9.0",
   "platformdirs>=2",
-  "tomli>=1.1.0; python_full_version < '3.11.0a7'",
+  "tomli>=1.1.0; python_version < '3.11'",
   "typed-ast>=1.4.2; python_version < '3.8' and implementation_name == 'cpython'",
   "typing_extensions>=3.10.0.0; python_version < '3.10'",
 ]

From 9ce75726fcf1f3a2617e873d925384fd6b876dcb Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Mon, 19 Dec 2022 18:08:13 -0800
Subject: [PATCH 0680/1034] Do not move docker `latest_release` tag for
 Pre-Releases (#3461)

* Do not move docker `latest_release` tag for Pre-Releases

- When we do a pre-release lets not move the latest_release tag
  - This tag should only move on official real releases

Fixes #3453

* Make it prettier - TIL we format our yaml
---
 .github/workflows/docker.yml | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
index a3106d04aae..855186f9bf1 100644
--- a/.github/workflows/docker.yml
+++ b/.github/workflows/docker.yml
@@ -44,7 +44,9 @@ jobs:
           tags: pyfound/black:latest,pyfound/black:${{ env.GIT_TAG }}
 
       - name: Build and push latest_release tag
-        if: ${{ github.event_name == 'release' && github.event.action == 'published' }}
+        if:
+          ${{ github.event_name == 'release' && github.event.action == 'published' &&
+          !github.event.release.prerelease }}
         uses: docker/build-push-action@v3
         with:
           context: .

From 1e8217fd6284bdb020e7ca70964d677a3016f914 Mon Sep 17 00:00:00 2001
From: "Yilei \"Dolee\" Yang" <yileiyang@google.com>
Date: Tue, 20 Dec 2022 06:36:42 -0800
Subject: [PATCH 0681/1034] Fix an f-string crash in ESP. (#3463)

---
 CHANGES.md                                    |  2 ++
 src/black/trans.py                            |  9 ++++--
 .../data/preview/long_strings__regression.py  | 28 +++++++++++++++++++
 3 files changed, 37 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index f786f1a1fed..61608c361cb 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -19,6 +19,8 @@
 - Fix a crash in preview style with assert + parenthesized string (#3415)
 - Fix crashes in preview style with walrus operators used in function return annotations
   and except clauses (#3423)
+- Fix a crash in preview advanced string processing where mixed implicitly concatenated
+  regular and f-strings start with an empty span (#3463)
 - Do not put the closing quotes in a docstring on a separate line, even if the line is
   too long (#3430)
 - Long values in dict literals are now wrapped in parentheses; correspondingly
diff --git a/src/black/trans.py b/src/black/trans.py
index b08a6d243d8..25d35afe74d 100644
--- a/src/black/trans.py
+++ b/src/black/trans.py
@@ -1359,9 +1359,14 @@ def more_splits_should_be_made() -> bool:
             # prefix, and the current custom split did NOT originally use a
             # prefix...
             if (
-                next_value != self._normalize_f_string(next_value, prefix)
-                and use_custom_breakpoints
+                use_custom_breakpoints
                 and not csplit.has_prefix
+                and (
+                    # `next_value == prefix + QUOTE` happens when the custom
+                    # split is an empty string.
+                    next_value == prefix + QUOTE
+                    or next_value != self._normalize_f_string(next_value, prefix)
+                )
             ):
                 # Then `csplit.break_idx` will be off by one after removing
                 # the 'f' prefix.
diff --git a/tests/data/preview/long_strings__regression.py b/tests/data/preview/long_strings__regression.py
index 8b8fc179147..5e8f012bc3e 100644
--- a/tests/data/preview/long_strings__regression.py
+++ b/tests/data/preview/long_strings__regression.py
@@ -531,6 +531,18 @@ async def foo(self):
         r"signiferumque, duo ea vocibus consetetur scriptorem. Facer \t",
 }
 
+# Regression test for https://github.com/psf/black/issues/3459.
+xxxx(
+    empty_str_as_first_split=''
+    f'xxxxxxx {xxxxxxxxxx} xxx xxxxxxxxxx xxxxx xxx xxx xx '
+    'xxxxx xxxxxxxxx xxxxxxx, xxx xxxxxxxxxxx xxx xxxxx. '
+    f'xxxxxxxxxxxxx xxxx xx xxxxxxxxxx. xxxxx: {x.xxx}',
+    empty_u_str_as_first_split=u''
+    f'xxxxxxx {xxxxxxxxxx} xxx xxxxxxxxxx xxxxx xxx xxx xx '
+    'xxxxx xxxxxxxxx xxxxxxx, xxx xxxxxxxxxxx xxx xxxxx. '
+    f'xxxxxxxxxxxxx xxxx xx xxxxxxxxxx. xxxxx: {x.xxx}',
+)
+
 
 # output
 
@@ -1193,3 +1205,19 @@ async def foo(self):
         r"signiferumque, duo ea vocibus consetetur scriptorem. Facer \t"
     ),
 }
+
+# Regression test for https://github.com/psf/black/issues/3459.
+xxxx(
+    empty_str_as_first_split=(
+        ""
+        f"xxxxxxx {xxxxxxxxxx} xxx xxxxxxxxxx xxxxx xxx xxx xx "
+        "xxxxx xxxxxxxxx xxxxxxx, xxx xxxxxxxxxxx xxx xxxxx. "
+        f"xxxxxxxxxxxxx xxxx xx xxxxxxxxxx. xxxxx: {x.xxx}"
+    ),
+    empty_u_str_as_first_split=(
+        ""
+        f"xxxxxxx {xxxxxxxxxx} xxx xxxxxxxxxx xxxxx xxx xxx xx "
+        "xxxxx xxxxxxxxx xxxxxxx, xxx xxxxxxxxxxx xxx xxxxx. "
+        f"xxxxxxxxxxxxx xxxx xx xxxxxxxxxx. xxxxx: {x.xxx}"
+    ),
+)

From a44dc3d59eb46901f9fe893727280903df41fc20 Mon Sep 17 00:00:00 2001
From: "Yilei \"Dolee\" Yang" <yileiyang@google.com>
Date: Tue, 20 Dec 2022 13:38:35 -0800
Subject: [PATCH 0682/1034] Exclude string type annotations from ESP (#3462)

---
 CHANGES.md                                    |  2 +
 src/black/brackets.py                         | 16 ++++-
 src/black/nodes.py                            | 12 ++++
 src/black/trans.py                            | 23 ++++----
 .../preview/long_strings__type_annotations.py | 59 +++++++++++++++++++
 5 files changed, 98 insertions(+), 14 deletions(-)
 create mode 100644 tests/data/preview/long_strings__type_annotations.py

diff --git a/CHANGES.md b/CHANGES.md
index 61608c361cb..c29933fe5d9 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -26,6 +26,8 @@
 - Long values in dict literals are now wrapped in parentheses; correspondingly
   unnecessary parentheses around short values in dict literals are now removed; long
   string lambda values are now wrapped in parentheses (#3440)
+- Exclude string type annotations from improved string processing; fix crash when the
+  return type annotation is stringified and spans across multiple lines (#3462)
 
 ### Configuration
 
diff --git a/src/black/brackets.py b/src/black/brackets.py
index ec9708cb08a..343f0608d50 100644
--- a/src/black/brackets.py
+++ b/src/black/brackets.py
@@ -80,9 +80,12 @@ def mark(self, leaf: Leaf) -> None:
         within brackets a given leaf is. 0 means there are no enclosing brackets
         that started on this line.
 
-        If a leaf is itself a closing bracket, it receives an `opening_bracket`
-        field that it forms a pair with. This is a one-directional link to
-        avoid reference cycles.
+        If a leaf is itself a closing bracket and there is a matching opening
+        bracket earlier, it receives an `opening_bracket` field with which it forms a
+        pair. This is a one-directional link to avoid reference cycles. Closing
+        bracket without opening happens on lines continued from previous
+        breaks, e.g. `) -> "ReturnType":` as part of a funcdef where we place
+        the return type annotation on its own line of the previous closing RPAR.
 
         If a leaf is a delimiter (a token on which Black can split the line if
         needed) and it's on depth 0, its `id()` is stored in the tracker's
@@ -91,6 +94,13 @@ def mark(self, leaf: Leaf) -> None:
         if leaf.type == token.COMMENT:
             return
 
+        if (
+            self.depth == 0
+            and leaf.type in CLOSING_BRACKETS
+            and (self.depth, leaf.type) not in self.bracket_match
+        ):
+            return
+
         self.maybe_decrement_after_for_loop_variable(leaf)
         self.maybe_decrement_after_lambda_arguments(leaf)
         if leaf.type in CLOSING_BRACKETS:
diff --git a/src/black/nodes.py b/src/black/nodes.py
index aeb2be389c8..a11fb7cc071 100644
--- a/src/black/nodes.py
+++ b/src/black/nodes.py
@@ -848,3 +848,15 @@ def is_string_token(nl: NL) -> TypeGuard[Leaf]:
 
 def is_number_token(nl: NL) -> TypeGuard[Leaf]:
     return nl.type == token.NUMBER
+
+
+def is_part_of_annotation(leaf: Leaf) -> bool:
+    """Returns whether this leaf is part of type annotations."""
+    ancestor = leaf.parent
+    while ancestor is not None:
+        if ancestor.prev_sibling and ancestor.prev_sibling.type == token.RARROW:
+            return True
+        if ancestor.parent and ancestor.parent.type == syms.tname:
+            return True
+        ancestor = ancestor.parent
+    return False
diff --git a/src/black/trans.py b/src/black/trans.py
index 25d35afe74d..a5cf4955f13 100644
--- a/src/black/trans.py
+++ b/src/black/trans.py
@@ -30,7 +30,6 @@
 
 from mypy_extensions import trait
 
-from black.brackets import BracketMatchError
 from black.comments import contains_pragma_comment
 from black.lines import Line, append_leaves
 from black.mode import Feature
@@ -41,6 +40,7 @@
     is_empty_lpar,
     is_empty_par,
     is_empty_rpar,
+    is_part_of_annotation,
     parent_type,
     replace_child,
     syms,
@@ -351,7 +351,7 @@ class StringMerger(StringTransformer, CustomSplitMapMixin):
 
     Requirements:
         (A) The line contains adjacent strings such that ALL of the validation checks
-        listed in StringMerger.__validate_msg(...)'s docstring pass.
+        listed in StringMerger._validate_msg(...)'s docstring pass.
             OR
         (B) The line contains a string which uses line continuation backslashes.
 
@@ -377,6 +377,8 @@ def do_match(self, line: Line) -> TMatchResult:
                 and is_valid_index(i + 1)
                 and LL[i + 1].type == token.STRING
             ):
+                if is_part_of_annotation(leaf):
+                    return TErr("String is part of type annotation.")
                 return Ok(i)
 
             if leaf.type == token.STRING and "\\\n" in leaf.value:
@@ -454,7 +456,7 @@ def _merge_string_group(self, line: Line, string_idx: int) -> TResult[Line]:
 
         Returns:
             Ok(new_line), if ALL of the validation checks found in
-            __validate_msg(...) pass.
+            _validate_msg(...) pass.
                 OR
             Err(CannotTransform), otherwise.
         """
@@ -608,7 +610,7 @@ def make_naked(string: str, string_prefix: str) -> str:
     def _validate_msg(line: Line, string_idx: int) -> TResult[None]:
         """Validate (M)erge (S)tring (G)roup
 
-        Transform-time string validation logic for __merge_string_group(...).
+        Transform-time string validation logic for _merge_string_group(...).
 
         Returns:
             * Ok(None), if ALL validation checks (listed below) pass.
@@ -622,6 +624,11 @@ def _validate_msg(line: Line, string_idx: int) -> TResult[None]:
                 - The set of all string prefixes in the string group is of
                   length greater than one and is not equal to {"", "f"}.
                 - The string group consists of raw strings.
+                - The string group is stringified type annotations. We don't want to
+                  process stringified type annotations since pyright doesn't support
+                  them spanning multiple string values. (NOTE: mypy, pytype, pyre do
+                  support them, so we can change if pyright also gains support in the
+                  future. See https://github.com/microsoft/pyright/issues/4359.)
         """
         # We first check for "inner" stand-alone comments (i.e. stand-alone
         # comments that have a string leaf before them AND after them).
@@ -812,13 +819,7 @@ def do_transform(self, line: Line, string_idx: int) -> Iterator[TResult[Line]]:
 
         new_line = line.clone()
         new_line.comments = line.comments.copy()
-        try:
-            append_leaves(new_line, line, LL[: string_idx - 1])
-        except BracketMatchError:
-            # HACK: I believe there is currently a bug somewhere in
-            # right_hand_split() that is causing brackets to not be tracked
-            # properly by a shared BracketTracker.
-            append_leaves(new_line, line, LL[: string_idx - 1], preformatted=True)
+        append_leaves(new_line, line, LL[: string_idx - 1])
 
         string_leaf = Leaf(token.STRING, LL[string_idx].value)
         LL[string_idx - 1].remove()
diff --git a/tests/data/preview/long_strings__type_annotations.py b/tests/data/preview/long_strings__type_annotations.py
new file mode 100644
index 00000000000..41d7ee2b67b
--- /dev/null
+++ b/tests/data/preview/long_strings__type_annotations.py
@@ -0,0 +1,59 @@
+def func(
+    arg1,
+    arg2,
+) -> Set["this_is_a_very_long_module_name.AndAVeryLongClasName"
+         ".WithAVeryVeryVeryVeryVeryLongSubClassName"]:
+  pass
+
+
+def func(
+    argument: (
+        "VeryLongClassNameWithAwkwardGenericSubtype[int] |"
+        "VeryLongClassNameWithAwkwardGenericSubtype[str]"
+    ),
+) -> (
+    "VeryLongClassNameWithAwkwardGenericSubtype[int] |"
+    "VeryLongClassNameWithAwkwardGenericSubtype[str]"
+):
+  pass
+
+
+def func(
+    argument: (
+        "int |"
+        "str"
+    ),
+) -> Set["int |"
+         " str"]:
+  pass
+
+
+# output
+
+
+def func(
+    arg1,
+    arg2,
+) -> Set[
+    "this_is_a_very_long_module_name.AndAVeryLongClasName"
+    ".WithAVeryVeryVeryVeryVeryLongSubClassName"
+]:
+    pass
+
+
+def func(
+    argument: (
+        "VeryLongClassNameWithAwkwardGenericSubtype[int] |"
+        "VeryLongClassNameWithAwkwardGenericSubtype[str]"
+    ),
+) -> (
+    "VeryLongClassNameWithAwkwardGenericSubtype[int] |"
+    "VeryLongClassNameWithAwkwardGenericSubtype[str]"
+):
+    pass
+
+
+def func(
+    argument: ("int |" "str"),
+) -> Set["int |" " str"]:
+    pass

From 73c2d5514ce604141abe176b1f3e5cd35ff51d56 Mon Sep 17 00:00:00 2001
From: "Yilei \"Dolee\" Yang" <yileiyang@google.com>
Date: Tue, 20 Dec 2022 14:59:38 -0800
Subject: [PATCH 0683/1034] Fix a crash in ESP where a standalone comment is
 placed before a dict's value (#3469)

---
 CHANGES.md                                     |  2 ++
 src/black/trans.py                             |  2 +-
 tests/data/preview/long_strings__regression.py | 14 ++++++++++++++
 3 files changed, 17 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index c29933fe5d9..1e51f3e9108 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -21,6 +21,8 @@
   and except clauses (#3423)
 - Fix a crash in preview advanced string processing where mixed implicitly concatenated
   regular and f-strings start with an empty span (#3463)
+- Fix a crash in preview advanced string processing where a standalone comment is placed
+  before a dict's value (#3469)
 - Do not put the closing quotes in a docstring on a separate line, even if the line is
   too long (#3430)
 - Long values in dict literals are now wrapped in parentheses; correspondingly
diff --git a/src/black/trans.py b/src/black/trans.py
index a5cf4955f13..0eb53e2b098 100644
--- a/src/black/trans.py
+++ b/src/black/trans.py
@@ -1866,7 +1866,7 @@ def _dict_or_lambda_match(LL: List[Leaf]) -> Optional[int]:
 
             for i, leaf in enumerate(LL):
                 # We MUST find a colon, it can either be dict's or lambda's colon...
-                if leaf.type == token.COLON:
+                if leaf.type == token.COLON and i < len(LL) - 1:
                     idx = i + 2 if is_empty_par(LL[i + 1]) else i + 1
 
                     # That colon MUST be followed by a string...
diff --git a/tests/data/preview/long_strings__regression.py b/tests/data/preview/long_strings__regression.py
index 5e8f012bc3e..ef9007f4ce1 100644
--- a/tests/data/preview/long_strings__regression.py
+++ b/tests/data/preview/long_strings__regression.py
@@ -543,6 +543,13 @@ async def foo(self):
     f'xxxxxxxxxxxxx xxxx xx xxxxxxxxxx. xxxxx: {x.xxx}',
 )
 
+# Regression test for https://github.com/psf/black/issues/3455.
+a_dict = {
+    "/this/is/a/very/very/very/very/very/very/very/very/very/very/long/key/without/spaces":
+        # And there is a comment before the value
+        ("item1", "item2", "item3"),
+}
+
 
 # output
 
@@ -1221,3 +1228,10 @@ async def foo(self):
         f"xxxxxxxxxxxxx xxxx xx xxxxxxxxxx. xxxxx: {x.xxx}"
     ),
 )
+
+# Regression test for https://github.com/psf/black/issues/3455.
+a_dict = {
+    "/this/is/a/very/very/very/very/very/very/very/very/very/very/long/key/without/spaces":
+    # And there is a comment before the value
+    ("item1", "item2", "item3"),
+}

From 59f03d1b9d3c77f214087948b4d5e3dbb024d0b3 Mon Sep 17 00:00:00 2001
From: Matthew Armand <marmand68@gmail.com>
Date: Tue, 20 Dec 2022 18:00:06 -0500
Subject: [PATCH 0684/1034] Vim plugin docs improvements (#3468)

* Organize vim plugin section with headers to separate out Installation, Usage, and Troubleshooting for readability and easy linking

* Add missing plugin configuration options, with current defaults

* Add installation note for Arch Linux, now that the plugin is shipped with the python-black package (ref: https://bugs.archlinux.org/task/73024)

* Fix vim-plug specification to follow stable releases. Moving the same tag is an antipattern that doesn't re-resolve with vim-plug, see this discussion for more detail (https://github.com/junegunn/vim-plug/pull/720\#issuecomment-1105829356). Per vim-plug's maintainer's recommendation, use the 'tag' key instead with a shell wildcard. Wildcard should be '*.*.*' as that follows Black's versioning detailed here (https://black.readthedocs.io/en/latest/contributing/release_process.html\#cutting-a-release) and doesn't include current alpha releases.
---
 CHANGES.md                   |  2 ++
 docs/integrations/editors.md | 49 +++++++++++++++++++++++++++++++++---
 2 files changed, 48 insertions(+), 3 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 1e51f3e9108..e2c5adfda35 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -75,6 +75,8 @@
 <!-- Major changes to documentation and policies. Small docs changes
      don't need a changelog entry. -->
 
+- Expand `vim-plug` installation instructions to offer more explicit options (#3468)
+
 ## 22.12.0
 
 ### Preview style
diff --git a/docs/integrations/editors.md b/docs/integrations/editors.md
index 0778c6a72f1..a8b7978c4d7 100644
--- a/docs/integrations/editors.md
+++ b/docs/integrations/editors.md
@@ -111,16 +111,51 @@ Configuration:
 - `g:black_fast` (defaults to `0`)
 - `g:black_linelength` (defaults to `88`)
 - `g:black_skip_string_normalization` (defaults to `0`)
+- `g:black_skip_magic_trailing_comma` (defaults to `0`)
 - `g:black_virtualenv` (defaults to `~/.vim/black` or `~/.local/share/nvim/black`)
+- `g:black_use_virtualenv` (defaults to `1`)
+- `g:black_target_version` (defaults to `""`)
 - `g:black_quiet` (defaults to `0`)
 - `g:black_preview` (defaults to `0`)
 
+#### Installation
+
+This plugin **requires Vim 7.0+ built with Python 3.7+ support**. It needs Python 3.7 to
+be able to run _Black_ inside the Vim process which is much faster than calling an
+external command.
+
+##### `vim-plug`
+
 To install with [vim-plug](https://github.com/junegunn/vim-plug):
 
+_Black_'s `stable` branch tracks official version updates, and can be used to simply
+follow the most recent stable version.
+
 ```
 Plug 'psf/black', { 'branch': 'stable' }
 ```
 
+Another option which is a bit more explicit and offers more control is to use
+`vim-plug`'s `tag` option with a shell wildcard. This will resolve to the latest tag
+which matches the given pattern.
+
+The following matches all stable versions (see the
+[Release Process](../contributing/release_process.md) section for documentation of
+version scheme used by Black):
+
+```
+Plug 'psf/black', { 'tag': '*.*.*' }
+```
+
+and the following demonstrates pinning to a specific year's stable style (2022 in this
+case):
+
+```
+Plug 'psf/black', { 'tag': '22.*.*' }
+```
+
+##### Vundle
+
 or with [Vundle](https://github.com/VundleVim/Vundle.vim):
 
 ```
@@ -134,6 +169,14 @@ $ cd ~/.vim/bundle/black
 $ git checkout origin/stable -b stable
 ```
 
+##### Arch Linux
+
+On Arch Linux, the plugin is shipped with the
+[`python-black`](https://archlinux.org/packages/community/any/python-black/) package, so
+you can start using it in Vim after install with no additional setup.
+
+##### Vim 8 Native Plugin Management
+
 or you can copy the plugin files from
 [plugin/black.vim](https://github.com/psf/black/blob/stable/plugin/black.vim) and
 [autoload/black.vim](https://github.com/psf/black/blob/stable/autoload/black.vim).
@@ -148,9 +191,7 @@ curl https://raw.githubusercontent.com/psf/black/stable/autoload/black.vim -o ~/
 Let me know if this requires any changes to work with Vim 8's builtin `packadd`, or
 Pathogen, and so on.
 
-This plugin **requires Vim 7.0+ built with Python 3.7+ support**. It needs Python 3.7 to
-be able to run _Black_ inside the Vim process which is much faster than calling an
-external command.
+#### Usage
 
 On first run, the plugin creates its own virtualenv using the right Python version and
 automatically installs _Black_. You can upgrade it later by calling `:BlackUpgrade` and
@@ -187,6 +228,8 @@ To run _Black_ on a key press (e.g. F9 below), add this:
 nnoremap <F9> :Black<CR>
 ```
 
+#### Troubleshooting
+
 **How to get Vim with Python 3.6?** On Ubuntu 17.10 Vim comes with Python 3.6 by
 default. On macOS with Homebrew run: `brew install vim`. When building Vim from source,
 use: `./configure --enable-python3interp=yes`. There's many guides online how to do

From 29dd25725303992d36c3a75c3a071080ac06085f Mon Sep 17 00:00:00 2001
From: "Yilei \"Dolee\" Yang" <yileiyang@google.com>
Date: Tue, 20 Dec 2022 17:58:02 -0800
Subject: [PATCH 0685/1034] Fix an issue where extra empty lines are added.
 (#3470)

---
 CHANGES.md                      |  2 ++
 src/black/lines.py              |  3 +-
 tests/data/preview/comments9.py | 51 +++++++++++++++++++++++++++++++++
 3 files changed, 55 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index e2c5adfda35..c07d81d1320 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -23,6 +23,8 @@
   regular and f-strings start with an empty span (#3463)
 - Fix a crash in preview advanced string processing where a standalone comment is placed
   before a dict's value (#3469)
+- Fix an issue where extra empty lines are added when a decorator has `# fmt: skip`
+  applied or there is a standalone comment between decorators (#3470)
 - Do not put the closing quotes in a docstring on a separate line, even if the line is
   too long (#3430)
 - Long values in dict literals are now wrapped in parentheses; correspondingly
diff --git a/src/black/lines.py b/src/black/lines.py
index 08281bcf370..2aa675c3b31 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -520,7 +520,8 @@ def maybe_empty_lines(self, current_line: Line) -> LinesBlock:
                 and (self.semantic_leading_comment is None or before)
             ):
                 self.semantic_leading_comment = block
-        elif not current_line.is_decorator:
+        # `or before` means this decorator already has an empty line before
+        elif not current_line.is_decorator or before:
             self.semantic_leading_comment = None
 
         self.previous_line = current_line
diff --git a/tests/data/preview/comments9.py b/tests/data/preview/comments9.py
index 449612c037a..77b25556e74 100644
--- a/tests/data/preview/comments9.py
+++ b/tests/data/preview/comments9.py
@@ -114,6 +114,31 @@ def first_method(self):
         pass
 
 
+# Regression test for https://github.com/psf/black/issues/3454.
+def foo():
+    pass
+    # Trailing comment that belongs to this function
+
+
+@decorator1
+@decorator2  # fmt: skip
+def bar():
+    pass
+
+
+# Regression test for https://github.com/psf/black/issues/3454.
+def foo():
+    pass
+    # Trailing comment that belongs to this function.
+    # NOTE this comment only has one empty line below, and the formatter
+    # should enforce two blank lines.
+
+@decorator1
+# A standalone comment
+def bar():
+    pass
+
+
 # output
 
 
@@ -252,3 +277,29 @@ class MyClass:
     # More comments.
     def first_method(self):
         pass
+
+
+# Regression test for https://github.com/psf/black/issues/3454.
+def foo():
+    pass
+    # Trailing comment that belongs to this function
+
+
+@decorator1
+@decorator2  # fmt: skip
+def bar():
+    pass
+
+
+# Regression test for https://github.com/psf/black/issues/3454.
+def foo():
+    pass
+    # Trailing comment that belongs to this function.
+    # NOTE this comment only has one empty line below, and the formatter
+    # should enforce two blank lines.
+
+
+@decorator1
+# A standalone comment
+def bar():
+    pass

From 3246df89d6d80fc09357b445630fad87f08f57ce Mon Sep 17 00:00:00 2001
From: Matthew Armand <marmand68@gmail.com>
Date: Tue, 20 Dec 2022 22:18:15 -0500
Subject: [PATCH 0686/1034] Add latest_prerelease Docker Hub tag for following
 the latest alpha release (#3465)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 .github/workflows/docker.yml                       | 11 +++++++++++
 CHANGES.md                                         |  2 ++
 docs/usage_and_configuration/black_docker_image.md |  5 +++++
 3 files changed, 18 insertions(+)

diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
index 855186f9bf1..04e30e727bd 100644
--- a/.github/workflows/docker.yml
+++ b/.github/workflows/docker.yml
@@ -54,5 +54,16 @@ jobs:
           push: true
           tags: pyfound/black:latest_release
 
+      - name: Build and push latest_prerelease tag
+        if:
+          ${{ github.event_name == 'release' && github.event.action == 'published' &&
+          github.event.release.prerelease }}
+        uses: docker/build-push-action@v3
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: pyfound/black:latest_prerelease
+
       - name: Image digest
         run: echo ${{ steps.docker_build.outputs.digest }}
diff --git a/CHANGES.md b/CHANGES.md
index c07d81d1320..c89b10638ed 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -71,6 +71,8 @@
 <!-- For example, Docker, GitHub Actions, pre-commit, editors -->
 
 - Move 3.11 CI to normal flow now all dependencies support 3.11 (#3446)
+- Docker: Add new `latest_prerelease` tag automation to follow latest black alpha
+  release on docker images (#3465)
 
 ### Documentation
 
diff --git a/docs/usage_and_configuration/black_docker_image.md b/docs/usage_and_configuration/black_docker_image.md
index 8de566ea270..85aec91ef1c 100644
--- a/docs/usage_and_configuration/black_docker_image.md
+++ b/docs/usage_and_configuration/black_docker_image.md
@@ -10,6 +10,11 @@ _Black_ images with the following tags are available:
 - `latest_release` - tag created when a new version of _Black_ is released.\
   ℹ Recommended for users who want to use released versions of _Black_. It maps to [the latest release](https://github.com/psf/black/releases/latest)
   of _Black_.
+- `latest_prerelease` - tag created when a new alpha (prerelease) version of _Black_ is
+  released.\
+  ℹ Recommended for users who want to preview or test alpha versions of _Black_. Note that
+  the most recent release may be newer than any prerelease, because no prereleases are created
+  before most releases.
 - `latest` - tag used for the newest image of _Black_.\
   ℹ Recommended for users who always want to use the latest version of _Black_, even before
   it is released.

From 3feff21eca0eee4b9fe72d12b506ac273cb5bcd0 Mon Sep 17 00:00:00 2001
From: "Yilei \"Dolee\" Yang" <yileiyang@google.com>
Date: Fri, 23 Dec 2022 12:13:45 -0800
Subject: [PATCH 0687/1034] Significantly speedup ESP on large expressions that
 contain many strings (#3467)

---
 CHANGES.md                         |   1 +
 src/black/trans.py                 | 279 +++++++++++++++++++++--------
 tests/data/preview/long_strings.py |  31 ++++
 3 files changed, 235 insertions(+), 76 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index c89b10638ed..587ca8a2a0d 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -16,6 +16,7 @@
 
 <!-- Changes that affect Black's preview style -->
 
+- Improve the performance on large expressions that contain many strings (#3467)
 - Fix a crash in preview style with assert + parenthesized string (#3415)
 - Fix crashes in preview style with walrus operators used in function return annotations
   and except clauses (#3423)
diff --git a/src/black/trans.py b/src/black/trans.py
index 0eb53e2b098..ec07f5eab74 100644
--- a/src/black/trans.py
+++ b/src/black/trans.py
@@ -69,7 +69,7 @@ class CannotTransform(Exception):
 ParserState = int
 StringID = int
 TResult = Result[T, CannotTransform]  # (T)ransform Result
-TMatchResult = TResult[Index]
+TMatchResult = TResult[List[Index]]
 
 
 def TErr(err_msg: str) -> Err[CannotTransform]:
@@ -198,14 +198,19 @@ def __init__(self, line_length: int, normalize_strings: bool) -> None:
     def do_match(self, line: Line) -> TMatchResult:
         """
         Returns:
-            * Ok(string_idx) such that `line.leaves[string_idx]` is our target
-            string, if a match was able to be made.
+            * Ok(string_indices) such that for each index, `line.leaves[index]`
+            is our target string if a match was able to be made. For
+            transformers that don't result in more lines (e.g. StringMerger,
+            StringParenStripper), multiple matches and transforms are done at
+            once to reduce the complexity.
                 OR
-            * Err(CannotTransform), if a match was not able to be made.
+            * Err(CannotTransform), if no match could be made.
         """
 
     @abstractmethod
-    def do_transform(self, line: Line, string_idx: int) -> Iterator[TResult[Line]]:
+    def do_transform(
+        self, line: Line, string_indices: List[int]
+    ) -> Iterator[TResult[Line]]:
         """
         Yields:
             * Ok(new_line) where new_line is the new transformed line.
@@ -246,9 +251,9 @@ def __call__(self, line: Line, _features: Collection[Feature]) -> Iterator[Line]
                 " this line as one that it can transform."
             ) from cant_transform
 
-        string_idx = match_result.ok()
+        string_indices = match_result.ok()
 
-        for line_result in self.do_transform(line, string_idx):
+        for line_result in self.do_transform(line, string_indices):
             if isinstance(line_result, Err):
                 cant_transform = line_result.err()
                 raise CannotTransform(
@@ -371,30 +376,50 @@ def do_match(self, line: Line) -> TMatchResult:
 
         is_valid_index = is_valid_index_factory(LL)
 
-        for i, leaf in enumerate(LL):
+        string_indices = []
+        idx = 0
+        while is_valid_index(idx):
+            leaf = LL[idx]
             if (
                 leaf.type == token.STRING
-                and is_valid_index(i + 1)
-                and LL[i + 1].type == token.STRING
+                and is_valid_index(idx + 1)
+                and LL[idx + 1].type == token.STRING
             ):
-                if is_part_of_annotation(leaf):
-                    return TErr("String is part of type annotation.")
-                return Ok(i)
+                if not is_part_of_annotation(leaf):
+                    string_indices.append(idx)
 
-            if leaf.type == token.STRING and "\\\n" in leaf.value:
-                return Ok(i)
+                # Advance to the next non-STRING leaf.
+                idx += 2
+                while is_valid_index(idx) and LL[idx].type == token.STRING:
+                    idx += 1
 
-        return TErr("This line has no strings that need merging.")
+            elif leaf.type == token.STRING and "\\\n" in leaf.value:
+                string_indices.append(idx)
+                # Advance to the next non-STRING leaf.
+                idx += 1
+                while is_valid_index(idx) and LL[idx].type == token.STRING:
+                    idx += 1
 
-    def do_transform(self, line: Line, string_idx: int) -> Iterator[TResult[Line]]:
+            else:
+                idx += 1
+
+        if string_indices:
+            return Ok(string_indices)
+        else:
+            return TErr("This line has no strings that need merging.")
+
+    def do_transform(
+        self, line: Line, string_indices: List[int]
+    ) -> Iterator[TResult[Line]]:
         new_line = line
+
         rblc_result = self._remove_backslash_line_continuation_chars(
-            new_line, string_idx
+            new_line, string_indices
         )
         if isinstance(rblc_result, Ok):
             new_line = rblc_result.ok()
 
-        msg_result = self._merge_string_group(new_line, string_idx)
+        msg_result = self._merge_string_group(new_line, string_indices)
         if isinstance(msg_result, Ok):
             new_line = msg_result.ok()
 
@@ -415,7 +440,7 @@ def do_transform(self, line: Line, string_idx: int) -> Iterator[TResult[Line]]:
 
     @staticmethod
     def _remove_backslash_line_continuation_chars(
-        line: Line, string_idx: int
+        line: Line, string_indices: List[int]
     ) -> TResult[Line]:
         """
         Merge strings that were split across multiple lines using
@@ -429,30 +454,40 @@ def _remove_backslash_line_continuation_chars(
         """
         LL = line.leaves
 
-        string_leaf = LL[string_idx]
-        if not (
-            string_leaf.type == token.STRING
-            and "\\\n" in string_leaf.value
-            and not has_triple_quotes(string_leaf.value)
-        ):
+        indices_to_transform = []
+        for string_idx in string_indices:
+            string_leaf = LL[string_idx]
+            if (
+                string_leaf.type == token.STRING
+                and "\\\n" in string_leaf.value
+                and not has_triple_quotes(string_leaf.value)
+            ):
+                indices_to_transform.append(string_idx)
+
+        if not indices_to_transform:
             return TErr(
-                f"String leaf {string_leaf} does not contain any backslash line"
-                " continuation characters."
+                "Found no string leaves that contain backslash line continuation"
+                " characters."
             )
 
         new_line = line.clone()
         new_line.comments = line.comments.copy()
         append_leaves(new_line, line, LL)
 
-        new_string_leaf = new_line.leaves[string_idx]
-        new_string_leaf.value = new_string_leaf.value.replace("\\\n", "")
+        for string_idx in indices_to_transform:
+            new_string_leaf = new_line.leaves[string_idx]
+            new_string_leaf.value = new_string_leaf.value.replace("\\\n", "")
 
         return Ok(new_line)
 
-    def _merge_string_group(self, line: Line, string_idx: int) -> TResult[Line]:
+    def _merge_string_group(
+        self, line: Line, string_indices: List[int]
+    ) -> TResult[Line]:
         """
-        Merges string group (i.e. set of adjacent strings) where the first
-        string in the group is `line.leaves[string_idx]`.
+        Merges string groups (i.e. set of adjacent strings).
+
+        Each index from `string_indices` designates one string group's first
+        leaf in `line.leaves`.
 
         Returns:
             Ok(new_line), if ALL of the validation checks found in
@@ -464,10 +499,54 @@ def _merge_string_group(self, line: Line, string_idx: int) -> TResult[Line]:
 
         is_valid_index = is_valid_index_factory(LL)
 
-        vresult = self._validate_msg(line, string_idx)
-        if isinstance(vresult, Err):
-            return vresult
+        # A dict of {string_idx: tuple[num_of_strings, string_leaf]}.
+        merged_string_idx_dict: Dict[int, Tuple[int, Leaf]] = {}
+        for string_idx in string_indices:
+            vresult = self._validate_msg(line, string_idx)
+            if isinstance(vresult, Err):
+                continue
+            merged_string_idx_dict[string_idx] = self._merge_one_string_group(
+                LL, string_idx, is_valid_index
+            )
+
+        if not merged_string_idx_dict:
+            return TErr("No string group is merged")
+
+        # Build the final line ('new_line') that this method will later return.
+        new_line = line.clone()
+        previous_merged_string_idx = -1
+        previous_merged_num_of_strings = -1
+        for i, leaf in enumerate(LL):
+            if i in merged_string_idx_dict:
+                previous_merged_string_idx = i
+                previous_merged_num_of_strings, string_leaf = merged_string_idx_dict[i]
+                new_line.append(string_leaf)
+
+            if (
+                previous_merged_string_idx
+                <= i
+                < previous_merged_string_idx + previous_merged_num_of_strings
+            ):
+                for comment_leaf in line.comments_after(LL[i]):
+                    new_line.append(comment_leaf, preformatted=True)
+                continue
+
+            append_leaves(new_line, line, [leaf])
+
+        return Ok(new_line)
 
+    def _merge_one_string_group(
+        self, LL: List[Leaf], string_idx: int, is_valid_index: Callable[[int], bool]
+    ) -> Tuple[int, Leaf]:
+        """
+        Merges one string group where the first string in the group is
+        `LL[string_idx]`.
+
+        Returns:
+            A tuple of `(num_of_strings, leaf)` where `num_of_strings` is the
+            number of strings merged and `leaf` is the newly merged string
+            to be replaced in the new line.
+        """
         # If the string group is wrapped inside an Atom node, we must make sure
         # to later replace that Atom with our new (merged) string leaf.
         atom_node = LL[string_idx].parent
@@ -590,21 +669,8 @@ def make_naked(string: str, string_prefix: str) -> str:
                 # Else replace the atom node with the new string leaf.
                 replace_child(atom_node, string_leaf)
 
-        # Build the final line ('new_line') that this method will later return.
-        new_line = line.clone()
-        for i, leaf in enumerate(LL):
-            if i == string_idx:
-                new_line.append(string_leaf)
-
-            if string_idx <= i < string_idx + num_of_strings:
-                for comment_leaf in line.comments_after(LL[i]):
-                    new_line.append(comment_leaf, preformatted=True)
-                continue
-
-            append_leaves(new_line, line, [leaf])
-
         self.add_custom_splits(string_leaf.value, custom_splits)
-        return Ok(new_line)
+        return num_of_strings, string_leaf
 
     @staticmethod
     def _validate_msg(line: Line, string_idx: int) -> TResult[None]:
@@ -718,7 +784,15 @@ def do_match(self, line: Line) -> TMatchResult:
 
         is_valid_index = is_valid_index_factory(LL)
 
-        for idx, leaf in enumerate(LL):
+        string_indices = []
+
+        idx = -1
+        while True:
+            idx += 1
+            if idx >= len(LL):
+                break
+            leaf = LL[idx]
+
             # Should be a string...
             if leaf.type != token.STRING:
                 continue
@@ -800,39 +874,73 @@ def do_match(self, line: Line) -> TMatchResult:
                 }:
                     continue
 
-                return Ok(string_idx)
+                string_indices.append(string_idx)
+                idx = string_idx
+                while idx < len(LL) - 1 and LL[idx + 1].type == token.STRING:
+                    idx += 1
 
+        if string_indices:
+            return Ok(string_indices)
         return TErr("This line has no strings wrapped in parens.")
 
-    def do_transform(self, line: Line, string_idx: int) -> Iterator[TResult[Line]]:
+    def do_transform(
+        self, line: Line, string_indices: List[int]
+    ) -> Iterator[TResult[Line]]:
         LL = line.leaves
 
-        string_parser = StringParser()
-        rpar_idx = string_parser.parse(LL, string_idx)
+        string_and_rpar_indices: List[int] = []
+        for string_idx in string_indices:
+            string_parser = StringParser()
+            rpar_idx = string_parser.parse(LL, string_idx)
+
+            should_transform = True
+            for leaf in (LL[string_idx - 1], LL[rpar_idx]):
+                if line.comments_after(leaf):
+                    # Should not strip parentheses which have comments attached
+                    # to them.
+                    should_transform = False
+                    break
+            if should_transform:
+                string_and_rpar_indices.extend((string_idx, rpar_idx))
 
-        for leaf in (LL[string_idx - 1], LL[rpar_idx]):
-            if line.comments_after(leaf):
-                yield TErr(
-                    "Will not strip parentheses which have comments attached to them."
-                )
-                return
+        if string_and_rpar_indices:
+            yield Ok(self._transform_to_new_line(line, string_and_rpar_indices))
+        else:
+            yield Err(
+                CannotTransform("All string groups have comments attached to them.")
+            )
+
+    def _transform_to_new_line(
+        self, line: Line, string_and_rpar_indices: List[int]
+    ) -> Line:
+        LL = line.leaves
 
         new_line = line.clone()
         new_line.comments = line.comments.copy()
-        append_leaves(new_line, line, LL[: string_idx - 1])
 
-        string_leaf = Leaf(token.STRING, LL[string_idx].value)
-        LL[string_idx - 1].remove()
-        replace_child(LL[string_idx], string_leaf)
-        new_line.append(string_leaf)
+        previous_idx = -1
+        # We need to sort the indices, since string_idx and its matching
+        # rpar_idx may not come in order, e.g. in
+        # `("outer" % ("inner".join(items)))`, the "inner" string's
+        # string_idx is smaller than "outer" string's rpar_idx.
+        for idx in sorted(string_and_rpar_indices):
+            leaf = LL[idx]
+            lpar_or_rpar_idx = idx - 1 if leaf.type == token.STRING else idx
+            append_leaves(new_line, line, LL[previous_idx + 1 : lpar_or_rpar_idx])
+            if leaf.type == token.STRING:
+                string_leaf = Leaf(token.STRING, LL[idx].value)
+                LL[lpar_or_rpar_idx].remove()  # Remove lpar.
+                replace_child(LL[idx], string_leaf)
+                new_line.append(string_leaf)
+            else:
+                LL[lpar_or_rpar_idx].remove()  # This is a rpar.
 
-        append_leaves(
-            new_line, line, LL[string_idx + 1 : rpar_idx] + LL[rpar_idx + 1 :]
-        )
+            previous_idx = idx
 
-        LL[rpar_idx].remove()
+        # Append the leaves after the last idx:
+        append_leaves(new_line, line, LL[idx + 1 :])
 
-        yield Ok(new_line)
+        return new_line
 
 
 class BaseStringSplitter(StringTransformer):
@@ -885,7 +993,12 @@ def do_match(self, line: Line) -> TMatchResult:
         if isinstance(match_result, Err):
             return match_result
 
-        string_idx = match_result.ok()
+        string_indices = match_result.ok()
+        assert len(string_indices) == 1, (
+            f"{self.__class__.__name__} should only find one match at a time, found"
+            f" {len(string_indices)}"
+        )
+        string_idx = string_indices[0]
         vresult = self._validate(line, string_idx)
         if isinstance(vresult, Err):
             return vresult
@@ -1219,10 +1332,17 @@ def do_splitter_match(self, line: Line) -> TMatchResult:
         if is_valid_index(idx):
             return TErr("This line does not end with a string.")
 
-        return Ok(string_idx)
+        return Ok([string_idx])
 
-    def do_transform(self, line: Line, string_idx: int) -> Iterator[TResult[Line]]:
+    def do_transform(
+        self, line: Line, string_indices: List[int]
+    ) -> Iterator[TResult[Line]]:
         LL = line.leaves
+        assert len(string_indices) == 1, (
+            f"{self.__class__.__name__} should only find one match at a time, found"
+            f" {len(string_indices)}"
+        )
+        string_idx = string_indices[0]
 
         QUOTE = LL[string_idx].value[-1]
 
@@ -1710,7 +1830,7 @@ def do_splitter_match(self, line: Line) -> TMatchResult:
                             " resultant line would still be over the specified line"
                             " length and can't be split further by StringSplitter."
                         )
-            return Ok(string_idx)
+            return Ok([string_idx])
 
         return TErr("This line does not contain any non-atomic strings.")
 
@@ -1887,8 +2007,15 @@ def _dict_or_lambda_match(LL: List[Leaf]) -> Optional[int]:
 
         return None
 
-    def do_transform(self, line: Line, string_idx: int) -> Iterator[TResult[Line]]:
+    def do_transform(
+        self, line: Line, string_indices: List[int]
+    ) -> Iterator[TResult[Line]]:
         LL = line.leaves
+        assert len(string_indices) == 1, (
+            f"{self.__class__.__name__} should only find one match at a time, found"
+            f" {len(string_indices)}"
+        )
+        string_idx = string_indices[0]
 
         is_valid_index = is_valid_index_factory(LL)
         insert_str_child = insert_str_child_factory(LL[string_idx])
diff --git a/tests/data/preview/long_strings.py b/tests/data/preview/long_strings.py
index 9c78f675b8f..b7a0a42f82a 100644
--- a/tests/data/preview/long_strings.py
+++ b/tests/data/preview/long_strings.py
@@ -287,6 +287,23 @@ def foo():
     ),
 }
 
+# Complex string concatenations with a method call in the middle.
+code = (
+    ("    return [\n")
+    + (
+        ", \n".join(
+            "        (%r, self.%s, visitor.%s)"
+            % (attrname, attrname, visit_name)
+            for attrname, visit_name in names
+        )
+    )
+    + ("\n    ]\n")
+)
+
+
+# Test case of an outer string' parens enclose an inner string's parens.
+call(body=("%s %s" % ((",".join(items)), suffix)))
+
 
 # output
 
@@ -828,3 +845,17 @@ def foo():
         f"{some_function_call(j.right)})"
     ),
 }
+
+# Complex string concatenations with a method call in the middle.
+code = (
+    "    return [\n"
+    + ", \n".join(
+        "        (%r, self.%s, visitor.%s)" % (attrname, attrname, visit_name)
+        for attrname, visit_name in names
+    )
+    + "\n    ]\n"
+)
+
+
+# Test case of an outer string' parens enclose an inner string's parens.
+call(body="%s %s" % (",".join(items), suffix))

From 9b91638190342cf5a66d4edb11068526f7ebda59 Mon Sep 17 00:00:00 2001
From: Semen Zhydenko <simeon.zhidenko@gmail.com>
Date: Mon, 26 Dec 2022 03:39:51 +0100
Subject: [PATCH 0688/1034] Fix some typos (#3474)

---
 docs/contributing/issue_triage.md      | 2 +-
 tests/data/preview/prefer_rhs_split.py | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/contributing/issue_triage.md b/docs/contributing/issue_triage.md
index 9b987fb2425..865a47935ed 100644
--- a/docs/contributing/issue_triage.md
+++ b/docs/contributing/issue_triage.md
@@ -42,7 +42,7 @@ The lifecycle of a bug report or user support issue typically goes something lik
 1. _the issue is waiting for triage_
 2. **identified** - has been marked with a type label and other relevant labels, more
    details or a functional reproduction may be still needed (and therefore should be
-   marked with `S: needs repro` or `S: awaiting reponse`)
+   marked with `S: needs repro` or `S: awaiting response`)
 3. **confirmed** - the issue can reproduced and necessary details have been provided
 4. **discussion** - initial triage has been done and now the general details on how the
    issue should be best resolved are being hashed out
diff --git a/tests/data/preview/prefer_rhs_split.py b/tests/data/preview/prefer_rhs_split.py
index 5b89113e618..2f3cf33db41 100644
--- a/tests/data/preview/prefer_rhs_split.py
+++ b/tests/data/preview/prefer_rhs_split.py
@@ -50,7 +50,7 @@
     forth_item,
     fifth_item,
     last_item_very_loooooong,
-) = everyting = some_loooooog_function_name(
+) = everything = some_looooong_function_name(
     first_argument, second_argument, third_argument
 )
 

From 72a3408965f944f39f1080a5b67c25790acdc4e2 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 26 Dec 2022 06:32:42 -0800
Subject: [PATCH 0689/1034] Bump pypa/cibuildwheel from 2.11.3 to 2.11.4
 (#3475)

Bumps [pypa/cibuildwheel](https://github.com/pypa/cibuildwheel) from 2.11.3 to 2.11.4.
- [Release notes](https://github.com/pypa/cibuildwheel/releases)
- [Changelog](https://github.com/pypa/cibuildwheel/blob/main/docs/changelog.md)
- [Commits](https://github.com/pypa/cibuildwheel/compare/v2.11.3...v2.11.4)

---
updated-dependencies:
- dependency-name: pypa/cibuildwheel
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/pypi_upload.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/pypi_upload.yml b/.github/workflows/pypi_upload.yml
index 7fd760ef727..ee1c1fa7bcf 100644
--- a/.github/workflows/pypi_upload.yml
+++ b/.github/workflows/pypi_upload.yml
@@ -59,7 +59,7 @@ jobs:
       - uses: actions/checkout@v3
 
       - name: Build wheels via cibuildwheel
-        uses: pypa/cibuildwheel@v2.11.3
+        uses: pypa/cibuildwheel@v2.11.4
         env:
           CIBW_ARCHS_MACOS: "${{ matrix.macos_arch }}"
 

From 0abe85eebb94e7640aa5d443aefe5b9bed507bfc Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Thu, 29 Dec 2022 14:00:23 -0800
Subject: [PATCH 0690/1034] Bump peter-evans/find-comment from 2.1.0 to 2.2.0
 (#3476)

Bumps [peter-evans/find-comment](https://github.com/peter-evans/find-comment) from 2.1.0 to 2.2.0.
- [Release notes](https://github.com/peter-evans/find-comment/releases)
- [Commits](https://github.com/peter-evans/find-comment/compare/f4499a714d59013c74a08789b48abe4b704364a0...81e2da3af01c92f83cb927cf3ace0e085617c556)

---
updated-dependencies:
- dependency-name: peter-evans/find-comment
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/diff_shades_comment.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/diff_shades_comment.yml b/.github/workflows/diff_shades_comment.yml
index 1375be9788d..26d06090919 100644
--- a/.github/workflows/diff_shades_comment.yml
+++ b/.github/workflows/diff_shades_comment.yml
@@ -33,7 +33,7 @@ jobs:
       - name: Try to find pre-existing PR comment
         if: steps.metadata.outputs.needs-comment == 'true'
         id: find-comment
-        uses: peter-evans/find-comment@f4499a714d59013c74a08789b48abe4b704364a0
+        uses: peter-evans/find-comment@81e2da3af01c92f83cb927cf3ace0e085617c556
         with:
           issue-number: ${{ steps.metadata.outputs.pr-number }}
           comment-author: "github-actions[bot]"

From 4e3303fa08e030722d6fd4d7fe7b8d44ef98991c Mon Sep 17 00:00:00 2001
From: Jordan Ephron <j@jephron.com>
Date: Thu, 29 Dec 2022 18:13:15 -0500
Subject: [PATCH 0691/1034] Parenthesize conditional expressions (#2278)

Co-authored-by: Jordan Ephron <JEphron@users.noreply.github.com>
Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 CHANGES.md                           |   1 +
 src/black/__init__.py                |  16 ++-
 src/black/linegen.py                 |  16 +++
 src/black/mode.py                    |   1 +
 tests/data/conditional_expression.py | 160 +++++++++++++++++++++++++++
 5 files changed, 188 insertions(+), 6 deletions(-)
 create mode 100644 tests/data/conditional_expression.py

diff --git a/CHANGES.md b/CHANGES.md
index 587ca8a2a0d..2da0fb4720c 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -16,6 +16,7 @@
 
 <!-- Changes that affect Black's preview style -->
 
+- Add parentheses around `if`-`else` expressions (#2278)
 - Improve the performance on large expressions that contain many strings (#3467)
 - Fix a crash in preview style with assert + parenthesized string (#3415)
 - Fix crashes in preview style with walrus operators used in function return annotations
diff --git a/src/black/__init__.py b/src/black/__init__.py
index f00749aaed8..9f44722bfae 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -478,16 +478,20 @@ def main(  # noqa: C901
             )
 
             normalized = [
-                (source, source)
-                if source == "-"
-                else (normalize_path_maybe_ignore(Path(source), root), source)
+                (
+                    (source, source)
+                    if source == "-"
+                    else (normalize_path_maybe_ignore(Path(source), root), source)
+                )
                 for source in src
             ]
             srcs_string = ", ".join(
                 [
-                    f'"{_norm}"'
-                    if _norm
-                    else f'\033[31m"{source} (skipping - invalid)"\033[34m'
+                    (
+                        f'"{_norm}"'
+                        if _norm
+                        else f'\033[31m"{source} (skipping - invalid)"\033[34m'
+                    )
                     for _norm, source in normalized
                 ]
             )
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 2e75bc94506..4da75b28235 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -140,6 +140,22 @@ def visit_default(self, node: LN) -> Iterator[Line]:
                 self.current_line.append(node)
         yield from super().visit_default(node)
 
+    def visit_test(self, node: Node) -> Iterator[Line]:
+        """Visit an `x if y else z` test"""
+
+        if Preview.parenthesize_conditional_expressions in self.mode:
+            already_parenthesized = (
+                node.prev_sibling and node.prev_sibling.type == token.LPAR
+            )
+
+            if not already_parenthesized:
+                lpar = Leaf(token.LPAR, "")
+                rpar = Leaf(token.RPAR, "")
+                node.insert_child(0, lpar)
+                node.append_child(rpar)
+
+        yield from self.visit_default(node)
+
     def visit_INDENT(self, node: Leaf) -> Iterator[Line]:
         """Increase indentation level, maybe yield a line."""
         # In blib2to3 INDENT never holds comments.
diff --git a/src/black/mode.py b/src/black/mode.py
index a104d1b9862..775805ae960 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -161,6 +161,7 @@ class Preview(Enum):
     # NOTE: string_processing requires wrap_long_dict_values_in_parens
     # for https://github.com/psf/black/issues/3117 to be fixed.
     string_processing = auto()
+    parenthesize_conditional_expressions = auto()
     skip_magic_trailing_comma_in_subscript = auto()
     wrap_long_dict_values_in_parens = auto()
 
diff --git a/tests/data/conditional_expression.py b/tests/data/conditional_expression.py
new file mode 100644
index 00000000000..620a12dc986
--- /dev/null
+++ b/tests/data/conditional_expression.py
@@ -0,0 +1,160 @@
+long_kwargs_single_line = my_function(
+    foo="test, this is a sample value",
+    bar=some_long_value_name_foo_bar_baz if some_boolean_variable else some_fallback_value_foo_bar_baz,
+    baz="hello, this is a another value",
+)
+
+multiline_kwargs_indented = my_function(
+    foo="test, this is a sample value",
+    bar=some_long_value_name_foo_bar_baz
+    if some_boolean_variable
+    else some_fallback_value_foo_bar_baz,
+    baz="hello, this is a another value",
+)
+
+imploding_kwargs = my_function(
+    foo="test, this is a sample value",
+    bar=a
+    if foo
+    else b,
+    baz="hello, this is a another value",
+)
+
+imploding_line = (
+    1
+    if 1 + 1 == 2
+    else 0
+)
+
+exploding_line = "hello this is a slightly long string" if some_long_value_name_foo_bar_baz else "this one is a little shorter"
+
+positional_argument_test(some_long_value_name_foo_bar_baz if some_boolean_variable else some_fallback_value_foo_bar_baz)
+
+def weird_default_argument(x=some_long_value_name_foo_bar_baz
+        if SOME_CONSTANT
+        else some_fallback_value_foo_bar_baz):
+    pass
+
+nested = "hello this is a slightly long string" if (some_long_value_name_foo_bar_baz if
+                                                    nesting_test_expressions else some_fallback_value_foo_bar_baz) \
+    else "this one is a little shorter"
+
+generator_expression = (
+    some_long_value_name_foo_bar_baz if some_boolean_variable else some_fallback_value_foo_bar_baz for some_boolean_variable in some_iterable
+)
+
+
+def limit_offset_sql(self, low_mark, high_mark):
+    """Return LIMIT/OFFSET SQL clause."""
+    limit, offset = self._get_limit_offset_params(low_mark, high_mark)
+    return " ".join(
+        sql
+        for sql in (
+            "LIMIT %d" % limit if limit else None,
+            ("OFFSET %d" % offset) if offset else None,
+        )
+        if sql
+    )
+
+
+def something():
+    clone._iterable_class = (
+        NamedValuesListIterable
+        if named
+        else FlatValuesListIterable
+        if flat
+        else ValuesListIterable
+    )
+
+# output
+
+long_kwargs_single_line = my_function(
+    foo="test, this is a sample value",
+    bar=(
+        some_long_value_name_foo_bar_baz
+        if some_boolean_variable
+        else some_fallback_value_foo_bar_baz
+    ),
+    baz="hello, this is a another value",
+)
+
+multiline_kwargs_indented = my_function(
+    foo="test, this is a sample value",
+    bar=(
+        some_long_value_name_foo_bar_baz
+        if some_boolean_variable
+        else some_fallback_value_foo_bar_baz
+    ),
+    baz="hello, this is a another value",
+)
+
+imploding_kwargs = my_function(
+    foo="test, this is a sample value",
+    bar=a if foo else b,
+    baz="hello, this is a another value",
+)
+
+imploding_line = 1 if 1 + 1 == 2 else 0
+
+exploding_line = (
+    "hello this is a slightly long string"
+    if some_long_value_name_foo_bar_baz
+    else "this one is a little shorter"
+)
+
+positional_argument_test(
+    some_long_value_name_foo_bar_baz
+    if some_boolean_variable
+    else some_fallback_value_foo_bar_baz
+)
+
+
+def weird_default_argument(
+    x=(
+        some_long_value_name_foo_bar_baz
+        if SOME_CONSTANT
+        else some_fallback_value_foo_bar_baz
+    ),
+):
+    pass
+
+
+nested = (
+    "hello this is a slightly long string"
+    if (
+        some_long_value_name_foo_bar_baz
+        if nesting_test_expressions
+        else some_fallback_value_foo_bar_baz
+    )
+    else "this one is a little shorter"
+)
+
+generator_expression = (
+    (
+        some_long_value_name_foo_bar_baz
+        if some_boolean_variable
+        else some_fallback_value_foo_bar_baz
+    )
+    for some_boolean_variable in some_iterable
+)
+
+
+def limit_offset_sql(self, low_mark, high_mark):
+    """Return LIMIT/OFFSET SQL clause."""
+    limit, offset = self._get_limit_offset_params(low_mark, high_mark)
+    return " ".join(
+        sql
+        for sql in (
+            "LIMIT %d" % limit if limit else None,
+            ("OFFSET %d" % offset) if offset else None,
+        )
+        if sql
+    )
+
+
+def something():
+    clone._iterable_class = (
+        NamedValuesListIterable
+        if named
+        else FlatValuesListIterable if flat else ValuesListIterable
+    )

From 37542e64855ce21bd580f973ae5ce1ed86812a7a Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Sat, 31 Dec 2022 01:52:35 -0500
Subject: [PATCH 0692/1034] Fail lint CI if the PR doesn't target main (#3477)

Let's skip the check if we're running on a fork just in case someone
opens a PR against a branch on said fork as part of a PR review
upstream.
---
 .github/workflows/lint.yml | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index 90c48013080..064d4745a53 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -16,6 +16,13 @@ jobs:
     steps:
       - uses: actions/checkout@v3
 
+      - name: Assert PR target is main
+        if: github.event_name == 'pull_request' && github.repository == 'psf/black'
+        run: |
+          if [ "$GITHUB_BASE_REF" != "main" ]; then
+              echo "::error::PR targeting '$GITHUB_BASE_REF', please refile targeting 'main'." && exit 1
+          fi
+
       - name: Set up latest Python
         uses: actions/setup-python@v4
         with:

From 5d0d5936db2ed7a01c50a374e32753e1afe9cc71 Mon Sep 17 00:00:00 2001
From: Richard Si <sichard26@gmail.com>
Date: Mon, 2 Jan 2023 09:43:48 -0500
Subject: [PATCH 0693/1034] Add email for Richard Si (#3478)

---
 AUTHORS.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/AUTHORS.md b/AUTHORS.md
index a635e8c3c92..ab3f30b8821 100644
--- a/AUTHORS.md
+++ b/AUTHORS.md
@@ -10,7 +10,7 @@ Maintained with:
 - [Mika Naylor](mailto:mail@autophagy.io)
 - [Zsolt Dollenstein](mailto:zsol.zsol@gmail.com)
 - [Cooper Lees](mailto:me@cooperlees.com)
-- Richard Si
+- [Richard Si](mailto:sichard26@gmail.com)
 - [Felix Hildén](mailto:felix.hilden@gmail.com)
 - [Batuhan Taskaya](mailto:batuhan@python.org)
 

From 4bee9cca5553c55493203822b5a112ec5216bc74 Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Wed, 11 Jan 2023 16:19:27 -0300
Subject: [PATCH 0694/1034] Remove misleading phrase in Usage and Configuration
 (#3492)

The CLI options were already shown in the "Command line options" in the same page.
---
 docs/usage_and_configuration/the_basics.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index 3dab644f2c8..9dc5277c61e 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -40,6 +40,9 @@ so style options are deliberately limited and rarely added.
 
 </details>
 
+Note that all command-line options listed above can also be configured using a
+`pyproject.toml` file (more on that below).
+
 ### Code input alternatives
 
 #### Standard Input
@@ -287,9 +290,6 @@ file hierarchy.
 
 ## Next steps
 
-You've probably noted that not all of the options you can pass to _Black_ have been
-covered. Don't worry, the rest will be covered in a later section.
-
 A good next step would be configuring auto-discovery so `black .` is all you need
 instead of laborously listing every file or directory. You can get started by heading
 over to [File collection and discovery](./file_collection_and_discovery.md).

From f7580103407743a317e22297793822dd91f8fefe Mon Sep 17 00:00:00 2001
From: "Yilei \"Dolee\" Yang" <yileiyang@google.com>
Date: Sat, 14 Jan 2023 09:51:59 -0800
Subject: [PATCH 0695/1034] Documentation: clarify the state of multiple
 context managers (#3488)

Clarify that the backslash & paren-wrapping formatting for multiple
context managers aren't yet implemented.
---
 docs/the_black_code_style/future_style.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/the_black_code_style/future_style.md b/docs/the_black_code_style/future_style.md
index 17b7eef092f..9ca260fc0ad 100644
--- a/docs/the_black_code_style/future_style.md
+++ b/docs/the_black_code_style/future_style.md
@@ -19,7 +19,7 @@ with make_context_manager1() as cm1, make_context_manager2() as cm2, make_contex
     ...  # nothing to split on - line too long
 ```
 
-So _Black_ will eventually format it like this:
+So _Black_ will, when we implement this, format it like this:
 
 ```py3
 with \
@@ -31,8 +31,8 @@ with \
     ...  # backslashes and an ugly stranded colon
 ```
 
-Although when the target version is Python 3.9 or higher, _Black_ will use parentheses
-instead since they're allowed in Python 3.9 and higher.
+Although when the target version is Python 3.9 or higher, _Black_ will, when we
+implement this, use parentheses instead since they're allowed in Python 3.9 and higher.
 
 An alternative to consider if the backslashes in the above formatting are undesirable is
 to use {external:py:obj}`contextlib.ExitStack` to combine context managers in the

From d4ff985853c8d140d73b9d362604deedb41eb20e Mon Sep 17 00:00:00 2001
From: Ruslan <7631314+ruslaniv@users.noreply.github.com>
Date: Sun, 15 Jan 2023 01:32:00 +0700
Subject: [PATCH 0696/1034] Add IntelliJ docs on external tools and file
 watcher (#3365)

Revert deleted documentation on setting up Black using IntelliJ
external tool or file watcher utilities. These are still worth keeping
because some peole might not want to use a third-party plugin or
install Blackd's extra dependencies.

Co-authored-by: Richard Si <sichard26@gmail.com>
---
 docs/integrations/editors.md | 106 +++++++++++++++++++++++++++++++++++
 1 file changed, 106 insertions(+)

diff --git a/docs/integrations/editors.md b/docs/integrations/editors.md
index a8b7978c4d7..74c6a283ab8 100644
--- a/docs/integrations/editors.md
+++ b/docs/integrations/editors.md
@@ -10,6 +10,19 @@ Options include the following:
 
 ## PyCharm/IntelliJ IDEA
 
+There are three different ways you can use _Black_ from PyCharm:
+
+1. As local server using the BlackConnect plugin
+1. As external tool
+1. As file watcher
+
+The first option is the simplest to set up and formats the fastest (by spinning up
+{doc}`Black's HTTP server </usage_and_configuration/black_as_a_server>`, avoiding the
+startup cost on subsequent formats), but if you would prefer to not install a
+third-party plugin or blackd's extra dependencies, the other two are also great options.
+
+### As local server
+
 1. Install _Black_ with the `d` extra.
 
    ```console
@@ -46,6 +59,99 @@ Options include the following:
    - In `Trigger Settings` section of plugin configuration check
      `Trigger when saving changed files`.
 
+### As external tool
+
+1. Install `black`.
+
+   ```console
+   $ pip install black
+   ```
+
+1. Locate your `black` installation folder.
+
+   On macOS / Linux / BSD:
+
+   ```console
+   $ which black
+   /usr/local/bin/black  # possible location
+   ```
+
+   On Windows:
+
+   ```console
+   $ where black
+   %LocalAppData%\Programs\Python\Python36-32\Scripts\black.exe  # possible location
+   ```
+
+   Note that if you are using a virtual environment detected by PyCharm, this is an
+   unneeded step. In this case the path to `black` is `$PyInterpreterDirectory$/black`.
+
+1. Open External tools in PyCharm/IntelliJ IDEA
+
+   On macOS:
+
+   `PyCharm -> Preferences -> Tools -> External Tools`
+
+   On Windows / Linux / BSD:
+
+   `File -> Settings -> Tools -> External Tools`
+
+1. Click the + icon to add a new external tool with the following values:
+
+   - Name: Black
+   - Description: Black is the uncompromising Python code formatter.
+   - Program: \<install_location_from_step_2>
+   - Arguments: `"$FilePath$"`
+
+1. Format the currently opened file by selecting `Tools -> External Tools -> black`.
+
+   - Alternatively, you can set a keyboard shortcut by navigating to
+     `Preferences or Settings -> Keymap -> External Tools -> External Tools - Black`.
+
+### As file watcher
+
+1. Install `black`.
+
+   ```console
+   $ pip install black
+   ```
+
+1. Locate your `black` installation folder.
+
+   On macOS / Linux / BSD:
+
+   ```console
+   $ which black
+   /usr/local/bin/black  # possible location
+   ```
+
+   On Windows:
+
+   ```console
+   $ where black
+   %LocalAppData%\Programs\Python\Python36-32\Scripts\black.exe  # possible location
+   ```
+
+   Note that if you are using a virtual environment detected by PyCharm, this is an
+   unneeded step. In this case the path to `black` is `$PyInterpreterDirectory$/black`.
+
+1. Make sure you have the
+   [File Watchers](https://plugins.jetbrains.com/plugin/7177-file-watchers) plugin
+   installed.
+1. Go to `Preferences or Settings -> Tools -> File Watchers` and click `+` to add a new
+   watcher:
+   - Name: Black
+   - File type: Python
+   - Scope: Project Files
+   - Program: \<install_location_from_step_2>
+   - Arguments: `$FilePath$`
+   - Output paths to refresh: `$FilePath$`
+   - Working directory: `$ProjectFileDir$`
+
+- In Advanced Options
+  - Uncheck "Auto-save edited files to trigger the watcher"
+  - Uncheck "Trigger the watcher on external changes"
+
 ## Wing IDE
 
 Wing IDE supports `black` via **Preference Settings** for system wide settings and

From 60a2e8e2c26d6312cd86b40f680c5037571acafc Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Mon, 16 Jan 2023 12:26:03 -0800
Subject: [PATCH 0697/1034] Fix two docstring crashes (#3451)

---
 CHANGES.md                              |  1 +
 src/black/linegen.py                    |  4 ++++
 tests/data/miscellaneous/linelength6.py |  5 +++++
 tests/data/simple_cases/docstring.py    | 11 +++++++++++
 tests/test_format.py                    |  7 +++++++
 5 files changed, 28 insertions(+)
 create mode 100644 tests/data/miscellaneous/linelength6.py

diff --git a/CHANGES.md b/CHANGES.md
index 2da0fb4720c..17dc0d686df 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -32,6 +32,7 @@
 - Long values in dict literals are now wrapped in parentheses; correspondingly
   unnecessary parentheses around short values in dict literals are now removed; long
   string lambda values are now wrapped in parentheses (#3440)
+- Fix two crashes in preview style involving edge cases with docstrings (#3451)
 - Exclude string type annotations from improved string processing; fix crash when the
   return type annotation is stringified and spans across multiple lines (#3462)
 
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 4da75b28235..da41886f80d 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -401,6 +401,7 @@ def visit_STRING(self, leaf: Leaf) -> Iterator[Line]:
             else:
                 docstring = docstring.strip()
 
+            has_trailing_backslash = False
             if docstring:
                 # Add some padding if the docstring starts / ends with a quote mark.
                 if docstring[0] == quote_char:
@@ -413,6 +414,7 @@ def visit_STRING(self, leaf: Leaf) -> Iterator[Line]:
                         # Odd number of tailing backslashes, add some padding to
                         # avoid escaping the closing string quote.
                         docstring += " "
+                        has_trailing_backslash = True
             elif not docstring_started_empty:
                 docstring = " "
 
@@ -435,6 +437,8 @@ def visit_STRING(self, leaf: Leaf) -> Iterator[Line]:
                 if (
                     len(lines) > 1
                     and last_line_length + quote_len > self.mode.line_length
+                    and len(indent) + quote_len <= self.mode.line_length
+                    and not has_trailing_backslash
                 ):
                     leaf.value = prefix + quote + docstring + "\n" + indent + quote
                 else:
diff --git a/tests/data/miscellaneous/linelength6.py b/tests/data/miscellaneous/linelength6.py
new file mode 100644
index 00000000000..4fb342726f5
--- /dev/null
+++ b/tests/data/miscellaneous/linelength6.py
@@ -0,0 +1,5 @@
+# Regression test for #3427, which reproes only with line length <= 6
+def f():
+    """
+    x
+    """
diff --git a/tests/data/simple_cases/docstring.py b/tests/data/simple_cases/docstring.py
index f08bba575fe..c31d6a68783 100644
--- a/tests/data/simple_cases/docstring.py
+++ b/tests/data/simple_cases/docstring.py
@@ -173,6 +173,11 @@ def multiline_backslash_2():
   '''
   hey there \ '''
 
+# Regression test for #3425
+def multiline_backslash_really_long_dont_crash():
+    """
+    hey there hello guten tag hi hoow are you ola zdravstvuyte ciao como estas ca va \ """
+
 
 def multiline_backslash_3():
   '''
@@ -391,6 +396,12 @@ def multiline_backslash_2():
     hey there \ """
 
 
+# Regression test for #3425
+def multiline_backslash_really_long_dont_crash():
+    """
+    hey there hello guten tag hi hoow are you ola zdravstvuyte ciao como estas ca va \ """
+
+
 def multiline_backslash_3():
     """
     already escaped \\"""
diff --git a/tests/test_format.py b/tests/test_format.py
index 01cd61eef63..0816bbd3692 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -146,6 +146,13 @@ def test_docstring_no_string_normalization() -> None:
     assert_format(source, expected, mode)
 
 
+def test_docstring_line_length_6() -> None:
+    """Like test_docstring but with line length set to 6."""
+    source, expected = read_data("miscellaneous", "linelength6")
+    mode = black.Mode(line_length=6)
+    assert_format(source, expected, mode)
+
+
 def test_preview_docstring_no_string_normalization() -> None:
     """
     Like test_docstring but with string normalization off *and* the preview style

From 24469c9bd14c3ddb4739f24c661aeb725f2decd5 Mon Sep 17 00:00:00 2001
From: Bartosz Sokorski <b.sokorski@gmail.com>
Date: Wed, 18 Jan 2023 03:01:03 +0100
Subject: [PATCH 0698/1034] Add flake8-bugbear B907 to ignore list (#3503)

---
 .flake8 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.flake8 b/.flake8
index eddaaba81fd..7bc346a09c1 100644
--- a/.flake8
+++ b/.flake8
@@ -1,6 +1,6 @@
 [flake8]
 # B905 should be enabled when we drop support for 3.9
-ignore = E203, E266, E501, W503, B905
+ignore = E203, E266, E501, W503, B905, B907
 # line length is intentionally set to 80 here because black uses Bugbear
 # See https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#line-length for more details
 max-line-length = 80

From 7e6d3fac197395b0a2b380cc60811536fe23626b Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Tue, 17 Jan 2023 22:25:05 -0800
Subject: [PATCH 0699/1034] Fix crash with walrus + await + with (#3473)

Fixes #3472
---
 CHANGES.md                                    |  2 +
 src/black/linegen.py                          |  4 ++
 src/black/nodes.py                            | 11 +++++
 .../data/fast/pep_572_do_not_remove_parens.py |  4 ++
 tests/data/py_38/pep_572_remove_parens.py     | 40 +++++++++++++++++++
 5 files changed, 61 insertions(+)

diff --git a/CHANGES.md b/CHANGES.md
index 17dc0d686df..97b68b90fb1 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -35,6 +35,8 @@
 - Fix two crashes in preview style involving edge cases with docstrings (#3451)
 - Exclude string type annotations from improved string processing; fix crash when the
   return type annotation is stringified and spans across multiple lines (#3462)
+- Fix several crashes in preview style with walrus operators used in `with` statements
+  or tuples (#3473)
 
 ### Configuration
 
diff --git a/src/black/linegen.py b/src/black/linegen.py
index da41886f80d..14f851161fd 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -46,6 +46,7 @@
     is_rpar_token,
     is_stub_body,
     is_stub_suite,
+    is_tuple_containing_walrus,
     is_vararg,
     is_walrus_assignment,
     is_yield,
@@ -1279,6 +1280,7 @@ def maybe_make_parens_invisible_in_atom(
             not remove_brackets_around_comma
             and max_delimiter_priority_in_atom(node) >= COMMA_PRIORITY
         )
+        or is_tuple_containing_walrus(node)
     ):
         return False
 
@@ -1290,9 +1292,11 @@ def maybe_make_parens_invisible_in_atom(
             syms.return_stmt,
             syms.except_clause,
             syms.funcdef,
+            syms.with_stmt,
             # these ones aren't useful to end users, but they do please fuzzers
             syms.for_stmt,
             syms.del_stmt,
+            syms.for_stmt,
         ]:
             return False
 
diff --git a/src/black/nodes.py b/src/black/nodes.py
index a11fb7cc071..a588077f4de 100644
--- a/src/black/nodes.py
+++ b/src/black/nodes.py
@@ -563,6 +563,17 @@ def is_one_tuple(node: LN) -> bool:
     )
 
 
+def is_tuple_containing_walrus(node: LN) -> bool:
+    """Return True if `node` holds a tuple that contains a walrus operator."""
+    if node.type != syms.atom:
+        return False
+    gexp = unwrap_singleton_parenthesis(node)
+    if gexp is None or gexp.type != syms.testlist_gexp:
+        return False
+
+    return any(child.type == syms.namedexpr_test for child in gexp.children)
+
+
 def is_one_sequence_between(
     opening: Leaf,
     closing: Leaf,
diff --git a/tests/data/fast/pep_572_do_not_remove_parens.py b/tests/data/fast/pep_572_do_not_remove_parens.py
index 20e80a69377..05619ddcc2b 100644
--- a/tests/data/fast/pep_572_do_not_remove_parens.py
+++ b/tests/data/fast/pep_572_do_not_remove_parens.py
@@ -19,3 +19,7 @@
 @(please := stop)
 def sigh():
     pass
+
+
+for (x := 3, y := 4) in y:
+    pass
diff --git a/tests/data/py_38/pep_572_remove_parens.py b/tests/data/py_38/pep_572_remove_parens.py
index 9718d95b499..4e95fb07f3a 100644
--- a/tests/data/py_38/pep_572_remove_parens.py
+++ b/tests/data/py_38/pep_572_remove_parens.py
@@ -49,6 +49,26 @@ def a():
 def this_is_so_dumb() -> (please := no):
     pass
 
+async def await_the_walrus():
+    with (x := y):
+        pass
+
+    with (x := y) as z, (a := b) as c:
+        pass
+
+    with (x := await y):
+        pass
+
+    with (x := await a, y := await b):
+        pass
+
+    # Ideally we should remove one set of parentheses
+    with ((x := await a, y := await b)):
+        pass
+
+    with (x := await a), (y := await b):
+        pass
+
 
 # output
 if foo := 0:
@@ -103,3 +123,23 @@ def a():
 def this_is_so_dumb() -> (please := no):
     pass
 
+
+async def await_the_walrus():
+    with (x := y):
+        pass
+
+    with (x := y) as z, (a := b) as c:
+        pass
+
+    with (x := await y):
+        pass
+
+    with (x := await a, y := await b):
+        pass
+
+    # Ideally we should remove one set of parentheses
+    with ((x := await a, y := await b)):
+        pass
+
+    with (x := await a), (y := await b):
+        pass

From 18fb88486d434dbde9b2a9c98f008a71cf5d941d Mon Sep 17 00:00:00 2001
From: Antonio Ossa-Guerra <aaossa@uc.cl>
Date: Wed, 18 Jan 2023 23:38:27 -0300
Subject: [PATCH 0700/1034] Fix false symlink detection claims in verbose
 output (#3385)

When trying to format a project from the outside, the verbose output
shows says that there are symbolic links that points outside of the
project, but displays the wrong project path, meaning that these
messages are false positives.

This bug is triggered when the command is executed from outside a
project on a folder inside it, causing an inconsistency between the
path to the detected project root and the relative path to the target
contents.

The fix is to normalize the target path using the project root before
processing the sources, which removes the presence of the incorrect
messages.

---

The test attemps to emulate the behavior of the CLI as closely as
posible by patching some `pathlib.Path` methods and passing certain
reference paths to the context object and `black.get_sources`.

Before the associated fix was introduced, this test failed because
some of the captured files reported the presence of a symlink due to
an incorrectly formated path. The test also asserts that only a single
file is reported as ignored, which is part of the expected behavior.

Signed-off-by: Antonio Ossa Guerra <aaossa@uc.cl>
---
 CHANGES.md            |  2 ++
 src/black/__init__.py |  3 ++-
 tests/test_black.py   | 47 +++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 51 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index 97b68b90fb1..313536e8480 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -66,6 +66,8 @@
 
 - Verbose logging now shows the values of `pyproject.toml` configuration variables
   (#3392)
+- Fix false symlink detection messages in verbose output due to using an incorrect
+  relative path to the project root (#3385)
 
 ### _Blackd_
 
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 9f44722bfae..5d35c805bac 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -673,10 +673,11 @@ def get_sources(
 
             sources.add(p)
         elif p.is_dir():
+            p = root / normalize_path_maybe_ignore(p, ctx.obj["root"], report)
             if using_default_exclude:
                 gitignore = {
                     root: root_gitignore,
-                    root / p: get_gitignore(p),
+                    p: get_gitignore(p),
                 }
             sources.update(
                 gen_python_files(
diff --git a/tests/test_black.py b/tests/test_black.py
index dda10555c97..44d617244f1 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -475,6 +475,53 @@ def test_tab_comment_indentation(self) -> None:
         self.assertFormatEqual(contents_spc, fs(contents_spc))
         self.assertFormatEqual(contents_spc, fs(contents_tab))
 
+    def test_false_positive_symlink_output_issue_3384(self) -> None:
+        # Emulate the behavior when using the CLI (`black ./child  --verbose`), which
+        # involves patching some `pathlib.Path` methods. In particular, `is_dir` is
+        # patched only on its first call: when checking if "./child" is a directory it
+        # should return True. The "./child" folder exists relative to the cwd when
+        # running from CLI, but fails when running the tests because cwd is different
+        project_root = Path(THIS_DIR / "data" / "nested_gitignore_tests")
+        working_directory = project_root / "root"
+        target_abspath = working_directory / "child"
+        target_contents = (
+            src.relative_to(working_directory) for src in target_abspath.iterdir()
+        )
+
+        def mock_n_calls(responses: List[bool]) -> Callable[[], bool]:
+            def _mocked_calls() -> bool:
+                if responses:
+                    return responses.pop(0)
+                return False
+
+            return _mocked_calls
+
+        with patch("pathlib.Path.iterdir", return_value=target_contents), patch(
+            "pathlib.Path.cwd", return_value=working_directory
+        ), patch("pathlib.Path.is_dir", side_effect=mock_n_calls([True])):
+            ctx = FakeContext()
+            ctx.obj["root"] = project_root
+            report = MagicMock(verbose=True)
+            black.get_sources(
+                ctx=ctx,
+                src=("./child",),
+                quiet=False,
+                verbose=True,
+                include=DEFAULT_INCLUDE,
+                exclude=None,
+                report=report,
+                extend_exclude=None,
+                force_exclude=None,
+                stdin_filename=None,
+            )
+        assert not any(
+            mock_args[1].startswith("is a symbolic link that points outside")
+            for _, mock_args, _ in report.path_ignored.mock_calls
+        ), "A symbolic link was reported."
+        report.path_ignored.assert_called_once_with(
+            Path("child", "b.py"), "matches a .gitignore file content"
+        )
+
     def test_report_verbose(self) -> None:
         report = Report(verbose=True)
         out_lines = []

From 91e1e1328aa0a11ef50017316ff97149886e1b05 Mon Sep 17 00:00:00 2001
From: "Yilei \"Dolee\" Yang" <yileiyang@google.com>
Date: Fri, 20 Jan 2023 04:14:05 -0800
Subject: [PATCH 0701/1034] Wrap multiple context managers in parentheses when
 targeting Python 3.9+ (#3489)

---
 CHANGES.md                                    |   1 +
 src/black/__init__.py                         |  28 ++++-
 src/black/linegen.py                          | 101 +++++++++++++----
 src/black/mode.py                             |   5 +
 .../auto_detect/features_3_10.py              |  35 ++++++
 .../auto_detect/features_3_11.py              |  37 +++++++
 .../auto_detect/features_3_8.py               |  30 +++++
 .../auto_detect/features_3_9.py               |  34 ++++++
 .../targeting_py38.py                         |  38 +++++++
 .../targeting_py39.py                         | 104 ++++++++++++++++++
 tests/test_format.py                          |  24 ++++
 11 files changed, 416 insertions(+), 21 deletions(-)
 create mode 100644 tests/data/preview_context_managers/auto_detect/features_3_10.py
 create mode 100644 tests/data/preview_context_managers/auto_detect/features_3_11.py
 create mode 100644 tests/data/preview_context_managers/auto_detect/features_3_8.py
 create mode 100644 tests/data/preview_context_managers/auto_detect/features_3_9.py
 create mode 100644 tests/data/preview_context_managers/targeting_py38.py
 create mode 100644 tests/data/preview_context_managers/targeting_py39.py

diff --git a/CHANGES.md b/CHANGES.md
index 313536e8480..1450278341b 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -35,6 +35,7 @@
 - Fix two crashes in preview style involving edge cases with docstrings (#3451)
 - Exclude string type annotations from improved string processing; fix crash when the
   return type annotation is stringified and spans across multiple lines (#3462)
+- Wrap multiple context managers in parentheses when targeting Python 3.9+ (#3489)
 - Fix several crashes in preview style with walrus operators used in `with` statements
   or tuples (#3473)
 
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 5d35c805bac..daf6f88f58e 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -1096,8 +1096,13 @@ def _format_str_once(src_contents: str, *, mode: Mode) -> str:
         future_imports = get_future_imports(src_node)
         versions = detect_target_versions(src_node, future_imports=future_imports)
 
+    context_manager_features = {
+        feature
+        for feature in {Feature.PARENTHESIZED_CONTEXT_MANAGERS}
+        if supports_feature(versions, feature)
+    }
     normalize_fmt_off(src_node, preview=mode.preview)
-    lines = LineGenerator(mode=mode)
+    lines = LineGenerator(mode=mode, features=context_manager_features)
     elt = EmptyLineTracker(mode=mode)
     split_line_features = {
         feature
@@ -1159,6 +1164,10 @@ def get_features_used(  # noqa: C901
     - relaxed decorator syntax;
     - usage of __future__ flags (annotations);
     - print / exec statements;
+    - parenthesized context managers;
+    - match statements;
+    - except* clause;
+    - variadic generics;
     """
     features: Set[Feature] = set()
     if future_imports:
@@ -1234,6 +1243,23 @@ def get_features_used(  # noqa: C901
         ):
             features.add(Feature.ANN_ASSIGN_EXTENDED_RHS)
 
+        elif (
+            n.type == syms.with_stmt
+            and len(n.children) > 2
+            and n.children[1].type == syms.atom
+        ):
+            atom_children = n.children[1].children
+            if (
+                len(atom_children) == 3
+                and atom_children[0].type == token.LPAR
+                and atom_children[1].type == syms.testlist_gexp
+                and atom_children[2].type == token.RPAR
+            ):
+                features.add(Feature.PARENTHESIZED_CONTEXT_MANAGERS)
+
+        elif n.type == syms.match_stmt:
+            features.add(Feature.PATTERN_MATCHING)
+
         elif (
             n.type == syms.except_clause
             and len(n.children) >= 2
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 14f851161fd..2f50257a930 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -90,8 +90,9 @@ class LineGenerator(Visitor[Line]):
     in ways that will no longer stringify to valid Python code on the tree.
     """
 
-    def __init__(self, mode: Mode) -> None:
+    def __init__(self, mode: Mode, features: Collection[Feature]) -> None:
         self.mode = mode
+        self.features = features
         self.current_line: Line
         self.__post_init__()
 
@@ -191,7 +192,9 @@ def visit_stmt(
         `parens` holds a set of string leaf values immediately after which
         invisible parens should be put.
         """
-        normalize_invisible_parens(node, parens_after=parens, preview=self.mode.preview)
+        normalize_invisible_parens(
+            node, parens_after=parens, mode=self.mode, features=self.features
+        )
         for child in node.children:
             if is_name_token(child) and child.value in keywords:
                 yield from self.line()
@@ -244,7 +247,9 @@ def visit_funcdef(self, node: Node) -> Iterator[Line]:
 
     def visit_match_case(self, node: Node) -> Iterator[Line]:
         """Visit either a match or case statement."""
-        normalize_invisible_parens(node, parens_after=set(), preview=self.mode.preview)
+        normalize_invisible_parens(
+            node, parens_after=set(), mode=self.mode, features=self.features
+        )
 
         yield from self.line()
         for child in node.children:
@@ -1090,7 +1095,7 @@ def normalize_prefix(leaf: Leaf, *, inside_brackets: bool) -> None:
 
 
 def normalize_invisible_parens(
-    node: Node, parens_after: Set[str], *, preview: bool
+    node: Node, parens_after: Set[str], *, mode: Mode, features: Collection[Feature]
 ) -> None:
     """Make existing optional parentheses invisible or create new ones.
 
@@ -1100,17 +1105,24 @@ def normalize_invisible_parens(
     Standardizes on visible parentheses for single-element tuples, and keeps
     existing visible parentheses for other tuples and generator expressions.
     """
-    for pc in list_comments(node.prefix, is_endmarker=False, preview=preview):
+    for pc in list_comments(node.prefix, is_endmarker=False, preview=mode.preview):
         if pc.value in FMT_OFF:
             # This `node` has a prefix with `# fmt: off`, don't mess with parens.
             return
+
+    # The multiple context managers grammar has a different pattern, thus this is
+    # separate from the for-loop below. This possibly wraps them in invisible parens,
+    # and later will be removed in remove_with_parens when needed.
+    if node.type == syms.with_stmt:
+        _maybe_wrap_cms_in_parens(node, mode, features)
+
     check_lpar = False
     for index, child in enumerate(list(node.children)):
         # Fixes a bug where invisible parens are not properly stripped from
         # assignment statements that contain type annotations.
         if isinstance(child, Node) and child.type == syms.annassign:
             normalize_invisible_parens(
-                child, parens_after=parens_after, preview=preview
+                child, parens_after=parens_after, mode=mode, features=features
             )
 
         # Add parentheses around long tuple unpacking in assignments.
@@ -1123,7 +1135,7 @@ def normalize_invisible_parens(
 
         if check_lpar:
             if (
-                preview
+                mode.preview
                 and child.type == syms.atom
                 and node.type == syms.for_stmt
                 and isinstance(child.prev_sibling, Leaf)
@@ -1136,7 +1148,9 @@ def normalize_invisible_parens(
                     remove_brackets_around_comma=True,
                 ):
                     wrap_in_parentheses(node, child, visible=False)
-            elif preview and isinstance(child, Node) and node.type == syms.with_stmt:
+            elif (
+                mode.preview and isinstance(child, Node) and node.type == syms.with_stmt
+            ):
                 remove_with_parens(child, node)
             elif child.type == syms.atom:
                 if maybe_make_parens_invisible_in_atom(
@@ -1147,17 +1161,7 @@ def normalize_invisible_parens(
             elif is_one_tuple(child):
                 wrap_in_parentheses(node, child, visible=True)
             elif node.type == syms.import_from:
-                # "import from" nodes store parentheses directly as part of
-                # the statement
-                if is_lpar_token(child):
-                    assert is_rpar_token(node.children[-1])
-                    # make parentheses invisible
-                    child.value = ""
-                    node.children[-1].value = ""
-                elif child.type != token.STAR:
-                    # insert invisible parentheses
-                    node.insert_child(index, Leaf(token.LPAR, ""))
-                    node.append_child(Leaf(token.RPAR, ""))
+                _normalize_import_from(node, child, index)
                 break
             elif (
                 index == 1
@@ -1172,13 +1176,27 @@ def normalize_invisible_parens(
             elif not (isinstance(child, Leaf) and is_multiline_string(child)):
                 wrap_in_parentheses(node, child, visible=False)
 
-        comma_check = child.type == token.COMMA if preview else False
+        comma_check = child.type == token.COMMA if mode.preview else False
 
         check_lpar = isinstance(child, Leaf) and (
             child.value in parens_after or comma_check
         )
 
 
+def _normalize_import_from(parent: Node, child: LN, index: int) -> None:
+    # "import from" nodes store parentheses directly as part of
+    # the statement
+    if is_lpar_token(child):
+        assert is_rpar_token(parent.children[-1])
+        # make parentheses invisible
+        child.value = ""
+        parent.children[-1].value = ""
+    elif child.type != token.STAR:
+        # insert invisible parentheses
+        parent.insert_child(index, Leaf(token.LPAR, ""))
+        parent.append_child(Leaf(token.RPAR, ""))
+
+
 def remove_await_parens(node: Node) -> None:
     if node.children[0].type == token.AWAIT and len(node.children) > 1:
         if (
@@ -1215,6 +1233,49 @@ def remove_await_parens(node: Node) -> None:
                 remove_await_parens(bracket_contents)
 
 
+def _maybe_wrap_cms_in_parens(
+    node: Node, mode: Mode, features: Collection[Feature]
+) -> None:
+    """When enabled and safe, wrap the multiple context managers in invisible parens.
+
+    It is only safe when `features` contain Feature.PARENTHESIZED_CONTEXT_MANAGERS.
+    """
+    if (
+        Feature.PARENTHESIZED_CONTEXT_MANAGERS not in features
+        or Preview.wrap_multiple_context_managers_in_parens not in mode
+        or len(node.children) <= 2
+        # If it's an atom, it's already wrapped in parens.
+        or node.children[1].type == syms.atom
+    ):
+        return
+    colon_index: Optional[int] = None
+    for i in range(2, len(node.children)):
+        if node.children[i].type == token.COLON:
+            colon_index = i
+            break
+    if colon_index is not None:
+        lpar = Leaf(token.LPAR, "")
+        rpar = Leaf(token.RPAR, "")
+        context_managers = node.children[1:colon_index]
+        for child in context_managers:
+            child.remove()
+        # After wrapping, the with_stmt will look like this:
+        #   with_stmt
+        #     NAME 'with'
+        #     atom
+        #       LPAR ''
+        #       testlist_gexp
+        #         ... <-- context_managers
+        #       /testlist_gexp
+        #       RPAR ''
+        #     /atom
+        #     COLON ':'
+        new_child = Node(
+            syms.atom, [lpar, Node(syms.testlist_gexp, context_managers), rpar]
+        )
+        node.insert_child(1, new_child)
+
+
 def remove_with_parens(node: Node, parent: Node) -> None:
     """Recursively hide optional parens in `with` statements."""
     # Removing all unnecessary parentheses in with statements in one pass is a tad
diff --git a/src/black/mode.py b/src/black/mode.py
index 775805ae960..af0706e6a0b 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -50,6 +50,7 @@ class Feature(Enum):
     EXCEPT_STAR = 14
     VARIADIC_GENERICS = 15
     DEBUG_F_STRINGS = 16
+    PARENTHESIZED_CONTEXT_MANAGERS = 17
     FORCE_OPTIONAL_PARENTHESES = 50
 
     # __future__ flags
@@ -106,6 +107,7 @@ class Feature(Enum):
         Feature.POS_ONLY_ARGUMENTS,
         Feature.UNPACKING_ON_FLOW,
         Feature.ANN_ASSIGN_EXTENDED_RHS,
+        Feature.PARENTHESIZED_CONTEXT_MANAGERS,
     },
     TargetVersion.PY310: {
         Feature.F_STRINGS,
@@ -120,6 +122,7 @@ class Feature(Enum):
         Feature.POS_ONLY_ARGUMENTS,
         Feature.UNPACKING_ON_FLOW,
         Feature.ANN_ASSIGN_EXTENDED_RHS,
+        Feature.PARENTHESIZED_CONTEXT_MANAGERS,
         Feature.PATTERN_MATCHING,
     },
     TargetVersion.PY311: {
@@ -135,6 +138,7 @@ class Feature(Enum):
         Feature.POS_ONLY_ARGUMENTS,
         Feature.UNPACKING_ON_FLOW,
         Feature.ANN_ASSIGN_EXTENDED_RHS,
+        Feature.PARENTHESIZED_CONTEXT_MANAGERS,
         Feature.PATTERN_MATCHING,
         Feature.EXCEPT_STAR,
         Feature.VARIADIC_GENERICS,
@@ -164,6 +168,7 @@ class Preview(Enum):
     parenthesize_conditional_expressions = auto()
     skip_magic_trailing_comma_in_subscript = auto()
     wrap_long_dict_values_in_parens = auto()
+    wrap_multiple_context_managers_in_parens = auto()
 
 
 class Deprecated(UserWarning):
diff --git a/tests/data/preview_context_managers/auto_detect/features_3_10.py b/tests/data/preview_context_managers/auto_detect/features_3_10.py
new file mode 100644
index 00000000000..1458df1cb41
--- /dev/null
+++ b/tests/data/preview_context_managers/auto_detect/features_3_10.py
@@ -0,0 +1,35 @@
+# This file uses pattern matching introduced in Python 3.10.
+
+
+match http_code:
+    case 404:
+        print("Not found")
+
+
+with \
+     make_context_manager1() as cm1, \
+     make_context_manager2() as cm2, \
+     make_context_manager3() as cm3, \
+     make_context_manager4() as cm4 \
+:
+    pass
+
+
+# output
+
+
+# This file uses pattern matching introduced in Python 3.10.
+
+
+match http_code:
+    case 404:
+        print("Not found")
+
+
+with (
+    make_context_manager1() as cm1,
+    make_context_manager2() as cm2,
+    make_context_manager3() as cm3,
+    make_context_manager4() as cm4,
+):
+    pass
diff --git a/tests/data/preview_context_managers/auto_detect/features_3_11.py b/tests/data/preview_context_managers/auto_detect/features_3_11.py
new file mode 100644
index 00000000000..f83c5330ab3
--- /dev/null
+++ b/tests/data/preview_context_managers/auto_detect/features_3_11.py
@@ -0,0 +1,37 @@
+# This file uses except* clause in Python 3.11.
+
+
+try:
+    some_call()
+except* Error as e:
+    pass
+
+
+with \
+     make_context_manager1() as cm1, \
+     make_context_manager2() as cm2, \
+     make_context_manager3() as cm3, \
+     make_context_manager4() as cm4 \
+:
+    pass
+
+
+# output
+
+
+# This file uses except* clause in Python 3.11.
+
+
+try:
+    some_call()
+except* Error as e:
+    pass
+
+
+with (
+    make_context_manager1() as cm1,
+    make_context_manager2() as cm2,
+    make_context_manager3() as cm3,
+    make_context_manager4() as cm4,
+):
+    pass
diff --git a/tests/data/preview_context_managers/auto_detect/features_3_8.py b/tests/data/preview_context_managers/auto_detect/features_3_8.py
new file mode 100644
index 00000000000..e05094e1421
--- /dev/null
+++ b/tests/data/preview_context_managers/auto_detect/features_3_8.py
@@ -0,0 +1,30 @@
+# This file doesn't use any Python 3.9+ only grammars.
+
+
+# Make sure parens around a single context manager don't get autodetected as
+# Python 3.9+.
+with (a):
+    pass
+
+
+with \
+     make_context_manager1() as cm1, \
+     make_context_manager2() as cm2, \
+     make_context_manager3() as cm3, \
+     make_context_manager4() as cm4 \
+:
+    pass
+
+
+# output
+# This file doesn't use any Python 3.9+ only grammars.
+
+
+# Make sure parens around a single context manager don't get autodetected as
+# Python 3.9+.
+with a:
+    pass
+
+
+with make_context_manager1() as cm1, make_context_manager2() as cm2, make_context_manager3() as cm3, make_context_manager4() as cm4:
+    pass
diff --git a/tests/data/preview_context_managers/auto_detect/features_3_9.py b/tests/data/preview_context_managers/auto_detect/features_3_9.py
new file mode 100644
index 00000000000..0d28f993108
--- /dev/null
+++ b/tests/data/preview_context_managers/auto_detect/features_3_9.py
@@ -0,0 +1,34 @@
+# This file uses parenthesized context managers introduced in Python 3.9.
+
+
+with \
+     make_context_manager1() as cm1, \
+     make_context_manager2() as cm2, \
+     make_context_manager3() as cm3, \
+     make_context_manager4() as cm4 \
+:
+    pass
+
+
+with (
+     new_new_new1() as cm1,
+     new_new_new2()
+):
+    pass
+
+
+# output
+# This file uses parenthesized context managers introduced in Python 3.9.
+
+
+with (
+    make_context_manager1() as cm1,
+    make_context_manager2() as cm2,
+    make_context_manager3() as cm3,
+    make_context_manager4() as cm4,
+):
+    pass
+
+
+with new_new_new1() as cm1, new_new_new2():
+    pass
diff --git a/tests/data/preview_context_managers/targeting_py38.py b/tests/data/preview_context_managers/targeting_py38.py
new file mode 100644
index 00000000000..6ec4684e441
--- /dev/null
+++ b/tests/data/preview_context_managers/targeting_py38.py
@@ -0,0 +1,38 @@
+with \
+     make_context_manager1() as cm1, \
+     make_context_manager2() as cm2, \
+     make_context_manager3() as cm3, \
+     make_context_manager4() as cm4 \
+:
+    pass
+
+
+with \
+     make_context_manager1() as cm1, \
+     make_context_manager2(), \
+     make_context_manager3() as cm3, \
+     make_context_manager4() \
+:
+    pass
+
+
+with \
+     new_new_new1() as cm1, \
+     new_new_new2() \
+:
+    pass
+
+
+# output
+
+
+with make_context_manager1() as cm1, make_context_manager2() as cm2, make_context_manager3() as cm3, make_context_manager4() as cm4:
+    pass
+
+
+with make_context_manager1() as cm1, make_context_manager2(), make_context_manager3() as cm3, make_context_manager4():
+    pass
+
+
+with new_new_new1() as cm1, new_new_new2():
+    pass
diff --git a/tests/data/preview_context_managers/targeting_py39.py b/tests/data/preview_context_managers/targeting_py39.py
new file mode 100644
index 00000000000..5cb8763040a
--- /dev/null
+++ b/tests/data/preview_context_managers/targeting_py39.py
@@ -0,0 +1,104 @@
+with \
+     make_context_manager1() as cm1, \
+     make_context_manager2() as cm2, \
+     make_context_manager3() as cm3, \
+     make_context_manager4() as cm4 \
+:
+    pass
+
+
+# Leading comment
+with \
+     make_context_manager1() as cm1, \
+     make_context_manager2(), \
+     make_context_manager3() as cm3, \
+     make_context_manager4() \
+:
+    pass
+
+
+with \
+     new_new_new1() as cm1, \
+     new_new_new2() \
+:
+    pass
+
+
+with (
+     new_new_new1() as cm1,
+     new_new_new2()
+):
+    pass
+
+
+# Leading comment.
+with (
+     # First comment.
+     new_new_new1() as cm1,
+     # Second comment.
+     new_new_new2()
+     # Last comment.
+):
+    pass
+
+
+with \
+    this_is_a_very_long_call(looong_arg1=looong_value1, looong_arg2=looong_value2) as cm1, \
+    this_is_a_very_long_call(looong_arg1=looong_value1, looong_arg2=looong_value2, looong_arg3=looong_value3, looong_arg4=looong_value4) as cm2 \
+:
+    pass
+
+
+# output
+
+
+with (
+    make_context_manager1() as cm1,
+    make_context_manager2() as cm2,
+    make_context_manager3() as cm3,
+    make_context_manager4() as cm4,
+):
+    pass
+
+
+# Leading comment
+with (
+    make_context_manager1() as cm1,
+    make_context_manager2(),
+    make_context_manager3() as cm3,
+    make_context_manager4(),
+):
+    pass
+
+
+with new_new_new1() as cm1, new_new_new2():
+    pass
+
+
+with new_new_new1() as cm1, new_new_new2():
+    pass
+
+
+# Leading comment.
+with (
+    # First comment.
+    new_new_new1() as cm1,
+    # Second comment.
+    new_new_new2()
+    # Last comment.
+):
+    pass
+
+
+with (
+    this_is_a_very_long_call(
+        looong_arg1=looong_value1, looong_arg2=looong_value2
+    ) as cm1,
+    this_is_a_very_long_call(
+        looong_arg1=looong_value1,
+        looong_arg2=looong_value2,
+        looong_arg3=looong_value3,
+        looong_arg4=looong_value4,
+    ) as cm2,
+):
+    pass
diff --git a/tests/test_format.py b/tests/test_format.py
index 0816bbd3692..adcbc02468d 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -1,3 +1,4 @@
+import re
 from dataclasses import replace
 from typing import Any, Iterator
 from unittest.mock import patch
@@ -58,6 +59,29 @@ def test_preview_minimum_python_310_format(filename: str) -> None:
     assert_format(source, expected, mode, minimum_version=(3, 10))
 
 
+def test_preview_context_managers_targeting_py38() -> None:
+    source, expected = read_data("preview_context_managers", "targeting_py38.py")
+    mode = black.Mode(preview=True, target_versions={black.TargetVersion.PY38})
+    assert_format(source, expected, mode, minimum_version=(3, 8))
+
+
+def test_preview_context_managers_targeting_py39() -> None:
+    source, expected = read_data("preview_context_managers", "targeting_py39.py")
+    mode = black.Mode(preview=True, target_versions={black.TargetVersion.PY39})
+    assert_format(source, expected, mode, minimum_version=(3, 9))
+
+
+@pytest.mark.parametrize(
+    "filename", all_data_cases("preview_context_managers/auto_detect")
+)
+def test_preview_context_managers_auto_detect(filename: str) -> None:
+    match = re.match(r"features_3_(\d+)", filename)
+    assert match is not None, "Unexpected filename format: %s" % filename
+    source, expected = read_data("preview_context_managers/auto_detect", filename)
+    mode = black.Mode(preview=True)
+    assert_format(source, expected, mode, minimum_version=(3, int(match.group(1))))
+
+
 # =============== #
 # Complex cases
 # ============= #

From c5df7b7d3ca5b568a81a9ccc1f647c183e8b4075 Mon Sep 17 00:00:00 2001
From: Richard Si <sichard26@gmail.com>
Date: Sat, 21 Jan 2023 02:50:00 -0500
Subject: [PATCH 0702/1034] Reenable macOS mypyc wheel build (#3511)

Hatchling implemented a workaround for the 'technically right tag but no
one understands it, including pip' issue so this should work now.
---
 .github/workflows/pypi_upload.yml | 13 ++++++-------
 1 file changed, 6 insertions(+), 7 deletions(-)

diff --git a/.github/workflows/pypi_upload.yml b/.github/workflows/pypi_upload.yml
index ee1c1fa7bcf..6b3eb903d84 100644
--- a/.github/workflows/pypi_upload.yml
+++ b/.github/workflows/pypi_upload.yml
@@ -47,13 +47,12 @@ jobs:
           - os: macos-11
             name: macos-x86_64
             macos_arch: "x86_64"
-          # Only build x86_64 wheels on macos until #3312 is fixed
-          # - os: macos-11
-          #   name: macos-arm64
-          #   macos_arch: "arm64"
-          # - os: macos-11
-          #   name: macos-universal2
-          #   macos_arch: "universal2"
+          - os: macos-11
+            name: macos-arm64
+            macos_arch: "arm64"
+          - os: macos-11
+            name: macos-universal2
+            macos_arch: "universal2"
 
     steps:
       - uses: actions/checkout@v3

From 1557f7d3a380ed38801f5fada27550c10f89870f Mon Sep 17 00:00:00 2001
From: Michael Eliachevitch <m.eliachevitch@posteo.de>
Date: Sun, 22 Jan 2023 06:20:54 +0100
Subject: [PATCH 0703/1034] Use dashes for pycodestyle max line length config
 (#3513)

The option is `max-line-length` with dashes, not underscores. The config option name is given in the output of `pycodestyle -h`, which can also be checked on https://pep8.readthedocs.io/en/stable/intro.html#example-usage-and-output:
```
Configuration:
    The project options are read from the [pycodestyle] section of the
    tox.ini file or the setup.cfg file located in any parent folder of the
    path(s) being processed.  Allowed options are: exclude, filename,
    select, ignore, max-line-length, max-doc-length, hang-closing, count,
    format, quiet, show-pep8, show-source, statistics, verbose
```
---
 docs/guides/using_black_with_other_tools.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/guides/using_black_with_other_tools.md b/docs/guides/using_black_with_other_tools.md
index 7bc0726dc27..9356caaf0bd 100644
--- a/docs/guides/using_black_with_other_tools.md
+++ b/docs/guides/using_black_with_other_tools.md
@@ -260,7 +260,7 @@ max-line-length = "88"
 #### Configuration
 
 ```
-max_line_length = 88
+max-line-length = 88
 ignore = E203
 ```
 

From eabff673b37c5430d4cf72fa050a189a57be2deb Mon Sep 17 00:00:00 2001
From: Shivansh-007 <shivansh-007@outlook.com>
Date: Sun, 22 Jan 2023 18:51:09 +0530
Subject: [PATCH 0704/1034] Format hex code in unicode escape sequences in
 string literals (#2916)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 CHANGES.md                                    |  1 +
 src/black/linegen.py                          |  4 ++
 src/black/mode.py                             |  1 +
 src/black/strings.py                          | 44 ++++++++++++++++++-
 .../data/preview/format_unicode_escape_seq.py | 33 ++++++++++++++
 5 files changed, 82 insertions(+), 1 deletion(-)
 create mode 100644 tests/data/preview/format_unicode_escape_seq.py

diff --git a/CHANGES.md b/CHANGES.md
index 1450278341b..e2e4b341761 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -16,6 +16,7 @@
 
 <!-- Changes that affect Black's preview style -->
 
+- Format hex code in unicode escape sequences in string literals (#2916)
 - Add parentheses around `if`-`else` expressions (#2278)
 - Improve the performance on large expressions that contain many strings (#3467)
 - Fix a crash in preview style with assert + parenthesized string (#3415)
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 2f50257a930..bfc28ca006c 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -59,6 +59,7 @@
     get_string_prefix,
     normalize_string_prefix,
     normalize_string_quotes,
+    normalize_unicode_escape_sequences,
 )
 from black.trans import (
     CannotTransform,
@@ -368,6 +369,9 @@ def visit_factor(self, node: Node) -> Iterator[Line]:
         yield from self.visit_default(node)
 
     def visit_STRING(self, leaf: Leaf) -> Iterator[Line]:
+        if Preview.hex_codes_in_unicode_sequences in self.mode:
+            normalize_unicode_escape_sequences(leaf)
+
         if is_docstring(leaf) and "\\\n" not in leaf.value:
             # We're ignoring docstrings with backslash newline escapes because changing
             # indentation of those changes the AST representation of the code.
diff --git a/src/black/mode.py b/src/black/mode.py
index af0706e6a0b..4309d4fa635 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -153,6 +153,7 @@ def supports_feature(target_versions: Set[TargetVersion], feature: Feature) -> b
 class Preview(Enum):
     """Individual preview style features."""
 
+    hex_codes_in_unicode_sequences = auto()
     annotation_parens = auto()
     empty_lines_before_class_or_def_with_leading_comments = auto()
     handle_trailing_commas_in_head = auto()
diff --git a/src/black/strings.py b/src/black/strings.py
index 9d0e2eb8430..3e3bc12fe72 100644
--- a/src/black/strings.py
+++ b/src/black/strings.py
@@ -5,7 +5,9 @@
 import re
 import sys
 from functools import lru_cache
-from typing import List, Pattern
+from typing import List, Match, Pattern
+
+from blib2to3.pytree import Leaf
 
 if sys.version_info < (3, 8):
     from typing_extensions import Final
@@ -18,6 +20,15 @@
     r"^([" + STRING_PREFIX_CHARS + r"]*)(.*)$", re.DOTALL
 )
 FIRST_NON_WHITESPACE_RE: Final = re.compile(r"\s*\t+\s*(\S)")
+UNICODE_ESCAPE_RE: Final = re.compile(
+    r"(?P<backslashes>\\+)(?P<body>"
+    r"(u(?P<u>[a-fA-F0-9]{4}))"  # Character with 16-bit hex value xxxx
+    r"|(U(?P<U>[a-fA-F0-9]{8}))"  # Character with 32-bit hex value xxxxxxxx
+    r"|(x(?P<x>[a-fA-F0-9]{2}))"  # Character with hex value hh
+    r"|(N\{(?P<N>[a-zA-Z0-9 \-]{2,})\})"  # Character named name in the Unicode database
+    r")",
+    re.VERBOSE,
+)
 
 
 def sub_twice(regex: Pattern[str], replacement: str, original: str) -> str:
@@ -236,3 +247,34 @@ def normalize_string_quotes(s: str) -> str:
         return s  # Prefer double quotes
 
     return f"{prefix}{new_quote}{new_body}{new_quote}"
+
+
+def normalize_unicode_escape_sequences(leaf: Leaf) -> None:
+    """Replace hex codes in Unicode escape sequences with lowercase representation."""
+    text = leaf.value
+    prefix = get_string_prefix(text)
+    if "r" in prefix.lower():
+        return
+
+    def replace(m: Match[str]) -> str:
+        groups = m.groupdict()
+        back_slashes = groups["backslashes"]
+
+        if len(back_slashes) % 2 == 0:
+            return back_slashes + groups["body"]
+
+        if groups["u"]:
+            # \u
+            return back_slashes + "u" + groups["u"].lower()
+        elif groups["U"]:
+            # \U
+            return back_slashes + "U" + groups["U"].lower()
+        elif groups["x"]:
+            # \x
+            return back_slashes + "x" + groups["x"].lower()
+        else:
+            assert groups["N"], f"Unexpected match: {m}"
+            # \N{}
+            return back_slashes + "N{" + groups["N"].upper() + "}"
+
+    leaf.value = re.sub(UNICODE_ESCAPE_RE, replace, text)
diff --git a/tests/data/preview/format_unicode_escape_seq.py b/tests/data/preview/format_unicode_escape_seq.py
new file mode 100644
index 00000000000..3440696c303
--- /dev/null
+++ b/tests/data/preview/format_unicode_escape_seq.py
@@ -0,0 +1,33 @@
+x = "\x1F"
+x = "\\x1B"
+x = "\\\x1B"
+x = "\U0001F60E"
+x = "\u0001F60E"
+x = r"\u0001F60E"
+x = "don't format me"
+x = "\xA3"
+x = "\u2717"
+x = "\uFaCe"
+x = "\N{ox}\N{OX}"
+x = "\N{lAtIn smaLL letteR x}"
+x = "\N{CYRILLIC small LETTER BYELORUSSIAN-UKRAINIAN I}"
+x = b"\x1Fdon't byte"
+x = rb"\x1Fdon't format"
+
+# output
+
+x = "\x1f"
+x = "\\x1B"
+x = "\\\x1b"
+x = "\U0001f60e"
+x = "\u0001F60E"
+x = r"\u0001F60E"
+x = "don't format me"
+x = "\xa3"
+x = "\u2717"
+x = "\uface"
+x = "\N{OX}\N{OX}"
+x = "\N{LATIN SMALL LETTER X}"
+x = "\N{CYRILLIC SMALL LETTER BYELORUSSIAN-UKRAINIAN I}"
+x = b"\x1fdon't byte"
+x = rb"\x1Fdon't format"

From a36878eb2f375e2ac1e13052f663909f3835ec46 Mon Sep 17 00:00:00 2001
From: "Yilei \"Dolee\" Yang" <yileiyang@google.com>
Date: Sun, 22 Jan 2023 05:27:11 -0800
Subject: [PATCH 0705/1034] Fix an invalid quote escaping bug in f-string
 expressions (#3509)

Fixes #3506

We can't simply escape the quotes in a naked f-string when merging string groups, because backslashes are invalid.

The quotes in f-string expressions should be toggled (this is safe since quotes can't be reused).

This fix also means implicitly concatenated f-strings with different quotes can now be merged or quote-normalized by changing the quotes used in expressions. e.g.:

```diff
         raise sa_exc.UnboundExecutionError(
             "Could not locate a bind configured on "
-            f'{", ".join(context)} or this Session.'
+            f"{', '.join(context)} or this Session."
         )
```
---
 CHANGES.md                                    |  3 ++
 src/black/trans.py                            | 30 +++++++++++++++++++
 .../data/preview/long_strings__regression.py  | 18 +++++++++++
 3 files changed, 51 insertions(+)

diff --git a/CHANGES.md b/CHANGES.md
index e2e4b341761..e311c492789 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -39,6 +39,9 @@
 - Wrap multiple context managers in parentheses when targeting Python 3.9+ (#3489)
 - Fix several crashes in preview style with walrus operators used in `with` statements
   or tuples (#3473)
+- Fix an invalid quote escaping bug in f-string expressions where it produced invalid
+  code. Implicitly concatenated f-strings with different quotes can now be merged or
+  quote-normalized by changing the quotes used in expressions. (#3509)
 
 ### Configuration
 
diff --git a/src/black/trans.py b/src/black/trans.py
index ec07f5eab74..2360c13f06a 100644
--- a/src/black/trans.py
+++ b/src/black/trans.py
@@ -572,6 +572,12 @@ def make_naked(string: str, string_prefix: str) -> str:
                 characters have been escaped.
             """
             assert_is_leaf_string(string)
+            if "f" in string_prefix:
+                string = _toggle_fexpr_quotes(string, QUOTE)
+                # After quotes toggling, quotes in expressions won't be escaped
+                # because quotes can't be reused in f-strings. So we can simply
+                # let the escaping logic below run without knowing f-string
+                # expressions.
 
             RE_EVEN_BACKSLASHES = r"(?:(?<!\\)(?:\\\\)*)"
             naked_string = string[len(string_prefix) + 1 : -1]
@@ -1240,6 +1246,30 @@ def fstring_contains_expr(s: str) -> bool:
     return any(iter_fexpr_spans(s))
 
 
+def _toggle_fexpr_quotes(fstring: str, old_quote: str) -> str:
+    """
+    Toggles quotes used in f-string expressions that are `old_quote`.
+
+    f-string expressions can't contain backslashes, so we need to toggle the
+    quotes if the f-string itself will end up using the same quote. We can
+    simply toggle without escaping because, quotes can't be reused in f-string
+    expressions. They will fail to parse.
+
+    NOTE: If PEP 701 is accepted, above statement will no longer be true.
+    Though if quotes can be reused, we can simply reuse them without updates or
+    escaping, once Black figures out how to parse the new grammar.
+    """
+    new_quote = "'" if old_quote == '"' else '"'
+    parts = []
+    previous_index = 0
+    for start, end in iter_fexpr_spans(fstring):
+        parts.append(fstring[previous_index:start])
+        parts.append(fstring[start:end].replace(old_quote, new_quote))
+        previous_index = end
+    parts.append(fstring[previous_index:])
+    return "".join(parts)
+
+
 class StringSplitter(BaseStringSplitter, CustomSplitMapMixin):
     """
     StringTransformer that splits "atom" strings (i.e. strings which exist on
diff --git a/tests/data/preview/long_strings__regression.py b/tests/data/preview/long_strings__regression.py
index ef9007f4ce1..eead8c204a9 100644
--- a/tests/data/preview/long_strings__regression.py
+++ b/tests/data/preview/long_strings__regression.py
@@ -550,6 +550,16 @@ async def foo(self):
         ("item1", "item2", "item3"),
 }
 
+# Regression test for https://github.com/psf/black/issues/3506.
+s = (
+    "With single quote: ' "
+    f" {my_dict['foo']}"
+    ' With double quote: " '
+    f' {my_dict["bar"]}'
+)
+
+s = f'Lorem Ipsum is simply dummy text of the printing and typesetting industry:\'{my_dict["foo"]}\''
+
 
 # output
 
@@ -1235,3 +1245,11 @@ async def foo(self):
     # And there is a comment before the value
     ("item1", "item2", "item3"),
 }
+
+# Regression test for https://github.com/psf/black/issues/3506.
+s = f"With single quote: '  {my_dict['foo']} With double quote: \"  {my_dict['bar']}"
+
+s = (
+    "Lorem Ipsum is simply dummy text of the printing and typesetting"
+    f" industry:'{my_dict['foo']}'"
+)

From d950f15987a49a5f3e37127ec718b4c12666b8cf Mon Sep 17 00:00:00 2001
From: "Yilei \"Dolee\" Yang" <yileiyang@google.com>
Date: Mon, 23 Jan 2023 21:38:30 -0800
Subject: [PATCH 0706/1034] Update document now that paren wrapping CMs on
 Python 3.9+ is implemented (#3520)

---
 docs/the_black_code_style/future_style.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/the_black_code_style/future_style.md b/docs/the_black_code_style/future_style.md
index 9ca260fc0ad..7a0b2d8f07a 100644
--- a/docs/the_black_code_style/future_style.md
+++ b/docs/the_black_code_style/future_style.md
@@ -31,8 +31,8 @@ with \
     ...  # backslashes and an ugly stranded colon
 ```
 
-Although when the target version is Python 3.9 or higher, _Black_ will, when we
-implement this, use parentheses instead since they're allowed in Python 3.9 and higher.
+Although when the target version is Python 3.9 or higher, _Black_ uses parentheses
+instead in `--preview` mode (see below) since they're allowed in Python 3.9 and higher.
 
 An alternative to consider if the backslashes in the above formatting are undesirable is
 to use {external:py:obj}`contextlib.ExitStack` to combine context managers in the

From 196b1f349eb2baa9bbbc483226874cc01fb7567d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Edouard=20Choini=C3=A8re?=
 <27212526+echoix@users.noreply.github.com>
Date: Tue, 24 Jan 2023 08:43:24 -0500
Subject: [PATCH 0707/1034] Fix `black --help` output for
 `--python-cell-magics` option to be reproducible (#3516)

---
 CHANGES.md            | 2 ++
 src/black/__init__.py | 2 +-
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index e311c492789..2acb31d6ac4 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -69,6 +69,8 @@
 
 <!-- Changes to Black's terminal output and error messages -->
 
+- Calling `black --help` multiple times will return the same help contents each time
+  (#3516)
 - Verbose logging now shows the values of `pyproject.toml` configuration variables
   (#3392)
 - Fix false symlink detection messages in verbose output due to using an incorrect
diff --git a/src/black/__init__.py b/src/black/__init__.py
index daf6f88f58e..f24487fd398 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -244,7 +244,7 @@ def validate_regex(
     multiple=True,
     help=(
         "When processing Jupyter Notebooks, add the given magic to the list"
-        f" of known python-magics ({', '.join(PYTHON_CELL_MAGICS)})."
+        f" of known python-magics ({', '.join(sorted(PYTHON_CELL_MAGICS))})."
         " Useful for formatting cells with custom python magics."
     ),
     default=[],

From 6407ebb870afe0062ee581abdea07c1ef5213d31 Mon Sep 17 00:00:00 2001
From: Evan Chen <evan@evanchen.cc>
Date: Sat, 28 Jan 2023 16:12:11 -0800
Subject: [PATCH 0708/1034] Remove Python version in the_basics.md (#3528)

---
 docs/contributing/the_basics.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/contributing/the_basics.md b/docs/contributing/the_basics.md
index 9325a9e44ed..5fdcdd802bd 100644
--- a/docs/contributing/the_basics.md
+++ b/docs/contributing/the_basics.md
@@ -4,8 +4,8 @@ An overview on contributing to the _Black_ project.
 
 ## Technicalities
 
-Development on the latest version of Python is preferred. As of this writing it's 3.9.
-You can use any operating system.
+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
 example:

From f4ebc683208d095b252b87147d002e925c9c1171 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Mon, 30 Jan 2023 18:45:12 -0800
Subject: [PATCH 0709/1034] Upgrade isort (#3534)

See PyCQA/isort#2077.
---
 .pre-commit-config.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 2d5ac26b629..576f6405d6c 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -24,7 +24,7 @@ repos:
         additional_dependencies: *version_check_dependencies
 
   - repo: https://github.com/pycqa/isort
-    rev: 5.10.1
+    rev: 5.12.0
     hooks:
       - id: isort
 

From 226cbf0226ee3bc26972357ba54c36409e9a84ae Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Mon, 30 Jan 2023 18:53:14 -0800
Subject: [PATCH 0710/1034] Fix unsafe cast in linegen.py w/ await yield
 handling (#3533)

Fixes #3532.
---
 CHANGES.md                                |  1 +
 src/black/linegen.py                      | 25 ++++++++++++-----------
 tests/data/preview/remove_await_parens.py |  7 +++++++
 3 files changed, 21 insertions(+), 12 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 2acb31d6ac4..8c6a4f40166 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -42,6 +42,7 @@
 - Fix an invalid quote escaping bug in f-string expressions where it produced invalid
   code. Implicitly concatenated f-strings with different quotes can now be merged or
   quote-normalized by changing the quotes used in expressions. (#3509)
+- Fix crash on `await (yield)` when Black is compiled with mypyc (#3533)
 
 ### Configuration
 
diff --git a/src/black/linegen.py b/src/black/linegen.py
index bfc28ca006c..9894a39c95f 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -1223,18 +1223,19 @@ def remove_await_parens(node: Node) -> None:
             # N.B. We've still removed any redundant nested brackets though :)
             opening_bracket = cast(Leaf, node.children[1].children[0])
             closing_bracket = cast(Leaf, node.children[1].children[-1])
-            bracket_contents = cast(Node, node.children[1].children[1])
-            if bracket_contents.type != syms.power:
-                ensure_visible(opening_bracket)
-                ensure_visible(closing_bracket)
-            elif (
-                bracket_contents.type == syms.power
-                and bracket_contents.children[0].type == token.AWAIT
-            ):
-                ensure_visible(opening_bracket)
-                ensure_visible(closing_bracket)
-                # If we are in a nested await then recurse down.
-                remove_await_parens(bracket_contents)
+            bracket_contents = node.children[1].children[1]
+            if isinstance(bracket_contents, Node):
+                if bracket_contents.type != syms.power:
+                    ensure_visible(opening_bracket)
+                    ensure_visible(closing_bracket)
+                elif (
+                    bracket_contents.type == syms.power
+                    and bracket_contents.children[0].type == token.AWAIT
+                ):
+                    ensure_visible(opening_bracket)
+                    ensure_visible(closing_bracket)
+                    # If we are in a nested await then recurse down.
+                    remove_await_parens(bracket_contents)
 
 
 def _maybe_wrap_cms_in_parens(
diff --git a/tests/data/preview/remove_await_parens.py b/tests/data/preview/remove_await_parens.py
index 571210a2d80..8c7223d2f39 100644
--- a/tests/data/preview/remove_await_parens.py
+++ b/tests/data/preview/remove_await_parens.py
@@ -77,6 +77,9 @@ async def main():
 async def main():
     await (await (await (await (await (asyncio.sleep(1))))))
 
+async def main():
+    await (yield)
+
 # output
 import asyncio
 
@@ -167,3 +170,7 @@ async def main():
 
 async def main():
     await (await (await (await (await asyncio.sleep(1)))))
+
+
+async def main():
+    await (yield)

From c4bd2e31ceeac84d68592986fe70920f3d3d0443 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Tue, 31 Jan 2023 15:39:56 -0800
Subject: [PATCH 0711/1034] Draft for Black 2023 stable style (#3418)

---
 CHANGES.md                                    | 29 ++++++
 docs/the_black_code_style/current_style.md    | 40 +++++++-
 docs/the_black_code_style/future_style.md     | 90 -----------------
 src/black/__init__.py                         |  9 +-
 src/black/comments.py                         | 58 +++++------
 src/black/linegen.py                          | 99 +++++++------------
 src/black/lines.py                            | 38 +++----
 src/black/mode.py                             |  8 --
 .../expression_skip_magic_trailing_comma.diff |  3 +-
 .../return_annotation_brackets_string.py      | 12 +++
 .../py_310/parenthesized_context_managers.py  | 24 +++++
 .../remove_newline_after_match.py             |  0
 tests/data/py_311/pep_654_style.py            |  2 +-
 tests/data/py_38/pep_572_remove_parens.py     |  4 +-
 .../remove_with_brackets.py                   |  0
 tests/data/simple_cases/comments2.py          |  1 +
 tests/data/simple_cases/comments3.py          |  5 +-
 tests/data/simple_cases/comments5.py          |  2 +
 .../{preview => simple_cases}/comments8.py    |  0
 .../{preview => simple_cases}/comments9.py    |  0
 .../docstring_preview.py                      |  0
 tests/data/simple_cases/empty_lines.py        |  1 -
 tests/data/simple_cases/fmtonoff.py           |  1 +
 .../simple_cases/function_trailing_comma.py   | 16 ++-
 .../one_element_subscript.py                  |  0
 .../prefer_rhs_split_reformatted.py           |  0
 .../remove_await_parens.py                    |  0
 .../remove_except_parens.py                   |  0
 .../remove_for_brackets.py                    |  0
 .../remove_newline_after_code_block_open.py   |  0
 .../return_annotation_brackets.py             | 12 ---
 .../skip_magic_trailing_comma.py              |  0
 .../trailing_commas_in_leading_parts.py       |  0
 .../{preview => simple_cases}/whitespace.py   |  0
 tests/test_black.py                           |  3 +-
 tests/test_format.py                          | 24 +----
 36 files changed, 207 insertions(+), 274 deletions(-)
 create mode 100644 tests/data/preview/return_annotation_brackets_string.py
 rename tests/data/{preview_310 => py_310}/remove_newline_after_match.py (100%)
 rename tests/data/{preview_39 => py_39}/remove_with_brackets.py (100%)
 rename tests/data/{preview => simple_cases}/comments8.py (100%)
 rename tests/data/{preview => simple_cases}/comments9.py (100%)
 rename tests/data/{preview => simple_cases}/docstring_preview.py (100%)
 rename tests/data/{preview => simple_cases}/one_element_subscript.py (100%)
 rename tests/data/{preview => simple_cases}/prefer_rhs_split_reformatted.py (100%)
 rename tests/data/{preview => simple_cases}/remove_await_parens.py (100%)
 rename tests/data/{preview => simple_cases}/remove_except_parens.py (100%)
 rename tests/data/{preview => simple_cases}/remove_for_brackets.py (100%)
 rename tests/data/{preview => simple_cases}/remove_newline_after_code_block_open.py (100%)
 rename tests/data/{preview => simple_cases}/return_annotation_brackets.py (93%)
 rename tests/data/{preview => simple_cases}/skip_magic_trailing_comma.py (100%)
 rename tests/data/{preview => simple_cases}/trailing_commas_in_leading_parts.py (100%)
 rename tests/data/{preview => simple_cases}/whitespace.py (100%)

diff --git a/CHANGES.md b/CHANGES.md
index 8c6a4f40166..ecc8a41f505 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -10,6 +10,35 @@
 
 <!-- Changes that affect Black's stable style -->
 
+- Introduce the 2023 stable style, which incorporates most aspects of last year's
+  preview style (#3418). Specific changes:
+  - Enforce empty lines before classes and functions with sticky leading comments
+    (#3302) (22.12.0)
+  - Reformat empty and whitespace-only files as either an empty file (if no newline is
+    present) or as a single newline character (if a newline is present) (#3348)
+    (22.12.0)
+  - Implicitly concatenated strings used as function args are now wrapped inside
+    parentheses (#3307) (22.12.0)
+  - Correctly handle trailing commas that are inside a line's leading non-nested parens
+    (#3370) (22.12.0)
+  - `--skip-string-normalization` / `-S` now prevents docstring prefixes from being
+    normalized as expected (#3168) (since 22.8.0)
+  - When using `--skip-magic-trailing-comma` or `-C`, trailing commas are stripped from
+    subscript expressions with more than 1 element (#3209) (22.8.0)
+  - Implicitly concatenated strings inside a list, set, or tuple are now wrapped inside
+    parentheses (#3162) (22.8.0)
+  - Fix a string merging/split issue when a comment is present in the middle of
+    implicitly concatenated strings on its own line (#3227) (22.8.0)
+  - Docstring quotes are no longer moved if it would violate the line length limit
+    (#3044, #3430) (22.6.0)
+  - Parentheses around return annotations are now managed (#2990) (22.6.0)
+  - Remove unnecessary parentheses around awaited objects (#2991) (22.6.0)
+  - Remove unnecessary parentheses in `with` statements (#2926) (22.6.0)
+  - Remove trailing newlines after code block open (#3035) (22.6.0)
+  - Code cell separators `#%%` are now standardised to `# %%` (#2919) (22.3.0)
+  - Remove unnecessary parentheses from `except` statements (#2939) (22.3.0)
+  - Remove unnecessary parentheses from tuple unpacking in `for` loops (#2945) (22.3.0)
+  - Avoid magic-trailing-comma in single-element subscripts (#2942) (22.3.0)
 - Fix a crash when a colon line is marked between `# fmt: off` and `# fmt: on` (#3439)
 
 ### Preview style
diff --git a/docs/the_black_code_style/current_style.md b/docs/the_black_code_style/current_style.md
index 56b92529d70..83f8785cc55 100644
--- a/docs/the_black_code_style/current_style.md
+++ b/docs/the_black_code_style/current_style.md
@@ -194,7 +194,45 @@ that in-function vertical whitespace should only be used sparingly.
 _Black_ will allow single empty lines inside functions, and single and double empty
 lines on module level left by the original editors, except when they're within
 parenthesized expressions. Since such expressions are always reformatted to fit minimal
-space, this whitespace is lost.
+space, this whitespace is lost. The other exception is that it will remove any empty
+lines immediately following a statement that introduces a new indentation level.
+
+```python
+# in:
+
+def foo():
+
+    print("All the newlines above me should be deleted!")
+
+
+if condition:
+
+    print("No newline above me!")
+
+    print("There is a newline above me, and that's OK!")
+
+
+class Point:
+
+    x: int
+    y: int
+
+# out:
+
+def foo():
+    print("All the newlines above me should be deleted!")
+
+
+if condition:
+    print("No newline above me!")
+
+    print("There is a newline above me, and that's OK!")
+
+
+class Point:
+    x: int
+    y: int
+```
 
 It will also insert proper spacing before and after function definitions. It's one line
 before and after inner functions and two lines before and after module-level functions
diff --git a/docs/the_black_code_style/future_style.md b/docs/the_black_code_style/future_style.md
index 7a0b2d8f07a..6d289d460a7 100644
--- a/docs/the_black_code_style/future_style.md
+++ b/docs/the_black_code_style/future_style.md
@@ -62,93 +62,3 @@ plain strings. User-made splits are respected when they do not exceed the line l
 limit. Line continuation backslashes are converted into parenthesized strings.
 Unnecessary parentheses are stripped. The stability and status of this feature is
 tracked in [this issue](https://github.com/psf/black/issues/2188).
-
-### Improved empty line management
-
-1.  _Black_ will remove newlines in the beginning of new code blocks, i.e. when the
-    indentation level is increased. For example:
-
-    ```python
-    def my_func():
-
-        print("The line above me will be deleted!")
-    ```
-
-    will be changed to:
-
-    ```python
-    def my_func():
-        print("The line above me will be deleted!")
-    ```
-
-    This new feature will be applied to **all code blocks**: `def`, `class`, `if`,
-    `for`, `while`, `with`, `case` and `match`.
-
-2.  _Black_ will enforce empty lines before classes and functions with leading comments.
-    For example:
-
-    ```python
-    some_var = 1
-    # Leading sticky comment
-    def my_func():
-        ...
-    ```
-
-    will be changed to:
-
-    ```python
-    some_var = 1
-
-
-    # Leading sticky comment
-    def my_func():
-        ...
-    ```
-
-### Improved parentheses management
-
-_Black_ will format parentheses around return annotations similarly to other sets of
-parentheses. For example:
-
-```python
-def foo() -> (int):
-    ...
-
-def foo() -> looooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong:
-    ...
-```
-
-will be changed to:
-
-```python
-def foo() -> int:
-    ...
-
-
-def foo() -> (
-    looooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong
-):
-    ...
-```
-
-And, extra parentheses in `await` expressions and `with` statements are removed. For
-example:
-
-```python
-with ((open("bla.txt")) as f, open("x")):
-    ...
-
-async def main():
-    await (asyncio.sleep(1))
-```
-
-will be changed to:
-
-```python
-with open("bla.txt") as f, open("x"):
-    ...
-
-
-async def main():
-    await asyncio.sleep(1)
-```
diff --git a/src/black/__init__.py b/src/black/__init__.py
index f24487fd398..42bdfc1a5dd 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -925,9 +925,6 @@ def format_file_contents(src_contents: str, *, fast: bool, mode: Mode) -> FileCo
     valid by calling :func:`assert_equivalent` and :func:`assert_stable` on it.
     `mode` is passed to :func:`format_str`.
     """
-    if not mode.preview and not src_contents.strip():
-        raise NothingChanged
-
     if mode.is_ipynb:
         dst_contents = format_ipynb_string(src_contents, fast=fast, mode=mode)
     else:
@@ -1022,7 +1019,7 @@ def format_ipynb_string(src_contents: str, *, fast: bool, mode: Mode) -> FileCon
     Operate cell-by-cell, only on code cells, only for Python notebooks.
     If the ``.ipynb`` originally had a trailing newline, it'll be preserved.
     """
-    if mode.preview and not src_contents:
+    if not src_contents:
         raise NothingChanged
 
     trailing_newline = src_contents[-1] == "\n"
@@ -1101,7 +1098,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, preview=mode.preview)
+    normalize_fmt_off(src_node)
     lines = LineGenerator(mode=mode, features=context_manager_features)
     elt = EmptyLineTracker(mode=mode)
     split_line_features = {
@@ -1122,7 +1119,7 @@ def _format_str_once(src_contents: str, *, mode: Mode) -> str:
     dst_contents = []
     for block in dst_blocks:
         dst_contents.extend(block.all_lines())
-    if mode.preview and not dst_contents:
+    if not dst_contents:
         # Use decode_bytes to retrieve the correct source newline (CRLF or LF),
         # and check if normalized_content has more than one line
         normalized_content, _, newline = decode_bytes(src_contents.encode("utf-8"))
diff --git a/src/black/comments.py b/src/black/comments.py
index e733dccd844..7cf15bf67b3 100644
--- a/src/black/comments.py
+++ b/src/black/comments.py
@@ -29,7 +29,7 @@
 FMT_PASS: Final = {*FMT_OFF, *FMT_SKIP}
 FMT_ON: Final = {"# fmt: on", "# fmt:on", "# yapf: enable"}
 
-COMMENT_EXCEPTIONS = {True: " !:#'", False: " !:#'%"}
+COMMENT_EXCEPTIONS = " !:#'"
 
 
 @dataclass
@@ -50,7 +50,7 @@ class ProtoComment:
     consumed: int  # how many characters of the original leaf's prefix did we consume
 
 
-def generate_comments(leaf: LN, *, preview: bool) -> Iterator[Leaf]:
+def generate_comments(leaf: LN) -> Iterator[Leaf]:
     """Clean the prefix of the `leaf` and generate comments from it, if any.
 
     Comments in lib2to3 are shoved into the whitespace prefix.  This happens
@@ -69,16 +69,12 @@ def generate_comments(leaf: LN, *, preview: bool) -> Iterator[Leaf]:
     Inline comments are emitted as regular token.COMMENT leaves.  Standalone
     are emitted with a fake STANDALONE_COMMENT token identifier.
     """
-    for pc in list_comments(
-        leaf.prefix, is_endmarker=leaf.type == token.ENDMARKER, preview=preview
-    ):
+    for pc in list_comments(leaf.prefix, is_endmarker=leaf.type == token.ENDMARKER):
         yield Leaf(pc.type, pc.value, prefix="\n" * pc.newlines)
 
 
 @lru_cache(maxsize=4096)
-def list_comments(
-    prefix: str, *, is_endmarker: bool, preview: bool
-) -> List[ProtoComment]:
+def list_comments(prefix: str, *, is_endmarker: bool) -> List[ProtoComment]:
     """Return a list of :class:`ProtoComment` objects parsed from the given `prefix`."""
     result: List[ProtoComment] = []
     if not prefix or "#" not in prefix:
@@ -104,7 +100,7 @@ def list_comments(
             comment_type = token.COMMENT  # simple trailing comment
         else:
             comment_type = STANDALONE_COMMENT
-        comment = make_comment(line, preview=preview)
+        comment = make_comment(line)
         result.append(
             ProtoComment(
                 type=comment_type, value=comment, newlines=nlines, consumed=consumed
@@ -114,7 +110,7 @@ def list_comments(
     return result
 
 
-def make_comment(content: str, *, preview: bool) -> str:
+def make_comment(content: str) -> str:
     """Return a consistently formatted comment from the given `content` string.
 
     All comments (except for "##", "#!", "#:", '#'") should have a single
@@ -135,26 +131,26 @@ def make_comment(content: str, *, preview: bool) -> str:
         and not content.lstrip().startswith("type:")
     ):
         content = " " + content[1:]  # Replace NBSP by a simple space
-    if content and content[0] not in COMMENT_EXCEPTIONS[preview]:
+    if content and content[0] not in COMMENT_EXCEPTIONS:
         content = " " + content
     return "#" + content
 
 
-def normalize_fmt_off(node: Node, *, preview: bool) -> None:
+def normalize_fmt_off(node: Node) -> None:
     """Convert content between `# fmt: off`/`# fmt: on` into standalone comments."""
     try_again = True
     while try_again:
-        try_again = convert_one_fmt_off_pair(node, preview=preview)
+        try_again = convert_one_fmt_off_pair(node)
 
 
-def convert_one_fmt_off_pair(node: Node, *, preview: bool) -> bool:
+def convert_one_fmt_off_pair(node: Node) -> bool:
     """Convert content of a single `# fmt: off`/`# fmt: on` into a standalone comment.
 
     Returns True if a pair was converted.
     """
     for leaf in node.leaves():
         previous_consumed = 0
-        for comment in list_comments(leaf.prefix, is_endmarker=False, preview=preview):
+        for comment in list_comments(leaf.prefix, is_endmarker=False):
             if comment.value not in FMT_PASS:
                 previous_consumed = comment.consumed
                 continue
@@ -169,7 +165,7 @@ def convert_one_fmt_off_pair(node: Node, *, preview: bool) -> bool:
                     if comment.value in FMT_SKIP and prev.type in WHITESPACE:
                         continue
 
-            ignored_nodes = list(generate_ignored_nodes(leaf, comment, preview=preview))
+            ignored_nodes = list(generate_ignored_nodes(leaf, comment))
             if not ignored_nodes:
                 continue
 
@@ -214,26 +210,24 @@ def convert_one_fmt_off_pair(node: Node, *, preview: bool) -> bool:
     return False
 
 
-def generate_ignored_nodes(
-    leaf: Leaf, comment: ProtoComment, *, preview: bool
-) -> Iterator[LN]:
+def generate_ignored_nodes(leaf: Leaf, comment: ProtoComment) -> Iterator[LN]:
     """Starting from the container of `leaf`, generate all leaves until `# fmt: on`.
 
     If comment is skip, returns leaf only.
     Stops at the end of the block.
     """
     if comment.value in FMT_SKIP:
-        yield from _generate_ignored_nodes_from_fmt_skip(leaf, comment, preview=preview)
+        yield from _generate_ignored_nodes_from_fmt_skip(leaf, comment)
         return
     container: Optional[LN] = container_of(leaf)
     while container is not None and container.type != token.ENDMARKER:
-        if is_fmt_on(container, preview=preview):
+        if is_fmt_on(container):
             return
 
         # fix for fmt: on in children
-        if children_contains_fmt_on(container, preview=preview):
+        if children_contains_fmt_on(container):
             for index, child in enumerate(container.children):
-                if isinstance(child, Leaf) and is_fmt_on(child, preview=preview):
+                if isinstance(child, Leaf) and is_fmt_on(child):
                     if child.type in CLOSING_BRACKETS:
                         # This means `# fmt: on` is placed at a different bracket level
                         # than `# fmt: off`. This is an invalid use, but as a courtesy,
@@ -244,14 +238,12 @@ def generate_ignored_nodes(
                 if (
                     child.type == token.INDENT
                     and index < len(container.children) - 1
-                    and children_contains_fmt_on(
-                        container.children[index + 1], preview=preview
-                    )
+                    and children_contains_fmt_on(container.children[index + 1])
                 ):
                     # This means `# fmt: on` is placed right after an indentation
                     # level, and we shouldn't swallow the previous INDENT token.
                     return
-                if children_contains_fmt_on(child, preview=preview):
+                if children_contains_fmt_on(child):
                     return
                 yield child
         else:
@@ -264,14 +256,14 @@ def generate_ignored_nodes(
 
 
 def _generate_ignored_nodes_from_fmt_skip(
-    leaf: Leaf, comment: ProtoComment, *, preview: bool
+    leaf: Leaf, comment: ProtoComment
 ) -> Iterator[LN]:
     """Generate all leaves that should be ignored by the `# fmt: skip` from `leaf`."""
     prev_sibling = leaf.prev_sibling
     parent = leaf.parent
     # Need to properly format the leaf prefix to compare it to comment.value,
     # which is also formatted
-    comments = list_comments(leaf.prefix, is_endmarker=False, preview=preview)
+    comments = list_comments(leaf.prefix, is_endmarker=False)
     if not comments or comment.value != comments[0].value:
         return
     if prev_sibling is not None:
@@ -305,12 +297,12 @@ def _generate_ignored_nodes_from_fmt_skip(
         yield from iter(ignored_nodes)
 
 
-def is_fmt_on(container: LN, preview: bool) -> bool:
+def is_fmt_on(container: LN) -> bool:
     """Determine whether formatting is switched on within a container.
     Determined by whether the last `# fmt:` comment is `on` or `off`.
     """
     fmt_on = False
-    for comment in list_comments(container.prefix, is_endmarker=False, preview=preview):
+    for comment in list_comments(container.prefix, is_endmarker=False):
         if comment.value in FMT_ON:
             fmt_on = True
         elif comment.value in FMT_OFF:
@@ -318,11 +310,11 @@ def is_fmt_on(container: LN, preview: bool) -> bool:
     return fmt_on
 
 
-def children_contains_fmt_on(container: LN, *, preview: bool) -> bool:
+def children_contains_fmt_on(container: LN) -> bool:
     """Determine if children have formatting switched on."""
     for child in container.children:
         leaf = first_leaf_of(child)
-        if leaf is not None and is_fmt_on(leaf, preview=preview):
+        if leaf is not None and is_fmt_on(leaf):
             return True
 
     return False
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 9894a39c95f..7afb1733939 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -117,7 +117,7 @@ def visit_default(self, node: LN) -> Iterator[Line]:
         """Default `visit_*()` implementation. Recurses to children of `node`."""
         if isinstance(node, Leaf):
             any_open_brackets = self.current_line.bracket_tracker.any_open_brackets()
-            for comment in generate_comments(node, preview=self.mode.preview):
+            for comment in generate_comments(node):
                 if any_open_brackets:
                     # any comment within brackets is subject to splitting
                     self.current_line.append(comment)
@@ -221,30 +221,27 @@ def visit_dictsetmaker(self, node: Node) -> Iterator[Line]:
 
     def visit_funcdef(self, node: Node) -> Iterator[Line]:
         """Visit function definition."""
-        if Preview.annotation_parens not in self.mode:
-            yield from self.visit_stmt(node, keywords={"def"}, parens=set())
-        else:
-            yield from self.line()
+        yield from self.line()
 
-            # Remove redundant brackets around return type annotation.
-            is_return_annotation = False
-            for child in node.children:
-                if child.type == token.RARROW:
-                    is_return_annotation = True
-                elif is_return_annotation:
-                    if child.type == syms.atom and child.children[0].type == token.LPAR:
-                        if maybe_make_parens_invisible_in_atom(
-                            child,
-                            parent=node,
-                            remove_brackets_around_comma=False,
-                        ):
-                            wrap_in_parentheses(node, child, visible=False)
-                    else:
+        # Remove redundant brackets around return type annotation.
+        is_return_annotation = False
+        for child in node.children:
+            if child.type == token.RARROW:
+                is_return_annotation = True
+            elif is_return_annotation:
+                if child.type == syms.atom and child.children[0].type == token.LPAR:
+                    if maybe_make_parens_invisible_in_atom(
+                        child,
+                        parent=node,
+                        remove_brackets_around_comma=False,
+                    ):
                         wrap_in_parentheses(node, child, visible=False)
-                    is_return_annotation = False
+                else:
+                    wrap_in_parentheses(node, child, visible=False)
+                is_return_annotation = False
 
-            for child in node.children:
-                yield from self.visit(child)
+        for child in node.children:
+            yield from self.visit(child)
 
     def visit_match_case(self, node: Node) -> Iterator[Line]:
         """Visit either a match or case statement."""
@@ -332,8 +329,7 @@ def visit_power(self, node: Node) -> Iterator[Line]:
             ):
                 wrap_in_parentheses(node, leaf)
 
-        if Preview.remove_redundant_parens in self.mode:
-            remove_await_parens(node)
+        remove_await_parens(node)
 
         yield from self.visit_default(node)
 
@@ -375,24 +371,17 @@ def visit_STRING(self, leaf: Leaf) -> Iterator[Line]:
         if is_docstring(leaf) and "\\\n" not in leaf.value:
             # We're ignoring docstrings with backslash newline escapes because changing
             # indentation of those changes the AST representation of the code.
-            if Preview.normalize_docstring_quotes_and_prefixes_properly in self.mode:
-                # There was a bug where --skip-string-normalization wouldn't stop us
-                # from normalizing docstring prefixes. To maintain stability, we can
-                # only address this buggy behaviour while the preview style is enabled.
-                if self.mode.string_normalization:
-                    docstring = normalize_string_prefix(leaf.value)
-                    # visit_default() does handle string normalization for us, but
-                    # since this method acts differently depending on quote style (ex.
-                    # see padding logic below), there's a possibility for unstable
-                    # formatting as visit_default() is called *after*. To avoid a
-                    # situation where this function formats a docstring differently on
-                    # the second pass, normalize it early.
-                    docstring = normalize_string_quotes(docstring)
-                else:
-                    docstring = leaf.value
-            else:
-                # ... otherwise, we'll keep the buggy behaviour >.<
+            if self.mode.string_normalization:
                 docstring = normalize_string_prefix(leaf.value)
+                # visit_default() does handle string normalization for us, but
+                # since this method acts differently depending on quote style (ex.
+                # see padding logic below), there's a possibility for unstable
+                # formatting as visit_default() is called *after*. To avoid a
+                # situation where this function formats a docstring differently on
+                # the second pass, normalize it early.
+                docstring = normalize_string_quotes(docstring)
+            else:
+                docstring = leaf.value
             prefix = get_string_prefix(docstring)
             docstring = docstring[len(prefix) :]  # Remove the prefix
             quote_char = docstring[0]
@@ -432,7 +421,7 @@ def visit_STRING(self, leaf: Leaf) -> Iterator[Line]:
             quote = quote_char * quote_len
 
             # It's invalid to put closing single-character quotes on a new line.
-            if Preview.long_docstring_quotes_on_newline in self.mode and quote_len == 3:
+            if self.mode and quote_len == 3:
                 # We need to find the length of the last line of the docstring
                 # to find if we can add the closing quotes to the line without
                 # exceeding the maximum line length.
@@ -473,14 +462,8 @@ def __post_init__(self) -> None:
         self.visit_try_stmt = partial(
             v, keywords={"try", "except", "else", "finally"}, parens=Ø
         )
-        if self.mode.preview:
-            self.visit_except_clause = partial(
-                v, keywords={"except"}, parens={"except"}
-            )
-            self.visit_with_stmt = partial(v, keywords={"with"}, parens={"with"})
-        else:
-            self.visit_except_clause = partial(v, keywords={"except"}, parens=Ø)
-            self.visit_with_stmt = partial(v, keywords={"with"}, parens=Ø)
+        self.visit_except_clause = partial(v, keywords={"except"}, parens={"except"})
+        self.visit_with_stmt = partial(v, keywords={"with"}, parens={"with"})
         self.visit_classdef = partial(v, keywords={"class"}, parens=Ø)
         self.visit_expr_stmt = partial(v, keywords=Ø, parens=ASSIGNMENTS)
         self.visit_return_stmt = partial(v, keywords={"return"}, parens={"return"})
@@ -932,10 +915,7 @@ def bracket_split_build_line(
                     break
 
     leaves_to_track: Set[LeafID] = set()
-    if (
-        Preview.handle_trailing_commas_in_head in original.mode
-        and component is _BracketSplitComponent.head
-    ):
+    if component is _BracketSplitComponent.head:
         leaves_to_track = get_leaves_inside_matching_brackets(leaves)
     # Populate the line
     for leaf in leaves:
@@ -1109,7 +1089,7 @@ def normalize_invisible_parens(
     Standardizes on visible parentheses for single-element tuples, and keeps
     existing visible parentheses for other tuples and generator expressions.
     """
-    for pc in list_comments(node.prefix, is_endmarker=False, preview=mode.preview):
+    for pc in list_comments(node.prefix, is_endmarker=False):
         if pc.value in FMT_OFF:
             # This `node` has a prefix with `# fmt: off`, don't mess with parens.
             return
@@ -1139,8 +1119,7 @@ def normalize_invisible_parens(
 
         if check_lpar:
             if (
-                mode.preview
-                and child.type == syms.atom
+                child.type == syms.atom
                 and node.type == syms.for_stmt
                 and isinstance(child.prev_sibling, Leaf)
                 and child.prev_sibling.type == token.NAME
@@ -1152,9 +1131,7 @@ def normalize_invisible_parens(
                     remove_brackets_around_comma=True,
                 ):
                     wrap_in_parentheses(node, child, visible=False)
-            elif (
-                mode.preview and isinstance(child, Node) and node.type == syms.with_stmt
-            ):
+            elif isinstance(child, Node) and node.type == syms.with_stmt:
                 remove_with_parens(child, node)
             elif child.type == syms.atom:
                 if maybe_make_parens_invisible_in_atom(
@@ -1180,7 +1157,7 @@ def normalize_invisible_parens(
             elif not (isinstance(child, Leaf) and is_multiline_string(child)):
                 wrap_in_parentheses(node, child, visible=False)
 
-        comma_check = child.type == token.COMMA if mode.preview else False
+        comma_check = child.type == token.COMMA
 
         check_lpar = isinstance(child, Leaf) and (
             child.value in parens_after or comma_check
diff --git a/src/black/lines.py b/src/black/lines.py
index 2aa675c3b31..ec6ef5d9522 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -14,7 +14,7 @@
 )
 
 from black.brackets import DOT_PRIORITY, BracketTracker
-from black.mode import Mode, Preview
+from black.mode import Mode
 from black.nodes import (
     BRACKETS,
     CLOSING_BRACKETS,
@@ -275,8 +275,7 @@ def has_magic_trailing_comma(
         - it's not a single-element subscript
         Additionally, if ensure_removable:
         - it's not from square bracket indexing
-        (specifically, single-element square bracket indexing with
-        Preview.skip_magic_trailing_comma_in_subscript)
+        (specifically, single-element square bracket indexing)
         """
         if not (
             closing.type in CLOSING_BRACKETS
@@ -290,8 +289,7 @@ def has_magic_trailing_comma(
 
         if closing.type == token.RSQB:
             if (
-                Preview.one_element_subscript in self.mode
-                and closing.parent
+                closing.parent
                 and closing.parent.type == syms.trailer
                 and closing.opening_bracket
                 and is_one_sequence_between(
@@ -309,18 +307,16 @@ def has_magic_trailing_comma(
             comma = self.leaves[-1]
             if comma.parent is None:
                 return False
-            if Preview.skip_magic_trailing_comma_in_subscript in self.mode:
-                return (
-                    comma.parent.type != syms.subscriptlist
-                    or closing.opening_bracket is None
-                    or not is_one_sequence_between(
-                        closing.opening_bracket,
-                        closing,
-                        self.leaves,
-                        brackets=(token.LSQB, token.RSQB),
-                    )
+            return (
+                comma.parent.type != syms.subscriptlist
+                or closing.opening_bracket is None
+                or not is_one_sequence_between(
+                    closing.opening_bracket,
+                    closing,
+                    self.leaves,
+                    brackets=(token.LSQB, token.RSQB),
                 )
-            return comma.parent.type == syms.listmaker
+            )
 
         if self.is_import:
             return True
@@ -592,11 +588,7 @@ def _maybe_empty_lines(self, current_line: Line) -> Tuple[int, int]:
         ):
             return before, 1
 
-        if (
-            Preview.remove_block_trailing_newline in current_line.mode
-            and self.previous_line
-            and self.previous_line.opens_block
-        ):
+        if self.previous_line and self.previous_line.opens_block:
             return 0, 0
         return before, 0
 
@@ -629,9 +621,7 @@ def _maybe_empty_lines_for_class_or_def(
         ):
             slc = self.semantic_leading_comment
             if (
-                Preview.empty_lines_before_class_or_def_with_leading_comments
-                in current_line.mode
-                and slc is not None
+                slc is not None
                 and slc.previous_block is not None
                 and not slc.previous_block.original_line.is_class
                 and not slc.previous_block.original_line.opens_block
diff --git a/src/black/mode.py b/src/black/mode.py
index 4309d4fa635..1af16070073 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -154,15 +154,7 @@ class Preview(Enum):
     """Individual preview style features."""
 
     hex_codes_in_unicode_sequences = auto()
-    annotation_parens = auto()
-    empty_lines_before_class_or_def_with_leading_comments = auto()
-    handle_trailing_commas_in_head = auto()
-    long_docstring_quotes_on_newline = auto()
-    normalize_docstring_quotes_and_prefixes_properly = auto()
-    one_element_subscript = auto()
     prefer_splitting_right_hand_side_of_assignments = auto()
-    remove_block_trailing_newline = auto()
-    remove_redundant_parens = auto()
     # NOTE: string_processing requires wrap_long_dict_values_in_parens
     # for https://github.com/psf/black/issues/3117 to be fixed.
     string_processing = auto()
diff --git a/tests/data/miscellaneous/expression_skip_magic_trailing_comma.diff b/tests/data/miscellaneous/expression_skip_magic_trailing_comma.diff
index eba3fd2da7d..d17467b15c7 100644
--- a/tests/data/miscellaneous/expression_skip_magic_trailing_comma.diff
+++ b/tests/data/miscellaneous/expression_skip_magic_trailing_comma.diff
@@ -144,8 +144,9 @@
 -tuple[
 -    str, int, float, dict[str, int]
 -]
+-tuple[str, int, float, dict[str, int],]
++tuple[str, int, float, dict[str, int]]
 +tuple[str, int, float, dict[str, int]]
- tuple[str, int, float, dict[str, int],]
  very_long_variable_name_filters: t.List[
      t.Tuple[str, t.Union[str, t.List[t.Optional[str]]]],
  ]
diff --git a/tests/data/preview/return_annotation_brackets_string.py b/tests/data/preview/return_annotation_brackets_string.py
new file mode 100644
index 00000000000..6978829fd5c
--- /dev/null
+++ b/tests/data/preview/return_annotation_brackets_string.py
@@ -0,0 +1,12 @@
+# Long string example
+def frobnicate() -> "ThisIsTrulyUnreasonablyExtremelyLongClassName | list[ThisIsTrulyUnreasonablyExtremelyLongClassName]":
+    pass
+
+# output
+
+# Long string example
+def frobnicate() -> (
+    "ThisIsTrulyUnreasonablyExtremelyLongClassName |"
+    " list[ThisIsTrulyUnreasonablyExtremelyLongClassName]"
+):
+    pass
diff --git a/tests/data/py_310/parenthesized_context_managers.py b/tests/data/py_310/parenthesized_context_managers.py
index ccf1f94883e..1ef09a1bd34 100644
--- a/tests/data/py_310/parenthesized_context_managers.py
+++ b/tests/data/py_310/parenthesized_context_managers.py
@@ -19,3 +19,27 @@
     CtxManager3() as example3,
 ):
     ...
+
+# output
+
+with CtxManager() as example:
+    ...
+
+with CtxManager1(), CtxManager2():
+    ...
+
+with CtxManager1() as example, CtxManager2():
+    ...
+
+with CtxManager1(), CtxManager2() as example:
+    ...
+
+with CtxManager1() as example1, CtxManager2() as example2:
+    ...
+
+with (
+    CtxManager1() as example1,
+    CtxManager2() as example2,
+    CtxManager3() as example3,
+):
+    ...
diff --git a/tests/data/preview_310/remove_newline_after_match.py b/tests/data/py_310/remove_newline_after_match.py
similarity index 100%
rename from tests/data/preview_310/remove_newline_after_match.py
rename to tests/data/py_310/remove_newline_after_match.py
diff --git a/tests/data/py_311/pep_654_style.py b/tests/data/py_311/pep_654_style.py
index 568e5e3efa4..9fc7c0c84db 100644
--- a/tests/data/py_311/pep_654_style.py
+++ b/tests/data/py_311/pep_654_style.py
@@ -76,7 +76,7 @@
     except:
         try:
             raise TypeError(int)
-        except* (Exception):
+        except* Exception:
             pass
         1 / 0
 except Exception as e:
diff --git a/tests/data/py_38/pep_572_remove_parens.py b/tests/data/py_38/pep_572_remove_parens.py
index 4e95fb07f3a..b952b2940c5 100644
--- a/tests/data/py_38/pep_572_remove_parens.py
+++ b/tests/data/py_38/pep_572_remove_parens.py
@@ -62,7 +62,6 @@ async def await_the_walrus():
     with (x := await a, y := await b):
         pass
 
-    # Ideally we should remove one set of parentheses
     with ((x := await a, y := await b)):
         pass
 
@@ -137,8 +136,7 @@ async def await_the_walrus():
     with (x := await a, y := await b):
         pass
 
-    # Ideally we should remove one set of parentheses
-    with ((x := await a, y := await b)):
+    with (x := await a, y := await b):
         pass
 
     with (x := await a), (y := await b):
diff --git a/tests/data/preview_39/remove_with_brackets.py b/tests/data/py_39/remove_with_brackets.py
similarity index 100%
rename from tests/data/preview_39/remove_with_brackets.py
rename to tests/data/py_39/remove_with_brackets.py
diff --git a/tests/data/simple_cases/comments2.py b/tests/data/simple_cases/comments2.py
index 4eea013151a..37e185abf4f 100644
--- a/tests/data/simple_cases/comments2.py
+++ b/tests/data/simple_cases/comments2.py
@@ -226,6 +226,7 @@ def _init_host(self, parsed) -> None:
     add_compiler(compilers[(7.0, 32)])
     # add_compiler(compilers[(7.1, 64)])
 
+
 # Comment before function.
 def inline_comments_in_brackets_ruin_everything():
     if typedargslist:
diff --git a/tests/data/simple_cases/comments3.py b/tests/data/simple_cases/comments3.py
index fbbef6dcc6b..f964bee6651 100644
--- a/tests/data/simple_cases/comments3.py
+++ b/tests/data/simple_cases/comments3.py
@@ -1,6 +1,7 @@
 # The percent-percent comments are Spyder IDE cells.
 
-#%%
+
+# %%
 def func():
     x = """
     a really long string
@@ -44,4 +45,4 @@ def func():
     )
 
 
-#%%
\ No newline at end of file
+# %%
\ No newline at end of file
diff --git a/tests/data/simple_cases/comments5.py b/tests/data/simple_cases/comments5.py
index c8c38813d55..bda40619f62 100644
--- a/tests/data/simple_cases/comments5.py
+++ b/tests/data/simple_cases/comments5.py
@@ -62,6 +62,8 @@ def decorated1():
 # Preview.empty_lines_before_class_or_def_with_leading_comments.
 # In the current style, the user will have to split those lines by hand.
 some_instruction
+
+
 # This comment should be split from `some_instruction` by two lines but isn't.
 def g():
     ...
diff --git a/tests/data/preview/comments8.py b/tests/data/simple_cases/comments8.py
similarity index 100%
rename from tests/data/preview/comments8.py
rename to tests/data/simple_cases/comments8.py
diff --git a/tests/data/preview/comments9.py b/tests/data/simple_cases/comments9.py
similarity index 100%
rename from tests/data/preview/comments9.py
rename to tests/data/simple_cases/comments9.py
diff --git a/tests/data/preview/docstring_preview.py b/tests/data/simple_cases/docstring_preview.py
similarity index 100%
rename from tests/data/preview/docstring_preview.py
rename to tests/data/simple_cases/docstring_preview.py
diff --git a/tests/data/simple_cases/empty_lines.py b/tests/data/simple_cases/empty_lines.py
index 4c03e432383..4fd47b93dca 100644
--- a/tests/data/simple_cases/empty_lines.py
+++ b/tests/data/simple_cases/empty_lines.py
@@ -119,7 +119,6 @@ def f():
     if not prev:
         prevp = preceding_leaf(p)
         if not prevp or prevp.type in OPENING_BRACKETS:
-
             return NO
 
         if prevp.type == token.EQUAL:
diff --git a/tests/data/simple_cases/fmtonoff.py b/tests/data/simple_cases/fmtonoff.py
index 5a50eb12ed3..e40ea2c8d21 100644
--- a/tests/data/simple_cases/fmtonoff.py
+++ b/tests/data/simple_cases/fmtonoff.py
@@ -205,6 +205,7 @@ def single_literal_yapf_disable():
 
 # Comment 2
 
+
 # fmt: off
 def func_no_args():
   a; b; c
diff --git a/tests/data/simple_cases/function_trailing_comma.py b/tests/data/simple_cases/function_trailing_comma.py
index abe9617c0e9..92f46e27516 100644
--- a/tests/data/simple_cases/function_trailing_comma.py
+++ b/tests/data/simple_cases/function_trailing_comma.py
@@ -116,9 +116,9 @@ def f(
         pass
 
 
-def xxxxxxxxxxxxxxxxxxxxxxxxxxxx() -> Set[
-    "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
-]:
+def xxxxxxxxxxxxxxxxxxxxxxxxxxxx() -> (
+    Set["xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"]
+):
     json = {
         "k": {
             "k2": {
@@ -140,9 +140,7 @@ def some_function_with_a_really_long_name() -> (
 
 def some_method_with_a_really_long_name(
     very_long_parameter_so_yeah: str, another_long_parameter: int
-) -> (
-    another_case_of_returning_a_deeply_nested_import_of_a_type_i_suppose_cause_why_not
-):
+) -> another_case_of_returning_a_deeply_nested_import_of_a_type_i_suppose_cause_why_not:
     pass
 
 
@@ -155,10 +153,8 @@ def func() -> (
 
 
 def func() -> (
-    (
-        also_super_long_type_annotation_that_may_cause_an_AST_related_crash_in_black(
-            this_shouldn_t_get_a_trailing_comma_too
-        )
+    also_super_long_type_annotation_that_may_cause_an_AST_related_crash_in_black(
+        this_shouldn_t_get_a_trailing_comma_too
     )
 ):
     pass
diff --git a/tests/data/preview/one_element_subscript.py b/tests/data/simple_cases/one_element_subscript.py
similarity index 100%
rename from tests/data/preview/one_element_subscript.py
rename to tests/data/simple_cases/one_element_subscript.py
diff --git a/tests/data/preview/prefer_rhs_split_reformatted.py b/tests/data/simple_cases/prefer_rhs_split_reformatted.py
similarity index 100%
rename from tests/data/preview/prefer_rhs_split_reformatted.py
rename to tests/data/simple_cases/prefer_rhs_split_reformatted.py
diff --git a/tests/data/preview/remove_await_parens.py b/tests/data/simple_cases/remove_await_parens.py
similarity index 100%
rename from tests/data/preview/remove_await_parens.py
rename to tests/data/simple_cases/remove_await_parens.py
diff --git a/tests/data/preview/remove_except_parens.py b/tests/data/simple_cases/remove_except_parens.py
similarity index 100%
rename from tests/data/preview/remove_except_parens.py
rename to tests/data/simple_cases/remove_except_parens.py
diff --git a/tests/data/preview/remove_for_brackets.py b/tests/data/simple_cases/remove_for_brackets.py
similarity index 100%
rename from tests/data/preview/remove_for_brackets.py
rename to tests/data/simple_cases/remove_for_brackets.py
diff --git a/tests/data/preview/remove_newline_after_code_block_open.py b/tests/data/simple_cases/remove_newline_after_code_block_open.py
similarity index 100%
rename from tests/data/preview/remove_newline_after_code_block_open.py
rename to tests/data/simple_cases/remove_newline_after_code_block_open.py
diff --git a/tests/data/preview/return_annotation_brackets.py b/tests/data/simple_cases/return_annotation_brackets.py
similarity index 93%
rename from tests/data/preview/return_annotation_brackets.py
rename to tests/data/simple_cases/return_annotation_brackets.py
index 27760bd51d7..265c30220d8 100644
--- a/tests/data/preview/return_annotation_brackets.py
+++ b/tests/data/simple_cases/return_annotation_brackets.py
@@ -87,10 +87,6 @@ def foo() -> tuple[loooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
 def foo() -> tuple[int, int, int,]:
     return 2
 
-# Long string example
-def frobnicate() -> "ThisIsTrulyUnreasonablyExtremelyLongClassName | list[ThisIsTrulyUnreasonablyExtremelyLongClassName]":
-    pass
-
 # output
 # Control
 def double(a: int) -> int:
@@ -212,11 +208,3 @@ def foo() -> (
     ]
 ):
     return 2
-
-
-# Long string example
-def frobnicate() -> (
-    "ThisIsTrulyUnreasonablyExtremelyLongClassName |"
-    " list[ThisIsTrulyUnreasonablyExtremelyLongClassName]"
-):
-    pass
diff --git a/tests/data/preview/skip_magic_trailing_comma.py b/tests/data/simple_cases/skip_magic_trailing_comma.py
similarity index 100%
rename from tests/data/preview/skip_magic_trailing_comma.py
rename to tests/data/simple_cases/skip_magic_trailing_comma.py
diff --git a/tests/data/preview/trailing_commas_in_leading_parts.py b/tests/data/simple_cases/trailing_commas_in_leading_parts.py
similarity index 100%
rename from tests/data/preview/trailing_commas_in_leading_parts.py
rename to tests/data/simple_cases/trailing_commas_in_leading_parts.py
diff --git a/tests/data/preview/whitespace.py b/tests/data/simple_cases/whitespace.py
similarity index 100%
rename from tests/data/preview/whitespace.py
rename to tests/data/simple_cases/whitespace.py
diff --git a/tests/test_black.py b/tests/test_black.py
index 44d617244f1..d0e78b7dd92 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -419,7 +419,8 @@ def test_skip_magic_trailing_comma(self) -> None:
             msg = (
                 "Expected diff isn't equal to the actual. If you made changes to"
                 " expression.py and this is an anticipated difference, overwrite"
-                f" tests/data/expression_skip_magic_trailing_comma.diff with {dump}"
+                " tests/data/miscellaneous/expression_skip_magic_trailing_comma.diff"
+                f" with {dump}"
             )
             self.assertEqual(expected, actual, msg)
 
diff --git a/tests/test_format.py b/tests/test_format.py
index adcbc02468d..ab849aac9a3 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -32,31 +32,15 @@ def check_file(
 @pytest.mark.filterwarnings("ignore:invalid escape sequence.*:DeprecationWarning")
 @pytest.mark.parametrize("filename", all_data_cases("simple_cases"))
 def test_simple_format(filename: str) -> None:
-    check_file("simple_cases", filename, DEFAULT_MODE)
-
-
-@pytest.mark.parametrize("filename", all_data_cases("preview"))
-def test_preview_format(filename: str) -> None:
     magic_trailing_comma = filename != "skip_magic_trailing_comma"
     check_file(
-        "preview",
-        filename,
-        black.Mode(preview=True, magic_trailing_comma=magic_trailing_comma),
+        "simple_cases", filename, black.Mode(magic_trailing_comma=magic_trailing_comma)
     )
 
 
-@pytest.mark.parametrize("filename", all_data_cases("preview_39"))
-def test_preview_minimum_python_39_format(filename: str) -> None:
-    source, expected = read_data("preview_39", filename)
-    mode = black.Mode(preview=True)
-    assert_format(source, expected, mode, minimum_version=(3, 9))
-
-
-@pytest.mark.parametrize("filename", all_data_cases("preview_310"))
-def test_preview_minimum_python_310_format(filename: str) -> None:
-    source, expected = read_data("preview_310", filename)
-    mode = black.Mode(preview=True)
-    assert_format(source, expected, mode, minimum_version=(3, 10))
+@pytest.mark.parametrize("filename", all_data_cases("preview"))
+def test_preview_format(filename: str) -> None:
+    check_file("preview", filename, black.Mode(preview=True))
 
 
 def test_preview_context_managers_targeting_py38() -> None:

From 69ca0a4c7a365c5f5eea519a90980bab72cab764 Mon Sep 17 00:00:00 2001
From: Stijn de Gooijer <stijn@degooijer.io>
Date: Wed, 1 Feb 2023 03:00:17 +0100
Subject: [PATCH 0712/1034] Infer target version based on project metadata
 (#3219)

Co-authored-by: Richard Si <sichard26@gmail.com>
---
 .pre-commit-config.yaml                       |   1 +
 CHANGES.md                                    |   5 +
 pyproject.toml                                |   1 +
 src/black/__init__.py                         |   5 +-
 src/black/files.py                            | 100 +++++++++++++++++-
 src/black/parsing.py                          |   6 +-
 .../data/project_metadata/both_pyproject.toml |   8 ++
 .../project_metadata/neither_pyproject.toml   |   6 ++
 .../only_black_pyproject.toml                 |   7 ++
 .../only_metadata_pyproject.toml              |   7 ++
 tests/test_black.py                           |  66 ++++++++++++
 11 files changed, 203 insertions(+), 9 deletions(-)
 create mode 100644 tests/data/project_metadata/both_pyproject.toml
 create mode 100644 tests/data/project_metadata/neither_pyproject.toml
 create mode 100644 tests/data/project_metadata/only_black_pyproject.toml
 create mode 100644 tests/data/project_metadata/only_metadata_pyproject.toml

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 576f6405d6c..a69fb645238 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -48,6 +48,7 @@ repos:
           - tomli >= 0.2.6, < 2.0.0
           - types-typed-ast >= 1.4.1
           - click >= 8.1.0
+          - packaging >= 22.0
           - platformdirs >= 2.1.0
           - pytest
           - hypothesis
diff --git a/CHANGES.md b/CHANGES.md
index ecc8a41f505..471567509d3 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -77,6 +77,9 @@
 
 <!-- Changes to how Black can be configured -->
 
+- Black now tries to infer its `--target-version` from the project metadata specified in
+  `pyproject.toml` (#3219)
+
 ### Packaging
 
 <!-- Changes to how Black is packaged, such as dependency requirements -->
@@ -86,6 +89,8 @@
 - Drop specific support for the `tomli` requirement on 3.11 alpha releases, working
   around a bug that would cause the requirement not to be installed on any non-final
   Python releases (#3448)
+- Black now depends on `packaging` version `22.0` or later. This is required for new
+  functionality that needs to parse part of the project metadata (#3219)
 
 ### Parser
 
diff --git a/pyproject.toml b/pyproject.toml
index ab38908ba15..435626ac8f4 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -65,6 +65,7 @@ classifiers = [
 dependencies = [
   "click>=8.0.0",
   "mypy_extensions>=0.4.3",
+  "packaging>=22.0",
   "pathspec>=0.9.0",
   "platformdirs>=2",
   "tomli>=1.1.0; python_version < '3.11'",
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 42bdfc1a5dd..4ebf28821c3 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -219,8 +219,9 @@ def validate_regex(
     callback=target_version_option_callback,
     multiple=True,
     help=(
-        "Python versions that should be supported by Black's output. [default: per-file"
-        " auto-detection]"
+        "Python versions that should be supported by Black's output. By default, Black"
+        " will try to infer this from the project metadata in pyproject.toml. If this"
+        " does not yield conclusive results, Black will use per-file auto-detection."
     ),
 )
 @click.option(
diff --git a/src/black/files.py b/src/black/files.py
index ea517f4ece9..8c0131126b7 100644
--- a/src/black/files.py
+++ b/src/black/files.py
@@ -18,6 +18,8 @@
 )
 
 from mypy_extensions import mypyc_attr
+from packaging.specifiers import InvalidSpecifier, Specifier, SpecifierSet
+from packaging.version import InvalidVersion, Version
 from pathspec import PathSpec
 from pathspec.patterns.gitwildmatch import GitWildMatchPatternError
 
@@ -32,6 +34,7 @@
     import tomli as tomllib
 
 from black.handle_ipynb_magics import jupyter_dependencies_are_installed
+from black.mode import TargetVersion
 from black.output import err
 from black.report import Report
 
@@ -108,14 +111,103 @@ def find_pyproject_toml(path_search_start: Tuple[str, ...]) -> Optional[str]:
 
 @mypyc_attr(patchable=True)
 def parse_pyproject_toml(path_config: str) -> Dict[str, Any]:
-    """Parse a pyproject toml file, pulling out relevant parts for Black
+    """Parse a pyproject toml file, pulling out relevant parts for Black.
 
-    If parsing fails, will raise a tomllib.TOMLDecodeError
+    If parsing fails, will raise a tomllib.TOMLDecodeError.
     """
     with open(path_config, "rb") as f:
         pyproject_toml = tomllib.load(f)
-    config = pyproject_toml.get("tool", {}).get("black", {})
-    return {k.replace("--", "").replace("-", "_"): v for k, v in config.items()}
+    config: Dict[str, Any] = pyproject_toml.get("tool", {}).get("black", {})
+    config = {k.replace("--", "").replace("-", "_"): v for k, v in config.items()}
+
+    if "target_version" not in config:
+        inferred_target_version = infer_target_version(pyproject_toml)
+        if inferred_target_version is not None:
+            config["target_version"] = [v.name.lower() for v in inferred_target_version]
+
+    return config
+
+
+def infer_target_version(
+    pyproject_toml: Dict[str, Any]
+) -> Optional[List[TargetVersion]]:
+    """Infer Black's target version from the project metadata in pyproject.toml.
+
+    Supports the PyPA standard format (PEP 621):
+    https://packaging.python.org/en/latest/specifications/declaring-project-metadata/#requires-python
+
+    If the target version cannot be inferred, returns None.
+    """
+    project_metadata = pyproject_toml.get("project", {})
+    requires_python = project_metadata.get("requires-python", None)
+    if requires_python is not None:
+        try:
+            return parse_req_python_version(requires_python)
+        except InvalidVersion:
+            pass
+        try:
+            return parse_req_python_specifier(requires_python)
+        except (InvalidSpecifier, InvalidVersion):
+            pass
+
+    return None
+
+
+def parse_req_python_version(requires_python: str) -> Optional[List[TargetVersion]]:
+    """Parse a version string (i.e. ``"3.7"``) to a list of TargetVersion.
+
+    If parsing fails, will raise a packaging.version.InvalidVersion error.
+    If the parsed version cannot be mapped to a valid TargetVersion, returns None.
+    """
+    version = Version(requires_python)
+    if version.release[0] != 3:
+        return None
+    try:
+        return [TargetVersion(version.release[1])]
+    except (IndexError, ValueError):
+        return None
+
+
+def parse_req_python_specifier(requires_python: str) -> Optional[List[TargetVersion]]:
+    """Parse a specifier string (i.e. ``">=3.7,<3.10"``) to a list of TargetVersion.
+
+    If parsing fails, will raise a packaging.specifiers.InvalidSpecifier error.
+    If the parsed specifier cannot be mapped to a valid TargetVersion, returns None.
+    """
+    specifier_set = strip_specifier_set(SpecifierSet(requires_python))
+    if not specifier_set:
+        return None
+
+    target_version_map = {f"3.{v.value}": v for v in TargetVersion}
+    compatible_versions: List[str] = list(specifier_set.filter(target_version_map))
+    if compatible_versions:
+        return [target_version_map[v] for v in compatible_versions]
+    return None
+
+
+def strip_specifier_set(specifier_set: SpecifierSet) -> SpecifierSet:
+    """Strip minor versions for some specifiers in the specifier set.
+
+    For background on version specifiers, see PEP 440:
+    https://peps.python.org/pep-0440/#version-specifiers
+    """
+    specifiers = []
+    for s in specifier_set:
+        if "*" in str(s):
+            specifiers.append(s)
+        elif s.operator in ["~=", "==", ">=", "==="]:
+            version = Version(s.version)
+            stripped = Specifier(f"{s.operator}{version.major}.{version.minor}")
+            specifiers.append(stripped)
+        elif s.operator == ">":
+            version = Version(s.version)
+            if len(version.release) > 2:
+                s = Specifier(f">={version.major}.{version.minor}")
+            specifiers.append(s)
+        else:
+            specifiers.append(s)
+
+    return SpecifierSet(",".join(str(s) for s in specifiers))
 
 
 @lru_cache()
diff --git a/src/black/parsing.py b/src/black/parsing.py
index c37c12b868d..ba474c5e047 100644
--- a/src/black/parsing.py
+++ b/src/black/parsing.py
@@ -11,7 +11,7 @@
 else:
     from typing import Final
 
-from black.mode import Feature, TargetVersion, supports_feature
+from black.mode import VERSION_TO_FEATURES, Feature, TargetVersion, supports_feature
 from black.nodes import syms
 from blib2to3 import pygram
 from blib2to3.pgen2 import driver
@@ -52,7 +52,7 @@ def get_grammars(target_versions: Set[TargetVersion]) -> List[Grammar]:
     if not target_versions:
         # No target_version specified, so try all grammars.
         return [
-            # Python 3.7+
+            # Python 3.7-3.9
             pygram.python_grammar_no_print_statement_no_exec_statement_async_keywords,
             # Python 3.0-3.6
             pygram.python_grammar_no_print_statement_no_exec_statement,
@@ -72,7 +72,7 @@ def get_grammars(target_versions: Set[TargetVersion]) -> List[Grammar]:
     if not supports_feature(target_versions, Feature.ASYNC_KEYWORDS):
         # Python 3.0-3.6
         grammars.append(pygram.python_grammar_no_print_statement_no_exec_statement)
-    if supports_feature(target_versions, Feature.PATTERN_MATCHING):
+    if any(Feature.PATTERN_MATCHING in VERSION_TO_FEATURES[v] for v in target_versions):
         # Python 3.10+
         grammars.append(pygram.python_grammar_soft_keywords)
 
diff --git a/tests/data/project_metadata/both_pyproject.toml b/tests/data/project_metadata/both_pyproject.toml
new file mode 100644
index 00000000000..cf8f148f856
--- /dev/null
+++ b/tests/data/project_metadata/both_pyproject.toml
@@ -0,0 +1,8 @@
+[project]
+name = "test"
+version = "1.0.0"
+requires-python = ">=3.7,<3.11"
+
+[tool.black]
+line-length = 79
+target-version = ["py310"]
diff --git a/tests/data/project_metadata/neither_pyproject.toml b/tests/data/project_metadata/neither_pyproject.toml
new file mode 100644
index 00000000000..67623d2279b
--- /dev/null
+++ b/tests/data/project_metadata/neither_pyproject.toml
@@ -0,0 +1,6 @@
+[project]
+name = "test"
+version = "1.0.0"
+
+[tool.black]
+line-length = 79
diff --git a/tests/data/project_metadata/only_black_pyproject.toml b/tests/data/project_metadata/only_black_pyproject.toml
new file mode 100644
index 00000000000..94058bb3b1e
--- /dev/null
+++ b/tests/data/project_metadata/only_black_pyproject.toml
@@ -0,0 +1,7 @@
+[project]
+name = "test"
+version = "1.0.0"
+
+[tool.black]
+line-length = 79
+target-version = ["py310"]
diff --git a/tests/data/project_metadata/only_metadata_pyproject.toml b/tests/data/project_metadata/only_metadata_pyproject.toml
new file mode 100644
index 00000000000..1c8cdbb31ad
--- /dev/null
+++ b/tests/data/project_metadata/only_metadata_pyproject.toml
@@ -0,0 +1,7 @@
+[project]
+name = "test"
+version = "1.0.0"
+requires-python = ">=3.7,<3.11"
+
+[tool.black]
+line-length = 79
diff --git a/tests/test_black.py b/tests/test_black.py
index d0e78b7dd92..e5e17777715 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -1560,6 +1560,72 @@ def test_parse_pyproject_toml(self) -> None:
         self.assertEqual(config["exclude"], r"\.pyi?$")
         self.assertEqual(config["include"], r"\.py?$")
 
+    def test_parse_pyproject_toml_project_metadata(self) -> None:
+        for test_toml, expected in [
+            ("only_black_pyproject.toml", ["py310"]),
+            ("only_metadata_pyproject.toml", ["py37", "py38", "py39", "py310"]),
+            ("neither_pyproject.toml", None),
+            ("both_pyproject.toml", ["py310"]),
+        ]:
+            test_toml_file = THIS_DIR / "data" / "project_metadata" / test_toml
+            config = black.parse_pyproject_toml(str(test_toml_file))
+            self.assertEqual(config.get("target_version"), expected)
+
+    def test_infer_target_version(self) -> None:
+        for version, expected in [
+            ("3.6", [TargetVersion.PY36]),
+            ("3.11.0rc1", [TargetVersion.PY311]),
+            (">=3.10", [TargetVersion.PY310, TargetVersion.PY311]),
+            (">=3.10.6", [TargetVersion.PY310, TargetVersion.PY311]),
+            ("<3.6", [TargetVersion.PY33, TargetVersion.PY34, TargetVersion.PY35]),
+            (">3.7,<3.10", [TargetVersion.PY38, TargetVersion.PY39]),
+            (">3.7,!=3.8,!=3.9", [TargetVersion.PY310, TargetVersion.PY311]),
+            (
+                "> 3.9.4, != 3.10.3",
+                [TargetVersion.PY39, TargetVersion.PY310, TargetVersion.PY311],
+            ),
+            (
+                "!=3.3,!=3.4",
+                [
+                    TargetVersion.PY35,
+                    TargetVersion.PY36,
+                    TargetVersion.PY37,
+                    TargetVersion.PY38,
+                    TargetVersion.PY39,
+                    TargetVersion.PY310,
+                    TargetVersion.PY311,
+                ],
+            ),
+            (
+                "==3.*",
+                [
+                    TargetVersion.PY33,
+                    TargetVersion.PY34,
+                    TargetVersion.PY35,
+                    TargetVersion.PY36,
+                    TargetVersion.PY37,
+                    TargetVersion.PY38,
+                    TargetVersion.PY39,
+                    TargetVersion.PY310,
+                    TargetVersion.PY311,
+                ],
+            ),
+            ("==3.8.*", [TargetVersion.PY38]),
+            (None, None),
+            ("", None),
+            ("invalid", None),
+            ("==invalid", None),
+            (">3.9,!=invalid", None),
+            ("3", None),
+            ("3.2", None),
+            ("2.7.18", None),
+            ("==2.7", None),
+            (">3.10,<3.11", None),
+        ]:
+            test_toml = {"project": {"requires-python": version}}
+            result = black.files.infer_target_version(test_toml)
+            self.assertEqual(result, expected)
+
     def test_read_pyproject_toml(self) -> None:
         test_toml_file = THIS_DIR / "test.toml"
         fake_ctx = FakeContext()

From b0d1fba7ac3be53c71fb0d3211d911e629f8aecb Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Tue, 31 Jan 2023 18:47:11 -0800
Subject: [PATCH 0713/1034] Prepare release 23.1.0 (#3536)

Co-authored-by: Richard Si <sichard26@gmail.com>
---
 CHANGES.md                                  | 78 +++++++++++++++++----
 docs/integrations/source_version_control.md |  2 +-
 docs/usage_and_configuration/the_basics.md  |  2 +-
 3 files changed, 65 insertions(+), 17 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 471567509d3..2071eb3f800 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -10,6 +10,64 @@
 
 <!-- Changes that affect Black's stable style -->
 
+### Preview style
+
+<!-- Changes that affect Black's preview style -->
+
+### Configuration
+
+<!-- Changes to how Black can be configured -->
+
+### Packaging
+
+<!-- Changes to how Black is packaged, such as dependency requirements -->
+
+### Parser
+
+<!-- Changes to the parser or to version autodetection -->
+
+### Performance
+
+<!-- Changes that improve Black's performance. -->
+
+### Output
+
+<!-- Changes to Black's terminal output and error messages -->
+
+### _Blackd_
+
+<!-- Changes to blackd -->
+
+### Integrations
+
+<!-- For example, Docker, GitHub Actions, pre-commit, editors -->
+
+### Documentation
+
+<!-- Major changes to documentation and policies. Small docs changes
+     don't need a changelog entry. -->
+
+## 23.1.0
+
+### Highlights
+
+This is the first release of 2023, and following our
+[stability policy](https://black.readthedocs.io/en/stable/the_black_code_style/index.html#stability-policy),
+it comes with a number of improvements to our stable style, including improvements to
+empty line handling, removal of redundant parentheses in several contexts, and output
+that highlights implicitly concatenated strings better.
+
+There are also many changes to the preview style; try out `black --preview` and give us
+feedback to help us set the stable style for next year.
+
+In addition to style changes, Black now automatically infers the supported Python
+versions from your `pyproject.toml` file, removing the need to set Black's target
+versions separately.
+
+### Stable style
+
+<!-- Changes that affect Black's stable style -->
+
 - Introduce the 2023 stable style, which incorporates most aspects of last year's
   preview style (#3418). Specific changes:
   - Enforce empty lines before classes and functions with sticky leading comments
@@ -45,9 +103,9 @@
 
 <!-- Changes that affect Black's preview style -->
 
-- Format hex code in unicode escape sequences in string literals (#2916)
+- Format hex codes in unicode escape sequences in string literals (#2916)
 - Add parentheses around `if`-`else` expressions (#2278)
-- Improve the performance on large expressions that contain many strings (#3467)
+- Improve performance on large expressions that contain many strings (#3467)
 - Fix a crash in preview style with assert + parenthesized string (#3415)
 - Fix crashes in preview style with walrus operators used in function return annotations
   and except clauses (#3423)
@@ -86,20 +144,14 @@
 
 - Upgrade mypyc from `0.971` to `0.991` so mypycified _Black_ can be built on armv7
   (#3380)
+  - This also fixes some crashes while using compiled Black with a debug build of
+    CPython
 - Drop specific support for the `tomli` requirement on 3.11 alpha releases, working
   around a bug that would cause the requirement not to be installed on any non-final
   Python releases (#3448)
 - Black now depends on `packaging` version `22.0` or later. This is required for new
   functionality that needs to parse part of the project metadata (#3219)
 
-### Parser
-
-<!-- Changes to the parser or to version autodetection -->
-
-### Performance
-
-<!-- Changes that improve Black's performance. -->
-
 ### Output
 
 <!-- Changes to Black's terminal output and error messages -->
@@ -111,15 +163,11 @@
 - Fix false symlink detection messages in verbose output due to using an incorrect
   relative path to the project root (#3385)
 
-### _Blackd_
-
-<!-- Changes to blackd -->
-
 ### Integrations
 
 <!-- For example, Docker, GitHub Actions, pre-commit, editors -->
 
-- Move 3.11 CI to normal flow now all dependencies support 3.11 (#3446)
+- Move 3.11 CI to normal flow now that all dependencies support 3.11 (#3446)
 - Docker: Add new `latest_prerelease` tag automation to follow latest black alpha
   release on docker images (#3465)
 
diff --git a/docs/integrations/source_version_control.md b/docs/integrations/source_version_control.md
index 712b9a688d1..d462e2cc18a 100644
--- a/docs/integrations/source_version_control.md
+++ b/docs/integrations/source_version_control.md
@@ -7,7 +7,7 @@ Use [pre-commit](https://pre-commit.com/). Once you
 ```yaml
 repos:
   - repo: https://github.com/psf/black
-    rev: 22.12.0
+    rev: 23.1.0
     hooks:
       - id: black
         # It is recommended to specify the latest version of Python
diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index 9dc5277c61e..2b41c187766 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -178,7 +178,7 @@ You can check the version of _Black_ you have installed using the `--version` fl
 
 ```console
 $ black --version
-black, version 22.12.0
+black, version 23.1.0
 ```
 
 An option to require a specific version to be running is also provided.

From dd0e912a6e7ebe432299e317e2e79b592fc2adc3 Mon Sep 17 00:00:00 2001
From: "Yilei \"Dolee\" Yang" <yileiyang@google.com>
Date: Fri, 3 Feb 2023 22:00:09 -0800
Subject: [PATCH 0714/1034] Fix import of blib2to3.pgen2.driver (#3546)

---
 src/blib2to3/pgen2/parse.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/blib2to3/pgen2/parse.py b/src/blib2to3/pgen2/parse.py
index d6deaac6964..c462f63ad2c 100644
--- a/src/blib2to3/pgen2/parse.py
+++ b/src/blib2to3/pgen2/parse.py
@@ -32,7 +32,7 @@
 from blib2to3.pytree import convert, NL, Context, RawNode, Leaf, Node
 
 if TYPE_CHECKING:
-    from blib2to3.driver import TokenProxy
+    from blib2to3.pgen2.driver import TokenProxy
 
 
 Results = Dict[Text, NL]

From ea5293b0360b6e2e56c004d1e27cbe33c87dcb94 Mon Sep 17 00:00:00 2001
From: "Yilei \"Dolee\" Yang" <yileiyang@google.com>
Date: Sat, 4 Feb 2023 19:30:47 -0800
Subject: [PATCH 0715/1034] Document the future style changes introduced in
 #3489 and #3440 (#3541)

---
 docs/the_black_code_style/future_style.md | 49 +++++++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/docs/the_black_code_style/future_style.md b/docs/the_black_code_style/future_style.md
index 6d289d460a7..b2cdca2590d 100644
--- a/docs/the_black_code_style/future_style.md
+++ b/docs/the_black_code_style/future_style.md
@@ -62,3 +62,52 @@ plain strings. User-made splits are respected when they do not exceed the line l
 limit. Line continuation backslashes are converted into parenthesized strings.
 Unnecessary parentheses are stripped. The stability and status of this feature is
 tracked in [this issue](https://github.com/psf/black/issues/2188).
+
+### Improved line breaks
+
+For assignment expressions, _Black_ now prefers to split and wrap the right side of the
+assignment instead of left side. For example:
+
+```python
+some_dict[
+    "with_a_long_key"
+] = some_looooooooong_module.some_looooooooooooooong_function_name(
+    first_argument, second_argument, third_argument
+)
+```
+
+will be changed to:
+
+```python
+some_dict["with_a_long_key"] = (
+    some_looooooooong_module.some_looooooooooooooong_function_name(
+        first_argument, second_argument, third_argument
+    )
+)
+```
+
+### Improved parentheses management
+
+For dict literals with long values, they are now wrapped in parentheses. Unnecessary
+parentheses are now removed. For example:
+
+```python
+my_dict = {
+    my_dict = {
+    "a key in my dict": a_very_long_variable
+    * and_a_very_long_function_call()
+    / 100000.0,
+    "another key": (short_value),
+}
+```
+
+will be changed to:
+
+```python
+my_dict = {
+    "a key in my dict": (
+        a_very_long_variable * and_a_very_long_function_call() / 100000.0
+    ),
+    "another key": short_value,
+}
+```

From ff53fc1b97b98075f92fcc954ed81b9252e7c9c1 Mon Sep 17 00:00:00 2001
From: mainj12 <118842653+mainj12@users.noreply.github.com>
Date: Sun, 5 Feb 2023 03:35:43 +0000
Subject: [PATCH 0716/1034] Actually add trailing commas to collection literals
 even if there are terminating comments (#3393)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Co-authored-by: Richard Si <sichard26@gmail.com>
---
 CHANGES.md                                    |  3 +
 src/black/linegen.py                          | 62 ++++++++++++++-----
 src/black/mode.py                             |  1 +
 src/black/trans.py                            | 12 ++--
 tests/data/preview/trailing_comma.py          | 55 ++++++++++++++++
 .../targeting_py39.py                         |  2 +-
 6 files changed, 114 insertions(+), 21 deletions(-)
 create mode 100644 tests/data/preview/trailing_comma.py

diff --git a/CHANGES.md b/CHANGES.md
index 2071eb3f800..a8b556cb7e8 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -14,6 +14,9 @@
 
 <!-- Changes that affect Black's preview style -->
 
+- Add trailing commas to collection literals even if there's a comment after the last
+  entry (#3393)
+
 ### Configuration
 
 <!-- Changes to how Black can be configured -->
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 7afb1733939..c582b2d6dff 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -520,7 +520,7 @@ def transform_line(
     else:
 
         def _rhs(
-            self: object, line: Line, features: Collection[Feature]
+            self: object, line: Line, features: Collection[Feature], mode: Mode
         ) -> Iterator[Line]:
             """Wraps calls to `right_hand_split`.
 
@@ -604,7 +604,9 @@ class _BracketSplitComponent(Enum):
     tail = auto()
 
 
-def left_hand_split(line: Line, _features: Collection[Feature] = ()) -> Iterator[Line]:
+def left_hand_split(
+    line: Line, _features: Collection[Feature], mode: Mode
+) -> Iterator[Line]:
     """Split line into many lines, starting with the first matching bracket pair.
 
     Note: this usually looks weird, only use this for function definitions.
@@ -940,16 +942,39 @@ def dont_increase_indentation(split_func: Transformer) -> Transformer:
     """
 
     @wraps(split_func)
-    def split_wrapper(line: Line, features: Collection[Feature] = ()) -> Iterator[Line]:
-        for split_line in split_func(line, features):
+    def split_wrapper(
+        line: Line, features: Collection[Feature], mode: Mode
+    ) -> Iterator[Line]:
+        for split_line in split_func(line, features, mode):
             normalize_prefix(split_line.leaves[0], inside_brackets=True)
             yield split_line
 
     return split_wrapper
 
 
+def _get_last_non_comment_leaf(line: Line) -> Optional[int]:
+    for leaf_idx in range(len(line.leaves) - 1, 0, -1):
+        if line.leaves[leaf_idx].type != STANDALONE_COMMENT:
+            return leaf_idx
+    return None
+
+
+def _safe_add_trailing_comma(safe: bool, delimiter_priority: int, line: Line) -> Line:
+    if (
+        safe
+        and delimiter_priority == COMMA_PRIORITY
+        and line.leaves[-1].type != token.COMMA
+        and line.leaves[-1].type != STANDALONE_COMMENT
+    ):
+        new_comma = Leaf(token.COMMA, ",")
+        line.append(new_comma)
+    return line
+
+
 @dont_increase_indentation
-def delimiter_split(line: Line, features: Collection[Feature] = ()) -> Iterator[Line]:
+def delimiter_split(
+    line: Line, features: Collection[Feature], mode: Mode
+) -> Iterator[Line]:
     """Split according to delimiters of the highest priority.
 
     If the appropriate Features are given, the split will add trailing commas
@@ -989,7 +1014,8 @@ def append_to_line(leaf: Leaf) -> Iterator[Line]:
             )
             current_line.append(leaf)
 
-    for leaf in line.leaves:
+    last_non_comment_leaf = _get_last_non_comment_leaf(line)
+    for leaf_idx, leaf in enumerate(line.leaves):
         yield from append_to_line(leaf)
 
         for comment_after in line.comments_after(leaf):
@@ -1006,6 +1032,15 @@ def append_to_line(leaf: Leaf) -> Iterator[Line]:
                     trailing_comma_safe and Feature.TRAILING_COMMA_IN_CALL in features
                 )
 
+        if (
+            Preview.add_trailing_comma_consistently in mode
+            and last_leaf.type == STANDALONE_COMMENT
+            and leaf_idx == last_non_comment_leaf
+        ):
+            current_line = _safe_add_trailing_comma(
+                trailing_comma_safe, delimiter_priority, current_line
+            )
+
         leaf_priority = bt.delimiters.get(id(leaf))
         if leaf_priority == delimiter_priority:
             yield current_line
@@ -1014,20 +1049,15 @@ def append_to_line(leaf: Leaf) -> Iterator[Line]:
                 mode=line.mode, depth=line.depth, inside_brackets=line.inside_brackets
             )
     if current_line:
-        if (
-            trailing_comma_safe
-            and delimiter_priority == COMMA_PRIORITY
-            and current_line.leaves[-1].type != token.COMMA
-            and current_line.leaves[-1].type != STANDALONE_COMMENT
-        ):
-            new_comma = Leaf(token.COMMA, ",")
-            current_line.append(new_comma)
+        current_line = _safe_add_trailing_comma(
+            trailing_comma_safe, delimiter_priority, current_line
+        )
         yield current_line
 
 
 @dont_increase_indentation
 def standalone_comment_split(
-    line: Line, features: Collection[Feature] = ()
+    line: Line, features: Collection[Feature], mode: Mode
 ) -> Iterator[Line]:
     """Split standalone comments from the rest of the line."""
     if not line.contains_standalone_comments(0):
@@ -1480,7 +1510,7 @@ def run_transformer(
     if not line_str:
         line_str = line_to_string(line)
     result: List[Line] = []
-    for transformed_line in transform(line, features):
+    for transformed_line in transform(line, features, mode):
         if str(transformed_line).strip("\n") == line_str:
             raise CannotTransform("Line transformer returned an unchanged result")
 
diff --git a/src/black/mode.py b/src/black/mode.py
index 1af16070073..c9a4c2b080c 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -153,6 +153,7 @@ def supports_feature(target_versions: Set[TargetVersion], feature: Feature) -> b
 class Preview(Enum):
     """Individual preview style features."""
 
+    add_trailing_comma_consistently = auto()
     hex_codes_in_unicode_sequences = auto()
     prefer_splitting_right_hand_side_of_assignments = auto()
     # NOTE: string_processing requires wrap_long_dict_values_in_parens
diff --git a/src/black/trans.py b/src/black/trans.py
index 2360c13f06a..a6a416e71bc 100644
--- a/src/black/trans.py
+++ b/src/black/trans.py
@@ -32,7 +32,7 @@
 
 from black.comments import contains_pragma_comment
 from black.lines import Line, append_leaves
-from black.mode import Feature
+from black.mode import Feature, Mode
 from black.nodes import (
     CLOSING_BRACKETS,
     OPENING_BRACKETS,
@@ -63,7 +63,7 @@ class CannotTransform(Exception):
 # types
 T = TypeVar("T")
 LN = Union[Leaf, Node]
-Transformer = Callable[[Line, Collection[Feature]], Iterator[Line]]
+Transformer = Callable[[Line, Collection[Feature], Mode], Iterator[Line]]
 Index = int
 NodeType = int
 ParserState = int
@@ -81,7 +81,9 @@ def TErr(err_msg: str) -> Err[CannotTransform]:
     return Err(cant_transform)
 
 
-def hug_power_op(line: Line, features: Collection[Feature]) -> Iterator[Line]:
+def hug_power_op(
+    line: Line, features: Collection[Feature], mode: Mode
+) -> Iterator[Line]:
     """A transformer which normalizes spacing around power operators."""
 
     # Performance optimization to avoid unnecessary Leaf clones and other ops.
@@ -228,7 +230,9 @@ def do_transform(
             yield an CannotTransform after that point.)
         """
 
-    def __call__(self, line: Line, _features: Collection[Feature]) -> Iterator[Line]:
+    def __call__(
+        self, line: Line, _features: Collection[Feature], _mode: Mode
+    ) -> Iterator[Line]:
         """
         StringTransformer instances have a call signature that mirrors that of
         the Transformer type.
diff --git a/tests/data/preview/trailing_comma.py b/tests/data/preview/trailing_comma.py
new file mode 100644
index 00000000000..5b09c664606
--- /dev/null
+++ b/tests/data/preview/trailing_comma.py
@@ -0,0 +1,55 @@
+e = {
+    "a": fun(msg, "ts"),
+    "longggggggggggggggid": ...,
+    "longgggggggggggggggggggkey": ..., "created": ...
+    # "longkey": ...
+}
+f = [
+    arg1,
+    arg2,
+    arg3, arg4
+    # comment
+]
+g = (
+    arg1,
+    arg2,
+    arg3, arg4
+    # comment
+)
+h = {
+    arg1,
+    arg2,
+    arg3, arg4
+    # comment
+}
+
+# output
+
+e = {
+    "a": fun(msg, "ts"),
+    "longggggggggggggggid": ...,
+    "longgggggggggggggggggggkey": ...,
+    "created": ...,
+    # "longkey": ...
+}
+f = [
+    arg1,
+    arg2,
+    arg3,
+    arg4,
+    # comment
+]
+g = (
+    arg1,
+    arg2,
+    arg3,
+    arg4,
+    # comment
+)
+h = {
+    arg1,
+    arg2,
+    arg3,
+    arg4,
+    # comment
+}
diff --git a/tests/data/preview_context_managers/targeting_py39.py b/tests/data/preview_context_managers/targeting_py39.py
index 5cb8763040a..64f5d09bbe8 100644
--- a/tests/data/preview_context_managers/targeting_py39.py
+++ b/tests/data/preview_context_managers/targeting_py39.py
@@ -84,7 +84,7 @@
     # First comment.
     new_new_new1() as cm1,
     # Second comment.
-    new_new_new2()
+    new_new_new2(),
     # Last comment.
 ):
     pass

From e506c46f7b44e788dfd279e9a474af83e4e03eca Mon Sep 17 00:00:00 2001
From: Richard Si <sichard26@gmail.com>
Date: Sat, 4 Feb 2023 22:51:46 -0500
Subject: [PATCH 0717/1034] Rename design label to style because it's clearer
 (#3547)

---
 .github/ISSUE_TEMPLATE/style_issue.md | 6 +++---
 docs/contributing/issue_triage.md     | 4 ++--
 docs/the_black_code_style/index.md    | 2 +-
 3 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/.github/ISSUE_TEMPLATE/style_issue.md b/.github/ISSUE_TEMPLATE/style_issue.md
index 2e4343a3527..a9ce85fd977 100644
--- a/.github/ISSUE_TEMPLATE/style_issue.md
+++ b/.github/ISSUE_TEMPLATE/style_issue.md
@@ -1,8 +1,8 @@
 ---
-name: Style issue
-about: Help us improve the Black style
+name: Code style issue
+about: Help us improve the Black code style
 title: ""
-labels: "T: design"
+labels: "T: style"
 assignees: ""
 ---
 
diff --git a/docs/contributing/issue_triage.md b/docs/contributing/issue_triage.md
index 865a47935ed..aa3e49a649b 100644
--- a/docs/contributing/issue_triage.md
+++ b/docs/contributing/issue_triage.md
@@ -1,6 +1,6 @@
 # Issue triage
 
-Currently, _Black_ uses the issue tracker for bugs, feature requests, proposed design
+Currently, _Black_ uses the issue tracker for bugs, feature requests, proposed style
 modifications, and general user support. Each of these issues have to be triaged so they
 can be eventually be resolved somehow. This document outlines the triaging process and
 also the current guidelines and recommendations.
@@ -53,7 +53,7 @@ The lifecycle of a bug report or user support issue typically goes something lik
    - the issue has been fixed
    - duplicate of another pre-existing issue or is invalid
 
-For enhancement, documentation, and design issues, the lifecycle looks very similar but
+For enhancement, documentation, and style issues, the lifecycle looks very similar but
 the details are different:
 
 1. _the issue is waiting for triage_
diff --git a/docs/the_black_code_style/index.md b/docs/the_black_code_style/index.md
index e5967be2db4..1719347eec8 100644
--- a/docs/the_black_code_style/index.md
+++ b/docs/the_black_code_style/index.md
@@ -17,7 +17,7 @@ Python language and, occasionally, in response to user feedback. Large-scale sty
 preferences presented in {doc}`current_style` are very unlikely to change, but minor
 style aspects and details might change according to the stability policy presented
 below. Ongoing style considerations are tracked on GitHub with the
-[design](https://github.com/psf/black/labels/T%3A%20design) issue label.
+[style](https://github.com/psf/black/labels/T%3A%20style) issue label.
 
 (labels/stability-policy)=
 

From e74a05286b8b0c4a65419d21c4c17a33d9d7e15c Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 6 Feb 2023 19:56:38 -0800
Subject: [PATCH 0718/1034] Bump docker/build-push-action from 3 to 4 (#3549)

Bumps [docker/build-push-action](https://github.com/docker/build-push-action) from 3 to 4.
- [Release notes](https://github.com/docker/build-push-action/releases)
- [Commits](https://github.com/docker/build-push-action/compare/v3...v4)

---
updated-dependencies:
- dependency-name: docker/build-push-action
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/docker.yml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
index 04e30e727bd..8baace940ba 100644
--- a/.github/workflows/docker.yml
+++ b/.github/workflows/docker.yml
@@ -36,7 +36,7 @@ jobs:
           latest_non_release)" >> $GITHUB_ENV
 
       - name: Build and push
-        uses: docker/build-push-action@v3
+        uses: docker/build-push-action@v4
         with:
           context: .
           platforms: linux/amd64,linux/arm64
@@ -47,7 +47,7 @@ jobs:
         if:
           ${{ github.event_name == 'release' && github.event.action == 'published' &&
           !github.event.release.prerelease }}
-        uses: docker/build-push-action@v3
+        uses: docker/build-push-action@v4
         with:
           context: .
           platforms: linux/amd64,linux/arm64
@@ -58,7 +58,7 @@ jobs:
         if:
           ${{ github.event_name == 'release' && github.event.action == 'published' &&
           github.event.release.prerelease }}
-        uses: docker/build-push-action@v3
+        uses: docker/build-push-action@v4
         with:
           context: .
           platforms: linux/amd64,linux/arm64

From 9c8464ca7ddd48d1c19112d895ae12d783f01563 Mon Sep 17 00:00:00 2001
From: "Yilei \"Dolee\" Yang" <yileiyang@google.com>
Date: Tue, 7 Feb 2023 14:48:09 -0800
Subject: [PATCH 0719/1034] Fix typos in comments: assignement -> assignment
 (#3556)

---
 src/black/linegen.py                                    | 2 +-
 tests/data/preview/prefer_rhs_split.py                  | 2 +-
 tests/data/simple_cases/prefer_rhs_split_reformatted.py | 4 ++--
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/black/linegen.py b/src/black/linegen.py
index c582b2d6dff..f7d3655e962 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -762,7 +762,7 @@ def _maybe_split_omitting_optional_parens(
                 # the split is right after `=`
                 and len(rhs.head.leaves) >= 2
                 and rhs.head.leaves[-2].type == token.EQUAL
-                # the left side of assignement contains brackets
+                # the left side of assignment contains brackets
                 and any(leaf.type in BRACKETS for leaf in rhs.head.leaves[:-1])
                 # the left side of assignment is short enough (the -1 is for the ending
                 # optional paren)
diff --git a/tests/data/preview/prefer_rhs_split.py b/tests/data/preview/prefer_rhs_split.py
index 2f3cf33db41..a809eacc773 100644
--- a/tests/data/preview/prefer_rhs_split.py
+++ b/tests/data/preview/prefer_rhs_split.py
@@ -69,7 +69,7 @@
 ] = lambda obj: obj.some_long_named_method()
 
 
-# Make when when the left side of assignement plus the opening paren "... = (" is
+# Make when when the left side of assignment plus the opening paren "... = (" is
 # exactly line length limit + 1, it won't be split like that.
 xxxxxxxxx_yyy_zzzzzzzz[
     xx.xxxxxx(x_yyy_zzzzzz.xxxxx[0]), x_yyy_zzzzzz.xxxxxx(xxxx=1)
diff --git a/tests/data/simple_cases/prefer_rhs_split_reformatted.py b/tests/data/simple_cases/prefer_rhs_split_reformatted.py
index 781e75be0aa..e15e5ddc86d 100644
--- a/tests/data/simple_cases/prefer_rhs_split_reformatted.py
+++ b/tests/data/simple_cases/prefer_rhs_split_reformatted.py
@@ -7,7 +7,7 @@
     arg2,
 )
 
-# Make when when the left side of assignement plus the opening paren "... = (" is
+# Make when when the left side of assignment plus the opening paren "... = (" is
 # exactly line length limit + 1, it won't be split like that.
 xxxxxxxxx_yyy_zzzzzzzz[xx.xxxxxx(x_yyy_zzzzzz.xxxxx[0]), x_yyy_zzzzzz.xxxxxx(xxxx=1)] = 1
 
@@ -31,7 +31,7 @@
     arg2,
 )
 
-# Make when when the left side of assignement plus the opening paren "... = (" is
+# Make when when the left side of assignment plus the opening paren "... = (" is
 # exactly line length limit + 1, it won't be split like that.
 xxxxxxxxx_yyy_zzzzzzzz[
     xx.xxxxxx(x_yyy_zzzzzz.xxxxx[0]), x_yyy_zzzzzz.xxxxxx(xxxx=1)

From d9b8a6407e2f46304a8d36b18e4a73d8e0613519 Mon Sep 17 00:00:00 2001
From: brucearctor <5032356+brucearctor@users.noreply.github.com>
Date: Mon, 13 Feb 2023 17:24:28 -0800
Subject: [PATCH 0720/1034] Update Action example to use checkout@v3 (#3563)

Latest version of `actions/checkout` is v3 (or rather v3.3) so let's
use that in the example now.
---
 docs/integrations/github_actions.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/integrations/github_actions.md b/docs/integrations/github_actions.md
index ebfcc2d95a2..56b2cdd0586 100644
--- a/docs/integrations/github_actions.md
+++ b/docs/integrations/github_actions.md
@@ -24,7 +24,7 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - uses: psf/black@stable
 ```
 

From 25d886f52c2bbbb58386ac8050f4e67952507bc7 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 27 Feb 2023 06:38:02 -0800
Subject: [PATCH 0721/1034] Bump peter-evans/find-comment from 2.2.0 to 2.3.0
 (#3584)

Bumps [peter-evans/find-comment](https://github.com/peter-evans/find-comment) from 2.2.0 to 2.3.0.
- [Release notes](https://github.com/peter-evans/find-comment/releases)
- [Commits](https://github.com/peter-evans/find-comment/compare/81e2da3af01c92f83cb927cf3ace0e085617c556...034abe94d3191f9c89d870519735beae326f2bdb)

---
updated-dependencies:
- dependency-name: peter-evans/find-comment
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/diff_shades_comment.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/diff_shades_comment.yml b/.github/workflows/diff_shades_comment.yml
index 26d06090919..af683cbb0ac 100644
--- a/.github/workflows/diff_shades_comment.yml
+++ b/.github/workflows/diff_shades_comment.yml
@@ -33,7 +33,7 @@ jobs:
       - name: Try to find pre-existing PR comment
         if: steps.metadata.outputs.needs-comment == 'true'
         id: find-comment
-        uses: peter-evans/find-comment@81e2da3af01c92f83cb927cf3ace0e085617c556
+        uses: peter-evans/find-comment@034abe94d3191f9c89d870519735beae326f2bdb
         with:
           issue-number: ${{ steps.metadata.outputs.pr-number }}
           comment-author: "github-actions[bot]"

From 4a063a9f8d7069ea82186ac9aff5a2cd1c2618d7 Mon Sep 17 00:00:00 2001
From: Aneesh Agrawal <aneeshusa@gmail.com>
Date: Tue, 7 Mar 2023 14:52:19 -0500
Subject: [PATCH 0722/1034] Improve multiline string handling (#1879)

Co-authored-by: Olivia Hong <ohong@lyft.com>
Co-authored-by: Olivia Hong <24500729+olivia-hong@users.noreply.github.com>
---
 CHANGES.md                                |   1 +
 docs/the_black_code_style/future_style.md |  48 +++
 src/black/linegen.py                      |  43 ++-
 src/black/lines.py                        |  96 +++++-
 src/black/mode.py                         |   1 +
 tests/data/preview/multiline_strings.py   | 358 ++++++++++++++++++++++
 6 files changed, 514 insertions(+), 33 deletions(-)
 create mode 100644 tests/data/preview/multiline_strings.py

diff --git a/CHANGES.md b/CHANGES.md
index a8b556cb7e8..53682df2b39 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -133,6 +133,7 @@ versions separately.
   code. Implicitly concatenated f-strings with different quotes can now be merged or
   quote-normalized by changing the quotes used in expressions. (#3509)
 - Fix crash on `await (yield)` when Black is compiled with mypyc (#3533)
+- Improve handling of multiline strings by changing line split behavior (#1879)
 
 ### Configuration
 
diff --git a/docs/the_black_code_style/future_style.md b/docs/the_black_code_style/future_style.md
index b2cdca2590d..96abc99ef41 100644
--- a/docs/the_black_code_style/future_style.md
+++ b/docs/the_black_code_style/future_style.md
@@ -111,3 +111,51 @@ my_dict = {
     "another key": short_value,
 }
 ```
+
+### Improved multiline string handling
+
+_Black_ is smarter when formatting multiline strings, especially in function arguments,
+to avoid introducing extra line breaks. Previously, it would always consider multiline
+strings as not fitting on a single line. With this new feature, _Black_ looks at the
+context around the multiline string to decide if it should be inlined or split to a
+separate line. For example, when a multiline string is passed to a function, _Black_
+will only split the multiline string if a line is too long or if multiple arguments are
+being passed.
+
+For example, _Black_ will reformat
+
+```python
+textwrap.dedent(
+    """\
+    This is a
+    multiline string
+"""
+)
+```
+
+to:
+
+```python
+textwrap.dedent("""\
+    This is a
+    multiline string
+""")
+```
+
+And:
+
+```python
+MULTILINE = """
+foobar
+""".replace(
+    "\n", ""
+)
+```
+
+to:
+
+```python
+MULTILINE = """
+foobar
+""".replace("\n", "")
+```
diff --git a/src/black/linegen.py b/src/black/linegen.py
index f7d3655e962..95d5583c5f5 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -2,7 +2,7 @@
 Generating lines of code.
 """
 import sys
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 from enum import Enum, auto
 from functools import partial, wraps
 from typing import Collection, Iterator, List, Optional, Set, Union, cast
@@ -505,7 +505,7 @@ def transform_line(
         and not line.should_split_rhs
         and not line.magic_trailing_comma
         and (
-            is_line_short_enough(line, line_length=mode.line_length, line_str=line_str)
+            is_line_short_enough(line, mode=mode, line_str=line_str)
             or line.contains_unsplittable_type_ignore()
         )
         and not (line.inside_brackets and line.contains_standalone_comments())
@@ -529,14 +529,12 @@ def _rhs(
             bracket pair instead.
             """
             for omit in generate_trailers_to_omit(line, mode.line_length):
-                lines = list(
-                    right_hand_split(line, mode.line_length, features, omit=omit)
-                )
+                lines = list(right_hand_split(line, mode, features, omit=omit))
                 # Note: this check is only able to figure out if the first line of the
                 # *current* transformation fits in the line length.  This is true only
                 # for simple cases.  All others require running more transforms via
                 # `transform_line()`.  This check doesn't know if those would succeed.
-                if is_line_short_enough(lines[0], line_length=mode.line_length):
+                if is_line_short_enough(lines[0], mode=mode):
                     yield from lines
                     return
 
@@ -544,9 +542,7 @@ def _rhs(
             # This mostly happens to multiline strings that are by definition
             # reported as not fitting a single line, as well as lines that contain
             # trailing commas (those have to be exploded).
-            yield from right_hand_split(
-                line, line_length=mode.line_length, features=features
-            )
+            yield from right_hand_split(line, mode, features=features)
 
         # HACK: nested functions (like _rhs) compiled by mypyc don't retain their
         # __name__ attribute which is needed in `run_transformer` further down.
@@ -664,7 +660,7 @@ class _RHSResult:
 
 def right_hand_split(
     line: Line,
-    line_length: int,
+    mode: Mode,
     features: Collection[Feature] = (),
     omit: Collection[LeafID] = (),
 ) -> Iterator[Line]:
@@ -678,7 +674,7 @@ def right_hand_split(
     """
     rhs_result = _first_right_hand_split(line, omit=omit)
     yield from _maybe_split_omitting_optional_parens(
-        rhs_result, line, line_length, features=features, omit=omit
+        rhs_result, line, mode, features=features, omit=omit
     )
 
 
@@ -733,7 +729,7 @@ def _first_right_hand_split(
 def _maybe_split_omitting_optional_parens(
     rhs: _RHSResult,
     line: Line,
-    line_length: int,
+    mode: Mode,
     features: Collection[Feature] = (),
     omit: Collection[LeafID] = (),
 ) -> Iterator[Line]:
@@ -751,7 +747,7 @@ def _maybe_split_omitting_optional_parens(
         # there are no standalone comments in the body
         and not rhs.body.contains_standalone_comments(0)
         # and we can actually remove the parens
-        and can_omit_invisible_parens(rhs.body, line_length)
+        and can_omit_invisible_parens(rhs.body, mode.line_length)
     ):
         omit = {id(rhs.closing_bracket), *omit}
         try:
@@ -766,23 +762,24 @@ def _maybe_split_omitting_optional_parens(
                 and any(leaf.type in BRACKETS for leaf in rhs.head.leaves[:-1])
                 # the left side of assignment is short enough (the -1 is for the ending
                 # optional paren)
-                and is_line_short_enough(rhs.head, line_length=line_length - 1)
+                and is_line_short_enough(
+                    rhs.head, mode=replace(mode, line_length=mode.line_length - 1)
+                )
                 # the left side of assignment won't explode further because of magic
                 # trailing comma
                 and rhs.head.magic_trailing_comma is None
                 # the split by omitting optional parens isn't preferred by some other
                 # reason
-                and not _prefer_split_rhs_oop(rhs_oop, line_length=line_length)
+                and not _prefer_split_rhs_oop(rhs_oop, mode)
             ):
                 yield from _maybe_split_omitting_optional_parens(
-                    rhs_oop, line, line_length, features=features, omit=omit
+                    rhs_oop, line, mode, features=features, omit=omit
                 )
                 return
 
         except CannotSplit as e:
             if not (
-                can_be_split(rhs.body)
-                or is_line_short_enough(rhs.body, line_length=line_length)
+                can_be_split(rhs.body) or is_line_short_enough(rhs.body, mode=mode)
             ):
                 raise CannotSplit(
                     "Splitting failed, body is still too long and can't be split."
@@ -806,7 +803,7 @@ def _maybe_split_omitting_optional_parens(
             yield result
 
 
-def _prefer_split_rhs_oop(rhs_oop: _RHSResult, line_length: int) -> bool:
+def _prefer_split_rhs_oop(rhs_oop: _RHSResult, mode: Mode) -> bool:
     """
     Returns whether we should prefer the result from a split omitting optional parens.
     """
@@ -826,7 +823,7 @@ def _prefer_split_rhs_oop(rhs_oop: _RHSResult, line_length: int) -> bool:
             # the first line still contains the `=`)
             any(leaf.type == token.EQUAL for leaf in rhs_oop.head.leaves)
             # the first line is short enough
-            and is_line_short_enough(rhs_oop.head, line_length=line_length)
+            and is_line_short_enough(rhs_oop.head, mode=mode)
         )
         # contains unsplittable type ignore
         or rhs_oop.head.contains_unsplittable_type_ignore()
@@ -1525,7 +1522,7 @@ def run_transformer(
         or line.contains_multiline_strings()
         or result[0].contains_uncollapsable_type_comments()
         or result[0].contains_unsplittable_type_ignore()
-        or is_line_short_enough(result[0], line_length=mode.line_length)
+        or is_line_short_enough(result[0], mode=mode)
         # If any leaves have no parents (which _can_ occur since
         # `transform(line)` potentially destroys the line's underlying node
         # structure), then we can't proceed. Doing so would cause the below
@@ -1540,8 +1537,6 @@ def run_transformer(
     second_opinion = run_transformer(
         line_copy, transform, mode, features_fop, line_str=line_str
     )
-    if all(
-        is_line_short_enough(ln, line_length=mode.line_length) for ln in second_opinion
-    ):
+    if all(is_line_short_enough(ln, mode=mode) for ln in second_opinion):
         result = second_opinion
     return result
diff --git a/src/black/lines.py b/src/black/lines.py
index ec6ef5d9522..b65604864a4 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -1,4 +1,5 @@
 import itertools
+import math
 import sys
 from dataclasses import dataclass, field
 from typing import (
@@ -10,11 +11,12 @@
     Sequence,
     Tuple,
     TypeVar,
+    Union,
     cast,
 )
 
 from black.brackets import DOT_PRIORITY, BracketTracker
-from black.mode import Mode
+from black.mode import Mode, Preview
 from black.nodes import (
     BRACKETS,
     CLOSING_BRACKETS,
@@ -37,6 +39,7 @@
 T = TypeVar("T")
 Index = int
 LeafID = int
+LN = Union[Leaf, Node]
 
 
 @dataclass
@@ -701,18 +704,93 @@ def append_leaves(
             new_line.append(comment_leaf, preformatted=True)
 
 
-def is_line_short_enough(line: Line, *, line_length: int, line_str: str = "") -> bool:
-    """Return True if `line` is no longer than `line_length`.
-
+def is_line_short_enough(  # noqa: C901
+    line: Line, *, mode: Mode, line_str: str = ""
+) -> bool:
+    """For non-multiline strings, return True if `line` is no longer than `line_length`.
+    For multiline strings, looks at the context around `line` to determine
+    if it should be inlined or split up.
     Uses the provided `line_str` rendering, if any, otherwise computes a new one.
     """
     if not line_str:
         line_str = line_to_string(line)
-    return (
-        len(line_str) <= line_length
-        and "\n" not in line_str  # multiline strings
-        and not line.contains_standalone_comments()
-    )
+
+    if Preview.multiline_string_handling not in mode:
+        return (
+            len(line_str) <= mode.line_length
+            and "\n" not in line_str  # multiline strings
+            and not line.contains_standalone_comments()
+        )
+
+    if line.contains_standalone_comments():
+        return False
+    if "\n" not in line_str:
+        # No multiline strings (MLS) present
+        return len(line_str) <= mode.line_length
+
+    first, *_, last = line_str.split("\n")
+    if len(first) > mode.line_length or len(last) > mode.line_length:
+        return False
+
+    # Traverse the AST to examine the context of the multiline string (MLS),
+    # tracking aspects such as depth and comma existence,
+    # to determine whether to split the MLS or keep it together.
+    # Depth (which is based on the existing bracket_depth concept)
+    # is needed to determine nesting level of the MLS.
+    # Includes special case for trailing commas.
+    commas: List[int] = []  # tracks number of commas per depth level
+    multiline_string: Optional[Leaf] = None
+    # store the leaves that contain parts of the MLS
+    multiline_string_contexts: List[LN] = []
+
+    max_level_to_update = math.inf  # track the depth of the MLS
+    for i, leaf in enumerate(line.leaves):
+        if max_level_to_update == math.inf:
+            had_comma: Optional[int] = None
+            if leaf.bracket_depth + 1 > len(commas):
+                commas.append(0)
+            elif leaf.bracket_depth + 1 < len(commas):
+                had_comma = commas.pop()
+            if (
+                had_comma is not None
+                and multiline_string is not None
+                and multiline_string.bracket_depth == leaf.bracket_depth + 1
+            ):
+                # Have left the level with the MLS, stop tracking commas
+                max_level_to_update = leaf.bracket_depth
+                if had_comma > 0:
+                    # MLS was in parens with at least one comma - force split
+                    return False
+
+        if leaf.bracket_depth <= max_level_to_update and leaf.type == token.COMMA:
+            # Ignore non-nested trailing comma
+            # directly after MLS/MLS-containing expression
+            ignore_ctxs: List[Optional[LN]] = [None]
+            ignore_ctxs += multiline_string_contexts
+            if not (leaf.prev_sibling in ignore_ctxs and i == len(line.leaves) - 1):
+                commas[leaf.bracket_depth] += 1
+        if max_level_to_update != math.inf:
+            max_level_to_update = min(max_level_to_update, leaf.bracket_depth)
+
+        if is_multiline_string(leaf):
+            if len(multiline_string_contexts) > 0:
+                # >1 multiline string cannot fit on a single line - force split
+                return False
+            multiline_string = leaf
+            ctx: LN = leaf
+            # fetch the leaf components of the MLS in the AST
+            while str(ctx) in line_str:
+                multiline_string_contexts.append(ctx)
+                if ctx.parent is None:
+                    break
+                ctx = ctx.parent
+
+    # May not have a triple-quoted multiline string at all,
+    # in case of a regular string with embedded newlines and line continuations
+    if len(multiline_string_contexts) == 0:
+        return True
+
+    return all(val == 0 for val in commas)
 
 
 def can_be_split(line: Line) -> bool:
diff --git a/src/black/mode.py b/src/black/mode.py
index c9a4c2b080c..d70388916da 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -155,6 +155,7 @@ class Preview(Enum):
 
     add_trailing_comma_consistently = auto()
     hex_codes_in_unicode_sequences = auto()
+    multiline_string_handling = auto()
     prefer_splitting_right_hand_side_of_assignments = auto()
     # NOTE: string_processing requires wrap_long_dict_values_in_parens
     # for https://github.com/psf/black/issues/3117 to be fixed.
diff --git a/tests/data/preview/multiline_strings.py b/tests/data/preview/multiline_strings.py
new file mode 100644
index 00000000000..bb517d128e2
--- /dev/null
+++ b/tests/data/preview/multiline_strings.py
@@ -0,0 +1,358 @@
+"""cow
+say""",
+call(3, "dogsay", textwrap.dedent("""dove
+    coo""" % "cowabunga"))
+call(3, "dogsay", textwrap.dedent("""dove
+coo""" % "cowabunga"))
+call(3, textwrap.dedent("""cow
+    moo""" % "cowabunga"), "dogsay")
+call(3, "dogsay", textwrap.dedent("""crow
+    caw""" % "cowabunga"),)
+call(3, textwrap.dedent("""cat
+    meow""" % "cowabunga"), {"dog", "say"})
+call(3, {"dog", "say"}, textwrap.dedent("""horse
+    neigh""" % "cowabunga"))
+call(3, {"dog", "say"}, textwrap.dedent("""pig
+    oink""" % "cowabunga"),)
+textwrap.dedent("""A one-line triple-quoted string.""")
+textwrap.dedent("""A two-line triple-quoted string
+since it goes to the next line.""")
+textwrap.dedent("""A three-line triple-quoted string
+that not only goes to the next line
+but also goes one line beyond.""")
+textwrap.dedent("""\
+    A triple-quoted string
+    actually leveraging the textwrap.dedent functionality
+    that ends in a trailing newline,
+    representing e.g. file contents.
+""")
+path.write_text(textwrap.dedent("""\
+    A triple-quoted string
+    actually leveraging the textwrap.dedent functionality
+    that ends in a trailing newline,
+    representing e.g. file contents.
+"""))
+path.write_text(textwrap.dedent("""\
+    A triple-quoted string
+    actually leveraging the textwrap.dedent functionality
+    that ends in a trailing newline,
+    representing e.g. {config_filename} file contents.
+""".format("config_filename", config_filename)))
+# Another use case
+data = yaml.load("""\
+a: 1
+b: 2
+""")
+data = yaml.load("""\
+a: 1
+b: 2
+""",)
+data = yaml.load(
+    """\
+    a: 1
+    b: 2
+"""
+)
+
+MULTILINE = """
+foo
+""".replace("\n", "")
+generated_readme = lambda project_name: """
+{}
+
+<Add content here!>
+""".strip().format(project_name)
+parser.usage += """
+Custom extra help summary.
+
+Extra test:
+- with
+- bullets
+"""
+
+
+def get_stuff(cr, value):
+    # original
+    cr.execute("""
+        SELECT whatever
+          FROM some_table t
+         WHERE id = %s
+    """, [value])
+    return cr.fetchone()
+
+
+def get_stuff(cr, value):
+    # preferred
+    cr.execute(
+        """
+        SELECT whatever
+          FROM some_table t
+         WHERE id = %s
+        """,
+        [value],
+    )
+    return cr.fetchone()
+
+
+call(arg1, arg2, """
+short
+""", arg3=True)
+test_vectors = [
+    "one-liner\n",
+    "two\nliner\n",
+    """expressed
+as a three line
+mulitline string""",
+]
+
+_wat = re.compile(
+    r"""
+    regex
+    """,
+    re.MULTILINE | re.VERBOSE,
+)
+dis_c_instance_method = """\
+%3d           0 LOAD_FAST                1 (x)
+              2 LOAD_CONST               1 (1)
+              4 COMPARE_OP               2 (==)
+              6 LOAD_FAST                0 (self)
+              8 STORE_ATTR               0 (x)
+             10 LOAD_CONST               0 (None)
+             12 RETURN_VALUE
+""" % (_C.__init__.__code__.co_firstlineno + 1,)
+path.write_text(textwrap.dedent("""\
+    A triple-quoted string
+    actually {verb} the textwrap.dedent functionality
+    that ends in a trailing newline,
+    representing e.g. {file_type} file contents.
+""".format(verb="using", file_type="test")))
+{"""cow
+moos"""}
+["""cow
+moos"""]
+["""cow
+moos""", """dog
+woofs
+and
+barks"""]
+def dastardly_default_value(
+    cow: String = json.loads("""this
+is
+quite
+the
+dastadardly
+value!"""),
+    **kwargs,
+):
+    pass
+
+print(f"""
+    This {animal}
+    moos and barks
+{animal} say
+""")
+msg = f"""The arguments {bad_arguments} were passed in.
+Please use `--build-option` instead,
+`--global-option` is reserved to flags like `--verbose` or `--quiet`.
+"""
+
+# output
+"""cow
+say""",
+call(
+    3,
+    "dogsay",
+    textwrap.dedent("""dove
+    coo""" % "cowabunga"),
+)
+call(
+    3,
+    "dogsay",
+    textwrap.dedent("""dove
+coo""" % "cowabunga"),
+)
+call(
+    3,
+    textwrap.dedent("""cow
+    moo""" % "cowabunga"),
+    "dogsay",
+)
+call(
+    3,
+    "dogsay",
+    textwrap.dedent("""crow
+    caw""" % "cowabunga"),
+)
+call(
+    3,
+    textwrap.dedent("""cat
+    meow""" % "cowabunga"),
+    {"dog", "say"},
+)
+call(
+    3,
+    {"dog", "say"},
+    textwrap.dedent("""horse
+    neigh""" % "cowabunga"),
+)
+call(
+    3,
+    {"dog", "say"},
+    textwrap.dedent("""pig
+    oink""" % "cowabunga"),
+)
+textwrap.dedent("""A one-line triple-quoted string.""")
+textwrap.dedent("""A two-line triple-quoted string
+since it goes to the next line.""")
+textwrap.dedent("""A three-line triple-quoted string
+that not only goes to the next line
+but also goes one line beyond.""")
+textwrap.dedent("""\
+    A triple-quoted string
+    actually leveraging the textwrap.dedent functionality
+    that ends in a trailing newline,
+    representing e.g. file contents.
+""")
+path.write_text(textwrap.dedent("""\
+    A triple-quoted string
+    actually leveraging the textwrap.dedent functionality
+    that ends in a trailing newline,
+    representing e.g. file contents.
+"""))
+path.write_text(textwrap.dedent("""\
+    A triple-quoted string
+    actually leveraging the textwrap.dedent functionality
+    that ends in a trailing newline,
+    representing e.g. {config_filename} file contents.
+""".format("config_filename", config_filename)))
+# Another use case
+data = yaml.load("""\
+a: 1
+b: 2
+""")
+data = yaml.load(
+    """\
+a: 1
+b: 2
+""",
+)
+data = yaml.load("""\
+    a: 1
+    b: 2
+""")
+
+MULTILINE = """
+foo
+""".replace("\n", "")
+generated_readme = lambda project_name: """
+{}
+
+<Add content here!>
+""".strip().format(project_name)
+parser.usage += """
+Custom extra help summary.
+
+Extra test:
+- with
+- bullets
+"""
+
+
+def get_stuff(cr, value):
+    # original
+    cr.execute(
+        """
+        SELECT whatever
+          FROM some_table t
+         WHERE id = %s
+    """,
+        [value],
+    )
+    return cr.fetchone()
+
+
+def get_stuff(cr, value):
+    # preferred
+    cr.execute(
+        """
+        SELECT whatever
+          FROM some_table t
+         WHERE id = %s
+        """,
+        [value],
+    )
+    return cr.fetchone()
+
+
+call(
+    arg1,
+    arg2,
+    """
+short
+""",
+    arg3=True,
+)
+test_vectors = [
+    "one-liner\n",
+    "two\nliner\n",
+    """expressed
+as a three line
+mulitline string""",
+]
+
+_wat = re.compile(
+    r"""
+    regex
+    """,
+    re.MULTILINE | re.VERBOSE,
+)
+dis_c_instance_method = """\
+%3d           0 LOAD_FAST                1 (x)
+              2 LOAD_CONST               1 (1)
+              4 COMPARE_OP               2 (==)
+              6 LOAD_FAST                0 (self)
+              8 STORE_ATTR               0 (x)
+             10 LOAD_CONST               0 (None)
+             12 RETURN_VALUE
+""" % (_C.__init__.__code__.co_firstlineno + 1,)
+path.write_text(textwrap.dedent("""\
+    A triple-quoted string
+    actually {verb} the textwrap.dedent functionality
+    that ends in a trailing newline,
+    representing e.g. {file_type} file contents.
+""".format(verb="using", file_type="test")))
+{"""cow
+moos"""}
+["""cow
+moos"""]
+[
+    """cow
+moos""",
+    """dog
+woofs
+and
+barks""",
+]
+
+
+def dastardly_default_value(
+    cow: String = json.loads("""this
+is
+quite
+the
+dastadardly
+value!"""),
+    **kwargs,
+):
+    pass
+
+
+print(f"""
+    This {animal}
+    moos and barks
+{animal} say
+""")
+msg = f"""The arguments {bad_arguments} were passed in.
+Please use `--build-option` instead,
+`--global-option` is reserved to flags like `--verbose` or `--quiet`.
+"""

From d16a1dbd05832632d7f3be28f0a4b6e9b208807c Mon Sep 17 00:00:00 2001
From: "Yilei \"Dolee\" Yang" <yileiyang@google.com>
Date: Thu, 9 Mar 2023 22:01:20 -0800
Subject: [PATCH 0723/1034] Consistently wrap two context managers in parens
 (in --preview). (#3589)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 CHANGES.md                                    |  2 +
 src/black/linegen.py                          | 26 ++++--------
 src/black/lines.py                            | 42 +++++++++++++++++--
 src/black/nodes.py                            | 10 +++++
 .../auto_detect/features_3_8.py               | 16 +++++++
 .../targeting_py38.py                         | 16 +++++++
 .../targeting_py39.py                         | 37 ++++++++++++++++
 7 files changed, 127 insertions(+), 22 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 53682df2b39..2fa0cb41b38 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -16,6 +16,8 @@
 
 - Add trailing commas to collection literals even if there's a comment after the last
   entry (#3393)
+- `with` statements that contain two context managers will be consistently wrapped in
+  parentheses (#3589)
 
 ### Configuration
 
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 95d5583c5f5..6f67799e717 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -2,7 +2,7 @@
 Generating lines of code.
 """
 import sys
-from dataclasses import dataclass, replace
+from dataclasses import replace
 from enum import Enum, auto
 from functools import partial, wraps
 from typing import Collection, Iterator, List, Optional, Set, Union, cast
@@ -16,6 +16,7 @@
 from black.comments import FMT_OFF, generate_comments, list_comments
 from black.lines import (
     Line,
+    RHSResult,
     append_leaves,
     can_be_split,
     can_omit_invisible_parens,
@@ -647,17 +648,6 @@ def left_hand_split(
             yield result
 
 
-@dataclass
-class _RHSResult:
-    """Intermediate split result from a right hand split."""
-
-    head: Line
-    body: Line
-    tail: Line
-    opening_bracket: Leaf
-    closing_bracket: Leaf
-
-
 def right_hand_split(
     line: Line,
     mode: Mode,
@@ -681,7 +671,7 @@ def right_hand_split(
 def _first_right_hand_split(
     line: Line,
     omit: Collection[LeafID] = (),
-) -> _RHSResult:
+) -> RHSResult:
     """Split the line into head, body, tail starting with the last bracket pair.
 
     Note: this function should not have side effects. It's relied upon by
@@ -723,11 +713,11 @@ def _first_right_hand_split(
         tail_leaves, line, opening_bracket, component=_BracketSplitComponent.tail
     )
     bracket_split_succeeded_or_raise(head, body, tail)
-    return _RHSResult(head, body, tail, opening_bracket, closing_bracket)
+    return RHSResult(head, body, tail, opening_bracket, closing_bracket)
 
 
 def _maybe_split_omitting_optional_parens(
-    rhs: _RHSResult,
+    rhs: RHSResult,
     line: Line,
     mode: Mode,
     features: Collection[Feature] = (),
@@ -747,11 +737,11 @@ def _maybe_split_omitting_optional_parens(
         # there are no standalone comments in the body
         and not rhs.body.contains_standalone_comments(0)
         # and we can actually remove the parens
-        and can_omit_invisible_parens(rhs.body, mode.line_length)
+        and can_omit_invisible_parens(rhs, mode.line_length)
     ):
         omit = {id(rhs.closing_bracket), *omit}
         try:
-            # The _RHSResult Omitting Optional Parens.
+            # The RHSResult Omitting Optional Parens.
             rhs_oop = _first_right_hand_split(line, omit=omit)
             if not (
                 Preview.prefer_splitting_right_hand_side_of_assignments in line.mode
@@ -803,7 +793,7 @@ def _maybe_split_omitting_optional_parens(
             yield result
 
 
-def _prefer_split_rhs_oop(rhs_oop: _RHSResult, mode: Mode) -> bool:
+def _prefer_split_rhs_oop(rhs_oop: RHSResult, mode: Mode) -> bool:
     """
     Returns whether we should prefer the result from a split omitting optional parens.
     """
diff --git a/src/black/lines.py b/src/black/lines.py
index b65604864a4..4b57d1f0ea8 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -15,7 +15,7 @@
     cast,
 )
 
-from black.brackets import DOT_PRIORITY, BracketTracker
+from black.brackets import COMMA_PRIORITY, DOT_PRIORITY, BracketTracker
 from black.mode import Mode, Preview
 from black.nodes import (
     BRACKETS,
@@ -28,6 +28,7 @@
     is_multiline_string,
     is_one_sequence_between,
     is_type_comment,
+    is_with_stmt,
     replace_child,
     syms,
     whitespace,
@@ -122,6 +123,11 @@ def is_import(self) -> bool:
         """Is this an import line?"""
         return bool(self) and is_import(self.leaves[0])
 
+    @property
+    def is_with_stmt(self) -> bool:
+        """Is this a with_stmt line?"""
+        return bool(self) and is_with_stmt(self.leaves[0])
+
     @property
     def is_class(self) -> bool:
         """Is this line a class definition?"""
@@ -449,6 +455,17 @@ def __bool__(self) -> bool:
         return bool(self.leaves or self.comments)
 
 
+@dataclass
+class RHSResult:
+    """Intermediate split result from a right hand split."""
+
+    head: Line
+    body: Line
+    tail: Line
+    opening_bracket: Leaf
+    closing_bracket: Leaf
+
+
 @dataclass
 class LinesBlock:
     """Class that holds information about a block of formatted lines.
@@ -830,25 +847,42 @@ def can_be_split(line: Line) -> bool:
 
 
 def can_omit_invisible_parens(
-    line: Line,
+    rhs: RHSResult,
     line_length: int,
 ) -> bool:
-    """Does `line` have a shape safe to reformat without optional parens around it?
+    """Does `rhs.body` have a shape safe to reformat without optional parens around it?
 
     Returns True for only a subset of potentially nice looking formattings but
     the point is to not return false positives that end up producing lines that
     are too long.
     """
+    line = rhs.body
     bt = line.bracket_tracker
     if not bt.delimiters:
         # Without delimiters the optional parentheses are useless.
         return True
 
     max_priority = bt.max_delimiter_priority()
-    if bt.delimiter_count_with_priority(max_priority) > 1:
+    delimiter_count = bt.delimiter_count_with_priority(max_priority)
+    if delimiter_count > 1:
         # With more than one delimiter of a kind the optional parentheses read better.
         return False
 
+    if delimiter_count == 1:
+        if (
+            Preview.wrap_multiple_context_managers_in_parens in line.mode
+            and max_priority == COMMA_PRIORITY
+            and rhs.head.is_with_stmt
+        ):
+            # For two context manager with statements, the optional parentheses read
+            # better. In this case, `rhs.body` is the context managers part of
+            # the with statement. `rhs.head` is the `with (` part on the previous
+            # line.
+            return False
+        # Otherwise it may also read better, but we don't do it today and requires
+        # careful considerations for all possible cases. See
+        # https://github.com/psf/black/issues/2156.
+
     if max_priority == DOT_PRIORITY:
         # A single stranded method call doesn't require optional parentheses.
         return True
diff --git a/src/black/nodes.py b/src/black/nodes.py
index a588077f4de..90728f3c87c 100644
--- a/src/black/nodes.py
+++ b/src/black/nodes.py
@@ -789,6 +789,16 @@ def is_import(leaf: Leaf) -> bool:
     )
 
 
+def is_with_stmt(leaf: Leaf) -> bool:
+    """Return True if the given leaf starts a with statement."""
+    return bool(
+        leaf.type == token.NAME
+        and leaf.value == "with"
+        and leaf.parent
+        and leaf.parent.type == syms.with_stmt
+    )
+
+
 def is_type_comment(leaf: Leaf, suffix: str = "") -> bool:
     """Return True if the given leaf is a special comment.
     Only returns true for type comments for now."""
diff --git a/tests/data/preview_context_managers/auto_detect/features_3_8.py b/tests/data/preview_context_managers/auto_detect/features_3_8.py
index e05094e1421..79e438b995e 100644
--- a/tests/data/preview_context_managers/auto_detect/features_3_8.py
+++ b/tests/data/preview_context_managers/auto_detect/features_3_8.py
@@ -16,6 +16,14 @@
     pass
 
 
+with mock.patch.object(
+    self.my_runner, "first_method", autospec=True
+) as mock_run_adb, mock.patch.object(
+    self.my_runner, "second_method", autospec=True, return_value="foo"
+):
+    pass
+
+
 # output
 # This file doesn't use any Python 3.9+ only grammars.
 
@@ -28,3 +36,11 @@
 
 with make_context_manager1() as cm1, make_context_manager2() as cm2, make_context_manager3() as cm3, make_context_manager4() as cm4:
     pass
+
+
+with mock.patch.object(
+    self.my_runner, "first_method", autospec=True
+) as mock_run_adb, mock.patch.object(
+    self.my_runner, "second_method", autospec=True, return_value="foo"
+):
+    pass
diff --git a/tests/data/preview_context_managers/targeting_py38.py b/tests/data/preview_context_managers/targeting_py38.py
index 6ec4684e441..f125cdffb8a 100644
--- a/tests/data/preview_context_managers/targeting_py38.py
+++ b/tests/data/preview_context_managers/targeting_py38.py
@@ -23,6 +23,14 @@
     pass
 
 
+with mock.patch.object(
+    self.my_runner, "first_method", autospec=True
+) as mock_run_adb, mock.patch.object(
+    self.my_runner, "second_method", autospec=True, return_value="foo"
+):
+    pass
+
+
 # output
 
 
@@ -36,3 +44,11 @@
 
 with new_new_new1() as cm1, new_new_new2():
     pass
+
+
+with mock.patch.object(
+    self.my_runner, "first_method", autospec=True
+) as mock_run_adb, mock.patch.object(
+    self.my_runner, "second_method", autospec=True, return_value="foo"
+):
+    pass
diff --git a/tests/data/preview_context_managers/targeting_py39.py b/tests/data/preview_context_managers/targeting_py39.py
index 64f5d09bbe8..643c6fd958b 100644
--- a/tests/data/preview_context_managers/targeting_py39.py
+++ b/tests/data/preview_context_managers/targeting_py39.py
@@ -49,6 +49,24 @@
     pass
 
 
+with mock.patch.object(
+    self.my_runner, "first_method", autospec=True
+) as mock_run_adb, mock.patch.object(
+    self.my_runner, "second_method", autospec=True, return_value="foo"
+):
+    pass
+
+
+with xxxxxxxx.some_kind_of_method(
+    some_argument=[
+        "first",
+        "second",
+        "third",
+    ]
+).another_method() as cmd:
+    pass
+
+
 # output
 
 
@@ -102,3 +120,22 @@
     ) as cm2,
 ):
     pass
+
+
+with (
+    mock.patch.object(self.my_runner, "first_method", autospec=True) as mock_run_adb,
+    mock.patch.object(
+        self.my_runner, "second_method", autospec=True, return_value="foo"
+    ),
+):
+    pass
+
+
+with xxxxxxxx.some_kind_of_method(
+    some_argument=[
+        "first",
+        "second",
+        "third",
+    ]
+).another_method() as cmd:
+    pass

From 6ffc5f7b01eab341f1b2cd373b6faed0072a2351 Mon Sep 17 00:00:00 2001
From: Casey Korver <84342833+Casey-Kiewit@users.noreply.github.com>
Date: Sat, 11 Mar 2023 09:43:31 -0600
Subject: [PATCH 0724/1034] Correct spelling mistakes (#3599)

---
 autoload/black.vim                   |  2 +-
 docs/contributing/issue_triage.md    |  2 +-
 src/blib2to3/pgen2/driver.py         |  2 +-
 tests/data/preview/long_strings.py   | 12 ++++++------
 tests/data/simple_cases/comments4.py |  2 +-
 5 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/autoload/black.vim b/autoload/black.vim
index 5aec8725bd0..c682d51e2b0 100644
--- a/autoload/black.vim
+++ b/autoload/black.vim
@@ -9,7 +9,7 @@ def strtobool(text):
     return True
   if text.lower() in ['n', 'no', 'f', 'false', 'off', '0']:
     return False
-  raise ValueError(f"{text} is not convertable to boolean")
+  raise ValueError(f"{text} is not convertible to boolean")
 
 class Flag(collections.namedtuple("FlagBase", "name, cast")):
   @property
diff --git a/docs/contributing/issue_triage.md b/docs/contributing/issue_triage.md
index aa3e49a649b..89cfff76f7f 100644
--- a/docs/contributing/issue_triage.md
+++ b/docs/contributing/issue_triage.md
@@ -59,7 +59,7 @@ the details are different:
 1. _the issue is waiting for triage_
 2. **identified** - has been marked with a type label and other relevant labels
 3. **discussion** - the merits of the suggested changes are currently being discussed, a
-   PR would be acceptable but would be at sigificant risk of being rejected
+   PR would be acceptable but would be at significant risk of being rejected
 4. **accepted & awaiting PR** - it's been determined the suggested changes are OK and a
    PR would be welcomed (`S: accepted`)
 5. **closed**: - the issue has been resolved, reasons include:
diff --git a/src/blib2to3/pgen2/driver.py b/src/blib2to3/pgen2/driver.py
index daf271dfa9a..1741b33c510 100644
--- a/src/blib2to3/pgen2/driver.py
+++ b/src/blib2to3/pgen2/driver.py
@@ -107,7 +107,7 @@ def __next__(self) -> Any:
 
     def can_advance(self, to: int) -> bool:
         # Try to eat, fail if it can't. The eat operation is cached
-        # so there wont be any additional cost of eating here
+        # so there won't be any additional cost of eating here
         try:
             self.eat(to)
         except StopIteration:
diff --git a/tests/data/preview/long_strings.py b/tests/data/preview/long_strings.py
index b7a0a42f82a..c68da3a8632 100644
--- a/tests/data/preview/long_strings.py
+++ b/tests/data/preview/long_strings.py
@@ -26,15 +26,15 @@
     ("This is a really long string that can't be expected to fit in one line and is used as a dict's key"): ["value1", "value2"],
 }
 
-L1 = ["The is a short string", "This is a really long string that can't possibly be expected to fit all together on one line. Also it is inside a list literal, so it's expected to be wrapped in parens when spliting to avoid implicit str concatenation.", short_call("arg", {"key": "value"}), "This is another really really (not really) long string that also can't be expected to fit on one line and is, like the other string, inside a list literal.", ("parens should be stripped for short string in list")]
+L1 = ["The is a short string", "This is a really long string that can't possibly be expected to fit all together on one line. Also it is inside a list literal, so it's expected to be wrapped in parens when splitting to avoid implicit str concatenation.", short_call("arg", {"key": "value"}), "This is another really really (not really) long string that also can't be expected to fit on one line and is, like the other string, inside a list literal.", ("parens should be stripped for short string in list")]
 
 L2 = ["This is a really long string that can't be expected to fit in one line and is the only child of a list literal."]
 
-S1 = {"The is a short string", "This is a really long string that can't possibly be expected to fit all together on one line. Also it is inside a set literal, so it's expected to be wrapped in parens when spliting to avoid implicit str concatenation.", short_call("arg", {"key": "value"}), "This is another really really (not really) long string that also can't be expected to fit on one line and is, like the other string, inside a set literal.", ("parens should be stripped for short string in set")}
+S1 = {"The is a short string", "This is a really long string that can't possibly be expected to fit all together on one line. Also it is inside a set literal, so it's expected to be wrapped in parens when splitting to avoid implicit str concatenation.", short_call("arg", {"key": "value"}), "This is another really really (not really) long string that also can't be expected to fit on one line and is, like the other string, inside a set literal.", ("parens should be stripped for short string in set")}
 
 S2 = {"This is a really long string that can't be expected to fit in one line and is the only child of a set literal."}
 
-T1 = ("The is a short string", "This is a really long string that can't possibly be expected to fit all together on one line. Also it is inside a tuple literal, so it's expected to be wrapped in parens when spliting to avoid implicit str concatenation.", short_call("arg", {"key": "value"}), "This is another really really (not really) long string that also can't be expected to fit on one line and is, like the other string, inside a tuple literal.", ("parens should be stripped for short string in list"))
+T1 = ("The is a short string", "This is a really long string that can't possibly be expected to fit all together on one line. Also it is inside a tuple literal, so it's expected to be wrapped in parens when splitting to avoid implicit str concatenation.", short_call("arg", {"key": "value"}), "This is another really really (not really) long string that also can't be expected to fit on one line and is, like the other string, inside a tuple literal.", ("parens should be stripped for short string in list"))
 
 T2 = ("This is a really long string that can't be expected to fit in one line and is the only child of a tuple literal.",)
 
@@ -410,7 +410,7 @@ def foo():
     (
         "This is a really long string that can't possibly be expected to fit all"
         " together on one line. Also it is inside a list literal, so it's expected to"
-        " be wrapped in parens when spliting to avoid implicit str concatenation."
+        " be wrapped in parens when splitting to avoid implicit str concatenation."
     ),
     short_call("arg", {"key": "value"}),
     (
@@ -431,7 +431,7 @@ def foo():
     (
         "This is a really long string that can't possibly be expected to fit all"
         " together on one line. Also it is inside a set literal, so it's expected to be"
-        " wrapped in parens when spliting to avoid implicit str concatenation."
+        " wrapped in parens when splitting to avoid implicit str concatenation."
     ),
     short_call("arg", {"key": "value"}),
     (
@@ -452,7 +452,7 @@ def foo():
     (
         "This is a really long string that can't possibly be expected to fit all"
         " together on one line. Also it is inside a tuple literal, so it's expected to"
-        " be wrapped in parens when spliting to avoid implicit str concatenation."
+        " be wrapped in parens when splitting to avoid implicit str concatenation."
     ),
     short_call("arg", {"key": "value"}),
     (
diff --git a/tests/data/simple_cases/comments4.py b/tests/data/simple_cases/comments4.py
index 2147d41c9da..9f4f39d8359 100644
--- a/tests/data/simple_cases/comments4.py
+++ b/tests/data/simple_cases/comments4.py
@@ -85,7 +85,7 @@ def foo2(list_a, list_b):
 
 def foo3(list_a, list_b):
     return (
-        # Standlone comment but weirdly placed.
+        # Standalone comment but weirdly placed.
         User.query.filter(User.foo == "bar")
         .filter(
             db.or_(User.field_a.astext.in_(list_a), User.field_b.astext.in_(list_b))

From 71a2daaacf92d361c09bc7613023b285df83e7bb Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Wed, 15 Mar 2023 00:30:04 -0700
Subject: [PATCH 0725/1034] Bump pypa/cibuildwheel from 2.11.4 to 2.12.1
 (#3602)

Bumps [pypa/cibuildwheel](https://github.com/pypa/cibuildwheel) from 2.11.4 to 2.12.1.
- [Release notes](https://github.com/pypa/cibuildwheel/releases)
- [Changelog](https://github.com/pypa/cibuildwheel/blob/main/docs/changelog.md)
- [Commits](https://github.com/pypa/cibuildwheel/compare/v2.11.4...v2.12.1)

---
updated-dependencies:
- dependency-name: pypa/cibuildwheel
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/pypi_upload.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/pypi_upload.yml b/.github/workflows/pypi_upload.yml
index 6b3eb903d84..d5797c7d230 100644
--- a/.github/workflows/pypi_upload.yml
+++ b/.github/workflows/pypi_upload.yml
@@ -58,7 +58,7 @@ jobs:
       - uses: actions/checkout@v3
 
       - name: Build wheels via cibuildwheel
-        uses: pypa/cibuildwheel@v2.11.4
+        uses: pypa/cibuildwheel@v2.12.1
         env:
           CIBW_ARCHS_MACOS: "${{ matrix.macos_arch }}"
 

From fc6cea0f0e0f6da99fffbedbfcf3d50cc0e641a4 Mon Sep 17 00:00:00 2001
From: "Yilei \"Dolee\" Yang" <hi@mangoumbrella.com>
Date: Thu, 16 Mar 2023 13:31:27 -0700
Subject: [PATCH 0726/1034] Consistently format async statements similar to
 their non-async version. (#3609)

---
 CHANGES.md                                    |  2 ++
 src/black/linegen.py                          | 19 +++++++++--
 src/black/lines.py                            |  8 ++---
 src/black/mode.py                             |  1 +
 src/black/nodes.py                            | 21 ++++++++++--
 tests/data/preview/async_stmts.py             | 27 +++++++++++++++
 .../targeting_py39.py                         | 33 +++++++++++++++++++
 7 files changed, 103 insertions(+), 8 deletions(-)
 create mode 100644 tests/data/preview/async_stmts.py

diff --git a/CHANGES.md b/CHANGES.md
index 2fa0cb41b38..eff2640a01e 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -16,6 +16,8 @@
 
 - Add trailing commas to collection literals even if there's a comment after the last
   entry (#3393)
+- `async def`, `async for`, and `async with` statements are now formatted consistently
+  compared to their non-async version. (#3609)
 - `with` statements that contain two context managers will be consistently wrapped in
   parentheses (#3589)
 
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 6f67799e717..b6b83da26f7 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -36,6 +36,7 @@
     Visitor,
     ensure_visible,
     is_arith_like,
+    is_async_stmt_or_funcdef,
     is_atom_with_invisible_parens,
     is_docstring,
     is_empty_tuple,
@@ -110,6 +111,17 @@ def line(self, indent: int = 0) -> Iterator[Line]:
             self.current_line.depth += indent
             return  # Line is empty, don't emit. Creating a new one unnecessary.
 
+        if (
+            Preview.improved_async_statements_handling in self.mode
+            and len(self.current_line.leaves) == 1
+            and is_async_stmt_or_funcdef(self.current_line.leaves[0])
+        ):
+            # Special case for async def/for/with statements. `visit_async_stmt`
+            # adds an `ASYNC` leaf then visits the child def/for/with statement
+            # nodes. Line yields from those nodes shouldn't treat the former
+            # `ASYNC` leaf as a complete line.
+            return
+
         complete_line = self.current_line
         self.current_line = Line(mode=self.mode, depth=complete_line.depth + indent)
         yield complete_line
@@ -301,8 +313,11 @@ def visit_async_stmt(self, node: Node) -> Iterator[Line]:
                 break
 
         internal_stmt = next(children)
-        for child in internal_stmt.children:
-            yield from self.visit(child)
+        if Preview.improved_async_statements_handling in self.mode:
+            yield from self.visit(internal_stmt)
+        else:
+            for child in internal_stmt.children:
+                yield from self.visit(child)
 
     def visit_decorators(self, node: Node) -> Iterator[Line]:
         """Visit decorators."""
diff --git a/src/black/lines.py b/src/black/lines.py
index 4b57d1f0ea8..329dfc4f0d3 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -28,7 +28,7 @@
     is_multiline_string,
     is_one_sequence_between,
     is_type_comment,
-    is_with_stmt,
+    is_with_or_async_with_stmt,
     replace_child,
     syms,
     whitespace,
@@ -124,9 +124,9 @@ def is_import(self) -> bool:
         return bool(self) and is_import(self.leaves[0])
 
     @property
-    def is_with_stmt(self) -> bool:
+    def is_with_or_async_with_stmt(self) -> bool:
         """Is this a with_stmt line?"""
-        return bool(self) and is_with_stmt(self.leaves[0])
+        return bool(self) and is_with_or_async_with_stmt(self.leaves[0])
 
     @property
     def is_class(self) -> bool:
@@ -872,7 +872,7 @@ def can_omit_invisible_parens(
         if (
             Preview.wrap_multiple_context_managers_in_parens in line.mode
             and max_priority == COMMA_PRIORITY
-            and rhs.head.is_with_stmt
+            and rhs.head.is_with_or_async_with_stmt
         ):
             # For two context manager with statements, the optional parentheses read
             # better. In this case, `rhs.body` is the context managers part of
diff --git a/src/black/mode.py b/src/black/mode.py
index d70388916da..6af04179193 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -155,6 +155,7 @@ class Preview(Enum):
 
     add_trailing_comma_consistently = auto()
     hex_codes_in_unicode_sequences = auto()
+    improved_async_statements_handling = auto()
     multiline_string_handling = auto()
     prefer_splitting_right_hand_side_of_assignments = auto()
     # NOTE: string_processing requires wrap_long_dict_values_in_parens
diff --git a/src/black/nodes.py b/src/black/nodes.py
index 90728f3c87c..4e9411b1b79 100644
--- a/src/black/nodes.py
+++ b/src/black/nodes.py
@@ -789,13 +789,30 @@ def is_import(leaf: Leaf) -> bool:
     )
 
 
-def is_with_stmt(leaf: Leaf) -> bool:
-    """Return True if the given leaf starts a with statement."""
+def is_with_or_async_with_stmt(leaf: Leaf) -> bool:
+    """Return True if the given leaf starts a with or async with statement."""
     return bool(
         leaf.type == token.NAME
         and leaf.value == "with"
         and leaf.parent
         and leaf.parent.type == syms.with_stmt
+    ) or bool(
+        leaf.type == token.ASYNC
+        and leaf.next_sibling
+        and leaf.next_sibling.type == syms.with_stmt
+    )
+
+
+def is_async_stmt_or_funcdef(leaf: Leaf) -> bool:
+    """Return True if the given leaf starts an async def/for/with statement.
+
+    Note that `async def` can be either an `async_stmt` or `async_funcdef`,
+    the latter is used when it has decorators.
+    """
+    return bool(
+        leaf.type == token.ASYNC
+        and leaf.parent
+        and leaf.parent.type in {syms.async_stmt, syms.async_funcdef}
     )
 
 
diff --git a/tests/data/preview/async_stmts.py b/tests/data/preview/async_stmts.py
new file mode 100644
index 00000000000..fe9594b2164
--- /dev/null
+++ b/tests/data/preview/async_stmts.py
@@ -0,0 +1,27 @@
+async def func() -> (int):
+    return 0
+
+
+@decorated
+async def func() -> (int):
+    return 0
+
+
+async for (item) in async_iter:
+    pass
+
+
+# output
+
+
+async def func() -> int:
+    return 0
+
+
+@decorated
+async def func() -> int:
+    return 0
+
+
+async for item in async_iter:
+    pass
diff --git a/tests/data/preview_context_managers/targeting_py39.py b/tests/data/preview_context_managers/targeting_py39.py
index 643c6fd958b..c9fcf9c8ba2 100644
--- a/tests/data/preview_context_managers/targeting_py39.py
+++ b/tests/data/preview_context_managers/targeting_py39.py
@@ -67,6 +67,23 @@
     pass
 
 
+async def func():
+    async with \
+        make_context_manager1() as cm1, \
+        make_context_manager2() as cm2, \
+        make_context_manager3() as cm3, \
+        make_context_manager4() as cm4 \
+    :
+        pass
+
+    async with some_function(
+        argument1, argument2, argument3="some_value"
+    ) as some_cm, some_other_function(
+        argument1, argument2, argument3="some_value"
+    ):
+        pass
+
+
 # output
 
 
@@ -139,3 +156,19 @@
     ]
 ).another_method() as cmd:
     pass
+
+
+async def func():
+    async with (
+        make_context_manager1() as cm1,
+        make_context_manager2() as cm2,
+        make_context_manager3() as cm3,
+        make_context_manager4() as cm4,
+    ):
+        pass
+
+    async with (
+        some_function(argument1, argument2, argument3="some_value") as some_cm,
+        some_other_function(argument1, argument2, argument3="some_value"),
+    ):
+        pass

From 268dcb677ce80331e0ef104d8335c2ada32872fb Mon Sep 17 00:00:00 2001
From: "Yilei \"Dolee\" Yang" <yileiyang@google.com>
Date: Fri, 17 Mar 2023 21:39:21 -0700
Subject: [PATCH 0727/1034] Do not add an extra blank line to an import line
 that has fmt disabled (#3610)

---
 CHANGES.md                                 |  3 +++
 src/black/comments.py                      |  1 +
 src/black/lines.py                         | 21 +++++++++++++++++++++
 src/blib2to3/pytree.py                     |  6 ++++++
 tests/data/simple_cases/fmtonoff.py        |  1 -
 tests/data/simple_cases/fmtpass_imports.py | 19 +++++++++++++++++++
 6 files changed, 50 insertions(+), 1 deletion(-)
 create mode 100644 tests/data/simple_cases/fmtpass_imports.py

diff --git a/CHANGES.md b/CHANGES.md
index eff2640a01e..06a0ab7e9eb 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -10,6 +10,9 @@
 
 <!-- Changes that affect Black's stable style -->
 
+- Import lines with `# fmt: skip` and `# fmt: off` no longer have an extra blank line
+  added when they are right after another import line (#3610)
+
 ### Preview style
 
 <!-- Changes that affect Black's preview style -->
diff --git a/src/black/comments.py b/src/black/comments.py
index 7cf15bf67b3..619123ab4be 100644
--- a/src/black/comments.py
+++ b/src/black/comments.py
@@ -203,6 +203,7 @@ def convert_one_fmt_off_pair(node: Node) -> bool:
                     STANDALONE_COMMENT,
                     hidden_value,
                     prefix=standalone_comment_prefix,
+                    fmt_pass_converted_first_leaf=first_leaf_of(first),
                 ),
             )
             return True
diff --git a/src/black/lines.py b/src/black/lines.py
index 329dfc4f0d3..66bba14b357 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -195,6 +195,26 @@ def opens_block(self) -> bool:
             return False
         return self.leaves[-1].type == token.COLON
 
+    def is_fmt_pass_converted(
+        self, *, first_leaf_matches: Optional[Callable[[Leaf], bool]] = None
+    ) -> bool:
+        """Is this line converted from fmt off/skip code?
+
+        If first_leaf_matches is not None, it only returns True if the first
+        leaf of converted code matches.
+        """
+        if len(self.leaves) != 1:
+            return False
+        leaf = self.leaves[0]
+        if (
+            leaf.type != STANDALONE_COMMENT
+            or leaf.fmt_pass_converted_first_leaf is None
+        ):
+            return False
+        return first_leaf_matches is None or first_leaf_matches(
+            leaf.fmt_pass_converted_first_leaf
+        )
+
     def contains_standalone_comments(self, depth_limit: int = sys.maxsize) -> bool:
         """If so, needs to be split before emitting."""
         for leaf in self.leaves:
@@ -597,6 +617,7 @@ def _maybe_empty_lines(self, current_line: Line) -> Tuple[int, int]:
             self.previous_line
             and self.previous_line.is_import
             and not current_line.is_import
+            and not current_line.is_fmt_pass_converted(first_leaf_matches=is_import)
             and depth == self.previous_line.depth
         ):
             return (before or 1), 0
diff --git a/src/blib2to3/pytree.py b/src/blib2to3/pytree.py
index 15a1420ef7d..ea60c894e20 100644
--- a/src/blib2to3/pytree.py
+++ b/src/blib2to3/pytree.py
@@ -392,6 +392,10 @@ class Leaf(Base):
     _prefix = ""  # Whitespace and comments preceding this token in the input
     lineno: int = 0  # Line where this token starts in the input
     column: int = 0  # Column where this token starts in the input
+    # If not None, this Leaf is created by converting a block of fmt off/skip
+    # code, and `fmt_pass_converted_first_leaf` points to the first Leaf in the
+    # converted code.
+    fmt_pass_converted_first_leaf: Optional["Leaf"] = None
 
     def __init__(
         self,
@@ -401,6 +405,7 @@ def __init__(
         prefix: Optional[Text] = None,
         fixers_applied: List[Any] = [],
         opening_bracket: Optional["Leaf"] = None,
+        fmt_pass_converted_first_leaf: Optional["Leaf"] = None,
     ) -> None:
         """
         Initializer.
@@ -419,6 +424,7 @@ def __init__(
         self.fixers_applied: Optional[List[Any]] = fixers_applied[:]
         self.children = []
         self.opening_bracket = opening_bracket
+        self.fmt_pass_converted_first_leaf = fmt_pass_converted_first_leaf
 
     def __repr__(self) -> str:
         """Return a canonical string representation."""
diff --git a/tests/data/simple_cases/fmtonoff.py b/tests/data/simple_cases/fmtonoff.py
index e40ea2c8d21..d1f15cd5c8b 100644
--- a/tests/data/simple_cases/fmtonoff.py
+++ b/tests/data/simple_cases/fmtonoff.py
@@ -195,7 +195,6 @@ def single_literal_yapf_disable():
 from third_party import X, Y, Z
 
 from library import some_connection, some_decorator
-
 # fmt: off
 from third_party import (X,
                          Y, Z)
diff --git a/tests/data/simple_cases/fmtpass_imports.py b/tests/data/simple_cases/fmtpass_imports.py
new file mode 100644
index 00000000000..8b3c0bc662a
--- /dev/null
+++ b/tests/data/simple_cases/fmtpass_imports.py
@@ -0,0 +1,19 @@
+# Regression test for https://github.com/psf/black/issues/3438
+
+import ast
+import collections  # fmt: skip
+import dataclasses
+# fmt: off
+import os
+# fmt: on
+import pathlib
+
+import re  # fmt: skip
+import secrets
+
+# fmt: off
+import sys
+# fmt: on
+
+import tempfile
+import zoneinfo

From 34a93a8d49951828dacd4237feda5db1f6ec854b Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Fri, 17 Mar 2023 21:59:33 -0700
Subject: [PATCH 0728/1034] Bump peter-evans/create-or-update-comment from
 2.1.0 to 2.1.1 (#3548)

Bumps [peter-evans/create-or-update-comment](https://github.com/peter-evans/create-or-update-comment) from 2.1.0 to 2.1.1.
- [Release notes](https://github.com/peter-evans/create-or-update-comment/releases)
- [Commits](https://github.com/peter-evans/create-or-update-comment/compare/5adcb0bb0f9fb3f95ef05400558bdb3f329ee808...67dcc547d311b736a8e6c5c236542148a47adc3d)

---
updated-dependencies:
- dependency-name: peter-evans/create-or-update-comment
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/diff_shades_comment.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/diff_shades_comment.yml b/.github/workflows/diff_shades_comment.yml
index af683cbb0ac..bb81ca4f0d6 100644
--- a/.github/workflows/diff_shades_comment.yml
+++ b/.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@5adcb0bb0f9fb3f95ef05400558bdb3f329ee808
+        uses: peter-evans/create-or-update-comment@67dcc547d311b736a8e6c5c236542148a47adc3d
         with:
           comment-id: ${{ steps.find-comment.outputs.comment-id }}
           issue-number: ${{ steps.metadata.outputs.pr-number }}

From c9efbf9d97b65d67f6e87ee4b77bed0445bd7a9f Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Sat, 18 Mar 2023 10:41:48 -0700
Subject: [PATCH 0729/1034] Add SECURITY.md (#3612)

---
 CHANGES.md  |  3 +++
 SECURITY.md | 11 +++++++++++
 2 files changed, 14 insertions(+)
 create mode 100644 SECURITY.md

diff --git a/CHANGES.md b/CHANGES.md
index 06a0ab7e9eb..e2f21cf8f8a 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -57,6 +57,9 @@
 <!-- Major changes to documentation and policies. Small docs changes
      don't need a changelog entry. -->
 
+- Document that only the most recent release is supported for security issues;
+  vulnerabilities should be reported through Tidelift (#3612)
+
 ## 23.1.0
 
 ### Highlights
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 00000000000..47049501183
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,11 @@
+# Security Policy
+
+## Supported Versions
+
+Only the latest non-prerelease version is supported.
+
+## Security contact information
+
+To report a security vulnerability, please use the
+[Tidelift security contact](https://tidelift.com/security). Tidelift will coordinate the
+fix and disclosure.

From a3e8247a41089175827a69e5413278ffdc28aff2 Mon Sep 17 00:00:00 2001
From: Mitch Negus <21086604+mitchnegus@users.noreply.github.com>
Date: Sat, 18 Mar 2023 14:30:02 -0600
Subject: [PATCH 0730/1034] Update documentation regarding isort compatibility
 (#3567)

---
 docs/guides/using_black_with_other_tools.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/guides/using_black_with_other_tools.md b/docs/guides/using_black_with_other_tools.md
index 9356caaf0bd..6c6fbb88174 100644
--- a/docs/guides/using_black_with_other_tools.md
+++ b/docs/guides/using_black_with_other_tools.md
@@ -51,9 +51,9 @@ line_length = 88
 
 #### Why those options above?
 
-_Black_ wraps imports that surpass `line-length` by moving identifiers into their own
-indented line. If that still doesn't fit the bill, it will put all of them in separate
-lines and put a trailing comma. A more detailed explanation of this behaviour can be
+_Black_ wraps imports that surpass `line-length` by moving identifiers onto separate
+lines and by adding a trailing comma after each. A more detailed explanation of this
+behaviour can be
 [found here](../the_black_code_style/current_style.md#how-black-wraps-lines).
 
 isort's default mode of wrapping imports that extend past the `line_length` limit is

From d7a28dd78631fb962da95fb2d2de0e18ca6754a4 Mon Sep 17 00:00:00 2001
From: WMOkiishi <w.muneo.o@gmail.com>
Date: Sat, 18 Mar 2023 15:04:13 -0600
Subject: [PATCH 0731/1034] Enforce a blank line after a nested class in stubs
 (#3564)

---
 CHANGES.md                                     |  2 ++
 src/black/lines.py                             | 12 +++++++++---
 src/black/mode.py                              |  1 +
 tests/data/miscellaneous/nested_class_stub.pyi | 16 ++++++++++++++++
 tests/test_format.py                           |  6 ++++++
 5 files changed, 34 insertions(+), 3 deletions(-)
 create mode 100644 tests/data/miscellaneous/nested_class_stub.pyi

diff --git a/CHANGES.md b/CHANGES.md
index e2f21cf8f8a..029d0bcbd3f 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -23,6 +23,8 @@
   compared to their non-async version. (#3609)
 - `with` statements that contain two context managers will be consistently wrapped in
   parentheses (#3589)
+- For stubs, enforce one blank line after a nested class with a body other than just
+  `...` (#3564)
 
 ### Configuration
 
diff --git a/src/black/lines.py b/src/black/lines.py
index 66bba14b357..b2bdcc441b4 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -521,7 +521,7 @@ class EmptyLineTracker:
     mode: Mode
     previous_line: Optional[Line] = None
     previous_block: Optional[LinesBlock] = None
-    previous_defs: List[int] = field(default_factory=list)
+    previous_defs: List[Line] = field(default_factory=list)
     semantic_leading_comment: Optional[LinesBlock] = None
 
     def maybe_empty_lines(self, current_line: Line) -> LinesBlock:
@@ -577,12 +577,18 @@ def _maybe_empty_lines(self, current_line: Line) -> Tuple[int, int]:
         else:
             before = 0
         depth = current_line.depth
-        while self.previous_defs and self.previous_defs[-1] >= depth:
+        while self.previous_defs and self.previous_defs[-1].depth >= depth:
             if self.mode.is_pyi:
                 assert self.previous_line is not None
                 if depth and not current_line.is_def and self.previous_line.is_def:
                     # Empty lines between attributes and methods should be preserved.
                     before = min(1, before)
+                elif (
+                    Preview.blank_line_after_nested_stub_class in self.mode
+                    and self.previous_defs[-1].is_class
+                    and not self.previous_defs[-1].is_stub_class
+                ):
+                    before = 1
                 elif depth:
                     before = 0
                 else:
@@ -637,7 +643,7 @@ def _maybe_empty_lines_for_class_or_def(
         self, current_line: Line, before: int
     ) -> Tuple[int, int]:
         if not current_line.is_decorator:
-            self.previous_defs.append(current_line.depth)
+            self.previous_defs.append(current_line)
         if self.previous_line is None:
             # Don't insert empty lines before the first line in the file.
             return 0, 0
diff --git a/src/black/mode.py b/src/black/mode.py
index 6af04179193..0511676ce53 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -154,6 +154,7 @@ class Preview(Enum):
     """Individual preview style features."""
 
     add_trailing_comma_consistently = auto()
+    blank_line_after_nested_stub_class = auto()
     hex_codes_in_unicode_sequences = auto()
     improved_async_statements_handling = auto()
     multiline_string_handling = auto()
diff --git a/tests/data/miscellaneous/nested_class_stub.pyi b/tests/data/miscellaneous/nested_class_stub.pyi
new file mode 100644
index 00000000000..daf281b517b
--- /dev/null
+++ b/tests/data/miscellaneous/nested_class_stub.pyi
@@ -0,0 +1,16 @@
+class Outer:
+    class InnerStub: ...
+    outer_attr_after_inner_stub: int
+    class Inner:
+        inner_attr: int
+    outer_attr: int
+
+# output
+class Outer:
+    class InnerStub: ...
+    outer_attr_after_inner_stub: int
+
+    class Inner:
+        inner_attr: int
+
+    outer_attr: int
diff --git a/tests/test_format.py b/tests/test_format.py
index ab849aac9a3..3a6cbc9e2e9 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -186,6 +186,12 @@ def test_stub() -> None:
     assert_format(source, expected, mode)
 
 
+def test_nested_class_stub() -> None:
+    mode = replace(DEFAULT_MODE, is_pyi=True, preview=True)
+    source, expected = read_data("miscellaneous", "nested_class_stub.pyi")
+    assert_format(source, expected, mode)
+
+
 def test_power_op_newline() -> None:
     # requires line_length=0
     source, expected = read_data("miscellaneous", "power_op_newline")

From dba3c2695c59fdb11825dbdf8f3b0ab6e0b368b2 Mon Sep 17 00:00:00 2001
From: "Yilei \"Dolee\" Yang" <yileiyang@google.com>
Date: Sun, 19 Mar 2023 07:43:39 -0700
Subject: [PATCH 0732/1034] Fix bug introduced in #3564. (#3615)

---
 src/black/lines.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/black/lines.py b/src/black/lines.py
index b2bdcc441b4..fb5933ecbfb 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -598,7 +598,7 @@ def _maybe_empty_lines(self, current_line: Line) -> Tuple[int, int]:
                     before = 1
                 elif (
                     not depth
-                    and self.previous_defs[-1]
+                    and self.previous_defs[-1].depth
                     and current_line.leaves[-1].type == token.COLON
                     and (
                         current_line.leaves[0].value

From 53c23e62df9b182edf9e7ccf726acdcf8c25846f Mon Sep 17 00:00:00 2001
From: Tushar Sadhwani <tushar.sadhwani000@gmail.com>
Date: Mon, 20 Mar 2023 04:22:06 +0530
Subject: [PATCH 0733/1034] Support files with type comment syntax errors
 (#3594)

---
 CHANGES.md                                    |  2 ++
 src/black/parsing.py                          | 26 ++++++++++++++-----
 .../type_comment_syntax_error.py              | 11 ++++++++
 tests/test_format.py                          |  7 +++++
 4 files changed, 39 insertions(+), 7 deletions(-)
 create mode 100644 tests/data/type_comments/type_comment_syntax_error.py

diff --git a/CHANGES.md b/CHANGES.md
index 029d0bcbd3f..f5c039f6509 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -38,6 +38,8 @@
 
 <!-- Changes to the parser or to version autodetection -->
 
+- Added support for formatting files with invalid type comments (#3594)
+
 ### Performance
 
 <!-- Changes that improve Black's performance. -->
diff --git a/src/black/parsing.py b/src/black/parsing.py
index ba474c5e047..eaa3c367e54 100644
--- a/src/black/parsing.py
+++ b/src/black/parsing.py
@@ -148,24 +148,29 @@ def lib2to3_unparse(node: Node) -> str:
 
 
 def parse_single_version(
-    src: str, version: Tuple[int, int]
+    src: str, version: Tuple[int, int], *, type_comments: bool
 ) -> Union[ast.AST, ast3.AST]:
     filename = "<unknown>"
     # typed-ast is needed because of feature version limitations in the builtin ast 3.8>
     if sys.version_info >= (3, 8) and version >= (3,):
-        return ast.parse(src, filename, feature_version=version, type_comments=True)
+        return ast.parse(
+            src, filename, feature_version=version, type_comments=type_comments
+        )
 
     if _IS_PYPY:
         # PyPy 3.7 doesn't support type comment tracking which is not ideal, but there's
         # not much we can do as typed-ast won't work either.
         if sys.version_info >= (3, 8):
-            return ast3.parse(src, filename, type_comments=True)
+            return ast3.parse(src, filename, type_comments=type_comments)
         else:
             return ast3.parse(src, filename)
     else:
-        # Typed-ast is guaranteed to be used here and automatically tracks type
-        # comments separately.
-        return ast3.parse(src, filename, feature_version=version[1])
+        if type_comments:
+            # Typed-ast is guaranteed to be used here and automatically tracks type
+            # comments separately.
+            return ast3.parse(src, filename, feature_version=version[1])
+        else:
+            return ast.parse(src, filename)
 
 
 def parse_ast(src: str) -> Union[ast.AST, ast3.AST]:
@@ -175,11 +180,18 @@ def parse_ast(src: str) -> Union[ast.AST, ast3.AST]:
     first_error = ""
     for version in sorted(versions, reverse=True):
         try:
-            return parse_single_version(src, version)
+            return parse_single_version(src, version, type_comments=True)
         except SyntaxError as e:
             if not first_error:
                 first_error = str(e)
 
+    # Try to parse without type comments
+    for version in sorted(versions, reverse=True):
+        try:
+            return parse_single_version(src, version, type_comments=False)
+        except SyntaxError:
+            pass
+
     raise SyntaxError(first_error)
 
 
diff --git a/tests/data/type_comments/type_comment_syntax_error.py b/tests/data/type_comments/type_comment_syntax_error.py
new file mode 100644
index 00000000000..2e5ca2ede8c
--- /dev/null
+++ b/tests/data/type_comments/type_comment_syntax_error.py
@@ -0,0 +1,11 @@
+def foo(
+    # type: Foo
+    x): pass
+
+# output
+
+def foo(
+    # type: Foo
+    x,
+):
+    pass
diff --git a/tests/test_format.py b/tests/test_format.py
index 3a6cbc9e2e9..5a7b3bb6762 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -196,3 +196,10 @@ def test_power_op_newline() -> None:
     # requires line_length=0
     source, expected = read_data("miscellaneous", "power_op_newline")
     assert_format(source, expected, mode=black.Mode(line_length=0))
+
+
+def test_type_comment_syntax_error() -> None:
+    """Test that black is able to format python code with type comment syntax errors."""
+    source, expected = read_data("type_comments", "type_comment_syntax_error")
+    assert_format(source, expected)
+    black.assert_equivalent(source, expected)

From 3a9d6f0a5f9013b97676f3d24246bd34d93fce4c Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Sun, 19 Mar 2023 18:52:40 -0400
Subject: [PATCH 0734/1034] Bump myst-parser from 0.18.1 to 1.0.0 in /docs
 (#3601)

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Richard Si <sichard26@gmail.com>
---
 docs/faq.md                               | 4 ++--
 docs/requirements.txt                     | 2 +-
 docs/the_black_code_style/future_style.md | 2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/faq.md b/docs/faq.md
index bc9deccb756..a6a422c2fec 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -23,7 +23,7 @@ hooks, and scripting `unexpand` to run after applying _Black_.
 ## Does Black have an API?
 
 Not yet. _Black_ is fundamentally a command line tool. Many
-[integrations](integrations/index.rst) are provided, but a Python interface is not one
+[integrations](/integrations/index.md) are provided, but a Python interface is not one
 of them. A simple API is being [planned](https://github.com/psf/black/issues/779)
 though.
 
@@ -39,7 +39,7 @@ other tools, such as `# noqa`, may be moved by _Black_. See below for more detai
 ## How stable is Black's style?
 
 Stable. _Black_ aims to enforce one style and one style only, with some room for
-pragmatism. See [The Black Code Style](the_black_code_style/index.rst) for more details.
+pragmatism. See [The Black Code Style](the_black_code_style/index.md) for more details.
 
 Starting in 2022, the formatting output will be stable for the releases made in the same
 year (other than unintentional bugs). It is possible to opt-in to the latest formatting
diff --git a/docs/requirements.txt b/docs/requirements.txt
index 9a269d02a75..f683fd52355 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,6 +1,6 @@
 # Used by ReadTheDocs; pinned requirements for stability.
 
-myst-parser==0.18.1
+myst-parser==1.0.0
 Sphinx==5.3.0
 # Older versions break Sphinx even though they're declared to be supported.
 docutils==0.19
diff --git a/docs/the_black_code_style/future_style.md b/docs/the_black_code_style/future_style.md
index 96abc99ef41..f5fc3644f18 100644
--- a/docs/the_black_code_style/future_style.md
+++ b/docs/the_black_code_style/future_style.md
@@ -51,7 +51,7 @@ with contextlib.ExitStack() as exit_stack:
 
 Experimental, potentially disruptive style changes are gathered under the `--preview`
 CLI flag. At the end of each year, these changes may be adopted into the default style,
-as described in [The Black Code Style](./index.rst). Because the functionality is
+as described in [The Black Code Style](index.md). Because the functionality is
 experimental, feedback and issue reports are highly encouraged!
 
 ### Improved string processing

From 5c064a986c388e2be1e448c3e4b28e5f5ba7ce5a Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Sun, 19 Mar 2023 19:00:14 -0400
Subject: [PATCH 0735/1034] Bump sphinx from 5.3.0 to 6.1.3 in /docs (#3499)

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 docs/requirements.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index f683fd52355..2916b3cee6a 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,7 +1,7 @@
 # Used by ReadTheDocs; pinned requirements for stability.
 
 myst-parser==1.0.0
-Sphinx==5.3.0
+Sphinx==6.1.3
 # Older versions break Sphinx even though they're declared to be supported.
 docutils==0.19
 sphinxcontrib-programoutput==0.17

From ef6e079901d53a42dfae4ab10b081ce7a73a47b5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Hong=20Minhee=20=28=E6=B4=AA=20=E6=B0=91=E6=86=99=29?=
 <hong@minhee.org>
Date: Mon, 20 Mar 2023 08:09:57 +0900
Subject: [PATCH 0736/1034] Let string splitters respect `East_Asian_Width`
 property (#3445)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This patch changes the preview style so that string splitters respect
Unicode East Asian Width[^1] property.  If you are not familiar to CJK
languages it is not clear immediately.  Let me elaborate with some
examples.

Traditionally, East Asian characters (including punctuation) have
taken up space twice than European letters and stops when they are
rendered in monospace typeset.  Compare the following characters:

```
abcdefg.
글、字。
```

The characters at the first line are half-width, and the second line
are full-width.  (Also note that the last character with a small
circle, the East Asian period, is also full-width.)  Therefore, if we
want to prevent those full-width characters to exceed the maximum
columns per line, we need to count their *width* rather than the number
of characters.  Again, the following characters:

```
글、字。
```

These are just 4 characters, but their total width is 8.

Suppose we want to maintain up to 4 columns per line with the following
text:

```
abcdefg.
글、字。
```

How should it be then?  We want it to look like:

```
abcd
efg.
글、
字。
```

However, Black currently turns it into like this:

```
abcd
efg.
글、字。
```

It's because Black currently counts the number of characters in the line
instead of measuring their width. So, how could we measure the width?
How can we tell if a character is full- or half-width? What if half-width
characters and full-width ones are mixed in a line? That's why Unicode
defined an attribute named `East_Asian_Width`. Unicode grouped every
single character according to their width in fixed-width typeset.

This partially addresses #1197, but only for string splitters. The other
parts need to be fixed as well in future patches.

This was implemented by copying rich's own approach to handling wide
characters: generate a table using wcwidth, check it into source
control, and use in to drive helper functions in Black's logic. This
gets us the best of both worlds: accuracy and performance (and let's us
update as per our stability policy too!).

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 CHANGES.md                                    |   5 +
 scripts/make_width_table.py                   |  73 +++
 src/black/_width_table.py                     | 484 ++++++++++++++++++
 src/black/lines.py                            |   9 +-
 src/black/strings.py                          |  55 ++
 src/black/trans.py                            |  48 +-
 .../preview/long_strings__east_asian_width.py |  25 +
 7 files changed, 678 insertions(+), 21 deletions(-)
 create mode 100644 scripts/make_width_table.py
 create mode 100644 src/black/_width_table.py
 create mode 100644 tests/data/preview/long_strings__east_asian_width.py

diff --git a/CHANGES.md b/CHANGES.md
index f5c039f6509..a429e32c8bd 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -23,6 +23,11 @@
   compared to their non-async version. (#3609)
 - `with` statements that contain two context managers will be consistently wrapped in
   parentheses (#3589)
+- Let string splitters respect [East Asian Width](https://www.unicode.org/reports/tr11/)
+  (#3445)
+- Now long string literals can be split after East Asian commas and periods (`、` U+3001
+  IDEOGRAPHIC COMMA, `。` U+3002 IDEOGRAPHIC FULL STOP, & `，` U+FF0C FULLWIDTH COMMA)
+  besides before spaces (#3445)
 - For stubs, enforce one blank line after a nested class with a body other than just
   `...` (#3564)
 
diff --git a/scripts/make_width_table.py b/scripts/make_width_table.py
new file mode 100644
index 00000000000..09aca9c34b5
--- /dev/null
+++ b/scripts/make_width_table.py
@@ -0,0 +1,73 @@
+"""Generates a width table for Unicode characters.
+
+This script generates a width table for Unicode characters that are not
+narrow (width 1). The table is written to src/black/_width_table.py (note
+that although this file is generated, it is checked into Git) and is used
+by the char_width() function in src/black/strings.py.
+
+You should run this script when you upgrade wcwidth, which is expected to
+happen when a new Unicode version is released. The generated table contains
+the version of wcwidth and Unicode that it was generated for.
+
+In order to run this script, you need to install the latest version of wcwidth.
+You can do this by running:
+
+    pip install -U wcwidth
+
+"""
+import sys
+from os.path import basename, dirname, join
+from typing import Iterable, Tuple
+
+import wcwidth
+
+
+def make_width_table() -> Iterable[Tuple[int, int, int]]:
+    start_codepoint = -1
+    end_codepoint = -1
+    range_width = -2
+    for codepoint in range(0, sys.maxunicode + 1):
+        width = wcwidth.wcwidth(chr(codepoint))
+        if width <= 1:
+            # Ignore narrow characters along with zero-width characters so that
+            # they are treated as single-width.  Note that treating zero-width
+            # characters as single-width is consistent with the heuristics built
+            # on top of str.isascii() in the str_width() function in strings.py.
+            continue
+        if start_codepoint < 0:
+            start_codepoint = codepoint
+            range_width = width
+        elif width != range_width or codepoint != end_codepoint + 1:
+            yield (start_codepoint, end_codepoint, range_width)
+            start_codepoint = codepoint
+            range_width = width
+        end_codepoint = codepoint
+    if start_codepoint >= 0:
+        yield (start_codepoint, end_codepoint, range_width)
+
+
+def main() -> None:
+    table_path = join(dirname(__file__), "..", "src", "black", "_width_table.py")
+    with open(table_path, "w") as f:
+        f.write(
+            f"""# Generated by {basename(__file__)}
+# wcwidth {wcwidth.__version__}
+# Unicode {wcwidth.list_versions()[-1]}
+import sys
+from typing import List, Tuple
+
+if sys.version_info < (3, 8):
+    from typing_extensions import Final
+else:
+    from typing import Final
+
+WIDTH_TABLE: Final[List[Tuple[int, int, int]]] = [
+"""
+        )
+        for triple in make_width_table():
+            f.write(f"    {triple!r},\n")
+        f.write("]\n")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/src/black/_width_table.py b/src/black/_width_table.py
new file mode 100644
index 00000000000..6923f597687
--- /dev/null
+++ b/src/black/_width_table.py
@@ -0,0 +1,484 @@
+# Generated by make_width_table.py
+# wcwidth 0.2.6
+# Unicode 15.0.0
+import sys
+from typing import List, Tuple
+
+if sys.version_info < (3, 8):
+    from typing_extensions import Final
+else:
+    from typing import Final
+
+WIDTH_TABLE: Final[List[Tuple[int, int, int]]] = [
+    (0, 0, 0),
+    (1, 31, -1),
+    (127, 159, -1),
+    (768, 879, 0),
+    (1155, 1161, 0),
+    (1425, 1469, 0),
+    (1471, 1471, 0),
+    (1473, 1474, 0),
+    (1476, 1477, 0),
+    (1479, 1479, 0),
+    (1552, 1562, 0),
+    (1611, 1631, 0),
+    (1648, 1648, 0),
+    (1750, 1756, 0),
+    (1759, 1764, 0),
+    (1767, 1768, 0),
+    (1770, 1773, 0),
+    (1809, 1809, 0),
+    (1840, 1866, 0),
+    (1958, 1968, 0),
+    (2027, 2035, 0),
+    (2045, 2045, 0),
+    (2070, 2073, 0),
+    (2075, 2083, 0),
+    (2085, 2087, 0),
+    (2089, 2093, 0),
+    (2137, 2139, 0),
+    (2200, 2207, 0),
+    (2250, 2273, 0),
+    (2275, 2306, 0),
+    (2362, 2362, 0),
+    (2364, 2364, 0),
+    (2369, 2376, 0),
+    (2381, 2381, 0),
+    (2385, 2391, 0),
+    (2402, 2403, 0),
+    (2433, 2433, 0),
+    (2492, 2492, 0),
+    (2497, 2500, 0),
+    (2509, 2509, 0),
+    (2530, 2531, 0),
+    (2558, 2558, 0),
+    (2561, 2562, 0),
+    (2620, 2620, 0),
+    (2625, 2626, 0),
+    (2631, 2632, 0),
+    (2635, 2637, 0),
+    (2641, 2641, 0),
+    (2672, 2673, 0),
+    (2677, 2677, 0),
+    (2689, 2690, 0),
+    (2748, 2748, 0),
+    (2753, 2757, 0),
+    (2759, 2760, 0),
+    (2765, 2765, 0),
+    (2786, 2787, 0),
+    (2810, 2815, 0),
+    (2817, 2817, 0),
+    (2876, 2876, 0),
+    (2879, 2879, 0),
+    (2881, 2884, 0),
+    (2893, 2893, 0),
+    (2901, 2902, 0),
+    (2914, 2915, 0),
+    (2946, 2946, 0),
+    (3008, 3008, 0),
+    (3021, 3021, 0),
+    (3072, 3072, 0),
+    (3076, 3076, 0),
+    (3132, 3132, 0),
+    (3134, 3136, 0),
+    (3142, 3144, 0),
+    (3146, 3149, 0),
+    (3157, 3158, 0),
+    (3170, 3171, 0),
+    (3201, 3201, 0),
+    (3260, 3260, 0),
+    (3263, 3263, 0),
+    (3270, 3270, 0),
+    (3276, 3277, 0),
+    (3298, 3299, 0),
+    (3328, 3329, 0),
+    (3387, 3388, 0),
+    (3393, 3396, 0),
+    (3405, 3405, 0),
+    (3426, 3427, 0),
+    (3457, 3457, 0),
+    (3530, 3530, 0),
+    (3538, 3540, 0),
+    (3542, 3542, 0),
+    (3633, 3633, 0),
+    (3636, 3642, 0),
+    (3655, 3662, 0),
+    (3761, 3761, 0),
+    (3764, 3772, 0),
+    (3784, 3790, 0),
+    (3864, 3865, 0),
+    (3893, 3893, 0),
+    (3895, 3895, 0),
+    (3897, 3897, 0),
+    (3953, 3966, 0),
+    (3968, 3972, 0),
+    (3974, 3975, 0),
+    (3981, 3991, 0),
+    (3993, 4028, 0),
+    (4038, 4038, 0),
+    (4141, 4144, 0),
+    (4146, 4151, 0),
+    (4153, 4154, 0),
+    (4157, 4158, 0),
+    (4184, 4185, 0),
+    (4190, 4192, 0),
+    (4209, 4212, 0),
+    (4226, 4226, 0),
+    (4229, 4230, 0),
+    (4237, 4237, 0),
+    (4253, 4253, 0),
+    (4352, 4447, 2),
+    (4957, 4959, 0),
+    (5906, 5908, 0),
+    (5938, 5939, 0),
+    (5970, 5971, 0),
+    (6002, 6003, 0),
+    (6068, 6069, 0),
+    (6071, 6077, 0),
+    (6086, 6086, 0),
+    (6089, 6099, 0),
+    (6109, 6109, 0),
+    (6155, 6157, 0),
+    (6159, 6159, 0),
+    (6277, 6278, 0),
+    (6313, 6313, 0),
+    (6432, 6434, 0),
+    (6439, 6440, 0),
+    (6450, 6450, 0),
+    (6457, 6459, 0),
+    (6679, 6680, 0),
+    (6683, 6683, 0),
+    (6742, 6742, 0),
+    (6744, 6750, 0),
+    (6752, 6752, 0),
+    (6754, 6754, 0),
+    (6757, 6764, 0),
+    (6771, 6780, 0),
+    (6783, 6783, 0),
+    (6832, 6862, 0),
+    (6912, 6915, 0),
+    (6964, 6964, 0),
+    (6966, 6970, 0),
+    (6972, 6972, 0),
+    (6978, 6978, 0),
+    (7019, 7027, 0),
+    (7040, 7041, 0),
+    (7074, 7077, 0),
+    (7080, 7081, 0),
+    (7083, 7085, 0),
+    (7142, 7142, 0),
+    (7144, 7145, 0),
+    (7149, 7149, 0),
+    (7151, 7153, 0),
+    (7212, 7219, 0),
+    (7222, 7223, 0),
+    (7376, 7378, 0),
+    (7380, 7392, 0),
+    (7394, 7400, 0),
+    (7405, 7405, 0),
+    (7412, 7412, 0),
+    (7416, 7417, 0),
+    (7616, 7679, 0),
+    (8203, 8207, 0),
+    (8232, 8238, 0),
+    (8288, 8291, 0),
+    (8400, 8432, 0),
+    (8986, 8987, 2),
+    (9001, 9002, 2),
+    (9193, 9196, 2),
+    (9200, 9200, 2),
+    (9203, 9203, 2),
+    (9725, 9726, 2),
+    (9748, 9749, 2),
+    (9800, 9811, 2),
+    (9855, 9855, 2),
+    (9875, 9875, 2),
+    (9889, 9889, 2),
+    (9898, 9899, 2),
+    (9917, 9918, 2),
+    (9924, 9925, 2),
+    (9934, 9934, 2),
+    (9940, 9940, 2),
+    (9962, 9962, 2),
+    (9970, 9971, 2),
+    (9973, 9973, 2),
+    (9978, 9978, 2),
+    (9981, 9981, 2),
+    (9989, 9989, 2),
+    (9994, 9995, 2),
+    (10024, 10024, 2),
+    (10060, 10060, 2),
+    (10062, 10062, 2),
+    (10067, 10069, 2),
+    (10071, 10071, 2),
+    (10133, 10135, 2),
+    (10160, 10160, 2),
+    (10175, 10175, 2),
+    (11035, 11036, 2),
+    (11088, 11088, 2),
+    (11093, 11093, 2),
+    (11503, 11505, 0),
+    (11647, 11647, 0),
+    (11744, 11775, 0),
+    (11904, 11929, 2),
+    (11931, 12019, 2),
+    (12032, 12245, 2),
+    (12272, 12283, 2),
+    (12288, 12329, 2),
+    (12330, 12333, 0),
+    (12334, 12350, 2),
+    (12353, 12438, 2),
+    (12441, 12442, 0),
+    (12443, 12543, 2),
+    (12549, 12591, 2),
+    (12593, 12686, 2),
+    (12688, 12771, 2),
+    (12784, 12830, 2),
+    (12832, 12871, 2),
+    (12880, 19903, 2),
+    (19968, 42124, 2),
+    (42128, 42182, 2),
+    (42607, 42610, 0),
+    (42612, 42621, 0),
+    (42654, 42655, 0),
+    (42736, 42737, 0),
+    (43010, 43010, 0),
+    (43014, 43014, 0),
+    (43019, 43019, 0),
+    (43045, 43046, 0),
+    (43052, 43052, 0),
+    (43204, 43205, 0),
+    (43232, 43249, 0),
+    (43263, 43263, 0),
+    (43302, 43309, 0),
+    (43335, 43345, 0),
+    (43360, 43388, 2),
+    (43392, 43394, 0),
+    (43443, 43443, 0),
+    (43446, 43449, 0),
+    (43452, 43453, 0),
+    (43493, 43493, 0),
+    (43561, 43566, 0),
+    (43569, 43570, 0),
+    (43573, 43574, 0),
+    (43587, 43587, 0),
+    (43596, 43596, 0),
+    (43644, 43644, 0),
+    (43696, 43696, 0),
+    (43698, 43700, 0),
+    (43703, 43704, 0),
+    (43710, 43711, 0),
+    (43713, 43713, 0),
+    (43756, 43757, 0),
+    (43766, 43766, 0),
+    (44005, 44005, 0),
+    (44008, 44008, 0),
+    (44013, 44013, 0),
+    (44032, 55203, 2),
+    (63744, 64255, 2),
+    (64286, 64286, 0),
+    (65024, 65039, 0),
+    (65040, 65049, 2),
+    (65056, 65071, 0),
+    (65072, 65106, 2),
+    (65108, 65126, 2),
+    (65128, 65131, 2),
+    (65281, 65376, 2),
+    (65504, 65510, 2),
+    (66045, 66045, 0),
+    (66272, 66272, 0),
+    (66422, 66426, 0),
+    (68097, 68099, 0),
+    (68101, 68102, 0),
+    (68108, 68111, 0),
+    (68152, 68154, 0),
+    (68159, 68159, 0),
+    (68325, 68326, 0),
+    (68900, 68903, 0),
+    (69291, 69292, 0),
+    (69373, 69375, 0),
+    (69446, 69456, 0),
+    (69506, 69509, 0),
+    (69633, 69633, 0),
+    (69688, 69702, 0),
+    (69744, 69744, 0),
+    (69747, 69748, 0),
+    (69759, 69761, 0),
+    (69811, 69814, 0),
+    (69817, 69818, 0),
+    (69826, 69826, 0),
+    (69888, 69890, 0),
+    (69927, 69931, 0),
+    (69933, 69940, 0),
+    (70003, 70003, 0),
+    (70016, 70017, 0),
+    (70070, 70078, 0),
+    (70089, 70092, 0),
+    (70095, 70095, 0),
+    (70191, 70193, 0),
+    (70196, 70196, 0),
+    (70198, 70199, 0),
+    (70206, 70206, 0),
+    (70209, 70209, 0),
+    (70367, 70367, 0),
+    (70371, 70378, 0),
+    (70400, 70401, 0),
+    (70459, 70460, 0),
+    (70464, 70464, 0),
+    (70502, 70508, 0),
+    (70512, 70516, 0),
+    (70712, 70719, 0),
+    (70722, 70724, 0),
+    (70726, 70726, 0),
+    (70750, 70750, 0),
+    (70835, 70840, 0),
+    (70842, 70842, 0),
+    (70847, 70848, 0),
+    (70850, 70851, 0),
+    (71090, 71093, 0),
+    (71100, 71101, 0),
+    (71103, 71104, 0),
+    (71132, 71133, 0),
+    (71219, 71226, 0),
+    (71229, 71229, 0),
+    (71231, 71232, 0),
+    (71339, 71339, 0),
+    (71341, 71341, 0),
+    (71344, 71349, 0),
+    (71351, 71351, 0),
+    (71453, 71455, 0),
+    (71458, 71461, 0),
+    (71463, 71467, 0),
+    (71727, 71735, 0),
+    (71737, 71738, 0),
+    (71995, 71996, 0),
+    (71998, 71998, 0),
+    (72003, 72003, 0),
+    (72148, 72151, 0),
+    (72154, 72155, 0),
+    (72160, 72160, 0),
+    (72193, 72202, 0),
+    (72243, 72248, 0),
+    (72251, 72254, 0),
+    (72263, 72263, 0),
+    (72273, 72278, 0),
+    (72281, 72283, 0),
+    (72330, 72342, 0),
+    (72344, 72345, 0),
+    (72752, 72758, 0),
+    (72760, 72765, 0),
+    (72767, 72767, 0),
+    (72850, 72871, 0),
+    (72874, 72880, 0),
+    (72882, 72883, 0),
+    (72885, 72886, 0),
+    (73009, 73014, 0),
+    (73018, 73018, 0),
+    (73020, 73021, 0),
+    (73023, 73029, 0),
+    (73031, 73031, 0),
+    (73104, 73105, 0),
+    (73109, 73109, 0),
+    (73111, 73111, 0),
+    (73459, 73460, 0),
+    (73472, 73473, 0),
+    (73526, 73530, 0),
+    (73536, 73536, 0),
+    (73538, 73538, 0),
+    (78912, 78912, 0),
+    (78919, 78933, 0),
+    (92912, 92916, 0),
+    (92976, 92982, 0),
+    (94031, 94031, 0),
+    (94095, 94098, 0),
+    (94176, 94179, 2),
+    (94180, 94180, 0),
+    (94192, 94193, 2),
+    (94208, 100343, 2),
+    (100352, 101589, 2),
+    (101632, 101640, 2),
+    (110576, 110579, 2),
+    (110581, 110587, 2),
+    (110589, 110590, 2),
+    (110592, 110882, 2),
+    (110898, 110898, 2),
+    (110928, 110930, 2),
+    (110933, 110933, 2),
+    (110948, 110951, 2),
+    (110960, 111355, 2),
+    (113821, 113822, 0),
+    (118528, 118573, 0),
+    (118576, 118598, 0),
+    (119143, 119145, 0),
+    (119163, 119170, 0),
+    (119173, 119179, 0),
+    (119210, 119213, 0),
+    (119362, 119364, 0),
+    (121344, 121398, 0),
+    (121403, 121452, 0),
+    (121461, 121461, 0),
+    (121476, 121476, 0),
+    (121499, 121503, 0),
+    (121505, 121519, 0),
+    (122880, 122886, 0),
+    (122888, 122904, 0),
+    (122907, 122913, 0),
+    (122915, 122916, 0),
+    (122918, 122922, 0),
+    (123023, 123023, 0),
+    (123184, 123190, 0),
+    (123566, 123566, 0),
+    (123628, 123631, 0),
+    (124140, 124143, 0),
+    (125136, 125142, 0),
+    (125252, 125258, 0),
+    (126980, 126980, 2),
+    (127183, 127183, 2),
+    (127374, 127374, 2),
+    (127377, 127386, 2),
+    (127488, 127490, 2),
+    (127504, 127547, 2),
+    (127552, 127560, 2),
+    (127568, 127569, 2),
+    (127584, 127589, 2),
+    (127744, 127776, 2),
+    (127789, 127797, 2),
+    (127799, 127868, 2),
+    (127870, 127891, 2),
+    (127904, 127946, 2),
+    (127951, 127955, 2),
+    (127968, 127984, 2),
+    (127988, 127988, 2),
+    (127992, 128062, 2),
+    (128064, 128064, 2),
+    (128066, 128252, 2),
+    (128255, 128317, 2),
+    (128331, 128334, 2),
+    (128336, 128359, 2),
+    (128378, 128378, 2),
+    (128405, 128406, 2),
+    (128420, 128420, 2),
+    (128507, 128591, 2),
+    (128640, 128709, 2),
+    (128716, 128716, 2),
+    (128720, 128722, 2),
+    (128725, 128727, 2),
+    (128732, 128735, 2),
+    (128747, 128748, 2),
+    (128756, 128764, 2),
+    (128992, 129003, 2),
+    (129008, 129008, 2),
+    (129292, 129338, 2),
+    (129340, 129349, 2),
+    (129351, 129535, 2),
+    (129648, 129660, 2),
+    (129664, 129672, 2),
+    (129680, 129725, 2),
+    (129727, 129733, 2),
+    (129742, 129755, 2),
+    (129760, 129768, 2),
+    (129776, 129784, 2),
+    (131072, 196605, 2),
+    (196608, 262141, 2),
+    (917760, 917999, 0),
+]
diff --git a/src/black/lines.py b/src/black/lines.py
index fb5933ecbfb..bf4c12cb684 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -33,6 +33,7 @@
     syms,
     whitespace,
 )
+from black.strings import str_width
 from blib2to3.pgen2 import token
 from blib2to3.pytree import Leaf, Node
 
@@ -759,9 +760,11 @@ def is_line_short_enough(  # noqa: C901
     if not line_str:
         line_str = line_to_string(line)
 
+    width = str_width if mode.preview else len
+
     if Preview.multiline_string_handling not in mode:
         return (
-            len(line_str) <= mode.line_length
+            width(line_str) <= mode.line_length
             and "\n" not in line_str  # multiline strings
             and not line.contains_standalone_comments()
         )
@@ -770,10 +773,10 @@ def is_line_short_enough(  # noqa: C901
         return False
     if "\n" not in line_str:
         # No multiline strings (MLS) present
-        return len(line_str) <= mode.line_length
+        return width(line_str) <= mode.line_length
 
     first, *_, last = line_str.split("\n")
-    if len(first) > mode.line_length or len(last) > mode.line_length:
+    if width(first) > mode.line_length or width(last) > mode.line_length:
         return False
 
     # Traverse the AST to examine the context of the multiline string (MLS),
diff --git a/src/black/strings.py b/src/black/strings.py
index 3e3bc12fe72..ac18aef51ed 100644
--- a/src/black/strings.py
+++ b/src/black/strings.py
@@ -14,6 +14,7 @@
 else:
     from typing import Final
 
+from black._width_table import WIDTH_TABLE
 
 STRING_PREFIX_CHARS: Final = "furbFURB"  # All possible string prefix characters.
 STRING_PREFIX_RE: Final = re.compile(
@@ -278,3 +279,57 @@ def replace(m: Match[str]) -> str:
             return back_slashes + "N{" + groups["N"].upper() + "}"
 
     leaf.value = re.sub(UNICODE_ESCAPE_RE, replace, text)
+
+
+@lru_cache(maxsize=4096)
+def char_width(char: str) -> int:
+    """Return the width of a single character as it would be displayed in a
+    terminal or editor (which respects Unicode East Asian Width).
+
+    Full width characters are counted as 2, while half width characters are
+    counted as 1.  Also control characters are counted as 0.
+    """
+    table = WIDTH_TABLE
+    codepoint = ord(char)
+    highest = len(table) - 1
+    lowest = 0
+    idx = highest // 2
+    while True:
+        start_codepoint, end_codepoint, width = table[idx]
+        if codepoint < start_codepoint:
+            highest = idx - 1
+        elif codepoint > end_codepoint:
+            lowest = idx + 1
+        else:
+            return 0 if width < 0 else width
+        if highest < lowest:
+            break
+        idx = (highest + lowest) // 2
+    return 1
+
+
+def str_width(line_str: str) -> int:
+    """Return the width of `line_str` as it would be displayed in a terminal
+    or editor (which respects Unicode East Asian Width).
+
+    You could utilize this function to determine, for example, if a string
+    is too wide to display in a terminal or editor.
+    """
+    if line_str.isascii():
+        # Fast path for a line consisting of only ASCII characters
+        return len(line_str)
+    return sum(map(char_width, line_str))
+
+
+def count_chars_in_width(line_str: str, max_width: int) -> int:
+    """Count the number of characters in `line_str` that would fit in a
+    terminal or editor of `max_width` (which respects Unicode East Asian
+    Width).
+    """
+    total_width = 0
+    for i, char in enumerate(line_str):
+        width = char_width(char)
+        if width + total_width > max_width:
+            return i
+        total_width += width
+    return len(line_str)
diff --git a/src/black/trans.py b/src/black/trans.py
index a6a416e71bc..95695f32b14 100644
--- a/src/black/trans.py
+++ b/src/black/trans.py
@@ -48,9 +48,11 @@
 from black.rusty import Err, Ok, Result
 from black.strings import (
     assert_is_leaf_string,
+    count_chars_in_width,
     get_string_prefix,
     has_triple_quotes,
     normalize_string_quotes,
+    str_width,
 )
 from blib2to3.pgen2 import token
 from blib2to3.pytree import Leaf, Node
@@ -71,6 +73,8 @@ class CannotTransform(Exception):
 TResult = Result[T, CannotTransform]  # (T)ransform Result
 TMatchResult = TResult[List[Index]]
 
+SPLIT_SAFE_CHARS = frozenset(["\u3001", "\u3002", "\uff0c"])  # East Asian stops
+
 
 def TErr(err_msg: str) -> Err[CannotTransform]:
     """(T)ransform Err
@@ -1164,7 +1168,7 @@ def _get_max_string_length(self, line: Line, string_idx: int) -> int:
             # WMA4 the length of the inline comment.
             offset += len(comment_leaf.value)
 
-        max_string_length = self.line_length - offset
+        max_string_length = count_chars_in_width(str(line), self.line_length - offset)
         return max_string_length
 
     @staticmethod
@@ -1419,11 +1423,13 @@ def maybe_append_string_operators(new_line: Line) -> None:
             is_valid_index(string_idx + 1) and LL[string_idx + 1].type == token.COMMA
         )
 
-        def max_last_string() -> int:
+        def max_last_string_column() -> int:
             """
             Returns:
-                The max allowed length of the string value used for the last
-                line we will construct.
+                The max allowed width of the string value used for the last
+                line we will construct.  Note that this value means the width
+                rather than the number of characters (e.g., many East Asian
+                characters expand to two columns).
             """
             result = self.line_length
             result -= line.depth * 4
@@ -1431,14 +1437,14 @@ def max_last_string() -> int:
             result -= string_op_leaves_length
             return result
 
-        # --- Calculate Max Break Index (for string value)
+        # --- Calculate Max Break Width (for string value)
         # We start with the line length limit
-        max_break_idx = self.line_length
+        max_break_width = self.line_length
         # The last index of a string of length N is N-1.
-        max_break_idx -= 1
+        max_break_width -= 1
         # Leading whitespace is not present in the string value (e.g. Leaf.value).
-        max_break_idx -= line.depth * 4
-        if max_break_idx < 0:
+        max_break_width -= line.depth * 4
+        if max_break_width < 0:
             yield TErr(
                 f"Unable to split {LL[string_idx].value} at such high of a line depth:"
                 f" {line.depth}"
@@ -1451,7 +1457,7 @@ def max_last_string() -> int:
         # line limit.
         use_custom_breakpoints = bool(
             custom_splits
-            and all(csplit.break_idx <= max_break_idx for csplit in custom_splits)
+            and all(csplit.break_idx <= max_break_width for csplit in custom_splits)
         )
 
         # Temporary storage for the remaining chunk of the string line that
@@ -1467,7 +1473,7 @@ def more_splits_should_be_made() -> bool:
             if use_custom_breakpoints:
                 return len(custom_splits) > 1
             else:
-                return len(rest_value) > max_last_string()
+                return str_width(rest_value) > max_last_string_column()
 
         string_line_results: List[Ok[Line]] = []
         while more_splits_should_be_made():
@@ -1477,7 +1483,10 @@ def more_splits_should_be_made() -> bool:
                 break_idx = csplit.break_idx
             else:
                 # Algorithmic Split (automatic)
-                max_bidx = max_break_idx - string_op_leaves_length
+                max_bidx = (
+                    count_chars_in_width(rest_value, max_break_width)
+                    - string_op_leaves_length
+                )
                 maybe_break_idx = self._get_break_idx(rest_value, max_bidx)
                 if maybe_break_idx is None:
                     # If we are unable to algorithmically determine a good split
@@ -1574,7 +1583,7 @@ def more_splits_should_be_made() -> bool:
 
             # Try to fit them all on the same line with the last substring...
             if (
-                len(temp_value) <= max_last_string()
+                str_width(temp_value) <= max_last_string_column()
                 or LL[string_idx + 1].type == token.COMMA
             ):
                 last_line.append(rest_leaf)
@@ -1694,6 +1703,7 @@ def passes_all_checks(i: Index) -> bool:
                 section of this classes' docstring would be be met by returning @i.
             """
             is_space = string[i] == " "
+            is_split_safe = is_valid_index(i - 1) and string[i - 1] in SPLIT_SAFE_CHARS
 
             is_not_escaped = True
             j = i - 1
@@ -1706,7 +1716,7 @@ def passes_all_checks(i: Index) -> bool:
                 and len(string[:i]) >= self.MIN_SUBSTR_SIZE
             )
             return (
-                is_space
+                (is_space or is_split_safe)
                 and is_not_escaped
                 and is_big_enough
                 and not breaks_unsplittable_expression(i)
@@ -1851,11 +1861,13 @@ def do_splitter_match(self, line: Line) -> TMatchResult:
 
         if string_idx is not None:
             string_value = line.leaves[string_idx].value
-            # If the string has no spaces...
-            if " " not in string_value:
+            # If the string has neither spaces nor East Asian stops...
+            if not any(
+                char == " " or char in SPLIT_SAFE_CHARS for char in string_value
+            ):
                 # And will still violate the line length limit when split...
-                max_string_length = self.line_length - ((line.depth + 1) * 4)
-                if len(string_value) > max_string_length:
+                max_string_width = self.line_length - ((line.depth + 1) * 4)
+                if str_width(string_value) > max_string_width:
                     # And has no associated custom splits...
                     if not self.has_custom_splits(string_value):
                         # Then we should NOT put this string on its own line.
diff --git a/tests/data/preview/long_strings__east_asian_width.py b/tests/data/preview/long_strings__east_asian_width.py
new file mode 100644
index 00000000000..fb66a78ed8b
--- /dev/null
+++ b/tests/data/preview/long_strings__east_asian_width.py
@@ -0,0 +1,25 @@
+# The following strings do not have not-so-many chars, but are long enough
+# when these are rendered in a monospace font (if the renderer respects
+# Unicode East Asian Width properties).
+hangul = '코드포인트 수는 적으나 실제 터미널이나 에디터에서 렌더링될 땐 너무 길어서 줄바꿈이 필요한 문자열'
+hanzi = '中文測試：代碼點數量少，但在真正的終端模擬器或編輯器中呈現時太長，因此需要換行的字符串。'
+japanese = 'コードポイントの数は少ないが、実際の端末エミュレータやエディタでレンダリングされる時は長すぎる為、改行が要る文字列'
+
+# output
+
+# The following strings do not have not-so-many chars, but are long enough
+# when these are rendered in a monospace font (if the renderer respects
+# Unicode East Asian Width properties).
+hangul = (
+    "코드포인트 수는 적으나 실제 터미널이나 에디터에서 렌더링될 땐 너무 길어서 줄바꿈이"
+    " 필요한 문자열"
+)
+hanzi = (
+    "中文測試：代碼點數量少，但在真正的終端模擬器或編輯器中呈現時太長，"
+    "因此需要換行的字符串。"
+)
+japanese = (
+    "コードポイントの数は少ないが、"
+    "実際の端末エミュレータやエディタでレンダリングされる時は長すぎる為、"
+    "改行が要る文字列"
+)

From f3b1a3b9d2fc6de8f0845399cb80d8bdfd6400fd Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 27 Mar 2023 07:15:43 -0400
Subject: [PATCH 0737/1034] Bump furo from 2022.12.7 to 2023.3.23 in /docs
 (#3624)

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 docs/requirements.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index 2916b3cee6a..9d059341b14 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -6,4 +6,4 @@ Sphinx==6.1.3
 docutils==0.19
 sphinxcontrib-programoutput==0.17
 sphinx_copybutton==0.5.1
-furo==2022.12.7
+furo==2023.3.23

From b542f589a5c4041f54847591104cd51684849f2e Mon Sep 17 00:00:00 2001
From: Jakub Kuczys <me@jacken.men>
Date: Tue, 28 Mar 2023 03:40:27 +0200
Subject: [PATCH 0738/1034] Use GH action version when version argument not
 specified (#3543)

---
 .git_archival.txt |  4 ++++
 .gitattributes    |  1 +
 CHANGES.md        |  3 +++
 action/main.py    | 24 +++++++++++++++++++++++-
 4 files changed, 31 insertions(+), 1 deletion(-)
 create mode 100644 .git_archival.txt
 create mode 100644 .gitattributes

diff --git a/.git_archival.txt b/.git_archival.txt
new file mode 100644
index 00000000000..8fb235d7045
--- /dev/null
+++ b/.git_archival.txt
@@ -0,0 +1,4 @@
+node: $Format:%H$
+node-date: $Format:%cI$
+describe-name: $Format:%(describe:tags=true,match=*[0-9]*)$
+ref-names: $Format:%D$
diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 00000000000..00a7b00c94e
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1 @@
+.git_archival.txt  export-subst
diff --git a/CHANGES.md b/CHANGES.md
index a429e32c8bd..47c04a7bc76 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -61,6 +61,9 @@
 
 <!-- For example, Docker, GitHub Actions, pre-commit, editors -->
 
+- Update GitHub Action to use the version of Black equivalent to action's version if
+  version input is not specified (#3543)
+
 ### Documentation
 
 <!-- Major changes to documentation and policies. Small docs changes
diff --git a/action/main.py b/action/main.py
index ff9d4112aed..23c3a652194 100644
--- a/action/main.py
+++ b/action/main.py
@@ -22,12 +22,34 @@
     extra_deps = "[colorama,jupyter]"
 else:
     extra_deps = "[colorama]"
-req = f"black{extra_deps}{version_specifier}"
+if version_specifier:
+    req = f"black{extra_deps}{version_specifier}"
+else:
+    describe_name = ""
+    with open(ACTION_PATH / ".git_archival.txt", encoding="utf-8") as fp:
+        for line in fp:
+            if line.startswith("describe-name: "):
+                describe_name = line[len("describe-name: ") :].rstrip()
+                break
+    if not describe_name:
+        print("::error::Failed to detect action version.", flush=True)
+        sys.exit(1)
+    # expected format is one of:
+    # - 23.1.0
+    # - 23.1.0-51-g448bba7
+    if describe_name.count("-") < 2:
+        # the action's commit matches a tag exactly, install exact version from PyPI
+        req = f"black{extra_deps}=={describe_name}"
+    else:
+        # the action's commit does not match any tag, install from the local git repo
+        req = f".{extra_deps}"
+print(f"Installing {req}...", flush=True)
 pip_proc = run(
     [str(ENV_BIN / "python"), "-m", "pip", "install", req],
     stdout=PIPE,
     stderr=STDOUT,
     encoding="utf-8",
+    cwd=ACTION_PATH,
 )
 if pip_proc.returncode:
     print(pip_proc.stdout)

From bf5abdb0b6cf6644628977230736a0a6478c1bff Mon Sep 17 00:00:00 2001
From: Ilia Lazarev <kephircheek@gmail.com>
Date: Tue, 28 Mar 2023 07:12:24 +0300
Subject: [PATCH 0739/1034] Specify Python exec path with minor version if
 available (#3508)

Fixes #3507
---
 CHANGES.md         |  1 +
 autoload/black.vim | 14 +++++++++++---
 2 files changed, 12 insertions(+), 3 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 47c04a7bc76..25710b1b2b0 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -196,6 +196,7 @@ versions separately.
 - Move 3.11 CI to normal flow now that all dependencies support 3.11 (#3446)
 - Docker: Add new `latest_prerelease` tag automation to follow latest black alpha
   release on docker images (#3465)
+- Fixed missing python binary path in autoload script for vim (#3508)
 
 ### Documentation
 
diff --git a/autoload/black.vim b/autoload/black.vim
index c682d51e2b0..4eb9b25db28 100644
--- a/autoload/black.vim
+++ b/autoload/black.vim
@@ -34,7 +34,7 @@ FLAGS = [
 ]
 
 
-def _get_python_binary(exec_prefix):
+def _get_python_binary(exec_prefix, pyver):
   try:
     default = vim.eval("g:pymode_python").strip()
   except vim.error:
@@ -43,7 +43,15 @@ def _get_python_binary(exec_prefix):
     return default
   if sys.platform[:3] == "win":
     return exec_prefix / 'python.exe'
-  return exec_prefix / 'bin' / 'python3'
+  bin_path = exec_prefix / "bin"
+  exec_path = (bin_path / f"python{pyver[0]}.{pyver[1]}").resolve()
+  if exec_path.exists():
+    return exec_path
+  # It is possible that some environments may only have python3
+  exec_path = (bin_path / f"python3").resolve()
+  if exec_path.exists():
+    return exec_path
+  raise ValueError("python executable not found")
 
 def _get_pip(venv_path):
   if sys.platform[:3] == "win":
@@ -82,7 +90,7 @@ def _initialize_black_env(upgrade=False):
     _executable = sys.executable
     _base_executable = getattr(sys, "_base_executable", _executable)
     try:
-      executable = str(_get_python_binary(Path(sys.exec_prefix)))
+      executable = str(_get_python_binary(Path(sys.exec_prefix), pyver))
       sys.executable = executable
       sys._base_executable = executable
       print(f'Creating a virtualenv in {virtualenv_path}...')

From 9b2b048692f0bd642f38230b4e61c778a4653f91 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Tue, 28 Mar 2023 18:46:04 -0600
Subject: [PATCH 0740/1034] Prepare release 23.3.0 (#3625)

---
 CHANGES.md                                  | 68 ++++++++++++++-------
 docs/integrations/source_version_control.md |  2 +-
 docs/usage_and_configuration/the_basics.md  |  2 +-
 3 files changed, 48 insertions(+), 24 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 25710b1b2b0..866d5489008 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -10,27 +10,10 @@
 
 <!-- Changes that affect Black's stable style -->
 
-- Import lines with `# fmt: skip` and `# fmt: off` no longer have an extra blank line
-  added when they are right after another import line (#3610)
-
 ### Preview style
 
 <!-- Changes that affect Black's preview style -->
 
-- Add trailing commas to collection literals even if there's a comment after the last
-  entry (#3393)
-- `async def`, `async for`, and `async with` statements are now formatted consistently
-  compared to their non-async version. (#3609)
-- `with` statements that contain two context managers will be consistently wrapped in
-  parentheses (#3589)
-- Let string splitters respect [East Asian Width](https://www.unicode.org/reports/tr11/)
-  (#3445)
-- Now long string literals can be split after East Asian commas and periods (`、` U+3001
-  IDEOGRAPHIC COMMA, `。` U+3002 IDEOGRAPHIC FULL STOP, & `，` U+FF0C FULLWIDTH COMMA)
-  besides before spaces (#3445)
-- For stubs, enforce one blank line after a nested class with a body other than just
-  `...` (#3564)
-
 ### Configuration
 
 <!-- Changes to how Black can be configured -->
@@ -43,8 +26,6 @@
 
 <!-- Changes to the parser or to version autodetection -->
 
-- Added support for formatting files with invalid type comments (#3594)
-
 ### Performance
 
 <!-- Changes that improve Black's performance. -->
@@ -61,14 +42,57 @@
 
 <!-- For example, Docker, GitHub Actions, pre-commit, editors -->
 
-- Update GitHub Action to use the version of Black equivalent to action's version if
-  version input is not specified (#3543)
-
 ### Documentation
 
 <!-- Major changes to documentation and policies. Small docs changes
      don't need a changelog entry. -->
 
+## 23.3.0
+
+### Highlights
+
+This release fixes a longstanding confusing behavior in Black's GitHub action, where the
+version of the action did not determine the version of Black being run (issue #3382). In
+addition, there is a small bug fix around imports and a number of improvements to the
+preview style.
+
+Please try out the
+[preview style](https://black.readthedocs.io/en/stable/the_black_code_style/future_style.html#preview-style)
+with `black --preview` and tell us your feedback. All changes in the preview style are
+expected to become part of Black's stable style in January 2024.
+
+### Stable style
+
+- Import lines with `# fmt: skip` and `# fmt: off` no longer have an extra blank line
+  added when they are right after another import line (#3610)
+
+### Preview style
+
+- Add trailing commas to collection literals even if there's a comment after the last
+  entry (#3393)
+- `async def`, `async for`, and `async with` statements are now formatted consistently
+  compared to their non-async version. (#3609)
+- `with` statements that contain two context managers will be consistently wrapped in
+  parentheses (#3589)
+- Let string splitters respect [East Asian Width](https://www.unicode.org/reports/tr11/)
+  (#3445)
+- Now long string literals can be split after East Asian commas and periods (`、` U+3001
+  IDEOGRAPHIC COMMA, `。` U+3002 IDEOGRAPHIC FULL STOP, & `，` U+FF0C FULLWIDTH COMMA)
+  besides before spaces (#3445)
+- For stubs, enforce one blank line after a nested class with a body other than just
+  `...` (#3564)
+
+### Parser
+
+- Added support for formatting files with invalid type comments (#3594)
+
+### Integrations
+
+- Update GitHub Action to use the version of Black equivalent to action's version if
+  version input is not specified (#3543)
+
+### Documentation
+
 - Document that only the most recent release is supported for security issues;
   vulnerabilities should be reported through Tidelift (#3612)
 
diff --git a/docs/integrations/source_version_control.md b/docs/integrations/source_version_control.md
index d462e2cc18a..de521833609 100644
--- a/docs/integrations/source_version_control.md
+++ b/docs/integrations/source_version_control.md
@@ -7,7 +7,7 @@ Use [pre-commit](https://pre-commit.com/). Once you
 ```yaml
 repos:
   - repo: https://github.com/psf/black
-    rev: 23.1.0
+    rev: 23.3.0
     hooks:
       - id: black
         # It is recommended to specify the latest version of Python
diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index 2b41c187766..b101e179d0e 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -178,7 +178,7 @@ You can check the version of _Black_ you have installed using the `--version` fl
 
 ```console
 $ black --version
-black, version 23.1.0
+black, version 23.3.0
 ```
 
 An option to require a specific version to be running is also provided.

From bf7a16254ec96b084a6caf3d435ec18f0f245cc7 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Tue, 28 Mar 2023 18:53:23 -0600
Subject: [PATCH 0741/1034] Fixup the changelog (#3628)

---
 CHANGES.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 866d5489008..7c76bca4f6a 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -81,6 +81,7 @@ expected to become part of Black's stable style in January 2024.
   besides before spaces (#3445)
 - For stubs, enforce one blank line after a nested class with a body other than just
   `...` (#3564)
+- Improve handling of multiline strings by changing line split behavior (#1879)
 
 ### Parser
 
@@ -90,6 +91,7 @@ expected to become part of Black's stable style in January 2024.
 
 - Update GitHub Action to use the version of Black equivalent to action's version if
   version input is not specified (#3543)
+- Fix missing Python binary path in autoload script for vim (#3508)
 
 ### Documentation
 
@@ -179,7 +181,6 @@ versions separately.
   code. Implicitly concatenated f-strings with different quotes can now be merged or
   quote-normalized by changing the quotes used in expressions. (#3509)
 - Fix crash on `await (yield)` when Black is compiled with mypyc (#3533)
-- Improve handling of multiline strings by changing line split behavior (#1879)
 
 ### Configuration
 
@@ -220,7 +221,6 @@ versions separately.
 - Move 3.11 CI to normal flow now that all dependencies support 3.11 (#3446)
 - Docker: Add new `latest_prerelease` tag automation to follow latest black alpha
   release on docker images (#3465)
-- Fixed missing python binary path in autoload script for vim (#3508)
 
 ### Documentation
 

From 96ee2fef3dd9fd53e290ab3237d6d5c4ff2bcc6b Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 3 Apr 2023 06:55:17 -0700
Subject: [PATCH 0742/1034] Bump furo from 2023.3.23 to 2023.3.27 in /docs
 (#3636)

Bumps [furo](https://github.com/pradyunsg/furo) from 2023.3.23 to 2023.3.27.
- [Release notes](https://github.com/pradyunsg/furo/releases)
- [Changelog](https://github.com/pradyunsg/furo/blob/main/docs/changelog.md)
- [Commits](https://github.com/pradyunsg/furo/compare/2023.03.23...2023.03.27)

---
updated-dependencies:
- dependency-name: furo
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 docs/requirements.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index 9d059341b14..727a1512cec 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -6,4 +6,4 @@ Sphinx==6.1.3
 docutils==0.19
 sphinxcontrib-programoutput==0.17
 sphinx_copybutton==0.5.1
-furo==2023.3.23
+furo==2023.3.27

From a552f7096a9f6e016c9bb1df1e0a77a17caeec1c Mon Sep 17 00:00:00 2001
From: Harutaka Kawamura <hkawamura0130@gmail.com>
Date: Mon, 3 Apr 2023 22:56:59 +0900
Subject: [PATCH 0743/1034] Fix an example for 'Improved parentheses
 management' in the (future of the) Black code style (#3635)

---
 docs/the_black_code_style/future_style.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/docs/the_black_code_style/future_style.md b/docs/the_black_code_style/future_style.md
index f5fc3644f18..bfab905b288 100644
--- a/docs/the_black_code_style/future_style.md
+++ b/docs/the_black_code_style/future_style.md
@@ -93,7 +93,6 @@ parentheses are now removed. For example:
 
 ```python
 my_dict = {
-    my_dict = {
     "a key in my dict": a_very_long_variable
     * and_a_very_long_function_call()
     / 100000.0,

From f265ff5bcd0eafcde1e62df89fb8b62ad1439887 Mon Sep 17 00:00:00 2001
From: "Yilei \"Dolee\" Yang" <yileiyang@google.com>
Date: Thu, 13 Apr 2023 17:12:05 -0700
Subject: [PATCH 0744/1034] Explicitly annotate this with `Final[str]` to make
 it work in mypyc 1.0.0+. (#3645)

---
 src/blib2to3/pgen2/tokenize.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/blib2to3/pgen2/tokenize.py b/src/blib2to3/pgen2/tokenize.py
index 257dbef4a19..a6353d154c9 100644
--- a/src/blib2to3/pgen2/tokenize.py
+++ b/src/blib2to3/pgen2/tokenize.py
@@ -425,7 +425,7 @@ def generate_tokens(
     logical line; continuation lines are included.
     """
     lnum = parenlev = continued = 0
-    numchars: Final = "0123456789"
+    numchars: Final[str] = "0123456789"
     contstr, needcont = "", 0
     contline: Optional[str] = None
     indents = [0]

From 02f81c6995db4688baedd3c63e4b9821c090f09c Mon Sep 17 00:00:00 2001
From: "Yilei \"Dolee\" Yang" <yileiyang@google.com>
Date: Fri, 14 Apr 2023 14:05:08 -0700
Subject: [PATCH 0745/1034] Fix two more mypyc issues with mypyc v1.2.0.
 (#3648)

---
 src/black/lines.py | 2 +-
 src/black/nodes.py | 6 +++---
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/black/lines.py b/src/black/lines.py
index bf4c12cb684..9d33bfa10b4 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -790,7 +790,7 @@ def is_line_short_enough(  # noqa: C901
     # store the leaves that contain parts of the MLS
     multiline_string_contexts: List[LN] = []
 
-    max_level_to_update = math.inf  # track the depth of the MLS
+    max_level_to_update: Union[int, float] = math.inf  # track the depth of the MLS
     for i, leaf in enumerate(line.leaves):
         if max_level_to_update == math.inf:
             had_comma: Optional[int] = None
diff --git a/src/black/nodes.py b/src/black/nodes.py
index 4e9411b1b79..45070909df4 100644
--- a/src/black/nodes.py
+++ b/src/black/nodes.py
@@ -181,9 +181,9 @@ def whitespace(leaf: Leaf, *, complex_subscript: bool) -> str:  # noqa: C901
     `complex_subscript` signals whether the given leaf is part of a subscription
     which has non-trivial arguments, like arithmetic expressions or function calls.
     """
-    NO: Final = ""
-    SPACE: Final = " "
-    DOUBLESPACE: Final = "  "
+    NO: Final[str] = ""
+    SPACE: Final[str] = " "
+    DOUBLESPACE: Final[str] = "  "
     t = leaf.type
     p = leaf.parent
     v = leaf.value

From 3da73399552b17b70f59d23d32f2347d9a551188 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 17 Apr 2023 07:17:11 -0700
Subject: [PATCH 0746/1034] Bump sphinx-copybutton from 0.5.1 to 0.5.2 in /docs
 (#3651)

Bumps [sphinx-copybutton](https://github.com/executablebooks/sphinx-copybutton) from 0.5.1 to 0.5.2.
- [Release notes](https://github.com/executablebooks/sphinx-copybutton/releases)
- [Changelog](https://github.com/executablebooks/sphinx-copybutton/blob/master/CHANGELOG.md)
- [Commits](https://github.com/executablebooks/sphinx-copybutton/compare/v0.5.1...v0.5.2)

---
updated-dependencies:
- dependency-name: sphinx-copybutton
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 docs/requirements.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index 727a1512cec..168f0c4ec91 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -5,5 +5,5 @@ Sphinx==6.1.3
 # Older versions break Sphinx even though they're declared to be supported.
 docutils==0.19
 sphinxcontrib-programoutput==0.17
-sphinx_copybutton==0.5.1
+sphinx_copybutton==0.5.2
 furo==2023.3.27

From 4b76a548153ed5e58e61c90d0f2e4d817fc19537 Mon Sep 17 00:00:00 2001
From: James Braza <jamesbraza@gmail.com>
Date: Wed, 19 Apr 2023 03:24:03 -0700
Subject: [PATCH 0747/1034] Document black-jupyter hook (#3650)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 docs/integrations/source_version_control.md | 24 +++++++++++++++++----
 1 file changed, 20 insertions(+), 4 deletions(-)

diff --git a/docs/integrations/source_version_control.md b/docs/integrations/source_version_control.md
index de521833609..8b8fd658e0e 100644
--- a/docs/integrations/source_version_control.md
+++ b/docs/integrations/source_version_control.md
@@ -14,7 +14,7 @@ repos:
         # supported by your project here, or alternatively use
         # pre-commit's default_language_version, see
         # https://pre-commit.com/#top_level-default_language_version
-        language_version: python3.9
+        language_version: python3.11
 ```
 
 Feel free to switch out the `rev` value to something else, like another
@@ -22,11 +22,27 @@ Feel free to switch out the `rev` value to something else, like another
 branches or other mutable refs since the hook [won't auto update as you may
 expect][pre-commit-mutable-rev].
 
-If you want support for Jupyter Notebooks as well, then replace `id: black` with
-`id: black-jupyter`.
+## Jupyter Notebooks
+
+There is an alternate hook `black-jupyter` that expands the targets of `black` to
+include Jupyter Notebooks. To use this hook, simply replace the hook's `id: black` with
+`id: black-jupyter` in the `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/psf/black
+    rev: 23.3.0
+    hooks:
+      - id: black-jupyter
+        # It is recommended to specify the latest version of Python
+        # supported by your project here, or alternatively use
+        # pre-commit's default_language_version, see
+        # https://pre-commit.com/#top_level-default_language_version
+        language_version: python3.11
+```
 
 ```{note}
-The `black-jupyter` hook is only available from version 21.8b0 and onwards.
+The `black-jupyter` hook became available in version 21.8b0.
 ```
 
 [black-tags]: https://github.com/psf/black/tags

From de65741b8d49d78fa2675ef79b799cd35e92e7c1 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 24 Apr 2023 04:46:34 -0700
Subject: [PATCH 0748/1034] Bump pypa/cibuildwheel from 2.12.1 to 2.12.3
 (#3657)

Bumps [pypa/cibuildwheel](https://github.com/pypa/cibuildwheel) from 2.12.1 to 2.12.3.
- [Release notes](https://github.com/pypa/cibuildwheel/releases)
- [Changelog](https://github.com/pypa/cibuildwheel/blob/main/docs/changelog.md)
- [Commits](https://github.com/pypa/cibuildwheel/compare/v2.12.1...v2.12.3)

---
updated-dependencies:
- dependency-name: pypa/cibuildwheel
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/pypi_upload.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/pypi_upload.yml b/.github/workflows/pypi_upload.yml
index d5797c7d230..4b59c481bb0 100644
--- a/.github/workflows/pypi_upload.yml
+++ b/.github/workflows/pypi_upload.yml
@@ -58,7 +58,7 @@ jobs:
       - uses: actions/checkout@v3
 
       - name: Build wheels via cibuildwheel
-        uses: pypa/cibuildwheel@v2.12.1
+        uses: pypa/cibuildwheel@v2.12.3
         env:
           CIBW_ARCHS_MACOS: "${{ matrix.macos_arch }}"
 

From e712e48e06420d9240ce95c81acfcf6f11d14c83 Mon Sep 17 00:00:00 2001
From: "Yilei \"Dolee\" Yang" <yileiyang@google.com>
Date: Fri, 28 Apr 2023 11:10:01 -0700
Subject: [PATCH 0749/1034] Do not wrap implicitly concatenated strings used as
 func args in parens (#3640)

---
 CHANGES.md                                    |   3 +
 src/black/__init__.py                         |   6 +-
 src/black/mode.py                             |   6 +-
 src/black/parsing.py                          |   8 +-
 src/black/trans.py                            |  43 ++++--
 tests/data/preview/cantfit.py                 |  12 +-
 tests/data/preview/long_strings.py            |  54 +++-----
 .../data/preview/long_strings__regression.py  |  22 ++-
 tests/test_black.py                           | 126 ++++++------------
 9 files changed, 113 insertions(+), 167 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 7c76bca4f6a..c7ecc396214 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -14,6 +14,9 @@
 
 <!-- Changes that affect Black's preview style -->
 
+- Implicitly concatenated strings used as function args are no longer wrapped inside
+  parentheses (#3640)
+
 ### Configuration
 
 <!-- Changes to how Black can be configured -->
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 4ebf28821c3..871e9a0d7c8 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -503,10 +503,8 @@ def main(  # noqa: C901
             user_level_config = str(find_user_pyproject_toml())
             if config == user_level_config:
                 out(
-                    (
-                        "Using configuration from user-level config at "
-                        f"'{user_level_config}'."
-                    ),
+                    "Using configuration from user-level config at "
+                    f"'{user_level_config}'.",
                     fg="blue",
                 )
             elif config_source in (
diff --git a/src/black/mode.py b/src/black/mode.py
index 0511676ce53..3e37a588e52 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -188,10 +188,8 @@ class Mode:
     def __post_init__(self) -> None:
         if self.experimental_string_processing:
             warn(
-                (
-                    "`experimental string processing` has been included in `preview`"
-                    " and deprecated. Use `preview` instead."
-                ),
+                "`experimental string processing` has been included in `preview`"
+                " and deprecated. Use `preview` instead.",
                 Deprecated,
             )
 
diff --git a/src/black/parsing.py b/src/black/parsing.py
index eaa3c367e54..70ed99c1549 100644
--- a/src/black/parsing.py
+++ b/src/black/parsing.py
@@ -29,11 +29,9 @@
 except ImportError:
     if sys.version_info < (3, 8) and not _IS_PYPY:
         print(
-            (
-                "The typed_ast package is required but not installed.\n"
-                "You can upgrade to Python 3.8+ or install typed_ast with\n"
-                "`python3 -m pip install typed-ast`."
-            ),
+            "The typed_ast package is required but not installed.\n"
+            "You can upgrade to Python 3.8+ or install typed_ast with\n"
+            "`python3 -m pip install typed-ast`.",
             file=sys.stderr,
         )
         sys.exit(1)
diff --git a/src/black/trans.py b/src/black/trans.py
index 95695f32b14..1e28ed0656e 100644
--- a/src/black/trans.py
+++ b/src/black/trans.py
@@ -1186,19 +1186,33 @@ def _prefer_paren_wrap_match(LL: List[Leaf]) -> Optional[int]:
         if LL[0].type != token.STRING:
             return None
 
-        # If the string is surrounded by commas (or is the first/last child)...
-        prev_sibling = LL[0].prev_sibling
-        next_sibling = LL[0].next_sibling
-        if not prev_sibling and not next_sibling and parent_type(LL[0]) == syms.atom:
-            # If it's an atom string, we need to check the parent atom's siblings.
-            parent = LL[0].parent
-            assert parent is not None  # For type checkers.
-            prev_sibling = parent.prev_sibling
-            next_sibling = parent.next_sibling
-        if (not prev_sibling or prev_sibling.type == token.COMMA) and (
-            not next_sibling or next_sibling.type == token.COMMA
+        matching_nodes = [
+            syms.listmaker,
+            syms.dictsetmaker,
+            syms.testlist_gexp,
+        ]
+        # If the string is an immediate child of a list/set/tuple literal...
+        if (
+            parent_type(LL[0]) in matching_nodes
+            or parent_type(LL[0].parent) in matching_nodes
         ):
-            return 0
+            # And the string is surrounded by commas (or is the first/last child)...
+            prev_sibling = LL[0].prev_sibling
+            next_sibling = LL[0].next_sibling
+            if (
+                not prev_sibling
+                and not next_sibling
+                and parent_type(LL[0]) == syms.atom
+            ):
+                # If it's an atom string, we need to check the parent atom's siblings.
+                parent = LL[0].parent
+                assert parent is not None  # For type checkers.
+                prev_sibling = parent.prev_sibling
+                next_sibling = parent.next_sibling
+            if (not prev_sibling or prev_sibling.type == token.COMMA) and (
+                not next_sibling or next_sibling.type == token.COMMA
+            ):
+                return 0
 
         return None
 
@@ -1811,8 +1825,9 @@ class StringParenWrapper(BaseStringSplitter, CustomSplitMapMixin):
         * The line is an lambda expression and the value is a string.
             OR
         * The line starts with an "atom" string that prefers to be wrapped in
-        parens. It's preferred to be wrapped when the string is surrounded by
-        commas (or is the first/last child).
+        parens. It's preferred to be wrapped when it's is an immediate child of
+        a list/set/tuple literal, AND the string is surrounded by commas (or is
+        the first/last child).
 
     Transformations:
         The chosen string is wrapped in parentheses and then split at the LPAR.
diff --git a/tests/data/preview/cantfit.py b/tests/data/preview/cantfit.py
index cade382e30d..0849374f776 100644
--- a/tests/data/preview/cantfit.py
+++ b/tests/data/preview/cantfit.py
@@ -79,14 +79,10 @@
 )
 # long arguments
 normal_name = normal_function_name(
-    (
-        "but with super long string arguments that on their own exceed the line limit"
-        " so there's no way it can ever fit"
-    ),
-    (
-        "eggs with spam and eggs and spam with eggs with spam and eggs and spam with"
-        " eggs with spam and eggs and spam with eggs"
-    ),
+    "but with super long string arguments that on their own exceed the line limit so"
+    " there's no way it can ever fit",
+    "eggs with spam and eggs and spam with eggs with spam and eggs and spam with eggs"
+    " with spam and eggs and spam with eggs",
     this_is_a_ridiculously_long_name_and_nobody_in_their_right_mind_would_use_one_like_it=0,
 )
 string_variable_name = "a string that is waaaaaaaayyyyyyyy too long, even in parens, there's nothing you can do"  # noqa
diff --git a/tests/data/preview/long_strings.py b/tests/data/preview/long_strings.py
index c68da3a8632..059148729d5 100644
--- a/tests/data/preview/long_strings.py
+++ b/tests/data/preview/long_strings.py
@@ -323,10 +323,8 @@ def foo():
 y = "Short string"
 
 print(
-    (
-        "This is a really long string inside of a print statement with extra arguments"
-        " attached at the end of it."
-    ),
+    "This is a really long string inside of a print statement with extra arguments"
+    " attached at the end of it.",
     x,
     y,
     z,
@@ -501,15 +499,13 @@ def foo():
 )
 
 bad_split_func1(
-    (
-        "But what should happen when code has already "
-        "been formatted but in the wrong way? Like "
-        "with a space at the end instead of the "
-        "beginning. Or what about when it is split too "
-        "soon? In the case of a split that is too "
-        "short, black will try to honer the custom "
-        "split."
-    ),
+    "But what should happen when code has already "
+    "been formatted but in the wrong way? Like "
+    "with a space at the end instead of the "
+    "beginning. Or what about when it is split too "
+    "soon? In the case of a split that is too "
+    "short, black will try to honer the custom "
+    "split.",
     xxx,
     yyy,
     zzz,
@@ -612,11 +608,9 @@ def foo():
 )
 
 arg_comment_string = print(
-    (  # This comment gets thrown to the top.
-        "Long lines with inline comments which are apart of (and not the only member"
-        " of) an argument list should have their comments appended to the reformatted"
-        " string's enclosing left parentheses."
-    ),
+    "Long lines with inline comments which are apart of (and not the only member of) an"
+    " argument list should have their comments appended to the reformatted string's"
+    " enclosing left parentheses.",  # This comment gets thrown to the top.
     "Arg #2",
     "Arg #3",
     "Arg #4",
@@ -676,31 +670,23 @@ def foo():
 )
 
 func_with_bad_comma(
-    (
-        "This is a really long string argument to a function that has a trailing comma"
-        " which should NOT be there."
-    ),
+    "This is a really long string argument to a function that has a trailing comma"
+    " which should NOT be there.",
 )
 
 func_with_bad_comma(
-    (  # comment after comma
-        "This is a really long string argument to a function that has a trailing comma"
-        " which should NOT be there."
-    ),
+    "This is a really long string argument to a function that has a trailing comma"
+    " which should NOT be there.",  # comment after comma
 )
 
 func_with_bad_comma(
-    (
-        "This is a really long string argument to a function that has a trailing comma"
-        " which should NOT be there."
-    ),
+    "This is a really long string argument to a function that has a trailing comma"
+    " which should NOT be there.",
 )
 
 func_with_bad_comma(
-    (  # comment after comma
-        "This is a really long string argument to a function that has a trailing comma"
-        " which should NOT be there."
-    ),
+    "This is a really long string argument to a function that has a trailing comma"
+    " which should NOT be there.",  # comment after comma
 )
 
 func_with_bad_parens_that_wont_fit_in_one_line(
diff --git a/tests/data/preview/long_strings__regression.py b/tests/data/preview/long_strings__regression.py
index eead8c204a9..5f0646e6029 100644
--- a/tests/data/preview/long_strings__regression.py
+++ b/tests/data/preview/long_strings__regression.py
@@ -715,11 +715,9 @@ class A:
     def foo():
         some_func_call(
             "xxxxxxxxxx",
-            (
-                "xx {xxxxxxxxxxx}/xxxxxxxxxxx.xxx xxxx.xxx && xxxxxx -x "
-                '"xxxx xxxxxxx xxxxxx xxxx; xxxx xxxxxx_xxxxx xxxxxx xxxx; '
-                "xxxx.xxxx_xxxxxx(['xxxx.xxx'], xxxx.xxxxxxx().xxxxxxxxxx)\" "
-            ),
+            "xx {xxxxxxxxxxx}/xxxxxxxxxxx.xxx xxxx.xxx && xxxxxx -x "
+            '"xxxx xxxxxxx xxxxxx xxxx; xxxx xxxxxx_xxxxx xxxxxx xxxx; '
+            "xxxx.xxxx_xxxxxx(['xxxx.xxx'], xxxx.xxxxxxx().xxxxxxxxxx)\" ",
             None,
             ("xxxxxxxxxxx",),
         ),
@@ -728,11 +726,9 @@ def foo():
 class A:
     def foo():
         some_func_call(
-            (
-                "xx {xxxxxxxxxxx}/xxxxxxxxxxx.xxx xxxx.xxx && xxxxxx -x "
-                "xxxx, ('xxxxxxx xxxxxx xxxx, xxxx') xxxxxx_xxxxx xxxxxx xxxx; "
-                "xxxx.xxxx_xxxxxx(['xxxx.xxx'], xxxx.xxxxxxx().xxxxxxxxxx)\" "
-            ),
+            "xx {xxxxxxxxxxx}/xxxxxxxxxxx.xxx xxxx.xxx && xxxxxx -x "
+            "xxxx, ('xxxxxxx xxxxxx xxxx, xxxx') xxxxxx_xxxxx xxxxxx xxxx; "
+            "xxxx.xxxx_xxxxxx(['xxxx.xxx'], xxxx.xxxxxxx().xxxxxxxxxx)\" ",
             None,
             ("xxxxxxxxxxx",),
         ),
@@ -850,10 +846,8 @@ def foo():
 )
 
 lpar_and_rpar_have_comments = func_call(  # LPAR Comment
-    (  # Comma Comment
-        "Long really ridiculous type of string that shouldn't really even exist at all."
-        " I mean commmme onnn!!!"
-    ),
+    "Long really ridiculous type of string that shouldn't really even exist at all. I"
+    " mean commmme onnn!!!",  # Comma Comment
 )  # RPAR Comment
 
 cmd_fstring = (
diff --git a/tests/test_black.py b/tests/test_black.py
index e5e17777715..00de5b745e7 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -567,10 +567,8 @@ def err(msg: str, **kwargs: Any) -> None:
             self.assertEqual(err_lines[-1], "error: cannot format e1: boom")
             self.assertEqual(
                 unstyle(str(report)),
-                (
-                    "1 file reformatted, 2 files left unchanged, 1 file failed to"
-                    " reformat."
-                ),
+                "1 file reformatted, 2 files left unchanged, 1 file failed to"
+                " reformat.",
             )
             self.assertEqual(report.return_code, 123)
             report.done(Path("f3"), black.Changed.YES)
@@ -579,10 +577,8 @@ def err(msg: str, **kwargs: Any) -> None:
             self.assertEqual(out_lines[-1], "reformatted f3")
             self.assertEqual(
                 unstyle(str(report)),
-                (
-                    "2 files reformatted, 2 files left unchanged, 1 file failed to"
-                    " reformat."
-                ),
+                "2 files reformatted, 2 files left unchanged, 1 file failed to"
+                " reformat.",
             )
             self.assertEqual(report.return_code, 123)
             report.failed(Path("e2"), "boom")
@@ -591,10 +587,8 @@ def err(msg: str, **kwargs: Any) -> None:
             self.assertEqual(err_lines[-1], "error: cannot format e2: boom")
             self.assertEqual(
                 unstyle(str(report)),
-                (
-                    "2 files reformatted, 2 files left unchanged, 2 files failed to"
-                    " reformat."
-                ),
+                "2 files reformatted, 2 files left unchanged, 2 files failed to"
+                " reformat.",
             )
             self.assertEqual(report.return_code, 123)
             report.path_ignored(Path("wat"), "no match")
@@ -603,10 +597,8 @@ def err(msg: str, **kwargs: Any) -> None:
             self.assertEqual(out_lines[-1], "wat ignored: no match")
             self.assertEqual(
                 unstyle(str(report)),
-                (
-                    "2 files reformatted, 2 files left unchanged, 2 files failed to"
-                    " reformat."
-                ),
+                "2 files reformatted, 2 files left unchanged, 2 files failed to"
+                " reformat.",
             )
             self.assertEqual(report.return_code, 123)
             report.done(Path("f4"), black.Changed.NO)
@@ -615,28 +607,22 @@ def err(msg: str, **kwargs: Any) -> None:
             self.assertEqual(out_lines[-1], "f4 already well formatted, good job.")
             self.assertEqual(
                 unstyle(str(report)),
-                (
-                    "2 files reformatted, 3 files left unchanged, 2 files failed to"
-                    " reformat."
-                ),
+                "2 files reformatted, 3 files left unchanged, 2 files failed to"
+                " reformat.",
             )
             self.assertEqual(report.return_code, 123)
             report.check = True
             self.assertEqual(
                 unstyle(str(report)),
-                (
-                    "2 files would be reformatted, 3 files would be left unchanged, 2"
-                    " files would fail to reformat."
-                ),
+                "2 files would be reformatted, 3 files would be left unchanged, 2"
+                " files would fail to reformat.",
             )
             report.check = False
             report.diff = True
             self.assertEqual(
                 unstyle(str(report)),
-                (
-                    "2 files would be reformatted, 3 files would be left unchanged, 2"
-                    " files would fail to reformat."
-                ),
+                "2 files would be reformatted, 3 files would be left unchanged, 2"
+                " files would fail to reformat.",
             )
 
     def test_report_quiet(self) -> None:
@@ -678,10 +664,8 @@ def err(msg: str, **kwargs: Any) -> None:
             self.assertEqual(err_lines[-1], "error: cannot format e1: boom")
             self.assertEqual(
                 unstyle(str(report)),
-                (
-                    "1 file reformatted, 2 files left unchanged, 1 file failed to"
-                    " reformat."
-                ),
+                "1 file reformatted, 2 files left unchanged, 1 file failed to"
+                " reformat.",
             )
             self.assertEqual(report.return_code, 123)
             report.done(Path("f3"), black.Changed.YES)
@@ -689,10 +673,8 @@ def err(msg: str, **kwargs: Any) -> None:
             self.assertEqual(len(err_lines), 1)
             self.assertEqual(
                 unstyle(str(report)),
-                (
-                    "2 files reformatted, 2 files left unchanged, 1 file failed to"
-                    " reformat."
-                ),
+                "2 files reformatted, 2 files left unchanged, 1 file failed to"
+                " reformat.",
             )
             self.assertEqual(report.return_code, 123)
             report.failed(Path("e2"), "boom")
@@ -701,10 +683,8 @@ def err(msg: str, **kwargs: Any) -> None:
             self.assertEqual(err_lines[-1], "error: cannot format e2: boom")
             self.assertEqual(
                 unstyle(str(report)),
-                (
-                    "2 files reformatted, 2 files left unchanged, 2 files failed to"
-                    " reformat."
-                ),
+                "2 files reformatted, 2 files left unchanged, 2 files failed to"
+                " reformat.",
             )
             self.assertEqual(report.return_code, 123)
             report.path_ignored(Path("wat"), "no match")
@@ -712,10 +692,8 @@ def err(msg: str, **kwargs: Any) -> None:
             self.assertEqual(len(err_lines), 2)
             self.assertEqual(
                 unstyle(str(report)),
-                (
-                    "2 files reformatted, 2 files left unchanged, 2 files failed to"
-                    " reformat."
-                ),
+                "2 files reformatted, 2 files left unchanged, 2 files failed to"
+                " reformat.",
             )
             self.assertEqual(report.return_code, 123)
             report.done(Path("f4"), black.Changed.NO)
@@ -723,28 +701,22 @@ def err(msg: str, **kwargs: Any) -> None:
             self.assertEqual(len(err_lines), 2)
             self.assertEqual(
                 unstyle(str(report)),
-                (
-                    "2 files reformatted, 3 files left unchanged, 2 files failed to"
-                    " reformat."
-                ),
+                "2 files reformatted, 3 files left unchanged, 2 files failed to"
+                " reformat.",
             )
             self.assertEqual(report.return_code, 123)
             report.check = True
             self.assertEqual(
                 unstyle(str(report)),
-                (
-                    "2 files would be reformatted, 3 files would be left unchanged, 2"
-                    " files would fail to reformat."
-                ),
+                "2 files would be reformatted, 3 files would be left unchanged, 2"
+                " files would fail to reformat.",
             )
             report.check = False
             report.diff = True
             self.assertEqual(
                 unstyle(str(report)),
-                (
-                    "2 files would be reformatted, 3 files would be left unchanged, 2"
-                    " files would fail to reformat."
-                ),
+                "2 files would be reformatted, 3 files would be left unchanged, 2"
+                " files would fail to reformat.",
             )
 
     def test_report_normal(self) -> None:
@@ -788,10 +760,8 @@ def err(msg: str, **kwargs: Any) -> None:
             self.assertEqual(err_lines[-1], "error: cannot format e1: boom")
             self.assertEqual(
                 unstyle(str(report)),
-                (
-                    "1 file reformatted, 2 files left unchanged, 1 file failed to"
-                    " reformat."
-                ),
+                "1 file reformatted, 2 files left unchanged, 1 file failed to"
+                " reformat.",
             )
             self.assertEqual(report.return_code, 123)
             report.done(Path("f3"), black.Changed.YES)
@@ -800,10 +770,8 @@ def err(msg: str, **kwargs: Any) -> None:
             self.assertEqual(out_lines[-1], "reformatted f3")
             self.assertEqual(
                 unstyle(str(report)),
-                (
-                    "2 files reformatted, 2 files left unchanged, 1 file failed to"
-                    " reformat."
-                ),
+                "2 files reformatted, 2 files left unchanged, 1 file failed to"
+                " reformat.",
             )
             self.assertEqual(report.return_code, 123)
             report.failed(Path("e2"), "boom")
@@ -812,10 +780,8 @@ def err(msg: str, **kwargs: Any) -> None:
             self.assertEqual(err_lines[-1], "error: cannot format e2: boom")
             self.assertEqual(
                 unstyle(str(report)),
-                (
-                    "2 files reformatted, 2 files left unchanged, 2 files failed to"
-                    " reformat."
-                ),
+                "2 files reformatted, 2 files left unchanged, 2 files failed to"
+                " reformat.",
             )
             self.assertEqual(report.return_code, 123)
             report.path_ignored(Path("wat"), "no match")
@@ -823,10 +789,8 @@ def err(msg: str, **kwargs: Any) -> None:
             self.assertEqual(len(err_lines), 2)
             self.assertEqual(
                 unstyle(str(report)),
-                (
-                    "2 files reformatted, 2 files left unchanged, 2 files failed to"
-                    " reformat."
-                ),
+                "2 files reformatted, 2 files left unchanged, 2 files failed to"
+                " reformat.",
             )
             self.assertEqual(report.return_code, 123)
             report.done(Path("f4"), black.Changed.NO)
@@ -834,28 +798,22 @@ def err(msg: str, **kwargs: Any) -> None:
             self.assertEqual(len(err_lines), 2)
             self.assertEqual(
                 unstyle(str(report)),
-                (
-                    "2 files reformatted, 3 files left unchanged, 2 files failed to"
-                    " reformat."
-                ),
+                "2 files reformatted, 3 files left unchanged, 2 files failed to"
+                " reformat.",
             )
             self.assertEqual(report.return_code, 123)
             report.check = True
             self.assertEqual(
                 unstyle(str(report)),
-                (
-                    "2 files would be reformatted, 3 files would be left unchanged, 2"
-                    " files would fail to reformat."
-                ),
+                "2 files would be reformatted, 3 files would be left unchanged, 2"
+                " files would fail to reformat.",
             )
             report.check = False
             report.diff = True
             self.assertEqual(
                 unstyle(str(report)),
-                (
-                    "2 files would be reformatted, 3 files would be left unchanged, 2"
-                    " files would fail to reformat."
-                ),
+                "2 files would be reformatted, 3 files would be left unchanged, 2"
+                " files would fail to reformat.",
             )
 
     def test_lib2to3_parse(self) -> None:

From a07871b9cd1b5a1469271be6aaac5766f5a0e0fc Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Wed, 3 May 2023 08:43:20 -0700
Subject: [PATCH 0750/1034] Fix new mypy error in blib2to3 (#3674)

See python/mypy#15174
---
 src/blib2to3/pgen2/tokenize.py     | 11 ++++++-----
 tests/data/simple_cases/fstring.py |  4 ++++
 2 files changed, 10 insertions(+), 5 deletions(-)

diff --git a/src/blib2to3/pgen2/tokenize.py b/src/blib2to3/pgen2/tokenize.py
index a6353d154c9..82ac5130bad 100644
--- a/src/blib2to3/pgen2/tokenize.py
+++ b/src/blib2to3/pgen2/tokenize.py
@@ -163,7 +163,6 @@ def _combinations(*l):
     '"""': double3prog,
     **{f"{prefix}'''": single3prog for prefix in _strprefixes},
     **{f'{prefix}"""': double3prog for prefix in _strprefixes},
-    **{prefix: None for prefix in _strprefixes},
 }
 
 triple_quoted: Final = (
@@ -599,11 +598,13 @@ def generate_tokens(
                 ):
                     if token[-1] == "\n":  # continued string
                         strstart = (lnum, start)
-                        endprog = (
-                            endprogs[initial]
-                            or endprogs[token[1]]
-                            or endprogs[token[2]]
+                        maybe_endprog = (
+                            endprogs.get(initial)
+                            or endprogs.get(token[1])
+                            or endprogs.get(token[2])
                         )
+                        assert maybe_endprog is not None, f"endprog not found for {token}"
+                        endprog = maybe_endprog
                         contstr, needcont = line[start:], 1
                         contline = line
                         break
diff --git a/tests/data/simple_cases/fstring.py b/tests/data/simple_cases/fstring.py
index 4b33231c01c..60560309376 100644
--- a/tests/data/simple_cases/fstring.py
+++ b/tests/data/simple_cases/fstring.py
@@ -7,6 +7,8 @@
 f"\"{f'{nested} inner'}\" outer"
 f"space between opening braces: { {a for a in (1, 2, 3)}}"
 f'Hello \'{tricky + "example"}\''
+f"Tried directories {str(rootdirs)} \
+but none started with prefix {parentdir_prefix}"
 
 # output
 
@@ -19,3 +21,5 @@
 f"\"{f'{nested} inner'}\" outer"
 f"space between opening braces: { {a for a in (1, 2, 3)}}"
 f'Hello \'{tricky + "example"}\''
+f"Tried directories {str(rootdirs)} \
+but none started with prefix {parentdir_prefix}"

From eb32729ab562c010d9f644a3bbb2305196b2deb7 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Wed, 3 May 2023 10:26:57 -0700
Subject: [PATCH 0751/1034] blib2to3: add a few annotations (#3675)

---
 src/blib2to3/pgen2/tokenize.py | 29 +++++++++++++++++------------
 1 file changed, 17 insertions(+), 12 deletions(-)

diff --git a/src/blib2to3/pgen2/tokenize.py b/src/blib2to3/pgen2/tokenize.py
index 82ac5130bad..2d0cc4324ce 100644
--- a/src/blib2to3/pgen2/tokenize.py
+++ b/src/blib2to3/pgen2/tokenize.py
@@ -34,6 +34,7 @@
     Iterator,
     List,
     Optional,
+    Set,
     Text,
     Tuple,
     Pattern,
@@ -66,19 +67,19 @@
 del token
 
 
-def group(*choices):
+def group(*choices: str) -> str:
     return "(" + "|".join(choices) + ")"
 
 
-def any(*choices):
+def any(*choices: str) -> str:
     return group(*choices) + "*"
 
 
-def maybe(*choices):
+def maybe(*choices: str) -> str:
     return group(*choices) + "?"
 
 
-def _combinations(*l):
+def _combinations(*l: str) -> Set[str]:
     return set(x + y for x in l for y in l + ("",) if x.casefold() != y.casefold())
 
 
@@ -187,15 +188,19 @@ class StopTokenizing(Exception):
     pass
 
 
-def printtoken(type, token, xxx_todo_changeme, xxx_todo_changeme1, line):  # for testing
-    (srow, scol) = xxx_todo_changeme
-    (erow, ecol) = xxx_todo_changeme1
+Coord = Tuple[int, int]
+
+
+def printtoken(
+    type: int, token: Text, srow_col: Coord, erow_col: Coord, line: Text
+) -> None:  # for testing
+    (srow, scol) = srow_col
+    (erow, ecol) = erow_col
     print(
         "%d,%d-%d,%d:\t%s\t%s" % (srow, scol, erow, ecol, tok_name[type], repr(token))
     )
 
 
-Coord = Tuple[int, int]
 TokenEater = Callable[[int, Text, Coord, Coord, Text], None]
 
 
@@ -219,7 +224,7 @@ def tokenize(readline: Callable[[], Text], tokeneater: TokenEater = printtoken)
 
 
 # backwards compatible interface
-def tokenize_loop(readline, tokeneater):
+def tokenize_loop(readline: Callable[[], Text], tokeneater: TokenEater) -> None:
     for token_info in generate_tokens(readline):
         tokeneater(*token_info)
 
@@ -229,7 +234,6 @@ def tokenize_loop(readline, tokeneater):
 
 
 class Untokenizer:
-
     tokens: List[Text]
     prev_row: int
     prev_col: int
@@ -603,7 +607,9 @@ def generate_tokens(
                             or endprogs.get(token[1])
                             or endprogs.get(token[2])
                         )
-                        assert maybe_endprog is not None, f"endprog not found for {token}"
+                        assert (
+                            maybe_endprog is not None
+                        ), f"endprog not found for {token}"
                         endprog = maybe_endprog
                         contstr, needcont = line[start:], 1
                         contline = line
@@ -632,7 +638,6 @@ def generate_tokens(
 
                     if token in ("def", "for"):
                         if stashed and stashed[0] == NAME and stashed[1] == "async":
-
                             if token == "def":
                                 async_def = True
                                 async_def_indent = indents[-1]

From 64887aab032c0fd64f9238cdab6684f2fc0c7f33 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 8 May 2023 06:36:24 -0700
Subject: [PATCH 0752/1034] Bump peter-evans/create-or-update-comment from
 2.1.1 to 3.0.1 (#3683)

Bumps [peter-evans/create-or-update-comment](https://github.com/peter-evans/create-or-update-comment) from 2.1.1 to 3.0.1.
- [Release notes](https://github.com/peter-evans/create-or-update-comment/releases)
- [Commits](https://github.com/peter-evans/create-or-update-comment/compare/67dcc547d311b736a8e6c5c236542148a47adc3d...ca08ebd5dc95aa0cd97021e9708fcd6b87138c9b)

---
updated-dependencies:
- dependency-name: peter-evans/create-or-update-comment
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/diff_shades_comment.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/diff_shades_comment.yml b/.github/workflows/diff_shades_comment.yml
index bb81ca4f0d6..70ab7ff4f7a 100644
--- a/.github/workflows/diff_shades_comment.yml
+++ b/.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@67dcc547d311b736a8e6c5c236542148a47adc3d
+        uses: peter-evans/create-or-update-comment@ca08ebd5dc95aa0cd97021e9708fcd6b87138c9b
         with:
           comment-id: ${{ steps.find-comment.outputs.comment-id }}
           issue-number: ${{ steps.metadata.outputs.pr-number }}

From c97b9c55b488a478afe171537c0e4c0f10631ca1 Mon Sep 17 00:00:00 2001
From: Matthieu Simon <matthieu@bluegreen.sh>
Date: Mon, 15 May 2023 23:35:39 +0200
Subject: [PATCH 0753/1034] [github action] display black result in job summary
 (#3688)

* send output to $GITHUB_STEP_SUMMARY

* update CHANGES.md

* update CHANGES.md with PR number

* implement PR feedback

* fix pre-commit issues (prettier/trailing whitespace)
---
 CHANGES.md     |  2 ++
 action.yml     |  7 ++++---
 action/main.py | 20 +++++++++++++++-----
 3 files changed, 21 insertions(+), 8 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index c7ecc396214..f9bec185ff5 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -45,6 +45,8 @@
 
 <!-- For example, Docker, GitHub Actions, pre-commit, editors -->
 
+- Update GitHub Action to display black output in the job summary (#3688)
+
 ### Documentation
 
 <!-- Major changes to documentation and policies. Small docs changes
diff --git a/action.yml b/action.yml
index 35705e99414..282fca43dea 100644
--- a/action.yml
+++ b/action.yml
@@ -33,11 +33,12 @@ branding:
 runs:
   using: composite
   steps:
-    - run: |
+    - name: black
+      run: |
         if [ "$RUNNER_OS" == "Windows" ]; then
-          python $GITHUB_ACTION_PATH/action/main.py
+          python $GITHUB_ACTION_PATH/action/main.py | tee -a $GITHUB_STEP_SUMMARY
         else
-          python3 $GITHUB_ACTION_PATH/action/main.py
+          python3 $GITHUB_ACTION_PATH/action/main.py | tee -a $GITHUB_STEP_SUMMARY
         fi
       env:
         # TODO: Remove once https://github.com/actions/runner/issues/665 is fixed.
diff --git a/action/main.py b/action/main.py
index 23c3a652194..1911cfd7a01 100644
--- a/action/main.py
+++ b/action/main.py
@@ -32,7 +32,7 @@
                 describe_name = line[len("describe-name: ") :].rstrip()
                 break
     if not describe_name:
-        print("::error::Failed to detect action version.", flush=True)
+        print("::error::Failed to detect action version.", file=sys.stderr, flush=True)
         sys.exit(1)
     # expected format is one of:
     # - 23.1.0
@@ -53,15 +53,25 @@
 )
 if pip_proc.returncode:
     print(pip_proc.stdout)
-    print("::error::Failed to install Black.", flush=True)
+    print("::error::Failed to install Black.", file=sys.stderr, flush=True)
     sys.exit(pip_proc.returncode)
 
 
 base_cmd = [str(ENV_BIN / "black")]
 if BLACK_ARGS:
     # TODO: remove after a while since this is deprecated in favour of SRC + OPTIONS.
-    proc = run([*base_cmd, *shlex.split(BLACK_ARGS)])
+    proc = run(
+        [*base_cmd, *shlex.split(BLACK_ARGS)],
+        stdout=PIPE,
+        stderr=STDOUT,
+        encoding="utf-8",
+    )
 else:
-    proc = run([*base_cmd, *shlex.split(OPTIONS), *shlex.split(SRC)])
-
+    proc = run(
+        [*base_cmd, *shlex.split(OPTIONS), *shlex.split(SRC)],
+        stdout=PIPE,
+        stderr=STDOUT,
+        encoding="utf-8",
+    )
+print(proc.stdout)
 sys.exit(proc.returncode)

From dc188f2060eff70b539c834f8576e8826cee5de7 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 15 May 2023 15:41:35 -0700
Subject: [PATCH 0754/1034] Bump peter-evans/find-comment from 2.3.0 to 2.4.0
 (#3670)

Bumps [peter-evans/find-comment](https://github.com/peter-evans/find-comment) from 2.3.0 to 2.4.0.
- [Release notes](https://github.com/peter-evans/find-comment/releases)
- [Commits](https://github.com/peter-evans/find-comment/compare/034abe94d3191f9c89d870519735beae326f2bdb...a54c31d7fa095754bfef525c0c8e5e5674c4b4b1)

---
updated-dependencies:
- dependency-name: peter-evans/find-comment
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Cooper Lees <me@cooperlees.com>
---
 .github/workflows/diff_shades_comment.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/diff_shades_comment.yml b/.github/workflows/diff_shades_comment.yml
index 70ab7ff4f7a..95dd9b01dba 100644
--- a/.github/workflows/diff_shades_comment.yml
+++ b/.github/workflows/diff_shades_comment.yml
@@ -33,7 +33,7 @@ jobs:
       - name: Try to find pre-existing PR comment
         if: steps.metadata.outputs.needs-comment == 'true'
         id: find-comment
-        uses: peter-evans/find-comment@034abe94d3191f9c89d870519735beae326f2bdb
+        uses: peter-evans/find-comment@a54c31d7fa095754bfef525c0c8e5e5674c4b4b1
         with:
           issue-number: ${{ steps.metadata.outputs.pr-number }}
           comment-author: "github-actions[bot]"

From db3668a381e82866269ff25cb4cd11d2a53d009a Mon Sep 17 00:00:00 2001
From: Ray Bell <rayjohnbell0@gmail.com>
Date: Tue, 16 May 2023 22:47:45 -0400
Subject: [PATCH 0755/1034] Sort DEFAULT_EXCLUDES and add .vscode,
 .pytest_cache and .ruff_cache (#3691)

Co-authored-by: Ray Bell <ray.bell@dtn.com>
---
 CHANGES.md         | 2 ++
 src/black/const.py | 2 +-
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index f9bec185ff5..a1bc7d59020 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -21,6 +21,8 @@
 
 <!-- Changes to how Black can be configured -->
 
+- `.pytest_cache`, `.ruff_cache` and `.vscode` are now excluded by default (#3691)
+
 ### Packaging
 
 <!-- Changes to how Black is packaged, such as dependency requirements -->
diff --git a/src/black/const.py b/src/black/const.py
index 0e13f31517d..ee466679c70 100644
--- a/src/black/const.py
+++ b/src/black/const.py
@@ -1,4 +1,4 @@
 DEFAULT_LINE_LENGTH = 88
-DEFAULT_EXCLUDES = r"/(\.direnv|\.eggs|\.git|\.hg|\.mypy_cache|\.nox|\.tox|\.venv|venv|\.svn|\.ipynb_checkpoints|_build|buck-out|build|dist|__pypackages__)/"  # noqa: B950
+DEFAULT_EXCLUDES = r"/(\.direnv|\.eggs|\.git|\.hg|\.ipynb_checkpoints|\.mypy_cache|\.nox|\.pytest_cache|\.ruff_cache|\.tox|\.svn|\.venv|\.vscode|__pypackages__|_build|buck-out|build|dist|venv)/"  # noqa: B950
 DEFAULT_INCLUDES = r"(\.pyi?|\.ipynb)$"
 STDIN_PLACEHOLDER = "__BLACK_STDIN_FILENAME__"

From 2fd9d8b339e1e2e1b93956c6d68b2b358b3fc29d Mon Sep 17 00:00:00 2001
From: Jonathan Berthias <jvberthias@gmail.com>
Date: Fri, 19 May 2023 01:57:17 +0200
Subject: [PATCH 0756/1034] Remove blank lines before class docstring (#3692)

---
 CHANGES.md                                    |  1 +
 src/black/lines.py                            |  2 +
 src/black/mode.py                             |  1 +
 .../preview/no_blank_line_before_docstring.py | 58 +++++++++++++++++++
 4 files changed, 62 insertions(+)
 create mode 100644 tests/data/preview/no_blank_line_before_docstring.py

diff --git a/CHANGES.md b/CHANGES.md
index a1bc7d59020..6a9923f8d8d 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -16,6 +16,7 @@
 
 - Implicitly concatenated strings used as function args are no longer wrapped inside
   parentheses (#3640)
+- Remove blank lines between a class definition and its docstring (#3692)
 
 ### Configuration
 
diff --git a/src/black/lines.py b/src/black/lines.py
index 9d33bfa10b4..daf0444d24e 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -634,6 +634,8 @@ def _maybe_empty_lines(self, current_line: Line) -> Tuple[int, int]:
             and self.previous_line.is_class
             and current_line.is_triple_quoted_string
         ):
+            if Preview.no_blank_line_before_class_docstring in current_line.mode:
+                return 0, 1
             return before, 1
 
         if self.previous_line and self.previous_line.opens_block:
diff --git a/src/black/mode.py b/src/black/mode.py
index 3e37a588e52..a5841edb30a 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -158,6 +158,7 @@ class Preview(Enum):
     hex_codes_in_unicode_sequences = auto()
     improved_async_statements_handling = auto()
     multiline_string_handling = auto()
+    no_blank_line_before_class_docstring = auto()
     prefer_splitting_right_hand_side_of_assignments = auto()
     # NOTE: string_processing requires wrap_long_dict_values_in_parens
     # for https://github.com/psf/black/issues/3117 to be fixed.
diff --git a/tests/data/preview/no_blank_line_before_docstring.py b/tests/data/preview/no_blank_line_before_docstring.py
new file mode 100644
index 00000000000..a37362de100
--- /dev/null
+++ b/tests/data/preview/no_blank_line_before_docstring.py
@@ -0,0 +1,58 @@
+def line_before_docstring():
+
+    """Please move me up"""
+
+
+class LineBeforeDocstring:
+
+    """Please move me up"""
+
+
+class EvenIfThereIsAMethodAfter:
+
+    """I'm the docstring"""
+    def method(self):
+        pass
+
+
+class TwoLinesBeforeDocstring:
+
+
+    """I want to be treated the same as if I were closer"""
+
+
+class MultilineDocstringsAsWell:
+
+    """I'm so far
+
+    and on so many lines...
+    """
+
+
+# output
+
+
+def line_before_docstring():
+    """Please move me up"""
+
+
+class LineBeforeDocstring:
+    """Please move me up"""
+
+
+class EvenIfThereIsAMethodAfter:
+    """I'm the docstring"""
+
+    def method(self):
+        pass
+
+
+class TwoLinesBeforeDocstring:
+    """I want to be treated the same as if I were closer"""
+
+
+class MultilineDocstringsAsWell:
+    """I'm so far
+
+    and on so many lines...
+    """

From eedfc3832290b3a32825b3c0f2dfa3f3d7ee9d1c Mon Sep 17 00:00:00 2001
From: "Jason R. Coombs" <jaraco@jaraco.com>
Date: Fri, 19 May 2023 13:00:29 -0400
Subject: [PATCH 0757/1034] Avoid EncodingWarning in blib2to3 (#3696)

---
 src/blib2to3/pgen2/pgen.py | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/src/blib2to3/pgen2/pgen.py b/src/blib2to3/pgen2/pgen.py
index 631682a77c9..b5ebc7b3e42 100644
--- a/src/blib2to3/pgen2/pgen.py
+++ b/src/blib2to3/pgen2/pgen.py
@@ -30,7 +30,6 @@ class PgenGrammar(grammar.Grammar):
 
 
 class ParserGenerator(object):
-
     filename: Path
     stream: IO[Text]
     generator: Iterator[GoodTokenInfo]
@@ -39,7 +38,7 @@ class ParserGenerator(object):
     def __init__(self, filename: Path, stream: Optional[IO[Text]] = None) -> None:
         close_stream = None
         if stream is None:
-            stream = open(filename)
+            stream = open(filename, encoding="utf-8")
             close_stream = stream.close
         self.filename = filename
         self.stream = stream

From cd02c2809b193e17aa7c43f8dd0fae4695898184 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 22 May 2023 11:47:58 -0400
Subject: [PATCH 0758/1034] Bump furo from 2023.3.27 to 2023.5.20 in /docs
 (#3698)

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 docs/requirements.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index 168f0c4ec91..7b26d089b01 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -6,4 +6,4 @@ Sphinx==6.1.3
 docutils==0.19
 sphinxcontrib-programoutput==0.17
 sphinx_copybutton==0.5.2
-furo==2023.3.27
+furo==2023.5.20

From c99417ffe8aa51015f08a96220072fa0dbcce51d Mon Sep 17 00:00:00 2001
From: Deepyaman Datta <deepyaman.datta@utexas.edu>
Date: Wed, 24 May 2023 22:52:59 -0400
Subject: [PATCH 0759/1034] Change example from `%%writeline` to `%%writefile`
 (#3673)

---
 docs/faq.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/faq.md b/docs/faq.md
index a6a422c2fec..8941ca3fe4d 100644
--- a/docs/faq.md
+++ b/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

From f95b43d6fa9883a87574f1d69d0a433422c19377 Mon Sep 17 00:00:00 2001
From: Stefaan Lippens <soxofaan@users.noreply.github.com>
Date: Thu, 25 May 2023 04:53:27 +0200
Subject: [PATCH 0760/1034] docs: update note on GitHub .git-blame-ignore-revs
 support (#3655)

---
 docs/guides/introducing_black_to_your_project.md | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/docs/guides/introducing_black_to_your_project.md b/docs/guides/introducing_black_to_your_project.md
index 9ae40a1928e..53bb0d9fcd6 100644
--- a/docs/guides/introducing_black_to_your_project.md
+++ b/docs/guides/introducing_black_to_your_project.md
@@ -46,7 +46,5 @@ $ 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.

From 3decbd6db9f120e8d7c8fa86b5b2f64f7861da0c Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Wed, 24 May 2023 19:55:12 -0700
Subject: [PATCH 0761/1034] Document each configuration option in more detail
 (#2839)

---
 docs/the_black_code_style/current_style.md |   8 +
 docs/the_black_code_style/future_style.md  |   2 +
 docs/usage_and_configuration/the_basics.md | 270 ++++++++++++++++-----
 scripts/check_version_in_basics_example.py |  17 +-
 4 files changed, 230 insertions(+), 67 deletions(-)

diff --git a/docs/the_black_code_style/current_style.md b/docs/the_black_code_style/current_style.md
index 83f8785cc55..e2625f9e16e 100644
--- a/docs/the_black_code_style/current_style.md
+++ b/docs/the_black_code_style/current_style.md
@@ -140,6 +140,8 @@ If you're reaching for backslashes, that's a clear signal that you can do better
 slightly refactor your code. I hope some of the examples above show you that there are
 many ways in which you can do it.
 
+(labels/line-length)=
+
 ### Line length
 
 You probably noticed the peculiar default line length. _Black_ defaults to 88 characters
@@ -273,6 +275,8 @@ A pre-existing trailing comma informs _Black_ to always explode contents of the
 bracket pair into one item per line. Read more about this in the
 [Pragmatism](#pragmatism) section below.
 
+(labels/strings)=
+
 ### Strings
 
 _Black_ prefers double quotes (`"` and `"""`) over single quotes (`'` and `'''`). It
@@ -457,6 +461,8 @@ there were not many users anyway. Not many edge cases were reported. As a mature
 _Black_ does make some exceptions to rules it otherwise holds. This section documents
 what those exceptions are and why this is the case.
 
+(labels/magic-trailing-comma)=
+
 ### The magic trailing comma
 
 _Black_ in general does not take existing formatting into account.
@@ -493,6 +499,8 @@ default by (among others) GitHub and Visual Studio Code, differentiates between
 r-strings and R-strings. The former are syntax highlighted as regular expressions while
 the latter are treated as true raw strings with no special semantics.
 
+(labels/ast-changes)=
+
 ### AST before and after formatting
 
 When run with `--safe` (the default), _Black_ checks that the code before and after is
diff --git a/docs/the_black_code_style/future_style.md b/docs/the_black_code_style/future_style.md
index bfab905b288..861bb64bff4 100644
--- a/docs/the_black_code_style/future_style.md
+++ b/docs/the_black_code_style/future_style.md
@@ -47,6 +47,8 @@ with contextlib.ExitStack() as exit_stack:
     ...
 ```
 
+(labels/preview-style)=
+
 ## Preview style
 
 Experimental, potentially disruptive style changes are gathered under the `--preview`
diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index b101e179d0e..48619c6bbe8 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -26,62 +26,106 @@ python -m black {source_file_or_directory}
 
 ### Command line options
 
-The CLI options of _Black_ can be displayed by expanding the view below or by running
-`black --help`. While _Black_ has quite a few knobs these days, it is still opinionated
-so style options are deliberately limited and rarely added.
+The CLI options of _Black_ can be displayed by running `black --help`. All options are
+also covered in more detail below.
 
-<details>
+While _Black_ has quite a few knobs these days, it is still opinionated so style options
+are deliberately limited and rarely added.
 
-<summary>CLI reference</summary>
+Note that all command-line options listed above can also be configured using a
+`pyproject.toml` file (more on that below).
 
-```{program-output} black --help
+#### `-c`, `--code`
 
+Format the code passed in as a string.
+
+```console
+$ black --code "print ( 'hello, world' )"
+print("hello, world")
 ```
 
-</details>
+#### `-l`, `--line-length`
 
-Note that all command-line options listed above can also be configured using a
-`pyproject.toml` file (more on that below).
+How many characters per line to allow. The default is 88.
 
-### Code input alternatives
+See also [the style documentation](labels/line-length).
 
-#### Standard Input
+#### `-t`, `--target-version`
 
-_Black_ supports formatting code via stdin, with the result being printed to stdout.
-Just let _Black_ know with `-` as the path.
+Python versions that should be supported by Black's output. You should include all
+versions that your code supports. If you support Python 3.7 through 3.10, you should
+write:
 
 ```console
-$ echo "print ( 'hello, world' )" | black -
-print("hello, world")
-reformatted -
-All done! ✨ 🍰 ✨
-1 file reformatted.
+$ black -t py37 -t py38 -t py39 -t py310
 ```
 
-**Tip:** if you need _Black_ to treat stdin input as a file passed directly via the CLI,
-use `--stdin-filename`. Useful to make sure _Black_ will respect the `--force-exclude`
-option on some editors that rely on using stdin.
+In a [configuration file](#configuration-via-a-file), you can write:
 
-#### As a string
+```toml
+target-versions = ["py37", "py38", "py39", "py310"]
+```
 
-You can also pass code as a string using the `-c` / `--code` option.
+_Black_ uses this option to decide what grammar to use to parse your code. In addition,
+it may use it to decide what style to use. For example, support for a trailing comma
+after `*args` in a function call was added in Python 3.5, so _Black_ will add this comma
+only if the target versions are all Python 3.5 or higher:
 
 ```console
-$ black --code "print ( 'hello, world' )"
-print("hello, world")
+$ black --line-length=10 --target-version=py35 -c 'f(a, *args)'
+f(
+    a,
+    *args,
+)
+$ black --line-length=10 --target-version=py34 -c 'f(a, *args)'
+f(
+    a,
+    *args
+)
+$ black --line-length=10 --target-version=py34 --target-version=py35 -c 'f(a, *args)'
+f(
+    a,
+    *args
+)
 ```
 
-### Writeback and reporting
+#### `--pyi`
 
-By default _Black_ reformats the files given and/or found in place. Sometimes you need
-_Black_ to just tell you what it _would_ do without actually rewriting the Python files.
+Format all input files like typing stubs regardless of file extension. This is useful
+when piping source on standard input.
 
-There's two variations to this mode that are independently enabled by their respective
-flags. Both variations can be enabled at once.
+#### `--ipynb`
+
+Format all input files like Jupyter Notebooks regardless of file extension. This is
+useful when piping source on standard input.
+
+#### `--python-cell-magics`
+
+When processing Jupyter Notebooks, add the given magic to the list of known python-
+magics. Useful for formatting cells with custom python magics.
+
+#### `-S, --skip-string-normalization`
+
+By default, _Black_ uses double quotes for all strings and normalizes string prefixes,
+as described in [the style documentation](labels/strings). If this option is given,
+strings are left unchanged instead.
+
+#### `-C, --skip-magic-trailing-comma`
+
+By default, _Black_ uses existing trailing commas as an indication that short lines
+should be left separate, as described in
+[the style documentation](labels/magic-trailing-comma). If this option is given, the
+magic trailing comma is ignored.
+
+#### `--preview`
+
+Enable potentially disruptive style changes that may be added to Black's main
+functionality in the next major release. Read more about
+[our preview style](labels/preview-style).
 
 (labels/exit-code)=
 
-#### Exit code
+#### `--check`
 
 Passing `--check` will make _Black_ exit with:
 
@@ -111,12 +155,12 @@ $ echo $?
 123
 ```
 
-#### Diffs
+#### `--diff`
 
 Passing `--diff` will make _Black_ print out diffs that indicate what changes _Black_
 would've made. They are printed to stdout so capturing them is simple.
 
-If you'd like colored diffs, you can enable them with the `--color`.
+If you'd like colored diffs, you can enable them with `--color`.
 
 ```console
 $ black test.py --diff
@@ -130,22 +174,92 @@ All done! ✨ 🍰 ✨
 1 file would be reformatted.
 ```
 
-### Output verbosity
+#### `--color` / `--no-color`
 
-_Black_ in general tries to produce the right amount of output, balancing between
-usefulness and conciseness. By default, _Black_ emits files modified and error messages,
-plus a short summary.
+Show (or do not show) colored diff. Only applies when `--diff` is given.
+
+#### `--fast` / `--safe`
+
+By default, _Black_ performs [an AST safety check](labels/ast-changes) after formatting
+your code. The `--fast` flag turns off this check and the `--safe` flag explicitly
+enables it.
+
+#### `--required-version`
+
+Require a specific version of _Black_ to be running. This is useful for ensuring that
+all contributors to your project are using the same version, because different versions
+of _Black_ may format code a little differently. This option can be set in a
+configuration file for consistent results across environments.
 
 ```console
-$ black src/
+$ black --version
+black, 23.3.0 (compiled: yes)
+$ black --required-version 23.3.0 -c "format = 'this'"
+format = "this"
+$ black --required-version 31.5b2 -c "still = 'beta?!'"
+Oh no! 💥 💔 💥 The required version does not match the running version!
+```
+
+You can also pass just the major version:
+
+```console
+$ black --required-version 22 -c "format = 'this'"
+format = "this"
+$ black --required-version 31 -c "still = 'beta?!'"
+Oh no! 💥 💔 💥 The required version does not match the running version!
+```
+
+Because of our [stability policy](../the_black_code_style/index.md), this will guarantee
+stable formatting, but still allow you to take advantage of improvements that do not
+affect formatting.
+
+#### `--include`
+
+A regular expression that matches files and directories that should be included on
+recursive searches. An empty value means all files are included regardless of the name.
+Use forward slashes for directories on all platforms (Windows, too). Exclusions are
+calculated first, inclusions later.
+
+#### `--exclude`
+
+A regular expression that matches files and directories that should be excluded on
+recursive searches. An empty value means no paths are excluded. Use forward slashes for
+directories on all platforms (Windows, too). Exclusions are calculated first, inclusions
+later.
+
+#### `--extend-exclude`
+
+Like `--exclude`, but adds additional files and directories on top of the excluded ones.
+Useful if you simply want to add to the default.
+
+#### `--force-exclude`
+
+Like `--exclude`, but files and directories matching this regex will be excluded even
+when they are passed explicitly as arguments. This is useful when invoking _Black_
+programmatically on changed files, such as in a pre-commit hook or editor plugin.
+
+#### `--stdin-filename`
+
+The name of the file when passing it through stdin. Useful to make sure Black will
+respect the `--force-exclude` option on some editors that rely on using stdin.
+
+#### `-W`, `--workers`
+
+When _Black_ formats multiple files, it may use a process pool to speed up formatting.
+This option controls the number of parallel workers.
+
+#### `-q`, `--quiet`
+
+Passing `-q` / `--quiet` will cause _Black_ to stop emitting all non-critical output.
+Error messages will still be emitted (which can silenced by `2>/dev/null`).
+
+```console
+$ black src/ -q
 error: cannot format src/black_primer/cli.py: Cannot parse: 5:6: mport asyncio
-reformatted src/black_primer/lib.py
-reformatted src/blackd/__init__.py
-reformatted src/black/__init__.py
-Oh no! 💥 💔 💥
-3 files reformatted, 2 files left unchanged, 1 file failed to reformat.
 ```
 
+#### `-v`, `--verbose`
+
 Passing `-v` / `--verbose` will cause _Black_ to also emit messages about files that
 were not changed or were ignored due to exclusion patterns. If _Black_ is using a
 configuration file, a blue message detailing which one it is using will be emitted.
@@ -164,35 +278,73 @@ Oh no! 💥 💔 💥
 3 files reformatted, 2 files left unchanged, 1 file failed to reformat
 ```
 
-Passing `-q` / `--quiet` will cause _Black_ to stop emitting all non-critial output.
-Error messages will still be emitted (which can silenced by `2>/dev/null`).
+#### `--version`
+
+You can check the version of _Black_ you have installed using the `--version` flag.
 
 ```console
-$ black src/ -q
-error: cannot format src/black_primer/cli.py: Cannot parse: 5:6: mport asyncio
+$ black --version
+black, 23.3.0
 ```
 
-### Versions
+#### `--config`
 
-You can check the version of _Black_ you have installed using the `--version` flag.
+Read configuration options from a configuration file. See
+[below](#configuration-via-a-file) for more details on the configuration file.
+
+#### `-h`, `--help`
+
+Show available command-line options and exit.
+
+### Code input alternatives
+
+_Black_ supports formatting code via stdin, with the result being printed to stdout.
+Just let _Black_ know with `-` as the path.
 
 ```console
-$ black --version
-black, version 23.3.0
+$ echo "print ( 'hello, world' )" | black -
+print("hello, world")
+reformatted -
+All done! ✨ 🍰 ✨
+1 file reformatted.
 ```
 
-An option to require a specific version to be running is also provided.
+**Tip:** if you need _Black_ to treat stdin input as a file passed directly via the CLI,
+use `--stdin-filename`. Useful to make sure _Black_ will respect the `--force-exclude`
+option on some editors that rely on using stdin.
+
+You can also pass code as a string using the `-c` / `--code` option.
+
+### Writeback and reporting
+
+By default _Black_ reformats the files given and/or found in place. Sometimes you need
+_Black_ to just tell you what it _would_ do without actually rewriting the Python files.
+
+There's two variations to this mode that are independently enabled by their respective
+flags:
+
+- `--check` (exit with code 1 if any file would be reformatted)
+- `--diff` (print a diff instead of reformatting files)
+
+Both variations can be enabled at once.
+
+### Output verbosity
+
+_Black_ in general tries to produce the right amount of output, balancing between
+usefulness and conciseness. By default, _Black_ emits files modified and error messages,
+plus a short summary.
 
 ```console
-$ black --required-version 21.9b0 -c "format = 'this'"
-format = "this"
-$ black --required-version 31.5b2 -c "still = 'beta?!'"
-Oh no! 💥 💔 💥 The required version does not match the running version!
+$ black src/
+error: cannot format src/black_primer/cli.py: Cannot parse: 5:6: mport asyncio
+reformatted src/black_primer/lib.py
+reformatted src/blackd/__init__.py
+reformatted src/black/__init__.py
+Oh no! 💥 💔 💥
+3 files reformatted, 2 files left unchanged, 1 file failed to reformat.
 ```
 
-This is useful for example when running _Black_ in multiple environments that haven't
-necessarily installed the correct version. This option can be set in a configuration
-file for consistent results across environments.
+The `--quiet` and `--verbose` flags control output verbosity.
 
 ## Configuration via a file
 
diff --git a/scripts/check_version_in_basics_example.py b/scripts/check_version_in_basics_example.py
index c62780d97ab..7f559b3aee1 100644
--- a/scripts/check_version_in_basics_example.py
+++ b/scripts/check_version_in_basics_example.py
@@ -20,20 +20,21 @@ def main(changes: str, the_basics: str) -> None:
 
     the_basics_html = commonmark.commonmark(the_basics)
     the_basics_soup = BeautifulSoup(the_basics_html, "html.parser")
-    (version_example,) = [
+    version_examples = [
         code_block.string
         for code_block in the_basics_soup.find_all(class_="language-console")
         if "$ black --version" in code_block.string
     ]
 
     for tag in tags:
-        if tag in version_example and tag != latest_tag:
-            print(
-                "Please set the version in the ``black --version`` "
-                "example from ``the_basics.md`` to be the latest one.\n"
-                f"Expected {latest_tag}, got {tag}.\n"
-            )
-            sys.exit(1)
+        for version_example in version_examples:
+            if tag in version_example and tag != latest_tag:
+                print(
+                    "Please set the version in the ``black --version`` "
+                    "examples from ``the_basics.md`` to be the latest one.\n"
+                    f"Expected {latest_tag}, got {tag}.\n"
+                )
+                sys.exit(1)
 
 
 if __name__ == "__main__":

From c42178690e96f3bf061ad44f70dec52b1d8a299a Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Wed, 24 May 2023 21:06:08 -0700
Subject: [PATCH 0762/1034] Fix docs formatting (#3704)

---
 docs/guides/introducing_black_to_your_project.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/docs/guides/introducing_black_to_your_project.md b/docs/guides/introducing_black_to_your_project.md
index 53bb0d9fcd6..71a566fbda1 100644
--- a/docs/guides/introducing_black_to_your_project.md
+++ b/docs/guides/introducing_black_to_your_project.md
@@ -46,5 +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)). 
-[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.
+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.

From a4032dce645b83e1faccc7274864869ddfe279fc Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 29 May 2023 06:33:41 -0700
Subject: [PATCH 0763/1034] Bump pypa/cibuildwheel from 2.12.3 to 2.13.0
 (#3710)

Bumps [pypa/cibuildwheel](https://github.com/pypa/cibuildwheel) from 2.12.3 to 2.13.0.
- [Release notes](https://github.com/pypa/cibuildwheel/releases)
- [Changelog](https://github.com/pypa/cibuildwheel/blob/main/docs/changelog.md)
- [Commits](https://github.com/pypa/cibuildwheel/compare/v2.12.3...v2.13.0)

---
updated-dependencies:
- dependency-name: pypa/cibuildwheel
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/pypi_upload.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/pypi_upload.yml b/.github/workflows/pypi_upload.yml
index 4b59c481bb0..20787f71cee 100644
--- a/.github/workflows/pypi_upload.yml
+++ b/.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.0
         env:
           CIBW_ARCHS_MACOS: "${{ matrix.macos_arch }}"
 

From a538ab76636bbe71b7fbfeaf56fd8e61805df38f Mon Sep 17 00:00:00 2001
From: jmcb <joelsgp@protonmail.com>
Date: Wed, 31 May 2023 22:29:31 +0100
Subject: [PATCH 0764/1034] blackd: show default values for options (#3712)

* blackd: show default values for options

Reference: https://click.palletsprojects.com/en/8.1.x/api/#click.Option

* Fix spacing in CHANGES.md
---
 CHANGES.md             |  3 +++
 src/blackd/__init__.py | 10 ++++++++--
 2 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 6a9923f8d8d..762a799a1d1 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -44,6 +44,9 @@
 
 <!-- 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 -->
diff --git a/src/blackd/__init__.py b/src/blackd/__init__.py
index ba4750b8298..d331ad000bc 100644
--- a/src/blackd/__init__.py
+++ b/src/blackd/__init__.py
@@ -59,9 +59,15 @@ class InvalidVariantHeader(Exception):
 
 @click.command(context_settings={"help_option_names": ["-h", "--help"]})
 @click.option(
-    "--bind-host", type=str, help="Address to bind the server to.", default="localhost"
+    "--bind-host",
+    type=str,
+    help="Address to bind the server to.",
+    default="localhost",
+    show_default=True,
+)
+@click.option(
+    "--bind-port", type=int, help="Port to listen on", default=45484, show_default=True
 )
-@click.option("--bind-port", type=int, help="Port to listen on", default=45484)
 @click.version_option(version=black.__version__)
 def main(bind_host: str, bind_port: int) -> None:
     logging.basicConfig(level=logging.INFO)

From 3aad6e385bfbd4348b2e13695cb6741806951160 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Thu, 1 Jun 2023 18:37:08 -0700
Subject: [PATCH 0765/1034] Add support for PEP 695 syntax (#3703)

---
 CHANGES.md                        |  2 ++
 pyproject.toml                    |  2 ++
 src/black/__init__.py             |  3 ++
 src/black/linegen.py              | 12 +++++++
 src/black/mode.py                 | 21 ++++++++++++
 src/blib2to3/Grammar.txt          | 13 +++++--
 src/blib2to3/pygram.py            |  6 ++++
 tests/data/py_312/type_aliases.py | 13 +++++++
 tests/data/py_312/type_params.py  | 57 +++++++++++++++++++++++++++++++
 tests/test_black.py               | 30 +++++++++++++---
 tests/test_format.py              |  7 ++++
 11 files changed, 159 insertions(+), 7 deletions(-)
 create mode 100644 tests/data/py_312/type_aliases.py
 create mode 100644 tests/data/py_312/type_params.py

diff --git a/CHANGES.md b/CHANGES.md
index 762a799a1d1..fb3dea8c348 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -32,6 +32,8 @@
 
 <!-- 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. -->
diff --git a/pyproject.toml b/pyproject.toml
index 435626ac8f4..6803a627e9a 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -214,4 +214,6 @@ filterwarnings = [
     # aiohttp is using deprecated cgi modules - Safe to remove when fixed:
     # https://github.com/aio-libs/aiohttp/issues/6905
     '''ignore:'cgi' is deprecated and slated for removal in Python 3.13:DeprecationWarning''',
+    # Work around https://github.com/pytest-dev/pytest/issues/10977 for Python 3.12
+    '''ignore:(Attribute s|Attribute n|ast.Str|ast.Bytes|ast.NameConstant|ast.Num) is deprecated and will be removed in Python 3.14:DeprecationWarning'''
 ]
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 871e9a0d7c8..8a759aa493a 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -1275,6 +1275,9 @@ def get_features_used(  # noqa: C901
         ):
             features.add(Feature.VARIADIC_GENERICS)
 
+        elif n.type in (syms.type_stmt, syms.typeparams):
+            features.add(Feature.TYPE_PARAMS)
+
     return features
 
 
diff --git a/src/black/linegen.py b/src/black/linegen.py
index b6b83da26f7..0091cbb3bd1 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -215,6 +215,18 @@ def visit_stmt(
 
             yield from self.visit(child)
 
+    def visit_typeparams(self, node: Node) -> Iterator[Line]:
+        yield from self.visit_default(node)
+        node.children[0].prefix = ""
+
+    def visit_typevartuple(self, node: Node) -> Iterator[Line]:
+        yield from self.visit_default(node)
+        node.children[1].prefix = ""
+
+    def visit_paramspec(self, node: Node) -> Iterator[Line]:
+        yield from self.visit_default(node)
+        node.children[1].prefix = ""
+
     def visit_dictsetmaker(self, node: Node) -> Iterator[Line]:
         if Preview.wrap_long_dict_values_in_parens in self.mode:
             for i, child in enumerate(node.children):
diff --git a/src/black/mode.py b/src/black/mode.py
index a5841edb30a..1091494afac 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -30,6 +30,7 @@ class TargetVersion(Enum):
     PY39 = 9
     PY310 = 10
     PY311 = 11
+    PY312 = 12
 
 
 class Feature(Enum):
@@ -51,6 +52,7 @@ class Feature(Enum):
     VARIADIC_GENERICS = 15
     DEBUG_F_STRINGS = 16
     PARENTHESIZED_CONTEXT_MANAGERS = 17
+    TYPE_PARAMS = 18
     FORCE_OPTIONAL_PARENTHESES = 50
 
     # __future__ flags
@@ -143,6 +145,25 @@ class Feature(Enum):
         Feature.EXCEPT_STAR,
         Feature.VARIADIC_GENERICS,
     },
+    TargetVersion.PY312: {
+        Feature.F_STRINGS,
+        Feature.DEBUG_F_STRINGS,
+        Feature.NUMERIC_UNDERSCORES,
+        Feature.TRAILING_COMMA_IN_CALL,
+        Feature.TRAILING_COMMA_IN_DEF,
+        Feature.ASYNC_KEYWORDS,
+        Feature.FUTURE_ANNOTATIONS,
+        Feature.ASSIGNMENT_EXPRESSIONS,
+        Feature.RELAXED_DECORATORS,
+        Feature.POS_ONLY_ARGUMENTS,
+        Feature.UNPACKING_ON_FLOW,
+        Feature.ANN_ASSIGN_EXTENDED_RHS,
+        Feature.PARENTHESIZED_CONTEXT_MANAGERS,
+        Feature.PATTERN_MATCHING,
+        Feature.EXCEPT_STAR,
+        Feature.VARIADIC_GENERICS,
+        Feature.TYPE_PARAMS,
+    },
 }
 
 
diff --git a/src/blib2to3/Grammar.txt b/src/blib2to3/Grammar.txt
index bd8a452a386..e48e66363fb 100644
--- a/src/blib2to3/Grammar.txt
+++ b/src/blib2to3/Grammar.txt
@@ -12,11 +12,17 @@ file_input: (NEWLINE | stmt)* ENDMARKER
 single_input: NEWLINE | simple_stmt | compound_stmt NEWLINE
 eval_input: testlist NEWLINE* ENDMARKER
 
+typevar: NAME [':' expr]
+paramspec: '**' NAME
+typevartuple: '*' NAME
+typeparam: typevar | paramspec | typevartuple
+typeparams: '[' typeparam (',' typeparam)* [','] ']'
+
 decorator: '@' namedexpr_test NEWLINE
 decorators: decorator+
 decorated: decorators (classdef | funcdef | async_funcdef)
 async_funcdef: ASYNC funcdef
-funcdef: 'def' NAME parameters ['->' test] ':' suite
+funcdef: 'def' NAME [typeparams] parameters ['->' test] ':' suite
 parameters: '(' [typedargslist] ')'
 
 # The following definition for typedarglist is equivalent to this set of rules:
@@ -74,7 +80,7 @@ vfplist: vfpdef (',' vfpdef)* [',']
 
 stmt: simple_stmt | compound_stmt
 simple_stmt: small_stmt (';' small_stmt)* [';'] NEWLINE
-small_stmt: (expr_stmt | print_stmt  | del_stmt | pass_stmt | flow_stmt |
+small_stmt: (type_stmt | expr_stmt | print_stmt  | del_stmt | pass_stmt | flow_stmt |
              import_stmt | global_stmt | exec_stmt | assert_stmt)
 expr_stmt: testlist_star_expr (annassign | augassign (yield_expr|testlist) |
                      ('=' (yield_expr|testlist_star_expr))*)
@@ -105,6 +111,7 @@ dotted_name: NAME ('.' NAME)*
 global_stmt: ('global' | 'nonlocal') NAME (',' NAME)*
 exec_stmt: 'exec' expr ['in' test [',' test]]
 assert_stmt: 'assert' test [',' test]
+type_stmt: "type" NAME [typeparams] '=' expr
 
 compound_stmt: if_stmt | while_stmt | for_stmt | try_stmt | with_stmt | funcdef | classdef | decorated | async_stmt | match_stmt
 async_stmt: ASYNC (funcdef | with_stmt | for_stmt)
@@ -174,7 +181,7 @@ dictsetmaker: ( ((test ':' asexpr_test | '**' expr)
                 ((test [':=' test] | star_expr)
 		 (comp_for | (',' (test [':=' test] | star_expr))* [','])) )
 
-classdef: 'class' NAME ['(' [arglist] ')'] ':' suite
+classdef: 'class' NAME [typeparams] ['(' [arglist] ')'] ':' suite
 
 arglist: argument (',' argument)* [',']
 
diff --git a/src/blib2to3/pygram.py b/src/blib2to3/pygram.py
index 99012cdd9cb..15702e4059e 100644
--- a/src/blib2to3/pygram.py
+++ b/src/blib2to3/pygram.py
@@ -95,6 +95,7 @@ class _python_symbols(Symbols):
     old_test: int
     or_test: int
     parameters: int
+    paramspec: int
     pass_stmt: int
     pattern: int
     patterns: int
@@ -126,7 +127,12 @@ class _python_symbols(Symbols):
     tname_star: int
     trailer: int
     try_stmt: int
+    type_stmt: int
     typedargslist: int
+    typeparam: int
+    typeparams: int
+    typevar: int
+    typevartuple: int
     varargslist: int
     vfpdef: int
     vfplist: int
diff --git a/tests/data/py_312/type_aliases.py b/tests/data/py_312/type_aliases.py
new file mode 100644
index 00000000000..84e07e50fe2
--- /dev/null
+++ b/tests/data/py_312/type_aliases.py
@@ -0,0 +1,13 @@
+type A=int
+type Gen[T]=list[T]
+
+type = aliased
+print(type(42))
+
+# output
+
+type A = int
+type Gen[T] = list[T]
+
+type = aliased
+print(type(42))
diff --git a/tests/data/py_312/type_params.py b/tests/data/py_312/type_params.py
new file mode 100644
index 00000000000..5f8ec43267c
--- /dev/null
+++ b/tests/data/py_312/type_params.py
@@ -0,0 +1,57 @@
+def func  [T ](): pass
+async def func [ T ] (): pass
+class C[ T ] : pass
+
+def all_in[T   :   int,U : (bytes, str),*   Ts,**P](): pass
+
+def really_long[WhatIsTheLongestTypeVarNameYouCanThinkOfEnoughToMakeBlackSplitThisLine](): pass
+
+def even_longer[WhatIsTheLongestTypeVarNameYouCanThinkOfEnoughToMakeBlackSplitThisLine: WhatIfItHadABound](): pass
+
+def it_gets_worse[WhatIsTheLongestTypeVarNameYouCanThinkOfEnoughToMakeBlackSplitThisLine, ItCouldBeGenericOverMultipleTypeVars](): pass
+
+def magic[Trailing, Comma,](): pass
+
+# output
+
+
+def func[T]():
+    pass
+
+
+async def func[T]():
+    pass
+
+
+class C[T]:
+    pass
+
+
+def all_in[T: int, U: (bytes, str), *Ts, **P]():
+    pass
+
+
+def really_long[
+    WhatIsTheLongestTypeVarNameYouCanThinkOfEnoughToMakeBlackSplitThisLine
+]():
+    pass
+
+
+def even_longer[
+    WhatIsTheLongestTypeVarNameYouCanThinkOfEnoughToMakeBlackSplitThisLine: WhatIfItHadABound
+]():
+    pass
+
+
+def it_gets_worse[
+    WhatIsTheLongestTypeVarNameYouCanThinkOfEnoughToMakeBlackSplitThisLine,
+    ItCouldBeGenericOverMultipleTypeVars,
+]():
+    pass
+
+
+def magic[
+    Trailing,
+    Comma,
+]():
+    pass
diff --git a/tests/test_black.py b/tests/test_black.py
index 00de5b745e7..42b0161d156 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -271,6 +271,15 @@ def test_pep_572_version_detection(self) -> None:
         versions = black.detect_target_versions(root)
         self.assertIn(black.TargetVersion.PY38, versions)
 
+    def test_pep_695_version_detection(self) -> None:
+        for file in ("type_aliases", "type_params"):
+            source, _ = read_data("py_312", file)
+            root = black.lib2to3_parse(source)
+            features = black.get_features_used(root)
+            self.assertIn(black.Feature.TYPE_PARAMS, features)
+            versions = black.detect_target_versions(root)
+            self.assertIn(black.TargetVersion.PY312, versions)
+
     def test_expression_ff(self) -> None:
         source, expected = read_data("simple_cases", "expression.py")
         tmp_file = Path(black.dump_to_file(source))
@@ -1533,14 +1542,25 @@ def test_infer_target_version(self) -> None:
         for version, expected in [
             ("3.6", [TargetVersion.PY36]),
             ("3.11.0rc1", [TargetVersion.PY311]),
-            (">=3.10", [TargetVersion.PY310, TargetVersion.PY311]),
-            (">=3.10.6", [TargetVersion.PY310, TargetVersion.PY311]),
+            (">=3.10", [TargetVersion.PY310, TargetVersion.PY311, TargetVersion.PY312]),
+            (
+                ">=3.10.6",
+                [TargetVersion.PY310, TargetVersion.PY311, TargetVersion.PY312],
+            ),
             ("<3.6", [TargetVersion.PY33, TargetVersion.PY34, TargetVersion.PY35]),
             (">3.7,<3.10", [TargetVersion.PY38, TargetVersion.PY39]),
-            (">3.7,!=3.8,!=3.9", [TargetVersion.PY310, TargetVersion.PY311]),
+            (
+                ">3.7,!=3.8,!=3.9",
+                [TargetVersion.PY310, TargetVersion.PY311, TargetVersion.PY312],
+            ),
             (
                 "> 3.9.4, != 3.10.3",
-                [TargetVersion.PY39, TargetVersion.PY310, TargetVersion.PY311],
+                [
+                    TargetVersion.PY39,
+                    TargetVersion.PY310,
+                    TargetVersion.PY311,
+                    TargetVersion.PY312,
+                ],
             ),
             (
                 "!=3.3,!=3.4",
@@ -1552,6 +1572,7 @@ def test_infer_target_version(self) -> None:
                     TargetVersion.PY39,
                     TargetVersion.PY310,
                     TargetVersion.PY311,
+                    TargetVersion.PY312,
                 ],
             ),
             (
@@ -1566,6 +1587,7 @@ def test_infer_target_version(self) -> None:
                     TargetVersion.PY39,
                     TargetVersion.PY310,
                     TargetVersion.PY311,
+                    TargetVersion.PY312,
                 ],
             ),
             ("==3.8.*", [TargetVersion.PY38]),
diff --git a/tests/test_format.py b/tests/test_format.py
index 5a7b3bb6762..8e0ada99cba 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -134,6 +134,13 @@ def test_python_311(filename: str) -> None:
     assert_format(source, expected, mode, minimum_version=(3, 11))
 
 
+@pytest.mark.parametrize("filename", all_data_cases("py_312"))
+def test_python_312(filename: str) -> None:
+    source, expected = read_data("py_312", filename)
+    mode = black.Mode(target_versions={black.TargetVersion.PY312})
+    assert_format(source, expected, mode, minimum_version=(3, 12))
+
+
 @pytest.mark.parametrize("filename", all_data_cases("fast"))
 def test_fast_cases(filename: str) -> None:
     source, expected = read_data("fast", filename)

From 898915d5569f503c278ef53cb6f10e003034943c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ville=20Skytt=C3=A4?= <ville.skytta@iki.fi>
Date: Sat, 10 Jun 2023 19:54:21 +0300
Subject: [PATCH 0766/1034] Use aware datetimes to represent UTC (#3728)

Avoids a Python 3.12 deprecation warning.

Subtle difference: previously, timestamps in diff filenames had the
`+0000` separated from the timestamp by space. With this, the space is
there no more, and there is a colon, as in `+00:00`.
---
 CHANGES.md                                 |  2 ++
 docs/usage_and_configuration/the_basics.md |  4 ++--
 src/black/__init__.py                      | 18 +++++++++---------
 src/blackd/__init__.py                     | 10 +++++-----
 tests/test_black.py                        | 10 +++++-----
 tests/test_blackd.py                       |  2 +-
 6 files changed, 24 insertions(+), 22 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index fb3dea8c348..658faad3a78 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -42,6 +42,8 @@
 
 <!-- Changes to Black's terminal output and error messages -->
 
+- Use aware UTC datetimes internally, avoids deprecation warning on Python 3.12 (#3728)
+
 ### _Blackd_
 
 <!-- Changes to blackd -->
diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index 48619c6bbe8..6f3a3cff30c 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -164,8 +164,8 @@ If you'd like colored diffs, you can enable them with `--color`.
 
 ```console
 $ black test.py --diff
---- test.py     2021-03-08 22:23:40.848954 +0000
-+++ test.py     2021-03-08 22:23:47.126319 +0000
+--- test.py     2021-03-08 22:23:40.848954+00:00
++++ test.py     2021-03-08 22:23:47.126319+00:00
 @@ -1 +1 @@
 -print ( 'hello, world' )
 +print("hello, world")
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 8a759aa493a..dbcb559f09d 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -7,7 +7,7 @@
 import traceback
 from contextlib import contextmanager
 from dataclasses import replace
-from datetime import datetime
+from datetime import datetime, timezone
 from enum import Enum
 from json.decoder import JSONDecodeError
 from pathlib import Path
@@ -807,7 +807,7 @@ def format_file_in_place(
     elif src.suffix == ".ipynb":
         mode = replace(mode, is_ipynb=True)
 
-    then = datetime.utcfromtimestamp(src.stat().st_mtime)
+    then = datetime.fromtimestamp(src.stat().st_mtime, timezone.utc)
     header = b""
     with open(src, "rb") as buf:
         if mode.skip_source_first_line:
@@ -828,9 +828,9 @@ def format_file_in_place(
         with open(src, "w", encoding=encoding, newline=newline) as f:
             f.write(dst_contents)
     elif write_back in (WriteBack.DIFF, WriteBack.COLOR_DIFF):
-        now = datetime.utcnow()
-        src_name = f"{src}\t{then} +0000"
-        dst_name = f"{src}\t{now} +0000"
+        now = datetime.now(timezone.utc)
+        src_name = f"{src}\t{then}"
+        dst_name = f"{src}\t{now}"
         if mode.is_ipynb:
             diff_contents = ipynb_diff(src_contents, dst_contents, src_name, dst_name)
         else:
@@ -868,7 +868,7 @@ def format_stdin_to_stdout(
     write a diff to stdout. The `mode` argument is passed to
     :func:`format_file_contents`.
     """
-    then = datetime.utcnow()
+    then = datetime.now(timezone.utc)
 
     if content is None:
         src, encoding, newline = decode_bytes(sys.stdin.buffer.read())
@@ -893,9 +893,9 @@ def format_stdin_to_stdout(
                 dst += "\n"
             f.write(dst)
         elif write_back in (WriteBack.DIFF, WriteBack.COLOR_DIFF):
-            now = datetime.utcnow()
-            src_name = f"STDIN\t{then} +0000"
-            dst_name = f"STDOUT\t{now} +0000"
+            now = datetime.now(timezone.utc)
+            src_name = f"STDIN\t{then}"
+            dst_name = f"STDOUT\t{now}"
             d = diff(src, dst, src_name, dst_name)
             if write_back == WriteBack.COLOR_DIFF:
                 d = color_diff(d)
diff --git a/src/blackd/__init__.py b/src/blackd/__init__.py
index d331ad000bc..c1b69feed63 100644
--- a/src/blackd/__init__.py
+++ b/src/blackd/__init__.py
@@ -1,7 +1,7 @@
 import asyncio
 import logging
 from concurrent.futures import Executor, ProcessPoolExecutor
-from datetime import datetime
+from datetime import datetime, timezone
 from functools import partial
 from multiprocessing import freeze_support
 from typing import Set, Tuple
@@ -138,7 +138,7 @@ async def handle(request: web.Request, executor: Executor) -> web.Response:
         req_bytes = await request.content.read()
         charset = request.charset if request.charset is not None else "utf8"
         req_str = req_bytes.decode(charset)
-        then = datetime.utcnow()
+        then = datetime.now(timezone.utc)
 
         header = ""
         if skip_source_first_line:
@@ -165,9 +165,9 @@ async def handle(request: web.Request, executor: Executor) -> web.Response:
         # Only output the diff in the HTTP response
         only_diff = bool(request.headers.get(DIFF_HEADER, False))
         if only_diff:
-            now = datetime.utcnow()
-            src_name = f"In\t{then} +0000"
-            dst_name = f"Out\t{now} +0000"
+            now = datetime.now(timezone.utc)
+            src_name = f"In\t{then}"
+            dst_name = f"Out\t{now}"
             loop = asyncio.get_event_loop()
             formatted_str = await loop.run_in_executor(
                 executor,
diff --git a/tests/test_black.py b/tests/test_black.py
index 42b0161d156..5f2e6f5b14c 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -207,8 +207,8 @@ def test_piping(self) -> None:
 
     def test_piping_diff(self) -> None:
         diff_header = re.compile(
-            r"(STDIN|STDOUT)\t\d\d\d\d-\d\d-\d\d \d\d:\d\d:\d\d\.\d\d\d\d\d\d "
-            r"\+\d\d\d\d"
+            r"(STDIN|STDOUT)\t\d\d\d\d-\d\d-\d\d \d\d:\d\d:\d\d\.\d\d\d\d\d\d"
+            r"\+\d\d:\d\d"
         )
         source, _ = read_data("simple_cases", "expression.py")
         expected, _ = read_data("simple_cases", "expression.diff")
@@ -300,7 +300,7 @@ def test_expression_diff(self) -> None:
         tmp_file = Path(black.dump_to_file(source))
         diff_header = re.compile(
             rf"{re.escape(str(tmp_file))}\t\d\d\d\d-\d\d-\d\d "
-            r"\d\d:\d\d:\d\d\.\d\d\d\d\d\d \+\d\d\d\d"
+            r"\d\d:\d\d:\d\d\.\d\d\d\d\d\d\+\d\d:\d\d"
         )
         try:
             result = BlackRunner().invoke(
@@ -411,7 +411,7 @@ def test_skip_magic_trailing_comma(self) -> None:
         tmp_file = Path(black.dump_to_file(source))
         diff_header = re.compile(
             rf"{re.escape(str(tmp_file))}\t\d\d\d\d-\d\d-\d\d "
-            r"\d\d:\d\d:\d\d\.\d\d\d\d\d\d \+\d\d\d\d"
+            r"\d\d:\d\d:\d\d\.\d\d\d\d\d\d\+\d\d:\d\d"
         )
         try:
             result = BlackRunner().invoke(
@@ -1750,7 +1750,7 @@ def test_bpo_2142_workaround(self) -> None:
         tmp_file = Path(black.dump_to_file(source, ensure_final_newline=False))
         diff_header = re.compile(
             rf"{re.escape(str(tmp_file))}\t\d\d\d\d-\d\d-\d\d "
-            r"\d\d:\d\d:\d\d\.\d\d\d\d\d\d \+\d\d\d\d"
+            r"\d\d:\d\d:\d\d\.\d\d\d\d\d\d\+\d\d:\d\d"
         )
         try:
             result = BlackRunner().invoke(black.main, ["--diff", str(tmp_file)])
diff --git a/tests/test_blackd.py b/tests/test_blackd.py
index 5b6461f7685..325bd7dd5aa 100644
--- a/tests/test_blackd.py
+++ b/tests/test_blackd.py
@@ -114,7 +114,7 @@ async def test_blackd_pyi(self) -> None:
     @unittest_run_loop
     async def test_blackd_diff(self) -> None:
         diff_header = re.compile(
-            r"(In|Out)\t\d\d\d\d-\d\d-\d\d \d\d:\d\d:\d\d\.\d\d\d\d\d\d \+\d\d\d\d"
+            r"(In|Out)\t\d\d\d\d-\d\d-\d\d \d\d:\d\d:\d\d\.\d\d\d\d\d\d\+\d\d:\d\d"
         )
 
         source, _ = read_data("miscellaneous", "blackd_diff")

From c76e0b03ec706619cc76bbd45e9c355c18462e2e Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 12 Jun 2023 10:05:49 -0700
Subject: [PATCH 0767/1034] Bump pypa/cibuildwheel from 2.13.0 to 2.13.1
 (#3729)

Bumps [pypa/cibuildwheel](https://github.com/pypa/cibuildwheel) from 2.13.0 to 2.13.1.
- [Release notes](https://github.com/pypa/cibuildwheel/releases)
- [Changelog](https://github.com/pypa/cibuildwheel/blob/main/docs/changelog.md)
- [Commits](https://github.com/pypa/cibuildwheel/compare/v2.13.0...v2.13.1)

---
updated-dependencies:
- dependency-name: pypa/cibuildwheel
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/pypi_upload.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/pypi_upload.yml b/.github/workflows/pypi_upload.yml
index 20787f71cee..06600fcbc45 100644
--- a/.github/workflows/pypi_upload.yml
+++ b/.github/workflows/pypi_upload.yml
@@ -58,7 +58,7 @@ jobs:
       - uses: actions/checkout@v3
 
       - name: Build wheels via cibuildwheel
-        uses: pypa/cibuildwheel@v2.13.0
+        uses: pypa/cibuildwheel@v2.13.1
         env:
           CIBW_ARCHS_MACOS: "${{ matrix.macos_arch }}"
 

From 688f78d380706fd20776b31eb1ead98ba3f45839 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 12 Jun 2023 10:08:45 -0700
Subject: [PATCH 0768/1034] Bump peter-evans/create-or-update-comment from
 3.0.1 to 3.0.2 (#3730)

Bumps [peter-evans/create-or-update-comment](https://github.com/peter-evans/create-or-update-comment) from 3.0.1 to 3.0.2.
- [Release notes](https://github.com/peter-evans/create-or-update-comment/releases)
- [Commits](https://github.com/peter-evans/create-or-update-comment/compare/ca08ebd5dc95aa0cd97021e9708fcd6b87138c9b...c6c9a1a66007646a28c153e2a8580a5bad27bcfa)

---
updated-dependencies:
- dependency-name: peter-evans/create-or-update-comment
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/diff_shades_comment.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/diff_shades_comment.yml b/.github/workflows/diff_shades_comment.yml
index 95dd9b01dba..22c293f91d2 100644
--- a/.github/workflows/diff_shades_comment.yml
+++ b/.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 }}

From 35722dff623f3cdf5018e3f1183cd4e02e91caa8 Mon Sep 17 00:00:00 2001
From: Alwyn Kik <alwyn@kik.pw>
Date: Mon, 12 Jun 2023 21:20:31 +0200
Subject: [PATCH 0769/1034] Max line length with bugbear (#3731)

* Make phrasing for flake8 users more concise

max-line-length should be 80 with flake8-bugbear
Fixes #3716

* Re-add rationale and an explanation for

disabling E203

* Run pre-commit
---
 docs/the_black_code_style/current_style.md | 50 +++++++++++-----------
 1 file changed, 26 insertions(+), 24 deletions(-)

diff --git a/docs/the_black_code_style/current_style.md b/docs/the_black_code_style/current_style.md
index e2625f9e16e..0fb59fe5aae 100644
--- a/docs/the_black_code_style/current_style.md
+++ b/docs/the_black_code_style/current_style.md
@@ -160,33 +160,35 @@ harder to work with line lengths exceeding 100 characters. It also adversely aff
 side-by-side diff review on typical screen resolutions. Long lines also make it harder
 to present code neatly in documentation or talk slides.
 
-If you're using Flake8, you can bump `max-line-length` to 88 and mostly forget about it.
-However, it's better if you use [Bugbear](https://github.com/PyCQA/flake8-bugbear)'s
-B950 warning instead of E501, and bump the max line length to 88 (or the `--line-length`
-you used for black), which will align more with black's _"try to respect
-`--line-length`, but don't become crazy if you can't"_. You'd do it like this:
-
-```ini
-[flake8]
-max-line-length = 88
-...
-select = C,E,F,W,B,B950
-extend-ignore = E203, E501
-```
+#### Flake8
 
-Explanation of why E203 is disabled can be found further in this documentation. And if
-you're curious about the reasoning behind B950,
-[Bugbear's documentation](https://github.com/PyCQA/flake8-bugbear#opinionated-warnings)
-explains it. The tl;dr is "it's like highway speed limits, we won't bother you if you
-overdo it by a few km/h".
+If you use Flake8, you have a few options:
 
-**If you're looking for a minimal, black-compatible flake8 configuration:**
+1. Recommended is using [Bugbear](https://github.com/PyCQA/flake8-bugbear) and enabling
+   its B950 check instead of using Flake8's E501, because it aligns with Black's 10%
+   rule. Install Bugbear and use the following config:
 
-```ini
-[flake8]
-max-line-length = 88
-extend-ignore = E203
-```
+   ```ini
+   [flake8]
+   max-line-length = 80
+   ...
+   select = C,E,F,W,B,B950
+   extend-ignore = E203, E501
+   ```
+
+   The rationale for E950 is explained in
+   [Bugbear's documentation](https://github.com/PyCQA/flake8-bugbear#opinionated-warnings).
+
+2. For a minimally compatible config:
+
+   ```ini
+   [flake8]
+   max-line-length = 88
+   extend-ignore = E203
+   ```
+
+An explanation of why E203 is disabled can be found in the [Slices section](#slices) of
+this page.
 
 ### Empty lines
 

From 01b8d3d4095ebdb91d0d39012a517931625c63cb Mon Sep 17 00:00:00 2001
From: "Yilei \"Dolee\" Yang" <yileiyang@google.com>
Date: Thu, 15 Jun 2023 17:08:26 -0700
Subject: [PATCH 0770/1034] Do not add trailing commas to return type
 annotations using PEP 604 unions (#3735)

Fix #3638: Do not add trailing commas to return type annotations using PEP 604 unions.
---
 CHANGES.md                         |  3 +++
 src/black/linegen.py               |  7 +++++++
 tests/data/simple_cases/pep_604.py | 25 +++++++++++++++++++++++++
 3 files changed, 35 insertions(+)
 create mode 100644 tests/data/simple_cases/pep_604.py

diff --git a/CHANGES.md b/CHANGES.md
index 658faad3a78..fd4d911287d 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -10,6 +10,9 @@
 
 <!-- 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)
+
 ### Preview style
 
 <!-- Changes that affect Black's preview style -->
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 0091cbb3bd1..ad21307c311 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -918,6 +918,13 @@ def bracket_split_build_line(
                     )
                     if isinstance(node, Node) and isinstance(node.prev_sibling, Leaf)
                 )
+                # Except the false negatives above for PEP 604 unions where we
+                # can't add the comma.
+                and not (
+                    leaves[0].parent
+                    and leaves[0].parent.next_sibling
+                    and leaves[0].parent.next_sibling.type == token.VBAR
+                )
             )
 
             if original.is_import or no_commas:
diff --git a/tests/data/simple_cases/pep_604.py b/tests/data/simple_cases/pep_604.py
new file mode 100644
index 00000000000..b68d59d6440
--- /dev/null
+++ b/tests/data/simple_cases/pep_604.py
@@ -0,0 +1,25 @@
+def some_very_long_name_function() -> my_module.Asdf | my_module.AnotherType | my_module.YetAnotherType | None:
+    pass
+
+
+def some_very_long_name_function() -> my_module.Asdf | my_module.AnotherType | my_module.YetAnotherType | my_module.EvenMoreType | None:
+    pass
+
+
+# output
+
+
+def some_very_long_name_function() -> (
+    my_module.Asdf | my_module.AnotherType | my_module.YetAnotherType | None
+):
+    pass
+
+
+def some_very_long_name_function() -> (
+    my_module.Asdf
+    | my_module.AnotherType
+    | my_module.YetAnotherType
+    | my_module.EvenMoreType
+    | None
+):
+    pass

From e7783e9ab27e95cd9b50c2ef84174f4e1c9d60cd Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 19 Jun 2023 06:58:20 -0700
Subject: [PATCH 0771/1034] Bump myst-parser from 1.0.0 to 2.0.0 in /docs
 (#3738)

Bumps [myst-parser](https://github.com/executablebooks/MyST-Parser) from 1.0.0 to 2.0.0.
- [Release notes](https://github.com/executablebooks/MyST-Parser/releases)
- [Changelog](https://github.com/executablebooks/MyST-Parser/blob/master/CHANGELOG.md)
- [Commits](https://github.com/executablebooks/MyST-Parser/compare/v1.0.0...v2.0.0)

---
updated-dependencies:
- dependency-name: myst-parser
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 docs/requirements.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index 7b26d089b01..f1b47c69413 100644
--- a/docs/requirements.txt
+++ b/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==6.1.3
 # Older versions break Sphinx even though they're declared to be supported.
 docutils==0.19

From d1248ca9beaf0ba526d265f4108836d89cf551b7 Mon Sep 17 00:00:00 2001
From: rdrll <13176405+rdrll@users.noreply.github.com>
Date: Tue, 20 Jun 2023 07:06:03 -0700
Subject: [PATCH 0772/1034] Doc: updating url link (#3739)

---
 docs/contributing/index.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/contributing/index.md b/docs/contributing/index.md
index f56e57c9e90..3314c8eaa39 100644
--- a/docs/contributing/index.md
+++ b/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

From 453828d17d50e4bf8bdef972fa6815258e380034 Mon Sep 17 00:00:00 2001
From: Renan Santos <renan.engmec@gmail.com>
Date: Fri, 23 Jun 2023 01:21:49 -0300
Subject: [PATCH 0773/1034] Fix not honouring pyproject.toml when using stdin
 and calling black from parent directory (#3719)

Co-authored-by: Renan Rodrigues <renan.rodrigues@appliedbiomath.com>
---
 CHANGES.md            |  2 ++
 src/black/__init__.py |  5 ++++-
 src/black/files.py    |  6 ++++--
 tests/test_black.py   | 34 ++++++++++++++++++++++++++++++++++
 4 files changed, 44 insertions(+), 3 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index fd4d911287d..e1028c17681 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -26,6 +26,8 @@
 <!-- Changes to how Black can be configured -->
 
 - `.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
 
diff --git a/src/black/__init__.py b/src/black/__init__.py
index dbcb559f09d..60a339cdd12 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -127,7 +127,9 @@ def read_pyproject_toml(
     otherwise.
     """
     if not value:
-        value = find_pyproject_toml(ctx.params.get("src", ()))
+        value = find_pyproject_toml(
+            ctx.params.get("src", ()), ctx.params.get("stdin_filename", None)
+        )
         if value is None:
             return None
 
@@ -362,6 +364,7 @@ def validate_regex(
 @click.option(
     "--stdin-filename",
     type=str,
+    is_eager=True,
     help=(
         "The name of the file when passing it through stdin. Useful to make "
         "sure Black will respect --force-exclude option on some "
diff --git a/src/black/files.py b/src/black/files.py
index 8c0131126b7..65b2d0a8402 100644
--- a/src/black/files.py
+++ b/src/black/files.py
@@ -89,9 +89,11 @@ def find_project_root(
     return directory, "file system root"
 
 
-def find_pyproject_toml(path_search_start: Tuple[str, ...]) -> Optional[str]:
+def find_pyproject_toml(
+    path_search_start: Tuple[str, ...], stdin_filename: Optional[str] = None
+) -> Optional[str]:
     """Find the absolute filepath to a pyproject.toml if it exists"""
-    path_project_root, _ = find_project_root(path_search_start)
+    path_project_root, _ = find_project_root(path_search_start, stdin_filename)
     path_pyproject_toml = path_project_root / "pyproject.toml"
     if path_pyproject_toml.is_file():
         return str(path_pyproject_toml)
diff --git a/tests/test_black.py b/tests/test_black.py
index 5f2e6f5b14c..abb304a246d 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -104,6 +104,7 @@ class FakeContext(click.Context):
 
     def __init__(self) -> None:
         self.default_map: Dict[str, Any] = {}
+        self.params: Dict[str, Any] = {}
         # Dummy root, since most of the tests don't care about it
         self.obj: Dict[str, Any] = {"root": PROJECT_ROOT}
 
@@ -1620,6 +1621,39 @@ def test_read_pyproject_toml(self) -> None:
         self.assertEqual(config["exclude"], r"\.pyi?$")
         self.assertEqual(config["include"], r"\.py?$")
 
+    def test_read_pyproject_toml_from_stdin(self) -> None:
+        with TemporaryDirectory() as workspace:
+            root = Path(workspace)
+
+            src_dir = root / "src"
+            src_dir.mkdir()
+
+            src_pyproject = src_dir / "pyproject.toml"
+            src_pyproject.touch()
+
+            test_toml_file = THIS_DIR / "test.toml"
+            src_pyproject.write_text(test_toml_file.read_text())
+
+            src_python = src_dir / "foo.py"
+            src_python.touch()
+
+            fake_ctx = FakeContext()
+            fake_ctx.params["src"] = ("-",)
+            fake_ctx.params["stdin_filename"] = str(src_python)
+
+            with change_directory(root):
+                black.read_pyproject_toml(fake_ctx, FakeParameter(), None)
+
+            config = fake_ctx.default_map
+            self.assertEqual(config["verbose"], "1")
+            self.assertEqual(config["check"], "no")
+            self.assertEqual(config["diff"], "y")
+            self.assertEqual(config["color"], "True")
+            self.assertEqual(config["line_length"], "79")
+            self.assertEqual(config["target_version"], ["py36", "py37", "py38"])
+            self.assertEqual(config["exclude"], r"\.pyi?$")
+            self.assertEqual(config["include"], r"\.py?$")
+
     @pytest.mark.incompatible_with_mypyc
     def test_find_project_root(self) -> None:
         with TemporaryDirectory() as workspace:

From c732a1f13a4b75d84dfd74eda0a57a55936d2e22 Mon Sep 17 00:00:00 2001
From: Stian Jensen <me@stianj.com>
Date: Fri, 23 Jun 2023 06:22:28 +0200
Subject: [PATCH 0774/1034] Build with mypyc 1.3 (#3697)

Several new versions of mypyc has been released since the last upgrade, and they include some performance improvements which could make the compiled version of Black run faster.

https://mypy-lang.org/news.html

The latest version of hatch-mypyc allows being installed next the 1.x series of mypy.
---
 CHANGES.md     | 2 ++
 pyproject.toml | 4 ++--
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index e1028c17681..460f9c95114 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -33,6 +33,8 @@
 
 <!-- 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 -->
diff --git a/pyproject.toml b/pyproject.toml
index 6803a627e9a..d44623fdbd3 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -119,8 +119,8 @@ sources = ["src"]
 [tool.hatch.build.targets.wheel.hooks.mypyc]
 enable-by-default = false
 dependencies = [
-  "hatch-mypyc>=0.13.0",
-  "mypy==0.991",
+  "hatch-mypyc>=0.16.0",
+  "mypy==1.3",
   # Required stubs to be removed when the packages support PEP 561 themselves
   "types-typed-ast>=1.4.2",
 ]

From 7be273531852a16a407fcb66d5efeede0f7ca474 Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Sat, 24 Jun 2023 16:06:12 -0700
Subject: [PATCH 0775/1034] Allow specifying `--workers` via environment
 variable (#3743)

---
 CHANGES.md                                 |  2 ++
 docs/usage_and_configuration/the_basics.md | 16 +++++++++++++++-
 src/black/__init__.py                      |  5 ++++-
 src/black/concurrency.py                   |  3 ++-
 4 files changed, 23 insertions(+), 3 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 460f9c95114..9717867df4e 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -25,6 +25,8 @@
 
 <!-- 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)
diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index 6f3a3cff30c..2a461487210 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -246,7 +246,8 @@ respect the `--force-exclude` option on some editors that rely on using stdin.
 #### `-W`, `--workers`
 
 When _Black_ formats multiple files, it may use a process pool to speed up formatting.
-This option controls the number of parallel workers.
+This option controls the number of parallel workers. This can also be specified via the
+`BLACK_NUM_WORKERS` environment variable.
 
 #### `-q`, `--quiet`
 
@@ -296,6 +297,19 @@ Read configuration options from a configuration file. See
 
 Show available command-line options and exit.
 
+### Environment variable options
+
+_Black_ supports the following configuration via environment variables.
+
+#### `BLACK_CACHE_DIR`
+
+The directory where _Black_ should store its cache.
+
+#### `BLACK_NUM_WORKERS`
+
+The number of parallel workers _Black_ should use. The command line option `-W` /
+`--workers` takes precedence over this environment variable.
+
 ### Code input alternatives
 
 _Black_ supports formatting code via stdin, with the result being printed to stdout.
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 60a339cdd12..3451c86b508 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -376,7 +376,10 @@ def validate_regex(
     "--workers",
     type=click.IntRange(min=1),
     default=None,
-    help="Number of parallel workers [default: number of CPUs in the system]",
+    help=(
+        "Number of parallel workers [default: BLACK_NUM_WORKERS environment variable "
+        "or number of CPUs in the system]"
+    ),
 )
 @click.option(
     "-q",
diff --git a/src/black/concurrency.py b/src/black/concurrency.py
index 1598f51e43f..893eba6675a 100644
--- a/src/black/concurrency.py
+++ b/src/black/concurrency.py
@@ -80,7 +80,8 @@ def reformat_many(
 
     executor: Executor
     if workers is None:
-        workers = os.cpu_count() or 1
+        workers = int(os.environ.get("BLACK_NUM_WORKERS", 0))
+        workers = workers or os.cpu_count() or 1
     if sys.platform == "win32":
         # Work around https://bugs.python.org/issue26903
         workers = min(workers, 60)

From 93989e995da7fa22c26abf8cc805273940265f5b Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Sat, 24 Jun 2023 17:27:47 -0700
Subject: [PATCH 0776/1034] Integrate verbose logging with get_sources (#3749)

Currently the verbose logging for "Sources to be formatted" is a little
suspect in that it is a completely different code path from
`get_sources`.

This can result in bugs like https://github.com/psf/black/pull/3216#issuecomment-1213557359
and generally limits the value of these logs.

This does change the "when" of this log, but the colours help separate
it from the even more verbose logs.
---
 CHANGES.md            |  1 +
 src/black/__init__.py | 34 +++++++++++++---------------------
 2 files changed, 14 insertions(+), 21 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 9717867df4e..a9d4d9d63c9 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -52,6 +52,7 @@
 <!-- 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_
 
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 3451c86b508..222cb3ca03d 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -484,26 +484,6 @@ def main(  # noqa: C901
                 fg="blue",
             )
 
-            normalized = [
-                (
-                    (source, source)
-                    if source == "-"
-                    else (normalize_path_maybe_ignore(Path(source), root), source)
-                )
-                for source in src
-            ]
-            srcs_string = ", ".join(
-                [
-                    (
-                        f'"{_norm}"'
-                        if _norm
-                        else f'\033[31m"{source} (skipping - invalid)"\033[34m'
-                    )
-                    for _norm, source in normalized
-                ]
-            )
-            out(f"Sources to be formatted: {srcs_string}", fg="blue")
-
         if config:
             config_source = ctx.get_parameter_source("config")
             user_level_config = str(find_user_pyproject_toml())
@@ -654,9 +634,15 @@ def get_sources(
             is_stdin = False
 
         if is_stdin or p.is_file():
-            normalized_path = normalize_path_maybe_ignore(p, ctx.obj["root"], report)
+            normalized_path: Optional[str] = normalize_path_maybe_ignore(
+                p, ctx.obj["root"], report
+            )
             if normalized_path is None:
+                if verbose:
+                    out(f'Skipping invalid source: "{normalized_path}"', fg="red")
                 continue
+            if verbose:
+                out(f'Found input source: "{normalized_path}"', fg="blue")
 
             normalized_path = "/" + normalized_path
             # Hard-exclude any files that matches the `--force-exclude` regex.
@@ -679,6 +665,9 @@ def get_sources(
             sources.add(p)
         elif p.is_dir():
             p = root / normalize_path_maybe_ignore(p, ctx.obj["root"], report)
+            if verbose:
+                out(f'Found input source directory: "{p}"', fg="blue")
+
             if using_default_exclude:
                 gitignore = {
                     root: root_gitignore,
@@ -699,9 +688,12 @@ def get_sources(
                 )
             )
         elif s == "-":
+            if verbose:
+                out("Found input source stdin", fg="blue")
             sources.add(p)
         else:
             err(f"invalid path: {s}")
+
     return sources
 
 

From e1036119f264a846bb049fad8404df318bc2f455 Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Sun, 25 Jun 2023 06:53:26 -0700
Subject: [PATCH 0777/1034] Check self format for the whole repo (#3750)

`black .` is changing things in gallery and scripts for me
---
 .github/workflows/test.yml  | 2 +-
 gallery/gallery.py          | 6 ++----
 scripts/make_width_table.py | 6 ++----
 3 files changed, 5 insertions(+), 9 deletions(-)

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 3ca2a469147..608c58af2ee 100644
--- a/.github/workflows/test.yml
+++ b/.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 .
diff --git a/gallery/gallery.py b/gallery/gallery.py
index 38e52e34795..ba5d6f65fbe 100755
--- a/gallery/gallery.py
+++ b/gallery/gallery.py
@@ -243,11 +243,9 @@ def format_repos(repos: Tuple[Path, ...], options: Namespace) -> None:
 
 
 def main() -> None:
-    parser = ArgumentParser(
-        description="""Black Gallery is a script that
+    parser = ArgumentParser(description="""Black Gallery is a script that
     automates the process of applying different Black versions to a selected
-    PyPI package and seeing the results between versions."""
-    )
+    PyPI package and seeing the results between versions.""")
 
     group = parser.add_mutually_exclusive_group(required=True)
     group.add_argument("-p", "--pypi-package", help="PyPI package to download.")
diff --git a/scripts/make_width_table.py b/scripts/make_width_table.py
index 09aca9c34b5..89c202553d3 100644
--- a/scripts/make_width_table.py
+++ b/scripts/make_width_table.py
@@ -49,8 +49,7 @@ def make_width_table() -> Iterable[Tuple[int, int, int]]:
 def main() -> None:
     table_path = join(dirname(__file__), "..", "src", "black", "_width_table.py")
     with open(table_path, "w") as f:
-        f.write(
-            f"""# Generated by {basename(__file__)}
+        f.write(f"""# Generated by {basename(__file__)}
 # wcwidth {wcwidth.__version__}
 # Unicode {wcwidth.list_versions()[-1]}
 import sys
@@ -62,8 +61,7 @@ def main() -> None:
     from typing import Final
 
 WIDTH_TABLE: Final[List[Tuple[int, int, int]]] = [
-"""
-        )
+""")
         for triple in make_width_table():
             f.write(f"    {triple!r},\n")
         f.write("]\n")

From 31b3b6701d2cfae072900f9d45dc8f1737ab282b Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Mon, 26 Jun 2023 17:47:55 -0700
Subject: [PATCH 0778/1034] Decrease cost of ipynb code path when unneeded
 (#3748)

IPython is a very expensive import, like, at least 300ms. I'd also
venture that it's much more common than tokenize-rt, which is like 30ms.
I work in a repo where I use black, have IPython installed and there
happen to be a couple notebooks (that we don't want formatted). I know I
can force exclude ipynb, but this change doesn't really have a cost.
---
 CHANGES.md                       | 2 ++
 src/black/handle_ipynb_magics.py | 7 ++++++-
 2 files changed, 8 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index a9d4d9d63c9..6fa0e4b7cc0 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -47,6 +47,8 @@
 
 <!-- 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 -->
diff --git a/src/black/handle_ipynb_magics.py b/src/black/handle_ipynb_magics.py
index 9e1af757c32..2b6b9209211 100644
--- a/src/black/handle_ipynb_magics.py
+++ b/src/black/handle_ipynb_magics.py
@@ -58,8 +58,13 @@ class Replacement:
 @lru_cache()
 def jupyter_dependencies_are_installed(*, verbose: bool, quiet: bool) -> bool:
     try:
-        import IPython  # noqa:F401
+        # isort: off
+        # tokenize_rt is less commonly installed than IPython
+        # and IPython is expensive to import
         import tokenize_rt  # noqa:F401
+        import IPython  # noqa:F401
+
+        # isort: on
     except ModuleNotFoundError:
         if verbose or not quiet:
             msg = (

From 63481bb9264a8c3756577089414d222da9c7fab0 Mon Sep 17 00:00:00 2001
From: rdrll <13176405+rdrll@users.noreply.github.com>
Date: Tue, 27 Jun 2023 07:23:39 -0700
Subject: [PATCH 0779/1034] Fix a magical comment caused internal error (#3740)

`is_type_comment` now specifically deals with general type comments for a leaf.
`is_type_ignore_comment` now handles type comments contains ignore annotation for a leaf
`is_type_ignore_comment_string` used to determine if a string is an ignore type comment
---
 CHANGES.md                                    |  2 +
 src/black/linegen.py                          | 10 ++++-
 src/black/lines.py                            |  5 ++-
 src/black/nodes.py                            | 23 +++++++++--
 ...ine_consecutive_open_parentheses_ignore.py | 41 +++++++++++++++++++
 5 files changed, 73 insertions(+), 8 deletions(-)
 create mode 100644 tests/data/simple_cases/multiline_consecutive_open_parentheses_ignore.py

diff --git a/CHANGES.md b/CHANGES.md
index 6fa0e4b7cc0..2dfed8a0dc4 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -12,6 +12,8 @@
 
 - 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
 
diff --git a/src/black/linegen.py b/src/black/linegen.py
index ad21307c311..5ef3bbd1705 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -49,6 +49,7 @@
     is_stub_body,
     is_stub_suite,
     is_tuple_containing_walrus,
+    is_type_ignore_comment_string,
     is_vararg,
     is_walrus_assignment,
     is_yield,
@@ -1399,8 +1400,13 @@ def maybe_make_parens_invisible_in_atom(
     if is_lpar_token(first) and is_rpar_token(last):
         middle = node.children[1]
         # make parentheses invisible
-        first.value = ""
-        last.value = ""
+        if (
+            # If the prefix of `middle` includes a type comment with
+            # ignore annotation, then we do not remove the parentheses
+            not is_type_ignore_comment_string(middle.prefix.strip())
+        ):
+            first.value = ""
+            last.value = ""
         maybe_make_parens_invisible_in_atom(
             middle,
             parent=parent,
diff --git a/src/black/lines.py b/src/black/lines.py
index daf0444d24e..ea8fe520756 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -28,6 +28,7 @@
     is_multiline_string,
     is_one_sequence_between,
     is_type_comment,
+    is_type_ignore_comment,
     is_with_or_async_with_stmt,
     replace_child,
     syms,
@@ -251,7 +252,7 @@ def contains_uncollapsable_type_comments(self) -> bool:
             for comment in comments:
                 if is_type_comment(comment):
                     if comment_seen or (
-                        not is_type_comment(comment, " ignore")
+                        not is_type_ignore_comment(comment)
                         and leaf_id not in ignored_ids
                     ):
                         return True
@@ -288,7 +289,7 @@ def contains_unsplittable_type_ignore(self) -> bool:
             # line.
             for node in self.leaves[-2:]:
                 for comment in self.comments.get(id(node), []):
-                    if is_type_comment(comment, " ignore"):
+                    if is_type_ignore_comment(comment):
                         return True
 
         return False
diff --git a/src/black/nodes.py b/src/black/nodes.py
index 45070909df4..b019b0c6440 100644
--- a/src/black/nodes.py
+++ b/src/black/nodes.py
@@ -816,12 +816,27 @@ def is_async_stmt_or_funcdef(leaf: Leaf) -> bool:
     )
 
 
-def is_type_comment(leaf: Leaf, suffix: str = "") -> bool:
-    """Return True if the given leaf is a special comment.
-    Only returns true for type comments for now."""
+def is_type_comment(leaf: Leaf) -> bool:
+    """Return True if the given leaf is a type comment. This function should only
+    be used for general type comments (excluding ignore annotations, which should
+    use `is_type_ignore_comment`). Note that general type comments are no longer
+    used in modern version of Python, this function may be deprecated in the future."""
     t = leaf.type
     v = leaf.value
-    return t in {token.COMMENT, STANDALONE_COMMENT} and v.startswith("# type:" + suffix)
+    return t in {token.COMMENT, STANDALONE_COMMENT} and v.startswith("# type:")
+
+
+def is_type_ignore_comment(leaf: Leaf) -> bool:
+    """Return True if the given leaf is a type comment with ignore annotation."""
+    t = leaf.type
+    v = leaf.value
+    return t in {token.COMMENT, STANDALONE_COMMENT} and is_type_ignore_comment_string(v)
+
+
+def is_type_ignore_comment_string(value: str) -> bool:
+    """Return True if the given string match with type comment with
+    ignore annotation."""
+    return value.startswith("# type: ignore")
 
 
 def wrap_in_parentheses(parent: Node, child: LN, *, visible: bool = True) -> None:
diff --git a/tests/data/simple_cases/multiline_consecutive_open_parentheses_ignore.py b/tests/data/simple_cases/multiline_consecutive_open_parentheses_ignore.py
new file mode 100644
index 00000000000..6ec8bb45408
--- /dev/null
+++ b/tests/data/simple_cases/multiline_consecutive_open_parentheses_ignore.py
@@ -0,0 +1,41 @@
+# This is a regression test. Issue #3737
+
+a = (  # type: ignore
+    int(  # type: ignore
+        int(  # type: ignore
+            int(  # type: ignore
+                6
+            )
+        )
+    )
+)
+
+b = (
+    int(
+        6
+    )
+)
+
+print(   "111") # type: ignore
+print(   "111"                         ) # type: ignore
+print(   "111"       ) # type: ignore
+
+
+# output
+
+
+# This is a regression test. Issue #3737
+
+a = (  # type: ignore
+    int(  # type: ignore
+        int(  # type: ignore
+            int(6)  # type: ignore
+        )
+    )
+)
+
+b = int(6)
+
+print("111")  # type: ignore
+print("111")  # type: ignore
+print("111")  # type: ignore
\ No newline at end of file

From f01aaa63a0ff792b932205cbb539f70aca769d7d Mon Sep 17 00:00:00 2001
From: rdrll <13176405+rdrll@users.noreply.github.com>
Date: Wed, 28 Jun 2023 13:45:56 -0700
Subject: [PATCH 0780/1034] Doc: Developer reference update (#3755)

---
 CHANGES.md                                    |   3 +
 .../reference/reference_classes.rst           | 161 +++++++++++++++++-
 .../reference/reference_exceptions.rst        |  10 +-
 .../reference/reference_summary.rst           |   7 +-
 src/black/handle_ipynb_magics.py              |   3 +-
 src/black/trans.py                            |  95 ++++++-----
 6 files changed, 220 insertions(+), 59 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 2dfed8a0dc4..ba7947a3c7d 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -76,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
diff --git a/docs/contributing/reference/reference_classes.rst b/docs/contributing/reference/reference_classes.rst
index 3931e0e0072..29b25003af2 100644
--- a/docs/contributing/reference/reference_classes.rst
+++ b/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,6 +52,12 @@
 .. autoclass:: black.comments.ProtoComment
     :members:
 
+:class:`Mode`
+---------------------
+
+.. autoclass:: black.mode.Mode
+    :members:
+
 :class:`Report`
 ---------------
 
@@ -50,6 +65,20 @@
     :members:
     :special-members: __str__
 
+:class:`Ok`
+---------------
+
+.. autoclass:: black.rusty.Ok
+    :show-inheritance:
+    :members:
+
+:class:`Err`
+---------------
+
+.. autoclass:: black.rusty.Err
+    :show-inheritance:
+    :members:
+
 :class:`Visitor`
 ----------------
 
@@ -57,20 +86,115 @@
     :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:
diff --git a/docs/contributing/reference/reference_exceptions.rst b/docs/contributing/reference/reference_exceptions.rst
index aafe61e5017..ab46ebdb628 100644
--- a/docs/contributing/reference/reference_exceptions.rst
+++ b/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
diff --git a/docs/contributing/reference/reference_summary.rst b/docs/contributing/reference/reference_summary.rst
index f6ff4681557..c6163d897b6 100644
--- a/docs/contributing/reference/reference_summary.rst
+++ b/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.*
 
diff --git a/src/black/handle_ipynb_magics.py b/src/black/handle_ipynb_magics.py
index 2b6b9209211..4324819beaf 100644
--- a/src/black/handle_ipynb_magics.py
+++ b/src/black/handle_ipynb_magics.py
@@ -335,7 +335,8 @@ class CellMagicFinder(ast.NodeVisitor):
 
     For example,
 
-        %%time\nfoo()
+        %%time\n
+        foo()
 
     would have been transformed to
 
diff --git a/src/black/trans.py b/src/black/trans.py
index 1e28ed0656e..4d40cb4bdf6 100644
--- a/src/black/trans.py
+++ b/src/black/trans.py
@@ -205,11 +205,11 @@ def do_match(self, line: Line) -> TMatchResult:
         """
         Returns:
             * Ok(string_indices) such that for each index, `line.leaves[index]`
-            is our target string if a match was able to be made. For
-            transformers that don't result in more lines (e.g. StringMerger,
-            StringParenStripper), multiple matches and transforms are done at
-            once to reduce the complexity.
-                OR
+              is our target string if a match was able to be made. For
+              transformers that don't result in more lines (e.g. StringMerger,
+              StringParenStripper), multiple matches and transforms are done at
+              once to reduce the complexity.
+              OR
             * Err(CannotTransform), if no match could be made.
         """
 
@@ -220,12 +220,12 @@ def do_transform(
         """
         Yields:
             * Ok(new_line) where new_line is the new transformed line.
-                OR
+              OR
             * Err(CannotTransform) if the transformation failed for some reason. The
-            `do_match(...)` template method should usually be used to reject
-            the form of the given Line, but in some cases it is difficult to
-            know whether or not a Line meets the StringTransformer's
-            requirements until the transformation is already midway.
+              `do_match(...)` template method should usually be used to reject
+              the form of the given Line, but in some cases it is difficult to
+              know whether or not a Line meets the StringTransformer's
+              requirements until the transformation is already midway.
 
         Side Effects:
             This method should NOT mutate @line directly, but it MAY mutate the
@@ -335,8 +335,8 @@ def pop_custom_splits(self, string: str) -> List[CustomSplit]:
 
         Returns:
             * A list of the custom splits that are mapped to @string, if any
-            exist.
-                OR
+              exist.
+              OR
             * [], otherwise.
 
         Side Effects:
@@ -365,14 +365,14 @@ class StringMerger(StringTransformer, CustomSplitMapMixin):
     Requirements:
         (A) The line contains adjacent strings such that ALL of the validation checks
         listed in StringMerger._validate_msg(...)'s docstring pass.
-            OR
+        OR
         (B) The line contains a string which uses line continuation backslashes.
 
     Transformations:
         Depending on which of the two requirements above where met, either:
 
         (A) The string group associated with the target string is merged.
-            OR
+        OR
         (B) All line-continuation backslashes are removed from the target string.
 
     Collaborations:
@@ -965,17 +965,20 @@ class BaseStringSplitter(StringTransformer):
 
     Requirements:
         * The target string value is responsible for the line going over the
-        line length limit. It follows that after all of black's other line
-        split methods have been exhausted, this line (or one of the resulting
-        lines after all line splits are performed) would still be over the
-        line_length limit unless we split this string.
-            AND
+          line length limit. It follows that after all of black's other line
+          split methods have been exhausted, this line (or one of the resulting
+          lines after all line splits are performed) would still be over the
+          line_length limit unless we split this string.
+          AND
+
         * The target string is NOT a "pointless" string (i.e. a string that has
-        no parent or siblings).
-            AND
+          no parent or siblings).
+          AND
+
         * The target string is not followed by an inline comment that appears
-        to be a pragma.
-            AND
+          to be a pragma.
+          AND
+
         * The target string is not a multiline (i.e. triple-quote) string.
     """
 
@@ -1027,7 +1030,7 @@ def _validate(self, line: Line, string_idx: int) -> TResult[None]:
 
         Returns:
             * Ok(None), if ALL of the requirements are met.
-                OR
+              OR
             * Err(CannotTransform), if ANY of the requirements are NOT met.
         """
         LL = line.leaves
@@ -1299,9 +1302,9 @@ class StringSplitter(BaseStringSplitter, CustomSplitMapMixin):
 
     Requirements:
         * The line consists ONLY of a single string (possibly prefixed by a
-        string operator [e.g. '+' or '==']), MAYBE a string trailer, and MAYBE
-        a trailing comma.
-            AND
+          string operator [e.g. '+' or '==']), MAYBE a string trailer, and MAYBE
+          a trailing comma.
+          AND
         * All of the requirements listed in BaseStringSplitter's docstring.
 
     Transformations:
@@ -1808,26 +1811,26 @@ class StringParenWrapper(BaseStringSplitter, CustomSplitMapMixin):
         addition to the requirements listed below:
 
         * The line is a return/yield statement, which returns/yields a string.
-            OR
+          OR
         * The line is part of a ternary expression (e.g. `x = y if cond else
-        z`) such that the line starts with `else <string>`, where <string> is
-        some string.
-            OR
+          z`) such that the line starts with `else <string>`, where <string> is
+          some string.
+          OR
         * The line is an assert statement, which ends with a string.
-            OR
+          OR
         * The line is an assignment statement (e.g. `x = <string>` or `x +=
-        <string>`) such that the variable is being assigned the value of some
-        string.
-            OR
+          <string>`) such that the variable is being assigned the value of some
+          string.
+          OR
         * The line is a dictionary key assignment where some valid key is being
-        assigned the value of some string.
-            OR
+          assigned the value of some string.
+          OR
         * The line is an lambda expression and the value is a string.
-            OR
+          OR
         * The line starts with an "atom" string that prefers to be wrapped in
-        parens. It's preferred to be wrapped when it's is an immediate child of
-        a list/set/tuple literal, AND the string is surrounded by commas (or is
-        the first/last child).
+          parens. It's preferred to be wrapped when it's is an immediate child of
+          a list/set/tuple literal, AND the string is surrounded by commas (or is
+          the first/last child).
 
     Transformations:
         The chosen string is wrapped in parentheses and then split at the LPAR.
@@ -2273,7 +2276,7 @@ def parse(self, leaves: List[Leaf], string_idx: int) -> int:
         Returns:
             The index directly after the last leaf which is apart of the string
             trailer, if a "trailer" exists.
-                OR
+            OR
             @string_idx + 1, if no string "trailer" exists.
         """
         assert leaves[string_idx].type == token.STRING
@@ -2287,11 +2290,11 @@ def _next_state(self, leaf: Leaf) -> bool:
         """
         Pre-conditions:
             * On the first call to this function, @leaf MUST be the leaf that
-            was directly after the string leaf in question (e.g. if our target
-            string is `line.leaves[i]` then the first call to this method must
-            be `line.leaves[i + 1]`).
+              was directly after the string leaf in question (e.g. if our target
+              string is `line.leaves[i]` then the first call to this method must
+              be `line.leaves[i + 1]`).
             * On the next call to this function, the leaf parameter passed in
-            MUST be the leaf directly following @leaf.
+              MUST be the leaf directly following @leaf.
 
         Returns:
             True iff @leaf is apart of the string's trailer.

From 839ef35dc1d72bb6eceac9fa809f095e2edcd12b Mon Sep 17 00:00:00 2001
From: rdrll <13176405+rdrll@users.noreply.github.com>
Date: Fri, 30 Jun 2023 07:07:42 -0700
Subject: [PATCH 0781/1034] CI Test: Deprecating 'set-output' command  (#3757)

---
 CHANGES.md                        | 2 ++
 scripts/diff_shades_gha_helper.py | 8 +++++++-
 2 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index ba7947a3c7d..d7928a30c5c 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -70,6 +70,8 @@
 <!-- For example, Docker, GitHub Actions, pre-commit, editors -->
 
 - Update GitHub Action to display black output in the job summary (#3688)
+- Deprecated `set-output` command in CI test to keep up to date with GitHub's
+  deprecation announcement (#3757)
 
 ### Documentation
 
diff --git a/scripts/diff_shades_gha_helper.py b/scripts/diff_shades_gha_helper.py
index b5fea5a817d..994fbe05045 100644
--- a/scripts/diff_shades_gha_helper.py
+++ b/scripts/diff_shades_gha_helper.py
@@ -52,7 +52,13 @@ def set_output(name: str, value: str) -> None:
         print(f"[INFO]: setting '{name}' to '{value}'")
     else:
         print(f"[INFO]: setting '{name}' to [{len(value)} chars]")
-    print(f"::set-output name={name}::{value}")
+
+    # Originally the `set-output` workflow command was used here, now replaced
+    # by setting variables through the `GITHUB_OUTPUT` environment variable
+    # to stay up to date with GitHub's update.
+    if "GITHUB_OUTPUT" in os.environ:
+        with open(os.environ["GITHUB_OUTPUT"], "a") as f:
+            print(f"{name}={value}", file=f)
 
 
 def http_get(url: str, *, is_json: bool = True, **kwargs: Any) -> Any:

From 8e618f386995fa89434834e6a793a1057e58112a Mon Sep 17 00:00:00 2001
From: Zac Hatfield-Dodds <zac.hatfield.dodds@gmail.com>
Date: Tue, 4 Jul 2023 16:38:39 -0700
Subject: [PATCH 0782/1034] Enable `PYTHONWARNDEFAULTENCODING = 1` in CI
 (#3763)

---
 CHANGES.md             |  3 ++
 tests/test_black.py    | 87 +++++++++++++++++-------------------------
 tests/test_ipynb.py    |  9 ++---
 tests/test_no_ipynb.py |  3 +-
 tox.ini                |  4 +-
 5 files changed, 44 insertions(+), 62 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index d7928a30c5c..acb5a822674 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -69,6 +69,9 @@
 
 <!-- For example, Docker, GitHub Actions, pre-commit, editors -->
 
+- Black is now tested with
+  [`PYTHONWARNDEFAULTENCODING = 1`](https://docs.python.org/3/library/io.html#io-encoding-warning)
+  (#3763)
 - Update GitHub Action to display black output in the job summary (#3688)
 - Deprecated `set-output` command in CI test to keep up to date with GitHub's
   deprecation announcement (#3757)
diff --git a/tests/test_black.py b/tests/test_black.py
index abb304a246d..dee6ead50d0 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -149,8 +149,7 @@ def test_empty_ff(self) -> None:
         tmp_file = Path(black.dump_to_file())
         try:
             self.assertFalse(ff(tmp_file, write_back=black.WriteBack.YES))
-            with open(tmp_file, encoding="utf8") as f:
-                actual = f.read()
+            actual = tmp_file.read_text(encoding="utf-8")
         finally:
             os.unlink(tmp_file)
         self.assertFormatEqual(expected, actual)
@@ -178,7 +177,7 @@ def test_one_empty_line_ff(self) -> None:
                     ff(tmp_file, mode=mode, write_back=black.WriteBack.YES)
                 )
                 with open(tmp_file, "rb") as f:
-                    actual = f.read().decode("utf8")
+                    actual = f.read().decode("utf-8")
             finally:
                 os.unlink(tmp_file)
             self.assertFormatEqual(expected, actual)
@@ -198,7 +197,7 @@ def test_piping(self) -> None:
                 f"--line-length={black.DEFAULT_LINE_LENGTH}",
                 f"--config={EMPTY_CONFIG}",
             ],
-            input=BytesIO(source.encode("utf8")),
+            input=BytesIO(source.encode("utf-8")),
         )
         self.assertEqual(result.exit_code, 0)
         self.assertFormatEqual(expected, result.output)
@@ -221,7 +220,7 @@ def test_piping_diff(self) -> None:
             f"--config={EMPTY_CONFIG}",
         ]
         result = BlackRunner().invoke(
-            black.main, args, input=BytesIO(source.encode("utf8"))
+            black.main, args, input=BytesIO(source.encode("utf-8"))
         )
         self.assertEqual(result.exit_code, 0)
         actual = diff_header.sub(DETERMINISTIC_HEADER, result.output)
@@ -239,7 +238,7 @@ def test_piping_diff_with_color(self) -> None:
             f"--config={EMPTY_CONFIG}",
         ]
         result = BlackRunner().invoke(
-            black.main, args, input=BytesIO(source.encode("utf8"))
+            black.main, args, input=BytesIO(source.encode("utf-8"))
         )
         actual = result.output
         # Again, the contents are checked in a different test, so only look for colors.
@@ -286,8 +285,7 @@ def test_expression_ff(self) -> None:
         tmp_file = Path(black.dump_to_file(source))
         try:
             self.assertTrue(ff(tmp_file, write_back=black.WriteBack.YES))
-            with open(tmp_file, encoding="utf8") as f:
-                actual = f.read()
+            actual = tmp_file.read_text(encoding="utf-8")
         finally:
             os.unlink(tmp_file)
         self.assertFormatEqual(expected, actual)
@@ -390,8 +388,7 @@ def test_skip_source_first_line(self) -> None:
             black.main, [str(tmp_file), "-x", f"--config={EMPTY_CONFIG}"]
         )
         self.assertEqual(result.exit_code, 0)
-        with open(tmp_file, encoding="utf8") as f:
-            actual = f.read()
+        actual = tmp_file.read_text(encoding="utf-8")
         self.assertFormatEqual(source, actual)
 
     def test_skip_source_first_line_when_mixing_newlines(self) -> None:
@@ -1081,7 +1078,7 @@ def test_works_in_mono_process_only_environment(self) -> None:
                 (workspace / "one.py").resolve(),
                 (workspace / "two.py").resolve(),
             ]:
-                f.write_text('print("hello")\n')
+                f.write_text('print("hello")\n', encoding="utf-8")
             self.invokeBlack([str(workspace)])
 
     @event_loop()
@@ -1118,11 +1115,9 @@ def test_single_file_force_pyi(self) -> None:
         contents, expected = read_data("miscellaneous", "force_pyi")
         with cache_dir() as workspace:
             path = (workspace / "file.py").resolve()
-            with open(path, "w") as fh:
-                fh.write(contents)
+            path.write_text(contents, encoding="utf-8")
             self.invokeBlack([str(path), "--pyi"])
-            with open(path, "r") as fh:
-                actual = fh.read()
+            actual = path.read_text(encoding="utf-8")
             # verify cache with --pyi is separate
             pyi_cache = black.read_cache(pyi_mode)
             self.assertIn(str(path), pyi_cache)
@@ -1143,12 +1138,10 @@ def test_multi_file_force_pyi(self) -> None:
                 (workspace / "file2.py").resolve(),
             ]
             for path in paths:
-                with open(path, "w") as fh:
-                    fh.write(contents)
+                path.write_text(contents, encoding="utf-8")
             self.invokeBlack([str(p) for p in paths] + ["--pyi"])
             for path in paths:
-                with open(path, "r") as fh:
-                    actual = fh.read()
+                actual = path.read_text(encoding="utf-8")
                 self.assertEqual(actual, expected)
             # verify cache with --pyi is separate
             pyi_cache = black.read_cache(pyi_mode)
@@ -1160,7 +1153,7 @@ def test_multi_file_force_pyi(self) -> None:
     def test_pipe_force_pyi(self) -> None:
         source, expected = read_data("miscellaneous", "force_pyi")
         result = CliRunner().invoke(
-            black.main, ["-", "-q", "--pyi"], input=BytesIO(source.encode("utf8"))
+            black.main, ["-", "-q", "--pyi"], input=BytesIO(source.encode("utf-8"))
         )
         self.assertEqual(result.exit_code, 0)
         actual = result.output
@@ -1172,11 +1165,9 @@ def test_single_file_force_py36(self) -> None:
         source, expected = read_data("miscellaneous", "force_py36")
         with cache_dir() as workspace:
             path = (workspace / "file.py").resolve()
-            with open(path, "w") as fh:
-                fh.write(source)
+            path.write_text(source, encoding="utf-8")
             self.invokeBlack([str(path), *PY36_ARGS])
-            with open(path, "r") as fh:
-                actual = fh.read()
+            actual = path.read_text(encoding="utf-8")
             # verify cache with --target-version is separate
             py36_cache = black.read_cache(py36_mode)
             self.assertIn(str(path), py36_cache)
@@ -1195,12 +1186,10 @@ def test_multi_file_force_py36(self) -> None:
                 (workspace / "file2.py").resolve(),
             ]
             for path in paths:
-                with open(path, "w") as fh:
-                    fh.write(source)
+                path.write_text(source, encoding="utf-8")
             self.invokeBlack([str(p) for p in paths] + PY36_ARGS)
             for path in paths:
-                with open(path, "r") as fh:
-                    actual = fh.read()
+                actual = path.read_text(encoding="utf-8")
                 self.assertEqual(actual, expected)
             # verify cache with --target-version is separate
             pyi_cache = black.read_cache(py36_mode)
@@ -1214,7 +1203,7 @@ def test_pipe_force_py36(self) -> None:
         result = CliRunner().invoke(
             black.main,
             ["-", "-q", "--target-version=py36"],
-            input=BytesIO(source.encode("utf8")),
+            input=BytesIO(source.encode("utf-8")),
         )
         self.assertEqual(result.exit_code, 0)
         actual = result.output
@@ -1443,11 +1432,11 @@ def test_preserves_line_endings_via_stdin(self) -> None:
             contents = nl.join(["def f(  ):", "    pass"])
             runner = BlackRunner()
             result = runner.invoke(
-                black.main, ["-", "--fast"], input=BytesIO(contents.encode("utf8"))
+                black.main, ["-", "--fast"], input=BytesIO(contents.encode("utf-8"))
             )
             self.assertEqual(result.exit_code, 0)
             output = result.stdout_bytes
-            self.assertIn(nl.encode("utf8"), output)
+            self.assertIn(nl.encode("utf-8"), output)
             if nl == "\n":
                 self.assertNotIn(b"\r\n", output)
 
@@ -1631,8 +1620,8 @@ def test_read_pyproject_toml_from_stdin(self) -> None:
             src_pyproject = src_dir / "pyproject.toml"
             src_pyproject.touch()
 
-            test_toml_file = THIS_DIR / "test.toml"
-            src_pyproject.write_text(test_toml_file.read_text())
+            test_toml_content = (THIS_DIR / "test.toml").read_text(encoding="utf-8")
+            src_pyproject.write_text(test_toml_content, encoding="utf-8")
 
             src_python = src_dir / "foo.py"
             src_python.touch()
@@ -1985,10 +1974,10 @@ def test_cache_broken_file(self) -> None:
         mode = DEFAULT_MODE
         with cache_dir() as workspace:
             cache_file = get_cache_file(mode)
-            cache_file.write_text("this is not a pickle")
+            cache_file.write_text("this is not a pickle", encoding="utf-8")
             assert black.read_cache(mode) == {}
             src = (workspace / "test.py").resolve()
-            src.write_text("print('hello')")
+            src.write_text("print('hello')", encoding="utf-8")
             invokeBlack([str(src)])
             cache = black.read_cache(mode)
             assert str(src) in cache
@@ -1997,10 +1986,10 @@ def test_cache_single_file_already_cached(self) -> None:
         mode = DEFAULT_MODE
         with cache_dir() as workspace:
             src = (workspace / "test.py").resolve()
-            src.write_text("print('hello')")
+            src.write_text("print('hello')", encoding="utf-8")
             black.write_cache({}, [src], mode)
             invokeBlack([str(src)])
-            assert src.read_text() == "print('hello')"
+            assert src.read_text(encoding="utf-8") == "print('hello')"
 
     @event_loop()
     def test_cache_multiple_files(self) -> None:
@@ -2009,17 +1998,13 @@ def test_cache_multiple_files(self) -> None:
             "concurrent.futures.ProcessPoolExecutor", new=ThreadPoolExecutor
         ):
             one = (workspace / "one.py").resolve()
-            with one.open("w") as fobj:
-                fobj.write("print('hello')")
+            one.write_text("print('hello')", encoding="utf-8")
             two = (workspace / "two.py").resolve()
-            with two.open("w") as fobj:
-                fobj.write("print('hello')")
+            two.write_text("print('hello')", encoding="utf-8")
             black.write_cache({}, [one], mode)
             invokeBlack([str(workspace)])
-            with one.open("r") as fobj:
-                assert fobj.read() == "print('hello')"
-            with two.open("r") as fobj:
-                assert fobj.read() == 'print("hello")\n'
+            assert one.read_text(encoding="utf-8") == "print('hello')"
+            assert two.read_text(encoding="utf-8") == 'print("hello")\n'
             cache = black.read_cache(mode)
             assert str(one) in cache
             assert str(two) in cache
@@ -2029,8 +2014,7 @@ def test_no_cache_when_writeback_diff(self, color: bool) -> None:
         mode = DEFAULT_MODE
         with cache_dir() as workspace:
             src = (workspace / "test.py").resolve()
-            with src.open("w") as fobj:
-                fobj.write("print('hello')")
+            src.write_text("print('hello')", encoding="utf-8")
             with patch("black.read_cache") as read_cache, patch(
                 "black.write_cache"
             ) as write_cache:
@@ -2049,8 +2033,7 @@ def test_output_locking_when_writeback_diff(self, color: bool) -> None:
         with cache_dir() as workspace:
             for tag in range(0, 4):
                 src = (workspace / f"test{tag}.py").resolve()
-                with src.open("w") as fobj:
-                    fobj.write("print('hello')")
+                src.write_text("print('hello')", encoding="utf-8")
             with patch(
                 "black.concurrency.Manager", wraps=multiprocessing.Manager
             ) as mgr:
@@ -2120,11 +2103,9 @@ def test_failed_formatting_does_not_get_cached(self) -> None:
             "concurrent.futures.ProcessPoolExecutor", new=ThreadPoolExecutor
         ):
             failing = (workspace / "failing.py").resolve()
-            with failing.open("w") as fobj:
-                fobj.write("not actually python")
+            failing.write_text("not actually python", encoding="utf-8")
             clean = (workspace / "clean.py").resolve()
-            with clean.open("w") as fobj:
-                fobj.write('print("hello")\n')
+            clean.write_text('print("hello")\n', encoding="utf-8")
             invokeBlack([str(workspace)], exit_code=123)
             cache = black.read_cache(mode)
             assert str(failing) not in cache
diff --git a/tests/test_ipynb.py b/tests/test_ipynb.py
index 7aa2e91dd00..91e7901125b 100644
--- a/tests/test_ipynb.py
+++ b/tests/test_ipynb.py
@@ -439,8 +439,7 @@ def test_cache_isnt_written_if_no_jupyter_deps_single(
     jupyter_dependencies_are_installed.cache_clear()
     nb = get_case_path("jupyter", "notebook_trailing_newline.ipynb")
     tmp_nb = tmp_path / "notebook.ipynb"
-    with open(nb) as src, open(tmp_nb, "w") as dst:
-        dst.write(src.read())
+    tmp_nb.write_bytes(nb.read_bytes())
     monkeypatch.setattr(
         "black.jupyter_dependencies_are_installed", lambda verbose, quiet: False
     )
@@ -465,8 +464,7 @@ def test_cache_isnt_written_if_no_jupyter_deps_dir(
     jupyter_dependencies_are_installed.cache_clear()
     nb = get_case_path("jupyter", "notebook_trailing_newline.ipynb")
     tmp_nb = tmp_path / "notebook.ipynb"
-    with open(nb) as src, open(tmp_nb, "w") as dst:
-        dst.write(src.read())
+    tmp_nb.write_bytes(nb.read_bytes())
     monkeypatch.setattr(
         "black.files.jupyter_dependencies_are_installed", lambda verbose, quiet: False
     )
@@ -483,8 +481,7 @@ def test_cache_isnt_written_if_no_jupyter_deps_dir(
 def test_ipynb_flag(tmp_path: pathlib.Path) -> None:
     nb = get_case_path("jupyter", "notebook_trailing_newline.ipynb")
     tmp_nb = tmp_path / "notebook.a_file_extension_which_is_definitely_not_ipynb"
-    with open(nb) as src, open(tmp_nb, "w") as dst:
-        dst.write(src.read())
+    tmp_nb.write_bytes(nb.read_bytes())
     result = runner.invoke(
         main,
         [
diff --git a/tests/test_no_ipynb.py b/tests/test_no_ipynb.py
index b63ecde8896..12c820def39 100644
--- a/tests/test_no_ipynb.py
+++ b/tests/test_no_ipynb.py
@@ -27,8 +27,7 @@ def test_ipynb_diff_with_no_change_dir(tmp_path: pathlib.Path) -> None:
     runner = CliRunner()
     nb = get_case_path("jupyter", "notebook_trailing_newline.ipynb")
     tmp_nb = tmp_path / "notebook.ipynb"
-    with open(nb) as src, open(tmp_nb, "w") as dst:
-        dst.write(src.read())
+    tmp_nb.write_bytes(nb.read_bytes())
     result = runner.invoke(main, [str(tmp_path)])
     expected_output = (
         "Skipping .ipynb files as Jupyter dependencies are not installed.\n"
diff --git a/tox.ini b/tox.ini
index 4934514264b..f8e1a785331 100644
--- a/tox.ini
+++ b/tox.ini
@@ -3,7 +3,9 @@ isolated_build = true
 envlist = {,ci-}py{37,38,39,310,311,py3},fuzz,run_self
 
 [testenv]
-setenv = PYTHONPATH = {toxinidir}/src
+setenv =
+    PYTHONPATH = {toxinidir}/src
+    PYTHONWARNDEFAULTENCODING = 1
 skip_install = True
 # We use `recreate=True` because otherwise, on the second run of `tox -e py`,
 # the `no_jupyter` tests would run with the jupyter extra dependencies installed.

From cf4cc2981900565ab931aada176abf08a1f5782d Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Tue, 4 Jul 2023 22:45:57 -0700
Subject: [PATCH 0783/1034] Better error message for invalid exclude types
 (#3764)

---
 CHANGES.md            |  2 ++
 src/black/__init__.py | 10 ++++++++++
 2 files changed, 12 insertions(+)

diff --git a/CHANGES.md b/CHANGES.md
index acb5a822674..bfa021617cb 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -32,6 +32,8 @@
 - `.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)
+- Black will now error if `exclude` and `extend-exclude` have invalid data types in
+  `pyproject.toml`, instead of silently doing the wrong thing (#3764)
 
 ### Packaging
 
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 222cb3ca03d..b6611bef84b 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -157,6 +157,16 @@ def read_pyproject_toml(
             "target-version", "Config key target-version must be a list"
         )
 
+    exclude = config.get("exclude")
+    if exclude is not None and not isinstance(exclude, str):
+        raise click.BadOptionUsage("exclude", "Config key exclude must be a string")
+
+    extend_exclude = config.get("extend_exclude")
+    if extend_exclude is not None and not isinstance(extend_exclude, str):
+        raise click.BadOptionUsage(
+            "extend-exclude", "Config key extend-exclude must be a string"
+        )
+
     default_map: Dict[str, Any] = {}
     if ctx.default_map:
         default_map.update(ctx.default_map)

From b4dca26c7d93f930bbd5a7b552807370b60d4298 Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Wed, 5 Jul 2023 10:08:04 -0700
Subject: [PATCH 0784/1034] Drop support for Python 3.7 (#3765)

---
 .github/workflows/fuzz.yml     |   2 +-
 .github/workflows/test.yml     |   2 +-
 CHANGES.md                     |   3 +
 docs/integrations/editors.md   |  54 ----------------
 mypy.ini                       |   2 +-
 pyproject.toml                 |  10 +--
 scripts/make_width_table.py    |   8 +--
 src/black/_width_table.py      |   8 +--
 src/black/brackets.py          |   8 +--
 src/black/comments.py          |   8 +--
 src/black/mode.py              |   8 +--
 src/black/nodes.py             |   6 +-
 src/black/parsing.py           | 109 +++++++--------------------------
 src/black/strings.py           |  10 +--
 src/black/trans.py             |   8 +--
 src/blib2to3/pgen2/token.py    |   5 +-
 src/blib2to3/pgen2/tokenize.py |   5 +-
 17 files changed, 43 insertions(+), 213 deletions(-)

diff --git a/.github/workflows/fuzz.yml b/.github/workflows/fuzz.yml
index 373e1500ee9..4439148a1c7 100644
--- a/.github/workflows/fuzz.yml
+++ b/.github/workflows/fuzz.yml
@@ -22,7 +22,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11"]
+        python-version: ["3.8", "3.9", "3.10", "3.11"]
 
     steps:
       - uses: actions/checkout@v3
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 608c58af2ee..92d7d411510 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -31,7 +31,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11", "pypy-3.7", "pypy-3.8"]
+        python-version: ["3.8", "3.9", "3.10", "3.11", "pypy-3.8"]
         os: [ubuntu-latest, macOS-latest, windows-latest]
 
     steps:
diff --git a/CHANGES.md b/CHANGES.md
index bfa021617cb..24ca54a82ac 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -6,6 +6,9 @@
 
 <!-- Include any especially major or disruptive changes here -->
 
+- Runtime support for Python 3.7 has been removed. Formatting 3.7 code will still be
+  supported until further notice (#3765)
+
 ### Stable style
 
 <!-- Changes that affect Black's stable style -->
diff --git a/docs/integrations/editors.md b/docs/integrations/editors.md
index 74c6a283ab8..ff563068e79 100644
--- a/docs/integrations/editors.md
+++ b/docs/integrations/editors.md
@@ -334,60 +334,6 @@ To run _Black_ on a key press (e.g. F9 below), add this:
 nnoremap <F9> :Black<CR>
 ```
 
-#### Troubleshooting
-
-**How to get Vim with Python 3.6?** On Ubuntu 17.10 Vim comes with Python 3.6 by
-default. On macOS with Homebrew run: `brew install vim`. When building Vim from source,
-use: `./configure --enable-python3interp=yes`. There's many guides online how to do
-this.
-
-**I get an import error when using _Black_ from a virtual environment**: If you get an
-error message like this:
-
-```text
-Traceback (most recent call last):
-  File "<string>", line 63, in <module>
-  File "/home/gui/.vim/black/lib/python3.7/site-packages/black.py", line 45, in <module>
-    from typed_ast import ast3, ast27
-  File "/home/gui/.vim/black/lib/python3.7/site-packages/typed_ast/ast3.py", line 40, in <module>
-    from typed_ast import _ast3
-ImportError: /home/gui/.vim/black/lib/python3.7/site-packages/typed_ast/_ast3.cpython-37m-x86_64-linux-gnu.so: undefined symbool: PyExc_KeyboardInterrupt
-```
-
-Then you need to install `typed_ast` directly from the source code. The error happens
-because `pip` will download [Python wheels](https://pythonwheels.com/) if they are
-available. Python wheels are a new standard of distributing Python packages and packages
-that have Cython and extensions written in C are already compiled, so the installation
-is much more faster. The problem here is that somehow the Python environment inside Vim
-does not match with those already compiled C extensions and these kind of errors are the
-result. Luckily there is an easy fix: installing the packages from the source code.
-
-The package that causes problems is:
-
-- [typed-ast](https://pypi.org/project/typed-ast/)
-
-Now remove those two packages:
-
-```console
-$ pip uninstall typed-ast -y
-```
-
-And now you can install them with:
-
-```console
-$ pip install --no-binary :all: typed-ast
-```
-
-The C extensions will be compiled and now Vim's Python environment will match. Note that
-you need to have the GCC compiler and the Python development files installed (on
-Ubuntu/Debian do `sudo apt-get install build-essential python3-dev`).
-
-If you later want to update _Black_, you should do it like this:
-
-```console
-$ pip install -U black --no-binary typed-ast
-```
-
 ### With ALE
 
 1. Install [`ale`](https://github.com/dense-analysis/ale)
diff --git a/mypy.ini b/mypy.ini
index 58bb7536173..95ec22d65be 100644
--- a/mypy.ini
+++ b/mypy.ini
@@ -2,7 +2,7 @@
 # Specify the target platform details in config, so your developers are
 # free to run mypy on Windows, Linux, or macOS and get consistent
 # results.
-python_version=3.7
+python_version=3.8
 
 mypy_path=src
 
diff --git a/pyproject.toml b/pyproject.toml
index d44623fdbd3..2d8da88f6c6 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -33,7 +33,7 @@ build-backend = "hatchling.build"
 name = "black"
 description = "The uncompromising code formatter."
 license = { text = "MIT" }
-requires-python = ">=3.7"
+requires-python = ">=3.8"
 authors = [
   { name = "Łukasz Langa", email = "lukasz@langa.pl" },
 ]
@@ -69,7 +69,6 @@ dependencies = [
   "pathspec>=0.9.0",
   "platformdirs>=2",
   "tomli>=1.1.0; python_version < '3.11'",
-  "typed-ast>=1.4.2; python_version < '3.8' and implementation_name == 'cpython'",
   "typing_extensions>=3.10.0.0; python_version < '3.10'",
 ]
 dynamic = ["readme", "version"]
@@ -121,8 +120,6 @@ enable-by-default = false
 dependencies = [
   "hatch-mypyc>=0.16.0",
   "mypy==1.3",
-  # Required stubs to be removed when the packages support PEP 561 themselves
-  "types-typed-ast>=1.4.2",
 ]
 require-runtime-dependencies = true
 exclude = [
@@ -145,7 +142,7 @@ options = { debug_level = "0" }
 [tool.cibuildwheel]
 build-verbosity = 1
 # So these are the environments we target:
-# - Python: CPython 3.7+ only
+# - Python: CPython 3.8+ only
 # - Architecture (64-bit only): amd64 / x86_64, universal2, and arm64
 # - OS: Linux (no musl), Windows, and macOS
 build = "cp3*-*"
@@ -208,9 +205,6 @@ filterwarnings = [
     # this is mitigated by a try/catch in https://github.com/psf/black/pull/3198/
     # this ignore can be removed when support for aiohttp 3.x is dropped.
     '''ignore:Middleware decorator is deprecated since 4\.0 and its behaviour is default, you can simply remove this decorator:DeprecationWarning''',
-    # this is mitigated by https://github.com/python/cpython/issues/79071 in python 3.8+
-    # this ignore can be removed when support for 3.7 is dropped.
-    '''ignore:Bare functions are deprecated, use async ones:DeprecationWarning''',
     # aiohttp is using deprecated cgi modules - Safe to remove when fixed:
     # https://github.com/aio-libs/aiohttp/issues/6905
     '''ignore:'cgi' is deprecated and slated for removal in Python 3.13:DeprecationWarning''',
diff --git a/scripts/make_width_table.py b/scripts/make_width_table.py
index 89c202553d3..30fd32c34b0 100644
--- a/scripts/make_width_table.py
+++ b/scripts/make_width_table.py
@@ -52,13 +52,7 @@ def main() -> None:
         f.write(f"""# Generated by {basename(__file__)}
 # wcwidth {wcwidth.__version__}
 # Unicode {wcwidth.list_versions()[-1]}
-import sys
-from typing import List, Tuple
-
-if sys.version_info < (3, 8):
-    from typing_extensions import Final
-else:
-    from typing import Final
+from typing import Final, List, Tuple
 
 WIDTH_TABLE: Final[List[Tuple[int, int, int]]] = [
 """)
diff --git a/src/black/_width_table.py b/src/black/_width_table.py
index 6923f597687..f3304e48ed0 100644
--- a/src/black/_width_table.py
+++ b/src/black/_width_table.py
@@ -1,13 +1,7 @@
 # Generated by make_width_table.py
 # wcwidth 0.2.6
 # Unicode 15.0.0
-import sys
-from typing import List, Tuple
-
-if sys.version_info < (3, 8):
-    from typing_extensions import Final
-else:
-    from typing import Final
+from typing import Final, List, Tuple
 
 WIDTH_TABLE: Final[List[Tuple[int, int, int]]] = [
     (0, 0, 0),
diff --git a/src/black/brackets.py b/src/black/brackets.py
index 343f0608d50..85dac6edd1e 100644
--- a/src/black/brackets.py
+++ b/src/black/brackets.py
@@ -1,13 +1,7 @@
 """Builds on top of nodes.py to track brackets."""
 
-import sys
 from dataclasses import dataclass, field
-from typing import Dict, Iterable, List, Optional, Sequence, Set, Tuple, Union
-
-if sys.version_info < (3, 8):
-    from typing_extensions import Final
-else:
-    from typing import Final
+from typing import Dict, Final, Iterable, List, Optional, Sequence, Set, Tuple, Union
 
 from black.nodes import (
     BRACKET,
diff --git a/src/black/comments.py b/src/black/comments.py
index 619123ab4be..226968bff98 100644
--- a/src/black/comments.py
+++ b/src/black/comments.py
@@ -1,13 +1,7 @@
 import re
-import sys
 from dataclasses import dataclass
 from functools import lru_cache
-from typing import Iterator, List, Optional, Union
-
-if sys.version_info >= (3, 8):
-    from typing import Final
-else:
-    from typing_extensions import Final
+from typing import Final, Iterator, List, Optional, Union
 
 from black.nodes import (
     CLOSING_BRACKETS,
diff --git a/src/black/mode.py b/src/black/mode.py
index 1091494afac..4d979afd84d 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -4,19 +4,13 @@
 chosen by the user.
 """
 
-import sys
 from dataclasses import dataclass, field
 from enum import Enum, auto
 from hashlib import sha256
 from operator import attrgetter
-from typing import Dict, Set
+from typing import Dict, Final, Set
 from warnings import warn
 
-if sys.version_info < (3, 8):
-    from typing_extensions import Final
-else:
-    from typing import Final
-
 from black.const import DEFAULT_LINE_LENGTH
 
 
diff --git a/src/black/nodes.py b/src/black/nodes.py
index b019b0c6440..ef42278d83f 100644
--- a/src/black/nodes.py
+++ b/src/black/nodes.py
@@ -3,12 +3,8 @@
 """
 
 import sys
-from typing import Generic, Iterator, List, Optional, Set, Tuple, TypeVar, Union
+from typing import Final, Generic, Iterator, List, Optional, Set, Tuple, TypeVar, Union
 
-if sys.version_info >= (3, 8):
-    from typing import Final
-else:
-    from typing_extensions import Final
 if sys.version_info >= (3, 10):
     from typing import TypeGuard
 else:
diff --git a/src/black/parsing.py b/src/black/parsing.py
index 70ed99c1549..455c5eed968 100644
--- a/src/black/parsing.py
+++ b/src/black/parsing.py
@@ -2,14 +2,8 @@
 Parse Python code and perform AST validation.
 """
 import ast
-import platform
 import sys
-from typing import Any, Iterable, Iterator, List, Set, Tuple, Type, Union
-
-if sys.version_info < (3, 8):
-    from typing_extensions import Final
-else:
-    from typing import Final
+from typing import Final, Iterable, Iterator, List, Set, Tuple
 
 from black.mode import VERSION_TO_FEATURES, Feature, TargetVersion, supports_feature
 from black.nodes import syms
@@ -20,25 +14,6 @@
 from blib2to3.pgen2.tokenize import TokenError
 from blib2to3.pytree import Leaf, Node
 
-ast3: Any
-
-_IS_PYPY = platform.python_implementation() == "PyPy"
-
-try:
-    from typed_ast import ast3
-except ImportError:
-    if sys.version_info < (3, 8) and not _IS_PYPY:
-        print(
-            "The typed_ast package is required but not installed.\n"
-            "You can upgrade to Python 3.8+ or install typed_ast with\n"
-            "`python3 -m pip install typed-ast`.",
-            file=sys.stderr,
-        )
-        sys.exit(1)
-    else:
-        ast3 = ast
-
-
 PY2_HINT: Final = "Python 2 support was removed in version 22.0."
 
 
@@ -147,31 +122,14 @@ def lib2to3_unparse(node: Node) -> str:
 
 def parse_single_version(
     src: str, version: Tuple[int, int], *, type_comments: bool
-) -> Union[ast.AST, ast3.AST]:
+) -> ast.AST:
     filename = "<unknown>"
-    # typed-ast is needed because of feature version limitations in the builtin ast 3.8>
-    if sys.version_info >= (3, 8) and version >= (3,):
-        return ast.parse(
-            src, filename, feature_version=version, type_comments=type_comments
-        )
-
-    if _IS_PYPY:
-        # PyPy 3.7 doesn't support type comment tracking which is not ideal, but there's
-        # not much we can do as typed-ast won't work either.
-        if sys.version_info >= (3, 8):
-            return ast3.parse(src, filename, type_comments=type_comments)
-        else:
-            return ast3.parse(src, filename)
-    else:
-        if type_comments:
-            # Typed-ast is guaranteed to be used here and automatically tracks type
-            # comments separately.
-            return ast3.parse(src, filename, feature_version=version[1])
-        else:
-            return ast.parse(src, filename)
+    return ast.parse(
+        src, filename, feature_version=version, type_comments=type_comments
+    )
 
 
-def parse_ast(src: str) -> Union[ast.AST, ast3.AST]:
+def parse_ast(src: str) -> ast.AST:
     # TODO: support Python 4+ ;)
     versions = [(3, minor) for minor in range(3, sys.version_info[1] + 1)]
 
@@ -193,9 +151,6 @@ def parse_ast(src: str) -> Union[ast.AST, ast3.AST]:
     raise SyntaxError(first_error)
 
 
-ast3_AST: Final[Type[ast3.AST]] = ast3.AST
-
-
 def _normalize(lineend: str, value: str) -> str:
     # To normalize, we strip any leading and trailing space from
     # each line...
@@ -206,23 +161,25 @@ def _normalize(lineend: str, value: str) -> str:
     return normalized.strip()
 
 
-def stringify_ast(node: Union[ast.AST, ast3.AST], depth: int = 0) -> Iterator[str]:
+def stringify_ast(node: ast.AST, depth: int = 0) -> Iterator[str]:
     """Simple visitor generating strings to compare ASTs by content."""
 
-    node = fixup_ast_constants(node)
+    if (
+        isinstance(node, ast.Constant)
+        and isinstance(node.value, str)
+        and node.kind == "u"
+    ):
+        # It's a quirk of history that we strip the u prefix over here. We used to
+        # rewrite the AST nodes for Python version compatibility and we never copied
+        # over the kind
+        node.kind = None
 
     yield f"{'  ' * depth}{node.__class__.__name__}("
 
-    type_ignore_classes: Tuple[Type[Any], ...]
     for field in sorted(node._fields):  # noqa: F402
-        # TypeIgnore will not be present using pypy < 3.8, so need for this
-        if not (_IS_PYPY and sys.version_info < (3, 8)):
-            # TypeIgnore has only one field 'lineno' which breaks this comparison
-            type_ignore_classes = (ast3.TypeIgnore,)
-            if sys.version_info >= (3, 8):
-                type_ignore_classes += (ast.TypeIgnore,)
-            if isinstance(node, type_ignore_classes):
-                break
+        # TypeIgnore has only one field 'lineno' which breaks this comparison
+        if isinstance(node, ast.TypeIgnore):
+            break
 
         try:
             value: object = getattr(node, field)
@@ -237,22 +194,16 @@ def stringify_ast(node: Union[ast.AST, ast3.AST], depth: int = 0) -> Iterator[st
                 # parentheses and they change the AST.
                 if (
                     field == "targets"
-                    and isinstance(node, (ast.Delete, ast3.Delete))
-                    and isinstance(item, (ast.Tuple, ast3.Tuple))
+                    and isinstance(node, ast.Delete)
+                    and isinstance(item, ast.Tuple)
                 ):
                     for elt in item.elts:
                         yield from stringify_ast(elt, depth + 2)
 
-                elif isinstance(item, (ast.AST, ast3.AST)):
+                elif isinstance(item, ast.AST):
                     yield from stringify_ast(item, depth + 2)
 
-        # Note that we are referencing the typed-ast ASTs via global variables and not
-        # direct module attribute accesses because that breaks mypyc. It's probably
-        # something to do with the ast3 variables being marked as Any leading
-        # mypy to think this branch is always taken, leaving the rest of the code
-        # unanalyzed. Tighting up the types for the typed-ast AST types avoids the
-        # mypyc crash.
-        elif isinstance(value, (ast.AST, ast3_AST)):
+        elif isinstance(value, ast.AST):
             yield from stringify_ast(value, depth + 2)
 
         else:
@@ -271,17 +222,3 @@ def stringify_ast(node: Union[ast.AST, ast3.AST], depth: int = 0) -> Iterator[st
             yield f"{'  ' * (depth+2)}{normalized!r},  # {value.__class__.__name__}"
 
     yield f"{'  ' * depth})  # /{node.__class__.__name__}"
-
-
-def fixup_ast_constants(node: Union[ast.AST, ast3.AST]) -> Union[ast.AST, ast3.AST]:
-    """Map ast nodes deprecated in 3.8 to Constant."""
-    if isinstance(node, (ast.Str, ast3.Str, ast.Bytes, ast3.Bytes)):
-        return ast.Constant(value=node.s)
-
-    if isinstance(node, (ast.Num, ast3.Num)):
-        return ast.Constant(value=node.n)
-
-    if isinstance(node, (ast.NameConstant, ast3.NameConstant)):
-        return ast.Constant(value=node.value)
-
-    return node
diff --git a/src/black/strings.py b/src/black/strings.py
index ac18aef51ed..0d30f09ed11 100644
--- a/src/black/strings.py
+++ b/src/black/strings.py
@@ -5,16 +5,10 @@
 import re
 import sys
 from functools import lru_cache
-from typing import List, Match, Pattern
-
-from blib2to3.pytree import Leaf
-
-if sys.version_info < (3, 8):
-    from typing_extensions import Final
-else:
-    from typing import Final
+from typing import Final, List, Match, Pattern
 
 from black._width_table import WIDTH_TABLE
+from blib2to3.pytree import Leaf
 
 STRING_PREFIX_CHARS: Final = "furbFURB"  # All possible string prefix characters.
 STRING_PREFIX_RE: Final = re.compile(
diff --git a/src/black/trans.py b/src/black/trans.py
index 4d40cb4bdf6..daed26427d7 100644
--- a/src/black/trans.py
+++ b/src/black/trans.py
@@ -2,7 +2,6 @@
 String transformers that can split and merge strings.
 """
 import re
-import sys
 from abc import ABC, abstractmethod
 from collections import defaultdict
 from dataclasses import dataclass
@@ -12,9 +11,11 @@
     ClassVar,
     Collection,
     Dict,
+    Final,
     Iterable,
     Iterator,
     List,
+    Literal,
     Optional,
     Sequence,
     Set,
@@ -23,11 +24,6 @@
     Union,
 )
 
-if sys.version_info < (3, 8):
-    from typing_extensions import Final, Literal
-else:
-    from typing import Literal, Final
-
 from mypy_extensions import trait
 
 from black.comments import contains_pragma_comment
diff --git a/src/blib2to3/pgen2/token.py b/src/blib2to3/pgen2/token.py
index 1e0dec9c714..c939531d7c8 100644
--- a/src/blib2to3/pgen2/token.py
+++ b/src/blib2to3/pgen2/token.py
@@ -3,10 +3,7 @@
 import sys
 from typing import Dict
 
-if sys.version_info < (3, 8):
-    from typing_extensions import Final
-else:
-    from typing import Final
+from typing import Final
 
 #  Taken from Python (r53757) and modified to include some tokens
 #   originally monkeypatched in by pgen2.tokenize
diff --git a/src/blib2to3/pgen2/tokenize.py b/src/blib2to3/pgen2/tokenize.py
index 2d0cc4324ce..a5e89188d87 100644
--- a/src/blib2to3/pgen2/tokenize.py
+++ b/src/blib2to3/pgen2/tokenize.py
@@ -42,10 +42,7 @@
     cast,
 )
 
-if sys.version_info >= (3, 8):
-    from typing import Final
-else:
-    from typing_extensions import Final
+from typing import Final
 
 from blib2to3.pgen2.token import *
 from blib2to3.pgen2.grammar import Grammar

From 4130c65578b9ac2a42b3b18f4f38917607db3500 Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Sun, 9 Jul 2023 08:14:38 -0700
Subject: [PATCH 0785/1034] Fix CI for Click typing issue (#3770)

https://github.com/pallets/click/issues/2558
---
 .github/workflows/diff_shades.yml | 4 ++--
 .pre-commit-config.yaml           | 2 +-
 pyproject.toml                    | 1 +
 3 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/diff_shades.yml b/.github/workflows/diff_shades.yml
index a126756f102..d685ef9456d 100644
--- a/.github/workflows/diff_shades.yml
+++ b/.github/workflows/diff_shades.yml
@@ -26,7 +26,7 @@ jobs:
 
       - name: Install diff-shades and support dependencies
         run: |
-          python -m pip install click packaging urllib3
+          python -m pip install 'click==8.1.3' packaging urllib3
           python -m pip install https://github.com/ichard26/diff-shades/archive/stable.zip
 
       - name: Calculate run configuration & metadata
@@ -64,7 +64,7 @@ jobs:
       - name: Install diff-shades and support dependencies
         run: |
           python -m pip install https://github.com/ichard26/diff-shades/archive/stable.zip
-          python -m pip install click packaging urllib3
+          python -m pip install 'click==8.1.3' packaging urllib3
           # After checking out old revisions, this might not exist so we'll use a copy.
           cat scripts/diff_shades_gha_helper.py > helper.py
           git config user.name "diff-shades-gha"
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index a69fb645238..bb647763e70 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -47,7 +47,7 @@ repos:
           - types-PyYAML
           - tomli >= 0.2.6, < 2.0.0
           - types-typed-ast >= 1.4.1
-          - click >= 8.1.0
+          - click >= 8.1.0, != 8.1.4
           - packaging >= 22.0
           - platformdirs >= 2.1.0
           - pytest
diff --git a/pyproject.toml b/pyproject.toml
index 2d8da88f6c6..175f7851dee 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -120,6 +120,7 @@ enable-by-default = false
 dependencies = [
   "hatch-mypyc>=0.16.0",
   "mypy==1.3",
+  "click==8.1.3",  # avoid https://github.com/pallets/click/issues/2558
 ]
 require-runtime-dependencies = true
 exclude = [

From 114e8357e65384e17baaa3c31aa528371e15679b Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Sun, 9 Jul 2023 13:29:47 -0700
Subject: [PATCH 0786/1034] Remove click patch (#3768)

Apparently this was only needed on Python 3.6. We've now dropped support
for 3.6 and 3.7. It's also not needed on new enough click.
---
 CHANGES.md                                    |  1 +
 .../reference/reference_functions.rst         |  2 --
 src/black/__init__.py                         | 35 -------------------
 src/blackd/__init__.py                        |  1 -
 tests/test_black.py                           | 24 -------------
 5 files changed, 1 insertion(+), 62 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 24ca54a82ac..1b0475fc7b9 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -43,6 +43,7 @@
 <!-- Changes to how Black is packaged, such as dependency requirements -->
 
 - Upgrade mypyc from 0.991 to 1.3 (#3697)
+- Remove patching of Click that mitigated errors on Python 3.6 with `LANG=C` (#3768)
 
 ### Parser
 
diff --git a/docs/contributing/reference/reference_functions.rst b/docs/contributing/reference/reference_functions.rst
index 3bda5de1774..09517f73961 100644
--- a/docs/contributing/reference/reference_functions.rst
+++ b/docs/contributing/reference/reference_functions.rst
@@ -165,8 +165,6 @@ Utilities
 
 .. autofunction:: black.linegen.normalize_invisible_parens
 
-.. autofunction:: black.patch_click
-
 .. autofunction:: black.nodes.preceding_leaf
 
 .. autofunction:: black.re_compile_maybe_verbose
diff --git a/src/black/__init__.py b/src/black/__init__.py
index b6611bef84b..301c18f7338 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -1410,40 +1410,6 @@ def nullcontext() -> Iterator[None]:
     yield
 
 
-def patch_click() -> None:
-    """Make Click not crash on Python 3.6 with LANG=C.
-
-    On certain misconfigured environments, Python 3 selects the ASCII encoding as the
-    default which restricts paths that it can access during the lifetime of the
-    application.  Click refuses to work in this scenario by raising a RuntimeError.
-
-    In case of Black the likelihood that non-ASCII characters are going to be used in
-    file paths is minimal since it's Python source code.  Moreover, this crash was
-    spurious on Python 3.7 thanks to PEP 538 and PEP 540.
-    """
-    modules: List[Any] = []
-    try:
-        from click import core
-    except ImportError:
-        pass
-    else:
-        modules.append(core)
-    try:
-        # Removed in Click 8.1.0 and newer; we keep this around for users who have
-        # older versions installed.
-        from click import _unicodefun  # type: ignore
-    except ImportError:
-        pass
-    else:
-        modules.append(_unicodefun)
-
-    for module in modules:
-        if hasattr(module, "_verify_python3_env"):
-            module._verify_python3_env = lambda: None
-        if hasattr(module, "_verify_python_env"):
-            module._verify_python_env = lambda: None
-
-
 def patched_main() -> None:
     # PyInstaller patches multiprocessing to need freeze_support() even in non-Windows
     # environments so just assume we always need to call it if frozen.
@@ -1452,7 +1418,6 @@ def patched_main() -> None:
 
         freeze_support()
 
-    patch_click()
     main()
 
 
diff --git a/src/blackd/__init__.py b/src/blackd/__init__.py
index c1b69feed63..4f2d87d0fca 100644
--- a/src/blackd/__init__.py
+++ b/src/blackd/__init__.py
@@ -225,7 +225,6 @@ def parse_python_variant_header(value: str) -> Tuple[bool, Set[black.TargetVersi
 def patched_main() -> None:
     maybe_install_uvloop()
     freeze_support()
-    black.patch_click()
     main()
 
 
diff --git a/tests/test_black.py b/tests/test_black.py
index dee6ead50d0..dd21d0a7ae6 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -1455,30 +1455,6 @@ def test_assert_equivalent_different_asts(self) -> None:
         with self.assertRaises(AssertionError):
             black.assert_equivalent("{}", "None")
 
-    def test_shhh_click(self) -> None:
-        try:
-            from click import _unicodefun  # type: ignore
-        except ImportError:
-            self.skipTest("Incompatible Click version")
-
-        if not hasattr(_unicodefun, "_verify_python_env"):
-            self.skipTest("Incompatible Click version")
-
-        # First, let's see if Click is crashing with a preferred ASCII charset.
-        with patch("locale.getpreferredencoding") as gpe:
-            gpe.return_value = "ASCII"
-            with self.assertRaises(RuntimeError):
-                _unicodefun._verify_python_env()
-        # Now, let's silence Click...
-        black.patch_click()
-        # ...and confirm it's silent.
-        with patch("locale.getpreferredencoding") as gpe:
-            gpe.return_value = "ASCII"
-            try:
-                _unicodefun._verify_python_env()
-            except RuntimeError as re:
-                self.fail(f"`patch_click()` failed, exception still raised: {re}")
-
     def test_root_logger_not_used_directly(self) -> None:
         def fail(*args: Any, **kwargs: Any) -> None:
             self.fail("Record created with root logger")

From 0b4d7d55f78913be9e0a3738681ef3aafd5d9a5a Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Sun, 9 Jul 2023 15:05:01 -0700
Subject: [PATCH 0787/1034] Run pyupgrade on blib2to3 and src (#3771)

---
 src/black/files.py               |  6 +--
 src/black/handle_ipynb_magics.py |  2 +-
 src/blib2to3/pgen2/conv.py       |  6 +--
 src/blib2to3/pgen2/driver.py     | 29 +++++++-------
 src/blib2to3/pgen2/grammar.py    |  6 +--
 src/blib2to3/pgen2/literals.py   |  8 ++--
 src/blib2to3/pgen2/parse.py      | 22 +++++------
 src/blib2to3/pgen2/pgen.py       | 35 ++++++++---------
 src/blib2to3/pgen2/token.py      |  3 +-
 src/blib2to3/pgen2/tokenize.py   | 27 +++++++------
 src/blib2to3/pygram.py           |  3 +-
 src/blib2to3/pytree.py           | 67 ++++++++++++++++----------------
 12 files changed, 102 insertions(+), 112 deletions(-)

diff --git a/src/black/files.py b/src/black/files.py
index 65b2d0a8402..4e2209e557d 100644
--- a/src/black/files.py
+++ b/src/black/files.py
@@ -42,7 +42,7 @@
     import colorama  # noqa: F401
 
 
-@lru_cache()
+@lru_cache
 def find_project_root(
     srcs: Sequence[str], stdin_filename: Optional[str] = None
 ) -> Tuple[Path, str]:
@@ -212,7 +212,7 @@ def strip_specifier_set(specifier_set: SpecifierSet) -> SpecifierSet:
     return SpecifierSet(",".join(str(s) for s in specifiers))
 
 
-@lru_cache()
+@lru_cache
 def find_user_pyproject_toml() -> Path:
     r"""Return the path to the top-level user configuration for black.
 
@@ -232,7 +232,7 @@ def find_user_pyproject_toml() -> Path:
     return user_config_path.resolve()
 
 
-@lru_cache()
+@lru_cache
 def get_gitignore(root: Path) -> PathSpec:
     """Return a PathSpec matching gitignore content if present."""
     gitignore = root / ".gitignore"
diff --git a/src/black/handle_ipynb_magics.py b/src/black/handle_ipynb_magics.py
index 4324819beaf..2a2d62220e2 100644
--- a/src/black/handle_ipynb_magics.py
+++ b/src/black/handle_ipynb_magics.py
@@ -55,7 +55,7 @@ class Replacement:
     src: str
 
 
-@lru_cache()
+@lru_cache
 def jupyter_dependencies_are_installed(*, verbose: bool, quiet: bool) -> bool:
     try:
         # isort: off
diff --git a/src/blib2to3/pgen2/conv.py b/src/blib2to3/pgen2/conv.py
index fa9825e54d6..04eccfa1d4b 100644
--- a/src/blib2to3/pgen2/conv.py
+++ b/src/blib2to3/pgen2/conv.py
@@ -63,7 +63,7 @@ def parse_graminit_h(self, filename):
         try:
             f = open(filename)
         except OSError as err:
-            print("Can't open %s: %s" % (filename, err))
+            print(f"Can't open {filename}: {err}")
             return False
         self.symbol2number = {}
         self.number2symbol = {}
@@ -72,7 +72,7 @@ def parse_graminit_h(self, filename):
             lineno += 1
             mo = re.match(r"^#define\s+(\w+)\s+(\d+)$", line)
             if not mo and line.strip():
-                print("%s(%s): can't parse %s" % (filename, lineno, line.strip()))
+                print(f"{filename}({lineno}): can't parse {line.strip()}")
             else:
                 symbol, number = mo.groups()
                 number = int(number)
@@ -113,7 +113,7 @@ def parse_graminit_c(self, filename):
         try:
             f = open(filename)
         except OSError as err:
-            print("Can't open %s: %s" % (filename, err))
+            print(f"Can't open {filename}: {err}")
             return False
         # The code below essentially uses f's iterator-ness!
         lineno = 0
diff --git a/src/blib2to3/pgen2/driver.py b/src/blib2to3/pgen2/driver.py
index 1741b33c510..bb73016a4c1 100644
--- a/src/blib2to3/pgen2/driver.py
+++ b/src/blib2to3/pgen2/driver.py
@@ -28,11 +28,8 @@
     Iterable,
     List,
     Optional,
-    Text,
     Iterator,
     Tuple,
-    TypeVar,
-    Generic,
     Union,
 )
 from contextlib import contextmanager
@@ -116,7 +113,7 @@ def can_advance(self, to: int) -> bool:
             return True
 
 
-class Driver(object):
+class Driver:
     def __init__(self, grammar: Grammar, logger: Optional[Logger] = None) -> None:
         self.grammar = grammar
         if logger is None:
@@ -189,30 +186,30 @@ def parse_tokens(self, tokens: Iterable[GoodTokenInfo], debug: bool = False) ->
         assert p.rootnode is not None
         return p.rootnode
 
-    def parse_stream_raw(self, stream: IO[Text], debug: bool = False) -> NL:
+    def parse_stream_raw(self, stream: IO[str], debug: bool = False) -> NL:
         """Parse a stream and return the syntax tree."""
         tokens = tokenize.generate_tokens(stream.readline, grammar=self.grammar)
         return self.parse_tokens(tokens, debug)
 
-    def parse_stream(self, stream: IO[Text], debug: bool = False) -> NL:
+    def parse_stream(self, stream: IO[str], debug: bool = False) -> NL:
         """Parse a stream and return the syntax tree."""
         return self.parse_stream_raw(stream, debug)
 
     def parse_file(
-        self, filename: Path, encoding: Optional[Text] = None, debug: bool = False
+        self, filename: Path, encoding: Optional[str] = None, debug: bool = False
     ) -> NL:
         """Parse a file and return the syntax tree."""
-        with io.open(filename, "r", encoding=encoding) as stream:
+        with open(filename, encoding=encoding) as stream:
             return self.parse_stream(stream, debug)
 
-    def parse_string(self, text: Text, debug: bool = False) -> NL:
+    def parse_string(self, text: str, debug: bool = False) -> NL:
         """Parse a string and return the syntax tree."""
         tokens = tokenize.generate_tokens(
             io.StringIO(text).readline, grammar=self.grammar
         )
         return self.parse_tokens(tokens, debug)
 
-    def _partially_consume_prefix(self, prefix: Text, column: int) -> Tuple[Text, Text]:
+    def _partially_consume_prefix(self, prefix: str, column: int) -> Tuple[str, str]:
         lines: List[str] = []
         current_line = ""
         current_column = 0
@@ -240,7 +237,7 @@ def _partially_consume_prefix(self, prefix: Text, column: int) -> Tuple[Text, Te
         return "".join(lines), current_line
 
 
-def _generate_pickle_name(gt: Path, cache_dir: Optional[Path] = None) -> Text:
+def _generate_pickle_name(gt: Path, cache_dir: Optional[Path] = None) -> str:
     head, tail = os.path.splitext(gt)
     if tail == ".txt":
         tail = ""
@@ -252,8 +249,8 @@ def _generate_pickle_name(gt: Path, cache_dir: Optional[Path] = None) -> Text:
 
 
 def load_grammar(
-    gt: Text = "Grammar.txt",
-    gp: Optional[Text] = None,
+    gt: str = "Grammar.txt",
+    gp: Optional[str] = None,
     save: bool = True,
     force: bool = False,
     logger: Optional[Logger] = None,
@@ -276,7 +273,7 @@ def load_grammar(
     return g
 
 
-def _newer(a: Text, b: Text) -> bool:
+def _newer(a: str, b: str) -> bool:
     """Inquire whether file a was written since file b."""
     if not os.path.exists(a):
         return False
@@ -286,7 +283,7 @@ def _newer(a: Text, b: Text) -> bool:
 
 
 def load_packaged_grammar(
-    package: str, grammar_source: Text, cache_dir: Optional[Path] = None
+    package: str, grammar_source: str, cache_dir: Optional[Path] = None
 ) -> grammar.Grammar:
     """Normally, loads a pickled grammar by doing
         pkgutil.get_data(package, pickled_grammar)
@@ -309,7 +306,7 @@ def load_packaged_grammar(
     return g
 
 
-def main(*args: Text) -> bool:
+def main(*args: str) -> bool:
     """Main program, when run as a script: produce grammar pickle files.
 
     Calls load_grammar for each argument, a path to a grammar text file.
diff --git a/src/blib2to3/pgen2/grammar.py b/src/blib2to3/pgen2/grammar.py
index 337a64f1726..1f3fdc55b97 100644
--- a/src/blib2to3/pgen2/grammar.py
+++ b/src/blib2to3/pgen2/grammar.py
@@ -16,19 +16,19 @@
 import os
 import pickle
 import tempfile
-from typing import Any, Dict, List, Optional, Text, Tuple, TypeVar, Union
+from typing import Any, Dict, List, Optional, Tuple, TypeVar, Union
 
 # Local imports
 from . import token
 
 _P = TypeVar("_P", bound="Grammar")
-Label = Tuple[int, Optional[Text]]
+Label = Tuple[int, Optional[str]]
 DFA = List[List[Tuple[int, int]]]
 DFAS = Tuple[DFA, Dict[int, int]]
 Path = Union[str, "os.PathLike[str]"]
 
 
-class Grammar(object):
+class Grammar:
     """Pgen parsing tables conversion class.
 
     Once initialized, this class supplies the grammar tables for the
diff --git a/src/blib2to3/pgen2/literals.py b/src/blib2to3/pgen2/literals.py
index b5fe4285114..c67b91d0463 100644
--- a/src/blib2to3/pgen2/literals.py
+++ b/src/blib2to3/pgen2/literals.py
@@ -5,10 +5,10 @@
 
 import re
 
-from typing import Dict, Match, Text
+from typing import Dict, Match
 
 
-simple_escapes: Dict[Text, Text] = {
+simple_escapes: Dict[str, str] = {
     "a": "\a",
     "b": "\b",
     "f": "\f",
@@ -22,7 +22,7 @@
 }
 
 
-def escape(m: Match[Text]) -> Text:
+def escape(m: Match[str]) -> str:
     all, tail = m.group(0, 1)
     assert all.startswith("\\")
     esc = simple_escapes.get(tail)
@@ -44,7 +44,7 @@ def escape(m: Match[Text]) -> Text:
     return chr(i)
 
 
-def evalString(s: Text) -> Text:
+def evalString(s: str) -> str:
     assert s.startswith("'") or s.startswith('"'), repr(s[:1])
     q = s[0]
     if s[:3] == q * 3:
diff --git a/src/blib2to3/pgen2/parse.py b/src/blib2to3/pgen2/parse.py
index c462f63ad2c..17bf118e9fc 100644
--- a/src/blib2to3/pgen2/parse.py
+++ b/src/blib2to3/pgen2/parse.py
@@ -9,7 +9,6 @@
 how this parsing engine works.
 
 """
-import copy
 from contextlib import contextmanager
 
 # Local imports
@@ -18,7 +17,6 @@
     cast,
     Any,
     Optional,
-    Text,
     Union,
     Tuple,
     Dict,
@@ -35,7 +33,7 @@
     from blib2to3.pgen2.driver import TokenProxy
 
 
-Results = Dict[Text, NL]
+Results = Dict[str, NL]
 Convert = Callable[[Grammar, RawNode], Union[Node, Leaf]]
 DFA = List[List[Tuple[int, int]]]
 DFAS = Tuple[DFA, Dict[int, int]]
@@ -100,7 +98,7 @@ def backtrack(self) -> Iterator[None]:
         finally:
             self.parser.is_backtracking = is_backtracking
 
-    def add_token(self, tok_type: int, tok_val: Text, raw: bool = False) -> None:
+    def add_token(self, tok_type: int, tok_val: str, raw: bool = False) -> None:
         func: Callable[..., Any]
         if raw:
             func = self.parser._addtoken
@@ -114,7 +112,7 @@ def add_token(self, tok_type: int, tok_val: Text, raw: bool = False) -> None:
                     args.insert(0, ilabel)
                 func(*args)
 
-    def determine_route(self, value: Optional[Text] = None, force: bool = False) -> Optional[int]:
+    def determine_route(self, value: Optional[str] = None, force: bool = False) -> Optional[int]:
         alive_ilabels = self.ilabels
         if len(alive_ilabels) == 0:
             *_, most_successful_ilabel = self._dead_ilabels
@@ -131,10 +129,10 @@ class ParseError(Exception):
     """Exception to signal the parser is stuck."""
 
     def __init__(
-        self, msg: Text, type: Optional[int], value: Optional[Text], context: Context
+        self, msg: str, type: Optional[int], value: Optional[str], context: Context
     ) -> None:
         Exception.__init__(
-            self, "%s: type=%r, value=%r, context=%r" % (msg, type, value, context)
+            self, f"{msg}: type={type!r}, value={value!r}, context={context!r}"
         )
         self.msg = msg
         self.type = type
@@ -142,7 +140,7 @@ def __init__(
         self.context = context
 
 
-class Parser(object):
+class Parser:
     """Parser engine.
 
     The proper usage sequence is:
@@ -236,7 +234,7 @@ def setup(self, proxy: "TokenProxy", start: Optional[int] = None) -> None:
         self.used_names: Set[str] = set()
         self.proxy = proxy
 
-    def addtoken(self, type: int, value: Text, context: Context) -> bool:
+    def addtoken(self, type: int, value: str, context: Context) -> bool:
         """Add a token; return True iff this is the end of the program."""
         # Map from token to label
         ilabels = self.classify(type, value, context)
@@ -284,7 +282,7 @@ def addtoken(self, type: int, value: Text, context: Context) -> bool:
 
         return self._addtoken(ilabel, type, value, context)
 
-    def _addtoken(self, ilabel: int, type: int, value: Text, context: Context) -> bool:
+    def _addtoken(self, ilabel: int, type: int, value: str, context: Context) -> bool:
         # Loop until the token is shifted; may raise exceptions
         while True:
             dfa, state, node = self.stack[-1]
@@ -329,7 +327,7 @@ def _addtoken(self, ilabel: int, type: int, value: Text, context: Context) -> bo
                     # No success finding a transition
                     raise ParseError("bad input", type, value, context)
 
-    def classify(self, type: int, value: Text, context: Context) -> List[int]:
+    def classify(self, type: int, value: str, context: Context) -> List[int]:
         """Turn a token into a label.  (Internal)
 
         Depending on whether the value is a soft-keyword or not,
@@ -352,7 +350,7 @@ def classify(self, type: int, value: Text, context: Context) -> List[int]:
             raise ParseError("bad token", type, value, context)
         return [ilabel]
 
-    def shift(self, type: int, value: Text, newstate: int, context: Context) -> None:
+    def shift(self, type: int, value: str, newstate: int, context: Context) -> None:
         """Shift a token.  (Internal)"""
         if self.is_backtracking:
             dfa, state, _ = self.stack[-1]
diff --git a/src/blib2to3/pgen2/pgen.py b/src/blib2to3/pgen2/pgen.py
index b5ebc7b3e42..046efd09338 100644
--- a/src/blib2to3/pgen2/pgen.py
+++ b/src/blib2to3/pgen2/pgen.py
@@ -11,7 +11,6 @@
     Iterator,
     List,
     Optional,
-    Text,
     Tuple,
     Union,
     Sequence,
@@ -29,13 +28,13 @@ class PgenGrammar(grammar.Grammar):
     pass
 
 
-class ParserGenerator(object):
+class ParserGenerator:
     filename: Path
-    stream: IO[Text]
+    stream: IO[str]
     generator: Iterator[GoodTokenInfo]
-    first: Dict[Text, Optional[Dict[Text, int]]]
+    first: Dict[str, Optional[Dict[str, int]]]
 
-    def __init__(self, filename: Path, stream: Optional[IO[Text]] = None) -> None:
+    def __init__(self, filename: Path, stream: Optional[IO[str]] = None) -> None:
         close_stream = None
         if stream is None:
             stream = open(filename, encoding="utf-8")
@@ -75,7 +74,7 @@ def make_grammar(self) -> PgenGrammar:
         c.start = c.symbol2number[self.startsymbol]
         return c
 
-    def make_first(self, c: PgenGrammar, name: Text) -> Dict[int, int]:
+    def make_first(self, c: PgenGrammar, name: str) -> Dict[int, int]:
         rawfirst = self.first[name]
         assert rawfirst is not None
         first = {}
@@ -85,7 +84,7 @@ def make_first(self, c: PgenGrammar, name: Text) -> Dict[int, int]:
             first[ilabel] = 1
         return first
 
-    def make_label(self, c: PgenGrammar, label: Text) -> int:
+    def make_label(self, c: PgenGrammar, label: str) -> int:
         # XXX Maybe this should be a method on a subclass of converter?
         ilabel = len(c.labels)
         if label[0].isalpha():
@@ -144,7 +143,7 @@ def addfirstsets(self) -> None:
                 self.calcfirst(name)
             # print name, self.first[name].keys()
 
-    def calcfirst(self, name: Text) -> None:
+    def calcfirst(self, name: str) -> None:
         dfa = self.dfas[name]
         self.first[name] = None  # dummy to detect left recursion
         state = dfa[0]
@@ -176,7 +175,7 @@ def calcfirst(self, name: Text) -> None:
                 inverse[symbol] = label
         self.first[name] = totalset
 
-    def parse(self) -> Tuple[Dict[Text, List["DFAState"]], Text]:
+    def parse(self) -> Tuple[Dict[str, List["DFAState"]], str]:
         dfas = {}
         startsymbol: Optional[str] = None
         # MSTART: (NEWLINE | RULE)* ENDMARKER
@@ -240,7 +239,7 @@ def addclosure(state: NFAState, base: Dict[NFAState, int]) -> None:
                 state.addarc(st, label)
         return states  # List of DFAState instances; first one is start
 
-    def dump_nfa(self, name: Text, start: "NFAState", finish: "NFAState") -> None:
+    def dump_nfa(self, name: str, start: "NFAState", finish: "NFAState") -> None:
         print("Dump of NFA for", name)
         todo = [start]
         for i, state in enumerate(todo):
@@ -256,7 +255,7 @@ def dump_nfa(self, name: Text, start: "NFAState", finish: "NFAState") -> None:
                 else:
                     print("    %s -> %d" % (label, j))
 
-    def dump_dfa(self, name: Text, dfa: Sequence["DFAState"]) -> None:
+    def dump_dfa(self, name: str, dfa: Sequence["DFAState"]) -> None:
         print("Dump of DFA for", name)
         for i, state in enumerate(dfa):
             print("  State", i, state.isfinal and "(final)" or "")
@@ -349,7 +348,7 @@ def parse_atom(self) -> Tuple["NFAState", "NFAState"]:
             )
             assert False
 
-    def expect(self, type: int, value: Optional[Any] = None) -> Text:
+    def expect(self, type: int, value: Optional[Any] = None) -> str:
         if self.type != type or (value is not None and self.value != value):
             self.raise_error(
                 "expected %s/%s, got %s/%s", type, value, self.type, self.value
@@ -374,22 +373,22 @@ def raise_error(self, msg: str, *args: Any) -> NoReturn:
         raise SyntaxError(msg, (self.filename, self.end[0], self.end[1], self.line))
 
 
-class NFAState(object):
-    arcs: List[Tuple[Optional[Text], "NFAState"]]
+class NFAState:
+    arcs: List[Tuple[Optional[str], "NFAState"]]
 
     def __init__(self) -> None:
         self.arcs = []  # list of (label, NFAState) pairs
 
-    def addarc(self, next: "NFAState", label: Optional[Text] = None) -> None:
+    def addarc(self, next: "NFAState", label: Optional[str] = None) -> None:
         assert label is None or isinstance(label, str)
         assert isinstance(next, NFAState)
         self.arcs.append((label, next))
 
 
-class DFAState(object):
+class DFAState:
     nfaset: Dict[NFAState, Any]
     isfinal: bool
-    arcs: Dict[Text, "DFAState"]
+    arcs: Dict[str, "DFAState"]
 
     def __init__(self, nfaset: Dict[NFAState, Any], final: NFAState) -> None:
         assert isinstance(nfaset, dict)
@@ -399,7 +398,7 @@ def __init__(self, nfaset: Dict[NFAState, Any], final: NFAState) -> None:
         self.isfinal = final in nfaset
         self.arcs = {}  # map from label to DFAState
 
-    def addarc(self, next: "DFAState", label: Text) -> None:
+    def addarc(self, next: "DFAState", label: str) -> None:
         assert isinstance(label, str)
         assert label not in self.arcs
         assert isinstance(next, DFAState)
diff --git a/src/blib2to3/pgen2/token.py b/src/blib2to3/pgen2/token.py
index c939531d7c8..117cc09d4ce 100644
--- a/src/blib2to3/pgen2/token.py
+++ b/src/blib2to3/pgen2/token.py
@@ -1,6 +1,5 @@
 """Token constants (from "token.h")."""
 
-import sys
 from typing import Dict
 
 from typing import Final
@@ -75,7 +74,7 @@
 
 tok_name: Final[Dict[int, str]] = {}
 for _name, _value in list(globals().items()):
-    if type(_value) is type(0):
+    if type(_value) is int:
         tok_name[_value] = _name
 
 
diff --git a/src/blib2to3/pgen2/tokenize.py b/src/blib2to3/pgen2/tokenize.py
index a5e89188d87..1dea89d7bb8 100644
--- a/src/blib2to3/pgen2/tokenize.py
+++ b/src/blib2to3/pgen2/tokenize.py
@@ -35,7 +35,6 @@
     List,
     Optional,
     Set,
-    Text,
     Tuple,
     Pattern,
     Union,
@@ -77,7 +76,7 @@ def maybe(*choices: str) -> str:
 
 
 def _combinations(*l: str) -> Set[str]:
-    return set(x + y for x in l for y in l + ("",) if x.casefold() != y.casefold())
+    return {x + y for x in l for y in l + ("",) if x.casefold() != y.casefold()}
 
 
 Whitespace = r"[ \f\t]*"
@@ -189,7 +188,7 @@ class StopTokenizing(Exception):
 
 
 def printtoken(
-    type: int, token: Text, srow_col: Coord, erow_col: Coord, line: Text
+    type: int, token: str, srow_col: Coord, erow_col: Coord, line: str
 ) -> None:  # for testing
     (srow, scol) = srow_col
     (erow, ecol) = erow_col
@@ -198,10 +197,10 @@ def printtoken(
     )
 
 
-TokenEater = Callable[[int, Text, Coord, Coord, Text], None]
+TokenEater = Callable[[int, str, Coord, Coord, str], None]
 
 
-def tokenize(readline: Callable[[], Text], tokeneater: TokenEater = printtoken) -> None:
+def tokenize(readline: Callable[[], str], tokeneater: TokenEater = printtoken) -> None:
     """
     The tokenize() function accepts two parameters: one representing the
     input stream, and one providing an output mechanism for tokenize().
@@ -221,17 +220,17 @@ def tokenize(readline: Callable[[], Text], tokeneater: TokenEater = printtoken)
 
 
 # backwards compatible interface
-def tokenize_loop(readline: Callable[[], Text], tokeneater: TokenEater) -> None:
+def tokenize_loop(readline: Callable[[], str], tokeneater: TokenEater) -> None:
     for token_info in generate_tokens(readline):
         tokeneater(*token_info)
 
 
-GoodTokenInfo = Tuple[int, Text, Coord, Coord, Text]
+GoodTokenInfo = Tuple[int, str, Coord, Coord, str]
 TokenInfo = Union[Tuple[int, str], GoodTokenInfo]
 
 
 class Untokenizer:
-    tokens: List[Text]
+    tokens: List[str]
     prev_row: int
     prev_col: int
 
@@ -247,13 +246,13 @@ def add_whitespace(self, start: Coord) -> None:
         if col_offset:
             self.tokens.append(" " * col_offset)
 
-    def untokenize(self, iterable: Iterable[TokenInfo]) -> Text:
+    def untokenize(self, iterable: Iterable[TokenInfo]) -> str:
         for t in iterable:
             if len(t) == 2:
                 self.compat(cast(Tuple[int, str], t), iterable)
                 break
             tok_type, token, start, end, line = cast(
-                Tuple[int, Text, Coord, Coord, Text], t
+                Tuple[int, str, Coord, Coord, str], t
             )
             self.add_whitespace(start)
             self.tokens.append(token)
@@ -263,7 +262,7 @@ def untokenize(self, iterable: Iterable[TokenInfo]) -> Text:
                 self.prev_col = 0
         return "".join(self.tokens)
 
-    def compat(self, token: Tuple[int, Text], iterable: Iterable[TokenInfo]) -> None:
+    def compat(self, token: Tuple[int, str], iterable: Iterable[TokenInfo]) -> None:
         startline = False
         indents = []
         toks_append = self.tokens.append
@@ -335,7 +334,7 @@ def read_or_stop() -> bytes:
         try:
             return readline()
         except StopIteration:
-            return bytes()
+            return b''
 
     def find_cookie(line: bytes) -> Optional[str]:
         try:
@@ -384,7 +383,7 @@ def find_cookie(line: bytes) -> Optional[str]:
     return default, [first, second]
 
 
-def untokenize(iterable: Iterable[TokenInfo]) -> Text:
+def untokenize(iterable: Iterable[TokenInfo]) -> str:
     """Transform tokens back into Python source code.
 
     Each element returned by the iterable must be a token sequence
@@ -407,7 +406,7 @@ def untokenize(iterable: Iterable[TokenInfo]) -> Text:
 
 
 def generate_tokens(
-    readline: Callable[[], Text], grammar: Optional[Grammar] = None
+    readline: Callable[[], str], grammar: Optional[Grammar] = None
 ) -> Iterator[GoodTokenInfo]:
     """
     The generate_tokens() generator requires one argument, readline, which
diff --git a/src/blib2to3/pygram.py b/src/blib2to3/pygram.py
index 15702e4059e..1b4832362bf 100644
--- a/src/blib2to3/pygram.py
+++ b/src/blib2to3/pygram.py
@@ -9,7 +9,6 @@
 from typing import Union
 
 # Local imports
-from .pgen2 import token
 from .pgen2 import driver
 
 from .pgen2.grammar import Grammar
@@ -21,7 +20,7 @@
 #                                      "PatternGrammar.txt")
 
 
-class Symbols(object):
+class Symbols:
     def __init__(self, grammar: Grammar) -> None:
         """Initializer.
 
diff --git a/src/blib2to3/pytree.py b/src/blib2to3/pytree.py
index ea60c894e20..156322cab7e 100644
--- a/src/blib2to3/pytree.py
+++ b/src/blib2to3/pytree.py
@@ -18,7 +18,6 @@
     Iterator,
     List,
     Optional,
-    Text,
     Tuple,
     TypeVar,
     Union,
@@ -34,10 +33,10 @@
 
 HUGE: int = 0x7FFFFFFF  # maximum repeat count, default max
 
-_type_reprs: Dict[int, Union[Text, int]] = {}
+_type_reprs: Dict[int, Union[str, int]] = {}
 
 
-def type_repr(type_num: int) -> Union[Text, int]:
+def type_repr(type_num: int) -> Union[str, int]:
     global _type_reprs
     if not _type_reprs:
         from .pygram import python_symbols
@@ -54,11 +53,11 @@ def type_repr(type_num: int) -> Union[Text, int]:
 _P = TypeVar("_P", bound="Base")
 
 NL = Union["Node", "Leaf"]
-Context = Tuple[Text, Tuple[int, int]]
-RawNode = Tuple[int, Optional[Text], Optional[Context], Optional[List[NL]]]
+Context = Tuple[str, Tuple[int, int]]
+RawNode = Tuple[int, Optional[str], Optional[Context], Optional[List[NL]]]
 
 
-class Base(object):
+class Base:
 
     """
     Abstract base class for Node and Leaf.
@@ -92,7 +91,7 @@ def __eq__(self, other: Any) -> bool:
         return self._eq(other)
 
     @property
-    def prefix(self) -> Text:
+    def prefix(self) -> str:
         raise NotImplementedError
 
     def _eq(self: _P, other: _P) -> bool:
@@ -225,7 +224,7 @@ def depth(self) -> int:
             return 0
         return 1 + self.parent.depth()
 
-    def get_suffix(self) -> Text:
+    def get_suffix(self) -> str:
         """
         Return the string immediately following the invocant node. This is
         effectively equivalent to node.next_sibling.prefix
@@ -242,14 +241,14 @@ class Node(Base):
     """Concrete implementation for interior nodes."""
 
     fixers_applied: Optional[List[Any]]
-    used_names: Optional[Set[Text]]
+    used_names: Optional[Set[str]]
 
     def __init__(
         self,
         type: int,
         children: List[NL],
         context: Optional[Any] = None,
-        prefix: Optional[Text] = None,
+        prefix: Optional[str] = None,
         fixers_applied: Optional[List[Any]] = None,
     ) -> None:
         """
@@ -274,16 +273,16 @@ def __init__(
         else:
             self.fixers_applied = None
 
-    def __repr__(self) -> Text:
+    def __repr__(self) -> str:
         """Return a canonical string representation."""
         assert self.type is not None
-        return "%s(%s, %r)" % (
+        return "{}({}, {!r})".format(
             self.__class__.__name__,
             type_repr(self.type),
             self.children,
         )
 
-    def __str__(self) -> Text:
+    def __str__(self) -> str:
         """
         Return a pretty string representation.
 
@@ -317,7 +316,7 @@ def pre_order(self) -> Iterator[NL]:
             yield from child.pre_order()
 
     @property
-    def prefix(self) -> Text:
+    def prefix(self) -> str:
         """
         The whitespace and comments preceding this node in the input.
         """
@@ -326,7 +325,7 @@ def prefix(self) -> Text:
         return self.children[0].prefix
 
     @prefix.setter
-    def prefix(self, prefix: Text) -> None:
+    def prefix(self, prefix: str) -> None:
         if self.children:
             self.children[0].prefix = prefix
 
@@ -383,12 +382,12 @@ class Leaf(Base):
     """Concrete implementation for leaf nodes."""
 
     # Default values for instance variables
-    value: Text
+    value: str
     fixers_applied: List[Any]
     bracket_depth: int
     # Changed later in brackets.py
     opening_bracket: Optional["Leaf"] = None
-    used_names: Optional[Set[Text]]
+    used_names: Optional[Set[str]]
     _prefix = ""  # Whitespace and comments preceding this token in the input
     lineno: int = 0  # Line where this token starts in the input
     column: int = 0  # Column where this token starts in the input
@@ -400,9 +399,9 @@ class Leaf(Base):
     def __init__(
         self,
         type: int,
-        value: Text,
+        value: str,
         context: Optional[Context] = None,
-        prefix: Optional[Text] = None,
+        prefix: Optional[str] = None,
         fixers_applied: List[Any] = [],
         opening_bracket: Optional["Leaf"] = None,
         fmt_pass_converted_first_leaf: Optional["Leaf"] = None,
@@ -431,13 +430,13 @@ def __repr__(self) -> str:
         from .pgen2.token import tok_name
 
         assert self.type is not None
-        return "%s(%s, %r)" % (
+        return "{}({}, {!r})".format(
             self.__class__.__name__,
             tok_name.get(self.type, self.type),
             self.value,
         )
 
-    def __str__(self) -> Text:
+    def __str__(self) -> str:
         """
         Return a pretty string representation.
 
@@ -471,14 +470,14 @@ def pre_order(self) -> Iterator["Leaf"]:
         yield self
 
     @property
-    def prefix(self) -> Text:
+    def prefix(self) -> str:
         """
         The whitespace and comments preceding this token in the input.
         """
         return self._prefix
 
     @prefix.setter
-    def prefix(self, prefix: Text) -> None:
+    def prefix(self, prefix: str) -> None:
         self.changed()
         self._prefix = prefix
 
@@ -503,10 +502,10 @@ def convert(gr: Grammar, raw_node: RawNode) -> NL:
         return Leaf(type, value or "", context=context)
 
 
-_Results = Dict[Text, NL]
+_Results = Dict[str, NL]
 
 
-class BasePattern(object):
+class BasePattern:
 
     """
     A pattern is a tree matching pattern.
@@ -526,19 +525,19 @@ class BasePattern(object):
     type: Optional[int]
     type = None  # Node type (token if < 256, symbol if >= 256)
     content: Any = None  # Optional content matching pattern
-    name: Optional[Text] = None  # Optional name used to store match in results dict
+    name: Optional[str] = None  # Optional name used to store match in results dict
 
     def __new__(cls, *args, **kwds):
         """Constructor that prevents BasePattern from being instantiated."""
         assert cls is not BasePattern, "Cannot instantiate BasePattern"
         return object.__new__(cls)
 
-    def __repr__(self) -> Text:
+    def __repr__(self) -> str:
         assert self.type is not None
         args = [type_repr(self.type), self.content, self.name]
         while args and args[-1] is None:
             del args[-1]
-        return "%s(%s)" % (self.__class__.__name__, ", ".join(map(repr, args)))
+        return "{}({})".format(self.__class__.__name__, ", ".join(map(repr, args)))
 
     def _submatch(self, node, results=None) -> bool:
         raise NotImplementedError
@@ -602,8 +601,8 @@ class LeafPattern(BasePattern):
     def __init__(
         self,
         type: Optional[int] = None,
-        content: Optional[Text] = None,
-        name: Optional[Text] = None,
+        content: Optional[str] = None,
+        name: Optional[str] = None,
     ) -> None:
         """
         Initializer.  Takes optional type, content, and name.
@@ -653,8 +652,8 @@ class NodePattern(BasePattern):
     def __init__(
         self,
         type: Optional[int] = None,
-        content: Optional[Iterable[Text]] = None,
-        name: Optional[Text] = None,
+        content: Optional[Iterable[str]] = None,
+        name: Optional[str] = None,
     ) -> None:
         """
         Initializer.  Takes optional type, content, and name.
@@ -734,10 +733,10 @@ class WildcardPattern(BasePattern):
 
     def __init__(
         self,
-        content: Optional[Text] = None,
+        content: Optional[str] = None,
         min: int = 0,
         max: int = HUGE,
-        name: Optional[Text] = None,
+        name: Optional[str] = None,
     ) -> None:
         """
         Initializer.

From f3b50e466969f9142393ec32a4b2a383ffbe5f23 Mon Sep 17 00:00:00 2001
From: Kenneth Schackart <schackartk1@gmail.com>
Date: Sun, 9 Jul 2023 15:07:21 -0700
Subject: [PATCH 0788/1034] Add CITATION.cff file (#3723)

---
 CHANGES.md   |  3 +++
 CITATION.cff | 22 ++++++++++++++++++++++
 2 files changed, 25 insertions(+)
 create mode 100644 CITATION.cff

diff --git a/CHANGES.md b/CHANGES.md
index 1b0475fc7b9..15027afbf0b 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -84,6 +84,9 @@
 
 ### Documentation
 
+- Add a CITATION.cff file to the root of the repository, containing metadata on how to
+  cite this software (#3723)
+
 <!-- Major changes to documentation and policies. Small docs changes
      don't need a changelog entry. -->
 
diff --git a/CITATION.cff b/CITATION.cff
new file mode 100644
index 00000000000..ddf64f616ff
--- /dev/null
+++ b/CITATION.cff
@@ -0,0 +1,22 @@
+cff-version: 1.2.0
+title: "Black: The uncompromising Python code formatter"
+message: >-
+  If you use this software, please cite it using the metadata from this file.
+type: software
+authors:
+  - family-names: Langa
+    given-names: Łukasz
+  - name: "contributors to Black"
+repository-code: "https://github.com/psf/black"
+url: "https://black.readthedocs.io/en/stable/"
+abstract: >-
+  Black is the uncompromising Python code formatter. By using it, you agree to cede
+  control over minutiae ofhand-formatting. In return, Black gives you speed,
+  determinism, and freedom from pycodestyle nagging about formatting. You will save time
+  and mental energy for more important matters.
+
+  Blackened code looks the same regardless of the project you're reading. Formatting
+  becomes transparent after a while and you can focus on the content instead.
+
+  Black makes code review faster by producing the smallest diffs possible.
+license: MIT

From 2593af2c5d211b58e28f7c1472f1f67e6783216a Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Sun, 9 Jul 2023 15:24:01 -0700
Subject: [PATCH 0789/1034] Improve performance by skipping unnecessary
 normalisation (#3751)

This speeds up black by about 40% when the cache is full
---
 CHANGES.md          |  1 +
 src/black/files.py  | 23 +++++++++++++++++------
 tests/test_black.py |  4 +++-
 3 files changed, 21 insertions(+), 7 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 15027afbf0b..93d8ee1921a 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -55,6 +55,7 @@
 
 <!-- Changes that improve Black's performance. -->
 
+- Speed up _Black_ significantly when the cache is full (#3751)
 - Avoid importing `IPython` in a case where we wouldn't need it (#3748)
 
 ### Output
diff --git a/src/black/files.py b/src/black/files.py
index 4e2209e557d..ef6895ee3af 100644
--- a/src/black/files.py
+++ b/src/black/files.py
@@ -276,15 +276,24 @@ def normalize_path_maybe_ignore(
     return root_relative_path
 
 
-def path_is_ignored(
-    path: Path, gitignore_dict: Dict[Path, PathSpec], report: Report
+def _path_is_ignored(
+    root_relative_path: str,
+    root: Path,
+    gitignore_dict: Dict[Path, PathSpec],
+    report: Report,
 ) -> bool:
+    path = root / root_relative_path
+    # Note that this logic is sensitive to the ordering of gitignore_dict. Callers must
+    # ensure that gitignore_dict is ordered from least specific to most specific.
     for gitignore_path, pattern in gitignore_dict.items():
-        relative_path = normalize_path_maybe_ignore(path, gitignore_path, report)
-        if relative_path is None:
+        try:
+            relative_path = path.relative_to(gitignore_path).as_posix()
+        except ValueError:
             break
         if pattern.match_file(relative_path):
-            report.path_ignored(path, "matches a .gitignore file content")
+            report.path_ignored(
+                path.relative_to(root), "matches a .gitignore file content"
+            )
             return True
     return False
 
@@ -326,7 +335,9 @@ def gen_python_files(
             continue
 
         # First ignore files matching .gitignore, if passed
-        if gitignore_dict and path_is_ignored(child, gitignore_dict, report):
+        if gitignore_dict and _path_is_ignored(
+            normalized_path, root, gitignore_dict, report
+        ):
             continue
 
         # Then ignore with `--exclude` `--extend-exclude` and `--force-exclude` options.
diff --git a/tests/test_black.py b/tests/test_black.py
index dd21d0a7ae6..3b3ab721c5f 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -508,6 +508,8 @@ def _mocked_calls() -> bool:
             "pathlib.Path.cwd", return_value=working_directory
         ), patch("pathlib.Path.is_dir", side_effect=mock_n_calls([True])):
             ctx = FakeContext()
+            # Note that the root folder (project_root) isn't the folder
+            # named "root" (aka working_directory)
             ctx.obj["root"] = project_root
             report = MagicMock(verbose=True)
             black.get_sources(
@@ -527,7 +529,7 @@ def _mocked_calls() -> bool:
             for _, mock_args, _ in report.path_ignored.mock_calls
         ), "A symbolic link was reported."
         report.path_ignored.assert_called_once_with(
-            Path("child", "b.py"), "matches a .gitignore file content"
+            Path("root", "child", "b.py"), "matches a .gitignore file content"
         )
 
     def test_report_verbose(self) -> None:

From 257d392217974a76231e306133288748c7b70786 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Sun, 9 Jul 2023 15:52:41 -0700
Subject: [PATCH 0790/1034] Fix removed comments in stub files (#3745)

---
 CHANGES.md                            |  2 ++
 src/black/nodes.py                    | 11 ++++++-
 tests/data/simple_cases/ignore_pyi.py | 41 +++++++++++++++++++++++++++
 tests/test_format.py                  |  5 ++--
 4 files changed, 56 insertions(+), 3 deletions(-)
 create mode 100644 tests/data/simple_cases/ignore_pyi.py

diff --git a/CHANGES.md b/CHANGES.md
index 93d8ee1921a..bb304296d63 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -15,6 +15,8 @@
 
 - Fix a bug where an illegal trailing comma was added to return type annotations using
   PEP 604 unions (#3735)
+- Fix several bugs and crashes where comments in stub files were removed or mishandled
+  under some circumstances. (#3745)
 - Fix a bug where multi-line open parenthesis magic comment like `type: ignore` were not
   correctly parsed (#3740)
 
diff --git a/src/black/nodes.py b/src/black/nodes.py
index ef42278d83f..45423b2596b 100644
--- a/src/black/nodes.py
+++ b/src/black/nodes.py
@@ -714,6 +714,11 @@ def is_multiline_string(leaf: Leaf) -> bool:
 
 def is_stub_suite(node: Node) -> bool:
     """Return True if `node` is a suite with a stub body."""
+
+    # If there is a comment, we want to keep it.
+    if node.prefix.strip():
+        return False
+
     if (
         len(node.children) != 4
         or node.children[0].type != token.NEWLINE
@@ -722,6 +727,9 @@ def is_stub_suite(node: Node) -> bool:
     ):
         return False
 
+    if node.children[3].prefix.strip():
+        return False
+
     return is_stub_body(node.children[2])
 
 
@@ -735,7 +743,8 @@ def is_stub_body(node: LN) -> bool:
 
     child = node.children[0]
     return (
-        child.type == syms.atom
+        not child.prefix.strip()
+        and child.type == syms.atom
         and len(child.children) == 3
         and all(leaf == Leaf(token.DOT, ".") for leaf in child.children)
     )
diff --git a/tests/data/simple_cases/ignore_pyi.py b/tests/data/simple_cases/ignore_pyi.py
new file mode 100644
index 00000000000..3ef61079bfe
--- /dev/null
+++ b/tests/data/simple_cases/ignore_pyi.py
@@ -0,0 +1,41 @@
+def f():  # type: ignore
+    ...
+
+class x:  # some comment
+    ...
+
+class y:
+    ...  # comment
+
+# whitespace doesn't matter (note the next line has a trailing space and tab)
+class z:        
+    ...
+
+def g():
+    # hi
+    ...
+
+def h():
+    ...
+    # bye
+
+# output
+
+def f():  # type: ignore
+    ...
+
+class x:  # some comment
+    ...
+
+class y: ...  # comment
+
+# whitespace doesn't matter (note the next line has a trailing space and tab)
+class z: ...
+
+def g():
+    # hi
+    ...
+
+def h():
+    ...
+    # bye
diff --git a/tests/test_format.py b/tests/test_format.py
index 8e0ada99cba..fb4d8eb4346 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -33,9 +33,10 @@ def check_file(
 @pytest.mark.parametrize("filename", all_data_cases("simple_cases"))
 def test_simple_format(filename: str) -> None:
     magic_trailing_comma = filename != "skip_magic_trailing_comma"
-    check_file(
-        "simple_cases", filename, black.Mode(magic_trailing_comma=magic_trailing_comma)
+    mode = black.Mode(
+        magic_trailing_comma=magic_trailing_comma, is_pyi=filename.endswith("_pyi")
     )
+    check_file("simple_cases", filename, mode)
 
 
 @pytest.mark.parametrize("filename", all_data_cases("preview"))

From b8e2ec728cc09d0f00829a9cffcb54da3efa5760 Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Sun, 9 Jul 2023 16:28:26 -0700
Subject: [PATCH 0791/1034] Fix crash on type comment with trailing space
 (#3773)

---
 CHANGES.md                           | 2 ++
 src/black/parsing.py                 | 9 ++++++---
 tests/data/simple_cases/comments2.py | 5 +++++
 3 files changed, 13 insertions(+), 3 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index bb304296d63..c7389ce57c6 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -19,6 +19,8 @@
   under some circumstances. (#3745)
 - Fix a bug where multi-line open parenthesis magic comment like `type: ignore` were not
   correctly parsed (#3740)
+- Fix error in AST validation when Black removes trailing whitespace in a type comment
+  (#3773)
 
 ### Preview style
 
diff --git a/src/black/parsing.py b/src/black/parsing.py
index 455c5eed968..e98e019cac6 100644
--- a/src/black/parsing.py
+++ b/src/black/parsing.py
@@ -208,15 +208,18 @@ def stringify_ast(node: ast.AST, depth: int = 0) -> Iterator[str]:
 
         else:
             normalized: object
-            # Constant strings may be indented across newlines, if they are
-            # docstrings; fold spaces after newlines when comparing. Similarly,
-            # trailing and leading space may be removed.
             if (
                 isinstance(node, ast.Constant)
                 and field == "value"
                 and isinstance(value, str)
             ):
+                # Constant strings may be indented across newlines, if they are
+                # docstrings; fold spaces after newlines when comparing. Similarly,
+                # trailing and leading space may be removed.
                 normalized = _normalize("\n", value)
+            elif field == "type_comment" and isinstance(value, str):
+                # Trailing whitespace in type comments is removed.
+                normalized = value.rstrip()
             else:
                 normalized = value
             yield f"{'  ' * (depth+2)}{normalized!r},  # {value.__class__.__name__}"
diff --git a/tests/data/simple_cases/comments2.py b/tests/data/simple_cases/comments2.py
index 37e185abf4f..1487dc4b6e2 100644
--- a/tests/data/simple_cases/comments2.py
+++ b/tests/data/simple_cases/comments2.py
@@ -154,6 +154,9 @@ def _init_host(self, parsed) -> None:
                 not parsed.hostname.strip()):
             pass
 
+
+a = "type comment with trailing space"  # type: str   
+
 #######################
 ### SECTION COMMENT ###
 #######################
@@ -332,6 +335,8 @@ def _init_host(self, parsed) -> None:
             pass
 
 
+a = "type comment with trailing space"  # type: str
+
 #######################
 ### SECTION COMMENT ###
 #######################

From ad3724b7ffc01d8152c97fe7f4dcf35220f21a8e Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Sun, 9 Jul 2023 17:04:50 -0700
Subject: [PATCH 0792/1034] Upgrade to latest mypy (#3775)

---
 .pre-commit-config.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index bb647763e70..c2f4b1684e6 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -38,7 +38,7 @@ repos:
           - flake8-simplify
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v0.991
+    rev: v1.4.1
     hooks:
       - id: mypy
         exclude: ^docs/conf.py

From 138769aa27d6bd86507a0cd98d9a5bf8f63a8e99 Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Mon, 10 Jul 2023 08:37:12 -0700
Subject: [PATCH 0793/1034] Disable coverage on pypy tests (#3777)

The pypy tests are reeeeaaally slow. Maybe this will help.
---
 .github/workflows/test.yml | 4 +++-
 tox.ini                    | 8 ++------
 2 files changed, 5 insertions(+), 7 deletions(-)

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 92d7d411510..4bf687435b4 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -58,7 +58,9 @@ jobs:
       - name: Upload coverage to Coveralls
         # Upload coverage if we are on the main repository and
         # we're running on Linux (this action only supports Linux)
-        if: github.repository == 'psf/black' && matrix.os == 'ubuntu-latest'
+        if:
+          github.repository == 'psf/black' && matrix.os == 'ubuntu-latest' &&
+          !startsWith(matrix.python-version, 'pypy')
         uses: AndreMiras/coveralls-python-action@v20201129
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
diff --git a/tox.ini b/tox.ini
index f8e1a785331..d34dbbc71db 100644
--- a/tox.ini
+++ b/tox.ini
@@ -39,19 +39,15 @@ deps =
 ; remove this when pypy releases the bugfix
 commands =
     pip install -e .[d]
-    coverage erase
     pytest tests \
         --run-optional no_jupyter \
         !ci: --numprocesses auto \
-        ci: --numprocesses 1 \
-        --cov {posargs}
+        ci: --numprocesses 1
     pip install -e .[jupyter]
     pytest tests --run-optional jupyter \
         -m jupyter \
         !ci: --numprocesses auto \
-        ci: --numprocesses 1 \
-        --cov --cov-append {posargs}
-    coverage report
+        ci: --numprocesses 1
 
 [testenv:{,ci-}311]
 setenv =

From 38723bb7787d50f8751fad2eaa48b52c9e94c18d Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Mon, 10 Jul 2023 11:49:40 -0700
Subject: [PATCH 0794/1034] Unpin pytest-xdist (#3772)

---
 test_requirements.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/test_requirements.txt b/test_requirements.txt
index ef61a1210ee..a3d262bc53d 100644
--- a/test_requirements.txt
+++ b/test_requirements.txt
@@ -1,6 +1,6 @@
 coverage >= 5.3
 pre-commit
 pytest >= 6.1.1
-pytest-xdist >= 2.2.1, < 3.0.2
-pytest-cov >= 2.11.1
+pytest-xdist >= 3.0.2
+pytest-cov >= 4.1.0
 tox

From 193ee766ca496871f93621d6b58d57a6564ff81b Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Mon, 10 Jul 2023 17:09:47 -0700
Subject: [PATCH 0795/1034] Prepare release 23.7.0 (#3776)

---
 CHANGES.md                                  | 89 +++++++++++++--------
 docs/integrations/source_version_control.md |  4 +-
 docs/usage_and_configuration/the_basics.md  |  6 +-
 3 files changed, 60 insertions(+), 39 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index c7389ce57c6..c61ee698c5d 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -6,97 +6,118 @@
 
 <!-- Include any especially major or disruptive changes here -->
 
+### Stable style
+
+<!-- Changes that affect Black's stable style -->
+
+### Preview style
+
+<!-- Changes that affect Black's preview style -->
+
+### Configuration
+
+<!-- Changes to how Black can be configured -->
+
+### Packaging
+
+<!-- Changes to how Black is packaged, such as dependency requirements -->
+
+### Parser
+
+<!-- Changes to the parser or to version autodetection -->
+
+### Performance
+
+<!-- Changes that improve Black's performance. -->
+
+### Output
+
+<!-- Changes to Black's terminal output and error messages -->
+
+### _Blackd_
+
+<!-- Changes to blackd -->
+
+### Integrations
+
+<!-- For example, Docker, GitHub Actions, pre-commit, editors -->
+
+### Documentation
+
+<!-- Major changes to documentation and policies. Small docs changes
+     don't need a changelog entry. -->
+
+## 23.7.0
+
+### Highlights
+
 - Runtime support for Python 3.7 has been removed. Formatting 3.7 code will still be
   supported until further notice (#3765)
 
 ### Stable style
 
-<!-- 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 several bugs and crashes where comments in stub files were removed or mishandled
-  under some circumstances. (#3745)
-- Fix a bug where multi-line open parenthesis magic comment like `type: ignore` were not
-  correctly parsed (#3740)
-- Fix error in AST validation when Black removes trailing whitespace in a type comment
+  under some circumstances (#3745)
+- Fix a crash with multi-line magic comments like `type: ignore` within parentheses
+  (#3740)
+- Fix error in AST validation when _Black_ removes trailing whitespace in a type comment
   (#3773)
 
 ### Preview style
 
-<!-- Changes that affect Black's preview style -->
-
 - Implicitly concatenated strings used as function args are no longer wrapped inside
   parentheses (#3640)
 - Remove blank lines between a class definition and its docstring (#3692)
 
 ### Configuration
 
-<!-- Changes to how Black can be configured -->
-
-- The `--workers` argument to Black can now be specified via the `BLACK_NUM_WORKERS`
+- 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)
-- Black will now error if `exclude` and `extend-exclude` have invalid data types in
+- Fix _Black_ not honouring `pyproject.toml` settings when running `--stdin-filename`
+  and the `pyproject.toml` found isn't in the current working directory (#3719)
+- _Black_ will now error if `exclude` and `extend-exclude` have invalid data types in
   `pyproject.toml`, instead of silently doing the wrong thing (#3764)
 
 ### Packaging
 
-<!-- Changes to how Black is packaged, such as dependency requirements -->
-
 - Upgrade mypyc from 0.991 to 1.3 (#3697)
 - Remove patching of Click that mitigated errors on Python 3.6 with `LANG=C` (#3768)
 
 ### 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. -->
-
 - Speed up _Black_ significantly when the cache is full (#3751)
 - 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 -->
-
 - Black is now tested with
   [`PYTHONWARNDEFAULTENCODING = 1`](https://docs.python.org/3/library/io.html#io-encoding-warning)
   (#3763)
 - Update GitHub Action to display black output in the job summary (#3688)
-- Deprecated `set-output` command in CI test to keep up to date with GitHub's
-  deprecation announcement (#3757)
 
 ### Documentation
 
 - Add a CITATION.cff file to the root of the repository, containing metadata on how to
   cite this software (#3723)
-
-<!-- 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)
+- Update the _classes_ and _exceptions_ documentation in Developer reference to match
+  the latest code base (#3755)
 
 ## 23.3.0
 
diff --git a/docs/integrations/source_version_control.md b/docs/integrations/source_version_control.md
index 8b8fd658e0e..a9d33d2d853 100644
--- a/docs/integrations/source_version_control.md
+++ b/docs/integrations/source_version_control.md
@@ -7,7 +7,7 @@ Use [pre-commit](https://pre-commit.com/). Once you
 ```yaml
 repos:
   - repo: https://github.com/psf/black
-    rev: 23.3.0
+    rev: 23.7.0
     hooks:
       - id: black
         # It is recommended to specify the latest version of Python
@@ -31,7 +31,7 @@ include Jupyter Notebooks. To use this hook, simply replace the hook's `id: blac
 ```yaml
 repos:
   - repo: https://github.com/psf/black
-    rev: 23.3.0
+    rev: 23.7.0
     hooks:
       - id: black-jupyter
         # It is recommended to specify the latest version of Python
diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index 2a461487210..f5862edccaa 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -193,8 +193,8 @@ configuration file for consistent results across environments.
 
 ```console
 $ black --version
-black, 23.3.0 (compiled: yes)
-$ black --required-version 23.3.0 -c "format = 'this'"
+black, 23.7.0 (compiled: yes)
+$ black --required-version 23.7.0 -c "format = 'this'"
 format = "this"
 $ black --required-version 31.5b2 -c "still = 'beta?!'"
 Oh no! 💥 💔 💥 The required version does not match the running version!
@@ -285,7 +285,7 @@ You can check the version of _Black_ you have installed using the `--version` fl
 
 ```console
 $ black --version
-black, 23.3.0
+black, 23.7.0
 ```
 
 #### `--config`

From a062d5c9854205c4ae3f4cbe8859ed59bcd6259c Mon Sep 17 00:00:00 2001
From: skykasko <88055150+skykasko@users.noreply.github.com>
Date: Mon, 10 Jul 2023 22:38:01 -0400
Subject: [PATCH 0796/1034] Fix typo in CITATION.cff (#3779)

Fix tiny typo in CITATION.cff
---
 CITATION.cff | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CITATION.cff b/CITATION.cff
index ddf64f616ff..7ff0e3ca9bc 100644
--- a/CITATION.cff
+++ b/CITATION.cff
@@ -11,7 +11,7 @@ repository-code: "https://github.com/psf/black"
 url: "https://black.readthedocs.io/en/stable/"
 abstract: >-
   Black is the uncompromising Python code formatter. By using it, you agree to cede
-  control over minutiae ofhand-formatting. In return, Black gives you speed,
+  control over minutiae of hand-formatting. In return, Black gives you speed,
   determinism, and freedom from pycodestyle nagging about formatting. You will save time
   and mental energy for more important matters.
 

From 027afda403d5da7b0ea2a1bf40788ad4c3eb510e Mon Sep 17 00:00:00 2001
From: Nicola Soranzo <nicola.soranzo@gmail.com>
Date: Tue, 11 Jul 2023 15:21:15 +0100
Subject: [PATCH 0797/1034] Remove Python 3.7 from classifiers (#3784)

Follow-up on https://github.com/psf/black/pull/3765
---
 pyproject.toml | 1 -
 1 file changed, 1 deletion(-)

diff --git a/pyproject.toml b/pyproject.toml
index 175f7851dee..aaac42b44b9 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -54,7 +54,6 @@ classifiers = [
   "Operating System :: OS Independent",
   "Programming Language :: Python",
   "Programming Language :: Python :: 3 :: Only",
-  "Programming Language :: Python :: 3.7",
   "Programming Language :: Python :: 3.8",
   "Programming Language :: Python :: 3.9",
   "Programming Language :: Python :: 3.10",

From f4490acfd7bf466ae30d7573d85107b46d4686b3 Mon Sep 17 00:00:00 2001
From: Alex Waygood <Alex.Waygood@Gmail.com>
Date: Tue, 11 Jul 2023 15:21:36 +0100
Subject: [PATCH 0798/1034] Remove unneeded mypy dependencies (#3783)

---
 .pre-commit-config.yaml | 2 --
 1 file changed, 2 deletions(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index c2f4b1684e6..3561df4f904 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -43,10 +43,8 @@ repos:
       - id: mypy
         exclude: ^docs/conf.py
         additional_dependencies:
-          - types-dataclasses >= 0.1.3
           - types-PyYAML
           - tomli >= 0.2.6, < 2.0.0
-          - types-typed-ast >= 1.4.1
           - click >= 8.1.0, != 8.1.4
           - packaging >= 22.0
           - platformdirs >= 2.1.0

From 8d2110320bef37534997af47edff243d1ec2720b Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Tue, 11 Jul 2023 07:35:41 -0700
Subject: [PATCH 0799/1034] Fix lint in test_ipynb (#3781)

Unblocks #3780
---
 tests/test_ipynb.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/tests/test_ipynb.py b/tests/test_ipynb.py
index 91e7901125b..a74f8ad5690 100644
--- a/tests/test_ipynb.py
+++ b/tests/test_ipynb.py
@@ -77,7 +77,7 @@ def test_trailing_semicolon_noop() -> None:
     [
         pytest.param(JUPYTER_MODE, id="default mode"),
         pytest.param(
-            replace(JUPYTER_MODE, python_cell_magics={"cust1", "cust1"}),
+            replace(JUPYTER_MODE, python_cell_magics={"cust1", "cust2"}),
             id="custom cell magics mode",
         ),
     ],
@@ -100,7 +100,7 @@ def test_cell_magic_noop() -> None:
     [
         pytest.param(JUPYTER_MODE, id="default mode"),
         pytest.param(
-            replace(JUPYTER_MODE, python_cell_magics={"cust1", "cust1"}),
+            replace(JUPYTER_MODE, python_cell_magics={"cust1", "cust2"}),
             id="custom cell magics mode",
         ),
     ],
@@ -183,7 +183,7 @@ def test_cell_magic_with_magic() -> None:
             id="No change when cell magic not registered",
         ),
         pytest.param(
-            replace(JUPYTER_MODE, python_cell_magics={"cust1", "cust1"}),
+            replace(JUPYTER_MODE, python_cell_magics={"cust1", "cust2"}),
             "%%custom_python_magic -n1 -n2\nx=2",
             pytest.raises(NothingChanged),
             id="No change when other cell magics registered",

From 37895f8e50486a0fa581f8fb039e536dc6d0d0e4 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Tue, 11 Jul 2023 07:50:52 -0700
Subject: [PATCH 0800/1034] [pre-commit.ci] pre-commit autoupdate (#3780)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

updates:
- [github.com/pycqa/flake8: 4.0.1 → 6.0.0](https://github.com/pycqa/flake8/compare/4.0.1...6.0.0)
- [github.com/pre-commit/mirrors-prettier: v2.7.1 → v3.0.0](https://github.com/pre-commit/mirrors-prettier/compare/v2.7.1...v3.0.0)
- [github.com/pre-commit/pre-commit-hooks: v4.3.0 → v4.4.0](https://github.com/pre-commit/pre-commit-hooks/compare/v4.3.0...v4.4.0)
---
 .pre-commit-config.yaml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 3561df4f904..70b4cd82532 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -29,7 +29,7 @@ repos:
       - id: isort
 
   - repo: https://github.com/pycqa/flake8
-    rev: 4.0.1
+    rev: 6.0.0
     hooks:
       - id: flake8
         additional_dependencies:
@@ -52,13 +52,13 @@ repos:
           - hypothesis
 
   - repo: https://github.com/pre-commit/mirrors-prettier
-    rev: v2.7.1
+    rev: v3.0.0
     hooks:
       - id: prettier
         exclude: \.github/workflows/diff_shades\.yml
 
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.3.0
+    rev: v4.4.0
     hooks:
       - id: end-of-file-fixer
       - id: trailing-whitespace

From 6123b4ac2696116090fee3da77e9be66417980dd Mon Sep 17 00:00:00 2001
From: rax <133822160+kotnen@users.noreply.github.com>
Date: Tue, 11 Jul 2023 14:16:43 -0500
Subject: [PATCH 0801/1034] Document shebang comment behaviour (#3787)

---
 docs/the_black_code_style/current_style.md | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/docs/the_black_code_style/current_style.md b/docs/the_black_code_style/current_style.md
index 0fb59fe5aae..e1a8078bf2c 100644
--- a/docs/the_black_code_style/current_style.md
+++ b/docs/the_black_code_style/current_style.md
@@ -254,11 +254,12 @@ required due to an inner function starting immediately after.
 
 _Black_ does not format comment contents, but it enforces two spaces between code and a
 comment on the same line, and a space before the comment text begins. Some types of
-comments that require specific spacing rules are respected: doc comments (`#: comment`),
-section comments with long runs of hashes, and Spyder cells. Non-breaking spaces after
-hashes are also preserved. Comments may sometimes be moved because of formatting
-changes, which can break tools that assign special meaning to them. See
-[AST before and after formatting](#ast-before-and-after-formatting) for more discussion.
+comments that require specific spacing rules are respected: shebangs (`#! comment`), doc
+comments (`#: comment`), section comments with long runs of hashes, and Spyder cells.
+Non-breaking spaces after hashes are also preserved. Comments may sometimes be moved
+because of formatting changes, which can break tools that assign special meaning to
+them. See [AST before and after formatting](#ast-before-and-after-formatting) for more
+discussion.
 
 ### Trailing commas
 

From 0e26ada66d16d2aea97bda5f907bb0b20b0985e7 Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Sun, 16 Jul 2023 17:35:19 -0700
Subject: [PATCH 0802/1034] Continue to avoid Click typing issue (#3791)

---
 .pre-commit-config.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 70b4cd82532..89c0de39c86 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -45,7 +45,7 @@ repos:
         additional_dependencies:
           - types-PyYAML
           - tomli >= 0.2.6, < 2.0.0
-          - click >= 8.1.0, != 8.1.4
+          - click >= 8.1.0, != 8.1.4, != 8.1.5
           - packaging >= 22.0
           - platformdirs >= 2.1.0
           - pytest

From 92e0f5b96500459b232a927fb26b0c990800b586 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Cl=C3=A9ment=20Robert?= <cr52@protonmail.com>
Date: Mon, 17 Jul 2023 03:09:26 +0200
Subject: [PATCH 0803/1034] Avoid importing `IPython` if notebook cells do not
 contain magics (#3782)

Co-authored-by: hauntsaninja <hauntsaninja@gmail.com>
Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
---
 CHANGES.md                       |  2 ++
 src/black/__init__.py            |  2 +-
 src/black/files.py               |  2 +-
 src/black/handle_ipynb_magics.py | 31 ++++++++++++-------------------
 tests/test_ipynb.py              | 12 ++++--------
 5 files changed, 20 insertions(+), 29 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index c61ee698c5d..709c767b329 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -30,6 +30,8 @@
 
 <!-- Changes that improve Black's performance. -->
 
+- Avoid importing `IPython` if notebook cells do not contain magics (#3782)
+
 ### Output
 
 <!-- Changes to Black's terminal output and error messages -->
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 301c18f7338..923a51867b5 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -668,7 +668,7 @@ def get_sources(
                 p = Path(f"{STDIN_PLACEHOLDER}{str(p)}")
 
             if p.suffix == ".ipynb" and not jupyter_dependencies_are_installed(
-                verbose=verbose, quiet=quiet
+                warn=verbose or not quiet
             ):
                 continue
 
diff --git a/src/black/files.py b/src/black/files.py
index ef6895ee3af..368e4170d47 100644
--- a/src/black/files.py
+++ b/src/black/files.py
@@ -384,7 +384,7 @@ def gen_python_files(
 
         elif child.is_file():
             if child.suffix == ".ipynb" and not jupyter_dependencies_are_installed(
-                verbose=verbose, quiet=quiet
+                warn=verbose or not quiet
             ):
                 continue
             include_match = include.search(normalized_path) if include else True
diff --git a/src/black/handle_ipynb_magics.py b/src/black/handle_ipynb_magics.py
index 2a2d62220e2..55ef2267df8 100644
--- a/src/black/handle_ipynb_magics.py
+++ b/src/black/handle_ipynb_magics.py
@@ -6,6 +6,7 @@
 import secrets
 import sys
 from functools import lru_cache
+from importlib.util import find_spec
 from typing import Dict, List, Optional, Tuple
 
 if sys.version_info >= (3, 10):
@@ -56,25 +57,17 @@ class Replacement:
 
 
 @lru_cache
-def jupyter_dependencies_are_installed(*, verbose: bool, quiet: bool) -> bool:
-    try:
-        # isort: off
-        # tokenize_rt is less commonly installed than IPython
-        # and IPython is expensive to import
-        import tokenize_rt  # noqa:F401
-        import IPython  # noqa:F401
-
-        # isort: on
-    except ModuleNotFoundError:
-        if verbose or not quiet:
-            msg = (
-                "Skipping .ipynb files as Jupyter dependencies are not installed.\n"
-                'You can fix this by running ``pip install "black[jupyter]"``'
-            )
-            out(msg)
-        return False
-    else:
-        return True
+def jupyter_dependencies_are_installed(*, warn: bool) -> bool:
+    installed = (
+        find_spec("tokenize_rt") is not None and find_spec("IPython") is not None
+    )
+    if not installed and warn:
+        msg = (
+            "Skipping .ipynb files as Jupyter dependencies are not installed.\n"
+            'You can fix this by running ``pip install "black[jupyter]"``'
+        )
+        out(msg)
+    return installed
 
 
 def remove_trailing_semicolon(src: str) -> Tuple[str, bool]:
diff --git a/tests/test_ipynb.py b/tests/test_ipynb.py
index a74f8ad5690..59897190304 100644
--- a/tests/test_ipynb.py
+++ b/tests/test_ipynb.py
@@ -440,17 +440,13 @@ def test_cache_isnt_written_if_no_jupyter_deps_single(
     nb = get_case_path("jupyter", "notebook_trailing_newline.ipynb")
     tmp_nb = tmp_path / "notebook.ipynb"
     tmp_nb.write_bytes(nb.read_bytes())
-    monkeypatch.setattr(
-        "black.jupyter_dependencies_are_installed", lambda verbose, quiet: False
-    )
+    monkeypatch.setattr("black.jupyter_dependencies_are_installed", lambda warn: False)
     result = runner.invoke(
         main, [str(tmp_path / "notebook.ipynb"), f"--config={EMPTY_CONFIG}"]
     )
     assert "No Python files are present to be formatted. Nothing to do" in result.output
     jupyter_dependencies_are_installed.cache_clear()
-    monkeypatch.setattr(
-        "black.jupyter_dependencies_are_installed", lambda verbose, quiet: True
-    )
+    monkeypatch.setattr("black.jupyter_dependencies_are_installed", lambda warn: True)
     result = runner.invoke(
         main, [str(tmp_path / "notebook.ipynb"), f"--config={EMPTY_CONFIG}"]
     )
@@ -466,13 +462,13 @@ def test_cache_isnt_written_if_no_jupyter_deps_dir(
     tmp_nb = tmp_path / "notebook.ipynb"
     tmp_nb.write_bytes(nb.read_bytes())
     monkeypatch.setattr(
-        "black.files.jupyter_dependencies_are_installed", lambda verbose, quiet: False
+        "black.files.jupyter_dependencies_are_installed", lambda warn: False
     )
     result = runner.invoke(main, [str(tmp_path), f"--config={EMPTY_CONFIG}"])
     assert "No Python files are present to be formatted. Nothing to do" in result.output
     jupyter_dependencies_are_installed.cache_clear()
     monkeypatch.setattr(
-        "black.files.jupyter_dependencies_are_installed", lambda verbose, quiet: True
+        "black.files.jupyter_dependencies_are_installed", lambda warn: True
     )
     result = runner.invoke(main, [str(tmp_path), f"--config={EMPTY_CONFIG}"])
     assert "reformatted" in result.output

From 8d80aecd50ea55a817807ae2d5174ccedaf12ecb Mon Sep 17 00:00:00 2001
From: Richard Si <sichard26@gmail.com>
Date: Sun, 16 Jul 2023 21:16:12 -0400
Subject: [PATCH 0804/1034] Maintainers += Shantanu Jain (hauntsaninja) (#3792)

---
 AUTHORS.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/AUTHORS.md b/AUTHORS.md
index ab3f30b8821..e0511bb9b7c 100644
--- a/AUTHORS.md
+++ b/AUTHORS.md
@@ -13,6 +13,7 @@ Maintained with:
 - [Richard Si](mailto:sichard26@gmail.com)
 - [Felix Hildén](mailto:felix.hilden@gmail.com)
 - [Batuhan Taskaya](mailto:batuhan@python.org)
+- [Shantanu Jain](mailto:hauntsaninja@gmail.com)
 
 Multiple contributions by:
 

From c1e30d97fe39e4c1b1967571b7e3854547239bf6 Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Sun, 16 Jul 2023 21:33:58 -0700
Subject: [PATCH 0805/1034] Fix most blib2to3 lint (#3794)

---
 .pre-commit-config.yaml        |  3 ++-
 pyproject.toml                 |  5 ++---
 src/blib2to3/README            | 13 +++++++------
 src/blib2to3/pgen2/driver.py   | 23 +++++++----------------
 src/blib2to3/pgen2/literals.py |  2 --
 src/blib2to3/pgen2/parse.py    | 27 +++++++++++++++------------
 src/blib2to3/pgen2/pgen.py     | 25 +++++++++++--------------
 src/blib2to3/pgen2/token.py    |  4 +---
 src/blib2to3/pgen2/tokenize.py | 29 ++++++++++++++++++++---------
 src/blib2to3/pygram.py         |  2 --
 src/blib2to3/pytree.py         | 11 +++--------
 11 files changed, 68 insertions(+), 76 deletions(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 89c0de39c86..0d68b81ccd7 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -1,6 +1,6 @@
 # Note: don't use this config for your own repositories. Instead, see
 # "Version control integration" in docs/integrations/source_version_control.md
-exclude: ^(src/blib2to3/|profiling/|tests/data/)
+exclude: ^(profiling/|tests/data/)
 repos:
   - repo: local
     hooks:
@@ -36,6 +36,7 @@ repos:
           - flake8-bugbear
           - flake8-comprehensions
           - flake8-simplify
+        exclude: ^src/blib2to3/
 
   - repo: https://github.com/pre-commit/mirrors-mypy
     rev: v1.4.1
diff --git a/pyproject.toml b/pyproject.toml
index aaac42b44b9..d29b768c289 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -12,8 +12,7 @@ include = '\.pyi?$'
 extend-exclude = '''
 /(
   # The following are specific to Black, you probably don't want those.
-  | blib2to3
-  | tests/data
+  tests/data
   | profiling
 )/
 '''
@@ -183,7 +182,7 @@ atomic = true
 profile = "black"
 line_length = 88
 skip_gitignore = true
-skip_glob = ["src/blib2to3", "tests/data", "profiling"]
+skip_glob = ["tests/data", "profiling"]
 known_first_party = ["black", "blib2to3", "blackd", "_black_version"]
 
 [tool.pytest.ini_options]
diff --git a/src/blib2to3/README b/src/blib2to3/README
index 0d3c607c9c7..38b04158ddb 100644
--- a/src/blib2to3/README
+++ b/src/blib2to3/README
@@ -1,18 +1,19 @@
-A subset of lib2to3 taken from Python 3.7.0b2.
-Commit hash: 9c17e3a1987004b8bcfbe423953aad84493a7984
+A subset of lib2to3 taken from Python 3.7.0b2. Commit hash:
+9c17e3a1987004b8bcfbe423953aad84493a7984
 
 Reasons for forking:
+
 - consistent handling of f-strings for users of Python < 3.6.2
-- backport of BPO-33064 that fixes parsing files with trailing commas after
-  *args and **kwargs
-- backport of GH-6143 that restores the ability to reformat legacy usage of
-  `async`
+- backport of BPO-33064 that fixes parsing files with trailing commas after \*args and
+  \*\*kwargs
+- backport of GH-6143 that restores the ability to reformat legacy usage of `async`
 - support all types of string literals
 - better ability to debug (better reprs)
 - INDENT and DEDENT don't hold whitespace and comment prefixes
 - ability to Cythonize
 
 Change Log:
+
 - Changes default logger used by Driver
 - Backported the following upstream parser changes:
   - "bpo-42381: Allow walrus in set literals and set comprehensions (GH-23332)"
diff --git a/src/blib2to3/pgen2/driver.py b/src/blib2to3/pgen2/driver.py
index bb73016a4c1..e629843f8b9 100644
--- a/src/blib2to3/pgen2/driver.py
+++ b/src/blib2to3/pgen2/driver.py
@@ -17,30 +17,21 @@
 
 # Python imports
 import io
-import os
 import logging
+import os
 import pkgutil
 import sys
-from typing import (
-    Any,
-    cast,
-    IO,
-    Iterable,
-    List,
-    Optional,
-    Iterator,
-    Tuple,
-    Union,
-)
 from contextlib import contextmanager
 from dataclasses import dataclass, field
-
-# Pgen imports
-from . import grammar, parse, token, tokenize, pgen
 from logging import Logger
-from blib2to3.pytree import NL
+from typing import IO, Any, Iterable, Iterator, List, Optional, Tuple, Union, cast
+
 from blib2to3.pgen2.grammar import Grammar
 from blib2to3.pgen2.tokenize import GoodTokenInfo
+from blib2to3.pytree import NL
+
+# Pgen imports
+from . import grammar, parse, pgen, token, tokenize
 
 Path = Union[str, "os.PathLike[str]"]
 
diff --git a/src/blib2to3/pgen2/literals.py b/src/blib2to3/pgen2/literals.py
index c67b91d0463..53c0b8ac2bb 100644
--- a/src/blib2to3/pgen2/literals.py
+++ b/src/blib2to3/pgen2/literals.py
@@ -4,10 +4,8 @@
 """Safely evaluate Python string literals without using eval()."""
 
 import re
-
 from typing import Dict, Match
 
-
 simple_escapes: Dict[str, str] = {
     "a": "\a",
     "b": "\b",
diff --git a/src/blib2to3/pgen2/parse.py b/src/blib2to3/pgen2/parse.py
index 17bf118e9fc..299cc24a15f 100644
--- a/src/blib2to3/pgen2/parse.py
+++ b/src/blib2to3/pgen2/parse.py
@@ -10,24 +10,25 @@
 
 """
 from contextlib import contextmanager
-
-# Local imports
-from . import grammar, token, tokenize
 from typing import (
-    cast,
+    TYPE_CHECKING,
     Any,
-    Optional,
-    Union,
-    Tuple,
+    Callable,
     Dict,
-    List,
     Iterator,
-    Callable,
+    List,
+    Optional,
     Set,
-    TYPE_CHECKING,
+    Tuple,
+    Union,
+    cast,
 )
+
 from blib2to3.pgen2.grammar import Grammar
-from blib2to3.pytree import convert, NL, Context, RawNode, Leaf, Node
+from blib2to3.pytree import NL, Context, Leaf, Node, RawNode, convert
+
+# Local imports
+from . import grammar, token, tokenize
 
 if TYPE_CHECKING:
     from blib2to3.pgen2.driver import TokenProxy
@@ -112,7 +113,9 @@ def add_token(self, tok_type: int, tok_val: str, raw: bool = False) -> None:
                     args.insert(0, ilabel)
                 func(*args)
 
-    def determine_route(self, value: Optional[str] = None, force: bool = False) -> Optional[int]:
+    def determine_route(
+        self, value: Optional[str] = None, force: bool = False
+    ) -> Optional[int]:
         alive_ilabels = self.ilabels
         if len(alive_ilabels) == 0:
             *_, most_successful_ilabel = self._dead_ilabels
diff --git a/src/blib2to3/pgen2/pgen.py b/src/blib2to3/pgen2/pgen.py
index 046efd09338..3ece9bb41ed 100644
--- a/src/blib2to3/pgen2/pgen.py
+++ b/src/blib2to3/pgen2/pgen.py
@@ -1,25 +1,22 @@
 # Copyright 2004-2005 Elemental Security, Inc. All Rights Reserved.
 # Licensed to PSF under a Contributor Agreement.
 
-# Pgen imports
-from . import grammar, token, tokenize
-
+import os
 from typing import (
+    IO,
     Any,
     Dict,
-    IO,
     Iterator,
     List,
+    NoReturn,
     Optional,
+    Sequence,
     Tuple,
     Union,
-    Sequence,
-    NoReturn,
 )
-from blib2to3.pgen2 import grammar
-from blib2to3.pgen2.tokenize import GoodTokenInfo
-import os
 
+from blib2to3.pgen2 import grammar, token, tokenize
+from blib2to3.pgen2.tokenize import GoodTokenInfo
 
 Path = Union[str, "os.PathLike[str]"]
 
@@ -149,7 +146,7 @@ def calcfirst(self, name: str) -> None:
         state = dfa[0]
         totalset: Dict[str, int] = {}
         overlapcheck = {}
-        for label, next in state.arcs.items():
+        for label in state.arcs:
             if label in self.dfas:
                 if label in self.first:
                     fset = self.first[label]
@@ -190,9 +187,9 @@ def parse(self) -> Tuple[Dict[str, List["DFAState"]], str]:
             # self.dump_nfa(name, a, z)
             dfa = self.make_dfa(a, z)
             # self.dump_dfa(name, dfa)
-            oldlen = len(dfa)
+            # oldlen = len(dfa)
             self.simplify_dfa(dfa)
-            newlen = len(dfa)
+            # newlen = len(dfa)
             dfas[name] = dfa
             # print name, oldlen, newlen
             if startsymbol is None:
@@ -346,7 +343,7 @@ def parse_atom(self) -> Tuple["NFAState", "NFAState"]:
             self.raise_error(
                 "expected (...) or NAME or STRING, got %s/%s", self.type, self.value
             )
-            assert False
+            raise AssertionError
 
     def expect(self, type: int, value: Optional[Any] = None) -> str:
         if self.type != type or (value is not None and self.value != value):
@@ -368,7 +365,7 @@ def raise_error(self, msg: str, *args: Any) -> NoReturn:
         if args:
             try:
                 msg = msg % args
-            except:
+            except Exception:
                 msg = " ".join([msg] + list(map(str, args)))
         raise SyntaxError(msg, (self.filename, self.end[0], self.end[1], self.line))
 
diff --git a/src/blib2to3/pgen2/token.py b/src/blib2to3/pgen2/token.py
index 117cc09d4ce..ed2fc4e85fc 100644
--- a/src/blib2to3/pgen2/token.py
+++ b/src/blib2to3/pgen2/token.py
@@ -1,8 +1,6 @@
 """Token constants (from "token.h")."""
 
-from typing import Dict
-
-from typing import Final
+from typing import Dict, Final
 
 #  Taken from Python (r53757) and modified to include some tokens
 #   originally monkeypatched in by pgen2.tokenize
diff --git a/src/blib2to3/pgen2/tokenize.py b/src/blib2to3/pgen2/tokenize.py
index 1dea89d7bb8..d0607f4b1e1 100644
--- a/src/blib2to3/pgen2/tokenize.py
+++ b/src/blib2to3/pgen2/tokenize.py
@@ -30,28 +30,41 @@
 import sys
 from typing import (
     Callable,
+    Final,
     Iterable,
     Iterator,
     List,
     Optional,
+    Pattern,
     Set,
     Tuple,
-    Pattern,
     Union,
     cast,
 )
 
-from typing import Final
-
-from blib2to3.pgen2.token import *
 from blib2to3.pgen2.grammar import Grammar
+from blib2to3.pgen2.token import (
+    ASYNC,
+    AWAIT,
+    COMMENT,
+    DEDENT,
+    ENDMARKER,
+    ERRORTOKEN,
+    INDENT,
+    NAME,
+    NEWLINE,
+    NL,
+    NUMBER,
+    OP,
+    STRING,
+    tok_name,
+)
 
 __author__ = "Ka-Ping Yee <ping@lfw.org>"
 __credits__ = "GvR, ESR, Tim Peters, Thomas Wouters, Fred Drake, Skip Montanaro"
 
 import re
 from codecs import BOM_UTF8, lookup
-from blib2to3.pgen2.token import *
 
 from . import token
 
@@ -334,7 +347,7 @@ def read_or_stop() -> bytes:
         try:
             return readline()
         except StopIteration:
-            return b''
+            return b""
 
     def find_cookie(line: bytes) -> Optional[str]:
         try:
@@ -676,14 +689,12 @@ def generate_tokens(
         yield stashed
         stashed = None
 
-    for indent in indents[1:]:  # pop remaining indent levels
+    for _indent in indents[1:]:  # pop remaining indent levels
         yield (DEDENT, "", (lnum, 0), (lnum, 0), "")
     yield (ENDMARKER, "", (lnum, 0), (lnum, 0), "")
 
 
 if __name__ == "__main__":  # testing
-    import sys
-
     if len(sys.argv) > 1:
         tokenize(open(sys.argv[1]).readline)
     else:
diff --git a/src/blib2to3/pygram.py b/src/blib2to3/pygram.py
index 1b4832362bf..c30c630e816 100644
--- a/src/blib2to3/pygram.py
+++ b/src/blib2to3/pygram.py
@@ -5,12 +5,10 @@
 
 # Python imports
 import os
-
 from typing import Union
 
 # Local imports
 from .pgen2 import driver
-
 from .pgen2.grammar import Grammar
 
 # Moved into initialize because mypyc can't handle __file__ (XXX bug)
diff --git a/src/blib2to3/pytree.py b/src/blib2to3/pytree.py
index 156322cab7e..2a0cd6d196a 100644
--- a/src/blib2to3/pytree.py
+++ b/src/blib2to3/pytree.py
@@ -15,15 +15,16 @@
 from typing import (
     Any,
     Dict,
+    Iterable,
     Iterator,
     List,
     Optional,
+    Set,
     Tuple,
     TypeVar,
     Union,
-    Set,
-    Iterable,
 )
+
 from blib2to3.pgen2.grammar import Grammar
 
 __author__ = "Guido van Rossum <guido@python.org>"
@@ -58,7 +59,6 @@ def type_repr(type_num: int) -> Union[str, int]:
 
 
 class Base:
-
     """
     Abstract base class for Node and Leaf.
 
@@ -237,7 +237,6 @@ def get_suffix(self) -> str:
 
 
 class Node(Base):
-
     """Concrete implementation for interior nodes."""
 
     fixers_applied: Optional[List[Any]]
@@ -378,7 +377,6 @@ def update_sibling_maps(self) -> None:
 
 
 class Leaf(Base):
-
     """Concrete implementation for leaf nodes."""
 
     # Default values for instance variables
@@ -506,7 +504,6 @@ def convert(gr: Grammar, raw_node: RawNode) -> NL:
 
 
 class BasePattern:
-
     """
     A pattern is a tree matching pattern.
 
@@ -646,7 +643,6 @@ def _submatch(self, node, results=None):
 
 
 class NodePattern(BasePattern):
-
     wildcards: bool = False
 
     def __init__(
@@ -715,7 +711,6 @@ def _submatch(self, node, results=None) -> bool:
 
 
 class WildcardPattern(BasePattern):
-
     """
     A wildcard pattern can match zero or more nodes.
 

From 068f6fb8fa2b52f647aec8696033e43f6b0db70b Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Sun, 16 Jul 2023 23:59:36 -0700
Subject: [PATCH 0806/1034] Bump pypa/cibuildwheel from 2.13.1 to 2.14.1
 (#3795)

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/pypi_upload.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/pypi_upload.yml b/.github/workflows/pypi_upload.yml
index 06600fcbc45..291193efc7a 100644
--- a/.github/workflows/pypi_upload.yml
+++ b/.github/workflows/pypi_upload.yml
@@ -58,7 +58,7 @@ jobs:
       - uses: actions/checkout@v3
 
       - name: Build wheels via cibuildwheel
-        uses: pypa/cibuildwheel@v2.13.1
+        uses: pypa/cibuildwheel@v2.14.1
         env:
           CIBW_ARCHS_MACOS: "${{ matrix.macos_arch }}"
 

From 2f68ac850b5b5b8e955110112f841121b76effa4 Mon Sep 17 00:00:00 2001
From: Richard Si <sichard26@gmail.com>
Date: Tue, 18 Jul 2023 10:51:16 -0400
Subject: [PATCH 0807/1034] Fix diff-shades comment missing newlines (#3799)

Preserving newlines is done differently when writing to $GITHUB_OUTPUT
over the deprecated :set-output: command.
---
 scripts/diff_shades_gha_helper.py | 17 ++++++++++-------
 1 file changed, 10 insertions(+), 7 deletions(-)

diff --git a/scripts/diff_shades_gha_helper.py b/scripts/diff_shades_gha_helper.py
index 994fbe05045..7a58fbe9b28 100644
--- a/scripts/diff_shades_gha_helper.py
+++ b/scripts/diff_shades_gha_helper.py
@@ -21,6 +21,7 @@
 import subprocess
 import sys
 import zipfile
+from base64 import b64encode
 from io import BytesIO
 from pathlib import Path
 from typing import Any
@@ -53,12 +54,16 @@ def set_output(name: str, value: str) -> None:
     else:
         print(f"[INFO]: setting '{name}' to [{len(value)} chars]")
 
-    # Originally the `set-output` workflow command was used here, now replaced
-    # by setting variables through the `GITHUB_OUTPUT` environment variable
-    # to stay up to date with GitHub's update.
     if "GITHUB_OUTPUT" in os.environ:
+        if "\n" in value:
+            # https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#multiline-strings
+            delimiter = b64encode(os.urandom(16)).decode()
+            value = f"{delimiter}\n{value}\n{delimiter}"
+            command = f"{name}<<{value}"
+        else:
+            command = f"{name}={value}"
         with open(os.environ["GITHUB_OUTPUT"], "a") as f:
-            print(f"{name}={value}", file=f)
+            print(command, file=f)
 
 
 def http_get(url: str, *, is_json: bool = True, **kwargs: Any) -> Any:
@@ -224,9 +229,7 @@ def comment_details(run_id: str) -> None:
     # while it's still in progress seems impossible).
     body = body.replace("$workflow-run-url", data["html_url"])
     body = body.replace("$job-diff-url", diff_url)
-    # https://github.community/t/set-output-truncates-multiline-strings/16852/3
-    escaped = body.replace("%", "%25").replace("\n", "%0A").replace("\r", "%0D")
-    set_output("comment-body", escaped)
+    set_output("comment-body", body)
 
 
 if __name__ == "__main__":

From 0b301f80954a026693c4c22de89267ad8c85f9b6 Mon Sep 17 00:00:00 2001
From: rdrll <13176405+rdrll@users.noreply.github.com>
Date: Tue, 18 Jul 2023 14:11:24 -0700
Subject: [PATCH 0808/1034] Improvements to contributing docs (#3753)

---
 docs/contributing/the_basics.md | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/docs/contributing/the_basics.md b/docs/contributing/the_basics.md
index 5fdcdd802bd..40d233257e3 100644
--- a/docs/contributing/the_basics.md
+++ b/docs/contributing/the_basics.md
@@ -12,7 +12,9 @@ example:
 
 ```console
 $ python3 -m venv .venv
-$ source .venv/bin/activate
+$ source .venv/bin/activate # activation for linux and mac
+$ .venv\Scripts\activate # activation for windows
+
 (.venv)$ pip install -r test_requirements.txt
 (.venv)$ pip install -e .[d]
 (.venv)$ pre-commit install
@@ -30,6 +32,9 @@ the root of the black repo:
 
 # Optional Fuzz testing
 (.venv)$ tox -e fuzz
+
+# Format Black itself
+(.venv)$ tox -e run_self
 ```
 
 ### News / Changelog Requirement
@@ -62,7 +67,7 @@ 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/
 ```
 

From e7e8d6287b38db3f15bdf3d4ec6987d4490b8d14 Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Sat, 22 Jul 2023 08:49:51 -0700
Subject: [PATCH 0809/1034] Simplify empty line tracker (#3797)

---
 src/black/lines.py | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

diff --git a/src/black/lines.py b/src/black/lines.py
index ea8fe520756..016a489310d 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -49,7 +49,7 @@
 class Line:
     """Holds leaves and comments. Can be printed with `str(line)`."""
 
-    mode: Mode
+    mode: Mode = field(repr=False)
     depth: int = 0
     leaves: List[Leaf] = field(default_factory=list)
     # keys ordered like `leaves`
@@ -579,16 +579,21 @@ def _maybe_empty_lines(self, current_line: Line) -> Tuple[int, int]:
         else:
             before = 0
         depth = current_line.depth
+
+        previous_def = None
         while self.previous_defs and self.previous_defs[-1].depth >= depth:
+            previous_def = self.previous_defs.pop()
+
+        if previous_def is not None:
+            assert self.previous_line is not None
             if self.mode.is_pyi:
-                assert self.previous_line is not None
                 if depth and not current_line.is_def and self.previous_line.is_def:
                     # Empty lines between attributes and methods should be preserved.
                     before = min(1, before)
                 elif (
                     Preview.blank_line_after_nested_stub_class in self.mode
-                    and self.previous_defs[-1].is_class
-                    and not self.previous_defs[-1].is_stub_class
+                    and previous_def.is_class
+                    and not previous_def.is_stub_class
                 ):
                     before = 1
                 elif depth:
@@ -600,7 +605,7 @@ def _maybe_empty_lines(self, current_line: Line) -> Tuple[int, int]:
                     before = 1
                 elif (
                     not depth
-                    and self.previous_defs[-1].depth
+                    and previous_def.depth
                     and current_line.leaves[-1].type == token.COLON
                     and (
                         current_line.leaves[0].value
@@ -617,7 +622,7 @@ def _maybe_empty_lines(self, current_line: Line) -> Tuple[int, int]:
                     before = 1
                 else:
                     before = 2
-            self.previous_defs.pop()
+
         if current_line.is_decorator or current_line.is_def or current_line.is_class:
             return self._maybe_empty_lines_for_class_or_def(current_line, before)
 

From 13bd4fffae0b95b0a1f55d335dd55a1de7de3d10 Mon Sep 17 00:00:00 2001
From: mihazagar <miha.zagar1@gmail.com>
Date: Sat, 22 Jul 2023 20:12:37 +0200
Subject: [PATCH 0810/1034] Fixing pre-commit using pyyaml with broken version
 (#3804)

---
 .pre-commit-config.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 0d68b81ccd7..10e65316e82 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -12,7 +12,7 @@ repos:
         additional_dependencies:
           &version_check_dependencies [
             commonmark==0.9.1,
-            pyyaml==5.4.1,
+            pyyaml==6.0.1,
             beautifulsoup4==4.9.3,
           ]
 

From c3235e6da7259394cd0c00fe36c3e089fbae1e4f Mon Sep 17 00:00:00 2001
From: Pradeep Kumar <gohanpra@gmail.com>
Date: Sun, 23 Jul 2023 21:56:19 -0700
Subject: [PATCH 0811/1034]  Fix unintentionally swapped words in index.md
 (#3809)

Fix unintentionally swapped words in index.md

I think the intent was to say "large changes in formatting", because it doesn't make sense to say "large formatting in changes".
---
 docs/index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/index.md b/docs/index.md
index 9d0db465022..49a44ecca5a 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -21,7 +21,7 @@ Try it out now using the [Black Playground](https://black.vercel.app).
 *Black* is [successfully used](https://github.com/psf/black#used-by) by
 many projects, small and big. *Black* has a comprehensive test suite, with efficient
 parallel tests, our own auto formatting and parallel Continuous Integration runner.
-Now that we have become stable, you should not expect large formatting to changes in
+Now that we have become stable, you should not expect large changes to formatting in
 the future. Stylistic changes will mostly be responses to bug reports and support for new Python
 syntax.
 

From d9d0a02d89207f712a40b6dabee708389208e558 Mon Sep 17 00:00:00 2001
From: "Yury V. Zaytsev" <yury@shurup.com>
Date: Thu, 27 Jul 2023 16:12:38 +0200
Subject: [PATCH 0812/1034] Fix typo in `target-version` param wrongly used in
 plural (#3817)

---
 docs/usage_and_configuration/the_basics.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index f5862edccaa..5efb50a9a12 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -63,7 +63,7 @@ $ black -t py37 -t py38 -t py39 -t py310
 In a [configuration file](#configuration-via-a-file), you can write:
 
 ```toml
-target-versions = ["py37", "py38", "py39", "py310"]
+target-version = ["py37", "py38", "py39", "py310"]
 ```
 
 _Black_ uses this option to decide what grammar to use to parse your code. In addition,

From 133af572072bf7bc92c23a609773c2ea66e483b7 Mon Sep 17 00:00:00 2001
From: freddiewanah <freddie.wanah@gmail.com>
Date: Fri, 28 Jul 2023 02:51:28 +1000
Subject: [PATCH 0813/1034] Rewrite mostly useless assert in test_trans.py
 (#3810)

This PR updates an assert statement that checks the bounds of a
string-slicing operation. The updated assertion provides more accurate
and informative error handling by specifically checking the relative
values of the indices and the string length.

The original assertion was essentially checking if Python's string
slicing was behaving as expected. However, it wasn't providing any
guarantees or useful information about the bounds i and j themselves.

The updated assertion checks that the indices used for slicing are
within the bounds of the string. It will throw an AssertionError if the
indices are out of bounds or if i > j, providing a more specific and
informative error.
---
 tests/test_trans.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tests/test_trans.py b/tests/test_trans.py
index dce8a939677..784e852e12a 100644
--- a/tests/test_trans.py
+++ b/tests/test_trans.py
@@ -13,7 +13,7 @@ def check(
         # a glance than only spans
         assert len(spans) == len(expected_slices)
         for (i, j), slice in zip(spans, expected_slices):
-            assert len(string[i:j]) == j - i
+            assert 0 <= i <= j <= len(string)
             assert string[i:j] == slice
 
         assert spans == expected_spans

From 1a972e3e11b144912155babdf48ff23d68059d57 Mon Sep 17 00:00:00 2001
From: Aneesh Agrawal <aagrawal@lyft.com>
Date: Thu, 27 Jul 2023 17:50:51 -0400
Subject: [PATCH 0814/1034] Add Lyft to organizations using black (#3818)

---
 README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index b12ddfb1290..9d0b29af215 100644
--- a/README.md
+++ b/README.md
@@ -137,8 +137,8 @@ SQLAlchemy, Poetry, PyPA applications (Warehouse, Bandersnatch, Pipenv, virtuale
 pandas, Pillow, Twisted, LocalStack, every Datadog Agent Integration, Home Assistant,
 Zulip, Kedro, OpenOA, FLORIS, ORBIT, WOMBAT, and many more.
 
-The following organizations use _Black_: Facebook, Dropbox, KeepTruckin, Mozilla, Quora,
-Duolingo, QuantumBlack, Tesla, Archer Aviation.
+The following organizations use _Black_: Facebook, Dropbox, KeepTruckin, Lyft, Mozilla,
+Quora, Duolingo, QuantumBlack, Tesla, Archer Aviation.
 
 Are we missing anyone? Let us know.
 

From 8a16b25fb1145e5b7de9c322e52167e8f6a59c79 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 31 Jul 2023 08:43:32 -0700
Subject: [PATCH 0815/1034] Bump furo from 2023.5.20 to 2023.7.26 in /docs
 (#3824)

Bumps [furo](https://github.com/pradyunsg/furo) from 2023.5.20 to 2023.7.26.
- [Release notes](https://github.com/pradyunsg/furo/releases)
- [Changelog](https://github.com/pradyunsg/furo/blob/main/docs/changelog.md)
- [Commits](https://github.com/pradyunsg/furo/compare/2023.05.20...2023.07.26)

---
updated-dependencies:
- dependency-name: furo
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 docs/requirements.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index f1b47c69413..ff179f3805e 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -6,4 +6,4 @@ Sphinx==6.1.3
 docutils==0.19
 sphinxcontrib-programoutput==0.17
 sphinx_copybutton==0.5.2
-furo==2023.5.20
+furo==2023.7.26

From 1b028cc9d99c2c2e82f9b727742539173a92a373 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Tue, 1 Aug 2023 01:48:21 -0700
Subject: [PATCH 0816/1034] [pre-commit.ci] pre-commit autoupdate (#3825)

---
 .pre-commit-config.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 10e65316e82..5430eef9180 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -29,7 +29,7 @@ repos:
       - id: isort
 
   - repo: https://github.com/pycqa/flake8
-    rev: 6.0.0
+    rev: 6.1.0
     hooks:
       - id: flake8
         additional_dependencies:

From 59e8936768889f583488df609c45302da8e88507 Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Thu, 3 Aug 2023 18:46:08 -0700
Subject: [PATCH 0817/1034] Document pre-commit mirror (#3828)

---
 .pre-commit-hooks.yaml                      |  2 ++
 CHANGES.md                                  |  5 +++++
 docs/integrations/source_version_control.md | 13 ++++++++-----
 3 files changed, 15 insertions(+), 5 deletions(-)

diff --git a/.pre-commit-hooks.yaml b/.pre-commit-hooks.yaml
index 137957045a6..a1ff41fded8 100644
--- a/.pre-commit-hooks.yaml
+++ b/.pre-commit-hooks.yaml
@@ -1,3 +1,5 @@
+# Note that we recommend using https://github.com/psf/black-pre-commit-mirror instead
+# This will work about 2x as fast as using the hooks in this repository
 - id: black
   name: black
   description: "Black: The uncompromising Python code formatter"
diff --git a/CHANGES.md b/CHANGES.md
index 709c767b329..1de08792f75 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -44,6 +44,11 @@
 
 <!-- For example, Docker, GitHub Actions, pre-commit, editors -->
 
+- Black now has an
+  [official pre-commit mirror](https://github.com/psf/black-pre-commit-mirror). Swapping
+  `https://github.com/psf/black` to `https://github.com/psf/black-pre-commit-mirror` in
+  your `.pre-commit-config.yaml` will make Black about 2x faster (#3828)
+
 ### Documentation
 
 <!-- Major changes to documentation and policies. Small docs changes
diff --git a/docs/integrations/source_version_control.md b/docs/integrations/source_version_control.md
index a9d33d2d853..24e732848f1 100644
--- a/docs/integrations/source_version_control.md
+++ b/docs/integrations/source_version_control.md
@@ -6,7 +6,8 @@ Use [pre-commit](https://pre-commit.com/). Once you
 
 ```yaml
 repos:
-  - repo: https://github.com/psf/black
+  # 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.7.0
     hooks:
       - id: black
@@ -17,8 +18,10 @@ repos:
         language_version: python3.11
 ```
 
-Feel free to switch out the `rev` value to something else, like another
-[tag/version][black-tags] or even a specific commit. Although we discourage the use of
+Feel free to switch out the `rev` value to a different version of Black.
+
+Note if you'd like to use a specific commit in `rev`, you'll need to swap the repo
+specified from the mirror to https://github.com/psf/black. We discourage the use of
 branches or other mutable refs since the hook [won't auto update as you may
 expect][pre-commit-mutable-rev].
 
@@ -30,7 +33,8 @@ include Jupyter Notebooks. To use this hook, simply replace the hook's `id: blac
 
 ```yaml
 repos:
-  - repo: https://github.com/psf/black
+  # 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.7.0
     hooks:
       - id: black-jupyter
@@ -45,6 +49,5 @@ repos:
 The `black-jupyter` hook became available in version 21.8b0.
 ```
 
-[black-tags]: https://github.com/psf/black/tags
 [pre-commit-mutable-rev]:
   https://pre-commit.com/#using-the-latest-version-for-a-repository

From c160e4b7ce30c661ac4f2dfa5038becf1b8c5c33 Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Thu, 3 Aug 2023 19:11:21 -0700
Subject: [PATCH 0818/1034] More concise formatting for dummy implementations
 (#3796)

---
 CHANGES.md                                  |  2 +
 src/black/linegen.py                        | 10 ++-
 src/black/lines.py                          | 27 +++++-
 src/black/mode.py                           |  1 +
 tests/data/miscellaneous/force_py36.py      |  4 +-
 tests/data/preview/comments7.py             |  3 +-
 tests/data/preview/dummy_implementations.py | 99 +++++++++++++++++++++
 7 files changed, 135 insertions(+), 11 deletions(-)
 create mode 100644 tests/data/preview/dummy_implementations.py

diff --git a/CHANGES.md b/CHANGES.md
index 1de08792f75..d084498f404 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -14,6 +14,8 @@
 
 <!-- Changes that affect Black's preview style -->
 
+- More concise formatting for dummy implementations (#3796)
+
 ### Configuration
 
 <!-- Changes to how Black can be configured -->
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 5ef3bbd1705..507e860190f 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -281,7 +281,9 @@ def visit_match_case(self, node: Node) -> Iterator[Line]:
 
     def visit_suite(self, node: Node) -> Iterator[Line]:
         """Visit a suite."""
-        if self.mode.is_pyi and is_stub_suite(node):
+        if (
+            self.mode.is_pyi or Preview.dummy_implementations in self.mode
+        ) and is_stub_suite(node):
             yield from self.visit(node.children[2])
         else:
             yield from self.visit_default(node)
@@ -296,7 +298,9 @@ def visit_simple_stmt(self, node: Node) -> Iterator[Line]:
 
         is_suite_like = node.parent and node.parent.type in STATEMENT
         if is_suite_like:
-            if self.mode.is_pyi and is_stub_body(node):
+            if (
+                self.mode.is_pyi or Preview.dummy_implementations in self.mode
+            ) and is_stub_body(node):
                 yield from self.visit_default(node)
             else:
                 yield from self.line(+1)
@@ -305,7 +309,7 @@ def visit_simple_stmt(self, node: Node) -> Iterator[Line]:
 
         else:
             if (
-                not self.mode.is_pyi
+                not (self.mode.is_pyi or Preview.dummy_implementations in self.mode)
                 or not node.parent
                 or not is_stub_suite(node.parent)
             ):
diff --git a/src/black/lines.py b/src/black/lines.py
index 016a489310d..0a307b45eff 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -165,6 +165,13 @@ def is_def(self) -> bool:
             and second_leaf.value == "def"
         )
 
+    @property
+    def is_stub_def(self) -> bool:
+        """Is this line a function definition with a body consisting only of "..."?"""
+        return self.is_def and self.leaves[-4:] == [Leaf(token.COLON, ":")] + [
+            Leaf(token.DOT, ".") for _ in range(3)
+        ]
+
     @property
     def is_class_paren_empty(self) -> bool:
         """Is this a class with no base classes but using parentheses?
@@ -578,6 +585,8 @@ def _maybe_empty_lines(self, current_line: Line) -> Tuple[int, int]:
             first_leaf.prefix = ""
         else:
             before = 0
+
+        user_had_newline = bool(before)
         depth = current_line.depth
 
         previous_def = None
@@ -589,7 +598,7 @@ def _maybe_empty_lines(self, current_line: Line) -> Tuple[int, int]:
             if self.mode.is_pyi:
                 if depth and not current_line.is_def and self.previous_line.is_def:
                     # Empty lines between attributes and methods should be preserved.
-                    before = min(1, before)
+                    before = 1 if user_had_newline else 0
                 elif (
                     Preview.blank_line_after_nested_stub_class in self.mode
                     and previous_def.is_class
@@ -624,7 +633,9 @@ def _maybe_empty_lines(self, current_line: Line) -> Tuple[int, int]:
                     before = 2
 
         if current_line.is_decorator or current_line.is_def or current_line.is_class:
-            return self._maybe_empty_lines_for_class_or_def(current_line, before)
+            return self._maybe_empty_lines_for_class_or_def(
+                current_line, before, user_had_newline
+            )
 
         if (
             self.previous_line
@@ -648,8 +659,8 @@ def _maybe_empty_lines(self, current_line: Line) -> Tuple[int, int]:
             return 0, 0
         return before, 0
 
-    def _maybe_empty_lines_for_class_or_def(
-        self, current_line: Line, before: int
+    def _maybe_empty_lines_for_class_or_def(  # noqa: C901
+        self, current_line: Line, before: int, user_had_newline: bool
     ) -> Tuple[int, int]:
         if not current_line.is_decorator:
             self.previous_defs.append(current_line)
@@ -715,6 +726,14 @@ def _maybe_empty_lines_for_class_or_def(
                 newlines = 0
         else:
             newlines = 1 if current_line.depth else 2
+            # If a user has left no space after a dummy implementation, don't insert
+            # new lines. This is useful for instance for @overload or Protocols.
+            if (
+                Preview.dummy_implementations in self.mode
+                and self.previous_line.is_stub_def
+                and not user_had_newline
+            ):
+                newlines = 0
         if comment_to_add_newlines is not None:
             previous_block = comment_to_add_newlines.previous_block
             if previous_block is not None:
diff --git a/src/black/mode.py b/src/black/mode.py
index 4d979afd84d..282c1669da7 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -182,6 +182,7 @@ class Preview(Enum):
     skip_magic_trailing_comma_in_subscript = auto()
     wrap_long_dict_values_in_parens = auto()
     wrap_multiple_context_managers_in_parens = auto()
+    dummy_implementations = auto()
 
 
 class Deprecated(UserWarning):
diff --git a/tests/data/miscellaneous/force_py36.py b/tests/data/miscellaneous/force_py36.py
index cad935e525a..4c9b70336e7 100644
--- a/tests/data/miscellaneous/force_py36.py
+++ b/tests/data/miscellaneous/force_py36.py
@@ -1,6 +1,6 @@
 # The input source must not contain any Py36-specific syntax (e.g. argument type
 # annotations, trailing comma after *rest) or this test becomes invalid.
-def long_function_name(argument_one, argument_two, argument_three, argument_four, argument_five, argument_six, *rest): ...
+def long_function_name(argument_one, argument_two, argument_three, argument_four, argument_five, argument_six, *rest): pass
 # output
 # The input source must not contain any Py36-specific syntax (e.g. argument type
 # annotations, trailing comma after *rest) or this test becomes invalid.
@@ -13,4 +13,4 @@ def long_function_name(
     argument_six,
     *rest,
 ):
-    ...
+    pass
diff --git a/tests/data/preview/comments7.py b/tests/data/preview/comments7.py
index ec2dc501d8e..8b1224017e5 100644
--- a/tests/data/preview/comments7.py
+++ b/tests/data/preview/comments7.py
@@ -278,8 +278,7 @@ class C:
     )
     def test_fails_invalid_post_data(
         self, pyramid_config, db_request, post_data, message
-    ):
-        ...
+    ): ...
 
 
 square = Square(4)  # type: Optional[Square]
diff --git a/tests/data/preview/dummy_implementations.py b/tests/data/preview/dummy_implementations.py
new file mode 100644
index 00000000000..e07c25ed129
--- /dev/null
+++ b/tests/data/preview/dummy_implementations.py
@@ -0,0 +1,99 @@
+from typing import NoReturn, Protocol, Union, overload
+
+
+def dummy(a): ...
+def other(b): ...
+
+
+@overload
+def a(arg: int) -> int: ...
+@overload
+def a(arg: str) -> str: ...
+@overload
+def a(arg: object) -> NoReturn: ...
+def a(arg: Union[int, str, object]) -> Union[int, str]:
+    if not isinstance(arg, (int, str)):
+        raise TypeError
+    return arg
+
+class Proto(Protocol):
+    def foo(self, a: int) -> int:
+        ...
+
+    def bar(self, b: str) -> str: ...
+    def baz(self, c: bytes) -> str:
+        ...
+
+
+def dummy_two():
+    ...
+@dummy
+def dummy_three():
+    ...
+
+def dummy_four():
+    ...
+
+@overload
+def b(arg: int) -> int: ...
+
+@overload
+def b(arg: str) -> str: ...
+@overload
+def b(arg: object) -> NoReturn: ...
+
+def b(arg: Union[int, str, object]) -> Union[int, str]:
+    if not isinstance(arg, (int, str)):
+        raise TypeError
+    return arg
+
+# output
+
+from typing import NoReturn, Protocol, Union, overload
+
+
+def dummy(a): ...
+def other(b): ...
+
+
+@overload
+def a(arg: int) -> int: ...
+@overload
+def a(arg: str) -> str: ...
+@overload
+def a(arg: object) -> NoReturn: ...
+def a(arg: Union[int, str, object]) -> Union[int, str]:
+    if not isinstance(arg, (int, str)):
+        raise TypeError
+    return arg
+
+
+class Proto(Protocol):
+    def foo(self, a: int) -> int: ...
+
+    def bar(self, b: str) -> str: ...
+    def baz(self, c: bytes) -> str: ...
+
+
+def dummy_two(): ...
+@dummy
+def dummy_three(): ...
+
+
+def dummy_four(): ...
+
+
+@overload
+def b(arg: int) -> int: ...
+
+
+@overload
+def b(arg: str) -> str: ...
+@overload
+def b(arg: object) -> NoReturn: ...
+
+
+def b(arg: Union[int, str, object]) -> Union[int, str]:
+    if not isinstance(arg, (int, str)):
+        raise TypeError
+    return arg

From 77f19944f632c48765175cafad07dc76b3810911 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Tue, 8 Aug 2023 08:41:39 -0700
Subject: [PATCH 0819/1034] [pre-commit.ci] pre-commit autoupdate (#3833)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

updates:
- [github.com/pre-commit/mirrors-prettier: v3.0.0 → v3.0.1](https://github.com/pre-commit/mirrors-prettier/compare/v3.0.0...v3.0.1)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 .pre-commit-config.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 5430eef9180..60a092f8b29 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -53,7 +53,7 @@ repos:
           - hypothesis
 
   - repo: https://github.com/pre-commit/mirrors-prettier
-    rev: v3.0.0
+    rev: v3.0.1
     hooks:
       - id: prettier
         exclude: \.github/workflows/diff_shades\.yml

From c36e468794f9256d5e922c399240d49782ba04f1 Mon Sep 17 00:00:00 2001
From: Christian Proud <christian.jay.proud.cic@gmail.com>
Date: Wed, 9 Aug 2023 02:12:05 +0800
Subject: [PATCH 0820/1034] Remove ENV_PATH on Black action completion (#3759)

---
 CHANGES.md     | 2 ++
 action/main.py | 2 ++
 2 files changed, 4 insertions(+)

diff --git a/CHANGES.md b/CHANGES.md
index d084498f404..8bf4188606c 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -50,6 +50,8 @@
   [official pre-commit mirror](https://github.com/psf/black-pre-commit-mirror). Swapping
   `https://github.com/psf/black` to `https://github.com/psf/black-pre-commit-mirror` in
   your `.pre-commit-config.yaml` will make Black about 2x faster (#3828)
+- The `.black.env` folder specified by `ENV_PATH` will now be removed on the completion
+  of the GitHub Action. (#3759)
 
 ### Documentation
 
diff --git a/action/main.py b/action/main.py
index 1911cfd7a01..c0af3930dbb 100644
--- a/action/main.py
+++ b/action/main.py
@@ -1,5 +1,6 @@
 import os
 import shlex
+import shutil
 import sys
 from pathlib import Path
 from subprocess import PIPE, STDOUT, run
@@ -73,5 +74,6 @@
         stderr=STDOUT,
         encoding="utf-8",
     )
+shutil.rmtree(ENV_PATH, ignore_errors=True)
 print(proc.stdout)
 sys.exit(proc.returncode)

From 66648c528a95553c1f822ece394ac98784baee47 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 14 Aug 2023 00:30:56 -0700
Subject: [PATCH 0821/1034] Bump pypa/cibuildwheel from 2.14.1 to 2.15.0
 (#3836)

---
 .github/workflows/pypi_upload.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/pypi_upload.yml b/.github/workflows/pypi_upload.yml
index 291193efc7a..9be231dd305 100644
--- a/.github/workflows/pypi_upload.yml
+++ b/.github/workflows/pypi_upload.yml
@@ -58,7 +58,7 @@ jobs:
       - uses: actions/checkout@v3
 
       - name: Build wheels via cibuildwheel
-        uses: pypa/cibuildwheel@v2.14.1
+        uses: pypa/cibuildwheel@v2.15.0
         env:
           CIBW_ARCHS_MACOS: "${{ matrix.macos_arch }}"
 

From 7c4fe83bd87ccef21f8c5a0cd5d122c5b004bb15 Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Tue, 15 Aug 2023 06:51:26 -0700
Subject: [PATCH 0822/1034] Make pre-commit do less (#3838)

---
 .pre-commit-config.yaml | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 60a092f8b29..a7ae7761494 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -63,3 +63,6 @@ repos:
     hooks:
       - id: end-of-file-fixer
       - id: trailing-whitespace
+
+ci:
+  autoupdate_schedule: quarterly

From ade371fd1c7118b8a82b281c28425fefb8cb719e Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Wed, 16 Aug 2023 00:01:21 -0700
Subject: [PATCH 0823/1034] [pre-commit.ci] pre-commit autoupdate (#3837)

---
 .pre-commit-config.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index a7ae7761494..6301526a445 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -39,7 +39,7 @@ repos:
         exclude: ^src/blib2to3/
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.4.1
+    rev: v1.5.0
     hooks:
       - id: mypy
         exclude: ^docs/conf.py

From 793c2b5f9f7c7ca267fbcab58d30997ac6b9497d Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Fri, 18 Aug 2023 18:32:47 -0700
Subject: [PATCH 0824/1034] Pin tox to fix CI (#3843)

---
 .github/workflows/test.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 4bf687435b4..8a139387c5b 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -45,7 +45,7 @@ jobs:
       - name: Install tox
         run: |
           python -m pip install --upgrade pip
-          python -m pip install --upgrade tox
+          python -m pip install --upgrade 'tox<4.7'
 
       - name: Unit tests
         if: "!startsWith(matrix.python-version, 'pypy')"

From c6a031e623c7991ac9129f578dc21dffe2d7ede3 Mon Sep 17 00:00:00 2001
From: Marc Mueller <30130371+cdce8p@users.noreply.github.com>
Date: Sat, 19 Aug 2023 04:26:36 +0200
Subject: [PATCH 0825/1034] Improve caching by comparing file hashes as
 fallback for mtime and size (#3821)

Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
---
 CHANGES.md                                    |   1 +
 .../reference/reference_classes.rst           |   7 +
 .../reference/reference_functions.rst         |   8 -
 pyproject.toml                                |   2 +-
 src/black/__init__.py                         |  11 +-
 src/black/cache.py                            | 160 +++++++++++-------
 src/black/concurrency.py                      |   9 +-
 tests/test_black.py                           | 155 +++++++++++------
 8 files changed, 219 insertions(+), 134 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 8bf4188606c..a14a55a03ac 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -33,6 +33,7 @@
 <!-- Changes that improve Black's performance. -->
 
 - Avoid importing `IPython` if notebook cells do not contain magics (#3782)
+- Improve caching by comparing file hashes as fallback for mtime and size. (#3821)
 
 ### Output
 
diff --git a/docs/contributing/reference/reference_classes.rst b/docs/contributing/reference/reference_classes.rst
index 29b25003af2..dc615579e30 100644
--- a/docs/contributing/reference/reference_classes.rst
+++ b/docs/contributing/reference/reference_classes.rst
@@ -186,6 +186,13 @@ Black Classes
     :show-inheritance:
     :members:
 
+:class:`Cache`
+------------------------
+
+.. autoclass:: black.cache.Cache
+    :show-inheritance:
+    :members:
+
 Enum Classes
 ~~~~~~~~~~~~~
 
diff --git a/docs/contributing/reference/reference_functions.rst b/docs/contributing/reference/reference_functions.rst
index 09517f73961..dd92e37a7d4 100644
--- a/docs/contributing/reference/reference_functions.rst
+++ b/docs/contributing/reference/reference_functions.rst
@@ -94,18 +94,10 @@ Split functions
 Caching
 -------
 
-.. autofunction:: black.cache.filter_cached
-
 .. autofunction:: black.cache.get_cache_dir
 
 .. autofunction:: black.cache.get_cache_file
 
-.. autofunction:: black.cache.get_cache_info
-
-.. autofunction:: black.cache.read_cache
-
-.. autofunction:: black.cache.write_cache
-
 Utilities
 ---------
 
diff --git a/pyproject.toml b/pyproject.toml
index d29b768c289..6cd3f34bc10 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -67,7 +67,7 @@ dependencies = [
   "pathspec>=0.9.0",
   "platformdirs>=2",
   "tomli>=1.1.0; python_version < '3.11'",
-  "typing_extensions>=3.10.0.0; python_version < '3.10'",
+  "typing_extensions>=4.0.1; python_version < '3.11'",
 ]
 dynamic = ["readme", "version"]
 
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 923a51867b5..dc06eab8dd0 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -34,7 +34,7 @@
 from pathspec.patterns.gitwildmatch import GitWildMatchPatternError
 
 from _black_version import version as __version__
-from black.cache import Cache, get_cache_info, read_cache, write_cache
+from black.cache import Cache
 from black.comments import normalize_fmt_off
 from black.const import (
     DEFAULT_EXCLUDES,
@@ -775,12 +775,9 @@ def reformat_one(
             if format_stdin_to_stdout(fast=fast, write_back=write_back, mode=mode):
                 changed = Changed.YES
         else:
-            cache: Cache = {}
+            cache = Cache.read(mode)
             if write_back not in (WriteBack.DIFF, WriteBack.COLOR_DIFF):
-                cache = read_cache(mode)
-                res_src = src.resolve()
-                res_src_s = str(res_src)
-                if res_src_s in cache and cache[res_src_s] == get_cache_info(res_src):
+                if not cache.is_changed(src):
                     changed = Changed.CACHED
             if changed is not Changed.CACHED and format_file_in_place(
                 src, fast=fast, write_back=write_back, mode=mode
@@ -789,7 +786,7 @@ def reformat_one(
             if (write_back is WriteBack.YES and changed is not Changed.CACHED) or (
                 write_back is WriteBack.CHECK and changed is Changed.NO
             ):
-                write_cache(cache, [src], mode)
+                cache.write([src])
         report.done(src, changed)
     except Exception as exc:
         if report.verbose:
diff --git a/src/black/cache.py b/src/black/cache.py
index 9455ff44772..ff15da2a94e 100644
--- a/src/black/cache.py
+++ b/src/black/cache.py
@@ -1,21 +1,28 @@
 """Caching of formatted files with feature-based invalidation."""
-
+import hashlib
 import os
 import pickle
+import sys
 import tempfile
+from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Dict, Iterable, Set, Tuple
+from typing import Dict, Iterable, NamedTuple, Set, Tuple
 
 from platformdirs import user_cache_dir
 
 from _black_version import version as __version__
 from black.mode import Mode
 
-# types
-Timestamp = float
-FileSize = int
-CacheInfo = Tuple[Timestamp, FileSize]
-Cache = Dict[str, CacheInfo]
+if sys.version_info >= (3, 11):
+    from typing import Self
+else:
+    from typing_extensions import Self
+
+
+class FileData(NamedTuple):
+    st_mtime: float
+    st_size: int
+    hash: str
 
 
 def get_cache_dir() -> Path:
@@ -37,61 +44,92 @@ def get_cache_dir() -> Path:
 CACHE_DIR = get_cache_dir()
 
 
-def read_cache(mode: Mode) -> Cache:
-    """Read the cache if it exists and is well formed.
-
-    If it is not well formed, the call to write_cache later should resolve the issue.
-    """
-    cache_file = get_cache_file(mode)
-    if not cache_file.exists():
-        return {}
-
-    with cache_file.open("rb") as fobj:
-        try:
-            cache: Cache = pickle.load(fobj)
-        except (pickle.UnpicklingError, ValueError, IndexError):
-            return {}
-
-    return cache
-
-
 def get_cache_file(mode: Mode) -> Path:
     return CACHE_DIR / f"cache.{mode.get_cache_key()}.pickle"
 
 
-def get_cache_info(path: Path) -> CacheInfo:
-    """Return the information used to check if a file is already formatted or not."""
-    stat = path.stat()
-    return stat.st_mtime, stat.st_size
-
-
-def filter_cached(cache: Cache, sources: Iterable[Path]) -> Tuple[Set[Path], Set[Path]]:
-    """Split an iterable of paths in `sources` into two sets.
-
-    The first contains paths of files that modified on disk or are not in the
-    cache. The other contains paths to non-modified files.
-    """
-    todo, done = set(), set()
-    for src in sources:
-        res_src = src.resolve()
-        if cache.get(str(res_src)) != get_cache_info(res_src):
-            todo.add(src)
-        else:
-            done.add(src)
-    return todo, done
-
-
-def write_cache(cache: Cache, sources: Iterable[Path], mode: Mode) -> None:
-    """Update the cache file."""
-    cache_file = get_cache_file(mode)
-    try:
-        CACHE_DIR.mkdir(parents=True, exist_ok=True)
-        new_cache = {
-            **cache,
-            **{str(src.resolve()): get_cache_info(src) for src in sources},
-        }
-        with tempfile.NamedTemporaryFile(dir=str(cache_file.parent), delete=False) as f:
-            pickle.dump(new_cache, f, protocol=4)
-        os.replace(f.name, cache_file)
-    except OSError:
-        pass
+@dataclass
+class Cache:
+    mode: Mode
+    cache_file: Path
+    file_data: Dict[str, FileData] = field(default_factory=dict)
+
+    @classmethod
+    def read(cls, mode: Mode) -> Self:
+        """Read the cache if it exists and is well formed.
+
+        If it is not well formed, the call to write later should
+        resolve the issue.
+        """
+        cache_file = get_cache_file(mode)
+        if not cache_file.exists():
+            return cls(mode, cache_file)
+
+        with cache_file.open("rb") as fobj:
+            try:
+                file_data: Dict[str, FileData] = pickle.load(fobj)
+            except (pickle.UnpicklingError, ValueError, IndexError):
+                return cls(mode, cache_file)
+
+        return cls(mode, cache_file, file_data)
+
+    @staticmethod
+    def hash_digest(path: Path) -> str:
+        """Return hash digest for path."""
+
+        data = path.read_bytes()
+        return hashlib.sha256(data).hexdigest()
+
+    @staticmethod
+    def get_file_data(path: Path) -> FileData:
+        """Return file data for path."""
+
+        stat = path.stat()
+        hash = Cache.hash_digest(path)
+        return FileData(stat.st_mtime, stat.st_size, hash)
+
+    def is_changed(self, source: Path) -> bool:
+        """Check if source has changed compared to cached version."""
+        res_src = source.resolve()
+        old = self.file_data.get(str(res_src))
+        if old is None:
+            return True
+
+        st = res_src.stat()
+        if st.st_size != old.st_size:
+            return True
+        if int(st.st_mtime) != int(old.st_mtime):
+            new_hash = Cache.hash_digest(res_src)
+            if new_hash != old.hash:
+                return True
+        return False
+
+    def filtered_cached(self, sources: Iterable[Path]) -> Tuple[Set[Path], Set[Path]]:
+        """Split an iterable of paths in `sources` into two sets.
+
+        The first contains paths of files that modified on disk or are not in the
+        cache. The other contains paths to non-modified files.
+        """
+        changed: Set[Path] = set()
+        done: Set[Path] = set()
+        for src in sources:
+            if self.is_changed(src):
+                changed.add(src)
+            else:
+                done.add(src)
+        return changed, done
+
+    def write(self, sources: Iterable[Path]) -> None:
+        """Update the cache file data and write a new cache file."""
+        self.file_data.update(
+            **{str(src.resolve()): Cache.get_file_data(src) for src in sources}
+        )
+        try:
+            CACHE_DIR.mkdir(parents=True, exist_ok=True)
+            with tempfile.NamedTemporaryFile(
+                dir=str(self.cache_file.parent), delete=False
+            ) as f:
+                pickle.dump(self.file_data, f, protocol=4)
+            os.replace(f.name, self.cache_file)
+        except OSError:
+            pass
diff --git a/src/black/concurrency.py b/src/black/concurrency.py
index 893eba6675a..ce016578399 100644
--- a/src/black/concurrency.py
+++ b/src/black/concurrency.py
@@ -17,7 +17,7 @@
 from mypy_extensions import mypyc_attr
 
 from black import WriteBack, format_file_in_place
-from black.cache import Cache, filter_cached, read_cache, write_cache
+from black.cache import Cache
 from black.mode import Mode
 from black.output import err
 from black.report import Changed, Report
@@ -133,10 +133,9 @@ async def schedule_formatting(
     `write_back`, `fast`, and `mode` options are passed to
     :func:`format_file_in_place`.
     """
-    cache: Cache = {}
+    cache = Cache.read(mode)
     if write_back not in (WriteBack.DIFF, WriteBack.COLOR_DIFF):
-        cache = read_cache(mode)
-        sources, cached = filter_cached(cache, sources)
+        sources, cached = cache.filtered_cached(sources)
         for src in sorted(cached):
             report.done(src, Changed.CACHED)
     if not sources:
@@ -185,4 +184,4 @@ async def schedule_formatting(
     if cancelled:
         await asyncio.gather(*cancelled, return_exceptions=True)
     if sources_to_cache:
-        write_cache(cache, sources_to_cache, mode)
+        cache.write(sources_to_cache)
diff --git a/tests/test_black.py b/tests/test_black.py
index 3b3ab721c5f..8ae92172d43 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -41,7 +41,7 @@
 import black.files
 from black import Feature, TargetVersion
 from black import re_compile_maybe_verbose as compile_pattern
-from black.cache import get_cache_dir, get_cache_file
+from black.cache import FileData, get_cache_dir, get_cache_file
 from black.debug import DebugVisitor
 from black.output import color_diff, diff
 from black.report import Report
@@ -1121,10 +1121,10 @@ def test_single_file_force_pyi(self) -> None:
             self.invokeBlack([str(path), "--pyi"])
             actual = path.read_text(encoding="utf-8")
             # verify cache with --pyi is separate
-            pyi_cache = black.read_cache(pyi_mode)
-            self.assertIn(str(path), pyi_cache)
-            normal_cache = black.read_cache(DEFAULT_MODE)
-            self.assertNotIn(str(path), normal_cache)
+            pyi_cache = black.Cache.read(pyi_mode)
+            assert not pyi_cache.is_changed(path)
+            normal_cache = black.Cache.read(DEFAULT_MODE)
+            assert normal_cache.is_changed(path)
         self.assertFormatEqual(expected, actual)
         black.assert_equivalent(contents, actual)
         black.assert_stable(contents, actual, pyi_mode)
@@ -1146,11 +1146,11 @@ def test_multi_file_force_pyi(self) -> None:
                 actual = path.read_text(encoding="utf-8")
                 self.assertEqual(actual, expected)
             # verify cache with --pyi is separate
-            pyi_cache = black.read_cache(pyi_mode)
-            normal_cache = black.read_cache(reg_mode)
+            pyi_cache = black.Cache.read(pyi_mode)
+            normal_cache = black.Cache.read(reg_mode)
             for path in paths:
-                self.assertIn(str(path), pyi_cache)
-                self.assertNotIn(str(path), normal_cache)
+                assert not pyi_cache.is_changed(path)
+                assert normal_cache.is_changed(path)
 
     def test_pipe_force_pyi(self) -> None:
         source, expected = read_data("miscellaneous", "force_pyi")
@@ -1171,10 +1171,10 @@ def test_single_file_force_py36(self) -> None:
             self.invokeBlack([str(path), *PY36_ARGS])
             actual = path.read_text(encoding="utf-8")
             # verify cache with --target-version is separate
-            py36_cache = black.read_cache(py36_mode)
-            self.assertIn(str(path), py36_cache)
-            normal_cache = black.read_cache(reg_mode)
-            self.assertNotIn(str(path), normal_cache)
+            py36_cache = black.Cache.read(py36_mode)
+            assert not py36_cache.is_changed(path)
+            normal_cache = black.Cache.read(reg_mode)
+            assert normal_cache.is_changed(path)
         self.assertEqual(actual, expected)
 
     @event_loop()
@@ -1194,11 +1194,11 @@ def test_multi_file_force_py36(self) -> None:
                 actual = path.read_text(encoding="utf-8")
                 self.assertEqual(actual, expected)
             # verify cache with --target-version is separate
-            pyi_cache = black.read_cache(py36_mode)
-            normal_cache = black.read_cache(reg_mode)
+            pyi_cache = black.Cache.read(py36_mode)
+            normal_cache = black.Cache.read(reg_mode)
             for path in paths:
-                self.assertIn(str(path), pyi_cache)
-                self.assertNotIn(str(path), normal_cache)
+                assert not pyi_cache.is_changed(path)
+                assert normal_cache.is_changed(path)
 
     def test_pipe_force_py36(self) -> None:
         source, expected = read_data("miscellaneous", "force_py36")
@@ -1953,19 +1953,20 @@ def test_cache_broken_file(self) -> None:
         with cache_dir() as workspace:
             cache_file = get_cache_file(mode)
             cache_file.write_text("this is not a pickle", encoding="utf-8")
-            assert black.read_cache(mode) == {}
+            assert black.Cache.read(mode).file_data == {}
             src = (workspace / "test.py").resolve()
             src.write_text("print('hello')", encoding="utf-8")
             invokeBlack([str(src)])
-            cache = black.read_cache(mode)
-            assert str(src) in cache
+            cache = black.Cache.read(mode)
+            assert not cache.is_changed(src)
 
     def test_cache_single_file_already_cached(self) -> None:
         mode = DEFAULT_MODE
         with cache_dir() as workspace:
             src = (workspace / "test.py").resolve()
             src.write_text("print('hello')", encoding="utf-8")
-            black.write_cache({}, [src], mode)
+            cache = black.Cache.read(mode)
+            cache.write([src])
             invokeBlack([str(src)])
             assert src.read_text(encoding="utf-8") == "print('hello')"
 
@@ -1979,13 +1980,14 @@ def test_cache_multiple_files(self) -> None:
             one.write_text("print('hello')", encoding="utf-8")
             two = (workspace / "two.py").resolve()
             two.write_text("print('hello')", encoding="utf-8")
-            black.write_cache({}, [one], mode)
+            cache = black.Cache.read(mode)
+            cache.write([one])
             invokeBlack([str(workspace)])
             assert one.read_text(encoding="utf-8") == "print('hello')"
             assert two.read_text(encoding="utf-8") == 'print("hello")\n'
-            cache = black.read_cache(mode)
-            assert str(one) in cache
-            assert str(two) in cache
+            cache = black.Cache.read(mode)
+            assert not cache.is_changed(one)
+            assert not cache.is_changed(two)
 
     @pytest.mark.parametrize("color", [False, True], ids=["no-color", "with-color"])
     def test_no_cache_when_writeback_diff(self, color: bool) -> None:
@@ -1993,8 +1995,8 @@ def test_no_cache_when_writeback_diff(self, color: bool) -> None:
         with cache_dir() as workspace:
             src = (workspace / "test.py").resolve()
             src.write_text("print('hello')", encoding="utf-8")
-            with patch("black.read_cache") as read_cache, patch(
-                "black.write_cache"
+            with patch.object(black.Cache, "read") as read_cache, patch.object(
+                black.Cache, "write"
             ) as write_cache:
                 cmd = [str(src), "--diff"]
                 if color:
@@ -2002,8 +2004,8 @@ def test_no_cache_when_writeback_diff(self, color: bool) -> None:
                 invokeBlack(cmd)
                 cache_file = get_cache_file(mode)
                 assert cache_file.exists() is False
+                read_cache.assert_called_once()
                 write_cache.assert_not_called()
-                read_cache.assert_not_called()
 
     @pytest.mark.parametrize("color", [False, True], ids=["no-color", "with-color"])
     @event_loop()
@@ -2036,17 +2038,17 @@ def test_no_cache_when_stdin(self) -> None:
     def test_read_cache_no_cachefile(self) -> None:
         mode = DEFAULT_MODE
         with cache_dir():
-            assert black.read_cache(mode) == {}
+            assert black.Cache.read(mode).file_data == {}
 
     def test_write_cache_read_cache(self) -> None:
         mode = DEFAULT_MODE
         with cache_dir() as workspace:
             src = (workspace / "test.py").resolve()
             src.touch()
-            black.write_cache({}, [src], mode)
-            cache = black.read_cache(mode)
-            assert str(src) in cache
-            assert cache[str(src)] == black.get_cache_info(src)
+            write_cache = black.Cache.read(mode)
+            write_cache.write([src])
+            read_cache = black.Cache.read(mode)
+            assert not read_cache.is_changed(src)
 
     def test_filter_cached(self) -> None:
         with TemporaryDirectory() as workspace:
@@ -2057,21 +2059,67 @@ def test_filter_cached(self) -> None:
             uncached.touch()
             cached.touch()
             cached_but_changed.touch()
-            cache = {
-                str(cached): black.get_cache_info(cached),
-                str(cached_but_changed): (0.0, 0),
-            }
-            todo, done = black.cache.filter_cached(
-                cache, {uncached, cached, cached_but_changed}
-            )
+            cache = black.Cache.read(DEFAULT_MODE)
+
+            orig_func = black.Cache.get_file_data
+
+            def wrapped_func(path: Path) -> FileData:
+                if path == cached:
+                    return orig_func(path)
+                if path == cached_but_changed:
+                    return FileData(0.0, 0, "")
+                raise AssertionError
+
+            with patch.object(black.Cache, "get_file_data", side_effect=wrapped_func):
+                cache.write([cached, cached_but_changed])
+            todo, done = cache.filtered_cached({uncached, cached, cached_but_changed})
             assert todo == {uncached, cached_but_changed}
             assert done == {cached}
 
+    def test_filter_cached_hash(self) -> None:
+        with TemporaryDirectory() as workspace:
+            path = Path(workspace)
+            src = (path / "test.py").resolve()
+            src.write_text("print('hello')", encoding="utf-8")
+            st = src.stat()
+            cache = black.Cache.read(DEFAULT_MODE)
+            cache.write([src])
+            cached_file_data = cache.file_data[str(src)]
+
+            todo, done = cache.filtered_cached([src])
+            assert todo == set()
+            assert done == {src}
+            assert cached_file_data.st_mtime == st.st_mtime
+
+            # Modify st_mtime
+            cached_file_data = cache.file_data[str(src)] = FileData(
+                cached_file_data.st_mtime - 1,
+                cached_file_data.st_size,
+                cached_file_data.hash,
+            )
+            todo, done = cache.filtered_cached([src])
+            assert todo == set()
+            assert done == {src}
+            assert cached_file_data.st_mtime < st.st_mtime
+            assert cached_file_data.st_size == st.st_size
+            assert cached_file_data.hash == black.Cache.hash_digest(src)
+
+            # Modify contents
+            src.write_text("print('hello world')", encoding="utf-8")
+            new_st = src.stat()
+            todo, done = cache.filtered_cached([src])
+            assert todo == {src}
+            assert done == set()
+            assert cached_file_data.st_mtime < new_st.st_mtime
+            assert cached_file_data.st_size != new_st.st_size
+            assert cached_file_data.hash != black.Cache.hash_digest(src)
+
     def test_write_cache_creates_directory_if_needed(self) -> None:
         mode = DEFAULT_MODE
         with cache_dir(exists=False) as workspace:
             assert not workspace.exists()
-            black.write_cache({}, [], mode)
+            cache = black.Cache.read(mode)
+            cache.write([])
             assert workspace.exists()
 
     @event_loop()
@@ -2085,15 +2133,17 @@ def test_failed_formatting_does_not_get_cached(self) -> None:
             clean = (workspace / "clean.py").resolve()
             clean.write_text('print("hello")\n', encoding="utf-8")
             invokeBlack([str(workspace)], exit_code=123)
-            cache = black.read_cache(mode)
-            assert str(failing) not in cache
-            assert str(clean) in cache
+            cache = black.Cache.read(mode)
+            assert cache.is_changed(failing)
+            assert not cache.is_changed(clean)
 
     def test_write_cache_write_fail(self) -> None:
         mode = DEFAULT_MODE
-        with cache_dir(), patch.object(Path, "open") as mock:
-            mock.side_effect = OSError
-            black.write_cache({}, [], mode)
+        with cache_dir():
+            cache = black.Cache.read(mode)
+            with patch.object(Path, "open") as mock:
+                mock.side_effect = OSError
+                cache.write([])
 
     def test_read_cache_line_lengths(self) -> None:
         mode = DEFAULT_MODE
@@ -2101,11 +2151,12 @@ def test_read_cache_line_lengths(self) -> None:
         with cache_dir() as workspace:
             path = (workspace / "file.py").resolve()
             path.touch()
-            black.write_cache({}, [path], mode)
-            one = black.read_cache(mode)
-            assert str(path) in one
-            two = black.read_cache(short_mode)
-            assert str(path) not in two
+            cache = black.Cache.read(mode)
+            cache.write([path])
+            one = black.Cache.read(mode)
+            assert not one.is_changed(path)
+            two = black.Cache.read(short_mode)
+            assert two.is_changed(path)
 
 
 def assert_collected_sources(

From 066aa9210ac7815cbb9b4a25075f54d614b0afc7 Mon Sep 17 00:00:00 2001
From: Marc Mueller <30130371+cdce8p@users.noreply.github.com>
Date: Sat, 19 Aug 2023 17:09:59 +0200
Subject: [PATCH 0826/1034] Remove tox pin (#3844)

---
 .github/workflows/test.yml | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 8a139387c5b..216b0ba5236 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -45,11 +45,12 @@ jobs:
       - name: Install tox
         run: |
           python -m pip install --upgrade pip
-          python -m pip install --upgrade 'tox<4.7'
+          python -m pip install --upgrade tox
 
       - name: Unit tests
         if: "!startsWith(matrix.python-version, 'pypy')"
-        run: tox -e ci-py -- -v --color=yes
+        run:
+          tox -e ci-py$(echo ${{ matrix.python-version }} | tr -d '.') -- -v --color=yes
 
       - name: Unit tests (pypy)
         if: "startsWith(matrix.python-version, 'pypy')"

From 6310a405f6663948f7e0b9411cb54e5db2b712a6 Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Sat, 19 Aug 2023 08:13:05 -0700
Subject: [PATCH 0827/1034] Improve handling of root to get_sources (#3847)

This is a little more type safe and a little cleaner
---
 src/black/__init__.py | 14 ++++++++------
 tests/test_black.py   | 28 ++++++++--------------------
 2 files changed, 16 insertions(+), 26 deletions(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index dc06eab8dd0..6fc91d2e6d3 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -560,9 +560,10 @@ def main(  # noqa: C901
             content=code, fast=fast, write_back=write_back, mode=mode, report=report
         )
     else:
+        assert root is not None  # root is only None if code is not None
         try:
             sources = get_sources(
-                ctx=ctx,
+                root=root,
                 src=src,
                 quiet=quiet,
                 verbose=verbose,
@@ -615,7 +616,7 @@ def main(  # noqa: C901
 
 def get_sources(
     *,
-    ctx: click.Context,
+    root: Path,
     src: Tuple[str, ...],
     quiet: bool,
     verbose: bool,
@@ -628,7 +629,6 @@ def get_sources(
 ) -> Set[Path]:
     """Compute the set of files to be formatted."""
     sources: Set[Path] = set()
-    root = ctx.obj["root"]
 
     using_default_exclude = exclude is None
     exclude = re_compile_maybe_verbose(DEFAULT_EXCLUDES) if exclude is None else exclude
@@ -645,7 +645,7 @@ def get_sources(
 
         if is_stdin or p.is_file():
             normalized_path: Optional[str] = normalize_path_maybe_ignore(
-                p, ctx.obj["root"], report
+                p, root, report
             )
             if normalized_path is None:
                 if verbose:
@@ -674,7 +674,9 @@ def get_sources(
 
             sources.add(p)
         elif p.is_dir():
-            p = root / normalize_path_maybe_ignore(p, ctx.obj["root"], report)
+            p_relative = normalize_path_maybe_ignore(p, root, report)
+            assert p_relative is not None
+            p = root / p_relative
             if verbose:
                 out(f'Found input source directory: "{p}"', fg="blue")
 
@@ -686,7 +688,7 @@ def get_sources(
             sources.update(
                 gen_python_files(
                     p.iterdir(),
-                    ctx.obj["root"],
+                    root,
                     include,
                     exclude,
                     extend_exclude,
diff --git a/tests/test_black.py b/tests/test_black.py
index 8ae92172d43..79930fabf1f 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -507,13 +507,11 @@ def _mocked_calls() -> bool:
         with patch("pathlib.Path.iterdir", return_value=target_contents), patch(
             "pathlib.Path.cwd", return_value=working_directory
         ), patch("pathlib.Path.is_dir", side_effect=mock_n_calls([True])):
-            ctx = FakeContext()
             # Note that the root folder (project_root) isn't the folder
             # named "root" (aka working_directory)
-            ctx.obj["root"] = project_root
             report = MagicMock(verbose=True)
             black.get_sources(
-                ctx=ctx,
+                root=project_root,
                 src=("./child",),
                 quiet=False,
                 verbose=True,
@@ -2163,7 +2161,7 @@ def assert_collected_sources(
     src: Sequence[Union[str, Path]],
     expected: Sequence[Union[str, Path]],
     *,
-    ctx: Optional[FakeContext] = None,
+    root: Optional[Path] = None,
     exclude: Optional[str] = None,
     include: Optional[str] = None,
     extend_exclude: Optional[str] = None,
@@ -2179,7 +2177,7 @@ def assert_collected_sources(
     )
     gs_force_exclude = None if force_exclude is None else compile_pattern(force_exclude)
     collected = black.get_sources(
-        ctx=ctx or FakeContext(),
+        root=root or THIS_DIR,
         src=gs_src,
         quiet=False,
         verbose=False,
@@ -2215,9 +2213,7 @@ def test_gitignore_used_as_default(self) -> None:
             base / "b/.definitely_exclude/a.pyi",
         ]
         src = [base / "b/"]
-        ctx = FakeContext()
-        ctx.obj["root"] = base
-        assert_collected_sources(src, expected, ctx=ctx, extend_exclude=r"/exclude/")
+        assert_collected_sources(src, expected, root=base, extend_exclude=r"/exclude/")
 
     def test_gitignore_used_on_multiple_sources(self) -> None:
         root = Path(DATA_DIR / "gitignore_used_on_multiple_sources")
@@ -2225,10 +2221,8 @@ def test_gitignore_used_on_multiple_sources(self) -> None:
             root / "dir1" / "b.py",
             root / "dir2" / "b.py",
         ]
-        ctx = FakeContext()
-        ctx.obj["root"] = root
         src = [root / "dir1", root / "dir2"]
-        assert_collected_sources(src, expected, ctx=ctx)
+        assert_collected_sources(src, expected, root=root)
 
     @patch("black.find_project_root", lambda *args: (THIS_DIR.resolve(), None))
     def test_exclude_for_issue_1572(self) -> None:
@@ -2334,9 +2328,7 @@ def test_gitignore_that_ignores_subfolders(self) -> None:
         # If gitignore with */* is in root
         root = Path(DATA_DIR / "ignore_subfolders_gitignore_tests" / "subdir")
         expected = [root / "b.py"]
-        ctx = FakeContext()
-        ctx.obj["root"] = root
-        assert_collected_sources([root], expected, ctx=ctx)
+        assert_collected_sources([root], expected, root=root)
 
         # If .gitignore with */* is nested
         root = Path(DATA_DIR / "ignore_subfolders_gitignore_tests")
@@ -2344,17 +2336,13 @@ def test_gitignore_that_ignores_subfolders(self) -> None:
             root / "a.py",
             root / "subdir" / "b.py",
         ]
-        ctx = FakeContext()
-        ctx.obj["root"] = root
-        assert_collected_sources([root], expected, ctx=ctx)
+        assert_collected_sources([root], expected, root=root)
 
         # If command is executed from outer dir
         root = Path(DATA_DIR / "ignore_subfolders_gitignore_tests")
         target = root / "subdir"
         expected = [target / "b.py"]
-        ctx = FakeContext()
-        ctx.obj["root"] = root
-        assert_collected_sources([target], expected, ctx=ctx)
+        assert_collected_sources([target], expected, root=root)
 
     def test_empty_include(self) -> None:
         path = DATA_DIR / "include_exclude_tests"

From d9c249c25a77f75e70278aab9ec65c10ce08b0a8 Mon Sep 17 00:00:00 2001
From: Kjell-Magnus <kmgrime@gmail.com>
Date: Tue, 22 Aug 2023 21:40:10 +0200
Subject: [PATCH 0828/1034] Fix download badge link (#3853)

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 9d0b29af215..b257c333f0d 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@
 <a href="https://coveralls.io/github/psf/black?branch=main"><img alt="Coverage Status" src="https://coveralls.io/repos/github/psf/black/badge.svg?branch=main"></a>
 <a href="/psf/black/blob/main/LICENSE"><img alt="License: MIT" src="https://black.readthedocs.io/en/stable/_static/license.svg"></a>
 <a href="https://pypi.org/project/black/"><img alt="PyPI" src="https://img.shields.io/pypi/v/black"></a>
-<a href="https://pepy.tech/project/black"><img alt="Downloads" src="https://pepy.tech/badge/black"></a>
+<a href="https://pepy.tech/project/black"><img alt="Downloads" src="https://static.pepy.tech/badge/black"></a>
 <a href="https://anaconda.org/conda-forge/black/"><img alt="conda-forge" src="https://img.shields.io/conda/dn/conda-forge/black.svg?label=conda-forge"></a>
 <a href="/psf/black"><img alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></a>
 </p>

From 47676bf5939ae5c8e670d947917bc8af4732eab6 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Sat, 26 Aug 2023 08:44:17 -0500
Subject: [PATCH 0829/1034] Bump furo from 2023.7.26 to 2023.8.19 in /docs +
 sphinx to 7.2.3 (#3848)

* Bump furo from 2023.7.26 to 2023.8.19 in /docs

Bumps [furo](https://github.com/pradyunsg/furo) from 2023.7.26 to 2023.8.19.
- [Release notes](https://github.com/pradyunsg/furo/releases)
- [Changelog](https://github.com/pradyunsg/furo/blob/main/docs/changelog.md)
- [Commits](https://github.com/pradyunsg/furo/compare/2023.07.26...2023.08.19)

---
updated-dependencies:
- dependency-name: furo
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>

* Move to sphinx 7.2.3 + fix intersphinx_mapping

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Cooper Ry Lees <me@cooperlees.com>
---
 docs/conf.py          | 2 +-
 docs/requirements.txt | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py
index 7fc4f8f589e..f7cf1b42842 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -213,4 +213,4 @@ def make_pypi_svg(version: str) -> None:
 # -- Options for intersphinx extension ---------------------------------------
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {"https://docs.python.org/3/": None}
+intersphinx_mapping = {"<name>": ("https://docs.python.org/3/", None)}
diff --git a/docs/requirements.txt b/docs/requirements.txt
index ff179f3805e..dad39f67ed3 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,9 +1,9 @@
 # Used by ReadTheDocs; pinned requirements for stability.
 
 myst-parser==2.0.0
-Sphinx==6.1.3
+Sphinx==7.2.3
 # Older versions break Sphinx even though they're declared to be supported.
 docutils==0.19
 sphinxcontrib-programoutput==0.17
 sphinx_copybutton==0.5.2
-furo==2023.7.26
+furo==2023.8.19

From 58f1bf69d2ed2f6e3e5fa6a31e01ae58c9ffcff9 Mon Sep 17 00:00:00 2001
From: "Johnny.H" <jnhyperion@gmail.com>
Date: Sun, 3 Sep 2023 10:46:23 +0800
Subject: [PATCH 0830/1034] Move coverage configurations to `pyproject.toml`
 (#3858)

---
 .coveragerc                | 9 ---------
 .github/workflows/test.yml | 4 ++--
 pyproject.toml             | 9 +++++++++
 3 files changed, 11 insertions(+), 11 deletions(-)
 delete mode 100644 .coveragerc

diff --git a/.coveragerc b/.coveragerc
deleted file mode 100644
index 5577e496a57..00000000000
--- a/.coveragerc
+++ /dev/null
@@ -1,9 +0,0 @@
-[report]
-omit =
-  src/blib2to3/*
-  tests/data/*
-  */site-packages/*
-  .tox/*
-
-[run]
-relative_files = True
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 216b0ba5236..7daa31ee903 100644
--- a/.github/workflows/test.yml
+++ b/.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@v20201129
+        uses: AndreMiras/coveralls-python-action@8799c9f4443ac4201d2e2f2c725d577174683b99
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           parallel: true
@@ -77,7 +77,7 @@ jobs:
     steps:
       - uses: actions/checkout@v3
       - name: Send finished signal to Coveralls
-        uses: AndreMiras/coveralls-python-action@v20201129
+        uses: AndreMiras/coveralls-python-action@8799c9f4443ac4201d2e2f2c725d577174683b99
         with:
           parallel-finished: true
           debug: true
diff --git a/pyproject.toml b/pyproject.toml
index 6cd3f34bc10..ea5c9f84684 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -210,3 +210,12 @@ filterwarnings = [
     # Work around https://github.com/pytest-dev/pytest/issues/10977 for Python 3.12
     '''ignore:(Attribute s|Attribute n|ast.Str|ast.Bytes|ast.NameConstant|ast.Num) is deprecated and will be removed in Python 3.14:DeprecationWarning'''
 ]
+[tool.coverage.report]
+omit = [
+  "src/blib2to3/*",
+  "tests/data/*",
+  "*/site-packages/*",
+  ".tox/*"
+]
+[tool.coverage.run]
+relative_files = true

From df50fee7fd85018f8db462774512a83031f00322 Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Wed, 6 Sep 2023 21:06:07 -0700
Subject: [PATCH 0831/1034] Apply ignore logic before symlink resolution
 (#3846)

This means, for instance, that a gitignored symlink cannot affect your
formatting. Fixes #3527, fixes #3826
---
 CHANGES.md          |  2 ++
 src/black/files.py  | 20 ++++++++-------
 tests/test_black.py | 62 +++++++++++++++++++++++++--------------------
 3 files changed, 48 insertions(+), 36 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index a14a55a03ac..2168c1b90ce 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -20,6 +20,8 @@
 
 <!-- Changes to how Black can be configured -->
 
+- Black now applies exclusion and ignore logic before resolving symlinks (#3846)
+
 ### Packaging
 
 <!-- Changes to how Black is packaged, such as dependency requirements -->
diff --git a/src/black/files.py b/src/black/files.py
index 368e4170d47..362898dc0fd 100644
--- a/src/black/files.py
+++ b/src/black/files.py
@@ -330,35 +330,37 @@ def gen_python_files(
 
     assert root.is_absolute(), f"INTERNAL ERROR: `root` must be absolute but is {root}"
     for child in paths:
-        normalized_path = normalize_path_maybe_ignore(child, root, report)
-        if normalized_path is None:
-            continue
+        root_relative_path = child.absolute().relative_to(root).as_posix()
 
         # First ignore files matching .gitignore, if passed
         if gitignore_dict and _path_is_ignored(
-            normalized_path, root, gitignore_dict, report
+            root_relative_path, root, gitignore_dict, report
         ):
             continue
 
         # Then ignore with `--exclude` `--extend-exclude` and `--force-exclude` options.
-        normalized_path = "/" + normalized_path
+        root_relative_path = "/" + root_relative_path
         if child.is_dir():
-            normalized_path += "/"
+            root_relative_path += "/"
 
-        if path_is_excluded(normalized_path, exclude):
+        if path_is_excluded(root_relative_path, exclude):
             report.path_ignored(child, "matches the --exclude regular expression")
             continue
 
-        if path_is_excluded(normalized_path, extend_exclude):
+        if path_is_excluded(root_relative_path, extend_exclude):
             report.path_ignored(
                 child, "matches the --extend-exclude regular expression"
             )
             continue
 
-        if path_is_excluded(normalized_path, force_exclude):
+        if path_is_excluded(root_relative_path, force_exclude):
             report.path_ignored(child, "matches the --force-exclude regular expression")
             continue
 
+        normalized_path = normalize_path_maybe_ignore(child, root, report)
+        if normalized_path is None:
+            continue
+
         if child.is_dir():
             # If gitignore is None, gitignore usage is disabled, while a Falsey
             # gitignore is when the directory doesn't have a .gitignore file.
diff --git a/tests/test_black.py b/tests/test_black.py
index 79930fabf1f..4fb6aef9bca 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -492,9 +492,7 @@ def test_false_positive_symlink_output_issue_3384(self) -> None:
         project_root = Path(THIS_DIR / "data" / "nested_gitignore_tests")
         working_directory = project_root / "root"
         target_abspath = working_directory / "child"
-        target_contents = (
-            src.relative_to(working_directory) for src in target_abspath.iterdir()
-        )
+        target_contents = list(target_abspath.iterdir())
 
         def mock_n_calls(responses: List[bool]) -> Callable[[], bool]:
             def _mocked_calls() -> bool:
@@ -2375,38 +2373,48 @@ def test_extend_exclude(self) -> None:
         )
 
     @pytest.mark.incompatible_with_mypyc
-    def test_symlink_out_of_root_directory(self) -> None:
+    def test_symlinks(self) -> None:
         path = MagicMock()
         root = THIS_DIR.resolve()
-        child = MagicMock()
         include = re.compile(black.DEFAULT_INCLUDES)
         exclude = re.compile(black.DEFAULT_EXCLUDES)
         report = black.Report()
         gitignore = PathSpec.from_lines("gitwildmatch", [])
-        # `child` should behave like a symlink which resolved path is clearly
-        # outside of the `root` directory.
-        path.iterdir.return_value = [child]
-        child.resolve.return_value = Path("/a/b/c")
-        child.as_posix.return_value = "/a/b/c"
-        try:
-            list(
-                black.gen_python_files(
-                    path.iterdir(),
-                    root,
-                    include,
-                    exclude,
-                    None,
-                    None,
-                    report,
-                    {path: gitignore},
-                    verbose=False,
-                    quiet=False,
-                )
+
+        regular = MagicMock()
+        outside_root_symlink = MagicMock()
+        ignored_symlink = MagicMock()
+
+        path.iterdir.return_value = [regular, outside_root_symlink, ignored_symlink]
+
+        regular.absolute.return_value = root / "regular.py"
+        regular.resolve.return_value = root / "regular.py"
+        regular.is_dir.return_value = False
+
+        outside_root_symlink.absolute.return_value = root / "symlink.py"
+        outside_root_symlink.resolve.return_value = Path("/nowhere")
+
+        ignored_symlink.absolute.return_value = root / ".mypy_cache" / "symlink.py"
+
+        files = list(
+            black.gen_python_files(
+                path.iterdir(),
+                root,
+                include,
+                exclude,
+                None,
+                None,
+                report,
+                {path: gitignore},
+                verbose=False,
+                quiet=False,
             )
-        except ValueError as ve:
-            pytest.fail(f"`get_python_files_in_dir()` failed: {ve}")
+        )
+        assert files == [regular]
+
         path.iterdir.assert_called_once()
-        child.resolve.assert_called_once()
+        outside_root_symlink.resolve.assert_called_once()
+        ignored_symlink.resolve.assert_not_called()
 
     @patch("black.find_project_root", lambda *args: (THIS_DIR.resolve(), None))
     def test_get_sources_with_stdin(self) -> None:

From 8daa64a2e10907539094df51f4c51306bb426f07 Mon Sep 17 00:00:00 2001
From: KotlinIsland <65446343+KotlinIsland@users.noreply.github.com>
Date: Thu, 7 Sep 2023 17:11:50 +1000
Subject: [PATCH 0832/1034] blackd: fix mishandling of single character input
 (#3558)

---
 CHANGES.md             | 2 ++
 src/blackd/__init__.py | 3 ++-
 tests/test_blackd.py   | 6 ++++++
 3 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index 2168c1b90ce..af9fc490acf 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -45,6 +45,8 @@
 
 <!-- Changes to blackd -->
 
+- Fix an issue in `blackd` with single character input (#3558)
+
 ### Integrations
 
 <!-- For example, Docker, GitHub Actions, pre-commit, editors -->
diff --git a/src/blackd/__init__.py b/src/blackd/__init__.py
index 4f2d87d0fca..6b0f3d33295 100644
--- a/src/blackd/__init__.py
+++ b/src/blackd/__init__.py
@@ -152,7 +152,8 @@ async def handle(request: web.Request, executor: Executor) -> web.Response:
         )
 
         # Preserve CRLF line endings
-        if req_str[req_str.find("\n") - 1] == "\r":
+        nl = req_str.find("\n")
+        if nl > 0 and req_str[nl - 1] == "\r":
             formatted_str = formatted_str.replace("\n", "\r\n")
             # If, after swapping line endings, nothing changed, then say so
             if formatted_str == req_str:
diff --git a/tests/test_blackd.py b/tests/test_blackd.py
index 325bd7dd5aa..dd2126e6bc2 100644
--- a/tests/test_blackd.py
+++ b/tests/test_blackd.py
@@ -240,3 +240,9 @@ async def test_normalizes_line_endings(self) -> None:
             response = await self.client.post("/", data=data)
             self.assertEqual(await response.text(), expected)
             self.assertEqual(response.status, 200)
+
+    @unittest_run_loop
+    async def test_single_character(self) -> None:
+        response = await self.client.post("/", data="1")
+        self.assertEqual(await response.text(), "1\n")
+        self.assertEqual(response.status, 200)

From 74d3009ba480a871df57197144578f1ae4016210 Mon Sep 17 00:00:00 2001
From: Jonas Haag <jonas@lophus.org>
Date: Fri, 8 Sep 2023 03:35:07 +0200
Subject: [PATCH 0833/1034] Add Black PyCharm 2023.2 integration instructions
 (#3839)

---
 docs/integrations/editors.md | 26 ++++++++++++++++++--------
 1 file changed, 18 insertions(+), 8 deletions(-)

diff --git a/docs/integrations/editors.md b/docs/integrations/editors.md
index ff563068e79..cebe2b0721e 100644
--- a/docs/integrations/editors.md
+++ b/docs/integrations/editors.md
@@ -10,16 +10,26 @@ Options include the following:
 
 ## PyCharm/IntelliJ IDEA
 
-There are three different ways you can use _Black_ from PyCharm:
+There are several different ways you can use _Black_ from PyCharm:
 
-1. As local server using the BlackConnect plugin
-1. As external tool
-1. As file watcher
+1. Using the built-in _Black_ integration (PyCharm 2023.2 and later). This option is the
+   simplest to set up.
+1. As local server using the BlackConnect plugin. This option formats the fastest. It
+   spins up {doc}`Black's HTTP server </usage_and_configuration/black_as_a_server>`, to
+   avoid the startup cost on subsequent formats.
+1. As external tool.
+1. As file watcher.
 
-The first option is the simplest to set up and formats the fastest (by spinning up
-{doc}`Black's HTTP server </usage_and_configuration/black_as_a_server>`, avoiding the
-startup cost on subsequent formats), but if you would prefer to not install a
-third-party plugin or blackd's extra dependencies, the other two are also great options.
+### Built-in _Black_ integration
+
+1. Install `black`.
+
+   ```console
+   $ pip install black
+   ```
+
+1. Go to `Preferences or Settings -> Tools -> Black` and configure _Black_ to your
+   liking.
 
 ### As local server
 

From a20338cf100ff20a24e2058c6f6014e82efdf914 Mon Sep 17 00:00:00 2001
From: Charlie Marsh <crmarsh416@gmail.com>
Date: Fri, 8 Sep 2023 16:37:13 +0200
Subject: [PATCH 0834/1034] Avoid removing whitespace for walrus operators
 within subscripts (#3823)

Co-authored-by: hauntsaninja <hauntsaninja@gmail.com>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 CHANGES.md                           |  1 +
 src/black/lines.py                   |  4 +++-
 src/black/mode.py                    |  1 +
 src/black/nodes.py                   |  8 +++++++-
 tests/data/preview/pep_572.py        |  6 ++++++
 tests/data/preview_py_310/pep_572.py | 12 ++++++++++++
 tests/test_format.py                 |  7 +++++++
 7 files changed, 37 insertions(+), 2 deletions(-)
 create mode 100644 tests/data/preview/pep_572.py
 create mode 100644 tests/data/preview_py_310/pep_572.py

diff --git a/CHANGES.md b/CHANGES.md
index af9fc490acf..4aa3123fab6 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -80,6 +80,7 @@
   (#3740)
 - Fix error in AST validation when _Black_ removes trailing whitespace in a type comment
   (#3773)
+- Fix a bug whereby spaces were removed from walrus operators within subscript (#3823)
 
 ### Preview style
 
diff --git a/src/black/lines.py b/src/black/lines.py
index 0a307b45eff..f3044ce47b8 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -81,7 +81,9 @@ def append(
             # Note: at this point leaf.prefix should be empty except for
             # imports, for which we only preserve newlines.
             leaf.prefix += whitespace(
-                leaf, complex_subscript=self.is_complex_subscript(leaf)
+                leaf,
+                complex_subscript=self.is_complex_subscript(leaf),
+                mode=self.mode,
             )
         if self.inside_brackets or not preformatted or track_bracket:
             self.bracket_tracker.mark(leaf)
diff --git a/src/black/mode.py b/src/black/mode.py
index 282c1669da7..06d20b7a7d6 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -183,6 +183,7 @@ class Preview(Enum):
     wrap_long_dict_values_in_parens = auto()
     wrap_multiple_context_managers_in_parens = auto()
     dummy_implementations = auto()
+    walrus_subscript = auto()
 
 
 class Deprecated(UserWarning):
diff --git a/src/black/nodes.py b/src/black/nodes.py
index 45423b2596b..edd201a21e9 100644
--- a/src/black/nodes.py
+++ b/src/black/nodes.py
@@ -13,6 +13,7 @@
 from mypy_extensions import mypyc_attr
 
 from black.cache import CACHE_DIR
+from black.mode import Mode, Preview
 from black.strings import has_triple_quotes
 from blib2to3 import pygram
 from blib2to3.pgen2 import token
@@ -171,7 +172,7 @@ def visit_default(self, node: LN) -> Iterator[T]:
                 yield from self.visit(child)
 
 
-def whitespace(leaf: Leaf, *, complex_subscript: bool) -> str:  # noqa: C901
+def whitespace(leaf: Leaf, *, complex_subscript: bool, mode: Mode) -> str:  # noqa: C901
     """Return whitespace prefix if needed for the given `leaf`.
 
     `complex_subscript` signals whether the given leaf is part of a subscription
@@ -345,6 +346,11 @@ def whitespace(leaf: Leaf, *, complex_subscript: bool) -> str:  # noqa: C901
 
             return NO
 
+        elif Preview.walrus_subscript in mode and (
+            t == token.COLONEQUAL or prev.type == token.COLONEQUAL
+        ):
+            return SPACE
+
         elif not complex_subscript:
             return NO
 
diff --git a/tests/data/preview/pep_572.py b/tests/data/preview/pep_572.py
new file mode 100644
index 00000000000..a50e130ad9c
--- /dev/null
+++ b/tests/data/preview/pep_572.py
@@ -0,0 +1,6 @@
+x[(a:=0):]
+x[:(a:=0)]
+
+# output
+x[(a := 0):]
+x[:(a := 0)]
diff --git a/tests/data/preview_py_310/pep_572.py b/tests/data/preview_py_310/pep_572.py
new file mode 100644
index 00000000000..78d4e9e4506
--- /dev/null
+++ b/tests/data/preview_py_310/pep_572.py
@@ -0,0 +1,12 @@
+x[a:=0]
+x[a := 0]
+x[a := 0, b := 1]
+x[5, b := 0]
+x[a:=0,b:=1]
+
+# output
+x[a := 0]
+x[a := 0]
+x[a := 0, b := 1]
+x[5, b := 0]
+x[a := 0, b := 1]
diff --git a/tests/test_format.py b/tests/test_format.py
index fb4d8eb4346..0650a2d6e53 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -56,6 +56,13 @@ def test_preview_context_managers_targeting_py39() -> None:
     assert_format(source, expected, mode, minimum_version=(3, 9))
 
 
+@pytest.mark.parametrize("filename", all_data_cases("preview_py_310"))
+def test_preview_python_310(filename: str) -> None:
+    source, expected = read_data("preview_py_310", filename)
+    mode = black.Mode(target_versions={black.TargetVersion.PY310}, preview=True)
+    assert_format(source, expected, mode, minimum_version=(3, 10))
+
+
 @pytest.mark.parametrize(
     "filename", all_data_cases("preview_context_managers/auto_detect")
 )

From b40b01ffe3dbf1fa989acd6050ef5e61c085b5da Mon Sep 17 00:00:00 2001
From: konsti <konstin@mailbox.org>
Date: Sat, 9 Sep 2023 03:51:27 +0200
Subject: [PATCH 0835/1034] Blank line between nested and function def in stub
 files. (#3862)

The idea behind this change is that we stop looking into previous body to determine if there should be a blank before a function or class definition.

Input:

```python
import sys

if sys.version_info > (3, 7):
    class Nested1:
        assignment = 1
        def function_definition(self): ...
    def f1(self) -> str: ...
    class Nested2:
        def function_definition(self): ...
        assignment = 1
    def f2(self) -> str: ...

if sys.version_info > (3, 7):
    def nested1():
        assignment = 1
        def function_definition(self): ...
    def f1(self) -> str: ...
    def nested2():
        def function_definition(self): ...
        assignment = 1
    def f2(self) -> str: ...
```

Stable style
```python
import sys

if sys.version_info > (3, 7):
    class Nested1:
        assignment = 1
        def function_definition(self): ...

    def f1(self) -> str: ...

    class Nested2:
        def function_definition(self): ...
        assignment = 1
    def f2(self) -> str: ...

if sys.version_info > (3, 7):
    def nested1():
        assignment = 1
        def function_definition(self): ...

    def f1(self) -> str: ...
    def nested2():
        def function_definition(self): ...
        assignment = 1
    def f2(self) -> str: ...
```

In the stable formatting, we have a blank line sometimes, not depending on the previous statement on the same level, but on the last (potentially nested) statement in the previous body.

#2783/#3564 fixes this for classes in preview style:

```python
import sys

if sys.version_info > (3, 7):
    class Nested1:
        assignment = 1
        def function_definition(self): ...

    def f1(self) -> str: ...

    class Nested2:
        def function_definition(self): ...
        assignment = 1

    def f2(self) -> str: ...

if sys.version_info > (3, 7):
    def nested1():
        assignment = 1
        def function_definition(self): ...

    def f1(self) -> str: ...
    def nested2():
        def function_definition(self): ...
        assignment = 1
    def f2(self) -> str: ...
```

This PR additionally fixes this for function definitions:

```python
if sys.version_info > (3, 7):
    if sys.platform == "win32":
        assignment = 1
        def function_definition(self): ...

    def f1(self) -> str: ...
    if sys.platform != "win32":
        def function_definition(self): ...
        assignment = 1

    def f2(self) -> str: ...

if sys.version_info > (3, 8):
    if sys.platform == "win32":
        assignment = 1
        def function_definition(self): ...

    class F1: ...
    if sys.platform != "win32":
        def function_definition(self): ...
        assignment = 1

    class F2: ...
```

You can see the effect of this change on typeshed in https://github.com/konstin/typeshed/pull/1/files. As baseline, the preview mode changes without this PR are at https://github.com/konstin/typeshed/pull/2.

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 CHANGES.md                                    |  2 +
 src/black/lines.py                            | 11 +++++
 src/black/mode.py                             |  1 +
 .../data/miscellaneous/nested_class_stub.pyi  | 16 -------
 tests/data/miscellaneous/nested_stub.pyi      | 43 +++++++++++++++++++
 tests/test_format.py                          |  4 +-
 6 files changed, 59 insertions(+), 18 deletions(-)
 delete mode 100644 tests/data/miscellaneous/nested_class_stub.pyi
 create mode 100644 tests/data/miscellaneous/nested_stub.pyi

diff --git a/CHANGES.md b/CHANGES.md
index 4aa3123fab6..b0fa5f8745e 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -171,6 +171,8 @@ expected to become part of Black's stable style in January 2024.
 - For stubs, enforce one blank line after a nested class with a body other than just
   `...` (#3564)
 - Improve handling of multiline strings by changing line split behavior (#1879)
+- In stub files, add a blank line between a statement with a body (e.g an
+  `if sys.version_info > (3, x):`) and a function definition on the same level. (#3862)
 
 ### Parser
 
diff --git a/src/black/lines.py b/src/black/lines.py
index f3044ce47b8..71b657a0654 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -711,6 +711,17 @@ def _maybe_empty_lines_for_class_or_def(  # noqa: C901
                     newlines = 0
                 else:
                     newlines = 1
+            # Remove case `self.previous_line.depth > current_line.depth` below when
+            # this becomes stable.
+            #
+            # Don't inspect the previous line if it's part of the body of the previous
+            # statement in the same level, we always want a blank line if there's
+            # something with a body preceding.
+            elif (
+                Preview.blank_line_between_nested_and_def_stub_file in current_line.mode
+                and self.previous_line.depth > current_line.depth
+            ):
+                newlines = 1
             elif (
                 current_line.is_def or current_line.is_decorator
             ) and not self.previous_line.is_def:
diff --git a/src/black/mode.py b/src/black/mode.py
index 06d20b7a7d6..8a855ac495a 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -170,6 +170,7 @@ class Preview(Enum):
 
     add_trailing_comma_consistently = auto()
     blank_line_after_nested_stub_class = auto()
+    blank_line_between_nested_and_def_stub_file = auto()
     hex_codes_in_unicode_sequences = auto()
     improved_async_statements_handling = auto()
     multiline_string_handling = auto()
diff --git a/tests/data/miscellaneous/nested_class_stub.pyi b/tests/data/miscellaneous/nested_class_stub.pyi
deleted file mode 100644
index daf281b517b..00000000000
--- a/tests/data/miscellaneous/nested_class_stub.pyi
+++ /dev/null
@@ -1,16 +0,0 @@
-class Outer:
-    class InnerStub: ...
-    outer_attr_after_inner_stub: int
-    class Inner:
-        inner_attr: int
-    outer_attr: int
-
-# output
-class Outer:
-    class InnerStub: ...
-    outer_attr_after_inner_stub: int
-
-    class Inner:
-        inner_attr: int
-
-    outer_attr: int
diff --git a/tests/data/miscellaneous/nested_stub.pyi b/tests/data/miscellaneous/nested_stub.pyi
new file mode 100644
index 00000000000..15e69d854db
--- /dev/null
+++ b/tests/data/miscellaneous/nested_stub.pyi
@@ -0,0 +1,43 @@
+import sys
+
+class Outer:
+    class InnerStub: ...
+    outer_attr_after_inner_stub: int
+    class Inner:
+        inner_attr: int
+    outer_attr: int
+
+if sys.version_info > (3, 7):
+    if sys.platform == "win32":
+        assignment = 1
+        def function_definition(self): ...
+    def f1(self) -> str: ...
+    if sys.platform != "win32":
+        def function_definition(self): ...
+        assignment = 1
+    def f2(self) -> str: ...
+
+# output
+
+import sys
+
+class Outer:
+    class InnerStub: ...
+    outer_attr_after_inner_stub: int
+
+    class Inner:
+        inner_attr: int
+
+    outer_attr: int
+
+if sys.version_info > (3, 7):
+    if sys.platform == "win32":
+        assignment = 1
+        def function_definition(self): ...
+
+    def f1(self) -> str: ...
+    if sys.platform != "win32":
+        def function_definition(self): ...
+        assignment = 1
+
+    def f2(self) -> str: ...
\ No newline at end of file
diff --git a/tests/test_format.py b/tests/test_format.py
index 0650a2d6e53..f3db423b637 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -201,9 +201,9 @@ def test_stub() -> None:
     assert_format(source, expected, mode)
 
 
-def test_nested_class_stub() -> None:
+def test_nested_stub() -> None:
     mode = replace(DEFAULT_MODE, is_pyi=True, preview=True)
-    source, expected = read_data("miscellaneous", "nested_class_stub.pyi")
+    source, expected = read_data("miscellaneous", "nested_stub.pyi")
     assert_format(source, expected, mode)
 
 

From b70b2c619671f0c6adc722742181bd2fa6e2a2f4 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Fri, 8 Sep 2023 20:24:49 -0700
Subject: [PATCH 0836/1034] Prepare release 23.9.0 (#3863)

---
 CHANGES.md                                  | 48 +++++++++++++--------
 docs/contributing/release_process.md        |  2 +
 docs/integrations/source_version_control.md |  4 +-
 docs/usage_and_configuration/the_basics.md  |  6 +--
 4 files changed, 37 insertions(+), 23 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index b0fa5f8745e..3829526871e 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -14,14 +14,10 @@
 
 <!-- Changes that affect Black's preview style -->
 
-- More concise formatting for dummy implementations (#3796)
-
 ### Configuration
 
 <!-- Changes to how Black can be configured -->
 
-- Black now applies exclusion and ignore logic before resolving symlinks (#3846)
-
 ### Packaging
 
 <!-- Changes to how Black is packaged, such as dependency requirements -->
@@ -34,9 +30,6 @@
 
 <!-- Changes that improve Black's performance. -->
 
-- Avoid importing `IPython` if notebook cells do not contain magics (#3782)
-- Improve caching by comparing file hashes as fallback for mtime and size. (#3821)
-
 ### Output
 
 <!-- Changes to Black's terminal output and error messages -->
@@ -45,23 +38,45 @@
 
 <!-- Changes to blackd -->
 
-- Fix an issue in `blackd` with single character input (#3558)
-
 ### Integrations
 
 <!-- For example, Docker, GitHub Actions, pre-commit, editors -->
 
+### Documentation
+
+<!-- Major changes to documentation and policies. Small docs changes
+     don't need a changelog entry. -->
+
+## 23.9.0
+
+### Preview style
+
+- More concise formatting for dummy implementations (#3796)
+- In stub files, add a blank line between a statement with a body (e.g an
+  `if sys.version_info > (3, x):`) and a function definition on the same level (#3862)
+- Fix a bug whereby spaces were removed from walrus operators within subscript(#3823)
+
+### Configuration
+
+- Black now applies exclusion and ignore logic before resolving symlinks (#3846)
+
+### Performance
+
+- Avoid importing `IPython` if notebook cells do not contain magics (#3782)
+- Improve caching by comparing file hashes as fallback for mtime and size (#3821)
+
+### _Blackd_
+
+- Fix an issue in `blackd` with single character input (#3558)
+
+### Integrations
+
 - Black now has an
   [official pre-commit mirror](https://github.com/psf/black-pre-commit-mirror). Swapping
   `https://github.com/psf/black` to `https://github.com/psf/black-pre-commit-mirror` in
   your `.pre-commit-config.yaml` will make Black about 2x faster (#3828)
 - The `.black.env` folder specified by `ENV_PATH` will now be removed on the completion
-  of the GitHub Action. (#3759)
-
-### Documentation
-
-<!-- Major changes to documentation and policies. Small docs changes
-     don't need a changelog entry. -->
+  of the GitHub Action (#3759)
 
 ## 23.7.0
 
@@ -80,7 +95,6 @@
   (#3740)
 - Fix error in AST validation when _Black_ removes trailing whitespace in a type comment
   (#3773)
-- Fix a bug whereby spaces were removed from walrus operators within subscript (#3823)
 
 ### Preview style
 
@@ -171,8 +185,6 @@ expected to become part of Black's stable style in January 2024.
 - For stubs, enforce one blank line after a nested class with a body other than just
   `...` (#3564)
 - Improve handling of multiline strings by changing line split behavior (#1879)
-- In stub files, add a blank line between a statement with a body (e.g an
-  `if sys.version_info > (3, x):`) and a function definition on the same level. (#3862)
 
 ### Parser
 
diff --git a/docs/contributing/release_process.md b/docs/contributing/release_process.md
index be9b08a6c82..02865d6f4bd 100644
--- a/docs/contributing/release_process.md
+++ b/docs/contributing/release_process.md
@@ -43,6 +43,8 @@ To cut a release:
    1. Remove any empty sections for the current release
    1. (_optional_) Read through and copy-edit the changelog (eg. by moving entries,
       fixing typos, or rephrasing entries)
+   1. Double-check that no changelog entries since the last release were put in the
+      wrong section (e.g., run `git diff <last release> CHANGES.md`)
    1. Add a new empty template for the next release above
       ([template below](#changelog-template))
    1. Update references to the latest version in
diff --git a/docs/integrations/source_version_control.md b/docs/integrations/source_version_control.md
index 24e732848f1..28414973ff5 100644
--- a/docs/integrations/source_version_control.md
+++ b/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.7.0
+    rev: 23.9.0
     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.7.0
+    rev: 23.9.0
     hooks:
       - id: black-jupyter
         # It is recommended to specify the latest version of Python
diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index 5efb50a9a12..6ae9441fb69 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -193,8 +193,8 @@ configuration file for consistent results across environments.
 
 ```console
 $ black --version
-black, 23.7.0 (compiled: yes)
-$ black --required-version 23.7.0 -c "format = 'this'"
+black, 23.9.0 (compiled: yes)
+$ black --required-version 23.9.0 -c "format = 'this'"
 format = "this"
 $ black --required-version 31.5b2 -c "still = 'beta?!'"
 Oh no! 💥 💔 💥 The required version does not match the running version!
@@ -285,7 +285,7 @@ You can check the version of _Black_ you have installed using the `--version` fl
 
 ```console
 $ black --version
-black, 23.7.0
+black, 23.9.0
 ```
 
 #### `--config`

From 716fa08090b6a51e4c72dd0a14b6c45f7da4a9d0 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Fri, 8 Sep 2023 22:16:15 -0700
Subject: [PATCH 0837/1034] Upgrade mypy (#3864)

---
 CHANGES.md     | 2 ++
 pyproject.toml | 2 +-
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index 3829526871e..1334efefe7b 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -22,6 +22,8 @@
 
 <!-- Changes to how Black is packaged, such as dependency requirements -->
 
+- Upgrade to mypy 1.5.1 (#3864)
+
 ### Parser
 
 <!-- Changes to the parser or to version autodetection -->
diff --git a/pyproject.toml b/pyproject.toml
index ea5c9f84684..8585f4efbed 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -117,7 +117,7 @@ sources = ["src"]
 enable-by-default = false
 dependencies = [
   "hatch-mypyc>=0.16.0",
-  "mypy==1.3",
+  "mypy==1.5.1",
   "click==8.1.3",  # avoid https://github.com/pallets/click/issues/2558
 ]
 require-runtime-dependencies = true

From 4e93f2aa01606154dc6af6e494b9f2b7e4c8c7fa Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Fri, 8 Sep 2023 22:16:25 -0700
Subject: [PATCH 0838/1034] Add classifier for 3.12 (#3866)

---
 pyproject.toml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/pyproject.toml b/pyproject.toml
index 8585f4efbed..ebfbede8559 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -57,6 +57,7 @@ classifiers = [
   "Programming Language :: Python :: 3.9",
   "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
   "Topic :: Software Development :: Libraries :: Python Modules",
   "Topic :: Software Development :: Quality Assurance",
 ]

From add161b367a0d5a3cc395ec8e045f7b965edaef8 Mon Sep 17 00:00:00 2001
From: Richard Si <sichard26@gmail.com>
Date: Sat, 9 Sep 2023 12:08:28 -0400
Subject: [PATCH 0839/1034] Bump RTD Python version from 3.8 to 3.11 (#3868)

Recent ReadTheDocs builds have been failing as our documentation dependencies (notably Sphinx) require Python 3.9+.
---
 .readthedocs.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index fff2d6ed341..fa612668850 100644
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -6,7 +6,7 @@ formats:
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.8"
+    python: "3.11"
 
 python:
   install:

From 4eebfd1a7a4aa2652cfc674cf301d1f2f48098aa Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Sun, 10 Sep 2023 07:53:27 -0700
Subject: [PATCH 0840/1034] Add mypyc test marks to new tests that patch
 (#3871)

This is enough for me to get a clean test run on Python 3.9 with mypyc.
I have not been able to repro the pickle failures on either Linux or
macOS.
---
 tests/test_black.py | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/tests/test_black.py b/tests/test_black.py
index 4fb6aef9bca..badb8fff5fb 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -1985,6 +1985,7 @@ def test_cache_multiple_files(self) -> None:
             assert not cache.is_changed(one)
             assert not cache.is_changed(two)
 
+    @pytest.mark.incompatible_with_mypyc
     @pytest.mark.parametrize("color", [False, True], ids=["no-color", "with-color"])
     def test_no_cache_when_writeback_diff(self, color: bool) -> None:
         mode = DEFAULT_MODE
@@ -2046,6 +2047,7 @@ def test_write_cache_read_cache(self) -> None:
             read_cache = black.Cache.read(mode)
             assert not read_cache.is_changed(src)
 
+    @pytest.mark.incompatible_with_mypyc
     def test_filter_cached(self) -> None:
         with TemporaryDirectory() as workspace:
             path = Path(workspace)

From c83ad6c077e7bb281cfd3fbdd89bbeb4c980e563 Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <hugovk@users.noreply.github.com>
Date: Sun, 10 Sep 2023 15:36:25 -0600
Subject: [PATCH 0841/1034] Upgrade to Furo 2023.9.10 to fix docs build (#3873)

---
 docs/requirements.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index dad39f67ed3..b8bab4393ff 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -6,4 +6,4 @@ Sphinx==7.2.3
 docutils==0.19
 sphinxcontrib-programoutput==0.17
 sphinx_copybutton==0.5.2
-furo==2023.8.19
+furo==2023.9.10

From 0b62b9c9a44a995e44d64ecf7cc08d8d7037642d Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Sun, 10 Sep 2023 15:45:13 -0700
Subject: [PATCH 0842/1034] Ignore aiohttp DeprecationWarning for 3.12 (#3876)

Co-authored-by: Marc Mueller <30130371+cdce8p@users.noreply.github.com>
---
 pyproject.toml | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/pyproject.toml b/pyproject.toml
index ebfbede8559..3d81e8f5ba9 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -209,7 +209,10 @@ filterwarnings = [
     # https://github.com/aio-libs/aiohttp/issues/6905
     '''ignore:'cgi' is deprecated and slated for removal in Python 3.13:DeprecationWarning''',
     # Work around https://github.com/pytest-dev/pytest/issues/10977 for Python 3.12
-    '''ignore:(Attribute s|Attribute n|ast.Str|ast.Bytes|ast.NameConstant|ast.Num) is deprecated and will be removed in Python 3.14:DeprecationWarning'''
+    '''ignore:(Attribute s|Attribute n|ast.Str|ast.Bytes|ast.NameConstant|ast.Num) is deprecated and will be removed in Python 3.14:DeprecationWarning''',
+    # Will be fixed with aiohttp 3.9.0
+    # https://github.com/aio-libs/aiohttp/pull/7302
+    "ignore:datetime.*utcfromtimestamp\\(\\) is deprecated and scheduled for removal:DeprecationWarning",
 ]
 [tool.coverage.report]
 omit = [

From f7917453c99f8183ffd0397affcccb2c37594771 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Sun, 10 Sep 2023 16:12:20 -0700
Subject: [PATCH 0843/1034] Re-export black.Mode (#3875)

---
 src/black/__init__.py | 11 +++--------
 tests/test_black.py   | 35 +++++++++++++++++++++++++++++++++++
 2 files changed, 38 insertions(+), 8 deletions(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index 6fc91d2e6d3..188a4f79f0e 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -63,14 +63,9 @@
 )
 from black.linegen import LN, LineGenerator, transform_line
 from black.lines import EmptyLineTracker, LinesBlock
-from black.mode import (
-    FUTURE_FLAG_TO_FEATURE,
-    VERSION_TO_FEATURES,
-    Feature,
-    Mode,
-    TargetVersion,
-    supports_feature,
-)
+from black.mode import FUTURE_FLAG_TO_FEATURE, VERSION_TO_FEATURES, Feature
+from black.mode import Mode as Mode  # re-exported
+from black.mode import TargetVersion, supports_feature
 from black.nodes import (
     STARS,
     is_number_token,
diff --git a/tests/test_black.py b/tests/test_black.py
index badb8fff5fb..d22b6859607 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -2482,6 +2482,41 @@ def test_get_sources_with_stdin_filename_and_force_exclude(self) -> None:
         )
 
 
+class TestDeFactoAPI:
+    """Test that certain symbols that are commonly used externally keep working.
+
+    We don't (yet) formally expose an API (see issue #779), but we should endeavor to
+    keep certain functions that external users commonly rely on working.
+
+    """
+
+    def test_format_str(self) -> None:
+        # format_str and Mode should keep working
+        assert (
+            black.format_str("print('hello')", mode=black.Mode()) == 'print("hello")\n'
+        )
+
+        # you can pass line length
+        assert (
+            black.format_str("print('hello')", mode=black.Mode(line_length=42))
+            == 'print("hello")\n'
+        )
+
+        # invalid input raises InvalidInput
+        with pytest.raises(black.InvalidInput):
+            black.format_str("syntax error", mode=black.Mode())
+
+    def test_format_file_contents(self) -> None:
+        # You probably should be using format_str() instead, but let's keep
+        # this one around since people do use it
+        assert (
+            black.format_file_contents("x=1", fast=True, mode=black.Mode()) == "x = 1\n"
+        )
+
+        with pytest.raises(black.NothingChanged):
+            black.format_file_contents("x = 1\n", fast=True, mode=black.Mode())
+
+
 try:
     with open(black.__file__, "r", encoding="utf-8") as _bf:
         black_source_lines = _bf.readlines()

From 751583a1dfc691423d96d7711a4c8d9cfe3ee9c8 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Sun, 10 Sep 2023 16:16:24 -0700
Subject: [PATCH 0844/1034] Pickle raw tuples in FileData cache (#3877)

Co-authored-by: Marc Mueller <30130371+cdce8p@users.noreply.github.com>
---
 CHANGES.md         |  3 +++
 src/black/cache.py | 10 ++++++++--
 2 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 1334efefe7b..9fa14f3ebc4 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -32,6 +32,9 @@
 
 <!-- Changes that improve Black's performance. -->
 
+- Store raw tuples instead of NamedTuples in Black's cache, improving performance and
+  decreasing the size of the cache (#3877)
+
 ### Output
 
 <!-- Changes to Black's terminal output and error messages -->
diff --git a/src/black/cache.py b/src/black/cache.py
index ff15da2a94e..77f66cc34a9 100644
--- a/src/black/cache.py
+++ b/src/black/cache.py
@@ -67,7 +67,8 @@ def read(cls, mode: Mode) -> Self:
 
         with cache_file.open("rb") as fobj:
             try:
-                file_data: Dict[str, FileData] = pickle.load(fobj)
+                data: Dict[str, Tuple[float, int, str]] = pickle.load(fobj)
+                file_data = {k: FileData(*v) for k, v in data.items()}
             except (pickle.UnpicklingError, ValueError, IndexError):
                 return cls(mode, cache_file)
 
@@ -129,7 +130,12 @@ def write(self, sources: Iterable[Path]) -> None:
             with tempfile.NamedTemporaryFile(
                 dir=str(self.cache_file.parent), delete=False
             ) as f:
-                pickle.dump(self.file_data, f, protocol=4)
+                # We store raw tuples in the cache because pickling NamedTuples
+                # doesn't work with mypyc on Python 3.8, and because it's faster.
+                data: Dict[str, Tuple[float, int, str]] = {
+                    k: (*v,) for k, v in self.file_data.items()
+                }
+                pickle.dump(data, f, protocol=4)
             os.replace(f.name, self.cache_file)
         except OSError:
             pass

From 62dca32dc55a850f39d78ba8b9c21cc4261a2ddf Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Sun, 10 Sep 2023 16:47:08 -0700
Subject: [PATCH 0845/1034] mypyc builds on PRs, skip mypyc wheels for 3.12
 (#3870)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 .github/workflows/pypi_upload.yml | 12 ++++++++----
 pyproject.toml                    |  2 +-
 2 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/pypi_upload.yml b/.github/workflows/pypi_upload.yml
index 9be231dd305..ab2c6402c23 100644
--- a/.github/workflows/pypi_upload.yml
+++ b/.github/workflows/pypi_upload.yml
@@ -1,8 +1,9 @@
-name: Publish to PyPI
+name: Build wheels and publish to PyPI
 
 on:
   release:
     types: [published]
+  pull_request:
 
 permissions:
   contents: read
@@ -28,7 +29,8 @@ jobs:
       - name: Build wheel and source distributions
         run: python -m build
 
-      - name: Upload to PyPI via Twine
+      - if: github.event_name == 'release'
+        name: Upload to PyPI via Twine
         env:
           TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
         run: twine upload --verbose -u '__token__' dist/*
@@ -68,7 +70,8 @@ jobs:
           name: ${{ matrix.name }}-mypyc-wheels
           path: ./wheelhouse/*.whl
 
-      - name: Upload wheels to PyPI via Twine
+      - if: github.event_name == 'release'
+        name: Upload wheels to PyPI via Twine
         env:
           TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
         run: pipx run twine upload --verbose -u '__token__' wheelhouse/*.whl
@@ -87,7 +90,8 @@ jobs:
           ref: stable
           fetch-depth: 0
 
-      - name: Update stable branch to release tag & push
+      - if: github.event_name == 'release'
+        name: Update stable branch to release tag & push
         run: |
           git reset --hard ${{ github.event.release.tag_name }}
           git push
diff --git a/pyproject.toml b/pyproject.toml
index 3d81e8f5ba9..159907ac8ec 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -146,7 +146,7 @@ build-verbosity = 1
 # - Architecture (64-bit only): amd64 / x86_64, universal2, and arm64
 # - OS: Linux (no musl), Windows, and macOS
 build = "cp3*-*"
-skip = ["*-manylinux_i686", "*-musllinux_*", "*-win32", "pp-*"]
+skip = ["*-manylinux_i686", "*-musllinux_*", "*-win32", "pp-*", "cp312-*"]
 # This is the bare minimum needed to run the test suite. Pulling in the full
 # test_requirements.txt would download a bunch of other packages not necessary
 # here and would slow down the testing step a fair bit.

From e87737140f32d3cd7c44ede75f02dcd58e55820e Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Sun, 10 Sep 2023 17:35:41 -0700
Subject: [PATCH 0846/1034] Prepare release 23.9.1 (#3878)

---
 CHANGES.md                                  | 23 ++++++++++++++++-----
 docs/integrations/source_version_control.md |  4 ++--
 docs/usage_and_configuration/the_basics.md  |  6 +++---
 3 files changed, 23 insertions(+), 10 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 9fa14f3ebc4..a68106ad23f 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -22,8 +22,6 @@
 
 <!-- Changes to how Black is packaged, such as dependency requirements -->
 
-- Upgrade to mypy 1.5.1 (#3864)
-
 ### Parser
 
 <!-- Changes to the parser or to version autodetection -->
@@ -32,9 +30,6 @@
 
 <!-- Changes that improve Black's performance. -->
 
-- Store raw tuples instead of NamedTuples in Black's cache, improving performance and
-  decreasing the size of the cache (#3877)
-
 ### Output
 
 <!-- Changes to Black's terminal output and error messages -->
@@ -52,6 +47,24 @@
 <!-- Major changes to documentation and policies. Small docs changes
      don't need a changelog entry. -->
 
+## 23.9.1
+
+Due to various issues, the previous release (23.9.0) did not include compiled mypyc
+wheels, which make Black significantly faster. These issues have now been fixed, and
+this release should come with compiled wheels once again.
+
+There will be no wheels for Python 3.12 due to a bug in mypyc. We will provide 3.12
+wheels in a future release as soon as the mypyc bug is fixed.
+
+### Packaging
+
+- Upgrade to mypy 1.5.1 (#3864)
+
+### Performance
+
+- Store raw tuples instead of NamedTuples in Black's cache, improving performance and
+  decreasing the size of the cache (#3877)
+
 ## 23.9.0
 
 ### Preview style
diff --git a/docs/integrations/source_version_control.md b/docs/integrations/source_version_control.md
index 28414973ff5..2afcc02f3cd 100644
--- a/docs/integrations/source_version_control.md
+++ b/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.9.0
+    rev: 23.9.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.9.0
+    rev: 23.9.1
     hooks:
       - id: black-jupyter
         # It is recommended to specify the latest version of Python
diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index 6ae9441fb69..57fafd87654 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -193,8 +193,8 @@ configuration file for consistent results across environments.
 
 ```console
 $ black --version
-black, 23.9.0 (compiled: yes)
-$ black --required-version 23.9.0 -c "format = 'this'"
+black, 23.9.1 (compiled: yes)
+$ black --required-version 23.9.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!
@@ -285,7 +285,7 @@ You can check the version of _Black_ you have installed using the `--version` fl
 
 ```console
 $ black --version
-black, 23.9.0
+black, 23.9.1
 ```
 
 #### `--config`

From 213cb655188fd56c548be3f0d9191c30595407ca Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 11 Sep 2023 09:34:36 -0700
Subject: [PATCH 0847/1034] Bump actions/checkout from 3 to 4 (#3883)

Bumps [actions/checkout](https://github.com/actions/checkout) from 3 to 4.
- [Release notes](https://github.com/actions/checkout/releases)
- [Changelog](https://github.com/actions/checkout/blob/main/CHANGELOG.md)
- [Commits](https://github.com/actions/checkout/compare/v3...v4)

---
updated-dependencies:
- dependency-name: actions/checkout
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/changelog.yml           | 2 +-
 .github/workflows/diff_shades.yml         | 4 ++--
 .github/workflows/diff_shades_comment.yml | 2 +-
 .github/workflows/doc.yml                 | 2 +-
 .github/workflows/docker.yml              | 2 +-
 .github/workflows/fuzz.yml                | 2 +-
 .github/workflows/lint.yml                | 2 +-
 .github/workflows/pypi_upload.yml         | 6 +++---
 .github/workflows/test.yml                | 6 +++---
 .github/workflows/upload_binary.yml       | 2 +-
 10 files changed, 15 insertions(+), 15 deletions(-)

diff --git a/.github/workflows/changelog.yml b/.github/workflows/changelog.yml
index b3e1f0b9024..a1804597d7d 100644
--- a/.github/workflows/changelog.yml
+++ b/.github/workflows/changelog.yml
@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Grep CHANGES.md for PR number
         if: contains(github.event.pull_request.labels.*.name, 'skip news') != true
diff --git a/.github/workflows/diff_shades.yml b/.github/workflows/diff_shades.yml
index d685ef9456d..637bd527eaa 100644
--- a/.github/workflows/diff_shades.yml
+++ b/.github/workflows/diff_shades.yml
@@ -19,7 +19,7 @@ jobs:
       matrix: ${{ steps.set-config.outputs.matrix }}
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: actions/setup-python@v4
         with:
           python-version: "*"
@@ -52,7 +52,7 @@ jobs:
 
     steps:
       - name: Checkout this repository (full clone)
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           # The baseline revision could be rather old so a full clone is ideal.
           fetch-depth: 0
diff --git a/.github/workflows/diff_shades_comment.yml b/.github/workflows/diff_shades_comment.yml
index 22c293f91d2..b86bd93410e 100644
--- a/.github/workflows/diff_shades_comment.yml
+++ b/.github/workflows/diff_shades_comment.yml
@@ -12,7 +12,7 @@ jobs:
   comment:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: actions/setup-python@v4
         with:
           python-version: "*"
diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml
index fc94dea62d9..fa3d87c70f5 100644
--- a/.github/workflows/doc.yml
+++ b/.github/workflows/doc.yml
@@ -21,7 +21,7 @@ jobs:
 
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Set up latest Python
         uses: actions/setup-python@v4
diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
index 8baace940ba..566fc880785 100644
--- a/.github/workflows/docker.yml
+++ b/.github/workflows/docker.yml
@@ -16,7 +16,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Set up QEMU
         uses: docker/setup-qemu-action@v2
diff --git a/.github/workflows/fuzz.yml b/.github/workflows/fuzz.yml
index 4439148a1c7..1b5a50c0e0b 100644
--- a/.github/workflows/fuzz.yml
+++ b/.github/workflows/fuzz.yml
@@ -25,7 +25,7 @@ jobs:
         python-version: ["3.8", "3.9", "3.10", "3.11"]
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v4
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index 064d4745a53..3eaf5785f5a 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Assert PR target is main
         if: github.event_name == 'pull_request' && github.repository == 'psf/black'
diff --git a/.github/workflows/pypi_upload.yml b/.github/workflows/pypi_upload.yml
index ab2c6402c23..bf4d8349c95 100644
--- a/.github/workflows/pypi_upload.yml
+++ b/.github/workflows/pypi_upload.yml
@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Set up latest Python
         uses: actions/setup-python@v4
@@ -57,7 +57,7 @@ jobs:
             macos_arch: "universal2"
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Build wheels via cibuildwheel
         uses: pypa/cibuildwheel@v2.15.0
@@ -85,7 +85,7 @@ jobs:
 
     steps:
       - name: Checkout stable branch
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           ref: stable
           fetch-depth: 0
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 7daa31ee903..1f33f2b814f 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -35,7 +35,7 @@ jobs:
         os: [ubuntu-latest, macOS-latest, windows-latest]
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v4
@@ -75,7 +75,7 @@ jobs:
 
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Send finished signal to Coveralls
         uses: AndreMiras/coveralls-python-action@8799c9f4443ac4201d2e2f2c725d577174683b99
         with:
@@ -93,7 +93,7 @@ jobs:
         os: [ubuntu-latest, macOS-latest]
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Set up latest Python
         uses: actions/setup-python@v4
diff --git a/.github/workflows/upload_binary.yml b/.github/workflows/upload_binary.yml
index 22535a64c67..bb19d48158c 100644
--- a/.github/workflows/upload_binary.yml
+++ b/.github/workflows/upload_binary.yml
@@ -29,7 +29,7 @@ jobs:
             executable_mime: "application/x-mach-binary"
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Set up latest Python
         uses: actions/setup-python@v4

From e73662ca7cfd6d4760e11a6ab489a1ec585d1cd4 Mon Sep 17 00:00:00 2001
From: Simon Alinder <92031780+AlinderS@users.noreply.github.com>
Date: Mon, 11 Sep 2023 18:47:47 +0200
Subject: [PATCH 0848/1034] Fix broken url in editors.md (#3885)

* Fix broken url in editors.md

Update a link pointing to the Arch Linux repos.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 docs/integrations/editors.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/integrations/editors.md b/docs/integrations/editors.md
index cebe2b0721e..ab8c6a743e5 100644
--- a/docs/integrations/editors.md
+++ b/docs/integrations/editors.md
@@ -288,8 +288,8 @@ $ git checkout origin/stable -b stable
 ##### Arch Linux
 
 On Arch Linux, the plugin is shipped with the
-[`python-black`](https://archlinux.org/packages/community/any/python-black/) package, so
-you can start using it in Vim after install with no additional setup.
+[`python-black`](https://archlinux.org/packages/extra/any/python-black/) package, so you
+can start using it in Vim after install with no additional setup.
 
 ##### Vim 8 Native Plugin Management
 

From b2f03f913282b359d6301c426093b59b04303cff Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 11 Sep 2023 13:19:57 -0700
Subject: [PATCH 0849/1034] Bump sphinx from 7.2.3 to 7.2.5 in /docs (#3882)

Bumps [sphinx](https://github.com/sphinx-doc/sphinx) from 7.2.3 to 7.2.5.
- [Release notes](https://github.com/sphinx-doc/sphinx/releases)
- [Changelog](https://github.com/sphinx-doc/sphinx/blob/master/CHANGES)
- [Commits](https://github.com/sphinx-doc/sphinx/compare/v7.2.3...v7.2.5)
---
 docs/requirements.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index b8bab4393ff..e4471b76031 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,7 +1,7 @@
 # Used by ReadTheDocs; pinned requirements for stability.
 
 myst-parser==2.0.0
-Sphinx==7.2.3
+Sphinx==7.2.5
 # Older versions break Sphinx even though they're declared to be supported.
 docutils==0.19
 sphinxcontrib-programoutput==0.17

From 14f60c84c84d6f872c09ec2171a873cac75f4c0f Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 11 Sep 2023 13:20:36 -0700
Subject: [PATCH 0850/1034] Bump docutils from 0.19 to 0.20.1 in /docs (#3699)

Bumps [docutils](https://docutils.sourceforge.io/) from 0.19 to 0.20.1.
---
 docs/requirements.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index e4471b76031..a29e295ae49 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -3,7 +3,7 @@
 myst-parser==2.0.0
 Sphinx==7.2.5
 # Older versions break Sphinx even though they're declared to be supported.
-docutils==0.19
+docutils==0.20.1
 sphinxcontrib-programoutput==0.17
 sphinx_copybutton==0.5.2
 furo==2023.9.10

From 004fb79706a02c9a06abd5c416b033340f99e558 Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Mon, 11 Sep 2023 13:36:37 -0700
Subject: [PATCH 0851/1034] mypyc build improvements (#3881)

Build in separate jobs. This makes it clearer if e.g. a single Python
version is failing. It also potentially gets you more parallelism.

Build everything on push to master.

Only build Linux 3.8 and 3.11 wheels on PRs.
---
 .github/workflows/pypi_upload.yml | 71 ++++++++++++++++++++++---------
 pyproject.toml                    |  4 +-
 2 files changed, 52 insertions(+), 23 deletions(-)

diff --git a/.github/workflows/pypi_upload.yml b/.github/workflows/pypi_upload.yml
index bf4d8349c95..813ac39186f 100644
--- a/.github/workflows/pypi_upload.yml
+++ b/.github/workflows/pypi_upload.yml
@@ -1,9 +1,12 @@
-name: Build wheels and publish to PyPI
+name: Build and publish
 
 on:
   release:
     types: [published]
   pull_request:
+  push:
+    branches:
+      - main
 
 permissions:
   contents: read
@@ -12,6 +15,7 @@ jobs:
   main:
     name: sdist + pure wheel
     runs-on: ubuntu-latest
+    if: github.event_name == 'release'
 
     steps:
       - uses: actions/checkout@v4
@@ -35,34 +39,58 @@ jobs:
           TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
         run: twine upload --verbose -u '__token__' dist/*
 
+  generate_wheels_matrix:
+    name: generate wheels matrix
+    runs-on: ubuntu-latest
+    outputs:
+      include: ${{ steps.set-matrix.outputs.include }}
+    steps:
+      - uses: actions/checkout@v3
+      - name: Install cibuildwheel and pypyp
+        run: |
+          pipx install cibuildwheel==2.15.0
+          pipx install pypyp==1
+      - name: generate matrix
+        if: github.event_name != 'pull_request'
+        run: |
+          {
+            cibuildwheel --print-build-identifiers --platform linux \
+            | pyp 'json.dumps({"only": x, "os": "ubuntu-latest"})' \
+            && cibuildwheel --print-build-identifiers --platform macos \
+            | pyp 'json.dumps({"only": x, "os": "macos-latest"})' \
+            && cibuildwheel --print-build-identifiers --platform windows \
+            | pyp 'json.dumps({"only": x, "os": "windows-latest"})'
+          } | pyp 'json.dumps(list(map(json.loads, lines)))' > /tmp/matrix
+        env:
+          CIBW_ARCHS_LINUX: x86_64
+          CIBW_ARCHS_MACOS: x86_64 arm64
+          CIBW_ARCHS_WINDOWS: AMD64
+      - name: generate matrix (PR)
+        if: github.event_name == 'pull_request'
+        run: |
+          cibuildwheel --print-build-identifiers --platform linux \
+          | pyp 'json.dumps({"only": x, "os": "ubuntu-latest"})' \
+          | pyp 'json.dumps(list(map(json.loads, lines)))' > /tmp/matrix
+        env:
+          CIBW_BUILD: "cp38-* cp311-*"
+          CIBW_ARCHS_LINUX: x86_64
+      - id: set-matrix
+        run: echo "include=$(cat /tmp/matrix)" | tee -a $GITHUB_OUTPUT
+
   mypyc:
-    name: mypyc wheels (${{ matrix.name }})
+    name: mypyc wheels ${{ matrix.only }}
+    needs: generate_wheels_matrix
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
       matrix:
-        include:
-          - os: ubuntu-latest
-            name: linux-x86_64
-          - os: windows-2019
-            name: windows-amd64
-          - os: macos-11
-            name: macos-x86_64
-            macos_arch: "x86_64"
-          - os: macos-11
-            name: macos-arm64
-            macos_arch: "arm64"
-          - os: macos-11
-            name: macos-universal2
-            macos_arch: "universal2"
+        include: ${{ fromJson(needs.generate_wheels_matrix.outputs.include) }}
 
     steps:
       - uses: actions/checkout@v4
-
-      - name: Build wheels via cibuildwheel
-        uses: pypa/cibuildwheel@v2.15.0
-        env:
-          CIBW_ARCHS_MACOS: "${{ matrix.macos_arch }}"
+      - uses: pypa/cibuildwheel@v2.15.0
+        with:
+          only: ${{ matrix.only }}
 
       - name: Upload wheels as workflow artifacts
         uses: actions/upload-artifact@v3
@@ -80,6 +108,7 @@ jobs:
     name: Update stable branch
     needs: [main, mypyc]
     runs-on: ubuntu-latest
+    if: github.event_name == 'release'
     permissions:
       contents: write
 
diff --git a/pyproject.toml b/pyproject.toml
index 159907ac8ec..d246eb0b272 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -145,8 +145,8 @@ build-verbosity = 1
 # - Python: CPython 3.8+ only
 # - Architecture (64-bit only): amd64 / x86_64, universal2, and arm64
 # - OS: Linux (no musl), Windows, and macOS
-build = "cp3*-*"
-skip = ["*-manylinux_i686", "*-musllinux_*", "*-win32", "pp-*", "cp312-*"]
+build = "cp3*"
+skip = ["*-manylinux_i686", "*-musllinux_*", "*-win32", "pp*", "cp312-*"]
 # This is the bare minimum needed to run the test suite. Pulling in the full
 # test_requirements.txt would download a bunch of other packages not necessary
 # here and would slow down the testing step a fair bit.

From e9356c1ff0083aea4416bf1d3e29748634bb4f7f Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Wed, 13 Sep 2023 00:40:41 -0700
Subject: [PATCH 0852/1034] Document disabling E704 (#3888)

Linking #3887
---
 .flake8                                     | 2 +-
 docs/guides/using_black_with_other_tools.md | 2 +-
 docs/the_black_code_style/current_style.md  | 4 ++--
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/.flake8 b/.flake8
index 7bc346a09c1..85f51cf9f05 100644
--- a/.flake8
+++ b/.flake8
@@ -1,6 +1,6 @@
 [flake8]
 # B905 should be enabled when we drop support for 3.9
-ignore = E203, E266, E501, W503, B905, B907
+ignore = E203, E266, E501, E704, W503, B905, B907
 # line length is intentionally set to 80 here because black uses Bugbear
 # See https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#line-length for more details
 max-line-length = 80
diff --git a/docs/guides/using_black_with_other_tools.md b/docs/guides/using_black_with_other_tools.md
index 6c6fbb88174..22c641a7420 100644
--- a/docs/guides/using_black_with_other_tools.md
+++ b/docs/guides/using_black_with_other_tools.md
@@ -173,7 +173,7 @@ limit of `88`, _Black_'s default. This explains `max-line-length = 88`.
 ```ini
 [flake8]
 max-line-length = 88
-extend-ignore = E203
+extend-ignore = E203, E704
 ```
 
 </details>
diff --git a/docs/the_black_code_style/current_style.md b/docs/the_black_code_style/current_style.md
index e1a8078bf2c..ff757a8276b 100644
--- a/docs/the_black_code_style/current_style.md
+++ b/docs/the_black_code_style/current_style.md
@@ -173,7 +173,7 @@ If you use Flake8, you have a few options:
    max-line-length = 80
    ...
    select = C,E,F,W,B,B950
-   extend-ignore = E203, E501
+   extend-ignore = E203, E501, E704
    ```
 
    The rationale for E950 is explained in
@@ -184,7 +184,7 @@ If you use Flake8, you have a few options:
    ```ini
    [flake8]
    max-line-length = 88
-   extend-ignore = E203
+   extend-ignore = E203, E704
    ```
 
 An explanation of why E203 is disabled can be found in the [Slices section](#slices) of

From 5a0615a7edd3339718a346577f03cf07da364025 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 18 Sep 2023 06:47:02 -0700
Subject: [PATCH 0853/1034] Bump sphinx from 7.2.5 to 7.2.6 in /docs (#3895)

Bumps [sphinx](https://github.com/sphinx-doc/sphinx) from 7.2.5 to 7.2.6.
- [Release notes](https://github.com/sphinx-doc/sphinx/releases)
- [Changelog](https://github.com/sphinx-doc/sphinx/blob/master/CHANGES.rst)
- [Commits](https://github.com/sphinx-doc/sphinx/compare/v7.2.5...v7.2.6)

---
updated-dependencies:
- dependency-name: sphinx
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 docs/requirements.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index a29e295ae49..b5b9e22fc84 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,7 +1,7 @@
 # Used by ReadTheDocs; pinned requirements for stability.
 
 myst-parser==2.0.0
-Sphinx==7.2.5
+Sphinx==7.2.6
 # Older versions break Sphinx even though they're declared to be supported.
 docutils==0.20.1
 sphinxcontrib-programoutput==0.17

From 34ed4cf8fd14eb423e3eb0fabf558aee93868a35 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 18 Sep 2023 06:47:26 -0700
Subject: [PATCH 0854/1034] Bump docker/build-push-action from 4 to 5 (#3894)

Bumps [docker/build-push-action](https://github.com/docker/build-push-action) from 4 to 5.
- [Release notes](https://github.com/docker/build-push-action/releases)
- [Commits](https://github.com/docker/build-push-action/compare/v4...v5)

---
updated-dependencies:
- dependency-name: docker/build-push-action
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/docker.yml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
index 566fc880785..41f92b58853 100644
--- a/.github/workflows/docker.yml
+++ b/.github/workflows/docker.yml
@@ -36,7 +36,7 @@ jobs:
           latest_non_release)" >> $GITHUB_ENV
 
       - name: Build and push
-        uses: docker/build-push-action@v4
+        uses: docker/build-push-action@v5
         with:
           context: .
           platforms: linux/amd64,linux/arm64
@@ -47,7 +47,7 @@ jobs:
         if:
           ${{ github.event_name == 'release' && github.event.action == 'published' &&
           !github.event.release.prerelease }}
-        uses: docker/build-push-action@v4
+        uses: docker/build-push-action@v5
         with:
           context: .
           platforms: linux/amd64,linux/arm64
@@ -58,7 +58,7 @@ jobs:
         if:
           ${{ github.event_name == 'release' && github.event.action == 'published' &&
           github.event.release.prerelease }}
-        uses: docker/build-push-action@v4
+        uses: docker/build-push-action@v5
         with:
           context: .
           platforms: linux/amd64,linux/arm64

From ab92daf408727718849d16fcd13590006e52c1bd Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 18 Sep 2023 06:47:43 -0700
Subject: [PATCH 0855/1034] Bump docker/login-action from 2 to 3 (#3891)

Bumps [docker/login-action](https://github.com/docker/login-action) from 2 to 3.
- [Release notes](https://github.com/docker/login-action/releases)
- [Commits](https://github.com/docker/login-action/compare/v2...v3)

---
updated-dependencies:
- dependency-name: docker/login-action
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/docker.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
index 41f92b58853..a5992f758c1 100644
--- a/.github/workflows/docker.yml
+++ b/.github/workflows/docker.yml
@@ -25,7 +25,7 @@ jobs:
         uses: docker/setup-buildx-action@v2
 
       - name: Login to DockerHub
-        uses: docker/login-action@v2
+        uses: docker/login-action@v3
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}

From edf66baa21d337ae069be3871e95f88b68a3ffcf Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 18 Sep 2023 06:48:03 -0700
Subject: [PATCH 0856/1034] Bump docker/setup-buildx-action from 2 to 3 (#3892)

Bumps [docker/setup-buildx-action](https://github.com/docker/setup-buildx-action) from 2 to 3.
- [Release notes](https://github.com/docker/setup-buildx-action/releases)
- [Commits](https://github.com/docker/setup-buildx-action/compare/v2...v3)

---
updated-dependencies:
- dependency-name: docker/setup-buildx-action
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/docker.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
index a5992f758c1..80930ccfee8 100644
--- a/.github/workflows/docker.yml
+++ b/.github/workflows/docker.yml
@@ -22,7 +22,7 @@ jobs:
         uses: docker/setup-qemu-action@v2
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v2
+        uses: docker/setup-buildx-action@v3
 
       - name: Login to DockerHub
         uses: docker/login-action@v3

From f5990e85474f7641717e70bafb797462995d974f Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 18 Sep 2023 06:48:11 -0700
Subject: [PATCH 0857/1034] Bump docker/setup-qemu-action from 2 to 3 (#3890)

Bumps [docker/setup-qemu-action](https://github.com/docker/setup-qemu-action) from 2 to 3.
- [Release notes](https://github.com/docker/setup-qemu-action/releases)
- [Commits](https://github.com/docker/setup-qemu-action/compare/v2...v3)

---
updated-dependencies:
- dependency-name: docker/setup-qemu-action
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/docker.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
index 80930ccfee8..ee858236fcf 100644
--- a/.github/workflows/docker.yml
+++ b/.github/workflows/docker.yml
@@ -19,7 +19,7 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Set up QEMU
-        uses: docker/setup-qemu-action@v2
+        uses: docker/setup-qemu-action@v3
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3

From 7316a793187eedd94c288f1df648ecca0d8763dd Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 18 Sep 2023 06:48:27 -0700
Subject: [PATCH 0858/1034] Bump actions/checkout from 3 to 4 (#3893)

Bumps [actions/checkout](https://github.com/actions/checkout) from 3 to 4.
- [Release notes](https://github.com/actions/checkout/releases)
- [Changelog](https://github.com/actions/checkout/blob/main/CHANGELOG.md)
- [Commits](https://github.com/actions/checkout/compare/v3...v4)

---
updated-dependencies:
- dependency-name: actions/checkout
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/pypi_upload.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/pypi_upload.yml b/.github/workflows/pypi_upload.yml
index 813ac39186f..2a74b7c6a55 100644
--- a/.github/workflows/pypi_upload.yml
+++ b/.github/workflows/pypi_upload.yml
@@ -45,7 +45,7 @@ jobs:
     outputs:
       include: ${{ steps.set-matrix.outputs.include }}
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Install cibuildwheel and pypyp
         run: |
           pipx install cibuildwheel==2.15.0

From e974fc3c52959e9f01bf62bdcd0d8c100ce78985 Mon Sep 17 00:00:00 2001
From: Eero Vaher <eero.vaher@gmail.com>
Date: Mon, 18 Sep 2023 20:35:07 +0300
Subject: [PATCH 0859/1034] Remove outdated mentions of runtime support of
 Python 3.7 (#3896)

Remove mentions of runtime support of Python 3.7

Runtime support of Python 3.7 was removed in
b4dca26c7d93f930bbd5a7b552807370b60d4298 but a few mentions of it being
supported have remained until now.
---
 README.md                    | 2 +-
 autoload/black.vim           | 4 ++--
 docs/faq.md                  | 6 +++---
 docs/getting_started.md      | 2 +-
 docs/integrations/editors.md | 2 +-
 5 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index b257c333f0d..cad8184f7bc 100644
--- a/README.md
+++ b/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.7+ to run.
+_Black_ can be installed by running `pip install black`. It requires Python 3.8+ 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:
diff --git a/autoload/black.vim b/autoload/black.vim
index 4eb9b25db28..051fea05c3b 100644
--- a/autoload/black.vim
+++ b/autoload/black.vim
@@ -75,8 +75,8 @@ def _initialize_black_env(upgrade=False):
       return True
 
   pyver = sys.version_info[:3]
-  if pyver < (3, 7):
-    print("Sorry, Black requires Python 3.7+ to run.")
+  if pyver < (3, 8):
+    print("Sorry, Black requires Python 3.8+ to run.")
     return False
 
   from pathlib import Path
diff --git a/docs/faq.md b/docs/faq.md
index 8941ca3fe4d..c62e1b504b5 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -86,7 +86,7 @@ disabled-by-default counterpart W504. E203 should be disabled while changes are
 
 ## Which Python versions does Black support?
 
-Currently the runtime requires Python 3.7-3.11. Formatting is supported for files
+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.
@@ -95,7 +95,7 @@ Support for formatting Python 2 code was removed in version 22.0. While we've ma
 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.6 was removed in version 22.10.0.
+Runtime support for 3.7 was removed in version 23.7.0.
 
 ## Why does my linter or typechecker complain after I format my code?
 
@@ -107,7 +107,7 @@ codebase with _Black_.
 
 ## Can I run Black with PyPy?
 
-Yes, there is support for PyPy 3.7 and higher.
+Yes, there is support for PyPy 3.8 and higher.
 
 ## Why does Black not detect syntax errors in my code?
 
diff --git a/docs/getting_started.md b/docs/getting_started.md
index 33fb2f978bb..15b7646a509 100644
--- a/docs/getting_started.md
+++ b/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.7+ to run.
+_Black_ can be installed by running `pip install black`. It requires Python 3.8+ 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:
diff --git a/docs/integrations/editors.md b/docs/integrations/editors.md
index ab8c6a743e5..9c7cfe19083 100644
--- a/docs/integrations/editors.md
+++ b/docs/integrations/editors.md
@@ -236,7 +236,7 @@ Configuration:
 
 #### Installation
 
-This plugin **requires Vim 7.0+ built with Python 3.7+ support**. It needs Python 3.7 to
+This plugin **requires Vim 7.0+ built with Python 3.8+ support**. It needs Python 3.8 to
 be able to run _Black_ inside the Vim process which is much faster than calling an
 external command.
 

From 8c5d96ffd3da6d621e67639dadd26a1d7d0227cd Mon Sep 17 00:00:00 2001
From: John Litborn <11260241+jakkdl@users.noreply.github.com>
Date: Fri, 22 Sep 2023 17:38:51 +0200
Subject: [PATCH 0860/1034] fix indentation of line breaks in long type hints
 by adding parens (#3899)

* fix indentation of line breaks in long type hints by adding parentheses, and remove unnecessary parentheses

* add entry in CHANGES.md, make the style change only in preview mode
---
 CHANGES.md                                    |   3 +
 src/black/linegen.py                          |  30 ++-
 src/black/mode.py                             |   1 +
 .../preview/long_strings__type_annotations.py |   2 +-
 .../pep604_union_types_line_breaks.py         | 187 ++++++++++++++++++
 5 files changed, 220 insertions(+), 3 deletions(-)
 create mode 100644 tests/data/preview_py_310/pep604_union_types_line_breaks.py

diff --git a/CHANGES.md b/CHANGES.md
index a68106ad23f..a879ab3e8da 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -12,6 +12,9 @@
 
 ### Preview style
 
+- Long type hints are now wrapped in parentheses and properly indented when split across
+  multiple lines (#3899)
+
 <!-- Changes that affect Black's preview style -->
 
 ### Configuration
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 507e860190f..9ddd4619f69 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -397,6 +397,24 @@ def visit_factor(self, node: Node) -> Iterator[Line]:
             node.insert_child(index, Node(syms.atom, [lpar, operand, rpar]))
         yield from self.visit_default(node)
 
+    def visit_tname(self, node: Node) -> Iterator[Line]:
+        """
+        Add potential parentheses around types in function parameter lists to be made
+        into real parentheses in case the type hint is too long to fit on a line
+        Examples:
+        def foo(a: int, b: float = 7): ...
+
+        ->
+
+        def foo(a: (int), b: (float) = 7): ...
+        """
+        if Preview.parenthesize_long_type_hints in self.mode:
+            assert len(node.children) == 3
+            if maybe_make_parens_invisible_in_atom(node.children[2], parent=node):
+                wrap_in_parentheses(node, node.children[2], visible=False)
+
+        yield from self.visit_default(node)
+
     def visit_STRING(self, leaf: Leaf) -> Iterator[Line]:
         if Preview.hex_codes_in_unicode_sequences in self.mode:
             normalize_unicode_escape_sequences(leaf)
@@ -498,7 +516,14 @@ def __post_init__(self) -> None:
         self.visit_except_clause = partial(v, keywords={"except"}, parens={"except"})
         self.visit_with_stmt = partial(v, keywords={"with"}, parens={"with"})
         self.visit_classdef = partial(v, keywords={"class"}, parens=Ø)
-        self.visit_expr_stmt = partial(v, keywords=Ø, parens=ASSIGNMENTS)
+
+        # When this is moved out of preview, add ":" directly to ASSIGNMENTS in nodes.py
+        if Preview.parenthesize_long_type_hints in self.mode:
+            assignments = ASSIGNMENTS | {":"}
+        else:
+            assignments = ASSIGNMENTS
+        self.visit_expr_stmt = partial(v, keywords=Ø, parens=assignments)
+
         self.visit_return_stmt = partial(v, keywords={"return"}, parens={"return"})
         self.visit_import_from = partial(v, keywords=Ø, parens={"import"})
         self.visit_del_stmt = partial(v, keywords=Ø, parens={"del"})
@@ -1368,7 +1393,7 @@ def maybe_make_parens_invisible_in_atom(
     Returns whether the node should itself be wrapped in invisible parentheses.
     """
     if (
-        node.type != syms.atom
+        node.type not in (syms.atom, syms.expr)
         or is_empty_tuple(node)
         or is_one_tuple(node)
         or (is_yield(node) and parent.type != syms.expr_stmt)
@@ -1392,6 +1417,7 @@ def maybe_make_parens_invisible_in_atom(
             syms.except_clause,
             syms.funcdef,
             syms.with_stmt,
+            syms.tname,
             # these ones aren't useful to end users, but they do please fuzzers
             syms.for_stmt,
             syms.del_stmt,
diff --git a/src/black/mode.py b/src/black/mode.py
index 8a855ac495a..f44a821bcd0 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -180,6 +180,7 @@ class Preview(Enum):
     # for https://github.com/psf/black/issues/3117 to be fixed.
     string_processing = auto()
     parenthesize_conditional_expressions = auto()
+    parenthesize_long_type_hints = auto()
     skip_magic_trailing_comma_in_subscript = auto()
     wrap_long_dict_values_in_parens = auto()
     wrap_multiple_context_managers_in_parens = auto()
diff --git a/tests/data/preview/long_strings__type_annotations.py b/tests/data/preview/long_strings__type_annotations.py
index 41d7ee2b67b..45de882d02c 100644
--- a/tests/data/preview/long_strings__type_annotations.py
+++ b/tests/data/preview/long_strings__type_annotations.py
@@ -54,6 +54,6 @@ def func(
 
 
 def func(
-    argument: ("int |" "str"),
+    argument: "int |" "str",
 ) -> Set["int |" " str"]:
     pass
diff --git a/tests/data/preview_py_310/pep604_union_types_line_breaks.py b/tests/data/preview_py_310/pep604_union_types_line_breaks.py
new file mode 100644
index 00000000000..9c4ab870766
--- /dev/null
+++ b/tests/data/preview_py_310/pep604_union_types_line_breaks.py
@@ -0,0 +1,187 @@
+# This has always worked
+z= Loooooooooooooooooooooooong | Loooooooooooooooooooooooong | Loooooooooooooooooooooooong | Loooooooooooooooooooooooong
+
+# "AnnAssign"s now also work
+z: Loooooooooooooooooooooooong | Loooooooooooooooooooooooong | Loooooooooooooooooooooooong | Loooooooooooooooooooooooong
+z: (Short
+    | Short2
+    | Short3
+    | Short4)
+z: (int)
+z: ((int))
+
+
+z: Loooooooooooooooooooooooong | Loooooooooooooooooooooooong | Loooooooooooooooooooooooong | Loooooooooooooooooooooooong = 7
+z: (Short
+    | Short2
+    | Short3
+    | Short4) = 8
+z: (int) = 2.3
+z: ((int)) = foo()
+
+# In case I go for not enforcing parantheses, this might get improved at the same time
+x = (
+    z
+    == 9999999999999999999999999999999999999999
+    | 9999999999999999999999999999999999999999
+    | 9999999999999999999999999999999999999999
+    | 9999999999999999999999999999999999999999,
+    y
+    == 9999999999999999999999999999999999999999
+    + 9999999999999999999999999999999999999999
+    + 9999999999999999999999999999999999999999
+    + 9999999999999999999999999999999999999999,
+)
+
+x = (
+    z == (9999999999999999999999999999999999999999
+    | 9999999999999999999999999999999999999999
+    | 9999999999999999999999999999999999999999
+    | 9999999999999999999999999999999999999999),
+    y == (9999999999999999999999999999999999999999
+    + 9999999999999999999999999999999999999999
+    + 9999999999999999999999999999999999999999
+    + 9999999999999999999999999999999999999999),
+)
+
+# handle formatting of "tname"s in parameter list
+
+# remove unnecessary paren
+def foo(i: (int)) -> None: ...
+
+
+# this is a syntax error in the type annotation according to mypy, but it's not invalid *python* code, so make sure we don't mess with it and make it so.
+def foo(i: (int,)) -> None: ...
+
+def foo(
+    i: int,
+    x: Loooooooooooooooooooooooong
+    | Looooooooooooooooong
+    | Looooooooooooooooooooong
+    | Looooooong,
+    *,
+    s: str,
+) -> None:
+    pass
+
+
+@app.get("/path/")
+async def foo(
+    q: str
+    | None = Query(None, title="Some long title", description="Some long description")
+):
+    pass
+
+
+def f(
+    max_jobs: int
+    | None = Option(
+        None, help="Maximum number of jobs to launch. And some additional text."
+        ),
+    another_option: bool = False
+    ):
+    ...
+
+
+# output
+# This has always worked
+z = (
+    Loooooooooooooooooooooooong
+    | Loooooooooooooooooooooooong
+    | Loooooooooooooooooooooooong
+    | Loooooooooooooooooooooooong
+)
+
+# "AnnAssign"s now also work
+z: (
+    Loooooooooooooooooooooooong
+    | Loooooooooooooooooooooooong
+    | Loooooooooooooooooooooooong
+    | Loooooooooooooooooooooooong
+)
+z: Short | Short2 | Short3 | Short4
+z: int
+z: int
+
+
+z: (
+    Loooooooooooooooooooooooong
+    | Loooooooooooooooooooooooong
+    | Loooooooooooooooooooooooong
+    | Loooooooooooooooooooooooong
+) = 7
+z: Short | Short2 | Short3 | Short4 = 8
+z: int = 2.3
+z: int = foo()
+
+# In case I go for not enforcing parantheses, this might get improved at the same time
+x = (
+    z
+    == 9999999999999999999999999999999999999999
+    | 9999999999999999999999999999999999999999
+    | 9999999999999999999999999999999999999999
+    | 9999999999999999999999999999999999999999,
+    y
+    == 9999999999999999999999999999999999999999
+    + 9999999999999999999999999999999999999999
+    + 9999999999999999999999999999999999999999
+    + 9999999999999999999999999999999999999999,
+)
+
+x = (
+    z
+    == (
+        9999999999999999999999999999999999999999
+        | 9999999999999999999999999999999999999999
+        | 9999999999999999999999999999999999999999
+        | 9999999999999999999999999999999999999999
+    ),
+    y
+    == (
+        9999999999999999999999999999999999999999
+        + 9999999999999999999999999999999999999999
+        + 9999999999999999999999999999999999999999
+        + 9999999999999999999999999999999999999999
+    ),
+)
+
+# handle formatting of "tname"s in parameter list
+
+
+# remove unnecessary paren
+def foo(i: int) -> None: ...
+
+
+# this is a syntax error in the type annotation according to mypy, but it's not invalid *python* code, so make sure we don't mess with it and make it so.
+def foo(i: (int,)) -> None: ...
+
+
+def foo(
+    i: int,
+    x: (
+        Loooooooooooooooooooooooong
+        | Looooooooooooooooong
+        | Looooooooooooooooooooong
+        | Looooooong
+    ),
+    *,
+    s: str,
+) -> None:
+    pass
+
+
+@app.get("/path/")
+async def foo(
+    q: str | None = Query(
+        None, title="Some long title", description="Some long description"
+    )
+):
+    pass
+
+
+def f(
+    max_jobs: int | None = Option(
+        None, help="Maximum number of jobs to launch. And some additional text."
+    ),
+    another_option: bool = False,
+): ...

From 5f6ea5ff20100290ba8e8803a924caea12d2d0b6 Mon Sep 17 00:00:00 2001
From: Syed Mohammad Ibrahim <8592115+iamibi@users.noreply.github.com>
Date: Sun, 24 Sep 2023 07:53:03 +0530
Subject: [PATCH 0861/1034] added the py311 to target-version config (#3898)

---
 docs/usage_and_configuration/the_basics.md | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index 57fafd87654..36119f225e6 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -52,18 +52,19 @@ See also [the style documentation](labels/line-length).
 
 #### `-t`, `--target-version`
 
-Python versions that should be supported by Black's output. You should include all
-versions that your code supports. If you support Python 3.7 through 3.10, you should
-write:
+Python versions that should be supported by Black's output. You can run `black --help`
+and look for the `--target-version` option to see the full list of supported versions.
+You should include all versions that your code supports. If you support Python 3.8
+through 3.11, you should write:
 
 ```console
-$ black -t py37 -t py38 -t py39 -t py310
+$ black -t py38 -t py39 -t py310 -t py311
 ```
 
 In a [configuration file](#configuration-via-a-file), you can write:
 
 ```toml
-target-version = ["py37", "py38", "py39", "py310"]
+target-version = ["py38", "py39", "py310", "py311"]
 ```
 
 _Black_ uses this option to decide what grammar to use to parse your code. In addition,

From 3dcacdda0d7f69a1705f3e2a151c24a6cf004171 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 25 Sep 2023 09:32:58 -0700
Subject: [PATCH 0862/1034] Bump pypa/cibuildwheel from 2.15.0 to 2.16.0
 (#3901)

Bumps [pypa/cibuildwheel](https://github.com/pypa/cibuildwheel) from 2.15.0 to 2.16.0.
- [Release notes](https://github.com/pypa/cibuildwheel/releases)
- [Changelog](https://github.com/pypa/cibuildwheel/blob/main/docs/changelog.md)
- [Commits](https://github.com/pypa/cibuildwheel/compare/v2.15.0...v2.16.0)

---
updated-dependencies:
- dependency-name: pypa/cibuildwheel
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/pypi_upload.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/pypi_upload.yml b/.github/workflows/pypi_upload.yml
index 2a74b7c6a55..026f74e1c9f 100644
--- a/.github/workflows/pypi_upload.yml
+++ b/.github/workflows/pypi_upload.yml
@@ -88,7 +88,7 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
-      - uses: pypa/cibuildwheel@v2.15.0
+      - uses: pypa/cibuildwheel@v2.16.0
         with:
           only: ${{ matrix.only }}
 

From 9b82120ddb81373377b58da5de7caa9495a1551e Mon Sep 17 00:00:00 2001
From: John Litborn <11260241+jakkdl@users.noreply.github.com>
Date: Thu, 28 Sep 2023 16:03:24 +0200
Subject: [PATCH 0863/1034] add support for printing the diff of AST trees when
 running tests (#3902)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 docs/contributing/the_basics.md | 38 +++++++++++++++++++++++++++++++++
 src/black/debug.py              | 21 ++++++++++++------
 tests/conftest.py               | 27 +++++++++++++++++++++++
 tests/test_black.py             | 29 ++++++++++++++++++++++---
 tests/util.py                   | 24 ++++++++++++++++-----
 tox.ini                         |  2 +-
 6 files changed, 125 insertions(+), 16 deletions(-)

diff --git a/docs/contributing/the_basics.md b/docs/contributing/the_basics.md
index 40d233257e3..864894b491f 100644
--- a/docs/contributing/the_basics.md
+++ b/docs/contributing/the_basics.md
@@ -37,6 +37,44 @@ the root of the black repo:
 (.venv)$ tox -e run_self
 ```
 
+### Development
+
+Further examples of invoking the tests
+
+```console
+# Run all of the above mentioned, in parallel
+(.venv)$ tox --parallel=auto
+
+# Run tests on a specific python version
+(.venv)$ tox -e py39
+
+# pass arguments to pytest
+(.venv)$ tox -e py -- --no-cov
+
+# print full tree diff, see documentation below
+(.venv)$ tox -e py -- --print-full-tree
+
+# disable diff printing, see documentation below
+(.venv)$ tox -e py -- --print-tree-diff=False
+```
+
+`Black` has two pytest command-line options affecting test files in `tests/data/` that
+are split into an input part, and an output part, separated by a line with`# output`.
+These can be passed to `pytest` through `tox`, or directly into pytest if not using
+`tox`.
+
+#### `--print-full-tree`
+
+Upon a failing test, print the full concrete syntax tree (CST) as it is after processing
+the input ("actual"), and the tree that's yielded after parsing the output ("expected").
+Note that a test can fail with different output with the same CST. This used to be the
+default, but now defaults to `False`.
+
+#### `--print-tree-diff`
+
+Upon a failing test, print the diff of the trees as described above. This is the
+default. To turn it off pass `--print-tree-diff=False`.
+
 ### News / Changelog Requirement
 
 `Black` has CI that will check for an entry corresponding to your PR in `CHANGES.md`. If
diff --git a/src/black/debug.py b/src/black/debug.py
index 150b44842dd..cebc48765ba 100644
--- a/src/black/debug.py
+++ b/src/black/debug.py
@@ -1,5 +1,5 @@
-from dataclasses import dataclass
-from typing import Iterator, TypeVar, Union
+from dataclasses import dataclass, field
+from typing import Any, Iterator, List, TypeVar, Union
 
 from black.nodes import Visitor
 from black.output import out
@@ -14,26 +14,33 @@
 @dataclass
 class DebugVisitor(Visitor[T]):
     tree_depth: int = 0
+    list_output: List[str] = field(default_factory=list)
+    print_output: bool = True
+
+    def out(self, message: str, *args: Any, **kwargs: Any) -> None:
+        self.list_output.append(message)
+        if self.print_output:
+            out(message, *args, **kwargs)
 
     def visit_default(self, node: LN) -> Iterator[T]:
         indent = " " * (2 * self.tree_depth)
         if isinstance(node, Node):
             _type = type_repr(node.type)
-            out(f"{indent}{_type}", fg="yellow")
+            self.out(f"{indent}{_type}", fg="yellow")
             self.tree_depth += 1
             for child in node.children:
                 yield from self.visit(child)
 
             self.tree_depth -= 1
-            out(f"{indent}/{_type}", fg="yellow", bold=False)
+            self.out(f"{indent}/{_type}", fg="yellow", bold=False)
         else:
             _type = token.tok_name.get(node.type, str(node.type))
-            out(f"{indent}{_type}", fg="blue", nl=False)
+            self.out(f"{indent}{_type}", fg="blue", nl=False)
             if node.prefix:
                 # We don't have to handle prefixes for `Node` objects since
                 # that delegates to the first child anyway.
-                out(f" {node.prefix!r}", fg="green", bold=False, nl=False)
-            out(f" {node.value!r}", fg="blue", bold=False)
+                self.out(f" {node.prefix!r}", fg="green", bold=False, nl=False)
+            self.out(f" {node.value!r}", fg="blue", bold=False)
 
     @classmethod
     def show(cls, code: Union[str, Leaf, Node]) -> None:
diff --git a/tests/conftest.py b/tests/conftest.py
index 67517268d1b..1a0dd747d8e 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -1 +1,28 @@
+import pytest
+
 pytest_plugins = ["tests.optional"]
+
+PRINT_FULL_TREE: bool = False
+PRINT_TREE_DIFF: bool = True
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    parser.addoption(
+        "--print-full-tree",
+        action="store_true",
+        default=False,
+        help="print full syntax trees on failed tests",
+    )
+    parser.addoption(
+        "--print-tree-diff",
+        action="store_true",
+        default=True,
+        help="print diff of syntax trees on failed tests",
+    )
+
+
+def pytest_configure(config: pytest.Config) -> None:
+    global PRINT_FULL_TREE
+    global PRINT_TREE_DIFF
+    PRINT_FULL_TREE = config.getoption("--print-full-tree")
+    PRINT_TREE_DIFF = config.getoption("--print-tree-diff")
diff --git a/tests/test_black.py b/tests/test_black.py
index d22b6859607..c665eee3a6c 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -9,7 +9,6 @@
 import re
 import sys
 import types
-import unittest
 from concurrent.futures import ThreadPoolExecutor
 from contextlib import contextmanager, redirect_stderr
 from dataclasses import replace
@@ -1047,9 +1046,10 @@ def test_endmarker(self) -> None:
         self.assertEqual(len(n.children), 1)
         self.assertEqual(n.children[0].type, black.token.ENDMARKER)
 
+    @patch("tests.conftest.PRINT_FULL_TREE", True)
+    @patch("tests.conftest.PRINT_TREE_DIFF", False)
     @pytest.mark.incompatible_with_mypyc
-    @unittest.skipIf(os.environ.get("SKIP_AST_PRINT"), "user set SKIP_AST_PRINT")
-    def test_assertFormatEqual(self) -> None:
+    def test_assertFormatEqual_print_full_tree(self) -> None:
         out_lines = []
         err_lines = []
 
@@ -1068,6 +1068,29 @@ def err(msg: str, **kwargs: Any) -> None:
         self.assertIn("Actual tree:", out_str)
         self.assertEqual("".join(err_lines), "")
 
+    @patch("tests.conftest.PRINT_FULL_TREE", False)
+    @patch("tests.conftest.PRINT_TREE_DIFF", True)
+    @pytest.mark.incompatible_with_mypyc
+    def test_assertFormatEqual_print_tree_diff(self) -> None:
+        out_lines = []
+        err_lines = []
+
+        def out(msg: str, **kwargs: Any) -> None:
+            out_lines.append(msg)
+
+        def err(msg: str, **kwargs: Any) -> None:
+            err_lines.append(msg)
+
+        with patch("black.output._out", out), patch("black.output._err", err):
+            with self.assertRaises(AssertionError):
+                self.assertFormatEqual("j = [1, 2, 3]\n", "j = [1, 2, 3,]\n")
+
+        out_str = "".join(out_lines)
+        self.assertIn("Tree Diff:", out_str)
+        self.assertIn("+          COMMA", out_str)
+        self.assertIn("+ ','", out_str)
+        self.assertEqual("".join(err_lines), "")
+
     @event_loop()
     @patch("concurrent.futures.ProcessPoolExecutor", MagicMock(side_effect=OSError))
     def test_works_in_mono_process_only_environment(self) -> None:
diff --git a/tests/util.py b/tests/util.py
index 967d576fafe..541d21da4df 100644
--- a/tests/util.py
+++ b/tests/util.py
@@ -12,6 +12,8 @@
 from black.mode import TargetVersion
 from black.output import diff, err, out
 
+from . import conftest
+
 PYTHON_SUFFIX = ".py"
 ALLOWED_SUFFIXES = (PYTHON_SUFFIX, ".pyi", ".out", ".diff", ".ipynb")
 
@@ -34,22 +36,34 @@
 
 
 def _assert_format_equal(expected: str, actual: str) -> None:
-    if actual != expected and not os.environ.get("SKIP_AST_PRINT"):
+    if actual != expected and (conftest.PRINT_FULL_TREE or conftest.PRINT_TREE_DIFF):
         bdv: DebugVisitor[Any]
-        out("Expected tree:", fg="green")
+        actual_out: str = ""
+        expected_out: str = ""
+        if conftest.PRINT_FULL_TREE:
+            out("Expected tree:", fg="green")
         try:
             exp_node = black.lib2to3_parse(expected)
-            bdv = DebugVisitor()
+            bdv = DebugVisitor(print_output=conftest.PRINT_FULL_TREE)
             list(bdv.visit(exp_node))
+            expected_out = "\n".join(bdv.list_output)
         except Exception as ve:
             err(str(ve))
-        out("Actual tree:", fg="red")
+        if conftest.PRINT_FULL_TREE:
+            out("Actual tree:", fg="red")
         try:
             exp_node = black.lib2to3_parse(actual)
-            bdv = DebugVisitor()
+            bdv = DebugVisitor(print_output=conftest.PRINT_FULL_TREE)
             list(bdv.visit(exp_node))
+            actual_out = "\n".join(bdv.list_output)
         except Exception as ve:
             err(str(ve))
+        if conftest.PRINT_TREE_DIFF:
+            out("Tree Diff:")
+            out(
+                diff(expected_out, actual_out, "expected tree", "actual tree")
+                or "Trees do not differ"
+            )
 
     if actual != expected:
         out(diff(expected, actual, "expected", "actual"))
diff --git a/tox.ini b/tox.ini
index d34dbbc71db..018cef993c0 100644
--- a/tox.ini
+++ b/tox.ini
@@ -1,6 +1,6 @@
 [tox]
 isolated_build = true
-envlist = {,ci-}py{37,38,39,310,311,py3},fuzz,run_self
+envlist = {,ci-}py{38,39,310,311,py3},fuzz,run_self
 
 [testenv]
 setenv =

From e7c3368c1316c38338cef34fffc42ea3252b1802 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Thu, 28 Sep 2023 09:10:01 -0700
Subject: [PATCH 0864/1034] Try newer clang in diff-shades job (#3904)

---
 .github/workflows/diff_shades.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/diff_shades.yml b/.github/workflows/diff_shades.yml
index 637bd527eaa..97db907abc8 100644
--- a/.github/workflows/diff_shades.yml
+++ b/.github/workflows/diff_shades.yml
@@ -44,7 +44,7 @@ jobs:
       HATCH_BUILD_HOOKS_ENABLE: "1"
       # Clang is less picky with the C code it's given than gcc (and may
       # generate faster binaries too).
-      CC: clang-12
+      CC: clang-14
     strategy:
       fail-fast: false
       matrix:

From a91eb73064c9bef76c3a961ab662bb5f75a1543d Mon Sep 17 00:00:00 2001
From: Eddie Darling <darling@berkeley.edu>
Date: Sun, 1 Oct 2023 15:35:42 -0700
Subject: [PATCH 0865/1034] Fix comments getting removed from inside
 parenthesized strings (#3909)

Since the id of the old leaf may be
the key to comments, the new leaf
must adopt the old comments
---
 CHANGES.md                      |  2 ++
 src/black/trans.py              |  3 +++
 tests/data/preview/comments7.py | 24 ++++++++++++++++++++++++
 3 files changed, 29 insertions(+)

diff --git a/CHANGES.md b/CHANGES.md
index a879ab3e8da..028a01acd62 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -17,6 +17,8 @@
 
 <!-- Changes that affect Black's preview style -->
 
+- Fix comments getting removed from inside parenthesized strings (#3909)
+
 ### Configuration
 
 <!-- Changes to how Black can be configured -->
diff --git a/src/black/trans.py b/src/black/trans.py
index daed26427d7..c0cc92613ac 100644
--- a/src/black/trans.py
+++ b/src/black/trans.py
@@ -942,6 +942,9 @@ def _transform_to_new_line(
                 LL[lpar_or_rpar_idx].remove()  # Remove lpar.
                 replace_child(LL[idx], string_leaf)
                 new_line.append(string_leaf)
+                # replace comments
+                old_comments = new_line.comments.pop(id(LL[idx]), [])
+                new_line.comments.setdefault(id(string_leaf), []).extend(old_comments)
             else:
                 LL[lpar_or_rpar_idx].remove()  # This is a rpar.
 
diff --git a/tests/data/preview/comments7.py b/tests/data/preview/comments7.py
index 8b1224017e5..0655de999ec 100644
--- a/tests/data/preview/comments7.py
+++ b/tests/data/preview/comments7.py
@@ -131,6 +131,18 @@ def test_fails_invalid_post_data(
 
 square = Square(4) # type: Optional[Square]
 
+# Regression test for https://github.com/psf/black/issues/3756.
+[
+    (
+        "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"  # aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+    ),
+]
+[
+    (  # aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+        "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"  # aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+    ),
+]
+
 # output
 
 from .config import (
@@ -282,3 +294,15 @@ def test_fails_invalid_post_data(
 
 
 square = Square(4)  # type: Optional[Square]
+
+# Regression test for https://github.com/psf/black/issues/3756.
+[
+    (  # aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+        "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+    ),
+]
+[
+    (  # aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+        "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"  # aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+    ),
+]

From f99ef6e190785b3e6a58e83f1382e7d6d3c4881e Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Sun, 1 Oct 2023 15:41:32 -0700
Subject: [PATCH 0866/1034] Fix up changelog (#3910)

---
 CHANGES.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 028a01acd62..5e518497c92 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -10,14 +10,14 @@
 
 <!-- Changes that affect Black's stable style -->
 
-### Preview style
+- Fix comments getting removed from inside parenthesized strings (#3909)
 
-- Long type hints are now wrapped in parentheses and properly indented when split across
-  multiple lines (#3899)
+### Preview style
 
 <!-- Changes that affect Black's preview style -->
 
-- Fix comments getting removed from inside parenthesized strings (#3909)
+- Long type hints are now wrapped in parentheses and properly indented when split across
+  multiple lines (#3899)
 
 ### Configuration
 

From 1b08cbc63400a8b8e0fbb620b6b2a4dab35e1e7b Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Sun, 1 Oct 2023 23:40:00 -0700
Subject: [PATCH 0867/1034] Bump pypa/cibuildwheel from 2.16.0 to 2.16.1
 (#3911)

---
 .github/workflows/pypi_upload.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/pypi_upload.yml b/.github/workflows/pypi_upload.yml
index 026f74e1c9f..41ab6460793 100644
--- a/.github/workflows/pypi_upload.yml
+++ b/.github/workflows/pypi_upload.yml
@@ -88,7 +88,7 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
-      - uses: pypa/cibuildwheel@v2.16.0
+      - uses: pypa/cibuildwheel@v2.16.1
         with:
           only: ${{ matrix.only }}
 

From 9e9fdce9a81a53fd3771e1825de523a6413b3c35 Mon Sep 17 00:00:00 2001
From: Shreya Agarwal <a.shreya202@gmail.com>
Date: Mon, 2 Oct 2023 20:05:57 +0530
Subject: [PATCH 0868/1034] docs: use LSP for SublimeText 4 (#3913)

---
 docs/integrations/editors.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/docs/integrations/editors.md b/docs/integrations/editors.md
index 9c7cfe19083..83904144c48 100644
--- a/docs/integrations/editors.md
+++ b/docs/integrations/editors.md
@@ -399,9 +399,10 @@ close and reopen your File, _Black_ will be done with its job.
   server for Black. Formatting is much more responsive using this extension, **but the
   minimum supported version of Black is 22.3.0**.
 
-## SublimeText 3
+## SublimeText
 
-Use [sublack plugin](https://github.com/jgirardet/sublack).
+For SublimeText 3, use [sublack plugin](https://github.com/jgirardet/sublack). For
+higher versions, it is recommended to use [LSP](#python-lsp-server) as documented below.
 
 ## Python LSP Server
 

From 947bd3825e5dc67f16f48f916462c4470b7a5247 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Tue, 3 Oct 2023 10:19:53 -0700
Subject: [PATCH 0869/1034] [pre-commit.ci] pre-commit autoupdate (#3915)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

updates:
- [github.com/pre-commit/mirrors-mypy: v1.5.0 → v1.5.1](https://github.com/pre-commit/mirrors-mypy/compare/v1.5.0...v1.5.1)
- [github.com/pre-commit/mirrors-prettier: v3.0.1 → v3.0.3](https://github.com/pre-commit/mirrors-prettier/compare/v3.0.1...v3.0.3)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 .pre-commit-config.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 6301526a445..99b3565ed0e 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -39,7 +39,7 @@ repos:
         exclude: ^src/blib2to3/
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.5.0
+    rev: v1.5.1
     hooks:
       - id: mypy
         exclude: ^docs/conf.py
@@ -53,7 +53,7 @@ repos:
           - hypothesis
 
   - repo: https://github.com/pre-commit/mirrors-prettier
-    rev: v3.0.1
+    rev: v3.0.3
     hooks:
       - id: prettier
         exclude: \.github/workflows/diff_shades\.yml

From 36078bc83f24dcd5f74e021a105429595a3fd63c Mon Sep 17 00:00:00 2001
From: John Litborn <11260241+jakkdl@users.noreply.github.com>
Date: Thu, 5 Oct 2023 01:42:35 +0200
Subject: [PATCH 0870/1034] respect magic trailing commas in return types
 (#3916)

---
 CHANGES.md                                    |   1 +
 src/black/linegen.py                          |  36 ++-
 src/black/mode.py                             |   1 +
 .../return_annotation_brackets_string.py      |  11 +
 .../funcdef_return_type_trailing_comma.py     | 300 ++++++++++++++++++
 .../return_annotation_brackets.py             |  13 +
 6 files changed, 361 insertions(+), 1 deletion(-)
 create mode 100644 tests/data/preview_py_310/funcdef_return_type_trailing_comma.py

diff --git a/CHANGES.md b/CHANGES.md
index 5e518497c92..888824ee055 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -18,6 +18,7 @@
 
 - Long type hints are now wrapped in parentheses and properly indented when split across
   multiple lines (#3899)
+- Magic trailing commas are now respected in return types. (#3916)
 
 ### Configuration
 
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 9ddd4619f69..bdc4ee54ab2 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -573,7 +573,7 @@ def transform_line(
             transformers = [string_merge, string_paren_strip]
         else:
             transformers = []
-    elif line.is_def:
+    elif line.is_def and not should_split_funcdef_with_rhs(line, mode):
         transformers = [left_hand_split]
     else:
 
@@ -652,6 +652,40 @@ def _rhs(
         yield line
 
 
+def should_split_funcdef_with_rhs(line: Line, mode: Mode) -> bool:
+    """If a funcdef has a magic trailing comma in the return type, then we should first
+    split the line with rhs to respect the comma.
+    """
+    if Preview.respect_magic_trailing_comma_in_return_type not in mode:
+        return False
+
+    return_type_leaves: List[Leaf] = []
+    in_return_type = False
+
+    for leaf in line.leaves:
+        if leaf.type == token.COLON:
+            in_return_type = False
+        if in_return_type:
+            return_type_leaves.append(leaf)
+        if leaf.type == token.RARROW:
+            in_return_type = True
+
+    # using `bracket_split_build_line` will mess with whitespace, so we duplicate a
+    # couple lines from it.
+    result = Line(mode=line.mode, depth=line.depth)
+    leaves_to_track = get_leaves_inside_matching_brackets(return_type_leaves)
+    for leaf in return_type_leaves:
+        result.append(
+            leaf,
+            preformatted=True,
+            track_bracket=id(leaf) in leaves_to_track,
+        )
+
+    # we could also return true if the line is too long, and the return type is longer
+    # than the param list. Or if `should_split_rhs` returns True.
+    return result.magic_trailing_comma is not None
+
+
 class _BracketSplitComponent(Enum):
     head = auto()
     body = auto()
diff --git a/src/black/mode.py b/src/black/mode.py
index f44a821bcd0..30c5d2f1b2f 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -181,6 +181,7 @@ class Preview(Enum):
     string_processing = auto()
     parenthesize_conditional_expressions = auto()
     parenthesize_long_type_hints = auto()
+    respect_magic_trailing_comma_in_return_type = auto()
     skip_magic_trailing_comma_in_subscript = auto()
     wrap_long_dict_values_in_parens = auto()
     wrap_multiple_context_managers_in_parens = auto()
diff --git a/tests/data/preview/return_annotation_brackets_string.py b/tests/data/preview/return_annotation_brackets_string.py
index 6978829fd5c..9148bd045bc 100644
--- a/tests/data/preview/return_annotation_brackets_string.py
+++ b/tests/data/preview/return_annotation_brackets_string.py
@@ -2,6 +2,10 @@
 def frobnicate() -> "ThisIsTrulyUnreasonablyExtremelyLongClassName | list[ThisIsTrulyUnreasonablyExtremelyLongClassName]":
     pass
 
+# splitting the string breaks if there's any parameters
+def frobnicate(a) -> "ThisIsTrulyUnreasonablyExtremelyLongClassName | list[ThisIsTrulyUnreasonablyExtremelyLongClassName]":
+    pass
+
 # output
 
 # Long string example
@@ -10,3 +14,10 @@ def frobnicate() -> (
     " list[ThisIsTrulyUnreasonablyExtremelyLongClassName]"
 ):
     pass
+
+
+# splitting the string breaks if there's any parameters
+def frobnicate(
+    a,
+) -> "ThisIsTrulyUnreasonablyExtremelyLongClassName | list[ThisIsTrulyUnreasonablyExtremelyLongClassName]":
+    pass
diff --git a/tests/data/preview_py_310/funcdef_return_type_trailing_comma.py b/tests/data/preview_py_310/funcdef_return_type_trailing_comma.py
new file mode 100644
index 00000000000..15db772f01e
--- /dev/null
+++ b/tests/data/preview_py_310/funcdef_return_type_trailing_comma.py
@@ -0,0 +1,300 @@
+# normal, short, function definition
+def foo(a, b) -> tuple[int, float]: ...
+
+
+# normal, short, function definition w/o return type
+def foo(a, b): ...
+
+
+# no splitting
+def foo(a: A, b: B) -> list[p, q]:
+    pass
+
+
+# magic trailing comma in param list
+def foo(a, b,): ...
+
+
+# magic trailing comma in nested params in param list
+def foo(a, b: tuple[int, float,]): ...
+
+
+# magic trailing comma in return type, no params
+def a() -> tuple[
+    a,
+    b,
+]: ...
+
+
+# magic trailing comma in return type, params
+def foo(a: A, b: B) -> list[
+    p,
+    q,
+]:
+    pass
+
+
+# magic trailing comma in param list and in return type
+def foo(
+    a: a,
+    b: b,
+) -> list[
+    a,
+    a,
+]:
+    pass
+
+
+# long function definition, param list is longer
+def aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa(
+    bbbbbbbbbbbbbbbbbb,
+) -> cccccccccccccccccccccccccccccc: ...
+
+
+# long function definition, return type is longer
+# this should maybe split on rhs?
+def aaaaaaaaaaaaaaaaa(bbbbbbbbbbbbbbbbbb) -> list[
+    Ccccccccccccccccccccccccccccccccccccccccccccccccccc, Dddddd
+]: ...
+
+
+# long return type, no param list
+def foo() -> list[
+    Loooooooooooooooooooooooooooooooooooong,
+    Loooooooooooooooooooong,
+    Looooooooooooong,
+]: ...
+
+
+# long function name, no param list, no return value
+def thiiiiiiiiiiiiiiiiiis_iiiiiiiiiiiiiiiiiiiiiiiiiiiiiis_veeeeeeeeeeeeeeeeeeeeeeery_looooooong():
+    pass
+
+
+# long function name, no param list
+def thiiiiiiiiiiiiiiiiiis_iiiiiiiiiiiiiiiiiiiiiiiiiiiiiis_veeeeeeeeeeeeeeeeeeeeeeery_looooooong() -> (
+    list[int, float]
+): ...
+
+
+# long function name, no return value
+def thiiiiiiiiiiiiiiiiiis_iiiiiiiiiiiiiiiiiiiiiiiiiiiiiis_veeeeeeeeeeeeeeeeeeeeeeery_looooooong(
+    a, b
+): ...
+
+
+# unskippable type hint (??)
+def foo(a) -> list[aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa, aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa]:  # type: ignore
+    pass
+
+
+def foo(a) -> list[
+    aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa, aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+]:  # abpedeifnore
+    pass
+
+def foo(a, b: list[Bad],): ... # type: ignore
+
+# don't lose any comments (no magic)
+def foo( # 1
+    a, # 2
+    b) -> list[ # 3
+               a, # 4
+               b]: # 5
+        ... # 6
+
+
+# don't lose any comments (param list magic)
+def foo( # 1
+    a, # 2
+    b,) -> list[ # 3
+               a, # 4
+               b]: # 5
+        ... # 6
+
+
+# don't lose any comments (return type magic)
+def foo( # 1
+    a, # 2
+    b) -> list[ # 3
+               a, # 4
+               b,]: # 5
+        ... # 6
+
+
+# don't lose any comments (both magic)
+def foo( # 1
+    a, # 2
+    b,) -> list[ # 3
+               a, # 4
+               b,]: # 5
+        ... # 6
+
+# real life example
+def SimplePyFn(
+    context: hl.GeneratorContext,
+    buffer_input: Buffer[UInt8, 2],
+    func_input: Buffer[Int32, 2],
+    float_arg: Scalar[Float32],
+    offset: int = 0,
+) -> tuple[
+    Buffer[UInt8, 2],
+    Buffer[UInt8, 2],
+]: ...
+# output
+# normal, short, function definition
+def foo(a, b) -> tuple[int, float]: ...
+
+
+# normal, short, function definition w/o return type
+def foo(a, b): ...
+
+
+# no splitting
+def foo(a: A, b: B) -> list[p, q]:
+    pass
+
+
+# magic trailing comma in param list
+def foo(
+    a,
+    b,
+): ...
+
+
+# magic trailing comma in nested params in param list
+def foo(
+    a,
+    b: tuple[
+        int,
+        float,
+    ],
+): ...
+
+
+# magic trailing comma in return type, no params
+def a() -> tuple[
+    a,
+    b,
+]: ...
+
+
+# magic trailing comma in return type, params
+def foo(a: A, b: B) -> list[
+    p,
+    q,
+]:
+    pass
+
+
+# magic trailing comma in param list and in return type
+def foo(
+    a: a,
+    b: b,
+) -> list[
+    a,
+    a,
+]:
+    pass
+
+
+# long function definition, param list is longer
+def aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa(
+    bbbbbbbbbbbbbbbbbb,
+) -> cccccccccccccccccccccccccccccc: ...
+
+
+# long function definition, return type is longer
+# this should maybe split on rhs?
+def aaaaaaaaaaaaaaaaa(
+    bbbbbbbbbbbbbbbbbb,
+) -> list[Ccccccccccccccccccccccccccccccccccccccccccccccccccc, Dddddd]: ...
+
+
+# long return type, no param list
+def foo() -> list[
+    Loooooooooooooooooooooooooooooooooooong,
+    Loooooooooooooooooooong,
+    Looooooooooooong,
+]: ...
+
+
+# long function name, no param list, no return value
+def thiiiiiiiiiiiiiiiiiis_iiiiiiiiiiiiiiiiiiiiiiiiiiiiiis_veeeeeeeeeeeeeeeeeeeeeeery_looooooong():
+    pass
+
+
+# long function name, no param list
+def thiiiiiiiiiiiiiiiiiis_iiiiiiiiiiiiiiiiiiiiiiiiiiiiiis_veeeeeeeeeeeeeeeeeeeeeeery_looooooong() -> (
+    list[int, float]
+): ...
+
+
+# long function name, no return value
+def thiiiiiiiiiiiiiiiiiis_iiiiiiiiiiiiiiiiiiiiiiiiiiiiiis_veeeeeeeeeeeeeeeeeeeeeeery_looooooong(
+    a, b
+): ...
+
+
+# unskippable type hint (??)
+def foo(a) -> list[aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa, aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa]:  # type: ignore
+    pass
+
+
+def foo(
+    a,
+) -> list[
+    aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa, aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+]:  # abpedeifnore
+    pass
+
+
+def foo(
+    a,
+    b: list[Bad],
+): ...  # type: ignore
+
+
+# don't lose any comments (no magic)
+def foo(a, b) -> list[a, b]:  # 1  # 2  # 3  # 4  # 5
+    ...  # 6
+
+
+# don't lose any comments (param list magic)
+def foo(  # 1
+    a,  # 2
+    b,
+) -> list[a, b]:  # 3  # 4  # 5
+    ...  # 6
+
+
+# don't lose any comments (return type magic)
+def foo(a, b) -> list[  # 1  # 2  # 3
+    a,  # 4
+    b,
+]:  # 5
+    ...  # 6
+
+
+# don't lose any comments (both magic)
+def foo(  # 1
+    a,  # 2
+    b,
+) -> list[  # 3
+    a,  # 4
+    b,
+]:  # 5
+    ...  # 6
+
+
+# real life example
+def SimplePyFn(
+    context: hl.GeneratorContext,
+    buffer_input: Buffer[UInt8, 2],
+    func_input: Buffer[Int32, 2],
+    float_arg: Scalar[Float32],
+    offset: int = 0,
+) -> tuple[
+    Buffer[UInt8, 2],
+    Buffer[UInt8, 2],
+]: ...
diff --git a/tests/data/simple_cases/return_annotation_brackets.py b/tests/data/simple_cases/return_annotation_brackets.py
index 265c30220d8..8509ecdb92c 100644
--- a/tests/data/simple_cases/return_annotation_brackets.py
+++ b/tests/data/simple_cases/return_annotation_brackets.py
@@ -87,6 +87,11 @@ def foo() -> tuple[loooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
 def foo() -> tuple[int, int, int,]:
     return 2
 
+# Magic trailing comma example, with params
+# this is broken - the trailing comma is transferred to the param list. Fixed in preview
+def foo(a,b) -> tuple[int, int, int,]:
+    return 2
+
 # output
 # Control
 def double(a: int) -> int:
@@ -208,3 +213,11 @@ def foo() -> (
     ]
 ):
     return 2
+
+
+# Magic trailing comma example, with params
+# this is broken - the trailing comma is transferred to the param list. Fixed in preview
+def foo(
+    a, b
+) -> tuple[int, int, int,]:
+    return 2

From 6c88e8e46e19aa9f1986ab9d1f0ee4cf95f49956 Mon Sep 17 00:00:00 2001
From: Jake Anto <64896514+jake-anto@users.noreply.github.com>
Date: Fri, 6 Oct 2023 06:44:59 +0530
Subject: [PATCH 0871/1034] Update link to VS Code formatting instructions
 (#3921)

Update link
---
 docs/integrations/editors.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/integrations/editors.md b/docs/integrations/editors.md
index 83904144c48..7d056160fcb 100644
--- a/docs/integrations/editors.md
+++ b/docs/integrations/editors.md
@@ -391,7 +391,7 @@ close and reopen your File, _Black_ will be done with its job.
 
 - Use the
   [Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python)
-  ([instructions](https://code.visualstudio.com/docs/python/editing#_formatting)).
+  ([instructions](https://code.visualstudio.com/docs/python/formatting)).
 
 - Alternatively the pre-release
   [Black Formatter](https://marketplace.visualstudio.com/items?itemName=ms-python.black-formatter)

From 27c05e1e24e02c62d0c2de2a1ab0673b2c2ca653 Mon Sep 17 00:00:00 2001
From: John Litborn <11260241+jakkdl@users.noreply.github.com>
Date: Fri, 6 Oct 2023 03:15:35 +0200
Subject: [PATCH 0872/1034] exclude tests/data/.* from mypy (#3917)

---
 mypy.ini | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/mypy.ini b/mypy.ini
index 95ec22d65be..ad916185bce 100644
--- a/mypy.ini
+++ b/mypy.ini
@@ -39,3 +39,8 @@ ignore_missing_imports = True
 
 [mypy-_black_version.*]
 ignore_missing_imports = True
+
+# CI only checks src/, but in case users are running LSP or similar we explicitly ignore
+# errors in test data files.
+[mypy-tests.data.*]
+ignore_errors = True

From 3a2d76c7bcf39e852f3b379b76537d7847ed4225 Mon Sep 17 00:00:00 2001
From: David Lev <42866208+david-lev@users.noreply.github.com>
Date: Fri, 6 Oct 2023 04:21:56 +0300
Subject: [PATCH 0873/1034] =?UTF-8?q?Remove=20`$`,=20`>>>`=20and=20other?=
 =?UTF-8?q?=20prompt=20prefixes=20when=20code=20copied=20from=20the?=
 =?UTF-8?q?=E2=80=A6=20(#3884)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adding configurations for sphinx-copybutton in conf.py
https://sphinx-copybutton.readthedocs.io/en/latest/use.html#using-regexp-prompt-identifiers
---
 docs/conf.py | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/docs/conf.py b/docs/conf.py
index f7cf1b42842..6b645435325 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -210,6 +210,13 @@ def make_pypi_svg(version: str) -> None:
 
 autodoc_member_order = "bysource"
 
+#  -- sphinx-copybutton configuration ----------------------------------------
+copybutton_prompt_text = (
+    r">>> |\.\.\. |> |\$ |\# | In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "
+)
+copybutton_prompt_is_regexp = True
+copybutton_remove_prompts = True
+
 # -- Options for intersphinx extension ---------------------------------------
 
 # Example configuration for intersphinx: refer to the Python standard library.

From 3457ec48af0f4c481cdf35f280998bde3f484efd Mon Sep 17 00:00:00 2001
From: Cristiano Salerno <119511125+csalerno-asml@users.noreply.github.com>
Date: Fri, 6 Oct 2023 19:41:36 +0200
Subject: [PATCH 0874/1034] Update output display to job summary (#3914)

* Update output display to job summary

* fix: handled exit-code of script

* added changelog message
---
 CHANGES.md |  2 ++
 action.yml | 18 ++++++++++++++++--
 2 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 888824ee055..062a195717d 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -48,6 +48,8 @@
 
 <!-- For example, Docker, GitHub Actions, pre-commit, editors -->
 
+- The action output displayed in the job summary is now wrapped in Markdown (#3914)
+
 ### Documentation
 
 <!-- Major changes to documentation and policies. Small docs changes
diff --git a/action.yml b/action.yml
index 282fca43dea..8b698ae3c80 100644
--- a/action.yml
+++ b/action.yml
@@ -36,10 +36,24 @@ runs:
     - name: black
       run: |
         if [ "$RUNNER_OS" == "Windows" ]; then
-          python $GITHUB_ACTION_PATH/action/main.py | tee -a $GITHUB_STEP_SUMMARY
+          runner="python"
         else
-          python3 $GITHUB_ACTION_PATH/action/main.py | tee -a $GITHUB_STEP_SUMMARY
+          runner="python3"
         fi
+
+        out=$(${runner} $GITHUB_ACTION_PATH/action/main.py)
+        exit_code=$?
+
+        # 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
+
+        # Exit with the exit-code returned by Black
+        exit ${exit_code}
       env:
         # TODO: Remove once https://github.com/actions/runner/issues/665 is fixed.
         INPUT_OPTIONS: ${{ inputs.options }}

From 738c2789cc07dbbd6bcf5908fd06627ee8d5cd6c Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Fri, 6 Oct 2023 11:39:20 -0700
Subject: [PATCH 0875/1034] Set Docker to use 3.11 for now (#3927)

Until we get new aiohttp wheels we need to build with 3.11.
You can see an example of a fail here:

Workaround for #3919 - Will leave it open until we can move to 3.21
---
 Dockerfile | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Dockerfile b/Dockerfile
index 4e8f12f9798..a9e0ea5081e 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -1,4 +1,4 @@
-FROM python:3-slim AS builder
+FROM python:3.11-slim AS builder
 
 RUN mkdir /src
 COPY . /src/
@@ -10,7 +10,7 @@ RUN . /opt/venv/bin/activate && pip install --no-cache-dir --upgrade pip setupto
     && cd /src \
     && pip install --no-cache-dir .[colorama,d]
 
-FROM python:3-slim
+FROM python:3.11-slim
 
 # copy only Python packages to limit the image size
 COPY --from=builder /opt/venv /opt/venv

From a8f68f57fed6cd6bf585b10abd3cc84d37c2fd05 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 9 Oct 2023 07:00:49 -0700
Subject: [PATCH 0876/1034] Bump pypa/cibuildwheel from 2.16.1 to 2.16.2
 (#3934)

Bumps [pypa/cibuildwheel](https://github.com/pypa/cibuildwheel) from 2.16.1 to 2.16.2.
- [Release notes](https://github.com/pypa/cibuildwheel/releases)
- [Changelog](https://github.com/pypa/cibuildwheel/blob/main/docs/changelog.md)
- [Commits](https://github.com/pypa/cibuildwheel/compare/v2.16.1...v2.16.2)

---
updated-dependencies:
- dependency-name: pypa/cibuildwheel
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/pypi_upload.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/pypi_upload.yml b/.github/workflows/pypi_upload.yml
index 41ab6460793..a57013d67c1 100644
--- a/.github/workflows/pypi_upload.yml
+++ b/.github/workflows/pypi_upload.yml
@@ -88,7 +88,7 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
-      - uses: pypa/cibuildwheel@v2.16.1
+      - uses: pypa/cibuildwheel@v2.16.2
         with:
           only: ${{ matrix.only }}
 

From 715f60c11bc12d8d6ffedded90c2b9a6a1b6a287 Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Mon, 9 Oct 2023 07:02:49 -0700
Subject: [PATCH 0877/1034] Drop support for parsing Python 2 (#3933)

---
 CHANGES.md               |  3 +++
 src/black/parsing.py     | 22 +++++----------------
 src/blib2to3/Grammar.txt |  7 ++-----
 src/blib2to3/pygram.py   | 41 ++++++++++------------------------------
 tests/test_format.py     |  6 ------
 5 files changed, 20 insertions(+), 59 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 062a195717d..ffc63b3287d 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -40,6 +40,9 @@
 
 <!-- Changes to Black's terminal output and error messages -->
 
+- Black no longer attempts to provide special errors for attempting to format Python 2
+  code (#3933)
+
 ### _Blackd_
 
 <!-- Changes to blackd -->
diff --git a/src/black/parsing.py b/src/black/parsing.py
index e98e019cac6..03e767a333b 100644
--- a/src/black/parsing.py
+++ b/src/black/parsing.py
@@ -3,7 +3,7 @@
 """
 import ast
 import sys
-from typing import Final, Iterable, Iterator, List, Set, Tuple
+from typing import Iterable, Iterator, List, Set, Tuple
 
 from black.mode import VERSION_TO_FEATURES, Feature, TargetVersion, supports_feature
 from black.nodes import syms
@@ -14,8 +14,6 @@
 from blib2to3.pgen2.tokenize import TokenError
 from blib2to3.pytree import Leaf, Node
 
-PY2_HINT: Final = "Python 2 support was removed in version 22.0."
-
 
 class InvalidInput(ValueError):
     """Raised when input source code fails all parse attempts."""
@@ -26,9 +24,9 @@ def get_grammars(target_versions: Set[TargetVersion]) -> List[Grammar]:
         # No target_version specified, so try all grammars.
         return [
             # Python 3.7-3.9
-            pygram.python_grammar_no_print_statement_no_exec_statement_async_keywords,
+            pygram.python_grammar_async_keywords,
             # Python 3.0-3.6
-            pygram.python_grammar_no_print_statement_no_exec_statement,
+            pygram.python_grammar,
             # Python 3.10+
             pygram.python_grammar_soft_keywords,
         ]
@@ -39,12 +37,10 @@ def get_grammars(target_versions: Set[TargetVersion]) -> List[Grammar]:
         target_versions, Feature.ASYNC_IDENTIFIERS
     ) and not supports_feature(target_versions, Feature.PATTERN_MATCHING):
         # Python 3.7-3.9
-        grammars.append(
-            pygram.python_grammar_no_print_statement_no_exec_statement_async_keywords
-        )
+        grammars.append(pygram.python_grammar_async_keywords)
     if not supports_feature(target_versions, Feature.ASYNC_KEYWORDS):
         # Python 3.0-3.6
-        grammars.append(pygram.python_grammar_no_print_statement_no_exec_statement)
+        grammars.append(pygram.python_grammar)
     if any(Feature.PATTERN_MATCHING in VERSION_TO_FEATURES[v] for v in target_versions):
         # Python 3.10+
         grammars.append(pygram.python_grammar_soft_keywords)
@@ -89,14 +85,6 @@ def lib2to3_parse(src_txt: str, target_versions: Iterable[TargetVersion] = ()) -
         # Choose the latest version when raising the actual parsing error.
         assert len(errors) >= 1
         exc = errors[max(errors)]
-
-        if matches_grammar(src_txt, pygram.python_grammar) or matches_grammar(
-            src_txt, pygram.python_grammar_no_print_statement
-        ):
-            original_msg = exc.args[0]
-            msg = f"{original_msg}\n{PY2_HINT}"
-            raise InvalidInput(msg) from None
-
         raise exc from None
 
     if isinstance(result, Leaf):
diff --git a/src/blib2to3/Grammar.txt b/src/blib2to3/Grammar.txt
index e48e66363fb..be91df75740 100644
--- a/src/blib2to3/Grammar.txt
+++ b/src/blib2to3/Grammar.txt
@@ -80,8 +80,8 @@ vfplist: vfpdef (',' vfpdef)* [',']
 
 stmt: simple_stmt | compound_stmt
 simple_stmt: small_stmt (';' small_stmt)* [';'] NEWLINE
-small_stmt: (type_stmt | expr_stmt | print_stmt  | del_stmt | pass_stmt | flow_stmt |
-             import_stmt | global_stmt | exec_stmt | assert_stmt)
+small_stmt: (type_stmt | expr_stmt | del_stmt | pass_stmt | flow_stmt |
+             import_stmt | global_stmt | assert_stmt)
 expr_stmt: testlist_star_expr (annassign | augassign (yield_expr|testlist) |
                      ('=' (yield_expr|testlist_star_expr))*)
 annassign: ':' test ['=' (yield_expr|testlist_star_expr)]
@@ -89,8 +89,6 @@ testlist_star_expr: (test|star_expr) (',' (test|star_expr))* [',']
 augassign: ('+=' | '-=' | '*=' | '@=' | '/=' | '%=' | '&=' | '|=' | '^=' |
             '<<=' | '>>=' | '**=' | '//=')
 # For normal and annotated assignments, additional restrictions enforced by the interpreter
-print_stmt: 'print' ( [ test (',' test)* [','] ] |
-                      '>>' test [ (',' test)+ [','] ] )
 del_stmt: 'del' exprlist
 pass_stmt: 'pass'
 flow_stmt: break_stmt | continue_stmt | return_stmt | raise_stmt | yield_stmt
@@ -109,7 +107,6 @@ import_as_names: import_as_name (',' import_as_name)* [',']
 dotted_as_names: dotted_as_name (',' dotted_as_name)*
 dotted_name: NAME ('.' NAME)*
 global_stmt: ('global' | 'nonlocal') NAME (',' NAME)*
-exec_stmt: 'exec' expr ['in' test [',' test]]
 assert_stmt: 'assert' test [',' test]
 type_stmt: "type" NAME [typeparams] '=' expr
 
diff --git a/src/blib2to3/pygram.py b/src/blib2to3/pygram.py
index c30c630e816..2b43b4c112b 100644
--- a/src/blib2to3/pygram.py
+++ b/src/blib2to3/pygram.py
@@ -63,7 +63,6 @@ class _python_symbols(Symbols):
     encoding_decl: int
     eval_input: int
     except_clause: int
-    exec_stmt: int
     expr: int
     expr_stmt: int
     exprlist: int
@@ -97,7 +96,6 @@ class _python_symbols(Symbols):
     pattern: int
     patterns: int
     power: int
-    print_stmt: int
     raise_stmt: int
     return_stmt: int
     shift_expr: int
@@ -153,22 +151,16 @@ class _pattern_symbols(Symbols):
 
 
 python_grammar: Grammar
-python_grammar_no_print_statement: Grammar
-python_grammar_no_print_statement_no_exec_statement: Grammar
-python_grammar_no_print_statement_no_exec_statement_async_keywords: Grammar
-python_grammar_no_exec_statement: Grammar
-pattern_grammar: Grammar
+python_grammar_async_keywords: Grammar
 python_grammar_soft_keywords: Grammar
-
+pattern_grammar: Grammar
 python_symbols: _python_symbols
 pattern_symbols: _pattern_symbols
 
 
 def initialize(cache_dir: Union[str, "os.PathLike[str]", None] = None) -> None:
     global python_grammar
-    global python_grammar_no_print_statement
-    global python_grammar_no_print_statement_no_exec_statement
-    global python_grammar_no_print_statement_no_exec_statement_async_keywords
+    global python_grammar_async_keywords
     global python_grammar_soft_keywords
     global python_symbols
     global pattern_grammar
@@ -180,38 +172,25 @@ def initialize(cache_dir: Union[str, "os.PathLike[str]", None] = None) -> None:
         os.path.dirname(__file__), "PatternGrammar.txt"
     )
 
-    # Python 2
     python_grammar = driver.load_packaged_grammar("blib2to3", _GRAMMAR_FILE, cache_dir)
-    python_grammar.version = (2, 0)
+    assert "print" not in python_grammar.keywords
+    assert "exec" not in python_grammar.keywords
 
     soft_keywords = python_grammar.soft_keywords.copy()
     python_grammar.soft_keywords.clear()
 
     python_symbols = _python_symbols(python_grammar)
 
-    # Python 2 + from __future__ import print_function
-    python_grammar_no_print_statement = python_grammar.copy()
-    del python_grammar_no_print_statement.keywords["print"]
-
     # Python 3.0-3.6
-    python_grammar_no_print_statement_no_exec_statement = python_grammar.copy()
-    del python_grammar_no_print_statement_no_exec_statement.keywords["print"]
-    del python_grammar_no_print_statement_no_exec_statement.keywords["exec"]
-    python_grammar_no_print_statement_no_exec_statement.version = (3, 0)
+    python_grammar.version = (3, 0)
 
     # Python 3.7+
-    python_grammar_no_print_statement_no_exec_statement_async_keywords = (
-        python_grammar_no_print_statement_no_exec_statement.copy()
-    )
-    python_grammar_no_print_statement_no_exec_statement_async_keywords.async_keywords = (
-        True
-    )
-    python_grammar_no_print_statement_no_exec_statement_async_keywords.version = (3, 7)
+    python_grammar_async_keywords = python_grammar.copy()
+    python_grammar_async_keywords.async_keywords = True
+    python_grammar_async_keywords.version = (3, 7)
 
     # Python 3.10+
-    python_grammar_soft_keywords = (
-        python_grammar_no_print_statement_no_exec_statement_async_keywords.copy()
-    )
+    python_grammar_soft_keywords = python_grammar_async_keywords.copy()
     python_grammar_soft_keywords.soft_keywords = soft_keywords
     python_grammar_soft_keywords.version = (3, 10)
 
diff --git a/tests/test_format.py b/tests/test_format.py
index f3db423b637..ff358d59c94 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -155,12 +155,6 @@ def test_fast_cases(filename: str) -> None:
     assert_format(source, expected, fast=True)
 
 
-def test_python_2_hint() -> None:
-    with pytest.raises(black.parsing.InvalidInput) as exc_info:
-        assert_format("print 'daylily'", "print 'daylily'")
-    exc_info.match(black.parsing.PY2_HINT)
-
-
 @pytest.mark.filterwarnings("ignore:invalid escape sequence.*:DeprecationWarning")
 def test_docstring_no_string_normalization() -> None:
     """Like test_docstring but with string normalization off."""

From a69bda3b9bde208d5489eb2e37fc982b6bc1d8df Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Mon, 9 Oct 2023 18:43:47 -0700
Subject: [PATCH 0878/1034] Use inline flags for test cases (#3931)

Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
---
 docs/contributing/the_basics.md               |  21 +-
 .../attribute_access_on_number_literals.py    |   0
 .../beginning_backslash.py                    |   0
 .../{simple_cases => cases}/bracketmatch.py   |   0
 .../class_blank_parentheses.py                |   0
 .../class_methods_new_line.py                 |   0
 .../{simple_cases => cases}/collections.py    |   0
 .../comment_after_escaped_newline.py          |   0
 .../data/{simple_cases => cases}/comments.py  |   0
 .../data/{simple_cases => cases}/comments2.py |   0
 .../data/{simple_cases => cases}/comments3.py |   0
 .../data/{simple_cases => cases}/comments4.py |   0
 .../data/{simple_cases => cases}/comments5.py |   0
 .../data/{simple_cases => cases}/comments6.py |   0
 .../data/{simple_cases => cases}/comments8.py |   0
 .../data/{simple_cases => cases}/comments9.py |   0
 .../comments_non_breaking_space.py            |   0
 .../{simple_cases => cases}/composition.py    |   0
 .../composition_no_trailing_comma.py          |   0
 .../data/{simple_cases => cases}/docstring.py |   0
 ...ocstring_no_extra_empty_line_before_eof.py |   0
 .../docstring_no_string_normalization.py      |   1 +
 .../docstring_preview.py                      |   0
 ...cstring_preview_no_string_normalization.py |   1 +
 .../{simple_cases => cases}/empty_lines.py    |   0
 .../{simple_cases => cases}/expression.diff   |   0
 .../{simple_cases => cases}/expression.py     |   0
 .../data/{simple_cases => cases}/fmtonoff.py  |   0
 .../data/{simple_cases => cases}/fmtonoff2.py |   0
 .../data/{simple_cases => cases}/fmtonoff3.py |   0
 .../data/{simple_cases => cases}/fmtonoff4.py |   0
 .../data/{simple_cases => cases}/fmtonoff5.py |   0
 .../fmtpass_imports.py                        |   0
 tests/data/{simple_cases => cases}/fmtskip.py |   0
 .../data/{simple_cases => cases}/fmtskip2.py  |   0
 .../data/{simple_cases => cases}/fmtskip3.py  |   0
 .../data/{simple_cases => cases}/fmtskip4.py  |   0
 .../data/{simple_cases => cases}/fmtskip5.py  |   0
 .../data/{simple_cases => cases}/fmtskip6.py  |   0
 .../data/{simple_cases => cases}/fmtskip7.py  |   0
 .../data/{simple_cases => cases}/fmtskip8.py  |   0
 tests/data/{simple_cases => cases}/fstring.py |   0
 .../funcdef_return_type_trailing_comma.py     |   1 +
 .../data/{simple_cases => cases}/function.py  |   0
 .../data/{simple_cases => cases}/function2.py |   0
 .../function_trailing_comma.py                |   0
 .../{simple_cases => cases}/ignore_pyi.py     |   1 +
 .../{simple_cases => cases}/import_spacing.py |   0
 .../{miscellaneous => cases}/linelength6.py   |   1 +
 .../long_strings_flag_disabled.py             |   0
 ...ine_consecutive_open_parentheses_ignore.py |   0
 .../nested_stub.pyi => cases/nested_stub.py}  |   1 +
 .../data/{py_36 => cases}/numeric_literals.py |   5 -
 .../numeric_literals_skip_underscores.py      |   4 -
 .../one_element_subscript.py                  |   0
 .../parenthesized_context_managers.py         |   1 +
 .../pattern_matching_complex.py               |   1 +
 .../pattern_matching_extras.py                |   1 +
 .../pattern_matching_generic.py               |   1 +
 .../pattern_matching_simple.py                |   1 +
 .../pattern_matching_style.py                 |   1 +
 .../pep604_union_types_line_breaks.py         |   1 +
 tests/data/{py_38 => cases}/pep_570.py        |   1 +
 tests/data/{py_38 => cases}/pep_572.py        |   1 +
 .../pep_572_do_not_remove_parens.py           |   1 +
 tests/data/{py_310 => cases}/pep_572_py310.py |   1 +
 tests/data/{py_39 => cases}/pep_572_py39.py   |   1 +
 .../{py_38 => cases}/pep_572_remove_parens.py |   1 +
 tests/data/{simple_cases => cases}/pep_604.py |   0
 tests/data/{py_311 => cases}/pep_646.py       |   1 +
 tests/data/{py_311 => cases}/pep_654.py       |   1 +
 tests/data/{py_311 => cases}/pep_654_style.py |   1 +
 .../power_op_newline.py                       |   1 +
 .../power_op_spacing.py                       |   0
 .../prefer_rhs_split_reformatted.py           |   0
 .../preview_async_stmts.py}                   |   1 +
 .../cantfit.py => cases/preview_cantfit.py}   |   1 +
 .../preview_comments7.py}                     |   1 +
 .../preview_context_managers_38.py}           |   1 +
 .../preview_context_managers_39.py}           |   1 +
 ...review_context_managers_autodetect_310.py} |   1 +
 ...review_context_managers_autodetect_311.py} |   1 +
 ...preview_context_managers_autodetect_38.py} |   1 +
 ...preview_context_managers_autodetect_39.py} |   1 +
 .../preview_dummy_implementations.py}         |   1 +
 .../preview_format_unicode_escape_seq.py}     |   1 +
 .../preview_long_dict_values.py}              |   1 +
 .../preview_long_strings.py}                  |   1 +
 ...preview_long_strings__east_asian_width.py} |   1 +
 .../preview_long_strings__edge_case.py}       |   1 +
 .../preview_long_strings__regression.py}      |   1 +
 ...preview_long_strings__type_annotations.py} |   1 +
 .../preview_multiline_strings.py}             |   1 +
 ...preview_no_blank_line_before_docstring.py} |   1 +
 .../pep_572.py => cases/preview_pep_572.py}   |   1 +
 .../preview_percent_precedence.py}            |   1 +
 .../preview_prefer_rhs_split.py}              |   1 +
 ...view_return_annotation_brackets_string.py} |   1 +
 .../preview_trailing_comma.py}                |   1 +
 .../pep_572.py => cases/py310_pep572.py}      |   1 +
 tests/data/{py_37 => cases}/python37.py       |   5 +-
 tests/data/{py_38 => cases}/python38.py       |   5 +-
 tests/data/{py_39 => cases}/python39.py       |   6 +-
 .../remove_await_parens.py                    |   0
 .../remove_except_parens.py                   |   0
 .../remove_for_brackets.py                    |   0
 .../remove_newline_after_code_block_open.py   |   0
 .../remove_newline_after_match.py             |   1 +
 .../{simple_cases => cases}/remove_parens.py  |   0
 .../{py_39 => cases}/remove_with_brackets.py  |   1 +
 .../return_annotation_brackets.py             |   0
 .../skip_magic_trailing_comma.py              |   1 +
 tests/data/{simple_cases => cases}/slices.py  |   0
 .../{py_310 => cases}/starred_for_target.py   |   1 +
 .../string_prefixes.py                        |   0
 .../{miscellaneous/stub.pyi => cases/stub.py} |   1 +
 tests/data/{simple_cases => cases}/torture.py |   0
 .../trailing_comma_optional_parens1.py        |   0
 .../trailing_comma_optional_parens2.py        |   0
 .../trailing_comma_optional_parens3.py        |   0
 .../trailing_commas_in_leading_parts.py       |   0
 .../tricky_unicode_symbols.py                 |   0
 .../{simple_cases => cases}/tupleassign.py    |   0
 tests/data/{py_312 => cases}/type_aliases.py  |   1 +
 .../type_comment_syntax_error.py              |   0
 tests/data/{py_312 => cases}/type_params.py   |   1 +
 .../{simple_cases => cases}/whitespace.py     |   0
 tests/data/miscellaneous/force_pyi.py         |   1 +
 tests/test_black.py                           |  42 ++--
 tests/test_blackd.py                          |   2 +-
 tests/test_format.py                          | 194 ++----------------
 tests/util.py                                 |  86 +++++++-
 132 files changed, 206 insertions(+), 220 deletions(-)
 rename tests/data/{simple_cases => cases}/attribute_access_on_number_literals.py (100%)
 rename tests/data/{simple_cases => cases}/beginning_backslash.py (100%)
 rename tests/data/{simple_cases => cases}/bracketmatch.py (100%)
 rename tests/data/{simple_cases => cases}/class_blank_parentheses.py (100%)
 rename tests/data/{simple_cases => cases}/class_methods_new_line.py (100%)
 rename tests/data/{simple_cases => cases}/collections.py (100%)
 rename tests/data/{simple_cases => cases}/comment_after_escaped_newline.py (100%)
 rename tests/data/{simple_cases => cases}/comments.py (100%)
 rename tests/data/{simple_cases => cases}/comments2.py (100%)
 rename tests/data/{simple_cases => cases}/comments3.py (100%)
 rename tests/data/{simple_cases => cases}/comments4.py (100%)
 rename tests/data/{simple_cases => cases}/comments5.py (100%)
 rename tests/data/{simple_cases => cases}/comments6.py (100%)
 rename tests/data/{simple_cases => cases}/comments8.py (100%)
 rename tests/data/{simple_cases => cases}/comments9.py (100%)
 rename tests/data/{simple_cases => cases}/comments_non_breaking_space.py (100%)
 rename tests/data/{simple_cases => cases}/composition.py (100%)
 rename tests/data/{simple_cases => cases}/composition_no_trailing_comma.py (100%)
 rename tests/data/{simple_cases => cases}/docstring.py (100%)
 rename tests/data/{simple_cases => cases}/docstring_no_extra_empty_line_before_eof.py (100%)
 rename tests/data/{miscellaneous => cases}/docstring_no_string_normalization.py (98%)
 rename tests/data/{simple_cases => cases}/docstring_preview.py (100%)
 rename tests/data/{miscellaneous => cases}/docstring_preview_no_string_normalization.py (88%)
 rename tests/data/{simple_cases => cases}/empty_lines.py (100%)
 rename tests/data/{simple_cases => cases}/expression.diff (100%)
 rename tests/data/{simple_cases => cases}/expression.py (100%)
 rename tests/data/{simple_cases => cases}/fmtonoff.py (100%)
 rename tests/data/{simple_cases => cases}/fmtonoff2.py (100%)
 rename tests/data/{simple_cases => cases}/fmtonoff3.py (100%)
 rename tests/data/{simple_cases => cases}/fmtonoff4.py (100%)
 rename tests/data/{simple_cases => cases}/fmtonoff5.py (100%)
 rename tests/data/{simple_cases => cases}/fmtpass_imports.py (100%)
 rename tests/data/{simple_cases => cases}/fmtskip.py (100%)
 rename tests/data/{simple_cases => cases}/fmtskip2.py (100%)
 rename tests/data/{simple_cases => cases}/fmtskip3.py (100%)
 rename tests/data/{simple_cases => cases}/fmtskip4.py (100%)
 rename tests/data/{simple_cases => cases}/fmtskip5.py (100%)
 rename tests/data/{simple_cases => cases}/fmtskip6.py (100%)
 rename tests/data/{simple_cases => cases}/fmtskip7.py (100%)
 rename tests/data/{simple_cases => cases}/fmtskip8.py (100%)
 rename tests/data/{simple_cases => cases}/fstring.py (100%)
 rename tests/data/{preview_py_310 => cases}/funcdef_return_type_trailing_comma.py (99%)
 rename tests/data/{simple_cases => cases}/function.py (100%)
 rename tests/data/{simple_cases => cases}/function2.py (100%)
 rename tests/data/{simple_cases => cases}/function_trailing_comma.py (100%)
 rename tests/data/{simple_cases => cases}/ignore_pyi.py (97%)
 rename tests/data/{simple_cases => cases}/import_spacing.py (100%)
 rename tests/data/{miscellaneous => cases}/linelength6.py (80%)
 rename tests/data/{miscellaneous => cases}/long_strings_flag_disabled.py (100%)
 rename tests/data/{simple_cases => cases}/multiline_consecutive_open_parentheses_ignore.py (100%)
 rename tests/data/{miscellaneous/nested_stub.pyi => cases/nested_stub.py} (97%)
 rename tests/data/{py_36 => cases}/numeric_literals.py (91%)
 rename tests/data/{py_36 => cases}/numeric_literals_skip_underscores.py (80%)
 rename tests/data/{simple_cases => cases}/one_element_subscript.py (100%)
 rename tests/data/{py_310 => cases}/parenthesized_context_managers.py (95%)
 rename tests/data/{py_310 => cases}/pattern_matching_complex.py (98%)
 rename tests/data/{py_310 => cases}/pattern_matching_extras.py (98%)
 rename tests/data/{py_310 => cases}/pattern_matching_generic.py (98%)
 rename tests/data/{py_310 => cases}/pattern_matching_simple.py (98%)
 rename tests/data/{py_310 => cases}/pattern_matching_style.py (97%)
 rename tests/data/{preview_py_310 => cases}/pep604_union_types_line_breaks.py (99%)
 rename tests/data/{py_38 => cases}/pep_570.py (95%)
 rename tests/data/{py_38 => cases}/pep_572.py (96%)
 rename tests/data/{fast => cases}/pep_572_do_not_remove_parens.py (96%)
 rename tests/data/{py_310 => cases}/pep_572_py310.py (93%)
 rename tests/data/{py_39 => cases}/pep_572_py39.py (89%)
 rename tests/data/{py_38 => cases}/pep_572_remove_parens.py (98%)
 rename tests/data/{simple_cases => cases}/pep_604.py (100%)
 rename tests/data/{py_311 => cases}/pep_646.py (98%)
 rename tests/data/{py_311 => cases}/pep_654.py (96%)
 rename tests/data/{py_311 => cases}/pep_654_style.py (98%)
 rename tests/data/{miscellaneous => cases}/power_op_newline.py (73%)
 rename tests/data/{simple_cases => cases}/power_op_spacing.py (100%)
 rename tests/data/{simple_cases => cases}/prefer_rhs_split_reformatted.py (100%)
 rename tests/data/{preview/async_stmts.py => cases/preview_async_stmts.py} (93%)
 rename tests/data/{preview/cantfit.py => cases/preview_cantfit.py} (99%)
 rename tests/data/{preview/comments7.py => cases/preview_comments7.py} (99%)
 rename tests/data/{preview_context_managers/targeting_py38.py => cases/preview_context_managers_38.py} (96%)
 rename tests/data/{preview_context_managers/targeting_py39.py => cases/preview_context_managers_39.py} (98%)
 rename tests/data/{preview_context_managers/auto_detect/features_3_10.py => cases/preview_context_managers_autodetect_310.py} (93%)
 rename tests/data/{preview_context_managers/auto_detect/features_3_11.py => cases/preview_context_managers_autodetect_311.py} (92%)
 rename tests/data/{preview_context_managers/auto_detect/features_3_8.py => cases/preview_context_managers_autodetect_38.py} (98%)
 rename tests/data/{preview_context_managers/auto_detect/features_3_9.py => cases/preview_context_managers_autodetect_39.py} (93%)
 rename tests/data/{preview/dummy_implementations.py => cases/preview_dummy_implementations.py} (98%)
 rename tests/data/{preview/format_unicode_escape_seq.py => cases/preview_format_unicode_escape_seq.py} (96%)
 rename tests/data/{preview/long_dict_values.py => cases/preview_long_dict_values.py} (99%)
 rename tests/data/{preview/long_strings.py => cases/preview_long_strings.py} (99%)
 rename tests/data/{preview/long_strings__east_asian_width.py => cases/preview_long_strings__east_asian_width.py} (96%)
 rename tests/data/{preview/long_strings__edge_case.py => cases/preview_long_strings__edge_case.py} (99%)
 rename tests/data/{preview/long_strings__regression.py => cases/preview_long_strings__regression.py} (99%)
 rename tests/data/{preview/long_strings__type_annotations.py => cases/preview_long_strings__type_annotations.py} (98%)
 rename tests/data/{preview/multiline_strings.py => cases/preview_multiline_strings.py} (99%)
 rename tests/data/{preview/no_blank_line_before_docstring.py => cases/preview_no_blank_line_before_docstring.py} (97%)
 rename tests/data/{preview/pep_572.py => cases/preview_pep_572.py} (75%)
 rename tests/data/{preview/percent_precedence.py => cases/preview_percent_precedence.py} (96%)
 rename tests/data/{preview/prefer_rhs_split.py => cases/preview_prefer_rhs_split.py} (99%)
 rename tests/data/{preview/return_annotation_brackets_string.py => cases/preview_return_annotation_brackets_string.py} (97%)
 rename tests/data/{preview/trailing_comma.py => cases/preview_trailing_comma.py} (97%)
 rename tests/data/{preview_py_310/pep_572.py => cases/py310_pep572.py} (77%)
 rename tests/data/{py_37 => cases}/python37.py (95%)
 rename tests/data/{py_38 => cases}/python38.py (93%)
 rename tests/data/{py_39 => cases}/python39.py (92%)
 rename tests/data/{simple_cases => cases}/remove_await_parens.py (100%)
 rename tests/data/{simple_cases => cases}/remove_except_parens.py (100%)
 rename tests/data/{simple_cases => cases}/remove_for_brackets.py (100%)
 rename tests/data/{simple_cases => cases}/remove_newline_after_code_block_open.py (100%)
 rename tests/data/{py_310 => cases}/remove_newline_after_match.py (94%)
 rename tests/data/{simple_cases => cases}/remove_parens.py (100%)
 rename tests/data/{py_39 => cases}/remove_with_brackets.py (98%)
 rename tests/data/{simple_cases => cases}/return_annotation_brackets.py (100%)
 rename tests/data/{simple_cases => cases}/skip_magic_trailing_comma.py (97%)
 rename tests/data/{simple_cases => cases}/slices.py (100%)
 rename tests/data/{py_310 => cases}/starred_for_target.py (92%)
 rename tests/data/{simple_cases => cases}/string_prefixes.py (100%)
 rename tests/data/{miscellaneous/stub.pyi => cases/stub.py} (99%)
 rename tests/data/{simple_cases => cases}/torture.py (100%)
 rename tests/data/{simple_cases => cases}/trailing_comma_optional_parens1.py (100%)
 rename tests/data/{simple_cases => cases}/trailing_comma_optional_parens2.py (100%)
 rename tests/data/{simple_cases => cases}/trailing_comma_optional_parens3.py (100%)
 rename tests/data/{simple_cases => cases}/trailing_commas_in_leading_parts.py (100%)
 rename tests/data/{simple_cases => cases}/tricky_unicode_symbols.py (100%)
 rename tests/data/{simple_cases => cases}/tupleassign.py (100%)
 rename tests/data/{py_312 => cases}/type_aliases.py (81%)
 rename tests/data/{type_comments => cases}/type_comment_syntax_error.py (100%)
 rename tests/data/{py_312 => cases}/type_params.py (97%)
 rename tests/data/{simple_cases => cases}/whitespace.py (100%)

diff --git a/docs/contributing/the_basics.md b/docs/contributing/the_basics.md
index 864894b491f..bc1680eecfd 100644
--- a/docs/contributing/the_basics.md
+++ b/docs/contributing/the_basics.md
@@ -58,7 +58,26 @@ Further examples of invoking the tests
 (.venv)$ tox -e py -- --print-tree-diff=False
 ```
 
-`Black` has two pytest command-line options affecting test files in `tests/data/` that
+### Testing
+
+All aspects of the _Black_ style should be tested. Normally, tests should be created as
+files in the `tests/data/cases` directory. These files consist of up to three parts:
+
+- A line that starts with `# flags: ` followed by a set of command-line options. For
+  example, if the line is `# flags: --preview --skip-magic-trailing-comma`, the test
+  case will be run with preview mode on and the magic trailing comma off. The options
+  accepted are mostly a subset of those of _Black_ itself, except for the
+  `--minimum-version=` flag, which should be used when testing a grammar feature that
+  works only in newer versions of Python. This flag ensures that we don't try to
+  validate the AST on older versions and tests that we autodetect the Python version
+  correctly when the feature is used. For the exact flags accepted, see the function
+  `get_flags_parser` in `tests/util.py`. If this line is omitted, the default options
+  are used.
+- A block of Python code used as input for the formatter.
+- The line `# output`, followed by the output of _Black_ when run on the previous block.
+  If this is omitted, the test asserts that _Black_ will leave the input code unchanged.
+
+_Black_ has two pytest command-line options affecting test files in `tests/data/` that
 are split into an input part, and an output part, separated by a line with`# output`.
 These can be passed to `pytest` through `tox`, or directly into pytest if not using
 `tox`.
diff --git a/tests/data/simple_cases/attribute_access_on_number_literals.py b/tests/data/cases/attribute_access_on_number_literals.py
similarity index 100%
rename from tests/data/simple_cases/attribute_access_on_number_literals.py
rename to tests/data/cases/attribute_access_on_number_literals.py
diff --git a/tests/data/simple_cases/beginning_backslash.py b/tests/data/cases/beginning_backslash.py
similarity index 100%
rename from tests/data/simple_cases/beginning_backslash.py
rename to tests/data/cases/beginning_backslash.py
diff --git a/tests/data/simple_cases/bracketmatch.py b/tests/data/cases/bracketmatch.py
similarity index 100%
rename from tests/data/simple_cases/bracketmatch.py
rename to tests/data/cases/bracketmatch.py
diff --git a/tests/data/simple_cases/class_blank_parentheses.py b/tests/data/cases/class_blank_parentheses.py
similarity index 100%
rename from tests/data/simple_cases/class_blank_parentheses.py
rename to tests/data/cases/class_blank_parentheses.py
diff --git a/tests/data/simple_cases/class_methods_new_line.py b/tests/data/cases/class_methods_new_line.py
similarity index 100%
rename from tests/data/simple_cases/class_methods_new_line.py
rename to tests/data/cases/class_methods_new_line.py
diff --git a/tests/data/simple_cases/collections.py b/tests/data/cases/collections.py
similarity index 100%
rename from tests/data/simple_cases/collections.py
rename to tests/data/cases/collections.py
diff --git a/tests/data/simple_cases/comment_after_escaped_newline.py b/tests/data/cases/comment_after_escaped_newline.py
similarity index 100%
rename from tests/data/simple_cases/comment_after_escaped_newline.py
rename to tests/data/cases/comment_after_escaped_newline.py
diff --git a/tests/data/simple_cases/comments.py b/tests/data/cases/comments.py
similarity index 100%
rename from tests/data/simple_cases/comments.py
rename to tests/data/cases/comments.py
diff --git a/tests/data/simple_cases/comments2.py b/tests/data/cases/comments2.py
similarity index 100%
rename from tests/data/simple_cases/comments2.py
rename to tests/data/cases/comments2.py
diff --git a/tests/data/simple_cases/comments3.py b/tests/data/cases/comments3.py
similarity index 100%
rename from tests/data/simple_cases/comments3.py
rename to tests/data/cases/comments3.py
diff --git a/tests/data/simple_cases/comments4.py b/tests/data/cases/comments4.py
similarity index 100%
rename from tests/data/simple_cases/comments4.py
rename to tests/data/cases/comments4.py
diff --git a/tests/data/simple_cases/comments5.py b/tests/data/cases/comments5.py
similarity index 100%
rename from tests/data/simple_cases/comments5.py
rename to tests/data/cases/comments5.py
diff --git a/tests/data/simple_cases/comments6.py b/tests/data/cases/comments6.py
similarity index 100%
rename from tests/data/simple_cases/comments6.py
rename to tests/data/cases/comments6.py
diff --git a/tests/data/simple_cases/comments8.py b/tests/data/cases/comments8.py
similarity index 100%
rename from tests/data/simple_cases/comments8.py
rename to tests/data/cases/comments8.py
diff --git a/tests/data/simple_cases/comments9.py b/tests/data/cases/comments9.py
similarity index 100%
rename from tests/data/simple_cases/comments9.py
rename to tests/data/cases/comments9.py
diff --git a/tests/data/simple_cases/comments_non_breaking_space.py b/tests/data/cases/comments_non_breaking_space.py
similarity index 100%
rename from tests/data/simple_cases/comments_non_breaking_space.py
rename to tests/data/cases/comments_non_breaking_space.py
diff --git a/tests/data/simple_cases/composition.py b/tests/data/cases/composition.py
similarity index 100%
rename from tests/data/simple_cases/composition.py
rename to tests/data/cases/composition.py
diff --git a/tests/data/simple_cases/composition_no_trailing_comma.py b/tests/data/cases/composition_no_trailing_comma.py
similarity index 100%
rename from tests/data/simple_cases/composition_no_trailing_comma.py
rename to tests/data/cases/composition_no_trailing_comma.py
diff --git a/tests/data/simple_cases/docstring.py b/tests/data/cases/docstring.py
similarity index 100%
rename from tests/data/simple_cases/docstring.py
rename to tests/data/cases/docstring.py
diff --git a/tests/data/simple_cases/docstring_no_extra_empty_line_before_eof.py b/tests/data/cases/docstring_no_extra_empty_line_before_eof.py
similarity index 100%
rename from tests/data/simple_cases/docstring_no_extra_empty_line_before_eof.py
rename to tests/data/cases/docstring_no_extra_empty_line_before_eof.py
diff --git a/tests/data/miscellaneous/docstring_no_string_normalization.py b/tests/data/cases/docstring_no_string_normalization.py
similarity index 98%
rename from tests/data/miscellaneous/docstring_no_string_normalization.py
rename to tests/data/cases/docstring_no_string_normalization.py
index a90b578f09a..4ec6b8a0153 100644
--- a/tests/data/miscellaneous/docstring_no_string_normalization.py
+++ b/tests/data/cases/docstring_no_string_normalization.py
@@ -1,3 +1,4 @@
+# flags: --skip-string-normalization
 class ALonelyClass:
     '''
     A multiline class docstring.
diff --git a/tests/data/simple_cases/docstring_preview.py b/tests/data/cases/docstring_preview.py
similarity index 100%
rename from tests/data/simple_cases/docstring_preview.py
rename to tests/data/cases/docstring_preview.py
diff --git a/tests/data/miscellaneous/docstring_preview_no_string_normalization.py b/tests/data/cases/docstring_preview_no_string_normalization.py
similarity index 88%
rename from tests/data/miscellaneous/docstring_preview_no_string_normalization.py
rename to tests/data/cases/docstring_preview_no_string_normalization.py
index 338cc01d33e..712c7364f51 100644
--- a/tests/data/miscellaneous/docstring_preview_no_string_normalization.py
+++ b/tests/data/cases/docstring_preview_no_string_normalization.py
@@ -1,3 +1,4 @@
+# flags: --preview --skip-string-normalization
 def do_not_touch_this_prefix():
     R"""There was a bug where docstring prefixes would be normalized even with -S."""
 
diff --git a/tests/data/simple_cases/empty_lines.py b/tests/data/cases/empty_lines.py
similarity index 100%
rename from tests/data/simple_cases/empty_lines.py
rename to tests/data/cases/empty_lines.py
diff --git a/tests/data/simple_cases/expression.diff b/tests/data/cases/expression.diff
similarity index 100%
rename from tests/data/simple_cases/expression.diff
rename to tests/data/cases/expression.diff
diff --git a/tests/data/simple_cases/expression.py b/tests/data/cases/expression.py
similarity index 100%
rename from tests/data/simple_cases/expression.py
rename to tests/data/cases/expression.py
diff --git a/tests/data/simple_cases/fmtonoff.py b/tests/data/cases/fmtonoff.py
similarity index 100%
rename from tests/data/simple_cases/fmtonoff.py
rename to tests/data/cases/fmtonoff.py
diff --git a/tests/data/simple_cases/fmtonoff2.py b/tests/data/cases/fmtonoff2.py
similarity index 100%
rename from tests/data/simple_cases/fmtonoff2.py
rename to tests/data/cases/fmtonoff2.py
diff --git a/tests/data/simple_cases/fmtonoff3.py b/tests/data/cases/fmtonoff3.py
similarity index 100%
rename from tests/data/simple_cases/fmtonoff3.py
rename to tests/data/cases/fmtonoff3.py
diff --git a/tests/data/simple_cases/fmtonoff4.py b/tests/data/cases/fmtonoff4.py
similarity index 100%
rename from tests/data/simple_cases/fmtonoff4.py
rename to tests/data/cases/fmtonoff4.py
diff --git a/tests/data/simple_cases/fmtonoff5.py b/tests/data/cases/fmtonoff5.py
similarity index 100%
rename from tests/data/simple_cases/fmtonoff5.py
rename to tests/data/cases/fmtonoff5.py
diff --git a/tests/data/simple_cases/fmtpass_imports.py b/tests/data/cases/fmtpass_imports.py
similarity index 100%
rename from tests/data/simple_cases/fmtpass_imports.py
rename to tests/data/cases/fmtpass_imports.py
diff --git a/tests/data/simple_cases/fmtskip.py b/tests/data/cases/fmtskip.py
similarity index 100%
rename from tests/data/simple_cases/fmtskip.py
rename to tests/data/cases/fmtskip.py
diff --git a/tests/data/simple_cases/fmtskip2.py b/tests/data/cases/fmtskip2.py
similarity index 100%
rename from tests/data/simple_cases/fmtskip2.py
rename to tests/data/cases/fmtskip2.py
diff --git a/tests/data/simple_cases/fmtskip3.py b/tests/data/cases/fmtskip3.py
similarity index 100%
rename from tests/data/simple_cases/fmtskip3.py
rename to tests/data/cases/fmtskip3.py
diff --git a/tests/data/simple_cases/fmtskip4.py b/tests/data/cases/fmtskip4.py
similarity index 100%
rename from tests/data/simple_cases/fmtskip4.py
rename to tests/data/cases/fmtskip4.py
diff --git a/tests/data/simple_cases/fmtskip5.py b/tests/data/cases/fmtskip5.py
similarity index 100%
rename from tests/data/simple_cases/fmtskip5.py
rename to tests/data/cases/fmtskip5.py
diff --git a/tests/data/simple_cases/fmtskip6.py b/tests/data/cases/fmtskip6.py
similarity index 100%
rename from tests/data/simple_cases/fmtskip6.py
rename to tests/data/cases/fmtskip6.py
diff --git a/tests/data/simple_cases/fmtskip7.py b/tests/data/cases/fmtskip7.py
similarity index 100%
rename from tests/data/simple_cases/fmtskip7.py
rename to tests/data/cases/fmtskip7.py
diff --git a/tests/data/simple_cases/fmtskip8.py b/tests/data/cases/fmtskip8.py
similarity index 100%
rename from tests/data/simple_cases/fmtskip8.py
rename to tests/data/cases/fmtskip8.py
diff --git a/tests/data/simple_cases/fstring.py b/tests/data/cases/fstring.py
similarity index 100%
rename from tests/data/simple_cases/fstring.py
rename to tests/data/cases/fstring.py
diff --git a/tests/data/preview_py_310/funcdef_return_type_trailing_comma.py b/tests/data/cases/funcdef_return_type_trailing_comma.py
similarity index 99%
rename from tests/data/preview_py_310/funcdef_return_type_trailing_comma.py
rename to tests/data/cases/funcdef_return_type_trailing_comma.py
index 15db772f01e..9b9b9c673de 100644
--- a/tests/data/preview_py_310/funcdef_return_type_trailing_comma.py
+++ b/tests/data/cases/funcdef_return_type_trailing_comma.py
@@ -1,3 +1,4 @@
+# flags: --preview --minimum-version=3.10
 # normal, short, function definition
 def foo(a, b) -> tuple[int, float]: ...
 
diff --git a/tests/data/simple_cases/function.py b/tests/data/cases/function.py
similarity index 100%
rename from tests/data/simple_cases/function.py
rename to tests/data/cases/function.py
diff --git a/tests/data/simple_cases/function2.py b/tests/data/cases/function2.py
similarity index 100%
rename from tests/data/simple_cases/function2.py
rename to tests/data/cases/function2.py
diff --git a/tests/data/simple_cases/function_trailing_comma.py b/tests/data/cases/function_trailing_comma.py
similarity index 100%
rename from tests/data/simple_cases/function_trailing_comma.py
rename to tests/data/cases/function_trailing_comma.py
diff --git a/tests/data/simple_cases/ignore_pyi.py b/tests/data/cases/ignore_pyi.py
similarity index 97%
rename from tests/data/simple_cases/ignore_pyi.py
rename to tests/data/cases/ignore_pyi.py
index 3ef61079bfe..4fae7530eb9 100644
--- a/tests/data/simple_cases/ignore_pyi.py
+++ b/tests/data/cases/ignore_pyi.py
@@ -1,3 +1,4 @@
+# flags: --pyi
 def f():  # type: ignore
     ...
 
diff --git a/tests/data/simple_cases/import_spacing.py b/tests/data/cases/import_spacing.py
similarity index 100%
rename from tests/data/simple_cases/import_spacing.py
rename to tests/data/cases/import_spacing.py
diff --git a/tests/data/miscellaneous/linelength6.py b/tests/data/cases/linelength6.py
similarity index 80%
rename from tests/data/miscellaneous/linelength6.py
rename to tests/data/cases/linelength6.py
index 4fb342726f5..158038bf960 100644
--- a/tests/data/miscellaneous/linelength6.py
+++ b/tests/data/cases/linelength6.py
@@ -1,3 +1,4 @@
+# flags: --line-length=6
 # Regression test for #3427, which reproes only with line length <= 6
 def f():
     """
diff --git a/tests/data/miscellaneous/long_strings_flag_disabled.py b/tests/data/cases/long_strings_flag_disabled.py
similarity index 100%
rename from tests/data/miscellaneous/long_strings_flag_disabled.py
rename to tests/data/cases/long_strings_flag_disabled.py
diff --git a/tests/data/simple_cases/multiline_consecutive_open_parentheses_ignore.py b/tests/data/cases/multiline_consecutive_open_parentheses_ignore.py
similarity index 100%
rename from tests/data/simple_cases/multiline_consecutive_open_parentheses_ignore.py
rename to tests/data/cases/multiline_consecutive_open_parentheses_ignore.py
diff --git a/tests/data/miscellaneous/nested_stub.pyi b/tests/data/cases/nested_stub.py
similarity index 97%
rename from tests/data/miscellaneous/nested_stub.pyi
rename to tests/data/cases/nested_stub.py
index 15e69d854db..b81549ec115 100644
--- a/tests/data/miscellaneous/nested_stub.pyi
+++ b/tests/data/cases/nested_stub.py
@@ -1,3 +1,4 @@
+# flags: --pyi --preview
 import sys
 
 class Outer:
diff --git a/tests/data/py_36/numeric_literals.py b/tests/data/cases/numeric_literals.py
similarity index 91%
rename from tests/data/py_36/numeric_literals.py
rename to tests/data/cases/numeric_literals.py
index 254da68d330..99669328744 100644
--- a/tests/data/py_36/numeric_literals.py
+++ b/tests/data/cases/numeric_literals.py
@@ -1,5 +1,3 @@
-#!/usr/bin/env python3.6
-
 x = 123456789
 x = 123456
 x = .1
@@ -21,9 +19,6 @@
 
 # output
 
-
-#!/usr/bin/env python3.6
-
 x = 123456789
 x = 123456
 x = 0.1
diff --git a/tests/data/py_36/numeric_literals_skip_underscores.py b/tests/data/cases/numeric_literals_skip_underscores.py
similarity index 80%
rename from tests/data/py_36/numeric_literals_skip_underscores.py
rename to tests/data/cases/numeric_literals_skip_underscores.py
index e345bb90276..6d60bdbb34d 100644
--- a/tests/data/py_36/numeric_literals_skip_underscores.py
+++ b/tests/data/cases/numeric_literals_skip_underscores.py
@@ -1,5 +1,3 @@
-#!/usr/bin/env python3.6
-
 x = 123456789
 x = 1_2_3_4_5_6_7
 x = 1E+1
@@ -11,8 +9,6 @@
 
 # output
 
-#!/usr/bin/env python3.6
-
 x = 123456789
 x = 1_2_3_4_5_6_7
 x = 1e1
diff --git a/tests/data/simple_cases/one_element_subscript.py b/tests/data/cases/one_element_subscript.py
similarity index 100%
rename from tests/data/simple_cases/one_element_subscript.py
rename to tests/data/cases/one_element_subscript.py
diff --git a/tests/data/py_310/parenthesized_context_managers.py b/tests/data/cases/parenthesized_context_managers.py
similarity index 95%
rename from tests/data/py_310/parenthesized_context_managers.py
rename to tests/data/cases/parenthesized_context_managers.py
index 1ef09a1bd34..16645a18baa 100644
--- a/tests/data/py_310/parenthesized_context_managers.py
+++ b/tests/data/cases/parenthesized_context_managers.py
@@ -1,3 +1,4 @@
+# flags: --minimum-version=3.10
 with (CtxManager() as example):
     ...
 
diff --git a/tests/data/py_310/pattern_matching_complex.py b/tests/data/cases/pattern_matching_complex.py
similarity index 98%
rename from tests/data/py_310/pattern_matching_complex.py
rename to tests/data/cases/pattern_matching_complex.py
index 97ee194fd39..b4355c7333a 100644
--- a/tests/data/py_310/pattern_matching_complex.py
+++ b/tests/data/cases/pattern_matching_complex.py
@@ -1,3 +1,4 @@
+# flags: --minimum-version=3.10
 # Cases sampled from Lib/test/test_patma.py
 
 # case black_test_patma_098
diff --git a/tests/data/py_310/pattern_matching_extras.py b/tests/data/cases/pattern_matching_extras.py
similarity index 98%
rename from tests/data/py_310/pattern_matching_extras.py
rename to tests/data/cases/pattern_matching_extras.py
index 0242d264e5b..1e1481d7bbe 100644
--- a/tests/data/py_310/pattern_matching_extras.py
+++ b/tests/data/cases/pattern_matching_extras.py
@@ -1,3 +1,4 @@
+# flags: --minimum-version=3.10
 import match
 
 match something:
diff --git a/tests/data/py_310/pattern_matching_generic.py b/tests/data/cases/pattern_matching_generic.py
similarity index 98%
rename from tests/data/py_310/pattern_matching_generic.py
rename to tests/data/cases/pattern_matching_generic.py
index 00a0e4a677d..4b4d45f0bff 100644
--- a/tests/data/py_310/pattern_matching_generic.py
+++ b/tests/data/cases/pattern_matching_generic.py
@@ -1,3 +1,4 @@
+# flags: --minimum-version=3.10
 re.match()
 match = a
 with match() as match:
diff --git a/tests/data/py_310/pattern_matching_simple.py b/tests/data/cases/pattern_matching_simple.py
similarity index 98%
rename from tests/data/py_310/pattern_matching_simple.py
rename to tests/data/cases/pattern_matching_simple.py
index 5ed62415a4b..6fa2000f0de 100644
--- a/tests/data/py_310/pattern_matching_simple.py
+++ b/tests/data/cases/pattern_matching_simple.py
@@ -1,3 +1,4 @@
+# flags: --minimum-version=3.10
 # Cases sampled from PEP 636 examples
 
 match command.split():
diff --git a/tests/data/py_310/pattern_matching_style.py b/tests/data/cases/pattern_matching_style.py
similarity index 97%
rename from tests/data/py_310/pattern_matching_style.py
rename to tests/data/cases/pattern_matching_style.py
index 8e18ce2ada6..2ee6ea2b6e9 100644
--- a/tests/data/py_310/pattern_matching_style.py
+++ b/tests/data/cases/pattern_matching_style.py
@@ -1,3 +1,4 @@
+# flags: --minimum-version=3.10
 match something:
     case b(): print(1+1)
     case c(
diff --git a/tests/data/preview_py_310/pep604_union_types_line_breaks.py b/tests/data/cases/pep604_union_types_line_breaks.py
similarity index 99%
rename from tests/data/preview_py_310/pep604_union_types_line_breaks.py
rename to tests/data/cases/pep604_union_types_line_breaks.py
index 9c4ab870766..fee2b840494 100644
--- a/tests/data/preview_py_310/pep604_union_types_line_breaks.py
+++ b/tests/data/cases/pep604_union_types_line_breaks.py
@@ -1,3 +1,4 @@
+# flags: --preview --minimum-version=3.10
 # This has always worked
 z= Loooooooooooooooooooooooong | Loooooooooooooooooooooooong | Loooooooooooooooooooooooong | Loooooooooooooooooooooooong
 
diff --git a/tests/data/py_38/pep_570.py b/tests/data/cases/pep_570.py
similarity index 95%
rename from tests/data/py_38/pep_570.py
rename to tests/data/cases/pep_570.py
index ca8f7ab1d95..2641c2b970e 100644
--- a/tests/data/py_38/pep_570.py
+++ b/tests/data/cases/pep_570.py
@@ -1,3 +1,4 @@
+# flags: --minimum-version=3.8
 def positional_only_arg(a, /):
     pass
 
diff --git a/tests/data/py_38/pep_572.py b/tests/data/cases/pep_572.py
similarity index 96%
rename from tests/data/py_38/pep_572.py
rename to tests/data/cases/pep_572.py
index d41805f1cb1..742b6d5b7e4 100644
--- a/tests/data/py_38/pep_572.py
+++ b/tests/data/cases/pep_572.py
@@ -1,3 +1,4 @@
+# flags: --minimum-version=3.8
 (a := 1)
 (a := a)
 if (match := pattern.search(data)) is None:
diff --git a/tests/data/fast/pep_572_do_not_remove_parens.py b/tests/data/cases/pep_572_do_not_remove_parens.py
similarity index 96%
rename from tests/data/fast/pep_572_do_not_remove_parens.py
rename to tests/data/cases/pep_572_do_not_remove_parens.py
index 05619ddcc2b..08dba3ffdf9 100644
--- a/tests/data/fast/pep_572_do_not_remove_parens.py
+++ b/tests/data/cases/pep_572_do_not_remove_parens.py
@@ -1,3 +1,4 @@
+# flags: --fast
 # Most of the following examples are really dumb, some of them aren't even accepted by Python,
 # we're fixing them only so fuzzers (which follow the grammar which actually allows these
 # examples matter of fact!) don't yell at us :p
diff --git a/tests/data/py_310/pep_572_py310.py b/tests/data/cases/pep_572_py310.py
similarity index 93%
rename from tests/data/py_310/pep_572_py310.py
rename to tests/data/cases/pep_572_py310.py
index cb82b2d23f8..9f999deeb89 100644
--- a/tests/data/py_310/pep_572_py310.py
+++ b/tests/data/cases/pep_572_py310.py
@@ -1,3 +1,4 @@
+# flags: --minimum-version=3.10
 # Unparenthesized walruses are now allowed in indices since Python 3.10.
 x[a:=0]
 x[a:=0, b:=1]
diff --git a/tests/data/py_39/pep_572_py39.py b/tests/data/cases/pep_572_py39.py
similarity index 89%
rename from tests/data/py_39/pep_572_py39.py
rename to tests/data/cases/pep_572_py39.py
index b8b081b8c45..d1614624d99 100644
--- a/tests/data/py_39/pep_572_py39.py
+++ b/tests/data/cases/pep_572_py39.py
@@ -1,3 +1,4 @@
+# flags: --minimum-version=3.9
 # Unparenthesized walruses are now allowed in set literals & set comprehensions
 # since Python 3.9
 {x := 1, 2, 3}
diff --git a/tests/data/py_38/pep_572_remove_parens.py b/tests/data/cases/pep_572_remove_parens.py
similarity index 98%
rename from tests/data/py_38/pep_572_remove_parens.py
rename to tests/data/cases/pep_572_remove_parens.py
index b952b2940c5..24f1ac29168 100644
--- a/tests/data/py_38/pep_572_remove_parens.py
+++ b/tests/data/cases/pep_572_remove_parens.py
@@ -1,3 +1,4 @@
+# flags: --minimum-version=3.8
 if (foo := 0):
     pass
 
diff --git a/tests/data/simple_cases/pep_604.py b/tests/data/cases/pep_604.py
similarity index 100%
rename from tests/data/simple_cases/pep_604.py
rename to tests/data/cases/pep_604.py
diff --git a/tests/data/py_311/pep_646.py b/tests/data/cases/pep_646.py
similarity index 98%
rename from tests/data/py_311/pep_646.py
rename to tests/data/cases/pep_646.py
index e843ecf39d8..92b568a379c 100644
--- a/tests/data/py_311/pep_646.py
+++ b/tests/data/cases/pep_646.py
@@ -1,3 +1,4 @@
+# flags: --minimum-version=3.11
 A[*b]
 A[*b] = 1
 A
diff --git a/tests/data/py_311/pep_654.py b/tests/data/cases/pep_654.py
similarity index 96%
rename from tests/data/py_311/pep_654.py
rename to tests/data/cases/pep_654.py
index 387c0816f4b..12e49180e41 100644
--- a/tests/data/py_311/pep_654.py
+++ b/tests/data/cases/pep_654.py
@@ -1,3 +1,4 @@
+# flags: --minimum-version=3.11
 try:
     raise OSError("blah")
 except* ExceptionGroup as e:
diff --git a/tests/data/py_311/pep_654_style.py b/tests/data/cases/pep_654_style.py
similarity index 98%
rename from tests/data/py_311/pep_654_style.py
rename to tests/data/cases/pep_654_style.py
index 9fc7c0c84db..0d34650e098 100644
--- a/tests/data/py_311/pep_654_style.py
+++ b/tests/data/cases/pep_654_style.py
@@ -1,3 +1,4 @@
+# flags: --minimum-version=3.11
 try:
     raise OSError("blah")
 except               * ExceptionGroup as e:
diff --git a/tests/data/miscellaneous/power_op_newline.py b/tests/data/cases/power_op_newline.py
similarity index 73%
rename from tests/data/miscellaneous/power_op_newline.py
rename to tests/data/cases/power_op_newline.py
index 85d434d63f6..d9b31403c9d 100644
--- a/tests/data/miscellaneous/power_op_newline.py
+++ b/tests/data/cases/power_op_newline.py
@@ -1,3 +1,4 @@
+# flags: --line-length=0
 importA;()<<0**0#
 
 # output
diff --git a/tests/data/simple_cases/power_op_spacing.py b/tests/data/cases/power_op_spacing.py
similarity index 100%
rename from tests/data/simple_cases/power_op_spacing.py
rename to tests/data/cases/power_op_spacing.py
diff --git a/tests/data/simple_cases/prefer_rhs_split_reformatted.py b/tests/data/cases/prefer_rhs_split_reformatted.py
similarity index 100%
rename from tests/data/simple_cases/prefer_rhs_split_reformatted.py
rename to tests/data/cases/prefer_rhs_split_reformatted.py
diff --git a/tests/data/preview/async_stmts.py b/tests/data/cases/preview_async_stmts.py
similarity index 93%
rename from tests/data/preview/async_stmts.py
rename to tests/data/cases/preview_async_stmts.py
index fe9594b2164..0a7671be5a6 100644
--- a/tests/data/preview/async_stmts.py
+++ b/tests/data/cases/preview_async_stmts.py
@@ -1,3 +1,4 @@
+# flags: --preview
 async def func() -> (int):
     return 0
 
diff --git a/tests/data/preview/cantfit.py b/tests/data/cases/preview_cantfit.py
similarity index 99%
rename from tests/data/preview/cantfit.py
rename to tests/data/cases/preview_cantfit.py
index 0849374f776..d5da6654f0c 100644
--- a/tests/data/preview/cantfit.py
+++ b/tests/data/cases/preview_cantfit.py
@@ -1,3 +1,4 @@
+# flags: --preview
 # long variable name
 this_is_a_ridiculously_long_name_and_nobody_in_their_right_mind_would_use_one_like_it = 0
 this_is_a_ridiculously_long_name_and_nobody_in_their_right_mind_would_use_one_like_it = 1  # with a comment
diff --git a/tests/data/preview/comments7.py b/tests/data/cases/preview_comments7.py
similarity index 99%
rename from tests/data/preview/comments7.py
rename to tests/data/cases/preview_comments7.py
index 0655de999ec..006d4f7266f 100644
--- a/tests/data/preview/comments7.py
+++ b/tests/data/cases/preview_comments7.py
@@ -1,3 +1,4 @@
+# flags: --preview
 from .config import (
     Any,
     Bool,
diff --git a/tests/data/preview_context_managers/targeting_py38.py b/tests/data/cases/preview_context_managers_38.py
similarity index 96%
rename from tests/data/preview_context_managers/targeting_py38.py
rename to tests/data/cases/preview_context_managers_38.py
index f125cdffb8a..719d94fdcc5 100644
--- a/tests/data/preview_context_managers/targeting_py38.py
+++ b/tests/data/cases/preview_context_managers_38.py
@@ -1,3 +1,4 @@
+# flags: --preview --minimum-version=3.8
 with \
      make_context_manager1() as cm1, \
      make_context_manager2() as cm2, \
diff --git a/tests/data/preview_context_managers/targeting_py39.py b/tests/data/cases/preview_context_managers_39.py
similarity index 98%
rename from tests/data/preview_context_managers/targeting_py39.py
rename to tests/data/cases/preview_context_managers_39.py
index c9fcf9c8ba2..589e00ad187 100644
--- a/tests/data/preview_context_managers/targeting_py39.py
+++ b/tests/data/cases/preview_context_managers_39.py
@@ -1,3 +1,4 @@
+# flags: --preview --minimum-version=3.9
 with \
      make_context_manager1() as cm1, \
      make_context_manager2() as cm2, \
diff --git a/tests/data/preview_context_managers/auto_detect/features_3_10.py b/tests/data/cases/preview_context_managers_autodetect_310.py
similarity index 93%
rename from tests/data/preview_context_managers/auto_detect/features_3_10.py
rename to tests/data/cases/preview_context_managers_autodetect_310.py
index 1458df1cb41..a9e31076f03 100644
--- a/tests/data/preview_context_managers/auto_detect/features_3_10.py
+++ b/tests/data/cases/preview_context_managers_autodetect_310.py
@@ -1,3 +1,4 @@
+# flags: --preview --minimum-version=3.10
 # This file uses pattern matching introduced in Python 3.10.
 
 
diff --git a/tests/data/preview_context_managers/auto_detect/features_3_11.py b/tests/data/cases/preview_context_managers_autodetect_311.py
similarity index 92%
rename from tests/data/preview_context_managers/auto_detect/features_3_11.py
rename to tests/data/cases/preview_context_managers_autodetect_311.py
index f83c5330ab3..af1e83fe74c 100644
--- a/tests/data/preview_context_managers/auto_detect/features_3_11.py
+++ b/tests/data/cases/preview_context_managers_autodetect_311.py
@@ -1,3 +1,4 @@
+# flags: --preview --minimum-version=3.11
 # This file uses except* clause in Python 3.11.
 
 
diff --git a/tests/data/preview_context_managers/auto_detect/features_3_8.py b/tests/data/cases/preview_context_managers_autodetect_38.py
similarity index 98%
rename from tests/data/preview_context_managers/auto_detect/features_3_8.py
rename to tests/data/cases/preview_context_managers_autodetect_38.py
index 79e438b995e..25217a40604 100644
--- a/tests/data/preview_context_managers/auto_detect/features_3_8.py
+++ b/tests/data/cases/preview_context_managers_autodetect_38.py
@@ -1,3 +1,4 @@
+# flags: --preview
 # This file doesn't use any Python 3.9+ only grammars.
 
 
diff --git a/tests/data/preview_context_managers/auto_detect/features_3_9.py b/tests/data/cases/preview_context_managers_autodetect_39.py
similarity index 93%
rename from tests/data/preview_context_managers/auto_detect/features_3_9.py
rename to tests/data/cases/preview_context_managers_autodetect_39.py
index 0d28f993108..3f72e48db9d 100644
--- a/tests/data/preview_context_managers/auto_detect/features_3_9.py
+++ b/tests/data/cases/preview_context_managers_autodetect_39.py
@@ -1,3 +1,4 @@
+# flags: --preview --minimum-version=3.9
 # This file uses parenthesized context managers introduced in Python 3.9.
 
 
diff --git a/tests/data/preview/dummy_implementations.py b/tests/data/cases/preview_dummy_implementations.py
similarity index 98%
rename from tests/data/preview/dummy_implementations.py
rename to tests/data/cases/preview_dummy_implementations.py
index e07c25ed129..98b69bf87b2 100644
--- a/tests/data/preview/dummy_implementations.py
+++ b/tests/data/cases/preview_dummy_implementations.py
@@ -1,3 +1,4 @@
+# flags: --preview
 from typing import NoReturn, Protocol, Union, overload
 
 
diff --git a/tests/data/preview/format_unicode_escape_seq.py b/tests/data/cases/preview_format_unicode_escape_seq.py
similarity index 96%
rename from tests/data/preview/format_unicode_escape_seq.py
rename to tests/data/cases/preview_format_unicode_escape_seq.py
index 3440696c303..65c3d8d166e 100644
--- a/tests/data/preview/format_unicode_escape_seq.py
+++ b/tests/data/cases/preview_format_unicode_escape_seq.py
@@ -1,3 +1,4 @@
+# flags: --preview
 x = "\x1F"
 x = "\\x1B"
 x = "\\\x1B"
diff --git a/tests/data/preview/long_dict_values.py b/tests/data/cases/preview_long_dict_values.py
similarity index 99%
rename from tests/data/preview/long_dict_values.py
rename to tests/data/cases/preview_long_dict_values.py
index 4c515180028..fbbacd13d1d 100644
--- a/tests/data/preview/long_dict_values.py
+++ b/tests/data/cases/preview_long_dict_values.py
@@ -1,3 +1,4 @@
+# flags: --preview
 my_dict = {
     "something_something":
         r"Lorem ipsum dolor sit amet, an sed convenire eloquentiam \t"
diff --git a/tests/data/preview/long_strings.py b/tests/data/cases/preview_long_strings.py
similarity index 99%
rename from tests/data/preview/long_strings.py
rename to tests/data/cases/preview_long_strings.py
index 059148729d5..5519f098774 100644
--- a/tests/data/preview/long_strings.py
+++ b/tests/data/cases/preview_long_strings.py
@@ -1,3 +1,4 @@
+# flags: --preview
 x = "This is a really long string that can't possibly be expected to fit all together on one line. In fact it may even take up three or more lines... like four or five... but probably just three."
 
 x += "This is a really long string that can't possibly be expected to fit all together on one line. In fact it may even take up three or more lines... like four or five... but probably just three."
diff --git a/tests/data/preview/long_strings__east_asian_width.py b/tests/data/cases/preview_long_strings__east_asian_width.py
similarity index 96%
rename from tests/data/preview/long_strings__east_asian_width.py
rename to tests/data/cases/preview_long_strings__east_asian_width.py
index fb66a78ed8b..d190f422a60 100644
--- a/tests/data/preview/long_strings__east_asian_width.py
+++ b/tests/data/cases/preview_long_strings__east_asian_width.py
@@ -1,3 +1,4 @@
+# flags: --preview
 # The following strings do not have not-so-many chars, but are long enough
 # when these are rendered in a monospace font (if the renderer respects
 # Unicode East Asian Width properties).
diff --git a/tests/data/preview/long_strings__edge_case.py b/tests/data/cases/preview_long_strings__edge_case.py
similarity index 99%
rename from tests/data/preview/long_strings__edge_case.py
rename to tests/data/cases/preview_long_strings__edge_case.py
index 2bc0b6ed328..a8e8971968c 100644
--- a/tests/data/preview/long_strings__edge_case.py
+++ b/tests/data/cases/preview_long_strings__edge_case.py
@@ -1,3 +1,4 @@
+# flags: --preview
 some_variable = "This string is long but not so long that it needs to be split just yet"
 some_variable = 'This string is long but not so long that it needs to be split just yet'
 some_variable = "This string is long, just long enough that it needs to be split, u get?"
diff --git a/tests/data/preview/long_strings__regression.py b/tests/data/cases/preview_long_strings__regression.py
similarity index 99%
rename from tests/data/preview/long_strings__regression.py
rename to tests/data/cases/preview_long_strings__regression.py
index 5f0646e6029..40d5e745cc8 100644
--- a/tests/data/preview/long_strings__regression.py
+++ b/tests/data/cases/preview_long_strings__regression.py
@@ -1,3 +1,4 @@
+# flags: --preview
 class A:
     def foo():
         result = type(message)("")
diff --git a/tests/data/preview/long_strings__type_annotations.py b/tests/data/cases/preview_long_strings__type_annotations.py
similarity index 98%
rename from tests/data/preview/long_strings__type_annotations.py
rename to tests/data/cases/preview_long_strings__type_annotations.py
index 45de882d02c..8beb877bdd1 100644
--- a/tests/data/preview/long_strings__type_annotations.py
+++ b/tests/data/cases/preview_long_strings__type_annotations.py
@@ -1,3 +1,4 @@
+# flags: --preview
 def func(
     arg1,
     arg2,
diff --git a/tests/data/preview/multiline_strings.py b/tests/data/cases/preview_multiline_strings.py
similarity index 99%
rename from tests/data/preview/multiline_strings.py
rename to tests/data/cases/preview_multiline_strings.py
index bb517d128e2..dec4ef2e548 100644
--- a/tests/data/preview/multiline_strings.py
+++ b/tests/data/cases/preview_multiline_strings.py
@@ -1,3 +1,4 @@
+# flags: --preview
 """cow
 say""",
 call(3, "dogsay", textwrap.dedent("""dove
diff --git a/tests/data/preview/no_blank_line_before_docstring.py b/tests/data/cases/preview_no_blank_line_before_docstring.py
similarity index 97%
rename from tests/data/preview/no_blank_line_before_docstring.py
rename to tests/data/cases/preview_no_blank_line_before_docstring.py
index a37362de100..303035a7efb 100644
--- a/tests/data/preview/no_blank_line_before_docstring.py
+++ b/tests/data/cases/preview_no_blank_line_before_docstring.py
@@ -1,3 +1,4 @@
+# flags: --preview
 def line_before_docstring():
 
     """Please move me up"""
diff --git a/tests/data/preview/pep_572.py b/tests/data/cases/preview_pep_572.py
similarity index 75%
rename from tests/data/preview/pep_572.py
rename to tests/data/cases/preview_pep_572.py
index a50e130ad9c..8e801ff6cdc 100644
--- a/tests/data/preview/pep_572.py
+++ b/tests/data/cases/preview_pep_572.py
@@ -1,3 +1,4 @@
+# flags: --preview
 x[(a:=0):]
 x[:(a:=0)]
 
diff --git a/tests/data/preview/percent_precedence.py b/tests/data/cases/preview_percent_precedence.py
similarity index 96%
rename from tests/data/preview/percent_precedence.py
rename to tests/data/cases/preview_percent_precedence.py
index b895443fb46..aeaf450ff5e 100644
--- a/tests/data/preview/percent_precedence.py
+++ b/tests/data/cases/preview_percent_precedence.py
@@ -1,3 +1,4 @@
+# flags: --preview
 ("" % a) ** 2
 ("" % a)[0]
 ("" % a)()
diff --git a/tests/data/preview/prefer_rhs_split.py b/tests/data/cases/preview_prefer_rhs_split.py
similarity index 99%
rename from tests/data/preview/prefer_rhs_split.py
rename to tests/data/cases/preview_prefer_rhs_split.py
index a809eacc773..c732c33b53a 100644
--- a/tests/data/preview/prefer_rhs_split.py
+++ b/tests/data/cases/preview_prefer_rhs_split.py
@@ -1,3 +1,4 @@
+# flags: --preview
 first_item, second_item = (
     some_looooooooong_module.some_looooooooooooooong_function_name(
         first_argument, second_argument, third_argument
diff --git a/tests/data/preview/return_annotation_brackets_string.py b/tests/data/cases/preview_return_annotation_brackets_string.py
similarity index 97%
rename from tests/data/preview/return_annotation_brackets_string.py
rename to tests/data/cases/preview_return_annotation_brackets_string.py
index 9148bd045bc..fea0ea6839a 100644
--- a/tests/data/preview/return_annotation_brackets_string.py
+++ b/tests/data/cases/preview_return_annotation_brackets_string.py
@@ -1,3 +1,4 @@
+# flags: --preview
 # Long string example
 def frobnicate() -> "ThisIsTrulyUnreasonablyExtremelyLongClassName | list[ThisIsTrulyUnreasonablyExtremelyLongClassName]":
     pass
diff --git a/tests/data/preview/trailing_comma.py b/tests/data/cases/preview_trailing_comma.py
similarity index 97%
rename from tests/data/preview/trailing_comma.py
rename to tests/data/cases/preview_trailing_comma.py
index 5b09c664606..bba7e7ad16d 100644
--- a/tests/data/preview/trailing_comma.py
+++ b/tests/data/cases/preview_trailing_comma.py
@@ -1,3 +1,4 @@
+# flags: --preview
 e = {
     "a": fun(msg, "ts"),
     "longggggggggggggggid": ...,
diff --git a/tests/data/preview_py_310/pep_572.py b/tests/data/cases/py310_pep572.py
similarity index 77%
rename from tests/data/preview_py_310/pep_572.py
rename to tests/data/cases/py310_pep572.py
index 78d4e9e4506..172be3898d6 100644
--- a/tests/data/preview_py_310/pep_572.py
+++ b/tests/data/cases/py310_pep572.py
@@ -1,3 +1,4 @@
+# flags: --preview --minimum-version=3.10
 x[a:=0]
 x[a := 0]
 x[a := 0, b := 1]
diff --git a/tests/data/py_37/python37.py b/tests/data/cases/python37.py
similarity index 95%
rename from tests/data/py_37/python37.py
rename to tests/data/cases/python37.py
index dab8b404a73..3f61106c45d 100644
--- a/tests/data/py_37/python37.py
+++ b/tests/data/cases/python37.py
@@ -1,4 +1,4 @@
-#!/usr/bin/env python3.7
+# flags: --minimum-version=3.7
 
 
 def f():
@@ -33,9 +33,6 @@ def make_arange(n):
 # output
 
 
-#!/usr/bin/env python3.7
-
-
 def f():
     return (i * 2 async for i in arange(42))
 
diff --git a/tests/data/py_38/python38.py b/tests/data/cases/python38.py
similarity index 93%
rename from tests/data/py_38/python38.py
rename to tests/data/cases/python38.py
index 63b0588bc27..919ea6aeed4 100644
--- a/tests/data/py_38/python38.py
+++ b/tests/data/cases/python38.py
@@ -1,4 +1,4 @@
-#!/usr/bin/env python3.8
+# flags: --minimum-version=3.8
 
 
 def starred_return():
@@ -22,9 +22,6 @@ def t():
 # output
 
 
-#!/usr/bin/env python3.8
-
-
 def starred_return():
     my_list = ["value2", "value3"]
     return "value1", *my_list
diff --git a/tests/data/py_39/python39.py b/tests/data/cases/python39.py
similarity index 92%
rename from tests/data/py_39/python39.py
rename to tests/data/cases/python39.py
index ae67c2257eb..1b9536c1529 100644
--- a/tests/data/py_39/python39.py
+++ b/tests/data/cases/python39.py
@@ -1,4 +1,4 @@
-#!/usr/bin/env python3.9
+# flags: --minimum-version=3.9
 
 @relaxed_decorator[0]
 def f():
@@ -14,10 +14,6 @@ def f():
 
 # output
 
-
-#!/usr/bin/env python3.9
-
-
 @relaxed_decorator[0]
 def f():
     ...
diff --git a/tests/data/simple_cases/remove_await_parens.py b/tests/data/cases/remove_await_parens.py
similarity index 100%
rename from tests/data/simple_cases/remove_await_parens.py
rename to tests/data/cases/remove_await_parens.py
diff --git a/tests/data/simple_cases/remove_except_parens.py b/tests/data/cases/remove_except_parens.py
similarity index 100%
rename from tests/data/simple_cases/remove_except_parens.py
rename to tests/data/cases/remove_except_parens.py
diff --git a/tests/data/simple_cases/remove_for_brackets.py b/tests/data/cases/remove_for_brackets.py
similarity index 100%
rename from tests/data/simple_cases/remove_for_brackets.py
rename to tests/data/cases/remove_for_brackets.py
diff --git a/tests/data/simple_cases/remove_newline_after_code_block_open.py b/tests/data/cases/remove_newline_after_code_block_open.py
similarity index 100%
rename from tests/data/simple_cases/remove_newline_after_code_block_open.py
rename to tests/data/cases/remove_newline_after_code_block_open.py
diff --git a/tests/data/py_310/remove_newline_after_match.py b/tests/data/cases/remove_newline_after_match.py
similarity index 94%
rename from tests/data/py_310/remove_newline_after_match.py
rename to tests/data/cases/remove_newline_after_match.py
index f7bcfbf27a2..fe6592b664d 100644
--- a/tests/data/py_310/remove_newline_after_match.py
+++ b/tests/data/cases/remove_newline_after_match.py
@@ -1,3 +1,4 @@
+# flags: --minimum-version=3.10
 def http_status(status):
 
     match status:
diff --git a/tests/data/simple_cases/remove_parens.py b/tests/data/cases/remove_parens.py
similarity index 100%
rename from tests/data/simple_cases/remove_parens.py
rename to tests/data/cases/remove_parens.py
diff --git a/tests/data/py_39/remove_with_brackets.py b/tests/data/cases/remove_with_brackets.py
similarity index 98%
rename from tests/data/py_39/remove_with_brackets.py
rename to tests/data/cases/remove_with_brackets.py
index ea58ab93a16..3ee64902a30 100644
--- a/tests/data/py_39/remove_with_brackets.py
+++ b/tests/data/cases/remove_with_brackets.py
@@ -1,3 +1,4 @@
+# flags: --minimum-version=3.9
 with (open("bla.txt")):
     pass
 
diff --git a/tests/data/simple_cases/return_annotation_brackets.py b/tests/data/cases/return_annotation_brackets.py
similarity index 100%
rename from tests/data/simple_cases/return_annotation_brackets.py
rename to tests/data/cases/return_annotation_brackets.py
diff --git a/tests/data/simple_cases/skip_magic_trailing_comma.py b/tests/data/cases/skip_magic_trailing_comma.py
similarity index 97%
rename from tests/data/simple_cases/skip_magic_trailing_comma.py
rename to tests/data/cases/skip_magic_trailing_comma.py
index c020db79864..4dda5df40f0 100644
--- a/tests/data/simple_cases/skip_magic_trailing_comma.py
+++ b/tests/data/cases/skip_magic_trailing_comma.py
@@ -1,3 +1,4 @@
+# flags: --skip-magic-trailing-comma
 # We should not remove the trailing comma in a single-element subscript.
 a: tuple[int,]
 b = tuple[int,]
diff --git a/tests/data/simple_cases/slices.py b/tests/data/cases/slices.py
similarity index 100%
rename from tests/data/simple_cases/slices.py
rename to tests/data/cases/slices.py
diff --git a/tests/data/py_310/starred_for_target.py b/tests/data/cases/starred_for_target.py
similarity index 92%
rename from tests/data/py_310/starred_for_target.py
rename to tests/data/cases/starred_for_target.py
index 8fc8e059ed3..13e517816d6 100644
--- a/tests/data/py_310/starred_for_target.py
+++ b/tests/data/cases/starred_for_target.py
@@ -1,3 +1,4 @@
+# flags: --minimum-version=3.10
 for x in *a, *b:
     print(x)
 
diff --git a/tests/data/simple_cases/string_prefixes.py b/tests/data/cases/string_prefixes.py
similarity index 100%
rename from tests/data/simple_cases/string_prefixes.py
rename to tests/data/cases/string_prefixes.py
diff --git a/tests/data/miscellaneous/stub.pyi b/tests/data/cases/stub.py
similarity index 99%
rename from tests/data/miscellaneous/stub.pyi
rename to tests/data/cases/stub.py
index af2cd2c2c02..f3828d55ba2 100644
--- a/tests/data/miscellaneous/stub.pyi
+++ b/tests/data/cases/stub.py
@@ -1,3 +1,4 @@
+# flags: --pyi
 X: int
 
 def f(): ...
diff --git a/tests/data/simple_cases/torture.py b/tests/data/cases/torture.py
similarity index 100%
rename from tests/data/simple_cases/torture.py
rename to tests/data/cases/torture.py
diff --git a/tests/data/simple_cases/trailing_comma_optional_parens1.py b/tests/data/cases/trailing_comma_optional_parens1.py
similarity index 100%
rename from tests/data/simple_cases/trailing_comma_optional_parens1.py
rename to tests/data/cases/trailing_comma_optional_parens1.py
diff --git a/tests/data/simple_cases/trailing_comma_optional_parens2.py b/tests/data/cases/trailing_comma_optional_parens2.py
similarity index 100%
rename from tests/data/simple_cases/trailing_comma_optional_parens2.py
rename to tests/data/cases/trailing_comma_optional_parens2.py
diff --git a/tests/data/simple_cases/trailing_comma_optional_parens3.py b/tests/data/cases/trailing_comma_optional_parens3.py
similarity index 100%
rename from tests/data/simple_cases/trailing_comma_optional_parens3.py
rename to tests/data/cases/trailing_comma_optional_parens3.py
diff --git a/tests/data/simple_cases/trailing_commas_in_leading_parts.py b/tests/data/cases/trailing_commas_in_leading_parts.py
similarity index 100%
rename from tests/data/simple_cases/trailing_commas_in_leading_parts.py
rename to tests/data/cases/trailing_commas_in_leading_parts.py
diff --git a/tests/data/simple_cases/tricky_unicode_symbols.py b/tests/data/cases/tricky_unicode_symbols.py
similarity index 100%
rename from tests/data/simple_cases/tricky_unicode_symbols.py
rename to tests/data/cases/tricky_unicode_symbols.py
diff --git a/tests/data/simple_cases/tupleassign.py b/tests/data/cases/tupleassign.py
similarity index 100%
rename from tests/data/simple_cases/tupleassign.py
rename to tests/data/cases/tupleassign.py
diff --git a/tests/data/py_312/type_aliases.py b/tests/data/cases/type_aliases.py
similarity index 81%
rename from tests/data/py_312/type_aliases.py
rename to tests/data/cases/type_aliases.py
index 84e07e50fe2..a3c1931c9fc 100644
--- a/tests/data/py_312/type_aliases.py
+++ b/tests/data/cases/type_aliases.py
@@ -1,3 +1,4 @@
+# flags: --minimum-version=3.12
 type A=int
 type Gen[T]=list[T]
 
diff --git a/tests/data/type_comments/type_comment_syntax_error.py b/tests/data/cases/type_comment_syntax_error.py
similarity index 100%
rename from tests/data/type_comments/type_comment_syntax_error.py
rename to tests/data/cases/type_comment_syntax_error.py
diff --git a/tests/data/py_312/type_params.py b/tests/data/cases/type_params.py
similarity index 97%
rename from tests/data/py_312/type_params.py
rename to tests/data/cases/type_params.py
index 5f8ec43267c..720a775ef31 100644
--- a/tests/data/py_312/type_params.py
+++ b/tests/data/cases/type_params.py
@@ -1,3 +1,4 @@
+# flags: --minimum-version=3.12
 def func  [T ](): pass
 async def func [ T ] (): pass
 class C[ T ] : pass
diff --git a/tests/data/simple_cases/whitespace.py b/tests/data/cases/whitespace.py
similarity index 100%
rename from tests/data/simple_cases/whitespace.py
rename to tests/data/cases/whitespace.py
diff --git a/tests/data/miscellaneous/force_pyi.py b/tests/data/miscellaneous/force_pyi.py
index 07ed93c6879..40caf30a983 100644
--- a/tests/data/miscellaneous/force_pyi.py
+++ b/tests/data/miscellaneous/force_pyi.py
@@ -1,3 +1,4 @@
+# flags: --pyi
 from typing import Union
 
 @bird
diff --git a/tests/test_black.py b/tests/test_black.py
index c665eee3a6c..bb5cc1e08c7 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -187,7 +187,9 @@ def test_experimental_string_processing_warns(self) -> None:
         )
 
     def test_piping(self) -> None:
-        source, expected = read_data_from_file(PROJECT_ROOT / "src/black/__init__.py")
+        _, source, expected = read_data_from_file(
+            PROJECT_ROOT / "src/black/__init__.py"
+        )
         result = BlackRunner().invoke(
             black.main,
             [
@@ -209,8 +211,8 @@ def test_piping_diff(self) -> None:
             r"(STDIN|STDOUT)\t\d\d\d\d-\d\d-\d\d \d\d:\d\d:\d\d\.\d\d\d\d\d\d"
             r"\+\d\d:\d\d"
         )
-        source, _ = read_data("simple_cases", "expression.py")
-        expected, _ = read_data("simple_cases", "expression.diff")
+        source, _ = read_data("cases", "expression.py")
+        expected, _ = read_data("cases", "expression.diff")
         args = [
             "-",
             "--fast",
@@ -227,7 +229,7 @@ def test_piping_diff(self) -> None:
         self.assertEqual(expected, actual)
 
     def test_piping_diff_with_color(self) -> None:
-        source, _ = read_data("simple_cases", "expression.py")
+        source, _ = read_data("cases", "expression.py")
         args = [
             "-",
             "--fast",
@@ -263,7 +265,7 @@ def _test_wip(self) -> None:
         black.assert_stable(source, actual, black.FileMode())
 
     def test_pep_572_version_detection(self) -> None:
-        source, _ = read_data("py_38", "pep_572")
+        source, _ = read_data("cases", "pep_572")
         root = black.lib2to3_parse(source)
         features = black.get_features_used(root)
         self.assertIn(black.Feature.ASSIGNMENT_EXPRESSIONS, features)
@@ -272,7 +274,7 @@ def test_pep_572_version_detection(self) -> None:
 
     def test_pep_695_version_detection(self) -> None:
         for file in ("type_aliases", "type_params"):
-            source, _ = read_data("py_312", file)
+            source, _ = read_data("cases", file)
             root = black.lib2to3_parse(source)
             features = black.get_features_used(root)
             self.assertIn(black.Feature.TYPE_PARAMS, features)
@@ -280,7 +282,7 @@ def test_pep_695_version_detection(self) -> None:
             self.assertIn(black.TargetVersion.PY312, versions)
 
     def test_expression_ff(self) -> None:
-        source, expected = read_data("simple_cases", "expression.py")
+        source, expected = read_data("cases", "expression.py")
         tmp_file = Path(black.dump_to_file(source))
         try:
             self.assertTrue(ff(tmp_file, write_back=black.WriteBack.YES))
@@ -293,8 +295,8 @@ def test_expression_ff(self) -> None:
             black.assert_stable(source, actual, DEFAULT_MODE)
 
     def test_expression_diff(self) -> None:
-        source, _ = read_data("simple_cases", "expression.py")
-        expected, _ = read_data("simple_cases", "expression.diff")
+        source, _ = read_data("cases", "expression.py")
+        expected, _ = read_data("cases", "expression.diff")
         tmp_file = Path(black.dump_to_file(source))
         diff_header = re.compile(
             rf"{re.escape(str(tmp_file))}\t\d\d\d\d-\d\d-\d\d "
@@ -319,8 +321,8 @@ def test_expression_diff(self) -> None:
             self.assertEqual(expected, actual, msg)
 
     def test_expression_diff_with_color(self) -> None:
-        source, _ = read_data("simple_cases", "expression.py")
-        expected, _ = read_data("simple_cases", "expression.diff")
+        source, _ = read_data("cases", "expression.py")
+        expected, _ = read_data("cases", "expression.diff")
         tmp_file = Path(black.dump_to_file(source))
         try:
             result = BlackRunner().invoke(
@@ -339,7 +341,7 @@ def test_expression_diff_with_color(self) -> None:
         self.assertIn("\033[0m", actual)
 
     def test_detect_pos_only_arguments(self) -> None:
-        source, _ = read_data("py_38", "pep_570")
+        source, _ = read_data("cases", "pep_570")
         root = black.lib2to3_parse(source)
         features = black.get_features_used(root)
         self.assertIn(black.Feature.POS_ONLY_ARGUMENTS, features)
@@ -401,7 +403,7 @@ def test_skip_source_first_line_when_mixing_newlines(self) -> None:
             self.assertEqual(test_file.read_bytes(), expected)
 
     def test_skip_magic_trailing_comma(self) -> None:
-        source, _ = read_data("simple_cases", "expression")
+        source, _ = read_data("cases", "expression")
         expected, _ = read_data(
             "miscellaneous", "expression_skip_magic_trailing_comma.diff"
         )
@@ -433,7 +435,7 @@ def test_skip_magic_trailing_comma(self) -> None:
     @patch("black.dump_to_file", dump_to_stderr)
     def test_async_as_identifier(self) -> None:
         source_path = get_case_path("miscellaneous", "async_as_identifier")
-        source, expected = read_data_from_file(source_path)
+        _, source, expected = read_data_from_file(source_path)
         actual = fs(source)
         self.assertFormatEqual(expected, actual)
         major, minor = sys.version_info[:2]
@@ -447,8 +449,8 @@ def test_async_as_identifier(self) -> None:
 
     @patch("black.dump_to_file", dump_to_stderr)
     def test_python37(self) -> None:
-        source_path = get_case_path("py_37", "python37")
-        source, expected = read_data_from_file(source_path)
+        source_path = get_case_path("cases", "python37")
+        _, source, expected = read_data_from_file(source_path)
         actual = fs(source)
         self.assertFormatEqual(expected, actual)
         major, minor = sys.version_info[:2]
@@ -884,7 +886,7 @@ def test_get_features_used(self) -> None:
         self.assertEqual(black.get_features_used(node), {Feature.NUMERIC_UNDERSCORES})
         node = black.lib2to3_parse("123456\n")
         self.assertEqual(black.get_features_used(node), set())
-        source, expected = read_data("simple_cases", "function")
+        source, expected = read_data("cases", "function")
         node = black.lib2to3_parse(source)
         expected_features = {
             Feature.TRAILING_COMMA_IN_CALL,
@@ -894,7 +896,7 @@ def test_get_features_used(self) -> None:
         self.assertEqual(black.get_features_used(node), expected_features)
         node = black.lib2to3_parse(expected)
         self.assertEqual(black.get_features_used(node), expected_features)
-        source, expected = read_data("simple_cases", "expression")
+        source, expected = read_data("cases", "expression")
         node = black.lib2to3_parse(source)
         self.assertEqual(black.get_features_used(node), set())
         node = black.lib2to3_parse(expected)
@@ -1109,7 +1111,7 @@ def test_check_diff_use_together(self) -> None:
             src1 = get_case_path("miscellaneous", "string_quotes")
             self.invokeBlack([str(src1), "--diff", "--check"], exit_code=1)
             # Files which will not be reformatted.
-            src2 = get_case_path("simple_cases", "composition")
+            src2 = get_case_path("cases", "composition")
             self.invokeBlack([str(src2), "--diff", "--check"])
             # Multi file command.
             self.invokeBlack([str(src1), str(src2), "--diff", "--check"], exit_code=1)
@@ -1330,7 +1332,7 @@ def test_reformat_one_with_stdin_and_existing_path(self) -> None:
             report = MagicMock()
             # Even with an existing file, since we are forcing stdin, black
             # should output to stdout and not modify the file inplace
-            p = THIS_DIR / "data" / "simple_cases" / "collections.py"
+            p = THIS_DIR / "data" / "cases" / "collections.py"
             # Make sure is_file actually returns True
             self.assertTrue(p.is_file())
             path = Path(f"__BLACK_STDIN_FILENAME__{p}")
diff --git a/tests/test_blackd.py b/tests/test_blackd.py
index dd2126e6bc2..c0152de73e6 100644
--- a/tests/test_blackd.py
+++ b/tests/test_blackd.py
@@ -104,7 +104,7 @@ async def check(header_value: str, expected_status: int = 400) -> None:
 
     @unittest_run_loop
     async def test_blackd_pyi(self) -> None:
-        source, expected = read_data("miscellaneous", "stub.pyi")
+        source, expected = read_data("cases", "stub.py")
         response = await self.client.post(
             "/", data=source, headers={blackd.PYTHON_VARIANT_HEADER: "pyi"}
         )
diff --git a/tests/test_format.py b/tests/test_format.py
index ff358d59c94..4e863c6c54b 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -1,4 +1,3 @@
-import re
 from dataclasses import replace
 from typing import Any, Iterator
 from unittest.mock import patch
@@ -6,13 +5,13 @@
 import pytest
 
 import black
+from black.mode import TargetVersion
 from tests.util import (
-    DEFAULT_MODE,
-    PY36_VERSIONS,
     all_data_cases,
     assert_format,
     dump_to_stderr,
     read_data,
+    read_data_with_mode,
 )
 
 
@@ -22,61 +21,33 @@ def patch_dump_to_file(request: Any) -> Iterator[None]:
         yield
 
 
-def check_file(
-    subdir: str, filename: str, mode: black.Mode, *, data: bool = True
-) -> None:
-    source, expected = read_data(subdir, filename, data=data)
-    assert_format(source, expected, mode, fast=False)
+def check_file(subdir: str, filename: str, *, data: bool = True) -> None:
+    args, source, expected = read_data_with_mode(subdir, filename, data=data)
+    assert_format(
+        source,
+        expected,
+        args.mode,
+        fast=args.fast,
+        minimum_version=args.minimum_version,
+    )
+    if args.minimum_version is not None:
+        major, minor = args.minimum_version
+        target_version = TargetVersion[f"PY{major}{minor}"]
+        mode = replace(args.mode, target_versions={target_version})
+        assert_format(
+            source, expected, mode, fast=args.fast, minimum_version=args.minimum_version
+        )
 
 
 @pytest.mark.filterwarnings("ignore:invalid escape sequence.*:DeprecationWarning")
-@pytest.mark.parametrize("filename", all_data_cases("simple_cases"))
+@pytest.mark.parametrize("filename", all_data_cases("cases"))
 def test_simple_format(filename: str) -> None:
-    magic_trailing_comma = filename != "skip_magic_trailing_comma"
-    mode = black.Mode(
-        magic_trailing_comma=magic_trailing_comma, is_pyi=filename.endswith("_pyi")
-    )
-    check_file("simple_cases", filename, mode)
-
-
-@pytest.mark.parametrize("filename", all_data_cases("preview"))
-def test_preview_format(filename: str) -> None:
-    check_file("preview", filename, black.Mode(preview=True))
-
-
-def test_preview_context_managers_targeting_py38() -> None:
-    source, expected = read_data("preview_context_managers", "targeting_py38.py")
-    mode = black.Mode(preview=True, target_versions={black.TargetVersion.PY38})
-    assert_format(source, expected, mode, minimum_version=(3, 8))
-
-
-def test_preview_context_managers_targeting_py39() -> None:
-    source, expected = read_data("preview_context_managers", "targeting_py39.py")
-    mode = black.Mode(preview=True, target_versions={black.TargetVersion.PY39})
-    assert_format(source, expected, mode, minimum_version=(3, 9))
-
-
-@pytest.mark.parametrize("filename", all_data_cases("preview_py_310"))
-def test_preview_python_310(filename: str) -> None:
-    source, expected = read_data("preview_py_310", filename)
-    mode = black.Mode(target_versions={black.TargetVersion.PY310}, preview=True)
-    assert_format(source, expected, mode, minimum_version=(3, 10))
-
-
-@pytest.mark.parametrize(
-    "filename", all_data_cases("preview_context_managers/auto_detect")
-)
-def test_preview_context_managers_auto_detect(filename: str) -> None:
-    match = re.match(r"features_3_(\d+)", filename)
-    assert match is not None, "Unexpected filename format: %s" % filename
-    source, expected = read_data("preview_context_managers/auto_detect", filename)
-    mode = black.Mode(preview=True)
-    assert_format(source, expected, mode, minimum_version=(3, int(match.group(1))))
+    check_file("cases", filename)
 
 
 # =============== #
-# Complex cases
-# ============= #
+# Unusual cases
+# =============== #
 
 
 def test_empty() -> None:
@@ -84,48 +55,6 @@ def test_empty() -> None:
     assert_format(source, expected)
 
 
-@pytest.mark.parametrize("filename", all_data_cases("py_36"))
-def test_python_36(filename: str) -> None:
-    source, expected = read_data("py_36", filename)
-    mode = black.Mode(target_versions=PY36_VERSIONS)
-    assert_format(source, expected, mode, minimum_version=(3, 6))
-
-
-@pytest.mark.parametrize("filename", all_data_cases("py_37"))
-def test_python_37(filename: str) -> None:
-    source, expected = read_data("py_37", filename)
-    mode = black.Mode(target_versions={black.TargetVersion.PY37})
-    assert_format(source, expected, mode, minimum_version=(3, 7))
-
-
-@pytest.mark.parametrize("filename", all_data_cases("py_38"))
-def test_python_38(filename: str) -> None:
-    source, expected = read_data("py_38", filename)
-    mode = black.Mode(target_versions={black.TargetVersion.PY38})
-    assert_format(source, expected, mode, minimum_version=(3, 8))
-
-
-@pytest.mark.parametrize("filename", all_data_cases("py_39"))
-def test_python_39(filename: str) -> None:
-    source, expected = read_data("py_39", filename)
-    mode = black.Mode(target_versions={black.TargetVersion.PY39})
-    assert_format(source, expected, mode, minimum_version=(3, 9))
-
-
-@pytest.mark.parametrize("filename", all_data_cases("py_310"))
-def test_python_310(filename: str) -> None:
-    source, expected = read_data("py_310", filename)
-    mode = black.Mode(target_versions={black.TargetVersion.PY310})
-    assert_format(source, expected, mode, minimum_version=(3, 10))
-
-
-@pytest.mark.parametrize("filename", all_data_cases("py_310"))
-def test_python_310_without_target_version(filename: str) -> None:
-    source, expected = read_data("py_310", filename)
-    mode = black.Mode()
-    assert_format(source, expected, mode, minimum_version=(3, 10))
-
-
 def test_patma_invalid() -> None:
     source, expected = read_data("miscellaneous", "pattern_matching_invalid")
     mode = black.Mode(target_versions={black.TargetVersion.PY310})
@@ -133,82 +62,3 @@ def test_patma_invalid() -> None:
         assert_format(source, expected, mode, minimum_version=(3, 10))
 
     exc_info.match("Cannot parse: 10:11")
-
-
-@pytest.mark.parametrize("filename", all_data_cases("py_311"))
-def test_python_311(filename: str) -> None:
-    source, expected = read_data("py_311", filename)
-    mode = black.Mode(target_versions={black.TargetVersion.PY311})
-    assert_format(source, expected, mode, minimum_version=(3, 11))
-
-
-@pytest.mark.parametrize("filename", all_data_cases("py_312"))
-def test_python_312(filename: str) -> None:
-    source, expected = read_data("py_312", filename)
-    mode = black.Mode(target_versions={black.TargetVersion.PY312})
-    assert_format(source, expected, mode, minimum_version=(3, 12))
-
-
-@pytest.mark.parametrize("filename", all_data_cases("fast"))
-def test_fast_cases(filename: str) -> None:
-    source, expected = read_data("fast", filename)
-    assert_format(source, expected, fast=True)
-
-
-@pytest.mark.filterwarnings("ignore:invalid escape sequence.*:DeprecationWarning")
-def test_docstring_no_string_normalization() -> None:
-    """Like test_docstring but with string normalization off."""
-    source, expected = read_data("miscellaneous", "docstring_no_string_normalization")
-    mode = replace(DEFAULT_MODE, string_normalization=False)
-    assert_format(source, expected, mode)
-
-
-def test_docstring_line_length_6() -> None:
-    """Like test_docstring but with line length set to 6."""
-    source, expected = read_data("miscellaneous", "linelength6")
-    mode = black.Mode(line_length=6)
-    assert_format(source, expected, mode)
-
-
-def test_preview_docstring_no_string_normalization() -> None:
-    """
-    Like test_docstring but with string normalization off *and* the preview style
-    enabled.
-    """
-    source, expected = read_data(
-        "miscellaneous", "docstring_preview_no_string_normalization"
-    )
-    mode = replace(DEFAULT_MODE, string_normalization=False, preview=True)
-    assert_format(source, expected, mode)
-
-
-def test_long_strings_flag_disabled() -> None:
-    """Tests for turning off the string processing logic."""
-    source, expected = read_data("miscellaneous", "long_strings_flag_disabled")
-    mode = replace(DEFAULT_MODE, experimental_string_processing=False)
-    assert_format(source, expected, mode)
-
-
-def test_stub() -> None:
-    mode = replace(DEFAULT_MODE, is_pyi=True)
-    source, expected = read_data("miscellaneous", "stub.pyi")
-    assert_format(source, expected, mode)
-
-
-def test_nested_stub() -> None:
-    mode = replace(DEFAULT_MODE, is_pyi=True, preview=True)
-    source, expected = read_data("miscellaneous", "nested_stub.pyi")
-    assert_format(source, expected, mode)
-
-
-def test_power_op_newline() -> None:
-    # requires line_length=0
-    source, expected = read_data("miscellaneous", "power_op_newline")
-    assert_format(source, expected, mode=black.Mode(line_length=0))
-
-
-def test_type_comment_syntax_error() -> None:
-    """Test that black is able to format python code with type comment syntax errors."""
-    source, expected = read_data("type_comments", "type_comment_syntax_error")
-    assert_format(source, expected)
-    black.assert_equivalent(source, expected)
diff --git a/tests/util.py b/tests/util.py
index 541d21da4df..a31ae0992c2 100644
--- a/tests/util.py
+++ b/tests/util.py
@@ -1,13 +1,17 @@
+import argparse
+import functools
 import os
+import shlex
 import sys
 import unittest
 from contextlib import contextmanager
-from dataclasses import replace
+from dataclasses import dataclass, field, replace
 from functools import partial
 from pathlib import Path
 from typing import Any, Iterator, List, Optional, Tuple
 
 import black
+from black.const import DEFAULT_LINE_LENGTH
 from black.debug import DebugVisitor
 from black.mode import TargetVersion
 from black.output import diff, err, out
@@ -35,6 +39,13 @@
 fs = partial(black.format_str, mode=DEFAULT_MODE)
 
 
+@dataclass
+class TestCaseArgs:
+    mode: black.Mode = field(default_factory=black.Mode)
+    fast: bool = False
+    minimum_version: Optional[Tuple[int, int]] = None
+
+
 def _assert_format_equal(expected: str, actual: str) -> None:
     if actual != expected and (conftest.PRINT_FULL_TREE or conftest.PRINT_TREE_DIFF):
         bdv: DebugVisitor[Any]
@@ -178,18 +189,85 @@ def get_case_path(
     return case_path
 
 
+def read_data_with_mode(
+    subdir_name: str, name: str, data: bool = True
+) -> Tuple[TestCaseArgs, str, str]:
+    """read_data_with_mode('test_name') -> Mode(), 'input', 'output'"""
+    return read_data_from_file(get_case_path(subdir_name, name, data))
+
+
 def read_data(subdir_name: str, name: str, data: bool = True) -> Tuple[str, str]:
     """read_data('test_name') -> 'input', 'output'"""
-    return read_data_from_file(get_case_path(subdir_name, name, data))
+    _, input, output = read_data_with_mode(subdir_name, name, data)
+    return input, output
+
+
+def _parse_minimum_version(version: str) -> Tuple[int, int]:
+    major, minor = version.split(".")
+    return int(major), int(minor)
 
 
-def read_data_from_file(file_name: Path) -> Tuple[str, str]:
+@functools.lru_cache()
+def get_flags_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--target-version",
+        action="append",
+        type=lambda val: TargetVersion[val.upper()],
+        default=(),
+    )
+    parser.add_argument("--line-length", default=DEFAULT_LINE_LENGTH, type=int)
+    parser.add_argument(
+        "--skip-string-normalization", default=False, action="store_true"
+    )
+    parser.add_argument("--pyi", default=False, action="store_true")
+    parser.add_argument("--ipynb", default=False, action="store_true")
+    parser.add_argument(
+        "--skip-magic-trailing-comma", default=False, action="store_true"
+    )
+    parser.add_argument("--preview", default=False, action="store_true")
+    parser.add_argument("--fast", default=False, action="store_true")
+    parser.add_argument(
+        "--minimum-version",
+        type=_parse_minimum_version,
+        default=None,
+        help=(
+            "Minimum version of Python where this test case is parseable. If this is"
+            " set, the test case will be run twice: once with the specified"
+            " --target-version, and once with --target-version set to exactly the"
+            " specified version. This ensures that Black's autodetection of the target"
+            " version works correctly."
+        ),
+    )
+    return parser
+
+
+def parse_mode(flags_line: str) -> TestCaseArgs:
+    parser = get_flags_parser()
+    args = parser.parse_args(shlex.split(flags_line))
+    mode = black.Mode(
+        target_versions=set(args.target_version),
+        line_length=args.line_length,
+        string_normalization=not args.skip_string_normalization,
+        is_pyi=args.pyi,
+        is_ipynb=args.ipynb,
+        magic_trailing_comma=not args.skip_magic_trailing_comma,
+        preview=args.preview,
+    )
+    return TestCaseArgs(mode=mode, fast=args.fast, minimum_version=args.minimum_version)
+
+
+def read_data_from_file(file_name: Path) -> Tuple[TestCaseArgs, str, str]:
     with open(file_name, "r", encoding="utf8") as test:
         lines = test.readlines()
     _input: List[str] = []
     _output: List[str] = []
     result = _input
+    mode = TestCaseArgs()
     for line in lines:
+        if not _input and line.startswith("# flags: "):
+            mode = parse_mode(line[len("# flags: ") :])
+            continue
         line = line.replace(EMPTY_LINE, "")
         if line.rstrip() == "# output":
             result = _output
@@ -199,7 +277,7 @@ def read_data_from_file(file_name: Path) -> Tuple[str, str]:
     if _input and not _output:
         # If there's no output marker, treat the entire file as already pre-formatted.
         _output = _input[:]
-    return "".join(_input).strip() + "\n", "".join(_output).strip() + "\n"
+    return mode, "".join(_input).strip() + "\n", "".join(_output).strip() + "\n"
 
 
 def read_jupyter_notebook(subdir_name: str, name: str, data: bool = True) -> str:

From 5d5bf6e0878539baeef797b87636235b8c02be3f Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Mon, 9 Oct 2023 18:44:36 -0700
Subject: [PATCH 0879/1034] Fix cache versioning when BLACK_CACHE_DIR is set
 (#3937)

---
 CHANGES.md          | 2 ++
 src/black/cache.py  | 3 ++-
 tests/test_black.py | 4 ++--
 3 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index ffc63b3287d..fe4b621a3e5 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -24,6 +24,8 @@
 
 <!-- Changes to how Black can be configured -->
 
+- Fix cache versioning logic when `BLACK_CACHE_DIR` is set (#3937)
+
 ### Packaging
 
 <!-- Changes to how Black is packaged, such as dependency requirements -->
diff --git a/src/black/cache.py b/src/black/cache.py
index 77f66cc34a9..f7dc64c0bca 100644
--- a/src/black/cache.py
+++ b/src/black/cache.py
@@ -36,8 +36,9 @@ def get_cache_dir() -> Path:
     repeated calls.
     """
     # NOTE: Function mostly exists as a clean way to test getting the cache directory.
-    default_cache_dir = user_cache_dir("black", version=__version__)
+    default_cache_dir = user_cache_dir("black")
     cache_dir = Path(os.environ.get("BLACK_CACHE_DIR", default_cache_dir))
+    cache_dir = cache_dir / __version__
     return cache_dir
 
 
diff --git a/tests/test_black.py b/tests/test_black.py
index bb5cc1e08c7..537ca80d432 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -1963,11 +1963,11 @@ def test_get_cache_dir(
         # If BLACK_CACHE_DIR is not set, use user_cache_dir
         monkeypatch.delenv("BLACK_CACHE_DIR", raising=False)
         with patch_user_cache_dir:
-            assert get_cache_dir() == workspace1
+            assert get_cache_dir().parent == workspace1
 
         # If it is set, use the path provided in the env var.
         monkeypatch.setenv("BLACK_CACHE_DIR", str(workspace2))
-        assert get_cache_dir() == workspace2
+        assert get_cache_dir().parent == workspace2
 
     def test_cache_broken_file(self) -> None:
         mode = DEFAULT_MODE

From 7aa37ea0adf864baf3ef3dfbcfaf5ff1ff780250 Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Mon, 9 Oct 2023 19:15:51 -0700
Subject: [PATCH 0880/1034] Report all stacktraces in verbose mode (#3938)

Previously these were swallowed (unlike the ones in black/__init__.py)
---
 CHANGES.md               | 2 ++
 src/black/concurrency.py | 7 +++++--
 2 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index fe4b621a3e5..6ad6308945c 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -44,6 +44,8 @@
 
 - Black no longer attempts to provide special errors for attempting to format Python 2
   code (#3933)
+- Black will more consistently print stacktraces on internal errors in verbose mode
+  (#3938)
 
 ### _Blackd_
 
diff --git a/src/black/concurrency.py b/src/black/concurrency.py
index ce016578399..55c96b66c86 100644
--- a/src/black/concurrency.py
+++ b/src/black/concurrency.py
@@ -9,6 +9,7 @@
 import os
 import signal
 import sys
+import traceback
 from concurrent.futures import Executor, ProcessPoolExecutor, ThreadPoolExecutor
 from multiprocessing import Manager
 from pathlib import Path
@@ -170,8 +171,10 @@ async def schedule_formatting(
             src = tasks.pop(task)
             if task.cancelled():
                 cancelled.append(task)
-            elif task.exception():
-                report.failed(src, str(task.exception()))
+            elif exc := task.exception():
+                if report.verbose:
+                    traceback.print_exception(type(exc), exc, exc.__traceback__)
+                report.failed(src, str(exc))
             else:
                 changed = Changed.YES if task.result() else Changed.NO
                 # If the file was written back or was successfully checked as

From b7717c3f1e73d6b847e2534a2cebbb657b96caf8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Dani=C3=ABl=20van=20Noord?=
 <13665637+DanielNoord@users.noreply.github.com>
Date: Tue, 10 Oct 2023 04:34:26 +0200
Subject: [PATCH 0881/1034] Standardise newlines after module-level docstrings
 (#3932)

Co-authored-by: jpy-git <josephyoung.jpy@gmail.com>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 CHANGES.md                                |  1 +
 scripts/make_width_table.py               |  1 +
 src/black/cache.py                        |  1 +
 src/black/linegen.py                      |  1 +
 src/black/lines.py                        |  9 +++
 src/black/mode.py                         |  1 +
 src/black/numerics.py                     |  1 +
 src/black/parsing.py                      |  1 +
 src/black/report.py                       |  1 +
 src/black/rusty.py                        |  1 +
 src/black/trans.py                        |  1 +
 tests/data/cases/module_docstring_1.py    | 26 +++++++++
 tests/data/cases/module_docstring_2.py    | 68 +++++++++++++++++++++++
 tests/data/cases/module_docstring_3.py    |  8 +++
 tests/data/cases/module_docstring_4.py    |  9 +++
 tests/data/miscellaneous/string_quotes.py |  2 +
 16 files changed, 132 insertions(+)
 create mode 100644 tests/data/cases/module_docstring_1.py
 create mode 100644 tests/data/cases/module_docstring_2.py
 create mode 100644 tests/data/cases/module_docstring_3.py
 create mode 100644 tests/data/cases/module_docstring_4.py

diff --git a/CHANGES.md b/CHANGES.md
index 6ad6308945c..a608551815f 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -19,6 +19,7 @@
 - Long type hints are now wrapped in parentheses and properly indented when split across
   multiple lines (#3899)
 - Magic trailing commas are now respected in return types. (#3916)
+- Require one empty line after module-level docstrings. (#3932)
 
 ### Configuration
 
diff --git a/scripts/make_width_table.py b/scripts/make_width_table.py
index 30fd32c34b0..061fdc8d95d 100644
--- a/scripts/make_width_table.py
+++ b/scripts/make_width_table.py
@@ -15,6 +15,7 @@
     pip install -U wcwidth
 
 """
+
 import sys
 from os.path import basename, dirname, join
 from typing import Iterable, Tuple
diff --git a/src/black/cache.py b/src/black/cache.py
index f7dc64c0bca..6baa096baca 100644
--- a/src/black/cache.py
+++ b/src/black/cache.py
@@ -1,4 +1,5 @@
 """Caching of formatted files with feature-based invalidation."""
+
 import hashlib
 import os
 import pickle
diff --git a/src/black/linegen.py b/src/black/linegen.py
index bdc4ee54ab2..faeb3ba664c 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -1,6 +1,7 @@
 """
 Generating lines of code.
 """
+
 import sys
 from dataclasses import replace
 from enum import Enum, auto
diff --git a/src/black/lines.py b/src/black/lines.py
index 71b657a0654..14754d7532f 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -550,6 +550,15 @@ def maybe_empty_lines(self, current_line: Line) -> LinesBlock:
             if self.previous_line is None
             else before - previous_after
         )
+        if (
+            Preview.module_docstring_newlines in current_line.mode
+            and self.previous_block
+            and self.previous_block.previous_block is None
+            and len(self.previous_block.original_line.leaves) == 1
+            and self.previous_block.original_line.is_triple_quoted_string
+        ):
+            before = 1
+
         block = LinesBlock(
             mode=self.mode,
             previous_block=self.previous_block,
diff --git a/src/black/mode.py b/src/black/mode.py
index 30c5d2f1b2f..baf886abb7f 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -187,6 +187,7 @@ class Preview(Enum):
     wrap_multiple_context_managers_in_parens = auto()
     dummy_implementations = auto()
     walrus_subscript = auto()
+    module_docstring_newlines = auto()
 
 
 class Deprecated(UserWarning):
diff --git a/src/black/numerics.py b/src/black/numerics.py
index 879e5b2cf36..67ac8595fcc 100644
--- a/src/black/numerics.py
+++ b/src/black/numerics.py
@@ -1,6 +1,7 @@
 """
 Formatting numeric literals.
 """
+
 from blib2to3.pytree import Leaf
 
 
diff --git a/src/black/parsing.py b/src/black/parsing.py
index 03e767a333b..ea282d1805c 100644
--- a/src/black/parsing.py
+++ b/src/black/parsing.py
@@ -1,6 +1,7 @@
 """
 Parse Python code and perform AST validation.
 """
+
 import ast
 import sys
 from typing import Iterable, Iterator, List, Set, Tuple
diff --git a/src/black/report.py b/src/black/report.py
index a507671e4c0..89899f2f389 100644
--- a/src/black/report.py
+++ b/src/black/report.py
@@ -1,6 +1,7 @@
 """
 Summarize Black runs to users.
 """
+
 from dataclasses import dataclass
 from enum import Enum
 from pathlib import Path
diff --git a/src/black/rusty.py b/src/black/rusty.py
index 84a80b5a2c2..ebd4c052d1f 100644
--- a/src/black/rusty.py
+++ b/src/black/rusty.py
@@ -2,6 +2,7 @@
 
 See https://doc.rust-lang.org/book/ch09-00-error-handling.html.
 """
+
 from typing import Generic, TypeVar, Union
 
 T = TypeVar("T")
diff --git a/src/black/trans.py b/src/black/trans.py
index c0cc92613ac..a2bff7f227a 100644
--- a/src/black/trans.py
+++ b/src/black/trans.py
@@ -1,6 +1,7 @@
 """
 String transformers that can split and merge strings.
 """
+
 import re
 from abc import ABC, abstractmethod
 from collections import defaultdict
diff --git a/tests/data/cases/module_docstring_1.py b/tests/data/cases/module_docstring_1.py
new file mode 100644
index 00000000000..d5897b4db60
--- /dev/null
+++ b/tests/data/cases/module_docstring_1.py
@@ -0,0 +1,26 @@
+# flags: --preview
+"""Single line module-level docstring should be followed by single newline."""
+
+
+
+
+a = 1
+
+
+"""I'm just a string so should be followed by 2 newlines."""
+
+
+
+
+b = 2
+
+# output
+"""Single line module-level docstring should be followed by single newline."""
+
+a = 1
+
+
+"""I'm just a string so should be followed by 2 newlines."""
+
+
+b = 2
diff --git a/tests/data/cases/module_docstring_2.py b/tests/data/cases/module_docstring_2.py
new file mode 100644
index 00000000000..e1f81b4d76b
--- /dev/null
+++ b/tests/data/cases/module_docstring_2.py
@@ -0,0 +1,68 @@
+# flags: --preview
+"""I am a very helpful module docstring.
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit,
+sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+Ut enim ad minim veniam,
+quis nostrud exercitation ullamco laboris
+nisi ut aliquip ex ea commodo consequat.
+Duis aute irure dolor in reprehenderit in voluptate
+velit esse cillum dolore eu fugiat nulla pariatur.
+Excepteur sint occaecat cupidatat non proident,
+sunt in culpa qui officia deserunt mollit anim id est laborum.
+"""
+
+
+
+
+a = 1
+
+
+"""Look at me I'm a docstring...
+
+............................................................
+............................................................
+............................................................
+............................................................
+............................................................
+............................................................
+............................................................
+........................................................NOT!
+"""
+
+
+
+
+b = 2
+
+# output
+"""I am a very helpful module docstring.
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit,
+sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+Ut enim ad minim veniam,
+quis nostrud exercitation ullamco laboris
+nisi ut aliquip ex ea commodo consequat.
+Duis aute irure dolor in reprehenderit in voluptate
+velit esse cillum dolore eu fugiat nulla pariatur.
+Excepteur sint occaecat cupidatat non proident,
+sunt in culpa qui officia deserunt mollit anim id est laborum.
+"""
+
+a = 1
+
+
+"""Look at me I'm a docstring...
+
+............................................................
+............................................................
+............................................................
+............................................................
+............................................................
+............................................................
+............................................................
+........................................................NOT!
+"""
+
+
+b = 2
diff --git a/tests/data/cases/module_docstring_3.py b/tests/data/cases/module_docstring_3.py
new file mode 100644
index 00000000000..0631e136a3d
--- /dev/null
+++ b/tests/data/cases/module_docstring_3.py
@@ -0,0 +1,8 @@
+# flags: --preview
+"""Single line module-level docstring should be followed by single newline."""
+a = 1
+
+# output
+"""Single line module-level docstring should be followed by single newline."""
+
+a = 1
diff --git a/tests/data/cases/module_docstring_4.py b/tests/data/cases/module_docstring_4.py
new file mode 100644
index 00000000000..515174dcc04
--- /dev/null
+++ b/tests/data/cases/module_docstring_4.py
@@ -0,0 +1,9 @@
+# flags: --preview
+"""Single line module-level docstring should be followed by single newline."""
+
+a = 1
+
+# output
+"""Single line module-level docstring should be followed by single newline."""
+
+a = 1
diff --git a/tests/data/miscellaneous/string_quotes.py b/tests/data/miscellaneous/string_quotes.py
index 3384241f4ad..6ec088ac79b 100644
--- a/tests/data/miscellaneous/string_quotes.py
+++ b/tests/data/miscellaneous/string_quotes.py
@@ -1,4 +1,5 @@
 ''''''
+
 '\''
 '"'
 "'"
@@ -59,6 +60,7 @@
 # output
 
 """"""
+
 "'"
 '"'
 "'"

From 935f303a0a7b794e722c7df00c906be285884874 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Mon, 9 Oct 2023 20:02:27 -0700
Subject: [PATCH 0882/1034] Fix test that was not being run (#3939)

---
 tests/data/{ => cases}/conditional_expression.py | 1 +
 1 file changed, 1 insertion(+)
 rename tests/data/{ => cases}/conditional_expression.py (99%)

diff --git a/tests/data/conditional_expression.py b/tests/data/cases/conditional_expression.py
similarity index 99%
rename from tests/data/conditional_expression.py
rename to tests/data/cases/conditional_expression.py
index 620a12dc986..c30cd76c791 100644
--- a/tests/data/conditional_expression.py
+++ b/tests/data/cases/conditional_expression.py
@@ -1,3 +1,4 @@
+# flags: --preview
 long_kwargs_single_line = my_function(
     foo="test, this is a sample value",
     bar=some_long_value_name_foo_bar_baz if some_boolean_variable else some_fallback_value_foo_bar_baz,

From 3bb92146f59804a6ead47d5f2d0fdc47daa6b698 Mon Sep 17 00:00:00 2001
From: rdrll <13176405+rdrll@users.noreply.github.com>
Date: Mon, 16 Oct 2023 05:13:53 -0700
Subject: [PATCH 0883/1034] CI Test: Deprecating 'Healthcheck.all()' from
 Hypothesis in fuzz.py (#3945)

---
 scripts/fuzz.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/fuzz.py b/scripts/fuzz.py
index 25362c927d4..0c507381d92 100644
--- a/scripts/fuzz.py
+++ b/scripts/fuzz.py
@@ -21,7 +21,7 @@
     max_examples=1000,  # roughly 1k tests/minute, or half that under coverage
     derandomize=True,  # deterministic mode to avoid CI flakiness
     deadline=None,  # ignore Hypothesis' health checks; we already know that
-    suppress_health_check=HealthCheck.all(),  # this is slow and filter-heavy.
+    suppress_health_check=list(HealthCheck),  # this is slow and filter-heavy.
 )
 @given(
     # Note that while Hypothesmith might generate code unlike that written by

From 6f84f652850dca8a1b578581e2fbb2cb95e791cc Mon Sep 17 00:00:00 2001
From: Charles Patel <17268094+acharles7@users.noreply.github.com>
Date: Mon, 16 Oct 2023 07:24:16 -0500
Subject: [PATCH 0884/1034] Migrate mypy config to pyproject.toml (#3936)

Co-authored-by: Charles Patel <charles.patel@apkudo.com>
---
 .gitignore                                 |  1 +
 .pre-commit-config.yaml                    |  5 +++
 mypy.ini                                   | 46 ----------------------
 pyproject.toml                             | 24 +++++++++++
 scripts/check_pre_commit_rev_in_example.py |  2 +-
 scripts/check_version_in_basics_example.py |  2 +-
 scripts/diff_shades_gha_helper.py          |  2 +-
 scripts/fuzz.py                            |  2 +-
 scripts/make_width_table.py                |  2 +-
 src/blackd/__init__.py                     |  4 +-
 tests/optional.py                          |  2 +-
 tests/test_blackd.py                       |  2 +-
 12 files changed, 40 insertions(+), 54 deletions(-)
 delete mode 100644 mypy.ini

diff --git a/.gitignore b/.gitignore
index 249499b135e..4a4f1b738ad 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,6 +4,7 @@
 _build
 .DS_Store
 .vscode
+.python-version
 docs/_static/pypi.svg
 .tox
 __pycache__
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 99b3565ed0e..623e661ac07 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -43,6 +43,7 @@ repos:
     hooks:
       - id: mypy
         exclude: ^docs/conf.py
+        args: ["--config-file", "pyproject.toml"]
         additional_dependencies:
           - types-PyYAML
           - tomli >= 0.2.6, < 2.0.0
@@ -51,6 +52,10 @@ repos:
           - platformdirs >= 2.1.0
           - pytest
           - hypothesis
+          - aiohttp >= 3.7.4
+          - types-commonmark
+          - urllib3
+          - hypothesmith
 
   - repo: https://github.com/pre-commit/mirrors-prettier
     rev: v3.0.3
diff --git a/mypy.ini b/mypy.ini
deleted file mode 100644
index ad916185bce..00000000000
--- a/mypy.ini
+++ /dev/null
@@ -1,46 +0,0 @@
-[mypy]
-# Specify the target platform details in config, so your developers are
-# free to run mypy on Windows, Linux, or macOS and get consistent
-# results.
-python_version=3.8
-
-mypy_path=src
-
-show_column_numbers=True
-show_error_codes=True
-
-# be strict
-strict=True
-
-# except for...
-no_implicit_reexport = False
-
-# Unreachable blocks have been an issue when compiling mypyc, let's try
-# to avoid 'em in the first place.
-warn_unreachable=True
-
-[mypy-blib2to3.driver.*]
-ignore_missing_imports = True
-
-[mypy-IPython.*]
-ignore_missing_imports = True
-
-[mypy-colorama.*]
-ignore_missing_imports = True
-
-[mypy-pathspec.*]
-ignore_missing_imports = True
-
-[mypy-tokenize_rt.*]
-ignore_missing_imports = True
-
-[mypy-uvloop.*]
-ignore_missing_imports = True
-
-[mypy-_black_version.*]
-ignore_missing_imports = True
-
-# CI only checks src/, but in case users are running LSP or similar we explicitly ignore
-# errors in test data files.
-[mypy-tests.data.*]
-ignore_errors = True
diff --git a/pyproject.toml b/pyproject.toml
index d246eb0b272..8c55076e4c9 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -137,6 +137,7 @@ exclude = [
   # Compiled modules can't be run directly and that's a problem here:
   "/src/black/__main__.py",
 ]
+mypy-args = ["--ignore-missing-imports"]
 options = { debug_level = "0" }
 
 [tool.cibuildwheel]
@@ -223,3 +224,26 @@ omit = [
 ]
 [tool.coverage.run]
 relative_files = true
+
+[tool.mypy]
+# Specify the target platform details in config, so your developers are
+# free to run mypy on Windows, Linux, or macOS and get consistent
+# results.
+python_version = "3.8"
+mypy_path = "src"
+strict = true
+# Unreachable blocks have been an issue when compiling mypyc, let's try to avoid 'em in the first place.
+warn_unreachable = true
+implicit_reexport = true
+show_error_codes = true
+show_column_numbers = true
+
+[[tool.mypy.overrides]]
+module = ["pathspec.*", "IPython.*", "colorama.*", "tokenize_rt.*", "uvloop.*", "_black_version.*"]
+ignore_missing_imports = true
+
+# CI only checks src/, but in case users are running LSP or similar we explicitly ignore
+# errors in test data files.
+[[tool.mypy.overrides]]
+module = ["tests.data.*"]
+ignore_errors = true
diff --git a/scripts/check_pre_commit_rev_in_example.py b/scripts/check_pre_commit_rev_in_example.py
index 9560b3b8401..107c6444dca 100644
--- a/scripts/check_pre_commit_rev_in_example.py
+++ b/scripts/check_pre_commit_rev_in_example.py
@@ -14,7 +14,7 @@
 
 import commonmark
 import yaml
-from bs4 import BeautifulSoup
+from bs4 import BeautifulSoup  # type: ignore[import]
 
 
 def main(changes: str, source_version_control: str) -> None:
diff --git a/scripts/check_version_in_basics_example.py b/scripts/check_version_in_basics_example.py
index 7f559b3aee1..0f42bafe334 100644
--- a/scripts/check_version_in_basics_example.py
+++ b/scripts/check_version_in_basics_example.py
@@ -8,7 +8,7 @@
 import sys
 
 import commonmark
-from bs4 import BeautifulSoup
+from bs4 import BeautifulSoup  # type: ignore[import]
 
 
 def main(changes: str, the_basics: str) -> None:
diff --git a/scripts/diff_shades_gha_helper.py b/scripts/diff_shades_gha_helper.py
index 7a58fbe9b28..895516deb51 100644
--- a/scripts/diff_shades_gha_helper.py
+++ b/scripts/diff_shades_gha_helper.py
@@ -119,7 +119,7 @@ def main() -> None:
 @main.command("config", help="Acquire run configuration and metadata.")
 @click.argument("event", type=click.Choice(["push", "pull_request"]))
 def config(event: Literal["push", "pull_request"]) -> None:
-    import diff_shades
+    import diff_shades  # type: ignore[import]
 
     if event == "push":
         jobs = [{"mode": "preview-changes", "force-flag": "--force-preview-style"}]
diff --git a/scripts/fuzz.py b/scripts/fuzz.py
index 0c507381d92..929d3eac4f5 100644
--- a/scripts/fuzz.py
+++ b/scripts/fuzz.py
@@ -80,7 +80,7 @@ def test_idempotent_any_syntatically_valid_python(
     try:
         import sys
 
-        import atheris
+        import atheris  # type: ignore[import]
     except ImportError:
         pass
     else:
diff --git a/scripts/make_width_table.py b/scripts/make_width_table.py
index 061fdc8d95d..3c7cae60f7f 100644
--- a/scripts/make_width_table.py
+++ b/scripts/make_width_table.py
@@ -20,7 +20,7 @@
 from os.path import basename, dirname, join
 from typing import Iterable, Tuple
 
-import wcwidth
+import wcwidth  # type: ignore[import]
 
 
 def make_width_table() -> Iterable[Tuple[int, int, int]]:
diff --git a/src/blackd/__init__.py b/src/blackd/__init__.py
index 6b0f3d33295..972f24181cb 100644
--- a/src/blackd/__init__.py
+++ b/src/blackd/__init__.py
@@ -74,7 +74,9 @@ def main(bind_host: str, bind_port: int) -> None:
     app = make_app()
     ver = black.__version__
     black.out(f"blackd version {ver} listening on {bind_host} port {bind_port}")
-    web.run_app(app, host=bind_host, port=bind_port, handle_signals=True, print=None)
+    # TODO: aiohttp had an incorrect annotation for `print` argument,
+    #  It'll be fixed once aiohttp releases that code
+    web.run_app(app, host=bind_host, port=bind_port, handle_signals=True, print=None)  # type: ignore[arg-type]
 
 
 def make_app() -> web.Application:
diff --git a/tests/optional.py b/tests/optional.py
index 8a39cc440a6..3f5277b6b03 100644
--- a/tests/optional.py
+++ b/tests/optional.py
@@ -26,7 +26,7 @@
     from pytest import StashKey
 except ImportError:
     # pytest < 7
-    from _pytest.store import StoreKey as StashKey  # type: ignore[no-redef]
+    from _pytest.store import StoreKey as StashKey  # type: ignore[import, no-redef]
 
 log = logging.getLogger(__name__)
 
diff --git a/tests/test_blackd.py b/tests/test_blackd.py
index c0152de73e6..59703036dc0 100644
--- a/tests/test_blackd.py
+++ b/tests/test_blackd.py
@@ -31,7 +31,7 @@ def unittest_run_loop(func, *args, **kwargs):
 
 
 @pytest.mark.blackd
-class BlackDTestCase(AioHTTPTestCase):  # type: ignore[misc]
+class BlackDTestCase(AioHTTPTestCase):
     def test_blackd_main(self) -> None:
         with patch("blackd.web.run_app"):
             result = CliRunner().invoke(blackd.main, [])

From 1648ac51806d092c95cb9bb2e4a5bffda6095bc1 Mon Sep 17 00:00:00 2001
From: Henri Holopainen <henri.i.holopainen@gmail.com>
Date: Mon, 16 Oct 2023 17:08:21 +0300
Subject: [PATCH 0885/1034] Fix long lines with power operator(s) getting
 splitted before line length (#3942)

Fixes #3889
---
 CHANGES.md                                   |  1 +
 src/black/linegen.py                         | 21 ++++-
 src/black/mode.py                            |  1 +
 tests/data/cases/power_op_spacing.py         | 18 ++++
 tests/data/cases/preview_power_op_spacing.py | 97 ++++++++++++++++++++
 5 files changed, 137 insertions(+), 1 deletion(-)
 create mode 100644 tests/data/cases/preview_power_op_spacing.py

diff --git a/CHANGES.md b/CHANGES.md
index a608551815f..d1c4a075c32 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -16,6 +16,7 @@
 
 <!-- Changes that affect Black's preview style -->
 
+- Fix long lines with power operators getting splitted before the line length (#3942)
 - Long type hints are now wrapped in parentheses and properly indented when split across
   multiple lines (#3899)
 - Magic trailing commas are now respected in return types. (#3916)
diff --git a/src/black/linegen.py b/src/black/linegen.py
index faeb3ba664c..d12ca39d037 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -536,6 +536,17 @@ def __post_init__(self) -> None:
         self.visit_case_block = self.visit_match_case
 
 
+def _hugging_power_ops_line_to_string(
+    line: Line,
+    features: Collection[Feature],
+    mode: Mode,
+) -> Optional[str]:
+    try:
+        return line_to_string(next(hug_power_op(line, features, mode)))
+    except CannotTransform:
+        return None
+
+
 def transform_line(
     line: Line, mode: Mode, features: Collection[Feature] = ()
 ) -> Iterator[Line]:
@@ -551,6 +562,14 @@ def transform_line(
 
     line_str = line_to_string(line)
 
+    # We need the line string when power operators are hugging to determine if we should
+    # split the line. Default to line_str, if no power operator are present on the line.
+    line_str_hugging_power_ops = (
+        (_hugging_power_ops_line_to_string(line, features, mode) or line_str)
+        if Preview.fix_power_op_line_length in mode
+        else line_str
+    )
+
     ll = mode.line_length
     sn = mode.string_normalization
     string_merge = StringMerger(ll, sn)
@@ -564,7 +583,7 @@ def transform_line(
         and not line.should_split_rhs
         and not line.magic_trailing_comma
         and (
-            is_line_short_enough(line, mode=mode, line_str=line_str)
+            is_line_short_enough(line, mode=mode, line_str=line_str_hugging_power_ops)
             or line.contains_unsplittable_type_ignore()
         )
         and not (line.inside_brackets and line.contains_standalone_comments())
diff --git a/src/black/mode.py b/src/black/mode.py
index baf886abb7f..a57fa373568 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -188,6 +188,7 @@ class Preview(Enum):
     dummy_implementations = auto()
     walrus_subscript = auto()
     module_docstring_newlines = auto()
+    fix_power_op_line_length = auto()
 
 
 class Deprecated(UserWarning):
diff --git a/tests/data/cases/power_op_spacing.py b/tests/data/cases/power_op_spacing.py
index c95fa788fc3..b3ef0aae084 100644
--- a/tests/data/cases/power_op_spacing.py
+++ b/tests/data/cases/power_op_spacing.py
@@ -29,6 +29,13 @@ def function_dont_replace_spaces():
 p = {(k, k**2): v**2 for k, v in pairs}
 q = [10**i for i in range(6)]
 r = x**y
+s = 1 ** 1
+t = (
+    1
+    ** 1
+    **1
+    ** 1
+)
 
 a = 5.0**~4.0
 b = 5.0 ** f()
@@ -47,6 +54,13 @@ def function_dont_replace_spaces():
 o = settings(max_examples=10**6.0)
 p = {(k, k**2): v**2.0 for k, v in pairs}
 q = [10.5**i for i in range(6)]
+s = 1.0 ** 1.0
+t = (
+    1.0
+    ** 1.0
+    **1.0
+    ** 1.0
+)
 
 
 # WE SHOULD DEFINITELY NOT EAT THESE COMMENTS (https://github.com/psf/black/issues/2873)
@@ -97,6 +111,8 @@ def function_dont_replace_spaces():
 p = {(k, k**2): v**2 for k, v in pairs}
 q = [10**i for i in range(6)]
 r = x**y
+s = 1**1
+t = 1**1**1**1
 
 a = 5.0**~4.0
 b = 5.0 ** f()
@@ -115,6 +131,8 @@ def function_dont_replace_spaces():
 o = settings(max_examples=10**6.0)
 p = {(k, k**2): v**2.0 for k, v in pairs}
 q = [10.5**i for i in range(6)]
+s = 1.0**1.0
+t = 1.0**1.0**1.0**1.0
 
 
 # WE SHOULD DEFINITELY NOT EAT THESE COMMENTS (https://github.com/psf/black/issues/2873)
diff --git a/tests/data/cases/preview_power_op_spacing.py b/tests/data/cases/preview_power_op_spacing.py
new file mode 100644
index 00000000000..650c6fecb20
--- /dev/null
+++ b/tests/data/cases/preview_power_op_spacing.py
@@ -0,0 +1,97 @@
+# flags: --preview
+a = 1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1
+b = 1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1
+c = 1 ** 1 ** 1 ** 1 ** 1 ** 1 ** 1 ** 1 ** 1 ** 1 ** 1 ** 1 ** 1 ** 1 ** 1 ** 1 ** 1 ** 1 ** 1 ** 1 ** 1 ** 1 ** 1 ** 1 ** 1 ** 1 ** 1 ** 1
+d = 1**1 ** 1**1 ** 1**1 ** 1**1 ** 1**1**1 ** 1 ** 1**1 ** 1**1**1**1**1 ** 1 ** 1**1**1 **1**1** 1 ** 1 ** 1
+e = 𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟
+f = 𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟
+
+a = 1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0
+b = 1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0
+c = 1.0 ** 1.0 ** 1.0 ** 1.0 ** 1.0 ** 1.0 ** 1.0 ** 1.0 ** 1.0 ** 1.0 ** 1.0 ** 1.0 ** 1.0 ** 1.0 ** 1.0 ** 1.0 ** 1.0
+d = 1.0**1.0 ** 1.0**1.0 ** 1.0**1.0 ** 1.0**1.0 ** 1.0**1.0**1.0 ** 1.0 ** 1.0**1.0 ** 1.0**1.0**1.0
+
+# output
+a = 1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1
+b = (
+    1
+    ** 1
+    ** 1
+    ** 1
+    ** 1
+    ** 1
+    ** 1
+    ** 1
+    ** 1
+    ** 1
+    ** 1
+    ** 1
+    ** 1
+    ** 1
+    ** 1
+    ** 1
+    ** 1
+    ** 1
+    ** 1
+    ** 1
+    ** 1
+    ** 1
+    ** 1
+    ** 1
+    ** 1
+    ** 1
+    ** 1
+    ** 1
+    ** 1
+)
+c = 1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1
+d = 1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1
+e = 𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟**𨉟
+f = (
+    𨉟
+    ** 𨉟
+    ** 𨉟
+    ** 𨉟
+    ** 𨉟
+    ** 𨉟
+    ** 𨉟
+    ** 𨉟
+    ** 𨉟
+    ** 𨉟
+    ** 𨉟
+    ** 𨉟
+    ** 𨉟
+    ** 𨉟
+    ** 𨉟
+    ** 𨉟
+    ** 𨉟
+    ** 𨉟
+    ** 𨉟
+    ** 𨉟
+    ** 𨉟
+    ** 𨉟
+)
+
+a = 1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0
+b = (
+    1.0
+    ** 1.0
+    ** 1.0
+    ** 1.0
+    ** 1.0
+    ** 1.0
+    ** 1.0
+    ** 1.0
+    ** 1.0
+    ** 1.0
+    ** 1.0
+    ** 1.0
+    ** 1.0
+    ** 1.0
+    ** 1.0
+    ** 1.0
+    ** 1.0
+    ** 1.0
+)
+c = 1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0
+d = 1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0**1.0

From abe57e3d92727f1b26c717fad3978159b987fe79 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Mon, 16 Oct 2023 10:51:51 -0700
Subject: [PATCH 0886/1034] Treat raw strings like other docstrings (#3947)

Fixes #3944
---
 CHANGES.md                  |  1 +
 src/black/lines.py          | 15 ++++++++++-----
 src/black/mode.py           |  1 +
 tests/data/raw_docstring.py | 32 ++++++++++++++++++++++++++++++++
 4 files changed, 44 insertions(+), 5 deletions(-)
 create mode 100644 tests/data/raw_docstring.py

diff --git a/CHANGES.md b/CHANGES.md
index d1c4a075c32..1f6a008d643 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -21,6 +21,7 @@
   multiple lines (#3899)
 - Magic trailing commas are now respected in return types. (#3916)
 - Require one empty line after module-level docstrings. (#3932)
+- Treat raw triple-quoted strings as docstrings (#3947)
 
 ### Configuration
 
diff --git a/src/black/lines.py b/src/black/lines.py
index 14754d7532f..48fde888208 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -193,11 +193,16 @@ def is_class_paren_empty(self) -> bool:
     @property
     def is_triple_quoted_string(self) -> bool:
         """Is the line a triple quoted string?"""
-        return (
-            bool(self)
-            and self.leaves[0].type == token.STRING
-            and self.leaves[0].value.startswith(('"""', "'''"))
-        )
+        if not self or self.leaves[0].type != token.STRING:
+            return False
+        value = self.leaves[0].value
+        if value.startswith(('"""', "'''")):
+            return True
+        if Preview.accept_raw_docstrings in self.mode and value.startswith(
+            ("r'''", 'r"""', "R'''", 'R"""')
+        ):
+            return True
+        return False
 
     @property
     def opens_block(self) -> bool:
diff --git a/src/black/mode.py b/src/black/mode.py
index a57fa373568..309f22dae94 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -188,6 +188,7 @@ class Preview(Enum):
     dummy_implementations = auto()
     walrus_subscript = auto()
     module_docstring_newlines = auto()
+    accept_raw_docstrings = auto()
     fix_power_op_line_length = auto()
 
 
diff --git a/tests/data/raw_docstring.py b/tests/data/raw_docstring.py
new file mode 100644
index 00000000000..751fd3201df
--- /dev/null
+++ b/tests/data/raw_docstring.py
@@ -0,0 +1,32 @@
+# flags: --preview --skip-string-normalization
+class C:
+
+    r"""Raw"""
+
+def f():
+
+    r"""Raw"""
+
+class SingleQuotes:
+
+
+    r'''Raw'''
+
+class UpperCaseR:
+    R"""Raw"""
+
+# output
+class C:
+    r"""Raw"""
+
+
+def f():
+    r"""Raw"""
+
+
+class SingleQuotes:
+    r'''Raw'''
+
+
+class UpperCaseR:
+    R"""Raw"""

From 722735d20ebdc66c0da0e0df7658293455694500 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Mon, 16 Oct 2023 10:53:38 -0700
Subject: [PATCH 0887/1034] Fix grammar for type alias support (#3949)

Fixes #3948
---
 CHANGES.md                       | 3 +++
 src/blib2to3/Grammar.txt         | 2 +-
 tests/data/cases/type_aliases.py | 7 +++++++
 3 files changed, 11 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index 1f6a008d643..610a9de0e43 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -37,6 +37,9 @@
 
 <!-- Changes to the parser or to version autodetection -->
 
+- Add support for PEP 695 type aliases containing lambdas and other unusual expressions
+  (#3949)
+
 ### Performance
 
 <!-- Changes that improve Black's performance. -->
diff --git a/src/blib2to3/Grammar.txt b/src/blib2to3/Grammar.txt
index be91df75740..5db78723cec 100644
--- a/src/blib2to3/Grammar.txt
+++ b/src/blib2to3/Grammar.txt
@@ -108,7 +108,7 @@ dotted_as_names: dotted_as_name (',' dotted_as_name)*
 dotted_name: NAME ('.' NAME)*
 global_stmt: ('global' | 'nonlocal') NAME (',' NAME)*
 assert_stmt: 'assert' test [',' test]
-type_stmt: "type" NAME [typeparams] '=' expr
+type_stmt: "type" NAME [typeparams] '=' test
 
 compound_stmt: if_stmt | while_stmt | for_stmt | try_stmt | with_stmt | funcdef | classdef | decorated | async_stmt | match_stmt
 async_stmt: ASYNC (funcdef | with_stmt | for_stmt)
diff --git a/tests/data/cases/type_aliases.py b/tests/data/cases/type_aliases.py
index a3c1931c9fc..9631bfd5ccc 100644
--- a/tests/data/cases/type_aliases.py
+++ b/tests/data/cases/type_aliases.py
@@ -1,6 +1,10 @@
 # flags: --minimum-version=3.12
+
 type A=int
 type Gen[T]=list[T]
+type Alias[T]=lambda: T
+type And[T]=T and T
+type IfElse[T]=T if T else T
 
 type = aliased
 print(type(42))
@@ -9,6 +13,9 @@
 
 type A = int
 type Gen[T] = list[T]
+type Alias[T] = lambda: T
+type And[T] = T and T
+type IfElse[T] = T if T else T
 
 type = aliased
 print(type(42))

From bb588073ab286a9f1f8d839ab2cebe13011dd22c Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Tue, 17 Oct 2023 00:59:15 -0700
Subject: [PATCH 0888/1034] Fix parser bug where "type" was misinterpreted as a
 keyword inside a match (#3950)

Fixes #3790

Slightly hacky, but I think this is correct and it should also improve performance somewhat.
---
 CHANGES.md                                   |  2 ++
 src/blib2to3/pgen2/parse.py                  | 19 ++++++++++++++++++-
 tests/data/cases/pattern_matching_complex.py |  4 ++++
 tests/data/cases/type_aliases.py             |  9 +++++++++
 4 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index 610a9de0e43..f89b1b9df0a 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -37,6 +37,8 @@
 
 <!-- Changes to the parser or to version autodetection -->
 
+- Fix bug where attributes named `type` were not acccepted inside `match` statements
+  (#3950)
 - Add support for PEP 695 type aliases containing lambdas and other unusual expressions
   (#3949)
 
diff --git a/src/blib2to3/pgen2/parse.py b/src/blib2to3/pgen2/parse.py
index 299cc24a15f..ad51a3dad08 100644
--- a/src/blib2to3/pgen2/parse.py
+++ b/src/blib2to3/pgen2/parse.py
@@ -211,6 +211,7 @@ def __init__(self, grammar: Grammar, convert: Optional[Convert] = None) -> None:
         # See note in docstring above. TL;DR this is ignored.
         self.convert = convert or lam_sub
         self.is_backtracking = False
+        self.last_token: Optional[int] = None
 
     def setup(self, proxy: "TokenProxy", start: Optional[int] = None) -> None:
         """Prepare for parsing.
@@ -236,6 +237,7 @@ def setup(self, proxy: "TokenProxy", start: Optional[int] = None) -> None:
         self.rootnode: Optional[NL] = None
         self.used_names: Set[str] = set()
         self.proxy = proxy
+        self.last_token = None
 
     def addtoken(self, type: int, value: str, context: Context) -> bool:
         """Add a token; return True iff this is the end of the program."""
@@ -317,6 +319,7 @@ def _addtoken(self, ilabel: int, type: int, value: str, context: Context) -> boo
                         dfa, state, node = self.stack[-1]
                         states, first = dfa
                     # Done with this token
+                    self.last_token = type
                     return False
 
             else:
@@ -343,9 +346,23 @@ def classify(self, type: int, value: str, context: Context) -> List[int]:
                 return [self.grammar.keywords[value]]
             elif value in self.grammar.soft_keywords:
                 assert type in self.grammar.tokens
+                # Current soft keywords (match, case, type) can only appear at the
+                # beginning of a statement. So as a shortcut, don't try to treat them
+                # like keywords in any other context.
+                # ('_' is also a soft keyword in the real grammar, but for our grammar
+                # it's just an expression, so we don't need to treat it specially.)
+                if self.last_token not in (
+                    None,
+                    token.INDENT,
+                    token.DEDENT,
+                    token.NEWLINE,
+                    token.SEMI,
+                    token.COLON,
+                ):
+                    return [self.grammar.tokens[type]]
                 return [
-                    self.grammar.soft_keywords[value],
                     self.grammar.tokens[type],
+                    self.grammar.soft_keywords[value],
                 ]
 
         ilabel = self.grammar.tokens.get(type)
diff --git a/tests/data/cases/pattern_matching_complex.py b/tests/data/cases/pattern_matching_complex.py
index b4355c7333a..10b4d26e289 100644
--- a/tests/data/cases/pattern_matching_complex.py
+++ b/tests/data/cases/pattern_matching_complex.py
@@ -143,3 +143,7 @@
         y = 1
     case []:
         y = 2
+# issue 3790
+match (X.type, Y):
+    case _:
+        pass
diff --git a/tests/data/cases/type_aliases.py b/tests/data/cases/type_aliases.py
index 9631bfd5ccc..7c2009e8202 100644
--- a/tests/data/cases/type_aliases.py
+++ b/tests/data/cases/type_aliases.py
@@ -5,6 +5,8 @@
 type Alias[T]=lambda: T
 type And[T]=T and T
 type IfElse[T]=T if T else T
+type One = int; type Another = str
+class X: type InClass = int
 
 type = aliased
 print(type(42))
@@ -16,6 +18,13 @@
 type Alias[T] = lambda: T
 type And[T] = T and T
 type IfElse[T] = T if T else T
+type One = int
+type Another = str
+
+
+class X:
+    type InClass = int
+
 
 type = aliased
 print(type(42))

From 9edba85f71d50d12996ef7bda576426362016171 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Tue, 17 Oct 2023 07:22:24 -0700
Subject: [PATCH 0889/1034] Prepare release 23.10.0 (#3951)

---
 CHANGES.md                                  | 60 +++++++++++++--------
 docs/integrations/source_version_control.md |  4 +-
 docs/usage_and_configuration/the_basics.md  |  6 +--
 3 files changed, 42 insertions(+), 28 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index f89b1b9df0a..2a50e456550 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -10,25 +10,14 @@
 
 <!-- Changes that affect Black's stable style -->
 
-- Fix comments getting removed from inside parenthesized strings (#3909)
-
 ### Preview style
 
 <!-- Changes that affect Black's preview style -->
 
-- Fix long lines with power operators getting splitted before the line length (#3942)
-- Long type hints are now wrapped in parentheses and properly indented when split across
-  multiple lines (#3899)
-- Magic trailing commas are now respected in return types. (#3916)
-- Require one empty line after module-level docstrings. (#3932)
-- Treat raw triple-quoted strings as docstrings (#3947)
-
 ### Configuration
 
 <!-- Changes to how Black can be configured -->
 
-- Fix cache versioning logic when `BLACK_CACHE_DIR` is set (#3937)
-
 ### Packaging
 
 <!-- Changes to how Black is packaged, such as dependency requirements -->
@@ -37,11 +26,6 @@
 
 <!-- Changes to the parser or to version autodetection -->
 
-- Fix bug where attributes named `type` were not acccepted inside `match` statements
-  (#3950)
-- Add support for PEP 695 type aliases containing lambdas and other unusual expressions
-  (#3949)
-
 ### Performance
 
 <!-- Changes that improve Black's performance. -->
@@ -50,11 +34,6 @@
 
 <!-- Changes to Black's terminal output and error messages -->
 
-- Black no longer attempts to provide special errors for attempting to format Python 2
-  code (#3933)
-- Black will more consistently print stacktraces on internal errors in verbose mode
-  (#3938)
-
 ### _Blackd_
 
 <!-- Changes to blackd -->
@@ -63,13 +42,48 @@
 
 <!-- For example, Docker, GitHub Actions, pre-commit, editors -->
 
-- The action output displayed in the job summary is now wrapped in Markdown (#3914)
-
 ### Documentation
 
 <!-- Major changes to documentation and policies. Small docs changes
      don't need a changelog entry. -->
 
+## 23.10.0
+
+### Stable style
+
+- Fix comments getting removed from inside parenthesized strings (#3909)
+
+### Preview style
+
+- Fix long lines with power operators getting split before the line length (#3942)
+- Long type hints are now wrapped in parentheses and properly indented when split across
+  multiple lines (#3899)
+- Magic trailing commas are now respected in return types. (#3916)
+- Require one empty line after module-level docstrings. (#3932)
+- Treat raw triple-quoted strings as docstrings (#3947)
+
+### Configuration
+
+- Fix cache versioning logic when `BLACK_CACHE_DIR` is set (#3937)
+
+### Parser
+
+- Fix bug where attributes named `type` were not acccepted inside `match` statements
+  (#3950)
+- Add support for PEP 695 type aliases containing lambdas and other unusual expressions
+  (#3949)
+
+### Output
+
+- Black no longer attempts to provide special errors for attempting to format Python 2
+  code (#3933)
+- Black will more consistently print stacktraces on internal errors in verbose mode
+  (#3938)
+
+### Integrations
+
+- The action output displayed in the job summary is now wrapped in Markdown (#3914)
+
 ## 23.9.1
 
 Due to various issues, the previous release (23.9.0) did not include compiled mypyc
diff --git a/docs/integrations/source_version_control.md b/docs/integrations/source_version_control.md
index 2afcc02f3cd..16354f849ba 100644
--- a/docs/integrations/source_version_control.md
+++ b/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.9.1
+    rev: 23.10.0
     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.9.1
+    rev: 23.10.0
     hooks:
       - id: black-jupyter
         # It is recommended to specify the latest version of Python
diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index 36119f225e6..5b132a95eae 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -194,8 +194,8 @@ configuration file for consistent results across environments.
 
 ```console
 $ black --version
-black, 23.9.1 (compiled: yes)
-$ black --required-version 23.9.1 -c "format = 'this'"
+black, 23.10.0 (compiled: yes)
+$ black --required-version 23.10.0 -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.9.1
+black, 23.10.0
 ```
 
 #### `--config`

From 882d8795c6ff65c02f2657e596391748d1b6b7f5 Mon Sep 17 00:00:00 2001
From: Henri Holopainen <henri.i.holopainen@gmail.com>
Date: Fri, 20 Oct 2023 06:09:33 +0300
Subject: [PATCH 0890/1034] Fix merging implicit multiline strings that have
 inline comments (#3956)

* Fix test behaviour

* Add new test cases

* Skip merging strings that have inline comments

* Don't merge lines with multiline strings with inline comments

* Changelog entry

* Document implicit multiline string merging rules

* Fix PR number
---
 CHANGES.md                                    |  2 +-
 docs/the_black_code_style/future_style.md     | 64 +++++++++++++++++++
 src/black/linegen.py                          |  1 +
 src/black/lines.py                            | 15 +++++
 src/black/trans.py                            | 14 +++-
 .../cases/preview_long_strings__regression.py |  6 +-
 tests/data/cases/preview_multiline_strings.py | 28 ++++++++
 7 files changed, 125 insertions(+), 5 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 2a50e456550..79b5c6034e8 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -12,7 +12,7 @@
 
 ### Preview style
 
-<!-- Changes that affect Black's preview style -->
+- Fix merging implicit multiline strings that have inline comments (#3956)
 
 ### Configuration
 
diff --git a/docs/the_black_code_style/future_style.md b/docs/the_black_code_style/future_style.md
index 861bb64bff4..367ff98537c 100644
--- a/docs/the_black_code_style/future_style.md
+++ b/docs/the_black_code_style/future_style.md
@@ -160,3 +160,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
+)
+```
diff --git a/src/black/linegen.py b/src/black/linegen.py
index d12ca39d037..2bfe587fa0e 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -587,6 +587,7 @@ def transform_line(
             or line.contains_unsplittable_type_ignore()
         )
         and not (line.inside_brackets and line.contains_standalone_comments())
+        and not line.contains_implicit_multiline_string_with_comments()
     ):
         # Only apply basic string preprocessing, since lines shouldn't be split here.
         if Preview.string_processing in mode:
diff --git a/src/black/lines.py b/src/black/lines.py
index 48fde888208..6acc95e7a7e 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -239,6 +239,21 @@ def contains_standalone_comments(self, depth_limit: int = sys.maxsize) -> bool:
 
         return False
 
+    def contains_implicit_multiline_string_with_comments(self) -> bool:
+        """Chck if we have an implicit multiline string with comments on the line"""
+        for leaf_type, leaf_group_iterator in itertools.groupby(
+            self.leaves, lambda leaf: leaf.type
+        ):
+            if leaf_type != token.STRING:
+                continue
+            leaf_list = list(leaf_group_iterator)
+            if len(leaf_list) == 1:
+                continue
+            for leaf in leaf_list:
+                if self.comments_after(leaf):
+                    return True
+        return False
+
     def contains_uncollapsable_type_comments(self) -> bool:
         ignored_ids = set()
         try:
diff --git a/src/black/trans.py b/src/black/trans.py
index a2bff7f227a..a3f6467cc9e 100644
--- a/src/black/trans.py
+++ b/src/black/trans.py
@@ -390,7 +390,19 @@ def do_match(self, line: Line) -> TMatchResult:
                 and is_valid_index(idx + 1)
                 and LL[idx + 1].type == token.STRING
             ):
-                if not is_part_of_annotation(leaf):
+                # Let's check if the string group contains an inline comment
+                # If we have a comment inline, we don't merge the strings
+                contains_comment = False
+                i = idx
+                while is_valid_index(i):
+                    if LL[i].type != token.STRING:
+                        break
+                    if line.comments_after(LL[i]):
+                        contains_comment = True
+                        break
+                    i += 1
+
+                if not is_part_of_annotation(leaf) and not contains_comment:
                     string_indices.append(idx)
 
                 # Advance to the next non-STRING leaf.
diff --git a/tests/data/cases/preview_long_strings__regression.py b/tests/data/cases/preview_long_strings__regression.py
index 40d5e745cc8..436157f4e05 100644
--- a/tests/data/cases/preview_long_strings__regression.py
+++ b/tests/data/cases/preview_long_strings__regression.py
@@ -210,8 +210,8 @@ def foo():
 
 some_tuple = ("some string", "some string" " which should be joined")
 
-some_commented_string = (
-    "This string is long but not so long that it needs hahahah toooooo be so greatttt"  # This comment gets thrown to the top.
+some_commented_string = (  # This comment stays at the top.
+    "This string is long but not so long that it needs hahahah toooooo be so greatttt"
     " {} that I just can't think of any more good words to say about it at"
     " allllllllllll".format("ha")  # comments here are fine
 )
@@ -834,7 +834,7 @@ def foo():
 
 some_tuple = ("some string", "some string which should be joined")
 
-some_commented_string = (  # This comment gets thrown to the top.
+some_commented_string = (  # This comment stays at the top.
     "This string is long but not so long that it needs hahahah toooooo be so greatttt"
     " {} that I just can't think of any more good words to say about it at"
     " allllllllllll".format("ha")  # comments here are fine
diff --git a/tests/data/cases/preview_multiline_strings.py b/tests/data/cases/preview_multiline_strings.py
index dec4ef2e548..3ff643610b7 100644
--- a/tests/data/cases/preview_multiline_strings.py
+++ b/tests/data/cases/preview_multiline_strings.py
@@ -157,6 +157,24 @@ def dastardly_default_value(
 `--global-option` is reserved to flags like `--verbose` or `--quiet`.
 """
 
+this_will_become_one_line = (
+    "a"
+    "b"
+    "c"
+)
+
+this_will_stay_on_three_lines = (
+    "a"  # comment
+    "b"
+    "c"
+)
+
+this_will_also_become_one_line = (  # comment
+    "a"
+    "b"
+    "c"
+)
+
 # output
 """cow
 say""",
@@ -357,3 +375,13 @@ def dastardly_default_value(
 Please use `--build-option` instead,
 `--global-option` is reserved to flags like `--verbose` or `--quiet`.
 """
+
+this_will_become_one_line = "abc"
+
+this_will_stay_on_three_lines = (
+    "a"  # comment
+    "b"
+    "c"
+)
+
+this_will_also_become_one_line = "abc"  # comment

From 0a37888e79059018eef9293a724b14da59d3377a Mon Sep 17 00:00:00 2001
From: Aniket Patil <128228805+AniketP04@users.noreply.github.com>
Date: Mon, 23 Oct 2023 02:46:43 +0530
Subject: [PATCH 0891/1034] Fix typos in CHANGES.md (#3963)

---
 CHANGES.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 79b5c6034e8..a75b54d8d81 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -68,7 +68,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)
@@ -926,7 +926,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)
 

From 2db5ab0a7b3b321e4cec70964239ee88087cd810 Mon Sep 17 00:00:00 2001
From: Henri Holopainen <henri.i.holopainen@gmail.com>
Date: Mon, 23 Oct 2023 17:38:36 +0300
Subject: [PATCH 0892/1034] Allow empty line after block open before a comment
 or compound statement (#3967)

---
 CHANGES.md                                    |   1 +
 src/black/lines.py                            |  27 ++++-
 src/black/mode.py                             |   1 +
 src/black/nodes.py                            |   4 +
 ...allow_empty_first_line_in_special_cases.py | 106 ++++++++++++++++++
 5 files changed, 138 insertions(+), 1 deletion(-)
 create mode 100644 tests/data/cases/preview_allow_empty_first_line_in_special_cases.py

diff --git a/CHANGES.md b/CHANGES.md
index a75b54d8d81..86e820a6fd9 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -13,6 +13,7 @@
 ### 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)
 
 ### Configuration
 
diff --git a/src/black/lines.py b/src/black/lines.py
index 6acc95e7a7e..a73c429e3d9 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -24,6 +24,8 @@
     STANDALONE_COMMENT,
     TEST_DESCENDANTS,
     child_towards,
+    is_docstring,
+    is_funcdef,
     is_import,
     is_multiline_string,
     is_one_sequence_between,
@@ -686,7 +688,30 @@ def _maybe_empty_lines(self, current_line: Line) -> Tuple[int, int]:
                 return 0, 1
             return before, 1
 
-        if self.previous_line and self.previous_line.opens_block:
+        is_empty_first_line_ok = (
+            Preview.allow_empty_first_line_before_new_block_or_comment
+            in current_line.mode
+            and (
+                # If it's a standalone comment
+                current_line.leaves[0].type == STANDALONE_COMMENT
+                # If it opens a new block
+                or current_line.opens_block
+                # If it's a triple quote comment (but not at the start of a funcdef)
+                or (
+                    is_docstring(current_line.leaves[0])
+                    and self.previous_line
+                    and self.previous_line.leaves[0]
+                    and self.previous_line.leaves[0].parent
+                    and not is_funcdef(self.previous_line.leaves[0].parent)
+                )
+            )
+        )
+
+        if (
+            self.previous_line
+            and self.previous_line.opens_block
+            and not is_empty_first_line_ok
+        ):
             return 0, 0
         return before, 0
 
diff --git a/src/black/mode.py b/src/black/mode.py
index 309f22dae94..4effeef3e7c 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -190,6 +190,7 @@ class Preview(Enum):
     module_docstring_newlines = auto()
     accept_raw_docstrings = auto()
     fix_power_op_line_length = auto()
+    allow_empty_first_line_before_new_block_or_comment = auto()
 
 
 class Deprecated(UserWarning):
diff --git a/src/black/nodes.py b/src/black/nodes.py
index edd201a21e9..b2e96cb9edf 100644
--- a/src/black/nodes.py
+++ b/src/black/nodes.py
@@ -718,6 +718,10 @@ def is_multiline_string(leaf: Leaf) -> bool:
     return has_triple_quotes(leaf.value) and "\n" in leaf.value
 
 
+def is_funcdef(node: Node) -> bool:
+    return node.type == syms.funcdef
+
+
 def is_stub_suite(node: Node) -> bool:
     """Return True if `node` is a suite with a stub body."""
 
diff --git a/tests/data/cases/preview_allow_empty_first_line_in_special_cases.py b/tests/data/cases/preview_allow_empty_first_line_in_special_cases.py
new file mode 100644
index 00000000000..96c1433c110
--- /dev/null
+++ b/tests/data/cases/preview_allow_empty_first_line_in_special_cases.py
@@ -0,0 +1,106 @@
+# flags: --preview
+def foo():
+    """
+    Docstring
+    """
+
+    # Here we go
+    if x:
+
+        # This is also now fine
+        a = 123
+
+    else:
+        # But not necessary
+        a = 123
+
+    if y:
+
+        while True:
+
+            """
+            Long comment here
+            """
+            a = 123
+    
+    if z:
+
+        for _ in range(100):
+            a = 123
+    else:
+
+        try:
+
+            # this should be ok
+            a = 123
+        except:
+
+            """also this"""
+            a = 123
+
+
+def bar():
+
+    if x:
+        a = 123
+
+
+def baz():
+
+    # OK
+    if x:
+        a = 123
+
+# output
+
+def foo():
+    """
+    Docstring
+    """
+
+    # Here we go
+    if x:
+
+        # This is also now fine
+        a = 123
+
+    else:
+        # But not necessary
+        a = 123
+
+    if y:
+
+        while True:
+
+            """
+            Long comment here
+            """
+            a = 123
+
+    if z:
+
+        for _ in range(100):
+            a = 123
+    else:
+
+        try:
+
+            # this should be ok
+            a = 123
+        except:
+
+            """also this"""
+            a = 123
+
+
+def bar():
+
+    if x:
+        a = 123
+
+
+def baz():
+
+    # OK
+    if x:
+        a = 123

From 7f1c578b89b2c256a6ce3b70fc1b970b3ffa3349 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 23 Oct 2023 07:42:49 -0700
Subject: [PATCH 0893/1034] Bump peter-evans/create-or-update-comment from
 3.0.2 to 3.1.0 (#3966)

Bumps [peter-evans/create-or-update-comment](https://github.com/peter-evans/create-or-update-comment) from 3.0.2 to 3.1.0.
- [Release notes](https://github.com/peter-evans/create-or-update-comment/releases)
- [Commits](https://github.com/peter-evans/create-or-update-comment/compare/c6c9a1a66007646a28c153e2a8580a5bad27bcfa...23ff15729ef2fc348714a3bb66d2f655ca9066f2)

---
updated-dependencies:
- dependency-name: peter-evans/create-or-update-comment
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/diff_shades_comment.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/diff_shades_comment.yml b/.github/workflows/diff_shades_comment.yml
index b86bd93410e..49fd376d85e 100644
--- a/.github/workflows/diff_shades_comment.yml
+++ b/.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 }}

From d291c2338c3c1feee4f3f26985c0964ec1b7eb9f Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Mon, 23 Oct 2023 08:36:47 -0700
Subject: [PATCH 0894/1034] Move Docker image to hatch + compile (#3965)

---
 CHANGES.md                                         |  2 ++
 Dockerfile                                         | 12 +++++++-----
 docs/usage_and_configuration/black_docker_image.md |  2 ++
 3 files changed, 11 insertions(+), 5 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 86e820a6fd9..fe0b2ebb9d8 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -23,6 +23,8 @@
 
 <!-- Changes to how Black is packaged, such as dependency requirements -->
 
+- Change Dockerfile to hatch + compile black (#3965)
+
 ### Parser
 
 <!-- Changes to the parser or to version autodetection -->
diff --git a/Dockerfile b/Dockerfile
index a9e0ea5081e..bfd9acccb99 100644
--- a/Dockerfile
+++ b/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
 
diff --git a/docs/usage_and_configuration/black_docker_image.md b/docs/usage_and_configuration/black_docker_image.md
index 85aec91ef1c..c97c25af328 100644
--- a/docs/usage_and_configuration/black_docker_image.md
+++ b/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

From a7643fac8d97c15640a2b1a79f68b3dc771aebfb Mon Sep 17 00:00:00 2001
From: Dario Curreri <48800335+dariocurr@users.noreply.github.com>
Date: Mon, 23 Oct 2023 18:40:09 +0200
Subject: [PATCH 0895/1034] Add summary parameter to action (#3958)

---
 CHANGES.md |  3 ++-
 action.yml | 14 ++++++++++----
 2 files changed, 12 insertions(+), 5 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index fe0b2ebb9d8..89837c8f545 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -43,7 +43,8 @@
 
 ### Integrations
 
-<!-- For example, Docker, GitHub Actions, pre-commit, editors -->
+- The summary output for GitHub workflows is now suppressible using the `summary`
+  parameter. (#3958)
 
 ### Documentation
 
diff --git a/action.yml b/action.yml
index 8b698ae3c80..a22005ac243 100644
--- a/action.yml
+++ b/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"
@@ -47,10 +51,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}

From c0adca321dc0d97a704de8ed0353e5b894a6a912 Mon Sep 17 00:00:00 2001
From: William Moreno <williamjmorenor@gmail.com>
Date: Mon, 23 Oct 2023 11:21:58 -0600
Subject: [PATCH 0896/1034] docs: specifies the use of the
 .git-blame-ignore-revs file (#3961)

---
 docs/guides/introducing_black_to_your_project.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/guides/introducing_black_to_your_project.md b/docs/guides/introducing_black_to_your_project.md
index 71a566fbda1..3927eb1a386 100644
--- a/docs/guides/introducing_black_to_your_project.md
+++ b/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

From 8de4be516879302afce542ac80a6a43ced807759 Mon Sep 17 00:00:00 2001
From: Kiyoon Kim <yoonkr33@gmail.com>
Date: Tue, 24 Oct 2023 02:37:14 +0900
Subject: [PATCH 0897/1034] Fix CI failing (#3957)

* Fix CI failing

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* docs: update CHANGES.md

* docs: fix changelog location to unreleased

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 CHANGES.md | 2 ++
 action.yml | 3 +++
 2 files changed, 5 insertions(+)

diff --git a/CHANGES.md b/CHANGES.md
index 89837c8f545..7e1ed79cd48 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -46,6 +46,8 @@
 - 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
 
 <!-- Major changes to documentation and policies. Small docs changes
diff --git a/action.yml b/action.yml
index a22005ac243..49cd6b06e4c 100644
--- a/action.yml
+++ b/action.yml
@@ -39,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

From 744d23b34800c06e10272149b70752396e90eeb8 Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Mon, 23 Oct 2023 10:59:16 -0700
Subject: [PATCH 0898/1034] Prepare release 23.10.1 (#3969)

* Prepare release 23.10.1

* Update docs/usage_and_configuration/the_basics.md

Add missed version string

We need to automate or remove this from docs ... It's painful.

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>

---------

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 CHANGES.md                                  | 35 +++------------------
 docs/integrations/source_version_control.md |  4 +--
 docs/usage_and_configuration/the_basics.md  |  6 ++--
 3 files changed, 9 insertions(+), 36 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 7e1ed79cd48..1e90c12b4fb 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,57 +1,30 @@
 # Change Log
 
-## Unreleased
+## 23.10.1
 
 ### Highlights
 
-<!-- Include any especially major or disruptive changes here -->
-
-### Stable style
-
-<!-- Changes that affect Black's stable style -->
+- Maintanence 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)
 
-### Configuration
-
-<!-- Changes to how Black can be configured -->
-
 ### Packaging
 
-<!-- Changes to how Black is packaged, such as dependency requirements -->
-
 - Change Dockerfile to hatch + compile black (#3965)
 
-### Parser
-
-<!-- Changes to the parser or to version autodetection -->
-
-### Performance
-
-<!-- Changes that improve Black's performance. -->
-
-### Output
-
-<!-- Changes to Black's terminal output and error messages -->
-
-### _Blackd_
-
-<!-- Changes to blackd -->
-
 ### 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
 
-<!-- Major changes to documentation and policies. Small docs changes
-     don't need a changelog entry. -->
+- It is known Windows documentation CI is broken
+  https://github.com/psf/black/issues/3968
 
 ## 23.10.0
 
diff --git a/docs/integrations/source_version_control.md b/docs/integrations/source_version_control.md
index 16354f849ba..597a6b993c7 100644
--- a/docs/integrations/source_version_control.md
+++ b/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
diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index 5b132a95eae..f25dbb13d4d 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/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`

From ef1048d5f8205cb03358a6a373710c2a71d047b4 Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Mon, 23 Oct 2023 23:26:40 -0700
Subject: [PATCH 0899/1034] Add Unreleased template to CHANGES.md (#3973)

Add Unreleased template to CHANGES.md - Did this via tool working on in another branch
---
 CHANGES.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/CHANGES.md b/CHANGES.md
index 1e90c12b4fb..c4ae056b1b9 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,5 +1,52 @@
 # Change Log
 
+## Unreleased
+
+### Highlights
+
+<!-- Include any especially major or disruptive changes here -->
+
+### Stable style
+
+<!-- Changes that affect Black's stable style -->
+
+### Preview style
+
+<!-- Changes that affect Black's preview style -->
+
+### Configuration
+
+<!-- Changes to how Black can be configured -->
+
+### Packaging
+
+<!-- Changes to how Black is packaged, such as dependency requirements -->
+
+### Parser
+
+<!-- Changes to the parser or to version autodetection -->
+
+### Performance
+
+<!-- Changes that improve Black's performance. -->
+
+### Output
+
+<!-- Changes to Black's terminal output and error messages -->
+
+### _Blackd_
+
+<!-- Changes to blackd -->
+
+### Integrations
+
+<!-- For example, Docker, GitHub Actions, pre-commit, editors -->
+
+### Documentation
+
+<!-- Major changes to documentation and policies. Small docs changes
+     don't need a changelog entry. -->
+
 ## 23.10.1
 
 ### Highlights

From 1d4c31aa589dc0c8633af7531f8cc09192917b38 Mon Sep 17 00:00:00 2001
From: Henri Holopainen <henri.i.holopainen@gmail.com>
Date: Wed, 25 Oct 2023 18:35:37 +0300
Subject: [PATCH 0900/1034] [925] Improve multiline dictionary and list
 indentation for sole function parameter (#3964)

---
 CHANGES.md                                    |   3 +-
 docs/the_black_code_style/future_style.md     |  26 ++
 src/black/linegen.py                          |  13 +
 src/black/mode.py                             |   1 +
 ..._parens_with_braces_and_square_brackets.py | 273 ++++++++++++++++++
 .../cases/preview_long_strings__regression.py |  22 +-
 6 files changed, 325 insertions(+), 13 deletions(-)
 create mode 100644 tests/data/cases/preview_hug_parens_with_braces_and_square_brackets.py

diff --git a/CHANGES.md b/CHANGES.md
index c4ae056b1b9..f7d02af187d 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -12,7 +12,8 @@
 
 ### 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
 
diff --git a/docs/the_black_code_style/future_style.md b/docs/the_black_code_style/future_style.md
index 367ff98537c..e73c16ba26e 100644
--- a/docs/the_black_code_style/future_style.md
+++ b/docs/the_black_code_style/future_style.md
@@ -113,6 +113,32 @@ my_dict = {
 }
 ```
 
+### Improved multiline dictionary and list indentation for sole function parameter
+
+For better readability and less verticality, _Black_ now pairs parantheses ("(", ")")
+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,
+])
+```
+
 ### Improved multiline string handling
 
 _Black_ is smarter when formatting multiline strings, especially in function arguments,
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 2bfe587fa0e..5f5a69152d5 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -815,6 +815,19 @@ def _first_right_hand_split(
     tail_leaves.reverse()
     body_leaves.reverse()
     head_leaves.reverse()
+
+    if Preview.hug_parens_with_braces_and_square_brackets in line.mode:
+        if (
+            tail_leaves[0].type == token.RPAR
+            and tail_leaves[0].value
+            and tail_leaves[0].opening_bracket is head_leaves[-1]
+            and body_leaves[-1].type in [token.RBRACE, token.RSQB]
+            and body_leaves[-1].opening_bracket is body_leaves[0]
+        ):
+            head_leaves = head_leaves + body_leaves[:1]
+            tail_leaves = body_leaves[-1:] + tail_leaves
+            body_leaves = body_leaves[1:-1]
+
     head = bracket_split_build_line(
         head_leaves, line, opening_bracket, component=_BracketSplitComponent.head
     )
diff --git a/src/black/mode.py b/src/black/mode.py
index 4effeef3e7c..99b2a84a63d 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -190,6 +190,7 @@ class Preview(Enum):
     module_docstring_newlines = auto()
     accept_raw_docstrings = auto()
     fix_power_op_line_length = auto()
+    hug_parens_with_braces_and_square_brackets = auto()
     allow_empty_first_line_before_new_block_or_comment = auto()
 
 
diff --git a/tests/data/cases/preview_hug_parens_with_braces_and_square_brackets.py b/tests/data/cases/preview_hug_parens_with_braces_and_square_brackets.py
new file mode 100644
index 00000000000..98ed342fcbc
--- /dev/null
+++ b/tests/data/cases/preview_hug_parens_with_braces_and_square_brackets.py
@@ -0,0 +1,273 @@
+# flags: --preview
+def foo_brackets(request):
+    return JsonResponse(
+        {
+            "var_1": foo,
+            "var_2": bar,
+        }
+    )
+
+def foo_square_brackets(request):
+    return JsonResponse(
+        [
+            "var_1",
+            "var_2",
+        ]
+    )
+
+func({"a": 37, "b": 42, "c": 927, "aaaaaaaaaaaaaaaaaaaaaaaaa": 11111111111111111111111111111111111111111})
+
+func(["random_string_number_one","random_string_number_two","random_string_number_three","random_string_number_four"])
+
+func(
+    {
+        # expand me
+        'a':37,
+        'b':42,
+        'c':927
+    }
+)
+
+func(
+    [
+        'a',
+        'b',
+        'c',
+    ]
+)
+
+func(  # a
+    [  # b
+        "c",  # c
+        "d",  # d
+        "e",  # e
+    ]  # f
+)  # g
+
+func(  # a
+    {  # b
+        "c": 1,  # c
+        "d": 2,  # d
+        "e": 3,  # e
+    }  # f
+)  # g
+
+func(
+    # preserve me
+    [
+        "c",
+        "d",
+        "e",
+    ]
+)
+
+func(
+    [  # preserve me but hug brackets
+        "c",
+        "d",
+        "e",
+    ]
+)
+
+func(
+    [
+        # preserve me but hug brackets
+        "c",
+        "d",
+        "e",
+    ]
+)
+
+func(
+    [
+        "c",
+        # preserve me but hug brackets
+        "d",
+        "e",
+    ]
+)
+
+func(
+    [
+        "c",
+        "d",
+        "e",
+        # preserve me but hug brackets
+    ]
+)
+
+func(
+    [
+        "c",
+        "d",
+        "e",
+    ]  # preserve me but hug brackets
+)
+
+func(
+    [
+        "c",
+        "d",
+        "e",
+    ]
+    # preserve me
+)
+
+func([x for x in "short line"])
+func([x for x in "long line long line long line long line long line long line long line"])
+func([x for x in [x for x in "long line long line long line long line long line long line long line"]])
+
+func({"short line"})
+func({"long line", "long long line", "long long long line", "long long long long line", "long long long long long line"})
+func({{"long line", "long long line", "long long long line", "long long long long line", "long long long long long line"}})
+
+foooooooooooooooooooo(
+    [{c: n + 1 for c in range(256)} for n in range(100)] + [{}], {size}
+)
+
+baaaaaaaaaaaaar(
+    [1, 2, 3, 4, 5, 6, 7, 8, 9, 10], {x}, "a string", [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+)
+
+# output
+def foo_brackets(request):
+    return JsonResponse({
+        "var_1": foo,
+        "var_2": bar,
+    })
+
+
+def foo_square_brackets(request):
+    return JsonResponse([
+        "var_1",
+        "var_2",
+    ])
+
+
+func({
+    "a": 37,
+    "b": 42,
+    "c": 927,
+    "aaaaaaaaaaaaaaaaaaaaaaaaa": 11111111111111111111111111111111111111111,
+})
+
+func([
+    "random_string_number_one",
+    "random_string_number_two",
+    "random_string_number_three",
+    "random_string_number_four",
+])
+
+func({
+    # expand me
+    "a": 37,
+    "b": 42,
+    "c": 927,
+})
+
+func([
+    "a",
+    "b",
+    "c",
+])
+
+func([  # a  # b
+    "c",  # c
+    "d",  # d
+    "e",  # e
+])  # f  # g
+
+func({  # a  # b
+    "c": 1,  # c
+    "d": 2,  # d
+    "e": 3,  # e
+})  # f  # g
+
+func(
+    # preserve me
+    [
+        "c",
+        "d",
+        "e",
+    ]
+)
+
+func([  # preserve me but hug brackets
+    "c",
+    "d",
+    "e",
+])
+
+func([
+    # preserve me but hug brackets
+    "c",
+    "d",
+    "e",
+])
+
+func([
+    "c",
+    # preserve me but hug brackets
+    "d",
+    "e",
+])
+
+func([
+    "c",
+    "d",
+    "e",
+    # preserve me but hug brackets
+])
+
+func([
+    "c",
+    "d",
+    "e",
+])  # preserve me but hug brackets
+
+func(
+    [
+        "c",
+        "d",
+        "e",
+    ]
+    # preserve me
+)
+
+func([x for x in "short line"])
+func([
+    x for x in "long line long line long line long line long line long line long line"
+])
+func([
+    x
+    for x in [
+        x
+        for x in "long line long line long line long line long line long line long line"
+    ]
+])
+
+func({"short line"})
+func({
+    "long line",
+    "long long line",
+    "long long long line",
+    "long long long long line",
+    "long long long long long line",
+})
+func({
+    {
+        "long line",
+        "long long line",
+        "long long long line",
+        "long long long long line",
+        "long long long long long line",
+    }
+})
+
+foooooooooooooooooooo(
+    [{c: n + 1 for c in range(256)} for n in range(100)] + [{}], {size}
+)
+
+baaaaaaaaaaaaar(
+    [1, 2, 3, 4, 5, 6, 7, 8, 9, 10], {x}, "a string", [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+)
diff --git a/tests/data/cases/preview_long_strings__regression.py b/tests/data/cases/preview_long_strings__regression.py
index 436157f4e05..313d898cd83 100644
--- a/tests/data/cases/preview_long_strings__regression.py
+++ b/tests/data/cases/preview_long_strings__regression.py
@@ -962,19 +962,17 @@ def who(self):
         )
 
 
-xxxxxxx_xxxxxx_xxxxxxx = xxx(
-    [
-        xxxxxxxxxxxx(
-            xxxxxx_xxxxxxx=(
-                '((x.aaaaaaaaa = "xxxxxx.xxxxxxxxxxxxxxxxxxxxx") || (x.xxxxxxxxx ='
-                ' "xxxxxxxxxxxx")) && '
-                # xxxxx xxxxxxxxxxxx xxxx xxx (xxxxxxxxxxxxxxxx) xx x xxxxxxxxx xx xxxxxx.
-                "(x.bbbbbbbbbbbb.xxx != "
-                '"xxx:xxx:xxx::cccccccccccc:xxxxxxx-xxxx/xxxxxxxxxxx/xxxxxxxxxxxxxxxxx") && '
-            )
+xxxxxxx_xxxxxx_xxxxxxx = xxx([
+    xxxxxxxxxxxx(
+        xxxxxx_xxxxxxx=(
+            '((x.aaaaaaaaa = "xxxxxx.xxxxxxxxxxxxxxxxxxxxx") || (x.xxxxxxxxx ='
+            ' "xxxxxxxxxxxx")) && '
+            # xxxxx xxxxxxxxxxxx xxxx xxx (xxxxxxxxxxxxxxxx) xx x xxxxxxxxx xx xxxxxx.
+            "(x.bbbbbbbbbbbb.xxx != "
+            '"xxx:xxx:xxx::cccccccccccc:xxxxxxx-xxxx/xxxxxxxxxxx/xxxxxxxxxxxxxxxxx") && '
         )
-    ]
-)
+    )
+])
 
 if __name__ == "__main__":
     for i in range(4, 8):

From 878937bcc3282319081057e2f1dbee5e24d69d68 Mon Sep 17 00:00:00 2001
From: Henri Holopainen <henri.i.holopainen@gmail.com>
Date: Wed, 25 Oct 2023 19:47:21 +0300
Subject: [PATCH 0901/1034] [2213] Add support for single line format skip with
 other comments on the same line (#3959)

---
 CHANGES.md                                    |  2 +-
 docs/the_black_code_style/current_style.md    | 12 ++--
 src/black/__init__.py                         |  2 +-
 src/black/comments.py                         | 63 +++++++++++++++----
 src/black/mode.py                             |  1 +
 ...line_format_skip_with_multiple_comments.py | 20 ++++++
 6 files changed, 81 insertions(+), 19 deletions(-)
 create mode 100644 tests/data/cases/preview_single_line_format_skip_with_multiple_comments.py

diff --git a/CHANGES.md b/CHANGES.md
index f7d02af187d..c96186c93cc 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -17,7 +17,7 @@
 
 ### Configuration
 
-<!-- Changes to how Black can be configured -->
+- Add support for single line format skip with other comments on the same line (#3959)
 
 ### Packaging
 
diff --git a/docs/the_black_code_style/current_style.md b/docs/the_black_code_style/current_style.md
index ff757a8276b..f59c1853f72 100644
--- a/docs/the_black_code_style/current_style.md
+++ b/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 separeted 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
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 188a4f79f0e..7cf93b89e42 100644
--- a/src/black/__init__.py
+++ b/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 = {
diff --git a/src/black/comments.py b/src/black/comments.py
index 226968bff98..862fc7607cc 100644
--- a/src/black/comments.py
+++ b/src/black/comments.py
@@ -3,6 +3,7 @@
 from functools import lru_cache
 from typing import Final, Iterator, List, Optional, Union
 
+from black.mode import Mode, Preview
 from black.nodes import (
     CLOSING_BRACKETS,
     STANDALONE_COMMENT,
@@ -20,10 +21,11 @@
 
 FMT_OFF: Final = {"# fmt: off", "# fmt:off", "# yapf: disable"}
 FMT_SKIP: Final = {"# fmt: skip", "# fmt:skip"}
-FMT_PASS: Final = {*FMT_OFF, *FMT_SKIP}
 FMT_ON: Final = {"# fmt: on", "# fmt:on", "# yapf: enable"}
 
 COMMENT_EXCEPTIONS = " !:#'"
+_COMMENT_PREFIX = "# "
+_COMMENT_LIST_SEPARATOR = ";"
 
 
 @dataclass
@@ -130,14 +132,14 @@ def make_comment(content: str) -> str:
     return "#" + content
 
 
-def normalize_fmt_off(node: Node) -> None:
+def normalize_fmt_off(node: Node, mode: Mode) -> None:
     """Convert content between `# fmt: off`/`# fmt: on` into standalone comments."""
     try_again = True
     while try_again:
-        try_again = convert_one_fmt_off_pair(node)
+        try_again = convert_one_fmt_off_pair(node, mode)
 
 
-def convert_one_fmt_off_pair(node: Node) -> bool:
+def convert_one_fmt_off_pair(node: Node, mode: Mode) -> bool:
     """Convert content of a single `# fmt: off`/`# fmt: on` into a standalone comment.
 
     Returns True if a pair was converted.
@@ -145,21 +147,27 @@ def convert_one_fmt_off_pair(node: Node) -> bool:
     for leaf in node.leaves():
         previous_consumed = 0
         for comment in list_comments(leaf.prefix, is_endmarker=False):
-            if comment.value not in FMT_PASS:
+            should_pass_fmt = comment.value in FMT_OFF or _contains_fmt_skip_comment(
+                comment.value, mode
+            )
+            if not should_pass_fmt:
                 previous_consumed = comment.consumed
                 continue
             # We only want standalone comments. If there's no previous leaf or
             # the previous leaf is indentation, it's a standalone comment in
             # disguise.
-            if comment.value in FMT_PASS and comment.type != STANDALONE_COMMENT:
+            if should_pass_fmt and comment.type != STANDALONE_COMMENT:
                 prev = preceding_leaf(leaf)
                 if prev:
                     if comment.value in FMT_OFF and prev.type not in WHITESPACE:
                         continue
-                    if comment.value in FMT_SKIP and prev.type in WHITESPACE:
+                    if (
+                        _contains_fmt_skip_comment(comment.value, mode)
+                        and prev.type in WHITESPACE
+                    ):
                         continue
 
-            ignored_nodes = list(generate_ignored_nodes(leaf, comment))
+            ignored_nodes = list(generate_ignored_nodes(leaf, comment, mode))
             if not ignored_nodes:
                 continue
 
@@ -168,7 +176,7 @@ def convert_one_fmt_off_pair(node: Node) -> bool:
             prefix = first.prefix
             if comment.value in FMT_OFF:
                 first.prefix = prefix[comment.consumed :]
-            if comment.value in FMT_SKIP:
+            if _contains_fmt_skip_comment(comment.value, mode):
                 first.prefix = ""
                 standalone_comment_prefix = prefix
             else:
@@ -178,7 +186,7 @@ def convert_one_fmt_off_pair(node: Node) -> bool:
             hidden_value = "".join(str(n) for n in ignored_nodes)
             if comment.value in FMT_OFF:
                 hidden_value = comment.value + "\n" + hidden_value
-            if comment.value in FMT_SKIP:
+            if _contains_fmt_skip_comment(comment.value, mode):
                 hidden_value += "  " + comment.value
             if hidden_value.endswith("\n"):
                 # That happens when one of the `ignored_nodes` ended with a NEWLINE
@@ -205,13 +213,15 @@ def convert_one_fmt_off_pair(node: Node) -> bool:
     return False
 
 
-def generate_ignored_nodes(leaf: Leaf, comment: ProtoComment) -> Iterator[LN]:
+def generate_ignored_nodes(
+    leaf: Leaf, comment: ProtoComment, mode: Mode
+) -> Iterator[LN]:
     """Starting from the container of `leaf`, generate all leaves until `# fmt: on`.
 
     If comment is skip, returns leaf only.
     Stops at the end of the block.
     """
-    if comment.value in FMT_SKIP:
+    if _contains_fmt_skip_comment(comment.value, mode):
         yield from _generate_ignored_nodes_from_fmt_skip(leaf, comment)
         return
     container: Optional[LN] = container_of(leaf)
@@ -327,3 +337,32 @@ def contains_pragma_comment(comment_list: List[Leaf]) -> bool:
             return True
 
     return False
+
+
+def _contains_fmt_skip_comment(comment_line: str, mode: Mode) -> bool:
+    """
+    Checks if the given comment contains FMT_SKIP alone or paired with other comments.
+    Matching styles:
+      # fmt:skip                           <-- single comment
+      # noqa:XXX # fmt:skip # a nice line  <-- multiple comments (Preview)
+      # pylint:XXX; fmt:skip               <-- list of comments (; separated, Preview)
+    """
+    semantic_comment_blocks = (
+        [
+            comment_line,
+            *[
+                _COMMENT_PREFIX + comment.strip()
+                for comment in comment_line.split(_COMMENT_PREFIX)[1:]
+            ],
+            *[
+                _COMMENT_PREFIX + comment.strip()
+                for comment in comment_line.strip(_COMMENT_PREFIX).split(
+                    _COMMENT_LIST_SEPARATOR
+                )
+            ],
+        ]
+        if Preview.single_line_format_skip_with_multiple_comments in mode
+        else [comment_line]
+    )
+
+    return any(comment in FMT_SKIP for comment in semantic_comment_blocks)
diff --git a/src/black/mode.py b/src/black/mode.py
index 99b2a84a63d..4e4effffb86 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -192,6 +192,7 @@ class Preview(Enum):
     fix_power_op_line_length = auto()
     hug_parens_with_braces_and_square_brackets = auto()
     allow_empty_first_line_before_new_block_or_comment = auto()
+    single_line_format_skip_with_multiple_comments = auto()
 
 
 class Deprecated(UserWarning):
diff --git a/tests/data/cases/preview_single_line_format_skip_with_multiple_comments.py b/tests/data/cases/preview_single_line_format_skip_with_multiple_comments.py
new file mode 100644
index 00000000000..efde662baa8
--- /dev/null
+++ b/tests/data/cases/preview_single_line_format_skip_with_multiple_comments.py
@@ -0,0 +1,20 @@
+# flags: --preview
+foo =  123  # fmt: skip # noqa: E501 # pylint
+bar =    (
+    123   ,
+    (        1      +           5      )  # pylint # fmt:skip
+)
+baz = "a"    +   "b"  # pylint; fmt: skip; noqa: E501
+skip_will_not_work =  "a" +  "b"  # pylint fmt:skip
+skip_will_not_work2 =  "a" +  "b"  # some text; fmt:skip happens to be part of it
+
+# output
+
+foo =  123  # fmt: skip # noqa: E501 # pylint
+bar = (
+    123   ,
+    (        1      +           5      )  # pylint # fmt:skip
+)
+baz = "a"    +   "b"  # pylint; fmt: skip; noqa: E501
+skip_will_not_work = "a" + "b"  # pylint fmt:skip
+skip_will_not_work2 = "a" + "b"  # some text; fmt:skip happens to be part of it

From f7174bfc431e22f38b502579d1234989c3c5ce15 Mon Sep 17 00:00:00 2001
From: Ikko Eltociear Ashimine <eltociear@gmail.com>
Date: Fri, 27 Oct 2023 01:43:42 +0900
Subject: [PATCH 0902/1034] Fix typo in future_style.md (#3979)

parantheses -> parentheses
---
 docs/the_black_code_style/future_style.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/the_black_code_style/future_style.md b/docs/the_black_code_style/future_style.md
index e73c16ba26e..f2534b0f0d0 100644
--- a/docs/the_black_code_style/future_style.md
+++ b/docs/the_black_code_style/future_style.md
@@ -115,7 +115,7 @@ my_dict = {
 
 ### Improved multiline dictionary and list indentation for sole function parameter
 
-For better readability and less verticality, _Black_ now pairs parantheses ("(", ")")
+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:
 

From de701fe6aa0d61526b806dd31610da5cf8b67ab9 Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Thu, 26 Oct 2023 21:13:25 -0700
Subject: [PATCH 0903/1034] Fix CI by running on Python 3.11 (#3984)

aiohttp doesn't yet support 3.12
---
 .github/workflows/diff_shades.yml | 4 ++--
 .github/workflows/doc.yml         | 2 +-
 .github/workflows/lint.yml        | 2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/diff_shades.yml b/.github/workflows/diff_shades.yml
index 97db907abc8..6bfc6ca9ed8 100644
--- a/.github/workflows/diff_shades.yml
+++ b/.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: |
diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml
index fa3d87c70f5..9a23e19cadd 100644
--- a/.github/workflows/doc.yml
+++ b/.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: |
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index 3eaf5785f5a..7fe1b04eb02 100644
--- a/.github/workflows/lint.yml
+++ b/.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: |

From 7bfa35cca88a2a6b875fb8564c19164143a46f1d Mon Sep 17 00:00:00 2001
From: Surav Shrestha <148626286+shresthasurav@users.noreply.github.com>
Date: Fri, 27 Oct 2023 10:11:47 +0545
Subject: [PATCH 0904/1034] docs: fix typos in change log and documentations
 (#3985)

---
 CHANGES.md                                 | 2 +-
 docs/the_black_code_style/current_style.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index c96186c93cc..7703223a119 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -52,7 +52,7 @@
 
 ### Highlights
 
-- Maintanence release to get a fix out for GitHub Action edge case (#3957)
+- Maintenance release to get a fix out for GitHub Action edge case (#3957)
 
 ### Preview style
 
diff --git a/docs/the_black_code_style/current_style.md b/docs/the_black_code_style/current_style.md
index f59c1853f72..431bae525f6 100644
--- a/docs/the_black_code_style/current_style.md
+++ b/docs/the_black_code_style/current_style.md
@@ -11,7 +11,7 @@ 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 contain
 `# fmt: skip` or blocks that start with `# fmt: off` and end with `# fmt: on`.
 `# fmt: skip` can be mixed with other pragmas/comments either with multiple comments
-(e.g. `# fmt: skip # pylint # noqa`) or as a semicolon separeted list (e.g.
+(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

From c369e446f9dbff313ebb555bf461b4e7778ca78d Mon Sep 17 00:00:00 2001
From: sth <sth.dev@tejp.de>
Date: Fri, 27 Oct 2023 09:43:51 +0200
Subject: [PATCH 0905/1034] Fix matching of absolute paths in `--include`
 (#3976)

---
 CHANGES.md          |  2 ++
 src/black/files.py  |  2 +-
 tests/test_black.py | 59 +++++++++++++++++++++++++++++++++++++++------
 3 files changed, 55 insertions(+), 8 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 7703223a119..71f62d0e11f 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -19,6 +19,8 @@
 
 - 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
 
 <!-- Changes to how Black is packaged, such as dependency requirements -->
diff --git a/src/black/files.py b/src/black/files.py
index 362898dc0fd..1eed7eda828 100644
--- a/src/black/files.py
+++ b/src/black/files.py
@@ -389,7 +389,7 @@ def gen_python_files(
                 warn=verbose or not quiet
             ):
                 continue
-            include_match = include.search(normalized_path) if include else True
+            include_match = include.search(root_relative_path) if include else True
             if include_match:
                 yield child
 
diff --git a/tests/test_black.py b/tests/test_black.py
index 537ca80d432..56c20243020 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -2388,6 +2388,27 @@ def test_empty_include(self) -> None:
         # Setting exclude explicitly to an empty string to block .gitignore usage.
         assert_collected_sources(src, expected, include="", exclude="")
 
+    def test_include_absolute_path(self) -> None:
+        path = DATA_DIR / "include_exclude_tests"
+        src = [path]
+        expected = [
+            Path(path / "b/dont_exclude/a.pie"),
+        ]
+        assert_collected_sources(
+            src, expected, root=path, include=r"^/b/dont_exclude/a\.pie$", exclude=""
+        )
+
+    def test_exclude_absolute_path(self) -> None:
+        path = DATA_DIR / "include_exclude_tests"
+        src = [path]
+        expected = [
+            Path(path / "b/dont_exclude/a.py"),
+            Path(path / "b/.definitely_exclude/a.py"),
+        ]
+        assert_collected_sources(
+            src, expected, root=path, include=r"\.py$", exclude=r"^/b/exclude/a\.py$"
+        )
+
     def test_extend_exclude(self) -> None:
         path = DATA_DIR / "include_exclude_tests"
         src = [path]
@@ -2401,7 +2422,6 @@ def test_extend_exclude(self) -> None:
 
     @pytest.mark.incompatible_with_mypyc
     def test_symlinks(self) -> None:
-        path = MagicMock()
         root = THIS_DIR.resolve()
         include = re.compile(black.DEFAULT_INCLUDES)
         exclude = re.compile(black.DEFAULT_EXCLUDES)
@@ -2409,19 +2429,44 @@ def test_symlinks(self) -> None:
         gitignore = PathSpec.from_lines("gitwildmatch", [])
 
         regular = MagicMock()
-        outside_root_symlink = MagicMock()
-        ignored_symlink = MagicMock()
-
-        path.iterdir.return_value = [regular, outside_root_symlink, ignored_symlink]
-
         regular.absolute.return_value = root / "regular.py"
         regular.resolve.return_value = root / "regular.py"
         regular.is_dir.return_value = False
+        regular.is_file.return_value = True
 
+        outside_root_symlink = MagicMock()
         outside_root_symlink.absolute.return_value = root / "symlink.py"
         outside_root_symlink.resolve.return_value = Path("/nowhere")
+        outside_root_symlink.is_dir.return_value = False
+        outside_root_symlink.is_file.return_value = True
 
+        ignored_symlink = MagicMock()
         ignored_symlink.absolute.return_value = root / ".mypy_cache" / "symlink.py"
+        ignored_symlink.is_dir.return_value = False
+        ignored_symlink.is_file.return_value = True
+
+        # A symlink that has an excluded name, but points to an included name
+        symlink_excluded_name = MagicMock()
+        symlink_excluded_name.absolute.return_value = root / "excluded_name"
+        symlink_excluded_name.resolve.return_value = root / "included_name.py"
+        symlink_excluded_name.is_dir.return_value = False
+        symlink_excluded_name.is_file.return_value = True
+
+        # A symlink that has an included name, but points to an excluded name
+        symlink_included_name = MagicMock()
+        symlink_included_name.absolute.return_value = root / "included_name.py"
+        symlink_included_name.resolve.return_value = root / "excluded_name"
+        symlink_included_name.is_dir.return_value = False
+        symlink_included_name.is_file.return_value = True
+
+        path = MagicMock()
+        path.iterdir.return_value = [
+            regular,
+            outside_root_symlink,
+            ignored_symlink,
+            symlink_excluded_name,
+            symlink_included_name,
+        ]
 
         files = list(
             black.gen_python_files(
@@ -2437,7 +2482,7 @@ def test_symlinks(self) -> None:
                 quiet=False,
             )
         )
-        assert files == [regular]
+        assert files == [regular, symlink_included_name]
 
         path.iterdir.assert_called_once()
         outside_root_symlink.resolve.assert_called_once()

From caef19689b153f3a7baea1764a5adccae8bf1f1e Mon Sep 17 00:00:00 2001
From: Gabriel Perren <Gabriel-p@users.noreply.github.com>
Date: Fri, 27 Oct 2023 15:54:31 -0300
Subject: [PATCH 0906/1034] Update current_style.md (#3990)

Fix small typo
---
 docs/the_black_code_style/current_style.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/the_black_code_style/current_style.md b/docs/the_black_code_style/current_style.md
index 431bae525f6..2a5e10162f2 100644
--- a/docs/the_black_code_style/current_style.md
+++ b/docs/the_black_code_style/current_style.md
@@ -178,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:

From c712d57ca9e30ba0db61c2fd7e4a2bf67f58bcc2 Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Fri, 27 Oct 2023 12:17:54 -0700
Subject: [PATCH 0907/1034] Add trailing comma test case for hugging parens
 (#3991)

---
 docs/the_black_code_style/future_style.md        | 13 +++++++++++++
 ...hug_parens_with_braces_and_square_brackets.py | 16 ++++++++++++++++
 2 files changed, 29 insertions(+)

diff --git a/docs/the_black_code_style/future_style.md b/docs/the_black_code_style/future_style.md
index f2534b0f0d0..c744902577d 100644
--- a/docs/the_black_code_style/future_style.md
+++ b/docs/the_black_code_style/future_style.md
@@ -139,6 +139,19 @@ foo([
 ])
 ```
 
+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,
diff --git a/tests/data/cases/preview_hug_parens_with_braces_and_square_brackets.py b/tests/data/cases/preview_hug_parens_with_braces_and_square_brackets.py
index 98ed342fcbc..6d10518133c 100644
--- a/tests/data/cases/preview_hug_parens_with_braces_and_square_brackets.py
+++ b/tests/data/cases/preview_hug_parens_with_braces_and_square_brackets.py
@@ -36,6 +36,14 @@ def foo_square_brackets(request):
     ]
 )
 
+func(
+    [
+        'a',
+        'b',
+        'c',
+    ],
+)
+
 func(  # a
     [  # b
         "c",  # c
@@ -171,6 +179,14 @@ def foo_square_brackets(request):
     "c",
 ])
 
+func(
+    [
+        "a",
+        "b",
+        "c",
+    ],
+)
+
 func([  # a  # b
     "c",  # c
     "d",  # d

From 53c4278a4c9b81baa86630ffda5f680f33968d1e Mon Sep 17 00:00:00 2001
From: Satyam Namdev <111422209+Spyrosigma@users.noreply.github.com>
Date: Sat, 28 Oct 2023 01:57:19 +0530
Subject: [PATCH 0908/1034] Update CHANGES.md (#3988)

Fixed a grammatical mistake
---
 CHANGES.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index 71f62d0e11f..84d9061135a 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -17,7 +17,7 @@
 
 ### Configuration
 
-- Add support for single line format skip with other comments on the same line (#3959)
+- 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)
 

From 7686989fc89aad5ea235a34977ebf8c81c26c4eb Mon Sep 17 00:00:00 2001
From: David Culley <6276049+davidculley@users.noreply.github.com>
Date: Sat, 28 Oct 2023 00:43:34 +0200
Subject: [PATCH 0909/1034] confine pre-commit to stages (#3940)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

See https://pre-commit.com/#confining-hooks-to-run-at-certain-stages

> If you are authoring a tool, it is usually a good idea to provide an appropriate `stages` property. For example a reasonable setting for a linter or code formatter would be `stages: [pre-commit, pre-merge-commit, pre-push, manual]`.

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 .pre-commit-hooks.yaml | 2 ++
 CHANGES.md             | 3 +++
 2 files changed, 5 insertions(+)

diff --git a/.pre-commit-hooks.yaml b/.pre-commit-hooks.yaml
index a1ff41fded8..54a03efe7a1 100644
--- a/.pre-commit-hooks.yaml
+++ b/.pre-commit-hooks.yaml
@@ -4,6 +4,7 @@
   name: black
   description: "Black: The uncompromising Python code formatter"
   entry: black
+  stages: [pre-commit, pre-merge-commit, pre-push, manual]
   language: python
   minimum_pre_commit_version: 2.9.2
   require_serial: true
@@ -13,6 +14,7 @@
   description:
     "Black: The uncompromising Python code formatter (with Jupyter Notebook support)"
   entry: black
+  stages: [pre-commit, pre-merge-commit, pre-push, manual]
   language: python
   minimum_pre_commit_version: 2.9.2
   require_serial: true
diff --git a/CHANGES.md b/CHANGES.md
index 84d9061135a..60231468bdf 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -45,6 +45,9 @@
 
 <!-- For example, Docker, GitHub Actions, pre-commit, editors -->
 
+- Black's pre-commit integration will now run only on git hooks appropriate for a code
+  formatter (#3940)
+
 ### Documentation
 
 <!-- Major changes to documentation and policies. Small docs changes

From 9a90fa2cb76e006b7b55162b1179846f6be07b64 Mon Sep 17 00:00:00 2001
From: Shivam Singh <103785990+Shivam250702@users.noreply.github.com>
Date: Sat, 28 Oct 2023 23:18:18 +0530
Subject: [PATCH 0910/1034] Fix typo in README.md (#3995)

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index cad8184f7bc..b9829ece177 100644
--- a/README.md
+++ b/README.md
@@ -68,7 +68,7 @@ projects, small and big. _Black_ has a comprehensive test suite, with efficient
 tests, and our own auto formatting and parallel Continuous Integration runner. Now that
 we have become stable, you should not expect large formatting changes in the future.
 Stylistic changes will mostly be responses to bug reports and support for new Python
-syntax. For more information please refer to the
+syntax. For more information please refer to
 [The Black Code Style](https://black.readthedocs.io/en/stable/the_black_code_style/index.html).
 
 Also, as a safety measure which slows down processing, _Black_ will check that the

From 5edd99312a8cde6ec3d232faa886ba15a6a6aec0 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Sat, 28 Oct 2023 11:05:53 -0700
Subject: [PATCH 0911/1034] Regression test for match variable inside match
 (#3993)

---
 tests/data/cases/pattern_matching_complex.py | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/tests/data/cases/pattern_matching_complex.py b/tests/data/cases/pattern_matching_complex.py
index 10b4d26e289..ba64f2639a0 100644
--- a/tests/data/cases/pattern_matching_complex.py
+++ b/tests/data/cases/pattern_matching_complex.py
@@ -147,3 +147,9 @@
 match (X.type, Y):
     case _:
         pass
+# issue 3487
+match = re.match(r"(?P<grade>LD|MD|HD)(?P<material>AL|SS)", "HDSS")
+
+match (match.group("grade"), match.group("material")):
+    case ("MD" | "HD", "SS" as code):
+        print("You will get here")

From 5515a5ac7ae775a080e5880caa5d0effb4cc5773 Mon Sep 17 00:00:00 2001
From: Aditya Garg <110886184+aditya7302@users.noreply.github.com>
Date: Sun, 29 Oct 2023 22:58:33 +0530
Subject: [PATCH 0912/1034] Update README.md (#3997)

Fixed a grammatical error in README.md
---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index b9829ece177..fb8170b626a 100644
--- a/README.md
+++ b/README.md
@@ -86,7 +86,7 @@ take previous formatting into account (see
 for exceptions).
 
 Our documentation covers the current _Black_ code style, but planned changes to it are
-also documented. They're both worth taking a look:
+also documented. They're both worth taking a look at:
 
 - [The _Black_ Code Style: Current style](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html)
 - [The _Black_ Code Style: Future style](https://black.readthedocs.io/en/stable/the_black_code_style/future_style.html)

From f7cbe4ae1b4c1f9c861913ba9fd88e067924ee37 Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Sun, 29 Oct 2023 15:34:38 -0700
Subject: [PATCH 0913/1034] Add release tool (#3974)

* Add release tool

- Add tool for release managers to use to generate commits
  - I'm trying to only use stdlib so we have no depdencies ...
- Default is to change date strings in hard coded documentation files + CHANGES.md
  - I write directly to files cause we have SCM to fix any screw ups ...
- We hackily convert calver to ints to sort (all for better ideas here)
  - If we hit a ValueError we just set to 0 for sorting - This is alhpa + beta release we can safely ignore these days
- Add new CI to only run release unittests in 3.12 only on all platforms
- Update release docs

- Checked with `mypy --strict` + ensure we are `black --preview` formatted :D

Tests:
- Run it to generate template PR
  - `python3.12 release.py --debug --add-changes-template`
- Run it to cleanup CHANGE.md + change version in specified doc files
```
crl-m1:black cooper$ python3.12 release.py -d
[2023-10-23 23:39:38,414] INFO: Current version detected to be 23.10.1 (release.py:221)
[2023-10-23 23:39:38,414] INFO: Next version will be 23.10.2 (release.py:222)
[2023-10-23 23:39:38,414] INFO: Cleaning up /Users/cooper/repos/black/CHANGES.md (release.py:127)
[2023-10-23 23:39:38,416] DEBUG: Finished Cleaning up /Users/cooper/repos/black/CHANGES.md (release.py:147)
[2023-10-23 23:39:38,416] INFO: Updating black version to 23.10.2 in /Users/cooper/repos/black/docs/integrations/source_version_control.md (release.py:173)
[2023-10-23 23:39:38,416] DEBUG: Finished updating black version to 23.10.2 in /Users/cooper/repos/black/docs/integrations/source_version_control.md (release.py:185)
[2023-10-23 23:39:38,416] INFO: Updating black version to 23.10.2 in /Users/cooper/repos/black/docs/usage_and_configuration/the_basics.md (release.py:173)
[2023-10-23 23:39:38,417] DEBUG: Finished updating black version to 23.10.2 in /Users/cooper/repos/black/docs/usage_and_configuration/the_basics.md (release.py:185)
```
- Add tests around some key logic

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Fix lints + add git to release CI

- Remove black + mypy as linting already runs it ...
- Ignore delete param to TemporaryDirectory as we can't set mypy to 3.12 :D

* Only run CI on linux/ubuntu for now

* Add lots of debug printing + directly run unitests (not via coverage)

* Overloading __str__ is bad on a TestCase

* Add more logging around git tag

* Print where git is in a step

* Rollback creating a fake black repo as we were not using it - I did plan to but I can't get it working on GitHub actions

* Do a deep checkout

* Add noqa for E701,E761 ... maybe we need this in our flake8 config now?

* Fix action to have correct workflow yaml to action on
- Also add fix to not double run when we push directly to psf/black

* All jelle suggestions
- Fix bug missing lines ending with --> in CHANGES.md to delete ...
- Update ci to run out of scripts dir too
- Update test_tuple_calver

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 .github/workflows/release_tests.yml  |  56 ++++++
 docs/contributing/release_process.md |  70 ++------
 scripts/release.py                   | 243 +++++++++++++++++++++++++++
 scripts/release_tests.py             |  69 ++++++++
 4 files changed, 383 insertions(+), 55 deletions(-)
 create mode 100644 .github/workflows/release_tests.yml
 create mode 100755 scripts/release.py
 create mode 100644 scripts/release_tests.py

diff --git a/.github/workflows/release_tests.yml b/.github/workflows/release_tests.yml
new file mode 100644
index 00000000000..74729445052
--- /dev/null
+++ b/.github/workflows/release_tests.yml
@@ -0,0 +1,56 @@
+name: Release tool CI
+
+on:
+  push:
+    paths:
+      - .github/workflows/release_tests.yml
+      - release.py
+      - release_tests.py
+  pull_request:
+    paths:
+      - .github/workflows/release_tests.yml
+      - release.py
+      - release_tests.py
+
+jobs:
+  build:
+    # We want to run on external PRs, but not on our own internal PRs as they'll be run
+    # by the push to the branch. Without this if check, checks are duplicated since
+    # internal PRs match both the push and pull_request events.
+    if:
+      github.event_name == 'push' || github.event.pull_request.head.repo.full_name !=
+      github.repository
+
+    name: Running python ${{ matrix.python-version }} on ${{matrix.os}}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        python-version: ["3.12"]
+        os: [macOS-latest, ubuntu-latest, windows-latest]
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Give us all history, branches and tags
+          fetch-depth: 0
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+          allow-prereleases: true
+
+      - name: Print Python Version
+        run: python --version --version && which python
+
+      - name: Print Git Version
+        run: git --version && which git
+
+      - name: Update pip, setuptools + wheels
+        run: |
+          python -m pip install --upgrade pip setuptools wheel
+
+      - name: Run unit tests via coverage + print report
+        run: |
+          python -m pip install coverage
+          coverage run scripts/release_tests.py
+          coverage report --show-missing
diff --git a/docs/contributing/release_process.md b/docs/contributing/release_process.md
index 02865d6f4bd..c66ffae8ace 100644
--- a/docs/contributing/release_process.md
+++ b/docs/contributing/release_process.md
@@ -32,21 +32,29 @@ The 10,000 foot view of the release process is that you prepare a release PR and
 publish a [GitHub Release]. This triggers [release automation](#release-workflows) that
 builds all release artifacts and publishes them to the various platforms we publish to.
 
+We now have a `scripts/release.py` script to help with cutting the release PRs.
+
+- `python3 scripts/release.py --help` is your friend.
+  - `release.py` has only been tested in Python 3.12 (so get with the times :D)
+
 To cut a release:
 
 1. Determine the release's version number
    - **_Black_ follows the [CalVer] versioning standard using the `YY.M.N` format**
      - So unless there already has been a release during this month, `N` should be `0`
    - Example: the first release in January, 2022 → `22.1.0`
+   - `release.py` will calculate this and log to stderr for you copy paste pleasure
 1. File a PR editing `CHANGES.md` and the docs to version the latest changes
+   - Run `python3 scripts/release.py [--debug]` to generate most changes
+     - Sub headings in the template, if they have no bullet points need manual removal
+       _PR welcome to improve :D_
+1. If `release.py` fail manually edit; otherwise, yay, skip this step!
    1. Replace the `## Unreleased` header with the version number
    1. Remove any empty sections for the current release
    1. (_optional_) Read through and copy-edit the changelog (eg. by moving entries,
       fixing typos, or rephrasing entries)
    1. Double-check that no changelog entries since the last release were put in the
       wrong section (e.g., run `git diff <last release> CHANGES.md`)
-   1. Add a new empty template for the next release above
-      ([template below](#changelog-template))
    1. Update references to the latest version in
       {doc}`/integrations/source_version_control` and
       {doc}`/usage_and_configuration/the_basics`
@@ -63,6 +71,11 @@ To cut a release:
       description box
 1. Publish the GitHub Release, triggering [release automation](#release-workflows) that
    will handle the rest
+1. Once CI is done add + commit (git push - No review) a new empty template for the next
+   release to CHANGES.md _(Template is able to be copy pasted from release.py should we
+   fail)_
+   1. `python3 scripts/release.py --add-changes-template|-a [--debug]`
+   1. Should that fail, please return to copy + paste
 1. At this point, you're basically done. It's good practice to go and [watch and verify
    that all the release workflows pass][black-actions], although you will receive a
    GitHub notification should something fail.
@@ -81,59 +94,6 @@ release is probably unnecessary.
 In the end, use your best judgement and ask other maintainers for their thoughts.
 ```
 
-### Changelog template
-
-Use the following template for a clean changelog after the release:
-
-```
-## Unreleased
-
-### Highlights
-
-<!-- Include any especially major or disruptive changes here -->
-
-### Stable style
-
-<!-- Changes that affect Black's stable style -->
-
-### Preview style
-
-<!-- Changes that affect Black's preview style -->
-
-### Configuration
-
-<!-- Changes to how Black can be configured -->
-
-### Packaging
-
-<!-- Changes to how Black is packaged, such as dependency requirements -->
-
-### Parser
-
-<!-- Changes to the parser or to version autodetection -->
-
-### Performance
-
-<!-- Changes that improve Black's performance. -->
-
-### Output
-
-<!-- Changes to Black's terminal output and error messages -->
-
-### _Blackd_
-
-<!-- Changes to blackd -->
-
-### Integrations
-
-<!-- For example, Docker, GitHub Actions, pre-commit, editors -->
-
-### Documentation
-
-<!-- Major changes to documentation and policies. Small docs changes
-     don't need a changelog entry. -->
-```
-
 ## Release workflows
 
 All of _Black_'s release automation uses [GitHub Actions]. All workflows are therefore
diff --git a/scripts/release.py b/scripts/release.py
new file mode 100755
index 00000000000..d588429c2d3
--- /dev/null
+++ b/scripts/release.py
@@ -0,0 +1,243 @@
+#!/usr/bin/env python3
+
+from __future__ import annotations
+
+"""
+Tool to help automate changes needed in commits during and after releases
+"""
+
+import argparse
+import logging
+import sys
+from datetime import datetime
+from pathlib import Path
+from subprocess import PIPE, run
+from typing import List
+
+LOG = logging.getLogger(__name__)
+NEW_VERSION_CHANGELOG_TEMPLATE = """\
+## Unreleased
+
+### Highlights
+
+<!-- Include any especially major or disruptive changes here -->
+
+### Stable style
+
+<!-- Changes that affect Black's stable style -->
+
+### Preview style
+
+<!-- Changes that affect Black's preview style -->
+
+### Configuration
+
+<!-- Changes to how Black can be configured -->
+
+### Packaging
+
+<!-- Changes to how Black is packaged, such as dependency requirements -->
+
+### Parser
+
+<!-- Changes to the parser or to version autodetection -->
+
+### Performance
+
+<!-- Changes that improve Black's performance. -->
+
+### Output
+
+<!-- Changes to Black's terminal output and error messages -->
+
+### _Blackd_
+
+<!-- Changes to blackd -->
+
+### Integrations
+
+<!-- For example, Docker, GitHub Actions, pre-commit, editors -->
+
+### Documentation
+
+<!-- Major changes to documentation and policies. Small docs changes
+     don't need a changelog entry. -->
+"""
+
+
+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]:
+    """Pull out all tags or calvers only"""
+    cp = run(["git", "tag"], stdout=PIPE, stderr=PIPE, check=True, encoding="utf8")
+    if not cp.stdout:
+        LOG.error(f"Returned no git tags stdout: {cp.stderr}")
+        raise NoGitTagsError
+    git_tags = cp.stdout.splitlines()
+    if versions_only:
+        return [t for t in git_tags if t[0].isdigit()]
+    return git_tags
+
+
+# TODO: Support sorting alhpa/beta releases correctly
+def tuple_calver(calver: str) -> tuple[int, ...]:  # mypy can't notice maxsplit below
+    """Convert a calver string into a tuple of ints for sorting"""
+    try:
+        return tuple(map(int, calver.split(".", maxsplit=2)))
+    except ValueError:
+        return (0, 0, 0)
+
+
+class SourceFiles:
+    def __init__(self, black_repo_dir: Path):
+        # File path fun all pathlib to be platform agnostic
+        self.black_repo_path = black_repo_dir
+        self.changes_path = self.black_repo_path / "CHANGES.md"
+        self.docs_path = self.black_repo_path / "docs"
+        self.version_doc_paths = (
+            self.docs_path / "integrations" / "source_version_control.md",
+            self.docs_path / "usage_and_configuration" / "the_basics.md",
+        )
+        self.current_version = self.get_current_version()
+        self.next_version = self.get_next_version()
+
+    def __str__(self) -> str:
+        return f"""\
+> SourceFiles ENV:
+  Repo path: {self.black_repo_path}
+  CHANGES.md path: {self.changes_path}
+  docs path: {self.docs_path}
+  Current version: {self.current_version}
+  Next version: {self.next_version}
+"""
+
+    def add_template_to_changes(self) -> int:
+        """Add the template to CHANGES.md if it does not exist"""
+        LOG.info(f"Adding template to {self.changes_path}")
+
+        with self.changes_path.open("r") as cfp:
+            changes_string = cfp.read()
+
+        if "## Unreleased" in changes_string:
+            LOG.error(f"{self.changes_path} already has unreleased template")
+            return 1
+
+        templated_changes_string = changes_string.replace(
+            "# Change Log\n",
+            f"# Change Log\n\n{NEW_VERSION_CHANGELOG_TEMPLATE}",
+        )
+
+        with self.changes_path.open("w") as cfp:
+            cfp.write(templated_changes_string)
+
+        LOG.info(f"Added template to {self.changes_path}")
+        return 0
+
+    def cleanup_changes_template_for_release(self) -> None:
+        LOG.info(f"Cleaning up {self.changes_path}")
+
+        with self.changes_path.open("r") as cfp:
+            changes_string = cfp.read()
+
+        # Change Unreleased to next version
+        versioned_changes = changes_string.replace(
+            "## Unreleased", f"## {self.next_version}"
+        )
+
+        # Remove all comments (subheadings are harder - Human required still)
+        no_comments_changes = []
+        for line in versioned_changes.splitlines():
+            if line.startswith("<!--") or line.endswith("-->"):
+                continue
+            no_comments_changes.append(line)
+
+        with self.changes_path.open("w") as cfp:
+            cfp.write("\n".join(no_comments_changes) + "\n")
+
+        LOG.debug(f"Finished Cleaning up {self.changes_path}")
+
+    def get_current_version(self) -> str:
+        """Get the latest git (version) tag as latest version"""
+        return sorted(get_git_tags(), key=lambda k: tuple_calver(k))[-1]
+
+    def get_next_version(self) -> str:
+        """Workout the year and month + version number we need to move to"""
+        base_calver = datetime.today().strftime("%y.%m")
+        calver_parts = base_calver.split(".")
+        base_calver = f"{calver_parts[0]}.{int(calver_parts[1])}"  # Remove leading 0
+        git_tags = get_git_tags()
+        same_month_releases = [t for t in git_tags if t.startswith(base_calver)]
+        if len(same_month_releases) < 1:
+            return f"{base_calver}.0"
+        same_month_version = same_month_releases[-1].split(".", 2)[-1]
+        return f"{base_calver}.{int(same_month_version) + 1}"
+
+    def update_repo_for_release(self) -> int:
+        """Update CHANGES.md + doc files ready for release"""
+        self.cleanup_changes_template_for_release()
+        self.update_version_in_docs()
+        return 0  # return 0 if no exceptions hit
+
+    def update_version_in_docs(self) -> None:
+        for doc_path in self.version_doc_paths:
+            LOG.info(f"Updating black version to {self.next_version} in {doc_path}")
+
+            with doc_path.open("r") as dfp:
+                doc_string = dfp.read()
+
+            next_version_doc = doc_string.replace(
+                self.current_version, self.next_version
+            )
+
+            with doc_path.open("w") as dfp:
+                dfp.write(next_version_doc)
+
+            LOG.debug(
+                f"Finished updating black version to {self.next_version} in {doc_path}"
+            )
+
+
+def _handle_debug(debug: bool) -> None:
+    """Turn on debugging if asked otherwise INFO default"""
+    log_level = logging.DEBUG if debug else logging.INFO
+    logging.basicConfig(
+        format="[%(asctime)s] %(levelname)s: %(message)s (%(filename)s:%(lineno)d)",
+        level=log_level,
+    )
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "-a",
+        "--add-changes-template",
+        action="store_true",
+        help="Add the Unreleased template to CHANGES.md",
+    )
+    parser.add_argument(
+        "-d", "--debug", action="store_true", help="Verbose debug output"
+    )
+    args = parser.parse_args()
+    _handle_debug(args.debug)
+    return args
+
+
+def main() -> int:
+    args = parse_args()
+
+    # Need parent.parent cause script is in scripts/ directory
+    sf = SourceFiles(Path(__file__).parent.parent)
+
+    if args.add_changes_template:
+        return sf.add_template_to_changes()
+
+    LOG.info(f"Current version detected to be {sf.current_version}")
+    LOG.info(f"Next version will be {sf.next_version}")
+    return sf.update_repo_for_release()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())
diff --git a/scripts/release_tests.py b/scripts/release_tests.py
new file mode 100644
index 00000000000..bd72cb4b48a
--- /dev/null
+++ b/scripts/release_tests.py
@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+
+import unittest
+from pathlib import Path
+from shutil import rmtree
+from tempfile import TemporaryDirectory
+from typing import Any
+from unittest.mock import Mock, patch
+
+from release import SourceFiles, tuple_calver  # type: ignore
+
+
+class FakeDateTime:
+    """Used to mock the date to test generating next calver function"""
+
+    def today(*args: Any, **kwargs: Any) -> "FakeDateTime":  # noqa
+        return FakeDateTime()
+
+    # Add leading 0 on purpose to ensure we remove it
+    def strftime(*args: Any, **kwargs: Any) -> str:  # noqa
+        return "69.01"
+
+
+class TestRelease(unittest.TestCase):
+    def setUp(self) -> None:
+        # We only test on >= 3.12
+        self.tempdir = TemporaryDirectory(delete=False)  # type: ignore
+        self.tempdir_path = Path(self.tempdir.name)
+        self.sf = SourceFiles(self.tempdir_path)
+
+    def tearDown(self) -> None:
+        rmtree(self.tempdir.name)
+        return super().tearDown()
+
+    @patch("release.get_git_tags")
+    def test_get_current_version(self, mocked_git_tags: Mock) -> None:
+        mocked_git_tags.return_value = ["1.1.0", "69.1.0", "69.1.1", "2.2.0"]
+        self.assertEqual("69.1.1", self.sf.get_current_version())
+
+    @patch("release.get_git_tags")
+    @patch("release.datetime", FakeDateTime)
+    def test_get_next_version(self, mocked_git_tags: Mock) -> None:
+        # test we handle no args
+        mocked_git_tags.return_value = []
+        self.assertEqual(
+            "69.1.0",
+            self.sf.get_next_version(),
+            "Unable to get correct next version with no git tags",
+        )
+
+        # test we handle
+        mocked_git_tags.return_value = ["1.1.0", "69.1.0", "69.1.1", "2.2.0"]
+        self.assertEqual(
+            "69.1.2",
+            self.sf.get_next_version(),
+            "Unable to get correct version with 2 previous versions released this"
+            " month",
+        )
+
+    def test_tuple_calver(self) -> None:
+        first_month_release = tuple_calver("69.1.0")
+        second_month_release = tuple_calver("69.1.1")
+        self.assertEqual((69, 1, 0), first_month_release)
+        self.assertEqual((0, 0, 0), tuple_calver("69.1.1a0"))  # Hack for alphas/betas
+        self.assertTrue(first_month_release < second_month_release)
+
+
+if __name__ == "__main__":
+    unittest.main()

From ddfecf06c13dd86205c851e340124e325ed82c5c Mon Sep 17 00:00:00 2001
From: Henri Holopainen <henri.i.holopainen@gmail.com>
Date: Mon, 30 Oct 2023 17:35:26 +0200
Subject: [PATCH 0914/1034] Hug parens also with multiline unpacking (#3992)

---
 CHANGES.md                                    |  2 ++
 docs/the_black_code_style/future_style.md     | 20 +++++++++++
 src/black/cache.py                            |  6 ++--
 src/black/linegen.py                          |  7 ++--
 ..._parens_with_braces_and_square_brackets.py | 36 +++++++++++++++++++
 5 files changed, 65 insertions(+), 6 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 60231468bdf..dd5f52cf706 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -14,6 +14,8 @@
 
 - Multiline dictionaries and lists that are the sole argument to a function are now
   indented less (#3964)
+- Multiline list and dict unpacking as the sole argument to a function is now also
+  indented less (#3992)
 
 ### Configuration
 
diff --git a/docs/the_black_code_style/future_style.md b/docs/the_black_code_style/future_style.md
index c744902577d..944ffad033e 100644
--- a/docs/the_black_code_style/future_style.md
+++ b/docs/the_black_code_style/future_style.md
@@ -139,6 +139,26 @@ foo([
 ])
 ```
 
+This also applies to list and dictionary unpacking:
+
+```python
+foo(
+    *[
+        a_long_function_name(a_long_variable_name)
+        for a_long_variable_name in some_generator
+    ]
+)
+```
+
+will become:
+
+```python
+foo(*[
+    a_long_function_name(a_long_variable_name)
+    for a_long_variable_name in some_generator
+])
+```
+
 You can use a magic trailing comma to avoid this compacting behavior; by default,
 _Black_ will not reformat the following code:
 
diff --git a/src/black/cache.py b/src/black/cache.py
index 6baa096baca..6a332304981 100644
--- a/src/black/cache.py
+++ b/src/black/cache.py
@@ -124,9 +124,9 @@ def filtered_cached(self, sources: Iterable[Path]) -> Tuple[Set[Path], Set[Path]
 
     def write(self, sources: Iterable[Path]) -> None:
         """Update the cache file data and write a new cache file."""
-        self.file_data.update(
-            **{str(src.resolve()): Cache.get_file_data(src) for src in sources}
-        )
+        self.file_data.update(**{
+            str(src.resolve()): Cache.get_file_data(src) for src in sources
+        })
         try:
             CACHE_DIR.mkdir(parents=True, exist_ok=True)
             with tempfile.NamedTemporaryFile(
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 5f5a69152d5..43bc08efbbd 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -817,16 +817,17 @@ def _first_right_hand_split(
     head_leaves.reverse()
 
     if Preview.hug_parens_with_braces_and_square_brackets in line.mode:
+        is_unpacking = 1 if body_leaves[0].type in [token.STAR, token.DOUBLESTAR] else 0
         if (
             tail_leaves[0].type == token.RPAR
             and tail_leaves[0].value
             and tail_leaves[0].opening_bracket is head_leaves[-1]
             and body_leaves[-1].type in [token.RBRACE, token.RSQB]
-            and body_leaves[-1].opening_bracket is body_leaves[0]
+            and body_leaves[-1].opening_bracket is body_leaves[is_unpacking]
         ):
-            head_leaves = head_leaves + body_leaves[:1]
+            head_leaves = head_leaves + body_leaves[: 1 + is_unpacking]
             tail_leaves = body_leaves[-1:] + tail_leaves
-            body_leaves = body_leaves[1:-1]
+            body_leaves = body_leaves[1 + is_unpacking : -1]
 
     head = bracket_split_build_line(
         head_leaves, line, opening_bracket, component=_BracketSplitComponent.head
diff --git a/tests/data/cases/preview_hug_parens_with_braces_and_square_brackets.py b/tests/data/cases/preview_hug_parens_with_braces_and_square_brackets.py
index 6d10518133c..51fe516add5 100644
--- a/tests/data/cases/preview_hug_parens_with_braces_and_square_brackets.py
+++ b/tests/data/cases/preview_hug_parens_with_braces_and_square_brackets.py
@@ -137,6 +137,21 @@ def foo_square_brackets(request):
     [1, 2, 3, 4, 5, 6, 7, 8, 9, 10], {x}, "a string", [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
 )
 
+foo(*["long long long long long line", "long long long long long line", "long long long long long line"])
+
+foo(*[str(i) for i in range(100000000000000000000000000000000000000000000000000000000000)])
+
+foo(
+    **{
+        "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa": 1,
+        "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb": 2,
+        "ccccccccccccccccccccccccccccccccc": 3,
+        **other,
+    }
+)
+
+foo(**{x: y for x, y in enumerate(["long long long long line","long long long long line"])})
+
 # output
 def foo_brackets(request):
     return JsonResponse({
@@ -287,3 +302,24 @@ def foo_square_brackets(request):
 baaaaaaaaaaaaar(
     [1, 2, 3, 4, 5, 6, 7, 8, 9, 10], {x}, "a string", [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
 )
+
+foo(*[
+    "long long long long long line",
+    "long long long long long line",
+    "long long long long long line",
+])
+
+foo(*[
+    str(i) for i in range(100000000000000000000000000000000000000000000000000000000000)
+])
+
+foo(**{
+    "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa": 1,
+    "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb": 2,
+    "ccccccccccccccccccccccccccccccccc": 3,
+    **other,
+})
+
+foo(**{
+    x: y for x, y in enumerate(["long long long long line", "long long long long line"])
+})

From e50110353ab81b539aaee686453c18c707b5f045 Mon Sep 17 00:00:00 2001
From: Henri Holopainen <henri.i.holopainen@gmail.com>
Date: Tue, 31 Oct 2023 17:27:11 +0200
Subject: [PATCH 0915/1034] Produce equivalent code for docstrings containing
 backslash followed by whitespace(s) before newline (#4008)

Fixes #3727
---
 CHANGES.md                    |  3 ++-
 src/black/linegen.py          |  3 ++-
 tests/data/cases/docstring.py | 13 +++++++++++++
 3 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index dd5f52cf706..e910fbed162 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -8,7 +8,8 @@
 
 ### Stable style
 
-<!-- Changes that affect Black's stable style -->
+- Fix a crash when whitespace(s) followed a backslash before newline in a docstring
+  (#4008)
 
 ### Preview style
 
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 43bc08efbbd..121c6e314fe 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -2,6 +2,7 @@
 Generating lines of code.
 """
 
+import re
 import sys
 from dataclasses import replace
 from enum import Enum, auto
@@ -420,7 +421,7 @@ def visit_STRING(self, leaf: Leaf) -> Iterator[Line]:
         if Preview.hex_codes_in_unicode_sequences in self.mode:
             normalize_unicode_escape_sequences(leaf)
 
-        if is_docstring(leaf) and "\\\n" not in leaf.value:
+        if is_docstring(leaf) and not re.search(r"\\\s*\n", leaf.value):
             # We're ignoring docstrings with backslash newline escapes because changing
             # indentation of those changes the AST representation of the code.
             if self.mode.string_normalization:
diff --git a/tests/data/cases/docstring.py b/tests/data/cases/docstring.py
index c31d6a68783..e983c5bd438 100644
--- a/tests/data/cases/docstring.py
+++ b/tests/data/cases/docstring.py
@@ -221,6 +221,12 @@ def stable_quote_normalization_with_immediate_inner_single_quote(self):
     '''
 
 
+def foo():
+    """
+    Docstring with a backslash followed by a space\ 
+    and then another line
+    """
+
 # output
 
 class MyClass:
@@ -442,3 +448,10 @@ def stable_quote_normalization_with_immediate_inner_single_quote(self):
 
     <text here, since without another non-empty line black is stable>
     """
+
+
+def foo():
+    """
+    Docstring with a backslash followed by a space\ 
+    and then another line
+    """

From 5758da6e3cda4ec037c5dbb7867373cf694edd03 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Tue, 31 Oct 2023 17:11:28 -0700
Subject: [PATCH 0916/1034] Fix bytes strings being treated as docstrings
 (#4003)

Fixes #4002
---
 CHANGES.md                              |  4 +--
 src/black/nodes.py                      |  9 ++++++-
 tests/data/cases/bytes_docstring.py     | 34 +++++++++++++++++++++++++
 tests/data/{ => cases}/raw_docstring.py |  0
 4 files changed, 44 insertions(+), 3 deletions(-)
 create mode 100644 tests/data/cases/bytes_docstring.py
 rename tests/data/{ => cases}/raw_docstring.py (100%)

diff --git a/CHANGES.md b/CHANGES.md
index e910fbed162..f365f1c239b 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -8,8 +8,8 @@
 
 ### Stable style
 
-- Fix a crash when whitespace(s) followed a backslash before newline in a docstring
-  (#4008)
+- Fix crash on formatting bytes strings that look like docstrings (#4003)
+- Fix crash when whitespace followed a backslash before newline in a docstring (#4008)
 
 ### Preview style
 
diff --git a/src/black/nodes.py b/src/black/nodes.py
index b2e96cb9edf..5f6b280c035 100644
--- a/src/black/nodes.py
+++ b/src/black/nodes.py
@@ -14,7 +14,7 @@
 
 from black.cache import CACHE_DIR
 from black.mode import Mode, Preview
-from black.strings import has_triple_quotes
+from black.strings import get_string_prefix, has_triple_quotes
 from blib2to3 import pygram
 from blib2to3.pgen2 import token
 from blib2to3.pytree import NL, Leaf, Node, type_repr
@@ -525,6 +525,13 @@ def is_arith_like(node: LN) -> bool:
 
 
 def is_docstring(leaf: Leaf) -> bool:
+    if leaf.type != token.STRING:
+        return False
+
+    prefix = get_string_prefix(leaf.value)
+    if "b" in prefix or "B" in prefix:
+        return False
+
     if prev_siblings_are(
         leaf.parent, [None, token.NEWLINE, token.INDENT, syms.simple_stmt]
     ):
diff --git a/tests/data/cases/bytes_docstring.py b/tests/data/cases/bytes_docstring.py
new file mode 100644
index 00000000000..2326e95293a
--- /dev/null
+++ b/tests/data/cases/bytes_docstring.py
@@ -0,0 +1,34 @@
+def bitey():
+    b" not a docstring"
+
+def bitey2():
+    b' also not a docstring'
+
+def triple_quoted_bytes():
+    b""" not a docstring"""
+
+def triple_quoted_bytes2():
+    b''' also not a docstring'''
+
+def capitalized_bytes():
+    B" NOT A DOCSTRING"
+
+# output
+def bitey():
+    b" not a docstring"
+
+
+def bitey2():
+    b" also not a docstring"
+
+
+def triple_quoted_bytes():
+    b""" not a docstring"""
+
+
+def triple_quoted_bytes2():
+    b""" also not a docstring"""
+
+
+def capitalized_bytes():
+    b" NOT A DOCSTRING"
\ No newline at end of file
diff --git a/tests/data/raw_docstring.py b/tests/data/cases/raw_docstring.py
similarity index 100%
rename from tests/data/raw_docstring.py
rename to tests/data/cases/raw_docstring.py

From e2f2bd076fbc19d4adb90b70b5a7be32b08d5dbe Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Wed, 1 Nov 2023 06:20:14 -0700
Subject: [PATCH 0917/1034] Minor refactoring in get_sources and
 gen_python_files (#4013)

---
 src/black/__init__.py | 39 ++++++++++++++++++---------------------
 src/black/files.py    |  7 ++-----
 tests/test_black.py   |  5 +++--
 3 files changed, 23 insertions(+), 28 deletions(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index 7cf93b89e42..c11a66b7bc8 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -50,6 +50,7 @@
     get_gitignore,
     normalize_path_maybe_ignore,
     parse_pyproject_toml,
+    path_is_excluded,
     wrap_stream_for_windows,
 )
 from black.handle_ipynb_magics import (
@@ -632,15 +633,15 @@ def get_sources(
 
     for s in src:
         if s == "-" and stdin_filename:
-            p = Path(stdin_filename)
+            path = Path(stdin_filename)
             is_stdin = True
         else:
-            p = Path(s)
+            path = Path(s)
             is_stdin = False
 
-        if is_stdin or p.is_file():
+        if is_stdin or path.is_file():
             normalized_path: Optional[str] = normalize_path_maybe_ignore(
-                p, root, report
+                path, root, report
             )
             if normalized_path is None:
                 if verbose:
@@ -651,38 +652,34 @@ def get_sources(
 
             normalized_path = "/" + normalized_path
             # Hard-exclude any files that matches the `--force-exclude` regex.
-            if force_exclude:
-                force_exclude_match = force_exclude.search(normalized_path)
-            else:
-                force_exclude_match = None
-            if force_exclude_match and force_exclude_match.group(0):
-                report.path_ignored(p, "matches the --force-exclude regular expression")
+            if path_is_excluded(normalized_path, force_exclude):
+                report.path_ignored(
+                    path, "matches the --force-exclude regular expression"
+                )
                 continue
 
             if is_stdin:
-                p = Path(f"{STDIN_PLACEHOLDER}{str(p)}")
+                path = Path(f"{STDIN_PLACEHOLDER}{str(path)}")
 
-            if p.suffix == ".ipynb" and not jupyter_dependencies_are_installed(
+            if path.suffix == ".ipynb" and not jupyter_dependencies_are_installed(
                 warn=verbose or not quiet
             ):
                 continue
 
-            sources.add(p)
-        elif p.is_dir():
-            p_relative = normalize_path_maybe_ignore(p, root, report)
-            assert p_relative is not None
-            p = root / p_relative
+            sources.add(path)
+        elif path.is_dir():
+            path = root / (path.resolve().relative_to(root))
             if verbose:
-                out(f'Found input source directory: "{p}"', fg="blue")
+                out(f'Found input source directory: "{path}"', fg="blue")
 
             if using_default_exclude:
                 gitignore = {
                     root: root_gitignore,
-                    p: get_gitignore(p),
+                    path: get_gitignore(path),
                 }
             sources.update(
                 gen_python_files(
-                    p.iterdir(),
+                    path.iterdir(),
                     root,
                     include,
                     exclude,
@@ -697,7 +694,7 @@ def get_sources(
         elif s == "-":
             if verbose:
                 out("Found input source stdin", fg="blue")
-            sources.add(p)
+            sources.add(path)
         else:
             err(f"invalid path: {s}")
 
diff --git a/src/black/files.py b/src/black/files.py
index 1eed7eda828..858303ca1a3 100644
--- a/src/black/files.py
+++ b/src/black/files.py
@@ -280,7 +280,6 @@ def _path_is_ignored(
     root_relative_path: str,
     root: Path,
     gitignore_dict: Dict[Path, PathSpec],
-    report: Report,
 ) -> bool:
     path = root / root_relative_path
     # Note that this logic is sensitive to the ordering of gitignore_dict. Callers must
@@ -291,9 +290,6 @@ def _path_is_ignored(
         except ValueError:
             break
         if pattern.match_file(relative_path):
-            report.path_ignored(
-                path.relative_to(root), "matches a .gitignore file content"
-            )
             return True
     return False
 
@@ -334,8 +330,9 @@ def gen_python_files(
 
         # First ignore files matching .gitignore, if passed
         if gitignore_dict and _path_is_ignored(
-            root_relative_path, root, gitignore_dict, report
+            root_relative_path, root, gitignore_dict
         ):
+            report.path_ignored(child, "matches a .gitignore file content")
             continue
 
         # Then ignore with `--exclude` `--extend-exclude` and `--force-exclude` options.
diff --git a/tests/test_black.py b/tests/test_black.py
index 56c20243020..c7196098e14 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -504,7 +504,7 @@ def _mocked_calls() -> bool:
             return _mocked_calls
 
         with patch("pathlib.Path.iterdir", return_value=target_contents), patch(
-            "pathlib.Path.cwd", return_value=working_directory
+            "pathlib.Path.resolve", return_value=target_abspath
         ), patch("pathlib.Path.is_dir", side_effect=mock_n_calls([True])):
             # Note that the root folder (project_root) isn't the folder
             # named "root" (aka working_directory)
@@ -526,7 +526,8 @@ def _mocked_calls() -> bool:
             for _, mock_args, _ in report.path_ignored.mock_calls
         ), "A symbolic link was reported."
         report.path_ignored.assert_called_once_with(
-            Path("root", "child", "b.py"), "matches a .gitignore file content"
+            Path(working_directory, "child", "b.py"),
+            "matches a .gitignore file content",
         )
 
     def test_report_verbose(self) -> None:

From c54c213d6a3132986feede0cf0525f5bae5b43d6 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Thu, 2 Nov 2023 20:42:11 -0700
Subject: [PATCH 0918/1034] Fix crash on await (a ** b) (#3994)

---
 CHANGES.md                              |  2 ++
 src/black/linegen.py                    | 22 ++++++++++------------
 tests/data/cases/remove_await_parens.py | 19 +++++++++++++++++++
 3 files changed, 31 insertions(+), 12 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index f365f1c239b..5ce37943693 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -11,6 +11,8 @@
 - Fix crash on formatting bytes strings that look like docstrings (#4003)
 - Fix crash when whitespace followed a backslash before newline in a docstring (#4008)
 
+- Fix crash on formatting code like `await (a ** b)` (#3994)
+
 ### Preview style
 
 - Multiline dictionaries and lists that are the sole argument to a function are now
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 121c6e314fe..b13b95d9b31 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -1352,18 +1352,16 @@ def remove_await_parens(node: Node) -> None:
             opening_bracket = cast(Leaf, node.children[1].children[0])
             closing_bracket = cast(Leaf, node.children[1].children[-1])
             bracket_contents = node.children[1].children[1]
-            if isinstance(bracket_contents, Node):
-                if bracket_contents.type != syms.power:
-                    ensure_visible(opening_bracket)
-                    ensure_visible(closing_bracket)
-                elif (
-                    bracket_contents.type == syms.power
-                    and bracket_contents.children[0].type == token.AWAIT
-                ):
-                    ensure_visible(opening_bracket)
-                    ensure_visible(closing_bracket)
-                    # If we are in a nested await then recurse down.
-                    remove_await_parens(bracket_contents)
+            if isinstance(bracket_contents, Node) and (
+                bracket_contents.type != syms.power
+                or bracket_contents.children[0].type == token.AWAIT
+                or any(
+                    isinstance(child, Leaf) and child.type == token.DOUBLESTAR
+                    for child in bracket_contents.children
+                )
+            ):
+                ensure_visible(opening_bracket)
+                ensure_visible(closing_bracket)
 
 
 def _maybe_wrap_cms_in_parens(
diff --git a/tests/data/cases/remove_await_parens.py b/tests/data/cases/remove_await_parens.py
index 8c7223d2f39..073150c5f08 100644
--- a/tests/data/cases/remove_await_parens.py
+++ b/tests/data/cases/remove_await_parens.py
@@ -80,6 +80,15 @@ async def main():
 async def main():
     await (yield)
 
+async def main():
+    await (a ** b)
+    await (a[b] ** c)
+    await (a ** b[c])
+    await ((a + b) ** (c + d))
+    await (a + b)
+    await (a[b])
+    await (a[b ** c])
+
 # output
 import asyncio
 
@@ -174,3 +183,13 @@ async def main():
 
 async def main():
     await (yield)
+
+
+async def main():
+    await (a**b)
+    await (a[b] ** c)
+    await (a ** b[c])
+    await ((a + b) ** (c + d))
+    await (a + b)
+    await a[b]
+    await a[b**c]

From 448324637d12514b540efb33b4df7bf8af10c6d5 Mon Sep 17 00:00:00 2001
From: Ran Benita <ran@unusedvar.com>
Date: Sat, 4 Nov 2023 22:49:12 +0200
Subject: [PATCH 0919/1034] Enable branch coverage (#4022)

When trying to understand the code logic, and looking at coverage
reports, branch coverage is very helpful.
---
 pyproject.toml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/pyproject.toml b/pyproject.toml
index 8c55076e4c9..f3689bfb746 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -224,6 +224,7 @@ omit = [
 ]
 [tool.coverage.run]
 relative_files = true
+branch = true
 
 [tool.mypy]
 # Specify the target platform details in config, so your developers are

From 9e3daa1107a66f311a8367395a33ed5fc5d5e73d Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Sun, 5 Nov 2023 18:29:37 -0800
Subject: [PATCH 0920/1034] Fix arm wheels on macOS (#4017)

---
 .github/workflows/pypi_upload.yml |  7 ++++---
 CHANGES.md                        |  2 ++
 pyproject.toml                    | 13 ++++++++++++-
 3 files changed, 18 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/pypi_upload.yml b/.github/workflows/pypi_upload.yml
index a57013d67c1..07273f09508 100644
--- a/.github/workflows/pypi_upload.yml
+++ b/.github/workflows/pypi_upload.yml
@@ -68,9 +68,10 @@ jobs:
       - name: generate matrix (PR)
         if: github.event_name == 'pull_request'
         run: |
-          cibuildwheel --print-build-identifiers --platform linux \
-          | pyp 'json.dumps({"only": x, "os": "ubuntu-latest"})' \
-          | pyp 'json.dumps(list(map(json.loads, lines)))' > /tmp/matrix
+          {
+            cibuildwheel --print-build-identifiers --platform linux \
+            | pyp 'json.dumps({"only": x, "os": "ubuntu-latest"})'
+          } | pyp 'json.dumps(list(map(json.loads, lines)))' > /tmp/matrix
         env:
           CIBW_BUILD: "cp38-* cp311-*"
           CIBW_ARCHS_LINUX: x86_64
diff --git a/CHANGES.md b/CHANGES.md
index 5ce37943693..97084a2bfc1 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -38,6 +38,8 @@
 
 <!-- Changes that improve Black's performance. -->
 
+- Fix mypyc builds on arm64 on macOS (#4017)
+
 ### Output
 
 <!-- Changes to Black's terminal output and error messages -->
diff --git a/pyproject.toml b/pyproject.toml
index f3689bfb746..c0302d2302a 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -113,6 +113,8 @@ exclude = ["/profiling"]
 [tool.hatch.build.targets.wheel]
 only-include = ["src"]
 sources = ["src"]
+# Note that we change the behaviour of this flag below
+macos-max-compat = true
 
 [tool.hatch.build.targets.wheel.hooks.mypyc]
 enable-by-default = false
@@ -175,9 +177,18 @@ before-build = [
 HATCH_BUILD_HOOKS_ENABLE = "1"
 MYPYC_OPT_LEVEL = "3"
 MYPYC_DEBUG_LEVEL = "0"
+AIOHTTP_NO_EXTENSIONS = "1"
+
 # Black needs Clang to compile successfully on Linux.
 CC = "clang"
-AIOHTTP_NO_EXTENSIONS = "1"
+
+[tool.cibuildwheel.macos]
+build-frontend = { name = "build", args = ["--no-isolation"] }
+# Unfortunately, hatch doesn't respect MACOSX_DEPLOYMENT_TARGET
+before-build = [
+    "python -m pip install 'hatchling==1.18.0' hatch-vcs hatch-fancy-pypi-readme 'hatch-mypyc>=0.16.0' 'mypy==1.5.1' 'click==8.1.3'",
+    """sed -i '' -e "600,700s/'10_16'/os.environ['MACOSX_DEPLOYMENT_TARGET'].replace('.', '_')/" $(python -c 'import hatchling.builders.wheel as h; print(h.__file__)') """,
+]
 
 [tool.isort]
 atomic = true

From e808e61db8c7a8f9c7fd4b2fff2281141f6b2517 Mon Sep 17 00:00:00 2001
From: Yilei Yang <yileiyang@google.com>
Date: Mon, 6 Nov 2023 14:30:04 -0800
Subject: [PATCH 0921/1034] Preview: Keep requiring two empty lines between
 module-level docstring and first function or class definition (#4028)

Fixes #4027.
---
 CHANGES.md                                            |  2 ++
 src/black/lines.py                                    |  1 +
 .../data/cases/module_docstring_followed_by_class.py  | 11 +++++++++++
 .../cases/module_docstring_followed_by_function.py    | 11 +++++++++++
 4 files changed, 25 insertions(+)
 create mode 100644 tests/data/cases/module_docstring_followed_by_class.py
 create mode 100644 tests/data/cases/module_docstring_followed_by_function.py

diff --git a/CHANGES.md b/CHANGES.md
index 97084a2bfc1..a68f87bfc12 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -19,6 +19,8 @@
   indented less (#3964)
 - Multiline list and dict unpacking as the sole argument to a function is now also
   indented less (#3992)
+- Keep requiring two empty lines between module-level docstring and first function or
+  class definition. (#4028)
 
 ### Configuration
 
diff --git a/src/black/lines.py b/src/black/lines.py
index a73c429e3d9..23c1a93d3d4 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -578,6 +578,7 @@ def maybe_empty_lines(self, current_line: Line) -> LinesBlock:
             and self.previous_block.previous_block is None
             and len(self.previous_block.original_line.leaves) == 1
             and self.previous_block.original_line.is_triple_quoted_string
+            and not (current_line.is_class or current_line.is_def)
         ):
             before = 1
 
diff --git a/tests/data/cases/module_docstring_followed_by_class.py b/tests/data/cases/module_docstring_followed_by_class.py
new file mode 100644
index 00000000000..6fdbfc8c240
--- /dev/null
+++ b/tests/data/cases/module_docstring_followed_by_class.py
@@ -0,0 +1,11 @@
+# flags: --preview
+"""Two blank lines between module docstring and a class."""
+class MyClass:
+    pass
+
+# output
+"""Two blank lines between module docstring and a class."""
+
+
+class MyClass:
+    pass
diff --git a/tests/data/cases/module_docstring_followed_by_function.py b/tests/data/cases/module_docstring_followed_by_function.py
new file mode 100644
index 00000000000..5913a59e1fe
--- /dev/null
+++ b/tests/data/cases/module_docstring_followed_by_function.py
@@ -0,0 +1,11 @@
+# flags: --preview
+"""Two blank lines between module docstring and a function def."""
+def function():
+    pass
+
+# output
+"""Two blank lines between module docstring and a function def."""
+
+
+def function():
+    pass

From ecbd9e8cf71f13068c7e6803a534e00363114c91 Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Mon, 6 Nov 2023 16:58:43 -0800
Subject: [PATCH 0922/1034] Fix crash with f-string docstrings (#4019)

Python does not consider f-strings to be docstrings, so we probably
shouldn't be formatting them as such

Fixes #4018

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
---
 CHANGES.md                                    |  3 +++
 src/black/nodes.py                            |  2 +-
 tests/data/cases/docstring_preview.py         |  3 ++-
 tests/data/cases/f_docstring.py               | 20 +++++++++++++++++++
 ...view_docstring_no_string_normalization.py} |  0
 5 files changed, 26 insertions(+), 2 deletions(-)
 create mode 100644 tests/data/cases/f_docstring.py
 rename tests/data/cases/{docstring_preview_no_string_normalization.py => preview_docstring_no_string_normalization.py} (100%)

diff --git a/CHANGES.md b/CHANGES.md
index a68f87bfc12..b1fe25ef625 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -13,6 +13,9 @@
 
 - Fix crash on formatting code like `await (a ** b)` (#3994)
 
+- No longer treat leading f-strings as docstrings. This matches Python's behaviour and
+  fixes a crash (#4019)
+
 ### Preview style
 
 - Multiline dictionaries and lists that are the sole argument to a function are now
diff --git a/src/black/nodes.py b/src/black/nodes.py
index 5f6b280c035..fff8e05a118 100644
--- a/src/black/nodes.py
+++ b/src/black/nodes.py
@@ -529,7 +529,7 @@ def is_docstring(leaf: Leaf) -> bool:
         return False
 
     prefix = get_string_prefix(leaf.value)
-    if "b" in prefix or "B" in prefix:
+    if set(prefix).intersection("bBfF"):
         return False
 
     if prev_siblings_are(
diff --git a/tests/data/cases/docstring_preview.py b/tests/data/cases/docstring_preview.py
index ff4819acb67..a3c656be2f8 100644
--- a/tests/data/cases/docstring_preview.py
+++ b/tests/data/cases/docstring_preview.py
@@ -58,7 +58,8 @@ def docstring_almost_at_line_limit():
 
 
 def docstring_almost_at_line_limit_with_prefix():
-    f"""long docstring................................................................"""
+    f"""long docstring................................................................
+    """
 
 
 def mulitline_docstring_almost_at_line_limit():
diff --git a/tests/data/cases/f_docstring.py b/tests/data/cases/f_docstring.py
new file mode 100644
index 00000000000..667f550b353
--- /dev/null
+++ b/tests/data/cases/f_docstring.py
@@ -0,0 +1,20 @@
+def foo(e):
+    f""" {'.'.join(e)}"""
+
+def bar(e):
+    f"{'.'.join(e)}"
+
+def baz(e):
+    F""" {'.'.join(e)}"""
+
+# output
+def foo(e):
+    f""" {'.'.join(e)}"""
+
+
+def bar(e):
+    f"{'.'.join(e)}"
+
+
+def baz(e):
+    f""" {'.'.join(e)}"""
diff --git a/tests/data/cases/docstring_preview_no_string_normalization.py b/tests/data/cases/preview_docstring_no_string_normalization.py
similarity index 100%
rename from tests/data/cases/docstring_preview_no_string_normalization.py
rename to tests/data/cases/preview_docstring_no_string_normalization.py

From 46be1f8e54ac9a7d67723c0fa28c7bec13a0a2bf Mon Sep 17 00:00:00 2001
From: Yilei Yang <yileiyang@google.com>
Date: Mon, 6 Nov 2023 18:05:25 -0800
Subject: [PATCH 0923/1034] Support formatting specified lines (#4020)

---
 CHANGES.md                                    |   3 +
 docs/usage_and_configuration/the_basics.md    |  17 +
 src/black/__init__.py                         | 130 ++++-
 src/black/nodes.py                            |  28 +
 src/black/ranges.py                           | 496 ++++++++++++++++++
 tests/data/cases/line_ranges_basic.py         | 107 ++++
 tests/data/cases/line_ranges_fmt_off.py       |  49 ++
 .../cases/line_ranges_fmt_off_decorator.py    |  27 +
 .../data/cases/line_ranges_fmt_off_overlap.py |  37 ++
 tests/data/cases/line_ranges_imports.py       |   9 +
 tests/data/cases/line_ranges_indentation.py   |  27 +
 tests/data/cases/line_ranges_two_passes.py    |  27 +
 tests/data/cases/line_ranges_unwrapping.py    |  25 +
 tests/data/invalid_line_ranges.toml           |   2 +
 tests/data/line_ranges_formatted/basic.py     |  50 ++
 .../line_ranges_formatted/pattern_matching.py |  25 +
 tests/test_black.py                           |  87 ++-
 tests/test_format.py                          |  26 +-
 tests/test_ranges.py                          | 185 +++++++
 tests/util.py                                 |  29 +-
 20 files changed, 1358 insertions(+), 28 deletions(-)
 create mode 100644 src/black/ranges.py
 create mode 100644 tests/data/cases/line_ranges_basic.py
 create mode 100644 tests/data/cases/line_ranges_fmt_off.py
 create mode 100644 tests/data/cases/line_ranges_fmt_off_decorator.py
 create mode 100644 tests/data/cases/line_ranges_fmt_off_overlap.py
 create mode 100644 tests/data/cases/line_ranges_imports.py
 create mode 100644 tests/data/cases/line_ranges_indentation.py
 create mode 100644 tests/data/cases/line_ranges_two_passes.py
 create mode 100644 tests/data/cases/line_ranges_unwrapping.py
 create mode 100644 tests/data/invalid_line_ranges.toml
 create mode 100644 tests/data/line_ranges_formatted/basic.py
 create mode 100644 tests/data/line_ranges_formatted/pattern_matching.py
 create mode 100644 tests/test_ranges.py

diff --git a/CHANGES.md b/CHANGES.md
index b1fe25ef625..780a00247ce 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -6,6 +6,9 @@
 
 <!-- Include any especially major or disruptive changes here -->
 
+- Support formatting ranges of lines with the new `--line-ranges` command-line option
+  (#4020).
+
 ### Stable style
 
 - Fix crash on formatting bytes strings that look like docstrings (#4003)
diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index f25dbb13d4d..dbd8c7ba434 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -175,6 +175,23 @@ All done! ✨ 🍰 ✨
 1 file would be reformatted.
 ```
 
+### `--line-ranges`
+
+When specified, _Black_ will try its best to only format these lines.
+
+This option can be specified multiple times, and a union of the lines will be formatted.
+Each range must be specified as two integers connected by a `-`: `<START>-<END>`. The
+`<START>` and `<END>` integer indices are 1-based and inclusive on both ends.
+
+_Black_ may still format lines outside of the ranges for multi-line statements.
+Formatting more than one file or any ipynb files with this option is not supported. This
+option cannot be specified in the `pyproject.toml` config.
+
+Example: `black --line-ranges=1-10 --line-ranges=21-30 test.py` will format lines from
+`1` to `10` and `21` to `30`.
+
+This option is mainly for editor integrations, such as "Format Selection".
+
 #### `--color` / `--no-color`
 
 Show (or do not show) colored diff. Only applies when `--diff` is given.
diff --git a/src/black/__init__.py b/src/black/__init__.py
index c11a66b7bc8..5aca3316df0 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -13,6 +13,7 @@
 from pathlib import Path
 from typing import (
     Any,
+    Collection,
     Dict,
     Generator,
     Iterator,
@@ -77,6 +78,7 @@
 from black.output import color_diff, diff, dump_to_file, err, ipynb_diff, out
 from black.parsing import InvalidInput  # noqa F401
 from black.parsing import lib2to3_parse, parse_ast, stringify_ast
+from black.ranges import adjusted_lines, convert_unchanged_lines, parse_line_ranges
 from black.report import Changed, NothingChanged, Report
 from black.trans import iter_fexpr_spans
 from blib2to3.pgen2 import token
@@ -163,6 +165,12 @@ def read_pyproject_toml(
             "extend-exclude", "Config key extend-exclude must be a string"
         )
 
+    line_ranges = config.get("line_ranges")
+    if line_ranges is not None:
+        raise click.BadOptionUsage(
+            "line-ranges", "Cannot use line-ranges in the pyproject.toml file."
+        )
+
     default_map: Dict[str, Any] = {}
     if ctx.default_map:
         default_map.update(ctx.default_map)
@@ -304,6 +312,19 @@ def validate_regex(
     is_flag=True,
     help="Don't write the files back, just output a diff for each file on stdout.",
 )
+@click.option(
+    "--line-ranges",
+    multiple=True,
+    metavar="START-END",
+    help=(
+        "When specified, _Black_ will try its best to only format these lines. This"
+        " option can be specified multiple times, and a union of the lines will be"
+        " formatted. Each range must be specified as two integers connected by a `-`:"
+        " `<START>-<END>`. The `<START>` and `<END>` integer indices are 1-based and"
+        " inclusive on both ends."
+    ),
+    default=(),
+)
 @click.option(
     "--color/--no-color",
     is_flag=True,
@@ -443,6 +464,7 @@ def main(  # noqa: C901
     target_version: List[TargetVersion],
     check: bool,
     diff: bool,
+    line_ranges: Sequence[str],
     color: bool,
     fast: bool,
     pyi: bool,
@@ -544,6 +566,18 @@ def main(  # noqa: C901
         python_cell_magics=set(python_cell_magics),
     )
 
+    lines: List[Tuple[int, int]] = []
+    if line_ranges:
+        if ipynb:
+            err("Cannot use --line-ranges with ipynb files.")
+            ctx.exit(1)
+
+        try:
+            lines = parse_line_ranges(line_ranges)
+        except ValueError as e:
+            err(str(e))
+            ctx.exit(1)
+
     if code is not None:
         # Run in quiet mode by default with -c; the extra output isn't useful.
         # You can still pass -v to get verbose output.
@@ -553,7 +587,12 @@ def main(  # noqa: C901
 
     if code is not None:
         reformat_code(
-            content=code, fast=fast, write_back=write_back, mode=mode, report=report
+            content=code,
+            fast=fast,
+            write_back=write_back,
+            mode=mode,
+            report=report,
+            lines=lines,
         )
     else:
         assert root is not None  # root is only None if code is not None
@@ -588,10 +627,14 @@ def main(  # noqa: C901
                 write_back=write_back,
                 mode=mode,
                 report=report,
+                lines=lines,
             )
         else:
             from black.concurrency import reformat_many
 
+            if lines:
+                err("Cannot use --line-ranges to format multiple files.")
+                ctx.exit(1)
             reformat_many(
                 sources=sources,
                 fast=fast,
@@ -714,7 +757,13 @@ def path_empty(
 
 
 def reformat_code(
-    content: str, fast: bool, write_back: WriteBack, mode: Mode, report: Report
+    content: str,
+    fast: bool,
+    write_back: WriteBack,
+    mode: Mode,
+    report: Report,
+    *,
+    lines: Collection[Tuple[int, int]] = (),
 ) -> None:
     """
     Reformat and print out `content` without spawning child processes.
@@ -727,7 +776,7 @@ def reformat_code(
     try:
         changed = Changed.NO
         if format_stdin_to_stdout(
-            content=content, fast=fast, write_back=write_back, mode=mode
+            content=content, fast=fast, write_back=write_back, mode=mode, lines=lines
         ):
             changed = Changed.YES
         report.done(path, changed)
@@ -741,7 +790,13 @@ def reformat_code(
 # not ideal, but this shouldn't cause any issues ... hopefully. ~ichard26
 @mypyc_attr(patchable=True)
 def reformat_one(
-    src: Path, fast: bool, write_back: WriteBack, mode: Mode, report: "Report"
+    src: Path,
+    fast: bool,
+    write_back: WriteBack,
+    mode: Mode,
+    report: "Report",
+    *,
+    lines: Collection[Tuple[int, int]] = (),
 ) -> None:
     """Reformat a single file under `src` without spawning child processes.
 
@@ -766,7 +821,9 @@ def reformat_one(
                 mode = replace(mode, is_pyi=True)
             elif src.suffix == ".ipynb":
                 mode = replace(mode, is_ipynb=True)
-            if format_stdin_to_stdout(fast=fast, write_back=write_back, mode=mode):
+            if format_stdin_to_stdout(
+                fast=fast, write_back=write_back, mode=mode, lines=lines
+            ):
                 changed = Changed.YES
         else:
             cache = Cache.read(mode)
@@ -774,7 +831,7 @@ def reformat_one(
                 if not cache.is_changed(src):
                     changed = Changed.CACHED
             if changed is not Changed.CACHED and format_file_in_place(
-                src, fast=fast, write_back=write_back, mode=mode
+                src, fast=fast, write_back=write_back, mode=mode, lines=lines
             ):
                 changed = Changed.YES
             if (write_back is WriteBack.YES and changed is not Changed.CACHED) or (
@@ -794,6 +851,8 @@ def format_file_in_place(
     mode: Mode,
     write_back: WriteBack = WriteBack.NO,
     lock: Any = None,  # multiprocessing.Manager().Lock() is some crazy proxy
+    *,
+    lines: Collection[Tuple[int, int]] = (),
 ) -> bool:
     """Format file under `src` path. Return True if changed.
 
@@ -813,7 +872,9 @@ def format_file_in_place(
             header = buf.readline()
         src_contents, encoding, newline = decode_bytes(buf.read())
     try:
-        dst_contents = format_file_contents(src_contents, fast=fast, mode=mode)
+        dst_contents = format_file_contents(
+            src_contents, fast=fast, mode=mode, lines=lines
+        )
     except NothingChanged:
         return False
     except JSONDecodeError:
@@ -858,6 +919,7 @@ def format_stdin_to_stdout(
     content: Optional[str] = None,
     write_back: WriteBack = WriteBack.NO,
     mode: Mode,
+    lines: Collection[Tuple[int, int]] = (),
 ) -> bool:
     """Format file on stdin. Return True if changed.
 
@@ -876,7 +938,7 @@ def format_stdin_to_stdout(
 
     dst = src
     try:
-        dst = format_file_contents(src, fast=fast, mode=mode)
+        dst = format_file_contents(src, fast=fast, mode=mode, lines=lines)
         return True
 
     except NothingChanged:
@@ -904,7 +966,11 @@ def format_stdin_to_stdout(
 
 
 def check_stability_and_equivalence(
-    src_contents: str, dst_contents: str, *, mode: Mode
+    src_contents: str,
+    dst_contents: str,
+    *,
+    mode: Mode,
+    lines: Collection[Tuple[int, int]] = (),
 ) -> None:
     """Perform stability and equivalence checks.
 
@@ -913,10 +979,16 @@ def check_stability_and_equivalence(
     content differently.
     """
     assert_equivalent(src_contents, dst_contents)
-    assert_stable(src_contents, dst_contents, mode=mode)
+    assert_stable(src_contents, dst_contents, mode=mode, lines=lines)
 
 
-def format_file_contents(src_contents: str, *, fast: bool, mode: Mode) -> FileContent:
+def format_file_contents(
+    src_contents: str,
+    *,
+    fast: bool,
+    mode: Mode,
+    lines: Collection[Tuple[int, int]] = (),
+) -> FileContent:
     """Reformat contents of a file and return new contents.
 
     If `fast` is False, additionally confirm that the reformatted code is
@@ -926,13 +998,15 @@ def format_file_contents(src_contents: str, *, fast: bool, mode: Mode) -> FileCo
     if mode.is_ipynb:
         dst_contents = format_ipynb_string(src_contents, fast=fast, mode=mode)
     else:
-        dst_contents = format_str(src_contents, mode=mode)
+        dst_contents = format_str(src_contents, mode=mode, lines=lines)
     if src_contents == dst_contents:
         raise NothingChanged
 
     if not fast and not mode.is_ipynb:
         # Jupyter notebooks will already have been checked above.
-        check_stability_and_equivalence(src_contents, dst_contents, mode=mode)
+        check_stability_and_equivalence(
+            src_contents, dst_contents, mode=mode, lines=lines
+        )
     return dst_contents
 
 
@@ -1043,7 +1117,9 @@ def format_ipynb_string(src_contents: str, *, fast: bool, mode: Mode) -> FileCon
         raise NothingChanged
 
 
-def format_str(src_contents: str, *, mode: Mode) -> str:
+def format_str(
+    src_contents: str, *, mode: Mode, lines: Collection[Tuple[int, int]] = ()
+) -> str:
     """Reformat a string and return new contents.
 
     `mode` determines formatting options, such as how many characters per line are
@@ -1073,16 +1149,20 @@ def f(
         hey
 
     """
-    dst_contents = _format_str_once(src_contents, mode=mode)
+    dst_contents = _format_str_once(src_contents, mode=mode, lines=lines)
     # Forced second pass to work around optional trailing commas (becoming
     # forced trailing commas on pass 2) interacting differently with optional
     # parentheses.  Admittedly ugly.
     if src_contents != dst_contents:
-        return _format_str_once(dst_contents, mode=mode)
+        if lines:
+            lines = adjusted_lines(lines, src_contents, dst_contents)
+        return _format_str_once(dst_contents, mode=mode, lines=lines)
     return dst_contents
 
 
-def _format_str_once(src_contents: str, *, mode: Mode) -> str:
+def _format_str_once(
+    src_contents: str, *, mode: Mode, lines: Collection[Tuple[int, int]] = ()
+) -> str:
     src_node = lib2to3_parse(src_contents.lstrip(), mode.target_versions)
     dst_blocks: List[LinesBlock] = []
     if mode.target_versions:
@@ -1097,7 +1177,11 @@ def _format_str_once(src_contents: str, *, mode: Mode) -> str:
         if supports_feature(versions, feature)
     }
     normalize_fmt_off(src_node, mode)
-    lines = LineGenerator(mode=mode, features=context_manager_features)
+    if lines:
+        # This should be called after normalize_fmt_off.
+        convert_unchanged_lines(src_node, lines)
+
+    line_generator = LineGenerator(mode=mode, features=context_manager_features)
     elt = EmptyLineTracker(mode=mode)
     split_line_features = {
         feature
@@ -1105,7 +1189,7 @@ def _format_str_once(src_contents: str, *, mode: Mode) -> str:
         if supports_feature(versions, feature)
     }
     block: Optional[LinesBlock] = None
-    for current_line in lines.visit(src_node):
+    for current_line in line_generator.visit(src_node):
         block = elt.maybe_empty_lines(current_line)
         dst_blocks.append(block)
         for line in transform_line(
@@ -1373,12 +1457,16 @@ def assert_equivalent(src: str, dst: str) -> None:
         ) from None
 
 
-def assert_stable(src: str, dst: str, mode: Mode) -> None:
+def assert_stable(
+    src: str, dst: str, mode: Mode, *, lines: Collection[Tuple[int, int]] = ()
+) -> None:
     """Raise AssertionError if `dst` reformats differently the second time."""
     # We shouldn't call format_str() here, because that formats the string
     # twice and may hide a bug where we bounce back and forth between two
     # versions.
-    newdst = _format_str_once(dst, mode=mode)
+    if lines:
+        lines = adjusted_lines(lines, src, dst)
+    newdst = _format_str_once(dst, mode=mode, lines=lines)
     if dst != newdst:
         log = dump_to_file(
             str(mode),
diff --git a/src/black/nodes.py b/src/black/nodes.py
index fff8e05a118..9251b0defb0 100644
--- a/src/black/nodes.py
+++ b/src/black/nodes.py
@@ -935,3 +935,31 @@ def is_part_of_annotation(leaf: Leaf) -> bool:
             return True
         ancestor = ancestor.parent
     return False
+
+
+def first_leaf(node: LN) -> Optional[Leaf]:
+    """Returns the first leaf of the ancestor node."""
+    if isinstance(node, Leaf):
+        return node
+    elif not node.children:
+        return None
+    else:
+        return first_leaf(node.children[0])
+
+
+def last_leaf(node: LN) -> Optional[Leaf]:
+    """Returns the last leaf of the ancestor node."""
+    if isinstance(node, Leaf):
+        return node
+    elif not node.children:
+        return None
+    else:
+        return last_leaf(node.children[-1])
+
+
+def furthest_ancestor_with_last_leaf(leaf: Leaf) -> LN:
+    """Returns the furthest ancestor that has this leaf node as the last leaf."""
+    node: LN = leaf
+    while node.parent and node.parent.children and node is node.parent.children[-1]:
+        node = node.parent
+    return node
diff --git a/src/black/ranges.py b/src/black/ranges.py
new file mode 100644
index 00000000000..b0c312e6274
--- /dev/null
+++ b/src/black/ranges.py
@@ -0,0 +1,496 @@
+"""Functions related to Black's formatting by line ranges feature."""
+
+import difflib
+from dataclasses import dataclass
+from typing import Collection, Iterator, List, Sequence, Set, Tuple, Union
+
+from black.nodes import (
+    LN,
+    STANDALONE_COMMENT,
+    Leaf,
+    Node,
+    Visitor,
+    first_leaf,
+    furthest_ancestor_with_last_leaf,
+    last_leaf,
+    syms,
+)
+from blib2to3.pgen2.token import ASYNC, NEWLINE
+
+
+def parse_line_ranges(line_ranges: Sequence[str]) -> List[Tuple[int, int]]:
+    lines: List[Tuple[int, int]] = []
+    for lines_str in line_ranges:
+        parts = lines_str.split("-")
+        if len(parts) != 2:
+            raise ValueError(
+                "Incorrect --line-ranges format, expect 'START-END', found"
+                f" {lines_str!r}"
+            )
+        try:
+            start = int(parts[0])
+            end = int(parts[1])
+        except ValueError:
+            raise ValueError(
+                "Incorrect --line-ranges value, expect integer ranges, found"
+                f" {lines_str!r}"
+            ) from None
+        else:
+            lines.append((start, end))
+    return lines
+
+
+def is_valid_line_range(lines: Tuple[int, int]) -> bool:
+    """Returns whether the line range is valid."""
+    return not lines or lines[0] <= lines[1]
+
+
+def adjusted_lines(
+    lines: Collection[Tuple[int, int]],
+    original_source: str,
+    modified_source: str,
+) -> List[Tuple[int, int]]:
+    """Returns the adjusted line ranges based on edits from the original code.
+
+    This computes the new line ranges by diffing original_source and
+    modified_source, and adjust each range based on how the range overlaps with
+    the diffs.
+
+    Note the diff can contain lines outside of the original line ranges. This can
+    happen when the formatting has to be done in adjacent to maintain consistent
+    local results. For example:
+
+    1. def my_func(arg1, arg2,
+    2.             arg3,):
+    3.   pass
+
+    If it restricts to line 2-2, it can't simply reformat line 2, it also has
+    to reformat line 1:
+
+    1. def my_func(
+    2.     arg1,
+    3.     arg2,
+    4.     arg3,
+    5. ):
+    6.   pass
+
+    In this case, we will expand the line ranges to also include the whole diff
+    block.
+
+    Args:
+      lines: a collection of line ranges.
+      original_source: the original source.
+      modified_source: the modified source.
+    """
+    lines_mappings = _calculate_lines_mappings(original_source, modified_source)
+
+    new_lines = []
+    # Keep an index of the current search. Since the lines and lines_mappings are
+    # sorted, this makes the search complexity linear.
+    current_mapping_index = 0
+    for start, end in sorted(lines):
+        start_mapping_index = _find_lines_mapping_index(
+            start,
+            lines_mappings,
+            current_mapping_index,
+        )
+        end_mapping_index = _find_lines_mapping_index(
+            end,
+            lines_mappings,
+            start_mapping_index,
+        )
+        current_mapping_index = start_mapping_index
+        if start_mapping_index >= len(lines_mappings) or end_mapping_index >= len(
+            lines_mappings
+        ):
+            # Protect against invalid inputs.
+            continue
+        start_mapping = lines_mappings[start_mapping_index]
+        end_mapping = lines_mappings[end_mapping_index]
+        if start_mapping.is_changed_block:
+            # When the line falls into a changed block, expands to the whole block.
+            new_start = start_mapping.modified_start
+        else:
+            new_start = (
+                start - start_mapping.original_start + start_mapping.modified_start
+            )
+        if end_mapping.is_changed_block:
+            # When the line falls into a changed block, expands to the whole block.
+            new_end = end_mapping.modified_end
+        else:
+            new_end = end - end_mapping.original_start + end_mapping.modified_start
+        new_range = (new_start, new_end)
+        if is_valid_line_range(new_range):
+            new_lines.append(new_range)
+    return new_lines
+
+
+def convert_unchanged_lines(src_node: Node, lines: Collection[Tuple[int, int]]) -> None:
+    """Converts unchanged lines to STANDALONE_COMMENT.
+
+    The idea is similar to how `# fmt: on/off` is implemented. It also converts the
+    nodes between those markers as a single `STANDALONE_COMMENT` leaf node with
+    the unformatted code as its value. `STANDALONE_COMMENT` is a "fake" token
+    that will be formatted as-is with its prefix normalized.
+
+    Here we perform two passes:
+
+    1. Visit the top-level statements, and convert them to a single
+       `STANDALONE_COMMENT` when unchanged. This speeds up formatting when some
+       of the top-level statements aren't changed.
+    2. Convert unchanged "unwrapped lines" to `STANDALONE_COMMENT` nodes line by
+       line. "unwrapped lines" are divided by the `NEWLINE` token. e.g. a
+       multi-line statement is *one* "unwrapped line" that ends with `NEWLINE`,
+       even though this statement itself can span multiple lines, and the
+       tokenizer only sees the last '\n' as the `NEWLINE` token.
+
+    NOTE: During pass (2), comment prefixes and indentations are ALWAYS
+    normalized even when the lines aren't changed. This is fixable by moving
+    more formatting to pass (1). However, it's hard to get it correct when
+    incorrect indentations are used. So we defer this to future optimizations.
+    """
+    lines_set: Set[int] = set()
+    for start, end in lines:
+        lines_set.update(range(start, end + 1))
+    visitor = _TopLevelStatementsVisitor(lines_set)
+    _ = list(visitor.visit(src_node))  # Consume all results.
+    _convert_unchanged_line_by_line(src_node, lines_set)
+
+
+def _contains_standalone_comment(node: LN) -> bool:
+    if isinstance(node, Leaf):
+        return node.type == STANDALONE_COMMENT
+    else:
+        for child in node.children:
+            if _contains_standalone_comment(child):
+                return True
+        return False
+
+
+class _TopLevelStatementsVisitor(Visitor[None]):
+    """
+    A node visitor that converts unchanged top-level statements to
+    STANDALONE_COMMENT.
+
+    This is used in addition to _convert_unchanged_lines_by_flatterning, to
+    speed up formatting when there are unchanged top-level
+    classes/functions/statements.
+    """
+
+    def __init__(self, lines_set: Set[int]):
+        self._lines_set = lines_set
+
+    def visit_simple_stmt(self, node: Node) -> Iterator[None]:
+        # This is only called for top-level statements, since `visit_suite`
+        # won't visit its children nodes.
+        yield from []
+        newline_leaf = last_leaf(node)
+        if not newline_leaf:
+            return
+        assert (
+            newline_leaf.type == NEWLINE
+        ), f"Unexpectedly found leaf.type={newline_leaf.type}"
+        # We need to find the furthest ancestor with the NEWLINE as the last
+        # leaf, since a `suite` can simply be a `simple_stmt` when it puts
+        # its body on the same line. Example: `if cond: pass`.
+        ancestor = furthest_ancestor_with_last_leaf(newline_leaf)
+        if not _get_line_range(ancestor).intersection(self._lines_set):
+            _convert_node_to_standalone_comment(ancestor)
+
+    def visit_suite(self, node: Node) -> Iterator[None]:
+        yield from []
+        # If there is a STANDALONE_COMMENT node, it means parts of the node tree
+        # have fmt on/off/skip markers. Those STANDALONE_COMMENT nodes can't
+        # be simply converted by calling str(node). So we just don't convert
+        # here.
+        if _contains_standalone_comment(node):
+            return
+        # Find the semantic parent of this suite. For `async_stmt` and
+        # `async_funcdef`, the ASYNC token is defined on a separate level by the
+        # grammar.
+        semantic_parent = node.parent
+        if semantic_parent is not None:
+            if (
+                semantic_parent.prev_sibling is not None
+                and semantic_parent.prev_sibling.type == ASYNC
+            ):
+                semantic_parent = semantic_parent.parent
+        if semantic_parent is not None and not _get_line_range(
+            semantic_parent
+        ).intersection(self._lines_set):
+            _convert_node_to_standalone_comment(semantic_parent)
+
+
+def _convert_unchanged_line_by_line(node: Node, lines_set: Set[int]) -> None:
+    """Converts unchanged to STANDALONE_COMMENT line by line."""
+    for leaf in node.leaves():
+        if leaf.type != NEWLINE:
+            # We only consider "unwrapped lines", which are divided by the NEWLINE
+            # token.
+            continue
+        if leaf.parent and leaf.parent.type == syms.match_stmt:
+            # The `suite` node is defined as:
+            #   match_stmt: "match" subject_expr ':' NEWLINE INDENT case_block+ DEDENT
+            # Here we need to check `subject_expr`. The `case_block+` will be
+            # checked by their own NEWLINEs.
+            nodes_to_ignore: List[LN] = []
+            prev_sibling = leaf.prev_sibling
+            while prev_sibling:
+                nodes_to_ignore.insert(0, prev_sibling)
+                prev_sibling = prev_sibling.prev_sibling
+            if not _get_line_range(nodes_to_ignore).intersection(lines_set):
+                _convert_nodes_to_standalone_comment(nodes_to_ignore, newline=leaf)
+        elif leaf.parent and leaf.parent.type == syms.suite:
+            # The `suite` node is defined as:
+            #   suite: simple_stmt | NEWLINE INDENT stmt+ DEDENT
+            # We will check `simple_stmt` and `stmt+` separately against the lines set
+            parent_sibling = leaf.parent.prev_sibling
+            nodes_to_ignore = []
+            while parent_sibling and not parent_sibling.type == syms.suite:
+                # NOTE: Multiple suite nodes can exist as siblings in e.g. `if_stmt`.
+                nodes_to_ignore.insert(0, parent_sibling)
+                parent_sibling = parent_sibling.prev_sibling
+            # Special case for `async_stmt` and `async_funcdef` where the ASYNC
+            # token is on the grandparent node.
+            grandparent = leaf.parent.parent
+            if (
+                grandparent is not None
+                and grandparent.prev_sibling is not None
+                and grandparent.prev_sibling.type == ASYNC
+            ):
+                nodes_to_ignore.insert(0, grandparent.prev_sibling)
+            if not _get_line_range(nodes_to_ignore).intersection(lines_set):
+                _convert_nodes_to_standalone_comment(nodes_to_ignore, newline=leaf)
+        else:
+            ancestor = furthest_ancestor_with_last_leaf(leaf)
+            # Consider multiple decorators as a whole block, as their
+            # newlines have different behaviors than the rest of the grammar.
+            if (
+                ancestor.type == syms.decorator
+                and ancestor.parent
+                and ancestor.parent.type == syms.decorators
+            ):
+                ancestor = ancestor.parent
+            if not _get_line_range(ancestor).intersection(lines_set):
+                _convert_node_to_standalone_comment(ancestor)
+
+
+def _convert_node_to_standalone_comment(node: LN) -> None:
+    """Convert node to STANDALONE_COMMENT by modifying the tree inline."""
+    parent = node.parent
+    if not parent:
+        return
+    first = first_leaf(node)
+    last = last_leaf(node)
+    if not first or not last:
+        return
+    if first is last:
+        # This can happen on the following edge cases:
+        # 1. A block of `# fmt: off/on` code except the `# fmt: on` is placed
+        #    on the end of the last line instead of on a new line.
+        # 2. A single backslash on its own line followed by a comment line.
+        # Ideally we don't want to format them when not requested, but fixing
+        # isn't easy. These cases are also badly formatted code, so it isn't
+        # too bad we reformat them.
+        return
+    # The prefix contains comments and indentation whitespaces. They are
+    # reformatted accordingly to the correct indentation level.
+    # This also means the indentation will be changed on the unchanged lines, and
+    # this is actually required to not break incremental reformatting.
+    prefix = first.prefix
+    first.prefix = ""
+    index = node.remove()
+    if index is not None:
+        # Remove the '\n', as STANDALONE_COMMENT will have '\n' appended when
+        # genearting the formatted code.
+        value = str(node)[:-1]
+        parent.insert_child(
+            index,
+            Leaf(
+                STANDALONE_COMMENT,
+                value,
+                prefix=prefix,
+                fmt_pass_converted_first_leaf=first,
+            ),
+        )
+
+
+def _convert_nodes_to_standalone_comment(nodes: Sequence[LN], *, newline: Leaf) -> None:
+    """Convert nodes to STANDALONE_COMMENT by modifying the tree inline."""
+    if not nodes:
+        return
+    parent = nodes[0].parent
+    first = first_leaf(nodes[0])
+    if not parent or not first:
+        return
+    prefix = first.prefix
+    first.prefix = ""
+    value = "".join(str(node) for node in nodes)
+    # The prefix comment on the NEWLINE leaf is the trailing comment of the statement.
+    if newline.prefix:
+        value += newline.prefix
+        newline.prefix = ""
+    index = nodes[0].remove()
+    for node in nodes[1:]:
+        node.remove()
+    if index is not None:
+        parent.insert_child(
+            index,
+            Leaf(
+                STANDALONE_COMMENT,
+                value,
+                prefix=prefix,
+                fmt_pass_converted_first_leaf=first,
+            ),
+        )
+
+
+def _leaf_line_end(leaf: Leaf) -> int:
+    """Returns the line number of the leaf node's last line."""
+    if leaf.type == NEWLINE:
+        return leaf.lineno
+    else:
+        # Leaf nodes like multiline strings can occupy multiple lines.
+        return leaf.lineno + str(leaf).count("\n")
+
+
+def _get_line_range(node_or_nodes: Union[LN, List[LN]]) -> Set[int]:
+    """Returns the line range of this node or list of nodes."""
+    if isinstance(node_or_nodes, list):
+        nodes = node_or_nodes
+        if not nodes:
+            return set()
+        first = first_leaf(nodes[0])
+        last = last_leaf(nodes[-1])
+        if first and last:
+            line_start = first.lineno
+            line_end = _leaf_line_end(last)
+            return set(range(line_start, line_end + 1))
+        else:
+            return set()
+    else:
+        node = node_or_nodes
+        if isinstance(node, Leaf):
+            return set(range(node.lineno, _leaf_line_end(node) + 1))
+        else:
+            first = first_leaf(node)
+            last = last_leaf(node)
+            if first and last:
+                return set(range(first.lineno, _leaf_line_end(last) + 1))
+            else:
+                return set()
+
+
+@dataclass
+class _LinesMapping:
+    """1-based lines mapping from original source to modified source.
+
+    Lines [original_start, original_end] from original source
+    are mapped to [modified_start, modified_end].
+
+    The ranges are inclusive on both ends.
+    """
+
+    original_start: int
+    original_end: int
+    modified_start: int
+    modified_end: int
+    # Whether this range corresponds to a changed block, or an unchanged block.
+    is_changed_block: bool
+
+
+def _calculate_lines_mappings(
+    original_source: str,
+    modified_source: str,
+) -> Sequence[_LinesMapping]:
+    """Returns a sequence of _LinesMapping by diffing the sources.
+
+    For example, given the following diff:
+        import re
+      - def func(arg1,
+      -   arg2, arg3):
+      + def func(arg1, arg2, arg3):
+          pass
+    It returns the following mappings:
+      original -> modified
+       (1, 1)  ->  (1, 1), is_changed_block=False (the "import re" line)
+       (2, 3)  ->  (2, 2), is_changed_block=True (the diff)
+       (4, 4)  ->  (3, 3), is_changed_block=False (the "pass" line)
+
+    You can think of this visually as if it brings up a side-by-side diff, and tries
+    to map the line ranges from the left side to the right side:
+
+      (1, 1)->(1, 1)    1. import re          1. import re
+      (2, 3)->(2, 2)    2. def func(arg1,     2. def func(arg1, arg2, arg3):
+                        3.   arg2, arg3):
+      (4, 4)->(3, 3)    4.   pass             3.   pass
+
+    Args:
+      original_source: the original source.
+      modified_source: the modified source.
+    """
+    matcher = difflib.SequenceMatcher(
+        None,
+        original_source.splitlines(keepends=True),
+        modified_source.splitlines(keepends=True),
+    )
+    matching_blocks = matcher.get_matching_blocks()
+    lines_mappings: List[_LinesMapping] = []
+    # matching_blocks is a sequence of "same block of code ranges", see
+    # https://docs.python.org/3/library/difflib.html#difflib.SequenceMatcher.get_matching_blocks
+    # Each block corresponds to a _LinesMapping with is_changed_block=False,
+    # and the ranges between two blocks corresponds to a _LinesMapping with
+    # is_changed_block=True,
+    # NOTE: matching_blocks is 0-based, but _LinesMapping is 1-based.
+    for i, block in enumerate(matching_blocks):
+        if i == 0:
+            if block.a != 0 or block.b != 0:
+                lines_mappings.append(
+                    _LinesMapping(
+                        original_start=1,
+                        original_end=block.a,
+                        modified_start=1,
+                        modified_end=block.b,
+                        is_changed_block=False,
+                    )
+                )
+        else:
+            previous_block = matching_blocks[i - 1]
+            lines_mappings.append(
+                _LinesMapping(
+                    original_start=previous_block.a + previous_block.size + 1,
+                    original_end=block.a,
+                    modified_start=previous_block.b + previous_block.size + 1,
+                    modified_end=block.b,
+                    is_changed_block=True,
+                )
+            )
+        if i < len(matching_blocks) - 1:
+            lines_mappings.append(
+                _LinesMapping(
+                    original_start=block.a + 1,
+                    original_end=block.a + block.size,
+                    modified_start=block.b + 1,
+                    modified_end=block.b + block.size,
+                    is_changed_block=False,
+                )
+            )
+    return lines_mappings
+
+
+def _find_lines_mapping_index(
+    original_line: int,
+    lines_mappings: Sequence[_LinesMapping],
+    start_index: int,
+) -> int:
+    """Returns the original index of the lines mappings for the original line."""
+    index = start_index
+    while index < len(lines_mappings):
+        mapping = lines_mappings[index]
+        if (
+            mapping.original_start <= original_line
+            and original_line <= mapping.original_end
+        ):
+            return index
+        index += 1
+    return index
diff --git a/tests/data/cases/line_ranges_basic.py b/tests/data/cases/line_ranges_basic.py
new file mode 100644
index 00000000000..9f0fb2da70e
--- /dev/null
+++ b/tests/data/cases/line_ranges_basic.py
@@ -0,0 +1,107 @@
+# flags: --line-ranges=5-6
+# NOTE: If you need to modify this file, pay special attention to the --line-ranges=
+# flag above as it's formatting specifically these lines.
+def foo1(parameter_1, parameter_2, parameter_3, parameter_4, parameter_5, parameter_6, parameter_7): pass
+def foo2(parameter_1, parameter_2, parameter_3, parameter_4, parameter_5, parameter_6, parameter_7): pass
+def foo3(parameter_1, parameter_2, parameter_3, parameter_4, parameter_5, parameter_6, parameter_7): pass
+def foo4(parameter_1, parameter_2, parameter_3, parameter_4, parameter_5, parameter_6, parameter_7): pass
+
+# Adding some unformated code covering a wide range of syntaxes.
+
+if True:
+      # Incorrectly indented prefix comments.
+  pass
+
+import   typing
+from  typing   import   (
+      Any  ,
+   )
+class   MyClass(  object):     # Trailing comment with extra leading space.
+        #NOTE: The following indentation is incorrect:
+      @decor( 1  *  3 )
+      def  my_func(  arg):
+                pass
+
+try:                                       # Trailing comment with extra leading space.
+    for   i   in   range(10):              # Trailing comment with extra leading space.
+        while    condition:
+            if   something:
+                then_something(  )
+            elif    something_else:
+                then_something_else(  )
+except  ValueError  as  e:
+    unformatted(  )
+finally:
+    unformatted(  )
+
+async  def  test_async_unformatted(  ):    # Trailing comment with extra leading space.
+    async  for  i  in some_iter(  unformatted  ):    # Trailing comment with extra leading space.
+        await  asyncio.sleep( 1 )
+        async  with  some_context(  unformatted  ):
+            print(  "unformatted"  )
+
+
+# output
+# flags: --line-ranges=5-6
+# NOTE: If you need to modify this file, pay special attention to the --line-ranges=
+# flag above as it's formatting specifically these lines.
+def foo1(parameter_1, parameter_2, parameter_3, parameter_4, parameter_5, parameter_6, parameter_7): pass
+def foo2(
+    parameter_1,
+    parameter_2,
+    parameter_3,
+    parameter_4,
+    parameter_5,
+    parameter_6,
+    parameter_7,
+):
+    pass
+
+
+def foo3(
+    parameter_1,
+    parameter_2,
+    parameter_3,
+    parameter_4,
+    parameter_5,
+    parameter_6,
+    parameter_7,
+):
+    pass
+
+
+def foo4(parameter_1, parameter_2, parameter_3, parameter_4, parameter_5, parameter_6, parameter_7): pass
+
+# Adding some unformated code covering a wide range of syntaxes.
+
+if True:
+      # Incorrectly indented prefix comments.
+  pass
+
+import   typing
+from  typing   import   (
+      Any  ,
+   )
+class   MyClass(  object):     # Trailing comment with extra leading space.
+        #NOTE: The following indentation is incorrect:
+      @decor( 1  *  3 )
+      def  my_func(  arg):
+                pass
+
+try:                                       # Trailing comment with extra leading space.
+    for   i   in   range(10):              # Trailing comment with extra leading space.
+        while    condition:
+            if   something:
+                then_something(  )
+            elif    something_else:
+                then_something_else(  )
+except  ValueError  as  e:
+    unformatted(  )
+finally:
+    unformatted(  )
+
+async  def  test_async_unformatted(  ):    # Trailing comment with extra leading space.
+    async  for  i  in some_iter(  unformatted  ):    # Trailing comment with extra leading space.
+        await  asyncio.sleep( 1 )
+        async  with  some_context(  unformatted  ):
+            print(  "unformatted"  )
diff --git a/tests/data/cases/line_ranges_fmt_off.py b/tests/data/cases/line_ranges_fmt_off.py
new file mode 100644
index 00000000000..b51cef58fe5
--- /dev/null
+++ b/tests/data/cases/line_ranges_fmt_off.py
@@ -0,0 +1,49 @@
+# flags: --line-ranges=7-7 --line-ranges=17-23
+# NOTE: If you need to modify this file, pay special attention to the --line-ranges=
+# flag above as it's formatting specifically these lines.
+
+# fmt: off
+import   os
+def   myfunc(  ):  # Intentionally unformatted.
+    pass
+# fmt: on
+
+
+def   myfunc(  ):  # This will not be reformatted.
+    print(  {"also won't be reformatted"}  )
+# fmt: off
+def   myfunc(  ):  # This will not be reformatted.
+    print(  {"also won't be reformatted"}  )
+def   myfunc(  ):  # This will not be reformatted.
+    print(  {"also won't be reformatted"}  )
+# fmt: on
+
+
+def   myfunc(  ):  # This will be reformatted.
+    print(  {"this will be reformatted"}  )
+
+# output
+
+# flags: --line-ranges=7-7 --line-ranges=17-23
+# NOTE: If you need to modify this file, pay special attention to the --line-ranges=
+# flag above as it's formatting specifically these lines.
+
+# fmt: off
+import   os
+def   myfunc(  ):  # Intentionally unformatted.
+    pass
+# fmt: on
+
+
+def   myfunc(  ):  # This will not be reformatted.
+    print(  {"also won't be reformatted"}  )
+# fmt: off
+def   myfunc(  ):  # This will not be reformatted.
+    print(  {"also won't be reformatted"}  )
+def   myfunc(  ):  # This will not be reformatted.
+    print(  {"also won't be reformatted"}  )
+# fmt: on
+
+
+def myfunc():  # This will be reformatted.
+    print({"this will be reformatted"})
diff --git a/tests/data/cases/line_ranges_fmt_off_decorator.py b/tests/data/cases/line_ranges_fmt_off_decorator.py
new file mode 100644
index 00000000000..14aa1dda02d
--- /dev/null
+++ b/tests/data/cases/line_ranges_fmt_off_decorator.py
@@ -0,0 +1,27 @@
+# flags: --line-ranges=12-12
+# NOTE: If you need to modify this file, pay special attention to the --line-ranges=
+# flag above as it's formatting specifically these lines.
+
+# Regression test for an edge case involving decorators and fmt: off/on.
+class MyClass:
+
+    # fmt: off
+    @decorator  (  )
+    # fmt: on
+    def method():
+        print   ( "str" )
+
+# output
+
+# flags: --line-ranges=12-12
+# NOTE: If you need to modify this file, pay special attention to the --line-ranges=
+# flag above as it's formatting specifically these lines.
+
+# Regression test for an edge case involving decorators and fmt: off/on.
+class MyClass:
+
+    # fmt: off
+    @decorator  (  )
+    # fmt: on
+    def method():
+        print("str")
diff --git a/tests/data/cases/line_ranges_fmt_off_overlap.py b/tests/data/cases/line_ranges_fmt_off_overlap.py
new file mode 100644
index 00000000000..0391d17a843
--- /dev/null
+++ b/tests/data/cases/line_ranges_fmt_off_overlap.py
@@ -0,0 +1,37 @@
+# flags: --line-ranges=11-17
+# NOTE: If you need to modify this file, pay special attention to the --line-ranges=
+# flag above as it's formatting specifically these lines.
+
+
+def   myfunc(  ):  # This will not be reformatted.
+    print(  {"also won't be reformatted"}  )
+# fmt: off
+def   myfunc(  ):  # This will not be reformatted.
+    print(  {"also won't be reformatted"}  )
+def   myfunc(  ):  # This will not be reformatted.
+    print(  {"also won't be reformatted"}  )
+# fmt: on
+
+
+def   myfunc(  ):  # This will be reformatted.
+    print(  {"this will be reformatted"}  )
+
+# output
+
+# flags: --line-ranges=11-17
+# NOTE: If you need to modify this file, pay special attention to the --line-ranges=
+# flag above as it's formatting specifically these lines.
+
+
+def   myfunc(  ):  # This will not be reformatted.
+    print(  {"also won't be reformatted"}  )
+# fmt: off
+def   myfunc(  ):  # This will not be reformatted.
+    print(  {"also won't be reformatted"}  )
+def   myfunc(  ):  # This will not be reformatted.
+    print(  {"also won't be reformatted"}  )
+# fmt: on
+
+
+def myfunc():  # This will be reformatted.
+    print({"this will be reformatted"})
diff --git a/tests/data/cases/line_ranges_imports.py b/tests/data/cases/line_ranges_imports.py
new file mode 100644
index 00000000000..76b18ffecb3
--- /dev/null
+++ b/tests/data/cases/line_ranges_imports.py
@@ -0,0 +1,9 @@
+# flags: --line-ranges=8-8
+# NOTE: If you need to modify this file, pay special attention to the --line-ranges=
+# flag above as it's formatting specifically these lines.
+
+# This test ensures no empty lines are added around import lines.
+# It caused an issue before https://github.com/psf/black/pull/3610 is merged.
+import os
+import re
+import sys
diff --git a/tests/data/cases/line_ranges_indentation.py b/tests/data/cases/line_ranges_indentation.py
new file mode 100644
index 00000000000..82d3ad69a5e
--- /dev/null
+++ b/tests/data/cases/line_ranges_indentation.py
@@ -0,0 +1,27 @@
+# flags: --line-ranges=5-5
+# NOTE: If you need to modify this file, pay special attention to the --line-ranges=
+# flag above as it's formatting specifically these lines.
+if cond1:
+  print("first")
+  if cond2:
+    print("second")
+  else:
+    print("else")
+
+if another_cond:
+  print("will not be changed")
+
+# output
+
+# flags: --line-ranges=5-5
+# NOTE: If you need to modify this file, pay special attention to the --line-ranges=
+# flag above as it's formatting specifically these lines.
+if cond1:
+    print("first")
+    if cond2:
+        print("second")
+    else:
+        print("else")
+
+if another_cond:
+  print("will not be changed")
diff --git a/tests/data/cases/line_ranges_two_passes.py b/tests/data/cases/line_ranges_two_passes.py
new file mode 100644
index 00000000000..aeed3260b8e
--- /dev/null
+++ b/tests/data/cases/line_ranges_two_passes.py
@@ -0,0 +1,27 @@
+# flags: --line-ranges=9-11
+# NOTE: If you need to modify this file, pay special attention to the --line-ranges=
+# flag above as it's formatting specifically these lines.
+
+# This is a specific case for Black's two-pass formatting behavior in `format_str`.
+# The second pass must respect the line ranges before the first pass.
+
+
+def restrict_to_this_line(arg1,
+  arg2,
+  arg3):
+    print  ( "This should not be formatted." )
+    print  ( "Note that in the second pass, the original line range 9-11 will cover these print lines.")
+
+# output
+
+# flags: --line-ranges=9-11
+# NOTE: If you need to modify this file, pay special attention to the --line-ranges=
+# flag above as it's formatting specifically these lines.
+
+# This is a specific case for Black's two-pass formatting behavior in `format_str`.
+# The second pass must respect the line ranges before the first pass.
+
+
+def restrict_to_this_line(arg1, arg2, arg3):
+    print  ( "This should not be formatted." )
+    print  ( "Note that in the second pass, the original line range 9-11 will cover these print lines.")
diff --git a/tests/data/cases/line_ranges_unwrapping.py b/tests/data/cases/line_ranges_unwrapping.py
new file mode 100644
index 00000000000..cd7751b9417
--- /dev/null
+++ b/tests/data/cases/line_ranges_unwrapping.py
@@ -0,0 +1,25 @@
+# flags: --line-ranges=5-5 --line-ranges=9-9 --line-ranges=13-13
+# NOTE: If you need to modify this file, pay special attention to the --line-ranges=
+# flag above as it's formatting specifically these lines.
+alist   =   [
+        1, 2
+]
+
+adict   =   {
+    "key"  :  "value"
+}
+
+func_call  (
+    arg  = value
+)
+
+# output
+
+# flags: --line-ranges=5-5 --line-ranges=9-9 --line-ranges=13-13
+# NOTE: If you need to modify this file, pay special attention to the --line-ranges=
+# flag above as it's formatting specifically these lines.
+alist = [1, 2]
+
+adict = {"key": "value"}
+
+func_call(arg=value)
diff --git a/tests/data/invalid_line_ranges.toml b/tests/data/invalid_line_ranges.toml
new file mode 100644
index 00000000000..791573f2625
--- /dev/null
+++ b/tests/data/invalid_line_ranges.toml
@@ -0,0 +1,2 @@
+[tool.black]
+line-ranges = "1-1"
diff --git a/tests/data/line_ranges_formatted/basic.py b/tests/data/line_ranges_formatted/basic.py
new file mode 100644
index 00000000000..b419b1f16ae
--- /dev/null
+++ b/tests/data/line_ranges_formatted/basic.py
@@ -0,0 +1,50 @@
+"""Module doc."""
+
+from typing import (
+    Callable,
+    Literal,
+)
+
+
+# fmt: off
+class  Unformatted:
+  def   should_also_work(self):
+    pass
+# fmt: on
+
+
+a   = [1, 2]  # fmt: skip
+
+
+# This should cover as many syntaxes as possible.
+class Foo:
+    """Class doc."""
+
+    def __init__(self) -> None:
+        pass
+
+    @add_logging
+    @memoize.memoize(max_items=2)
+    def plus_one(
+        self,
+        number: int,
+    ) -> int:
+        return number + 1
+
+    async def async_plus_one(self, number: int) -> int:
+        await asyncio.sleep(1)
+        async with some_context():
+            return number + 1
+
+
+try:
+    for i in range(10):
+        while condition:
+            if something:
+                then_something()
+            elif something_else:
+                then_something_else()
+except ValueError as e:
+    handle(e)
+finally:
+    done()
diff --git a/tests/data/line_ranges_formatted/pattern_matching.py b/tests/data/line_ranges_formatted/pattern_matching.py
new file mode 100644
index 00000000000..cd98efdd504
--- /dev/null
+++ b/tests/data/line_ranges_formatted/pattern_matching.py
@@ -0,0 +1,25 @@
+# flags: --minimum-version=3.10
+
+
+def pattern_matching():
+    match status:
+        case 1:
+            return "1"
+        case [single]:
+            return "single"
+        case [
+            action,
+            obj,
+        ]:
+            return "act on obj"
+        case Point(x=0):
+            return "class pattern"
+        case {"text": message}:
+            return "mapping"
+        case {
+            "text": message,
+            "format": _,
+        }:
+            return "mapping"
+        case _:
+            return "fallback"
diff --git a/tests/test_black.py b/tests/test_black.py
index c7196098e14..c9819742425 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -8,6 +8,7 @@
 import os
 import re
 import sys
+import textwrap
 import types
 from concurrent.futures import ThreadPoolExecutor
 from contextlib import contextmanager, redirect_stderr
@@ -1269,7 +1270,7 @@ def test_reformat_one_with_stdin_filename(self) -> None:
                 report=report,
             )
             fsts.assert_called_once_with(
-                fast=True, write_back=black.WriteBack.YES, mode=DEFAULT_MODE
+                fast=True, write_back=black.WriteBack.YES, mode=DEFAULT_MODE, lines=()
             )
             # __BLACK_STDIN_FILENAME__ should have been stripped
             report.done.assert_called_with(expected, black.Changed.YES)
@@ -1295,6 +1296,7 @@ def test_reformat_one_with_stdin_filename_pyi(self) -> None:
                 fast=True,
                 write_back=black.WriteBack.YES,
                 mode=replace(DEFAULT_MODE, is_pyi=True),
+                lines=(),
             )
             # __BLACK_STDIN_FILENAME__ should have been stripped
             report.done.assert_called_with(expected, black.Changed.YES)
@@ -1320,6 +1322,7 @@ def test_reformat_one_with_stdin_filename_ipynb(self) -> None:
                 fast=True,
                 write_back=black.WriteBack.YES,
                 mode=replace(DEFAULT_MODE, is_ipynb=True),
+                lines=(),
             )
             # __BLACK_STDIN_FILENAME__ should have been stripped
             report.done.assert_called_with(expected, black.Changed.YES)
@@ -1941,6 +1944,88 @@ def test_equivalency_ast_parse_failure_includes_error(self) -> None:
         err.match("invalid character")
         err.match(r"\(<unknown>, line 1\)")
 
+    def test_line_ranges_with_code_option(self) -> None:
+        code = textwrap.dedent("""\
+            if  a  ==  b:
+                print  ( "OK" )
+            """)
+        args = ["--line-ranges=1-1", "--code", code]
+        result = CliRunner().invoke(black.main, args)
+
+        expected = textwrap.dedent("""\
+            if a == b:
+                print  ( "OK" )
+            """)
+        self.compare_results(result, expected, expected_exit_code=0)
+
+    def test_line_ranges_with_stdin(self) -> None:
+        code = textwrap.dedent("""\
+            if  a  ==  b:
+                print  ( "OK" )
+            """)
+        runner = BlackRunner()
+        result = runner.invoke(
+            black.main, ["--line-ranges=1-1", "-"], input=BytesIO(code.encode("utf-8"))
+        )
+
+        expected = textwrap.dedent("""\
+            if a == b:
+                print  ( "OK" )
+            """)
+        self.compare_results(result, expected, expected_exit_code=0)
+
+    def test_line_ranges_with_source(self) -> None:
+        with TemporaryDirectory() as workspace:
+            test_file = Path(workspace) / "test.py"
+            test_file.write_text(
+                textwrap.dedent("""\
+            if  a  ==  b:
+                print  ( "OK" )
+            """),
+                encoding="utf-8",
+            )
+            args = ["--line-ranges=1-1", str(test_file)]
+            result = CliRunner().invoke(black.main, args)
+            assert not result.exit_code
+
+            formatted = test_file.read_text(encoding="utf-8")
+            expected = textwrap.dedent("""\
+            if a == b:
+                print  ( "OK" )
+            """)
+            assert expected == formatted
+
+    def test_line_ranges_with_multiple_sources(self) -> None:
+        with TemporaryDirectory() as workspace:
+            test1_file = Path(workspace) / "test1.py"
+            test1_file.write_text("", encoding="utf-8")
+            test2_file = Path(workspace) / "test2.py"
+            test2_file.write_text("", encoding="utf-8")
+            args = ["--line-ranges=1-1", str(test1_file), str(test2_file)]
+            result = CliRunner().invoke(black.main, args)
+            assert result.exit_code == 1
+            assert "Cannot use --line-ranges to format multiple files" in result.output
+
+    def test_line_ranges_with_ipynb(self) -> None:
+        with TemporaryDirectory() as workspace:
+            test_file = Path(workspace) / "test.ipynb"
+            test_file.write_text("{}", encoding="utf-8")
+            args = ["--line-ranges=1-1", "--ipynb", str(test_file)]
+            result = CliRunner().invoke(black.main, args)
+            assert "Cannot use --line-ranges with ipynb files" in result.output
+            assert result.exit_code == 1
+
+    def test_line_ranges_in_pyproject_toml(self) -> None:
+        config = THIS_DIR / "data" / "invalid_line_ranges.toml"
+        result = BlackRunner().invoke(
+            black.main, ["--code", "print()", "--config", str(config)]
+        )
+        assert result.exit_code == 2
+        assert result.stderr_bytes is not None
+        assert (
+            b"Cannot use line-ranges in the pyproject.toml file." in result.stderr_bytes
+        )
+
 
 class TestCaching:
     def test_get_cache_dir(
diff --git a/tests/test_format.py b/tests/test_format.py
index 4e863c6c54b..6c2eca8c618 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -29,13 +29,19 @@ def check_file(subdir: str, filename: str, *, data: bool = True) -> None:
         args.mode,
         fast=args.fast,
         minimum_version=args.minimum_version,
+        lines=args.lines,
     )
     if args.minimum_version is not None:
         major, minor = args.minimum_version
         target_version = TargetVersion[f"PY{major}{minor}"]
         mode = replace(args.mode, target_versions={target_version})
         assert_format(
-            source, expected, mode, fast=args.fast, minimum_version=args.minimum_version
+            source,
+            expected,
+            mode,
+            fast=args.fast,
+            minimum_version=args.minimum_version,
+            lines=args.lines,
         )
 
 
@@ -45,6 +51,24 @@ def test_simple_format(filename: str) -> None:
     check_file("cases", filename)
 
 
+@pytest.mark.parametrize("filename", all_data_cases("line_ranges_formatted"))
+def test_line_ranges_line_by_line(filename: str) -> None:
+    args, source, expected = read_data_with_mode("line_ranges_formatted", filename)
+    assert (
+        source == expected
+    ), "Test cases in line_ranges_formatted must already be formatted."
+    line_count = len(source.splitlines())
+    for line in range(1, line_count + 1):
+        assert_format(
+            source,
+            expected,
+            args.mode,
+            fast=args.fast,
+            minimum_version=args.minimum_version,
+            lines=[(line, line)],
+        )
+
+
 # =============== #
 # Unusual cases
 # =============== #
diff --git a/tests/test_ranges.py b/tests/test_ranges.py
new file mode 100644
index 00000000000..d9fa9171a7f
--- /dev/null
+++ b/tests/test_ranges.py
@@ -0,0 +1,185 @@
+"""Test the black.ranges module."""
+
+from typing import List, Tuple
+
+import pytest
+
+from black.ranges import adjusted_lines
+
+
+@pytest.mark.parametrize(
+    "lines",
+    [[(1, 1)], [(1, 3)], [(1, 1), (3, 4)]],
+)
+def test_no_diff(lines: List[Tuple[int, int]]) -> None:
+    source = """\
+import re
+
+def func():
+pass
+"""
+    assert lines == adjusted_lines(lines, source, source)
+
+
+@pytest.mark.parametrize(
+    "lines",
+    [
+        [(1, 0)],
+        [(-8, 0)],
+        [(-8, 8)],
+        [(1, 100)],
+        [(2, 1)],
+        [(0, 8), (3, 1)],
+    ],
+)
+def test_invalid_lines(lines: List[Tuple[int, int]]) -> None:
+    original_source = """\
+import re
+def foo(arg):
+'''This is the foo function.
+
+This is foo function's
+docstring with more descriptive texts.
+'''
+
+def func(arg1,
+arg2, arg3):
+pass
+"""
+    modified_source = """\
+import re
+def foo(arg):
+'''This is the foo function.
+
+This is foo function's
+docstring with more descriptive texts.
+'''
+
+def func(arg1, arg2, arg3):
+pass
+"""
+    assert not adjusted_lines(lines, original_source, modified_source)
+
+
+@pytest.mark.parametrize(
+    "lines,adjusted",
+    [
+        (
+            [(1, 1)],
+            [(1, 1)],
+        ),
+        (
+            [(1, 2)],
+            [(1, 1)],
+        ),
+        (
+            [(1, 6)],
+            [(1, 2)],
+        ),
+        (
+            [(6, 6)],
+            [],
+        ),
+    ],
+)
+def test_removals(
+    lines: List[Tuple[int, int]], adjusted: List[Tuple[int, int]]
+) -> None:
+    original_source = """\
+1. first line
+2. second line
+3. third line
+4. fourth line
+5. fifth line
+6. sixth line
+"""
+    modified_source = """\
+2. second line
+5. fifth line
+"""
+    assert adjusted == adjusted_lines(lines, original_source, modified_source)
+
+
+@pytest.mark.parametrize(
+    "lines,adjusted",
+    [
+        (
+            [(1, 1)],
+            [(2, 2)],
+        ),
+        (
+            [(1, 2)],
+            [(2, 5)],
+        ),
+        (
+            [(2, 2)],
+            [(5, 5)],
+        ),
+    ],
+)
+def test_additions(
+    lines: List[Tuple[int, int]], adjusted: List[Tuple[int, int]]
+) -> None:
+    original_source = """\
+1. first line
+2. second line
+"""
+    modified_source = """\
+this is added
+1. first line
+this is added
+this is added
+2. second line
+this is added
+"""
+    assert adjusted == adjusted_lines(lines, original_source, modified_source)
+
+
+@pytest.mark.parametrize(
+    "lines,adjusted",
+    [
+        (
+            [(1, 11)],
+            [(1, 10)],
+        ),
+        (
+            [(1, 12)],
+            [(1, 11)],
+        ),
+        (
+            [(10, 10)],
+            [(9, 9)],
+        ),
+        ([(1, 1), (9, 10)], [(1, 1), (9, 9)]),
+        ([(9, 10), (1, 1)], [(1, 1), (9, 9)]),
+    ],
+)
+def test_diffs(lines: List[Tuple[int, int]], adjusted: List[Tuple[int, int]]) -> None:
+    original_source = """\
+ 1. import re
+ 2. def foo(arg):
+ 3.   '''This is the foo function.
+ 4.
+ 5.   This is foo function's
+ 6.   docstring with more descriptive texts.
+ 7.   '''
+ 8.
+ 9. def func(arg1,
+10.   arg2, arg3):
+11.   pass
+12. # last line
+"""
+    modified_source = """\
+ 1. import re  # changed
+ 2. def foo(arg):
+ 3.   '''This is the foo function.
+ 4.
+ 5.   This is foo function's
+ 6.   docstring with more descriptive texts.
+ 7.   '''
+ 8.
+ 9. def func(arg1, arg2, arg3):
+11.   pass
+12. # last line changed
+"""
+    assert adjusted == adjusted_lines(lines, original_source, modified_source)
diff --git a/tests/util.py b/tests/util.py
index a31ae0992c2..c8699d335ab 100644
--- a/tests/util.py
+++ b/tests/util.py
@@ -8,13 +8,14 @@
 from dataclasses import dataclass, field, replace
 from functools import partial
 from pathlib import Path
-from typing import Any, Iterator, List, Optional, Tuple
+from typing import Any, Collection, Iterator, List, Optional, Tuple
 
 import black
 from black.const import DEFAULT_LINE_LENGTH
 from black.debug import DebugVisitor
 from black.mode import TargetVersion
 from black.output import diff, err, out
+from black.ranges import parse_line_ranges
 
 from . import conftest
 
@@ -44,6 +45,7 @@ class TestCaseArgs:
     mode: black.Mode = field(default_factory=black.Mode)
     fast: bool = False
     minimum_version: Optional[Tuple[int, int]] = None
+    lines: Collection[Tuple[int, int]] = ()
 
 
 def _assert_format_equal(expected: str, actual: str) -> None:
@@ -93,6 +95,7 @@ def assert_format(
     *,
     fast: bool = False,
     minimum_version: Optional[Tuple[int, int]] = None,
+    lines: Collection[Tuple[int, int]] = (),
 ) -> None:
     """Convenience function to check that Black formats as expected.
 
@@ -101,7 +104,7 @@ def assert_format(
     separate from TargetVerson Mode configuration.
     """
     _assert_format_inner(
-        source, expected, mode, fast=fast, minimum_version=minimum_version
+        source, expected, mode, fast=fast, minimum_version=minimum_version, lines=lines
     )
 
     # For both preview and non-preview tests, ensure that Black doesn't crash on
@@ -113,6 +116,7 @@ def assert_format(
             replace(mode, preview=not mode.preview),
             fast=fast,
             minimum_version=minimum_version,
+            lines=lines,
         )
     except Exception as e:
         text = "non-preview" if mode.preview else "preview"
@@ -129,6 +133,7 @@ def assert_format(
             replace(mode, preview=False, line_length=1),
             fast=fast,
             minimum_version=minimum_version,
+            lines=lines,
         )
     except Exception as e:
         raise FormatFailure(
@@ -143,8 +148,9 @@ def _assert_format_inner(
     *,
     fast: bool = False,
     minimum_version: Optional[Tuple[int, int]] = None,
+    lines: Collection[Tuple[int, int]] = (),
 ) -> None:
-    actual = black.format_str(source, mode=mode)
+    actual = black.format_str(source, mode=mode, lines=lines)
     if expected is not None:
         _assert_format_equal(expected, actual)
     # It's not useful to run safety checks if we're expecting no changes anyway. The
@@ -156,7 +162,7 @@ def _assert_format_inner(
         # when checking modern code on older versions.
         if minimum_version is None or sys.version_info >= minimum_version:
             black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, mode=mode)
+        black.assert_stable(source, actual, mode=mode, lines=lines)
 
 
 def dump_to_stderr(*output: str) -> str:
@@ -239,6 +245,7 @@ def get_flags_parser() -> argparse.ArgumentParser:
             " version works correctly."
         ),
     )
+    parser.add_argument("--line-ranges", action="append")
     return parser
 
 
@@ -254,7 +261,13 @@ def parse_mode(flags_line: str) -> TestCaseArgs:
         magic_trailing_comma=not args.skip_magic_trailing_comma,
         preview=args.preview,
     )
-    return TestCaseArgs(mode=mode, fast=args.fast, minimum_version=args.minimum_version)
+    if args.line_ranges:
+        lines = parse_line_ranges(args.line_ranges)
+    else:
+        lines = []
+    return TestCaseArgs(
+        mode=mode, fast=args.fast, minimum_version=args.minimum_version, lines=lines
+    )
 
 
 def read_data_from_file(file_name: Path) -> Tuple[TestCaseArgs, str, str]:
@@ -267,6 +280,12 @@ def read_data_from_file(file_name: Path) -> Tuple[TestCaseArgs, str, str]:
     for line in lines:
         if not _input and line.startswith("# flags: "):
             mode = parse_mode(line[len("# flags: ") :])
+            if mode.lines:
+                # Retain the `# flags: ` line when using --line-ranges=. This requires
+                # the `# output` section to also include this line, but retaining the
+                # line is important to make the line ranges match what you see in the
+                # test file.
+                result.append(line)
             continue
         line = line.replace(EMPTY_LINE, "")
         if line.rstrip() == "# output":

From 50ed6221d97b265025abaa66116a7b185f2df5e2 Mon Sep 17 00:00:00 2001
From: rdrll <13176405+rdrll@users.noreply.github.com>
Date: Tue, 7 Nov 2023 06:31:58 -0800
Subject: [PATCH 0924/1034] Fix long case blocks not split into multiple lines
 (#4024)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 CHANGES.md                                    |  2 +
 src/black/linegen.py                          | 24 +++++++++++-
 src/black/mode.py                             |  1 +
 tests/data/cases/pattern_matching_extras.py   | 22 +----------
 .../cases/preview_pattern_matching_long.py    | 34 ++++++++++++++++
 ...preview_pattern_matching_trailing_comma.py | 39 +++++++++++++++++++
 6 files changed, 101 insertions(+), 21 deletions(-)
 create mode 100644 tests/data/cases/preview_pattern_matching_long.py
 create mode 100644 tests/data/cases/preview_pattern_matching_trailing_comma.py

diff --git a/CHANGES.md b/CHANGES.md
index 780a00247ce..c8ba83b5ae9 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -25,6 +25,8 @@
   indented less (#3964)
 - Multiline list and dict unpacking as the sole argument to a function is now also
   indented less (#3992)
+- Fix a bug where long `case` blocks were not split into multiple lines. Also enable
+  general trailing comma rules on `case` blocks (#4024)
 - Keep requiring two empty lines between module-level docstring and first function or
   class definition. (#4028)
 
diff --git a/src/black/linegen.py b/src/black/linegen.py
index b13b95d9b31..30cfff3e846 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -1229,7 +1229,7 @@ def normalize_prefix(leaf: Leaf, *, inside_brackets: bool) -> None:
     leaf.prefix = ""
 
 
-def normalize_invisible_parens(
+def normalize_invisible_parens(  # noqa: C901
     node: Node, parens_after: Set[str], *, mode: Mode, features: Collection[Feature]
 ) -> None:
     """Make existing optional parentheses invisible or create new ones.
@@ -1260,6 +1260,17 @@ def normalize_invisible_parens(
                 child, parens_after=parens_after, mode=mode, features=features
             )
 
+        # Fixes a bug where invisible parens are not properly wrapped around
+        # case blocks.
+        if (
+            isinstance(child, Node)
+            and child.type == syms.case_block
+            and Preview.long_case_block_line_splitting in mode
+        ):
+            normalize_invisible_parens(
+                child, parens_after={"case"}, mode=mode, features=features
+            )
+
         # Add parentheses around long tuple unpacking in assignments.
         if (
             index == 0
@@ -1305,6 +1316,17 @@ def normalize_invisible_parens(
                 # invisible parentheses to work more precisely.
                 continue
 
+            elif (
+                isinstance(child, Leaf)
+                and child.next_sibling is not None
+                and child.next_sibling.type == token.COLON
+                and child.value == "case"
+                and Preview.long_case_block_line_splitting in mode
+            ):
+                # A special patch for "case case:" scenario, the second occurrence
+                # of case will be not parsed as a Python keyword.
+                break
+
             elif not (isinstance(child, Leaf) and is_multiline_string(child)):
                 wrap_in_parentheses(node, child, visible=False)
 
diff --git a/src/black/mode.py b/src/black/mode.py
index 4e4effffb86..1aa5cbecc86 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -193,6 +193,7 @@ class Preview(Enum):
     hug_parens_with_braces_and_square_brackets = auto()
     allow_empty_first_line_before_new_block_or_comment = auto()
     single_line_format_skip_with_multiple_comments = auto()
+    long_case_block_line_splitting = auto()
 
 
 class Deprecated(UserWarning):
diff --git a/tests/data/cases/pattern_matching_extras.py b/tests/data/cases/pattern_matching_extras.py
index 1e1481d7bbe..1aef8f16b5a 100644
--- a/tests/data/cases/pattern_matching_extras.py
+++ b/tests/data/cases/pattern_matching_extras.py
@@ -30,22 +30,6 @@ def func(match: case, case: match) -> case:
             ...
 
 
-match maybe, multiple:
-    case perhaps, 5:
-        pass
-    case perhaps, 6,:
-        pass
-
-
-match more := (than, one), indeed,:
-    case _, (5, 6):
-        pass
-    case [[5], (6)], [7],:
-        pass
-    case _:
-        pass
-
-
 match a, *b, c:
     case [*_]:
         assert "seq" == _
@@ -67,12 +51,12 @@ def func(match: case, case: match) -> case:
         ),
     ):
         pass
-
     case [a as match]:
         pass
-
     case case:
         pass
+    case something:
+        pass
 
 
 match match:
@@ -98,10 +82,8 @@ def func(match: case, case: match) -> case:
 match something:
     case 1 as a:
         pass
-
     case 2 as b, 3 as c:
         pass
-
     case 4 as d, (5 as e), (6 | 7 as g), *h:
         pass
 
diff --git a/tests/data/cases/preview_pattern_matching_long.py b/tests/data/cases/preview_pattern_matching_long.py
new file mode 100644
index 00000000000..df849fdc4f2
--- /dev/null
+++ b/tests/data/cases/preview_pattern_matching_long.py
@@ -0,0 +1,34 @@
+# flags: --preview --minimum-version=3.10
+match x:
+    case "abcd" | "abcd" | "abcd" :
+        pass
+    case "abcd" | "abcd" | "abcd" | "abcd" | "abcd" | "abcd" | "abcd" | "abcd" | "abcd" | "abcd" | "abcd" | "abcd" | "abcd" | "abcd" | "abcd":
+        pass
+    case xxxxxxxxxxxxxxxxxxxxxxx:
+        pass
+
+# output
+
+match x:
+    case "abcd" | "abcd" | "abcd":
+        pass
+    case (
+        "abcd"
+        | "abcd"
+        | "abcd"
+        | "abcd"
+        | "abcd"
+        | "abcd"
+        | "abcd"
+        | "abcd"
+        | "abcd"
+        | "abcd"
+        | "abcd"
+        | "abcd"
+        | "abcd"
+        | "abcd"
+        | "abcd"
+    ):
+        pass
+    case xxxxxxxxxxxxxxxxxxxxxxx:
+        pass
diff --git a/tests/data/cases/preview_pattern_matching_trailing_comma.py b/tests/data/cases/preview_pattern_matching_trailing_comma.py
new file mode 100644
index 00000000000..e6c0d88bb80
--- /dev/null
+++ b/tests/data/cases/preview_pattern_matching_trailing_comma.py
@@ -0,0 +1,39 @@
+# flags: --preview --minimum-version=3.10
+match maybe, multiple:
+    case perhaps, 5:
+        pass
+    case perhaps, 6,:
+        pass
+
+
+match more := (than, one), indeed,:
+    case _, (5, 6):
+        pass
+    case [[5], (6)], [7],:
+        pass
+    case _:
+        pass
+
+
+# output
+
+match maybe, multiple:
+    case perhaps, 5:
+        pass
+    case (
+        perhaps,
+        6,
+    ):
+        pass
+
+
+match more := (than, one), indeed,:
+    case _, (5, 6):
+        pass
+    case (
+        [[5], (6)],
+        [7],
+    ):
+        pass
+    case _:
+        pass
\ No newline at end of file

From 66008fda5dc07f5626e5f5d0dcefc476a9c12ab8 Mon Sep 17 00:00:00 2001
From: Henri Holopainen <henri.i.holopainen@gmail.com>
Date: Tue, 7 Nov 2023 21:29:24 +0200
Subject: [PATCH 0925/1034] [563] Fix standalone comments inside complex blocks
 crashing Black (#4016)

Bracket depth is not an accurate indicator of standalone comment position inside more complex blocks because bracket depth can be virtual (in loops' and lambdas' parameter blocks) or from optional parens. Here we try to stop cumulating lines upon standalone comments in complex blocks, and try to make standalone comment processing more simple. The fundamental idea is, that if we have a standalone comment, it needs to go on its own line, so we always have to split.

This is not perfect, but at least a first step.
---
 CHANGES.md                                    |   1 +
 src/black/brackets.py                         |   7 ++
 src/black/linegen.py                          |   4 +-
 src/black/lines.py                            |  27 ++++-
 tests/data/cases/comments_in_blocks.py        | 111 ++++++++++++++++++
 ..._parens_with_braces_and_square_brackets.py |  20 ++++
 6 files changed, 163 insertions(+), 7 deletions(-)
 create mode 100644 tests/data/cases/comments_in_blocks.py

diff --git a/CHANGES.md b/CHANGES.md
index c8ba83b5ae9..d30622b7786 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -13,6 +13,7 @@
 
 - Fix crash on formatting bytes strings that look like docstrings (#4003)
 - Fix crash when whitespace followed a backslash before newline in a docstring (#4008)
+- Fix standalone comments inside complex blocks crashing Black (#4016)
 
 - Fix crash on formatting code like `await (a ** b)` (#3994)
 
diff --git a/src/black/brackets.py b/src/black/brackets.py
index 85dac6edd1e..3020cc0d390 100644
--- a/src/black/brackets.py
+++ b/src/black/brackets.py
@@ -127,6 +127,13 @@ def mark(self, leaf: Leaf) -> None:
         self.maybe_increment_lambda_arguments(leaf)
         self.maybe_increment_for_loop_variable(leaf)
 
+    def any_open_for_or_lambda(self) -> bool:
+        """Return True if there is an open for or lambda expression on the line.
+
+        See maybe_increment_for_loop_variable and maybe_increment_lambda_arguments
+        for details."""
+        return bool(self._for_loop_depths or self._lambda_argument_depths)
+
     def any_open_brackets(self) -> bool:
         """Return True if there is an yet unmatched open bracket on the line."""
         return bool(self.bracket_match)
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 30cfff3e846..e2c961d7a01 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -861,8 +861,6 @@ def _maybe_split_omitting_optional_parens(
         # it's not an import (optional parens are the only thing we can split on
         # in this case; attempting a split without them is a waste of time)
         and not line.is_import
-        # there are no standalone comments in the body
-        and not rhs.body.contains_standalone_comments(0)
         # and we can actually remove the parens
         and can_omit_invisible_parens(rhs, mode.line_length)
     ):
@@ -1181,7 +1179,7 @@ def standalone_comment_split(
     line: Line, features: Collection[Feature], mode: Mode
 ) -> Iterator[Line]:
     """Split standalone comments from the rest of the line."""
-    if not line.contains_standalone_comments(0):
+    if not line.contains_standalone_comments():
         raise CannotSplit("Line does not have any standalone comments")
 
     current_line = Line(
diff --git a/src/black/lines.py b/src/black/lines.py
index 23c1a93d3d4..f0cf25ba3e7 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -1,6 +1,5 @@
 import itertools
 import math
-import sys
 from dataclasses import dataclass, field
 from typing import (
     Callable,
@@ -103,7 +102,10 @@ def append_safe(self, leaf: Leaf, preformatted: bool = False) -> None:
         Raises ValueError when any `leaf` is appended after a standalone comment
         or when a standalone comment is not the first leaf on the line.
         """
-        if self.bracket_tracker.depth == 0:
+        if (
+            self.bracket_tracker.depth == 0
+            or self.bracket_tracker.any_open_for_or_lambda()
+        ):
             if self.is_comment:
                 raise ValueError("cannot append to standalone comments")
 
@@ -233,10 +235,10 @@ def is_fmt_pass_converted(
             leaf.fmt_pass_converted_first_leaf
         )
 
-    def contains_standalone_comments(self, depth_limit: int = sys.maxsize) -> bool:
+    def contains_standalone_comments(self) -> bool:
         """If so, needs to be split before emitting."""
         for leaf in self.leaves:
-            if leaf.type == STANDALONE_COMMENT and leaf.bracket_depth <= depth_limit:
+            if leaf.type == STANDALONE_COMMENT:
                 return True
 
         return False
@@ -982,6 +984,23 @@ def can_omit_invisible_parens(
     are too long.
     """
     line = rhs.body
+
+    # We need optional parens in order to split standalone comments to their own lines
+    # if there are no nested parens around the standalone comments
+    closing_bracket: Optional[Leaf] = None
+    for leaf in reversed(line.leaves):
+        if closing_bracket and leaf is closing_bracket.opening_bracket:
+            closing_bracket = None
+        if leaf.type == STANDALONE_COMMENT and not closing_bracket:
+            return False
+        if (
+            not closing_bracket
+            and leaf.type in CLOSING_BRACKETS
+            and leaf.opening_bracket in line.leaves
+            and leaf.value
+        ):
+            closing_bracket = leaf
+
     bt = line.bracket_tracker
     if not bt.delimiters:
         # Without delimiters the optional parentheses are useless.
diff --git a/tests/data/cases/comments_in_blocks.py b/tests/data/cases/comments_in_blocks.py
new file mode 100644
index 00000000000..1221139b6d8
--- /dev/null
+++ b/tests/data/cases/comments_in_blocks.py
@@ -0,0 +1,111 @@
+# Test cases from:
+# - https://github.com/psf/black/issues/1798
+# - https://github.com/psf/black/issues/1499
+# - https://github.com/psf/black/issues/1211
+# - https://github.com/psf/black/issues/563
+
+(
+    lambda
+    # a comment
+    : None
+)
+
+(
+    lambda:
+    # b comment
+    None
+)
+
+(
+    lambda
+    # a comment
+    :
+    # b comment
+    None
+)
+
+[
+    x
+    # Let's do this
+    for
+    # OK?
+    x
+    # Some comment
+    # And another
+    in
+    # One more
+    y
+]
+
+return [
+    (offers[offer_index], 1.0)
+    for offer_index, _
+    # avoid returning any offers that don't match the grammar so
+    # that the return values here are consistent with what would be
+    # returned in AcceptValidHeader
+    in self._parse_and_normalize_offers(offers)
+]
+
+from foo import (
+    bar,
+    # qux
+)
+
+
+def convert(collection):
+    # replace all variables by integers
+    replacement_dict = {
+        variable: f"{index}"
+        for index, variable
+        # 0 is reserved as line terminator
+        in enumerate(collection.variables(), start=1)
+    }
+
+
+{
+    i: i
+    for i
+    # a comment
+    in range(5)
+}
+
+
+def get_subtree_proof_nodes(
+    chunk_index_groups: Sequence[Tuple[int, ...], ...],
+) -> Tuple[int, ...]:
+    subtree_node_paths = (
+        # We take a candidate element from each group and shift it to
+        # remove the bits that are not common to other group members, then
+        # we convert it to a tree path that all elements from this group
+        # have in common.
+        chunk_index
+        for chunk_index, bits_to_truncate
+        # Each group will contain an even "power-of-two" number of# elements.
+        # This tells us how many tailing bits each element has# which need to
+        # be truncated to get the group's common prefix.
+        in ((group[0], (len(group) - 1).bit_length()) for group in chunk_index_groups)
+    )
+    return subtree_node_paths
+
+
+if (
+    # comment1
+    a
+    # comment2
+    or (
+        # comment3
+        (
+            # comment4
+            b
+        )
+        # comment5
+        and
+        # comment6
+        c
+        or (
+            # comment7
+            d
+        )
+    )
+):
+    print("Foo")
diff --git a/tests/data/cases/preview_hug_parens_with_braces_and_square_brackets.py b/tests/data/cases/preview_hug_parens_with_braces_and_square_brackets.py
index 51fe516add5..97b5b2e8dd1 100644
--- a/tests/data/cases/preview_hug_parens_with_braces_and_square_brackets.py
+++ b/tests/data/cases/preview_hug_parens_with_braces_and_square_brackets.py
@@ -152,6 +152,16 @@ def foo_square_brackets(request):
 
 foo(**{x: y for x, y in enumerate(["long long long long line","long long long long line"])})
 
+for foo in ["a", "b"]:
+    output.extend([
+        individual
+        for
+        # Foobar
+        container in xs_by_y[foo]
+        # Foobar
+        for individual in container["nested"]
+    ])
+
 # output
 def foo_brackets(request):
     return JsonResponse({
@@ -323,3 +333,13 @@ def foo_square_brackets(request):
 foo(**{
     x: y for x, y in enumerate(["long long long long line", "long long long long line"])
 })
+
+for foo in ["a", "b"]:
+    output.extend([
+        individual
+        for
+        # Foobar
+        container in xs_by_y[foo]
+        # Foobar
+        for individual in container["nested"]
+    ])

From 2e4fac9d87615e904a49e46a9cab2293e0b13126 Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Tue, 7 Nov 2023 11:31:44 -0800
Subject: [PATCH 0926/1034] Apply force exclude logic before symlink resolution
 (#4015)

---
 CHANGES.md            |  2 +-
 src/black/__init__.py | 24 ++++++++++++++----------
 tests/test_black.py   | 17 +++++++++++++++++
 3 files changed, 32 insertions(+), 11 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index d30622b7786..17882194aad 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -34,7 +34,7 @@
 ### Configuration
 
 - Add support for single-line format skip with other comments on the same line (#3959)
-
+- Consistently apply force exclusion logic before resolving symlinks (#4015)
 - Fix a bug in the matching of absolute path names in `--include` (#3976)
 
 ### Packaging
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 5aca3316df0..2455e8648fc 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -682,7 +682,19 @@ def get_sources(
             path = Path(s)
             is_stdin = False
 
+        # Compare the logic here to the logic in `gen_python_files`.
         if is_stdin or path.is_file():
+            root_relative_path = path.absolute().relative_to(root).as_posix()
+
+            root_relative_path = "/" + root_relative_path
+
+            # Hard-exclude any files that matches the `--force-exclude` regex.
+            if path_is_excluded(root_relative_path, force_exclude):
+                report.path_ignored(
+                    path, "matches the --force-exclude regular expression"
+                )
+                continue
+
             normalized_path: Optional[str] = normalize_path_maybe_ignore(
                 path, root, report
             )
@@ -690,16 +702,6 @@ def get_sources(
                 if verbose:
                     out(f'Skipping invalid source: "{normalized_path}"', fg="red")
                 continue
-            if verbose:
-                out(f'Found input source: "{normalized_path}"', fg="blue")
-
-            normalized_path = "/" + normalized_path
-            # Hard-exclude any files that matches the `--force-exclude` regex.
-            if path_is_excluded(normalized_path, force_exclude):
-                report.path_ignored(
-                    path, "matches the --force-exclude regular expression"
-                )
-                continue
 
             if is_stdin:
                 path = Path(f"{STDIN_PLACEHOLDER}{str(path)}")
@@ -709,6 +711,8 @@ def get_sources(
             ):
                 continue
 
+            if verbose:
+                out(f'Found input source: "{normalized_path}"', fg="blue")
             sources.add(path)
         elif path.is_dir():
             path = root / (path.resolve().relative_to(root))
diff --git a/tests/test_black.py b/tests/test_black.py
index c9819742425..899cbeb111d 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -2637,6 +2637,23 @@ def test_get_sources_with_stdin_filename_and_force_exclude(self) -> None:
             stdin_filename=stdin_filename,
         )
 
+    @patch("black.find_project_root", lambda *args: (THIS_DIR.resolve(), None))
+    def test_get_sources_with_stdin_filename_and_force_exclude_and_symlink(
+        self,
+    ) -> None:
+        # Force exclude should exclude a symlink based on the symlink, not its target
+        path = THIS_DIR / "data" / "include_exclude_tests"
+        stdin_filename = str(path / "symlink.py")
+        expected = [f"__BLACK_STDIN_FILENAME__{stdin_filename}"]
+        target = path / "b/exclude/a.py"
+        with patch("pathlib.Path.resolve", return_value=target):
+            assert_collected_sources(
+                src=["-"],
+                expected=expected,
+                force_exclude=r"exclude/a\.py",
+                stdin_filename=stdin_filename,
+            )
+
 
 class TestDeFactoAPI:
     """Test that certain symbols that are commonly used externally keep working.

From f4c7be5445c87d9af5eba3d12faea62d2635e3d8 Mon Sep 17 00:00:00 2001
From: Abdenour Madani <61651582+Ab2nour@users.noreply.github.com>
Date: Wed, 8 Nov 2023 00:40:10 +0100
Subject: [PATCH 0927/1034] docs: fix minor typo (#4030)

Replace "E950" with "B950"

From 1a7d9c2f58de1ffcbbe6d133f60f283601ba3f54 Mon Sep 17 00:00:00 2001
From: Henri Holopainen <henri.i.holopainen@gmail.com>
Date: Wed, 8 Nov 2023 06:19:32 +0200
Subject: [PATCH 0928/1034] Preserve visible quote types for f-string debug
 expressions (#4005)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 CHANGES.md                               |  2 +
 src/black/trans.py                       | 21 +++++--
 tests/data/cases/preview_long_strings.py | 80 ++++++++++++++++++++++++
 3 files changed, 98 insertions(+), 5 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 17882194aad..26e4db5848b 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -26,6 +26,8 @@
   indented less (#3964)
 - Multiline list and dict unpacking as the sole argument to a function is now also
   indented less (#3992)
+- In f-string debug expressions preserve quote types that are visible in the final
+  string (#4005)
 - Fix a bug where long `case` blocks were not split into multiple lines. Also enable
   general trailing comma rules on `case` blocks (#4024)
 - Keep requiring two empty lines between module-level docstring and first function or
diff --git a/src/black/trans.py b/src/black/trans.py
index a3f6467cc9e..ab3197fa6df 100644
--- a/src/black/trans.py
+++ b/src/black/trans.py
@@ -590,11 +590,22 @@ def make_naked(string: str, string_prefix: str) -> str:
             """
             assert_is_leaf_string(string)
             if "f" in string_prefix:
-                string = _toggle_fexpr_quotes(string, QUOTE)
-                # After quotes toggling, quotes in expressions won't be escaped
-                # because quotes can't be reused in f-strings. So we can simply
-                # let the escaping logic below run without knowing f-string
-                # expressions.
+                f_expressions = (
+                    string[span[0] + 1 : span[1] - 1]  # +-1 to get rid of curly braces
+                    for span in iter_fexpr_spans(string)
+                )
+                debug_expressions_contain_visible_quotes = any(
+                    re.search(r".*[\'\"].*(?<![!:=])={1}(?!=)(?![^\s:])", expression)
+                    for expression in f_expressions
+                )
+                if not debug_expressions_contain_visible_quotes:
+                    # We don't want to toggle visible quotes in debug f-strings, as
+                    # that would modify the AST
+                    string = _toggle_fexpr_quotes(string, QUOTE)
+                    # After quotes toggling, quotes in expressions won't be escaped
+                    # because quotes can't be reused in f-strings. So we can simply
+                    # let the escaping logic below run without knowing f-string
+                    # expressions.
 
             RE_EVEN_BACKSLASHES = r"(?:(?<!\\)(?:\\\\)*)"
             naked_string = string[len(string_prefix) + 1 : -1]
diff --git a/tests/data/cases/preview_long_strings.py b/tests/data/cases/preview_long_strings.py
index 5519f098774..19ac47a7032 100644
--- a/tests/data/cases/preview_long_strings.py
+++ b/tests/data/cases/preview_long_strings.py
@@ -305,6 +305,29 @@ def foo():
 # Test case of an outer string' parens enclose an inner string's parens.
 call(body=("%s %s" % ((",".join(items)), suffix)))
 
+log.info(f'Skipping: {desc["db_id"]=} {desc["ms_name"]} {money=} {dte=} {pos_share=} {desc["status"]=} {desc["exposure_max"]=}')
+
+log.info(f"Skipping: {desc['db_id']=} {desc['ms_name']} {money=} {dte=} {pos_share=} {desc['status']=} {desc['exposure_max']=}")
+
+log.info(f'Skipping: {desc["db_id"]} {foo("bar",x=123)} {"foo" != "bar"} {(x := "abc=")} {pos_share=} {desc["status"]} {desc["exposure_max"]}')
+
+log.info(f'Skipping: {desc["db_id"]} {desc["ms_name"]} {money=} {(x := "abc=")=} {pos_share=} {desc["status"]} {desc["exposure_max"]}')
+
+log.info(f'Skipping: {desc["db_id"]} {foo("bar",x=123)=} {money=} {dte=} {pos_share=} {desc["status"]} {desc["exposure_max"]}')
+
+log.info(f'Skipping: {foo("asdf")=} {desc["ms_name"]} {money=} {dte=} {pos_share=} {desc["status"]} {desc["exposure_max"]}')
+
+log.info(f'Skipping: {"a" == "b" == "c" == "d"} {desc["ms_name"]} {money=} {dte=} {pos_share=} {desc["status"]} {desc["exposure_max"]}')
+
+log.info(f'Skipping: {"a" == "b" == "c" == "d"=} {desc["ms_name"]} {money=} {dte=} {pos_share=} {desc["status"]} {desc["exposure_max"]}')
+
+log.info(f'Skipping: {  longer_longer_longer_longer_longer_longer_name   [ "db_id" ]      [ "another_key" ]   =  :  .3f }')
+
+log.info(f'''Skipping: {"a" == 'b'} {desc["ms_name"]} {money=} {dte=} {pos_share=} {desc["status"]} {desc["exposure_max"]}''')
+
+log.info(f'''Skipping: {'a' == "b"=} {desc["ms_name"]} {money=} {dte=} {pos_share=} {desc["status"]} {desc["exposure_max"]}''')
+
+log.info(f"""Skipping: {'a' == 'b'} {desc['ms_name']} {money=} {dte=} {pos_share=} {desc['status']} {desc['exposure_max']}""")
 
 # output
 
@@ -846,3 +869,60 @@ def foo():
 
 # Test case of an outer string' parens enclose an inner string's parens.
 call(body="%s %s" % (",".join(items), suffix))
+
+log.info(
+    "Skipping:"
+    f' {desc["db_id"]=} {desc["ms_name"]} {money=} {dte=} {pos_share=} {desc["status"]=} {desc["exposure_max"]=}'
+)
+
+log.info(
+    "Skipping:"
+    f" {desc['db_id']=} {desc['ms_name']} {money=} {dte=} {pos_share=} {desc['status']=} {desc['exposure_max']=}"
+)
+
+log.info(
+    "Skipping:"
+    f" {desc['db_id']} {foo('bar',x=123)} {'foo' != 'bar'} {(x := 'abc=')} {pos_share=} {desc['status']} {desc['exposure_max']}"
+)
+
+log.info(
+    "Skipping:"
+    f' {desc["db_id"]} {desc["ms_name"]} {money=} {(x := "abc=")=} {pos_share=} {desc["status"]} {desc["exposure_max"]}'
+)
+
+log.info(
+    "Skipping:"
+    f' {desc["db_id"]} {foo("bar",x=123)=} {money=} {dte=} {pos_share=} {desc["status"]} {desc["exposure_max"]}'
+)
+
+log.info(
+    "Skipping:"
+    f' {foo("asdf")=} {desc["ms_name"]} {money=} {dte=} {pos_share=} {desc["status"]} {desc["exposure_max"]}'
+)
+
+log.info(
+    "Skipping:"
+    f" {'a' == 'b' == 'c' == 'd'} {desc['ms_name']} {money=} {dte=} {pos_share=} {desc['status']} {desc['exposure_max']}"
+)
+
+log.info(
+    "Skipping:"
+    f' {"a" == "b" == "c" == "d"=} {desc["ms_name"]} {money=} {dte=} {pos_share=} {desc["status"]} {desc["exposure_max"]}'
+)
+
+log.info(
+    "Skipping:"
+    f' {  longer_longer_longer_longer_longer_longer_name   [ "db_id" ]      [ "another_key" ]   =  :  .3f }'
+)
+
+log.info(
+    f"""Skipping: {"a" == 'b'} {desc["ms_name"]} {money=} {dte=} {pos_share=} {desc["status"]} {desc["exposure_max"]}"""
+)
+
+log.info(
+    f"""Skipping: {'a' == "b"=} {desc["ms_name"]} {money=} {dte=} {pos_share=} {desc["status"]} {desc["exposure_max"]}"""
+)
+
+log.info(
+    f"""Skipping: {'a' == 'b'} {desc['ms_name']} {money=} {dte=} {pos_share=} {desc['status']} {desc['exposure_max']}"""
+)

From 72e7a2e43eef2aa0c83652bb6725eb004a2a69f3 Mon Sep 17 00:00:00 2001
From: Ran Benita <ran@unusedvar.com>
Date: Wed, 8 Nov 2023 06:21:33 +0200
Subject: [PATCH 0929/1034] Remove redundant condition from
 `has_magic_trailing_comma` (#4023)

The second `if` cannot be true at its execution point, because it is
already covered by the first `if`. The condition
`comma.parent.type == syms.subscriptlist` always holds if
`closing.parent.type == syms.trailer` holds, because `subscriptlist`
only appears inside `trailer` in the grammar:

```
trailer: '(' [arglist] ')' | '[' subscriptlist ']' | '.' NAME
subscriptlist: (subscript|star_expr) (',' (subscript|star_expr))* [',']
```
---
 src/black/lines.py | 21 +++------------------
 1 file changed, 3 insertions(+), 18 deletions(-)

diff --git a/src/black/lines.py b/src/black/lines.py
index f0cf25ba3e7..3ade0a5f4a5 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -353,9 +353,9 @@ def has_magic_trailing_comma(
 
         if closing.type == token.RSQB:
             if (
-                closing.parent
+                closing.parent is not None
                 and closing.parent.type == syms.trailer
-                and closing.opening_bracket
+                and closing.opening_bracket is not None
                 and is_one_sequence_between(
                     closing.opening_bracket,
                     closing,
@@ -365,22 +365,7 @@ def has_magic_trailing_comma(
             ):
                 return False
 
-            if not ensure_removable:
-                return True
-
-            comma = self.leaves[-1]
-            if comma.parent is None:
-                return False
-            return (
-                comma.parent.type != syms.subscriptlist
-                or closing.opening_bracket is None
-                or not is_one_sequence_between(
-                    closing.opening_bracket,
-                    closing,
-                    self.leaves,
-                    brackets=(token.LSQB, token.RSQB),
-                )
-            )
+            return True
 
         if self.is_import:
             return True

From 2a1c67e0b2f81df602ec1f6e7aeb030b9709dc7c Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Tue, 7 Nov 2023 20:44:46 -0800
Subject: [PATCH 0930/1034] Prepare release 23.11.0 (#4032)

---
 CHANGES.md                                  | 70 +++------------------
 docs/integrations/source_version_control.md |  4 +-
 docs/usage_and_configuration/the_basics.md  |  6 +-
 3 files changed, 14 insertions(+), 66 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 26e4db5848b..b565d510a71 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,78 +1,49 @@
 # Change Log
 
-## Unreleased
+## 23.11.0
 
 ### Highlights
 
-<!-- Include any especially major or disruptive changes here -->
-
 - Support formatting ranges of lines with the new `--line-ranges` command-line option
-  (#4020).
+  (#4020)
 
 ### Stable style
 
 - Fix crash on formatting bytes strings that look like docstrings (#4003)
 - Fix crash when whitespace followed a backslash before newline in a docstring (#4008)
 - Fix standalone comments inside complex blocks crashing Black (#4016)
-
 - Fix crash on formatting code like `await (a ** b)` (#3994)
-
 - No longer treat leading f-strings as docstrings. This matches Python's behaviour and
   fixes a crash (#4019)
 
 ### Preview style
 
-- Multiline dictionaries and lists that are the sole argument to a function are now
-  indented less (#3964)
-- Multiline list and dict unpacking as the sole argument to a function is now also
+- Multiline dicts and lists that are the sole argument to a function are now indented
+  less (#3964)
+- Multiline unpacked dicts and lists as the sole argument to a function are now also
   indented less (#3992)
-- In f-string debug expressions preserve quote types that are visible in the final
-  string (#4005)
+- In f-string debug expressions, quote types that are visible in the final string are
+  now preserved (#4005)
 - Fix a bug where long `case` blocks were not split into multiple lines. Also enable
   general trailing comma rules on `case` blocks (#4024)
 - Keep requiring two empty lines between module-level docstring and first function or
-  class definition. (#4028)
+  class definition (#4028)
+- Add support for single-line format skip with other comments on the same line (#3959)
 
 ### Configuration
 
-- Add support for single-line format skip with other comments on the same line (#3959)
 - Consistently apply force exclusion logic before resolving symlinks (#4015)
 - Fix a bug in the matching of absolute path names in `--include` (#3976)
 
-### Packaging
-
-<!-- Changes to how Black is packaged, such as dependency requirements -->
-
-### Parser
-
-<!-- Changes to the parser or to version autodetection -->
-
 ### Performance
 
-<!-- Changes that improve Black's performance. -->
-
 - Fix mypyc builds on arm64 on macOS (#4017)
 
-### Output
-
-<!-- Changes to Black's terminal output and error messages -->
-
-### _Blackd_
-
-<!-- Changes to blackd -->
-
 ### Integrations
 
-<!-- For example, Docker, GitHub Actions, pre-commit, editors -->
-
 - Black's pre-commit integration will now run only on git hooks appropriate for a code
   formatter (#3940)
 
-### Documentation
-
-<!-- Major changes to documentation and policies. Small docs changes
-     don't need a changelog entry. -->
-
 ## 23.10.1
 
 ### Highlights
@@ -327,8 +298,6 @@ versions separately.
 
 ### Stable style
 
-<!-- Changes that affect Black's stable style -->
-
 - Introduce the 2023 stable style, which incorporates most aspects of last year's
   preview style (#3418). Specific changes:
   - Enforce empty lines before classes and functions with sticky leading comments
@@ -362,8 +331,6 @@ versions separately.
 
 ### Preview style
 
-<!-- Changes that affect Black's preview style -->
-
 - Format hex codes in unicode escape sequences in string literals (#2916)
 - Add parentheses around `if`-`else` expressions (#2278)
 - Improve performance on large expressions that contain many strings (#3467)
@@ -394,15 +361,11 @@ versions separately.
 
 ### Configuration
 
-<!-- Changes to how Black can be configured -->
-
 - Black now tries to infer its `--target-version` from the project metadata specified in
   `pyproject.toml` (#3219)
 
 ### Packaging
 
-<!-- Changes to how Black is packaged, such as dependency requirements -->
-
 - Upgrade mypyc from `0.971` to `0.991` so mypycified _Black_ can be built on armv7
   (#3380)
   - This also fixes some crashes while using compiled Black with a debug build of
@@ -415,8 +378,6 @@ versions separately.
 
 ### Output
 
-<!-- Changes to Black's terminal output and error messages -->
-
 - Calling `black --help` multiple times will return the same help contents each time
   (#3516)
 - Verbose logging now shows the values of `pyproject.toml` configuration variables
@@ -426,25 +387,18 @@ versions separately.
 
 ### Integrations
 
-<!-- For example, Docker, GitHub Actions, pre-commit, editors -->
-
 - Move 3.11 CI to normal flow now that all dependencies support 3.11 (#3446)
 - Docker: Add new `latest_prerelease` tag automation to follow latest black alpha
   release on docker images (#3465)
 
 ### Documentation
 
-<!-- Major changes to documentation and policies. Small docs changes
-     don't need a changelog entry. -->
-
 - Expand `vim-plug` installation instructions to offer more explicit options (#3468)
 
 ## 22.12.0
 
 ### Preview style
 
-<!-- Changes that affect Black's preview style -->
-
 - Enforce empty lines before classes and functions with sticky leading comments (#3302)
 - Reformat empty and whitespace-only files as either an empty file (if no newline is
   present) or as a single newline character (if a newline is present) (#3348)
@@ -457,8 +411,6 @@ versions separately.
 
 ### Configuration
 
-<!-- Changes to how Black can be configured -->
-
 - Fix incorrectly applied `.gitignore` rules by considering the `.gitignore` location
   and the relative path to the target file (#3338)
 - Fix incorrectly ignoring `.gitignore` presence when more than one source directory is
@@ -466,16 +418,12 @@ versions separately.
 
 ### Parser
 
-<!-- Changes to the parser or to version autodetection -->
-
 - Parsing support has been added for walruses inside generator expression that are
   passed as function args (for example,
   `any(match := my_re.match(text) for text in texts)`) (#3327).
 
 ### Integrations
 
-<!-- For example, Docker, GitHub Actions, pre-commit, editors -->
-
 - Vim plugin: Optionally allow using the system installation of Black via
   `let g:black_use_virtualenv = 0`(#3309)
 
diff --git a/docs/integrations/source_version_control.md b/docs/integrations/source_version_control.md
index 597a6b993c7..3c7ef89918f 100644
--- a/docs/integrations/source_version_control.md
+++ b/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.1
+    rev: 23.11.0
     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.1
+    rev: 23.11.0
     hooks:
       - id: black-jupyter
         # It is recommended to specify the latest version of Python
diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index dbd8c7ba434..6e7ee584cf9 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -211,8 +211,8 @@ configuration file for consistent results across environments.
 
 ```console
 $ black --version
-black, 23.10.1 (compiled: yes)
-$ black --required-version 23.10.1 -c "format = 'this'"
+black, 23.11.0 (compiled: yes)
+$ black --required-version 23.11.0 -c "format = 'this'"
 format = "this"
 $ black --required-version 31.5b2 -c "still = 'beta?!'"
 Oh no! 💥 💔 💥 The required version does not match the running version!
@@ -303,7 +303,7 @@ You can check the version of _Black_ you have installed using the `--version` fl
 
 ```console
 $ black --version
-black, 23.10.1
+black, 23.11.0
 ```
 
 #### `--config`

From 58f31a70efe6509ce8213afac998bc5d5bb7e34d Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Tue, 7 Nov 2023 22:10:35 -0800
Subject: [PATCH 0931/1034] Add new release template

---
 CHANGES.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/CHANGES.md b/CHANGES.md
index b565d510a71..9446927b8d1 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,5 +1,52 @@
 # Change Log
 
+## Unreleased
+
+### Highlights
+
+<!-- Include any especially major or disruptive changes here -->
+
+### Stable style
+
+<!-- Changes that affect Black's stable style -->
+
+### Preview style
+
+<!-- Changes that affect Black's preview style -->
+
+### Configuration
+
+<!-- Changes to how Black can be configured -->
+
+### Packaging
+
+<!-- Changes to how Black is packaged, such as dependency requirements -->
+
+### Parser
+
+<!-- Changes to the parser or to version autodetection -->
+
+### Performance
+
+<!-- Changes that improve Black's performance. -->
+
+### Output
+
+<!-- Changes to Black's terminal output and error messages -->
+
+### _Blackd_
+
+<!-- Changes to blackd -->
+
+### Integrations
+
+<!-- For example, Docker, GitHub Actions, pre-commit, editors -->
+
+### Documentation
+
+<!-- Major changes to documentation and policies. Small docs changes
+     don't need a changelog entry. -->
+
 ## 23.11.0
 
 ### Highlights

From 1b6b0bfcac37428f7f2eb6c97fd0a25628324db7 Mon Sep 17 00:00:00 2001
From: Alex Waygood <Alex.Waygood@Gmail.com>
Date: Fri, 17 Nov 2023 15:57:00 +0000
Subject: [PATCH 0932/1034] Improve annotations for `black.concurrency.cancel`
 (#4047)

---
 src/black/concurrency.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/black/concurrency.py b/src/black/concurrency.py
index 55c96b66c86..ff0a8f5fd32 100644
--- a/src/black/concurrency.py
+++ b/src/black/concurrency.py
@@ -38,7 +38,7 @@ def maybe_install_uvloop() -> None:
         pass
 
 
-def cancel(tasks: Iterable["asyncio.Task[Any]"]) -> None:
+def cancel(tasks: Iterable["asyncio.Future[Any]"]) -> None:
     """asyncio signal handler that cancels all `tasks` and reports to stderr."""
     err("Aborted!")
     for task in tasks:

From 5773d5cd2b532da185808f974a5875ca09064e28 Mon Sep 17 00:00:00 2001
From: cobalt <61329810+RedGuy12@users.noreply.github.com>
Date: Fri, 17 Nov 2023 15:39:44 -0600
Subject: [PATCH 0933/1034] Document target version inference (#4048)

---
 docs/usage_and_configuration/the_basics.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index 6e7ee584cf9..546fdc474e8 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -67,6 +67,10 @@ In a [configuration file](#configuration-via-a-file), you can write:
 target-version = ["py38", "py39", "py310", "py311"]
 ```
 
+By default, Black will infer target versions from the project metadata in
+`pyproject.toml`, specifically the `[project.requires-python]` field. If this does not
+yield conclusive results, Black will use per-file auto-detection.
+
 _Black_ uses this option to decide what grammar to use to parse your code. In addition,
 it may use it to decide what style to use. For example, support for a trailing comma
 after `*args` in a function call was added in Python 3.5, so _Black_ will add this comma

From 85b1c71a3445f32860d7b139ae4de4824f6ae102 Mon Sep 17 00:00:00 2001
From: Alex Waygood <Alex.Waygood@Gmail.com>
Date: Sat, 18 Nov 2023 19:15:07 +0000
Subject: [PATCH 0934/1034] Block aiohttp==3.9.0 from being installed in CI on
 Windows/pypy (#4051)

---
 pyproject.toml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/pyproject.toml b/pyproject.toml
index c0302d2302a..bea8e77ba04 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -76,7 +76,8 @@ dynamic = ["readme", "version"]
 colorama = ["colorama>=0.4.3"]
 uvloop = ["uvloop>=0.15.2"]
 d = [
-  "aiohttp>=3.7.4",
+  "aiohttp>=3.7.4; sys_platform != 'win32' or implementation_name != 'pypy'",
+  "aiohttp>=3.7.4, !=3.9.0; sys_platform == 'win32' and implementation_name == 'pypy'",
 ]
 jupyter = [
   "ipython>=7.8.0",

From c4cd200a063a4d5546b547809aa1e607f03c3f59 Mon Sep 17 00:00:00 2001
From: Alex Waygood <Alex.Waygood@Gmail.com>
Date: Sat, 18 Nov 2023 19:41:46 +0000
Subject: [PATCH 0935/1034] Make flake8 pass when run with Python 3.12 (#4050)

---
 src/black/parsing.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/black/parsing.py b/src/black/parsing.py
index ea282d1805c..178a7ef10e2 100644
--- a/src/black/parsing.py
+++ b/src/black/parsing.py
@@ -175,7 +175,7 @@ def stringify_ast(node: ast.AST, depth: int = 0) -> Iterator[str]:
         except AttributeError:
             continue
 
-        yield f"{'  ' * (depth+1)}{field}="
+        yield f"{'  ' * (depth + 1)}{field}="
 
         if isinstance(value, list):
             for item in value:
@@ -211,6 +211,6 @@ def stringify_ast(node: ast.AST, depth: int = 0) -> Iterator[str]:
                 normalized = value.rstrip()
             else:
                 normalized = value
-            yield f"{'  ' * (depth+2)}{normalized!r},  # {value.__class__.__name__}"
+            yield f"{'  ' * (depth + 2)}{normalized!r},  # {value.__class__.__name__}"
 
     yield f"{'  ' * depth})  # /{node.__class__.__name__}"

From d93a942a79762484a0f72c6fa271b45ec377009b Mon Sep 17 00:00:00 2001
From: Alex Waygood <Alex.Waygood@Gmail.com>
Date: Sat, 18 Nov 2023 19:42:36 +0000
Subject: [PATCH 0936/1034] Upgrade mypy to 1.6.1 (#4049)

---
 .pre-commit-config.yaml                    |  2 +-
 CHANGES.md                                 |  2 +-
 pyproject.toml                             |  4 ++--
 scripts/check_pre_commit_rev_in_example.py |  2 +-
 scripts/check_version_in_basics_example.py |  2 +-
 scripts/diff_shades_gha_helper.py          |  2 +-
 scripts/fuzz.py                            |  2 +-
 scripts/make_width_table.py                |  2 +-
 src/blackd/__init__.py                     |  4 +---
 tests/optional.py                          | 10 +++++++++-
 10 files changed, 19 insertions(+), 13 deletions(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 623e661ac07..c153746b621 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -39,7 +39,7 @@ repos:
         exclude: ^src/blib2to3/
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.5.1
+    rev: v1.6.1
     hooks:
       - id: mypy
         exclude: ^docs/conf.py
diff --git a/CHANGES.md b/CHANGES.md
index 9446927b8d1..13b6c7bdb21 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -20,7 +20,7 @@
 
 ### Packaging
 
-<!-- Changes to how Black is packaged, such as dependency requirements -->
+- Upgrade to mypy 1.6.1 (#4049)
 
 ### Parser
 
diff --git a/pyproject.toml b/pyproject.toml
index bea8e77ba04..f8f5155e898 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -121,7 +121,7 @@ macos-max-compat = true
 enable-by-default = false
 dependencies = [
   "hatch-mypyc>=0.16.0",
-  "mypy==1.5.1",
+  "mypy==1.6.1",
   "click==8.1.3",  # avoid https://github.com/pallets/click/issues/2558
 ]
 require-runtime-dependencies = true
@@ -187,7 +187,7 @@ CC = "clang"
 build-frontend = { name = "build", args = ["--no-isolation"] }
 # Unfortunately, hatch doesn't respect MACOSX_DEPLOYMENT_TARGET
 before-build = [
-    "python -m pip install 'hatchling==1.18.0' hatch-vcs hatch-fancy-pypi-readme 'hatch-mypyc>=0.16.0' 'mypy==1.5.1' 'click==8.1.3'",
+    "python -m pip install 'hatchling==1.18.0' hatch-vcs hatch-fancy-pypi-readme 'hatch-mypyc>=0.16.0' 'mypy==1.6.1' 'click==8.1.3'",
     """sed -i '' -e "600,700s/'10_16'/os.environ['MACOSX_DEPLOYMENT_TARGET'].replace('.', '_')/" $(python -c 'import hatchling.builders.wheel as h; print(h.__file__)') """,
 ]
 
diff --git a/scripts/check_pre_commit_rev_in_example.py b/scripts/check_pre_commit_rev_in_example.py
index 107c6444dca..cc45a31e1ed 100644
--- a/scripts/check_pre_commit_rev_in_example.py
+++ b/scripts/check_pre_commit_rev_in_example.py
@@ -14,7 +14,7 @@
 
 import commonmark
 import yaml
-from bs4 import BeautifulSoup  # type: ignore[import]
+from bs4 import BeautifulSoup  # type: ignore[import-untyped]
 
 
 def main(changes: str, source_version_control: str) -> None:
diff --git a/scripts/check_version_in_basics_example.py b/scripts/check_version_in_basics_example.py
index 0f42bafe334..c90fdb43da5 100644
--- a/scripts/check_version_in_basics_example.py
+++ b/scripts/check_version_in_basics_example.py
@@ -8,7 +8,7 @@
 import sys
 
 import commonmark
-from bs4 import BeautifulSoup  # type: ignore[import]
+from bs4 import BeautifulSoup  # type: ignore[import-untyped]
 
 
 def main(changes: str, the_basics: str) -> None:
diff --git a/scripts/diff_shades_gha_helper.py b/scripts/diff_shades_gha_helper.py
index 895516deb51..8cd8ba155ce 100644
--- a/scripts/diff_shades_gha_helper.py
+++ b/scripts/diff_shades_gha_helper.py
@@ -119,7 +119,7 @@ def main() -> None:
 @main.command("config", help="Acquire run configuration and metadata.")
 @click.argument("event", type=click.Choice(["push", "pull_request"]))
 def config(event: Literal["push", "pull_request"]) -> None:
-    import diff_shades  # type: ignore[import]
+    import diff_shades  # type: ignore[import-not-found]
 
     if event == "push":
         jobs = [{"mode": "preview-changes", "force-flag": "--force-preview-style"}]
diff --git a/scripts/fuzz.py b/scripts/fuzz.py
index 929d3eac4f5..018b66e0ea2 100644
--- a/scripts/fuzz.py
+++ b/scripts/fuzz.py
@@ -80,7 +80,7 @@ def test_idempotent_any_syntatically_valid_python(
     try:
         import sys
 
-        import atheris  # type: ignore[import]
+        import atheris  # type: ignore[import-not-found]
     except ImportError:
         pass
     else:
diff --git a/scripts/make_width_table.py b/scripts/make_width_table.py
index 3c7cae60f7f..1b53c1b2cc9 100644
--- a/scripts/make_width_table.py
+++ b/scripts/make_width_table.py
@@ -20,7 +20,7 @@
 from os.path import basename, dirname, join
 from typing import Iterable, Tuple
 
-import wcwidth  # type: ignore[import]
+import wcwidth  # type: ignore[import-not-found]
 
 
 def make_width_table() -> Iterable[Tuple[int, int, int]]:
diff --git a/src/blackd/__init__.py b/src/blackd/__init__.py
index 972f24181cb..6b0f3d33295 100644
--- a/src/blackd/__init__.py
+++ b/src/blackd/__init__.py
@@ -74,9 +74,7 @@ def main(bind_host: str, bind_port: int) -> None:
     app = make_app()
     ver = black.__version__
     black.out(f"blackd version {ver} listening on {bind_host} port {bind_port}")
-    # TODO: aiohttp had an incorrect annotation for `print` argument,
-    #  It'll be fixed once aiohttp releases that code
-    web.run_app(app, host=bind_host, port=bind_port, handle_signals=True, print=None)  # type: ignore[arg-type]
+    web.run_app(app, host=bind_host, port=bind_port, handle_signals=True, print=None)
 
 
 def make_app() -> web.Application:
diff --git a/tests/optional.py b/tests/optional.py
index 3f5277b6b03..70ee823e316 100644
--- a/tests/optional.py
+++ b/tests/optional.py
@@ -26,7 +26,15 @@
     from pytest import StashKey
 except ImportError:
     # pytest < 7
-    from _pytest.store import StoreKey as StashKey  # type: ignore[import, no-redef]
+    #
+    # "isort: skip" is needed or it moves the "type: ignore" to the following line
+    # because of the line length, and then mypy complains.
+    # Of course, adding the "isort: skip" means that
+    # flake8-bugbear then also complains about the line length,
+    # so we *also* need a "noqa" comment for good measure :)
+    from _pytest.store import (  # type: ignore[import-not-found, no-redef]  # isort: skip  # noqa: B950
+        StoreKey as StashKey,
+    )
 
 log = logging.getLogger(__name__)
 

From 11da02da72ed437facde3658bb61ddebce21e7a4 Mon Sep 17 00:00:00 2001
From: Yilei Yang <yileiyang@google.com>
Date: Sat, 18 Nov 2023 11:47:05 -0800
Subject: [PATCH 0937/1034] Handle more huggable immediately nested
 parens/brackets. (#4012)

Fixes #4011
---
 CHANGES.md                                    |   3 +
 docs/conf.py                                  |  36 +++---
 docs/the_black_code_style/future_style.md     |  17 ++-
 src/black/cache.py                            |   6 +-
 src/black/handle_ipynb_magics.py              |  54 ++++----
 src/black/linegen.py                          |  69 ++++++++--
 ..._parens_with_braces_and_square_brackets.py | 122 ++++++++++++++++--
 .../cases/preview_long_strings__regression.py |  15 +--
 8 files changed, 233 insertions(+), 89 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 13b6c7bdb21..29f037b4767 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -14,6 +14,9 @@
 
 <!-- Changes that affect Black's preview style -->
 
+- Additional cases of immediately nested tuples, lists, and dictionaries are now
+  indented less (#4012)
+
 ### Configuration
 
 <!-- Changes to how Black can be configured -->
diff --git a/docs/conf.py b/docs/conf.py
index 6b645435325..52a849d06a4 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -149,15 +149,13 @@ def make_pypi_svg(version: str) -> None:
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
-latex_documents = [
-    (
-        master_doc,
-        "black.tex",
-        "Documentation for Black",
-        "Łukasz Langa and contributors to Black",
-        "manual",
-    )
-]
+latex_documents = [(
+    master_doc,
+    "black.tex",
+    "Documentation for Black",
+    "Łukasz Langa and contributors to Black",
+    "manual",
+)]
 
 
 # -- Options for manual page output ------------------------------------------
@@ -172,17 +170,15 @@ def make_pypi_svg(version: str) -> None:
 # Grouping the document tree into Texinfo files. List of tuples
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
-texinfo_documents = [
-    (
-        master_doc,
-        "Black",
-        "Documentation for Black",
-        author,
-        "Black",
-        "The uncompromising Python code formatter",
-        "Miscellaneous",
-    )
-]
+texinfo_documents = [(
+    master_doc,
+    "Black",
+    "Documentation for Black",
+    author,
+    "Black",
+    "The uncompromising Python code formatter",
+    "Miscellaneous",
+)]
 
 
 # -- Options for Epub output -------------------------------------------------
diff --git a/docs/the_black_code_style/future_style.md b/docs/the_black_code_style/future_style.md
index 944ffad033e..428bd87ab50 100644
--- a/docs/the_black_code_style/future_style.md
+++ b/docs/the_black_code_style/future_style.md
@@ -116,8 +116,7 @@ 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:
+with braces ("{", "}") and square brackets ("[", "]") on the same line. For example:
 
 ```python
 foo(
@@ -127,6 +126,14 @@ foo(
         3,
     ]
 )
+
+nested_array = [
+    [
+        1,
+        2,
+        3,
+    ]
+]
 ```
 
 will be changed to:
@@ -137,6 +144,12 @@ foo([
     2,
     3,
 ])
+
+nested_array = [[
+    1,
+    2,
+    3,
+]]
 ```
 
 This also applies to list and dictionary unpacking:
diff --git a/src/black/cache.py b/src/black/cache.py
index 6a332304981..6baa096baca 100644
--- a/src/black/cache.py
+++ b/src/black/cache.py
@@ -124,9 +124,9 @@ def filtered_cached(self, sources: Iterable[Path]) -> Tuple[Set[Path], Set[Path]
 
     def write(self, sources: Iterable[Path]) -> None:
         """Update the cache file data and write a new cache file."""
-        self.file_data.update(**{
-            str(src.resolve()): Cache.get_file_data(src) for src in sources
-        })
+        self.file_data.update(
+            **{str(src.resolve()): Cache.get_file_data(src) for src in sources}
+        )
         try:
             CACHE_DIR.mkdir(parents=True, exist_ok=True)
             with tempfile.NamedTemporaryFile(
diff --git a/src/black/handle_ipynb_magics.py b/src/black/handle_ipynb_magics.py
index 55ef2267df8..5b2847cb0c4 100644
--- a/src/black/handle_ipynb_magics.py
+++ b/src/black/handle_ipynb_magics.py
@@ -17,36 +17,30 @@
 from black.output import out
 from black.report import NothingChanged
 
-TRANSFORMED_MAGICS = frozenset(
-    (
-        "get_ipython().run_cell_magic",
-        "get_ipython().system",
-        "get_ipython().getoutput",
-        "get_ipython().run_line_magic",
-    )
-)
-TOKENS_TO_IGNORE = frozenset(
-    (
-        "ENDMARKER",
-        "NL",
-        "NEWLINE",
-        "COMMENT",
-        "DEDENT",
-        "UNIMPORTANT_WS",
-        "ESCAPED_NL",
-    )
-)
-PYTHON_CELL_MAGICS = frozenset(
-    (
-        "capture",
-        "prun",
-        "pypy",
-        "python",
-        "python3",
-        "time",
-        "timeit",
-    )
-)
+TRANSFORMED_MAGICS = frozenset((
+    "get_ipython().run_cell_magic",
+    "get_ipython().system",
+    "get_ipython().getoutput",
+    "get_ipython().run_line_magic",
+))
+TOKENS_TO_IGNORE = frozenset((
+    "ENDMARKER",
+    "NL",
+    "NEWLINE",
+    "COMMENT",
+    "DEDENT",
+    "UNIMPORTANT_WS",
+    "ESCAPED_NL",
+))
+PYTHON_CELL_MAGICS = frozenset((
+    "capture",
+    "prun",
+    "pypy",
+    "python",
+    "python3",
+    "time",
+    "timeit",
+))
 TOKEN_HEX = secrets.token_hex
 
 
diff --git a/src/black/linegen.py b/src/black/linegen.py
index e2c961d7a01..8a2cd4710b9 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -817,25 +817,66 @@ def _first_right_hand_split(
     body_leaves.reverse()
     head_leaves.reverse()
 
-    if Preview.hug_parens_with_braces_and_square_brackets in line.mode:
-        is_unpacking = 1 if body_leaves[0].type in [token.STAR, token.DOUBLESTAR] else 0
-        if (
-            tail_leaves[0].type == token.RPAR
-            and tail_leaves[0].value
-            and tail_leaves[0].opening_bracket is head_leaves[-1]
-            and body_leaves[-1].type in [token.RBRACE, token.RSQB]
-            and body_leaves[-1].opening_bracket is body_leaves[is_unpacking]
+    body: Optional[Line] = None
+    if (
+        Preview.hug_parens_with_braces_and_square_brackets in line.mode
+        and tail_leaves[0].value
+        and tail_leaves[0].opening_bracket is head_leaves[-1]
+    ):
+        inner_body_leaves = list(body_leaves)
+        hugged_opening_leaves: List[Leaf] = []
+        hugged_closing_leaves: List[Leaf] = []
+        is_unpacking = body_leaves[0].type in [token.STAR, token.DOUBLESTAR]
+        unpacking_offset: int = 1 if is_unpacking else 0
+        while (
+            len(inner_body_leaves) >= 2 + unpacking_offset
+            and inner_body_leaves[-1].type in CLOSING_BRACKETS
+            and inner_body_leaves[-1].opening_bracket
+            is inner_body_leaves[unpacking_offset]
         ):
-            head_leaves = head_leaves + body_leaves[: 1 + is_unpacking]
-            tail_leaves = body_leaves[-1:] + tail_leaves
-            body_leaves = body_leaves[1 + is_unpacking : -1]
+            if unpacking_offset:
+                hugged_opening_leaves.append(inner_body_leaves.pop(0))
+                unpacking_offset = 0
+            hugged_opening_leaves.append(inner_body_leaves.pop(0))
+            hugged_closing_leaves.insert(0, inner_body_leaves.pop())
+
+        if hugged_opening_leaves and inner_body_leaves:
+            inner_body = bracket_split_build_line(
+                inner_body_leaves,
+                line,
+                hugged_opening_leaves[-1],
+                component=_BracketSplitComponent.body,
+            )
+            if (
+                line.mode.magic_trailing_comma
+                and inner_body_leaves[-1].type == token.COMMA
+            ):
+                should_hug = True
+            else:
+                line_length = line.mode.line_length - sum(
+                    len(str(leaf))
+                    for leaf in hugged_opening_leaves + hugged_closing_leaves
+                )
+                if is_line_short_enough(
+                    inner_body, mode=replace(line.mode, line_length=line_length)
+                ):
+                    # Do not hug if it fits on a single line.
+                    should_hug = False
+                else:
+                    should_hug = True
+            if should_hug:
+                body_leaves = inner_body_leaves
+                head_leaves.extend(hugged_opening_leaves)
+                tail_leaves = hugged_closing_leaves + tail_leaves
+                body = inner_body  # No need to re-calculate the body again later.
 
     head = bracket_split_build_line(
         head_leaves, line, opening_bracket, component=_BracketSplitComponent.head
     )
-    body = bracket_split_build_line(
-        body_leaves, line, opening_bracket, component=_BracketSplitComponent.body
-    )
+    if body is None:
+        body = bracket_split_build_line(
+            body_leaves, line, opening_bracket, component=_BracketSplitComponent.body
+        )
     tail = bracket_split_build_line(
         tail_leaves, line, opening_bracket, component=_BracketSplitComponent.tail
     )
diff --git a/tests/data/cases/preview_hug_parens_with_braces_and_square_brackets.py b/tests/data/cases/preview_hug_parens_with_braces_and_square_brackets.py
index 97b5b2e8dd1..9e5c9eb8546 100644
--- a/tests/data/cases/preview_hug_parens_with_braces_and_square_brackets.py
+++ b/tests/data/cases/preview_hug_parens_with_braces_and_square_brackets.py
@@ -128,6 +128,19 @@ def foo_square_brackets(request):
 func({"short line"})
 func({"long line", "long long line", "long long long line", "long long long long line", "long long long long long line"})
 func({{"long line", "long long line", "long long long line", "long long long long line", "long long long long long line"}})
+func(("long line", "long long line", "long long long line", "long long long long line", "long long long long long line"))
+func((("long line", "long long line", "long long long line", "long long long long line", "long long long long long line")))
+func([["long line", "long long line", "long long long line", "long long long long line", "long long long long long line"]])
+
+# Do not hug if the argument fits on a single line.
+func({"fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit line"})
+func(("fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit line"))
+func(["fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit line"])
+func(**{"fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit---"})
+func(*("fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit----"))
+array = [{"fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit line"}]
+array = [("fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit line")]
+array = [["fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit line"]]
 
 foooooooooooooooooooo(
     [{c: n + 1 for c in range(256)} for n in range(100)] + [{}], {size}
@@ -137,6 +150,13 @@ def foo_square_brackets(request):
     [1, 2, 3, 4, 5, 6, 7, 8, 9, 10], {x}, "a string", [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
 )
 
+nested_mapping = {"key": [{"a very long key 1": "with a very long value", "a very long key 2": "with a very long value"}]}
+nested_array = [[["long line", "long long line", "long long long line", "long long long long line", "long long long long long line"]]]
+explicit_exploding = [[["short", "line",],],]
+single_item_do_not_explode = Context({
+    "version": get_docs_version(),
+})
+
 foo(*["long long long long long line", "long long long long long line", "long long long long long line"])
 
 foo(*[str(i) for i in range(100000000000000000000000000000000000000000000000000000000000)])
@@ -152,6 +172,9 @@ def foo_square_brackets(request):
 
 foo(**{x: y for x, y in enumerate(["long long long long line","long long long long line"])})
 
+# Edge case when deciding whether to hug the brackets without inner content.
+very_very_very_long_variable = very_very_very_long_module.VeryVeryVeryVeryLongClassName([[]])
+
 for foo in ["a", "b"]:
     output.extend([
         individual
@@ -276,9 +299,9 @@ def foo_square_brackets(request):
 )
 
 func([x for x in "short line"])
-func([
-    x for x in "long line long line long line long line long line long line long line"
-])
+func(
+    [x for x in "long line long line long line long line long line long line long line"]
+)
 func([
     x
     for x in [
@@ -295,15 +318,60 @@ def foo_square_brackets(request):
     "long long long long line",
     "long long long long long line",
 })
-func({
-    {
-        "long line",
-        "long long line",
-        "long long long line",
-        "long long long long line",
-        "long long long long long line",
-    }
-})
+func({{
+    "long line",
+    "long long line",
+    "long long long line",
+    "long long long long line",
+    "long long long long long line",
+}})
+func((
+    "long line",
+    "long long line",
+    "long long long line",
+    "long long long long line",
+    "long long long long long line",
+))
+func(((
+    "long line",
+    "long long line",
+    "long long long line",
+    "long long long long line",
+    "long long long long long line",
+)))
+func([[
+    "long line",
+    "long long line",
+    "long long long line",
+    "long long long long line",
+    "long long long long long line",
+]])
+
+# Do not hug if the argument fits on a single line.
+func(
+    {"fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit line"}
+)
+func(
+    ("fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit line")
+)
+func(
+    ["fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit line"]
+)
+func(
+    **{"fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit---"}
+)
+func(
+    *("fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit----")
+)
+array = [
+    {"fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit line"}
+]
+array = [
+    ("fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit line")
+]
+array = [
+    ["fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit line"]
+]
 
 foooooooooooooooooooo(
     [{c: n + 1 for c in range(256)} for n in range(100)] + [{}], {size}
@@ -313,6 +381,31 @@ def foo_square_brackets(request):
     [1, 2, 3, 4, 5, 6, 7, 8, 9, 10], {x}, "a string", [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
 )
 
+nested_mapping = {
+    "key": [{
+        "a very long key 1": "with a very long value",
+        "a very long key 2": "with a very long value",
+    }]
+}
+nested_array = [[[
+    "long line",
+    "long long line",
+    "long long long line",
+    "long long long long line",
+    "long long long long long line",
+]]]
+explicit_exploding = [
+    [
+        [
+            "short",
+            "line",
+        ],
+    ],
+]
+single_item_do_not_explode = Context({
+    "version": get_docs_version(),
+})
+
 foo(*[
     "long long long long long line",
     "long long long long long line",
@@ -334,6 +427,11 @@ def foo_square_brackets(request):
     x: y for x, y in enumerate(["long long long long line", "long long long long line"])
 })
 
+# Edge case when deciding whether to hug the brackets without inner content.
+very_very_very_long_variable = very_very_very_long_module.VeryVeryVeryVeryLongClassName(
+    [[]]
+)
+
 for foo in ["a", "b"]:
     output.extend([
         individual
diff --git a/tests/data/cases/preview_long_strings__regression.py b/tests/data/cases/preview_long_strings__regression.py
index 313d898cd83..5e76a8cf61c 100644
--- a/tests/data/cases/preview_long_strings__regression.py
+++ b/tests/data/cases/preview_long_strings__regression.py
@@ -611,14 +611,13 @@ def foo():
 
 class A:
     def foo():
-        XXXXXXXXXXXX.append(
-            (
-                "xxx_xxxxxxxxxx(xxxxx={}, xxxx={}, xxxxx, xxxx_xxxx_xxxxxxxxxx={})"
-                .format(xxxxx, xxxx, xxxx_xxxx_xxxxxxxxxx),
-                my_var,
-                my_other_var,
-            )
-        )
+        XXXXXXXXXXXX.append((
+            "xxx_xxxxxxxxxx(xxxxx={}, xxxx={}, xxxxx, xxxx_xxxx_xxxxxxxxxx={})".format(
+                xxxxx, xxxx, xxxx_xxxx_xxxxxxxxxx
+            ),
+            my_var,
+            my_other_var,
+        ))
 
 
 class A:

From 80a166f2e115bda9f33d29a5ea313be2557dc7fd Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Sat, 18 Nov 2023 12:09:55 -0800
Subject: [PATCH 0938/1034] Make black[d] install + test run with 3.12 (#4035)

* Make black[d] install + test run with 3.12

- With aiohttp >= 3.9.0 we can now install all dependencies with 3.12
- Add actions to run 3.12
- Lint still needs to be 3.11

Test:
- `python3.12 -m venv /tmp/tb --upgrade-deps`
- `/tmp/tb/bin/pip install tox`
- `/tmp/tb/bin/pip install .[d]`
- `/tmp/tb/bin/tox -e py312`
```
  py312: OK (37.61=setup[3.98]+cmd[3.83,0.36,19.54,6.46,3.00,0.44] seconds)
  congratulations :) (37.63 seconds)
```

* Move to pypy-3.9

---------

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 .github/workflows/doc.yml  | 2 +-
 .github/workflows/fuzz.yml | 2 +-
 .github/workflows/test.yml | 2 +-
 CHANGES.md                 | 2 +-
 pyproject.toml             | 2 +-
 5 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml
index 9a23e19cadd..fa3d87c70f5 100644
--- a/.github/workflows/doc.yml
+++ b/.github/workflows/doc.yml
@@ -26,7 +26,7 @@ jobs:
       - name: Set up latest Python
         uses: actions/setup-python@v4
         with:
-          python-version: "3.11"
+          python-version: "*"
 
       - name: Install dependencies
         run: |
diff --git a/.github/workflows/fuzz.yml b/.github/workflows/fuzz.yml
index 1b5a50c0e0b..48c26452c54 100644
--- a/.github/workflows/fuzz.yml
+++ b/.github/workflows/fuzz.yml
@@ -22,7 +22,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.8", "3.9", "3.10", "3.11"]
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
 
     steps:
       - uses: actions/checkout@v4
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 1f33f2b814f..3f8928cc42a 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -31,7 +31,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.8", "3.9", "3.10", "3.11", "pypy-3.8"]
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "pypy-3.9"]
         os: [ubuntu-latest, macOS-latest, windows-latest]
 
     steps:
diff --git a/CHANGES.md b/CHANGES.md
index 29f037b4767..9f7ab685afe 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -43,7 +43,7 @@
 
 ### Integrations
 
-<!-- For example, Docker, GitHub Actions, pre-commit, editors -->
+- Enable 3.12 CI (#4035)
 
 ### Documentation
 
diff --git a/pyproject.toml b/pyproject.toml
index f8f5155e898..e63e0aea3ef 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -7,7 +7,7 @@
 
 [tool.black]
 line-length = 88
-target-version = ['py37', 'py38']
+target-version = ['py38']
 include = '\.pyi?$'
 extend-exclude = '''
 /(

From 96faa3b469298573be9d3e2d55982328ee5feef9 Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Sat, 18 Nov 2023 18:09:47 -0800
Subject: [PATCH 0939/1034] [docker] Build with 3.12 image (#4055)

Test:
```
crl-m1:black cooper$ docker build --tag black_3_12 .
...
 => [stage-1 2/2] COPY --from=builder /opt/venv /opt/venv                                                                                                                                                  0.2s
 => exporting to image                                                                                                                                                                                     0.1s
 => => exporting layers                                                                                                                                                                                    0.1s
 => => writing image sha256:bd66acc9d76d2c40d287b0684ce6601401631e0468204c4e6a81f8f1eebaf1dd                                                                                                               0.0s
 => => naming to docker.io/library/black_3_12

crl-m1:black cooper$ docker image ls | grep black_3_12
black_3_12                     latest            bd66acc9d76d   59 seconds ago   193MB
```
---
 CHANGES.md | 1 +
 Dockerfile | 4 ++--
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 9f7ab685afe..b3beefdd80e 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -44,6 +44,7 @@
 ### Integrations
 
 - Enable 3.12 CI (#4035)
+- Build docker images with 3.12 (#4055)
 
 ### Documentation
 
diff --git a/Dockerfile b/Dockerfile
index bfd9acccb99..ab961a2f491 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -1,4 +1,4 @@
-FROM python:3.11-slim AS builder
+FROM python:3.12-slim AS builder
 
 RUN mkdir /src
 COPY . /src/
@@ -12,7 +12,7 @@ RUN . /opt/venv/bin/activate && pip install --no-cache-dir --upgrade pip setupto
     && cd /src && hatch build -t wheel \
     && pip install --no-cache-dir dist/*-cp*[colorama,d,uvloop]
 
-FROM python:3.11-slim
+FROM python:3.12-slim
 
 # copy only Python packages to limit the image size
 COPY --from=builder /opt/venv /opt/venv

From f23b845a295f1422a1989f5ea1560ad2e0fadcdd Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Sat, 18 Nov 2023 18:11:50 -0800
Subject: [PATCH 0940/1034] [ci] Move 'lint' to 3.12 (#4053)

- Add to run on MacOS + Windows too
- Do not install [d] dependecies as blackd is not actually run / checked
- Move to default GitHub action version - which is 3.12 today
---
 .github/workflows/lint.yml | 12 ++++++++----
 tox.ini                    |  2 +-
 2 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index 7fe1b04eb02..d1ad23bb2ab 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -1,4 +1,4 @@
-name: Lint
+name: Lint + format ourselves
 
 on: [push, pull_request]
 
@@ -11,7 +11,11 @@ jobs:
       github.event_name == 'push' || github.event.pull_request.head.repo.full_name !=
       github.repository
 
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macOS-latest, windows-latest]
 
     steps:
       - uses: actions/checkout@v4
@@ -26,12 +30,12 @@ jobs:
       - name: Set up latest Python
         uses: actions/setup-python@v4
         with:
-          python-version: "3.11"
+          python-version: "*"
 
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          python -m pip install -e '.[d]'
+          python -m pip install -e '.'
           python -m pip install tox
 
       - name: Run pre-commit hooks
diff --git a/tox.ini b/tox.ini
index 018cef993c0..8b4175d23fe 100644
--- a/tox.ini
+++ b/tox.ini
@@ -94,5 +94,5 @@ commands =
 setenv = PYTHONPATH = {toxinidir}/src
 skip_install = True
 commands =
-    pip install -e .[d]
+    pip install -e .
     black --check {toxinidir}/src {toxinidir}/tests

From 30c6bb3651634ebf66177c85b27e7e277316eab7 Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Sun, 19 Nov 2023 10:44:00 -0800
Subject: [PATCH 0941/1034] [docker ci] Split up amd64 (x86_64) and arm64
 builds (#4054)

* [docker ci] Split up amd64 (x86_64) and arm64 builds

- Lets run them seperately to cut down total time
- Will also more clearly show if either arch has specific problems
- Kept amd64 (x86_64) using qemu actions so if GitHub ever offers arm64 boxes it could stay working too

Fixes #3971

* Add CHANGES entry

---------

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 .../{docker.yml => docker_amd64.yml}          |  8 +--
 .github/workflows/docker_arm64.yml            | 69 +++++++++++++++++++
 CHANGES.md                                    |  1 +
 3 files changed, 74 insertions(+), 4 deletions(-)
 rename .github/workflows/{docker.yml => docker_amd64.yml} (92%)
 create mode 100644 .github/workflows/docker_arm64.yml

diff --git a/.github/workflows/docker.yml b/.github/workflows/docker_amd64.yml
similarity index 92%
rename from .github/workflows/docker.yml
rename to .github/workflows/docker_amd64.yml
index ee858236fcf..846cd8c74e3 100644
--- a/.github/workflows/docker.yml
+++ b/.github/workflows/docker_amd64.yml
@@ -1,4 +1,4 @@
-name: docker
+name: docker amd64 (x86_64)
 
 on:
   push:
@@ -39,7 +39,7 @@ jobs:
         uses: docker/build-push-action@v5
         with:
           context: .
-          platforms: linux/amd64,linux/arm64
+          platforms: linux/amd64
           push: true
           tags: pyfound/black:latest,pyfound/black:${{ env.GIT_TAG }}
 
@@ -50,7 +50,7 @@ jobs:
         uses: docker/build-push-action@v5
         with:
           context: .
-          platforms: linux/amd64,linux/arm64
+          platforms: linux/amd64
           push: true
           tags: pyfound/black:latest_release
 
@@ -61,7 +61,7 @@ jobs:
         uses: docker/build-push-action@v5
         with:
           context: .
-          platforms: linux/amd64,linux/arm64
+          platforms: linux/amd64
           push: true
           tags: pyfound/black:latest_prerelease
 
diff --git a/.github/workflows/docker_arm64.yml b/.github/workflows/docker_arm64.yml
new file mode 100644
index 00000000000..ddd554165af
--- /dev/null
+++ b/.github/workflows/docker_arm64.yml
@@ -0,0 +1,69 @@
+name: docker arm64
+
+on:
+  push:
+    branches:
+      - "main"
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  docker:
+    if: github.repository == 'psf/black'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to DockerHub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Check + set version tag
+        run:
+          echo "GIT_TAG=$(git describe --candidates=0 --tags 2> /dev/null || echo
+          latest_non_release)" >> $GITHUB_ENV
+
+      - name: Build and push
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          platforms: linux/arm64
+          push: true
+          tags: pyfound/black:latest,pyfound/black:${{ env.GIT_TAG }}
+
+      - name: Build and push latest_release tag
+        if:
+          ${{ github.event_name == 'release' && github.event.action == 'published' &&
+          !github.event.release.prerelease }}
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          platforms: linux/arm64
+          push: true
+          tags: pyfound/black:latest_release
+
+      - name: Build and push latest_prerelease tag
+        if:
+          ${{ github.event_name == 'release' && github.event.action == 'published' &&
+          github.event.release.prerelease }}
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          platforms: linux/arm64
+          push: true
+          tags: pyfound/black:latest_prerelease
+
+      - name: Image digest
+        run: echo ${{ steps.docker_build.outputs.digest }}
diff --git a/CHANGES.md b/CHANGES.md
index b3beefdd80e..8d0f10a2f3a 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -44,6 +44,7 @@
 ### Integrations
 
 - Enable 3.12 CI (#4035)
+- Build docker images in parallel (#4054)
 - Build docker images with 3.12 (#4055)
 
 ### Documentation

From ec4a1525ee7f0daf05a2ab709123fbb0fe69e4e2 Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Sun, 19 Nov 2023 11:28:00 -0800
Subject: [PATCH 0942/1034] [docker ci] Revert "parallel" builds in seperate
 actions (#4057)

- Broke tagging images together
- Saved only a few mins
  - x86_64 build is fast, time is all spent on cross compile of arm64
- Also remove evil copy pasta ... which is nice

Was worth an attempt.
---
 .../{docker_amd64.yml => docker.yml}          |  8 +--
 .github/workflows/docker_arm64.yml            | 69 -------------------
 2 files changed, 4 insertions(+), 73 deletions(-)
 rename .github/workflows/{docker_amd64.yml => docker.yml} (92%)
 delete mode 100644 .github/workflows/docker_arm64.yml

diff --git a/.github/workflows/docker_amd64.yml b/.github/workflows/docker.yml
similarity index 92%
rename from .github/workflows/docker_amd64.yml
rename to .github/workflows/docker.yml
index 846cd8c74e3..ee858236fcf 100644
--- a/.github/workflows/docker_amd64.yml
+++ b/.github/workflows/docker.yml
@@ -1,4 +1,4 @@
-name: docker amd64 (x86_64)
+name: docker
 
 on:
   push:
@@ -39,7 +39,7 @@ jobs:
         uses: docker/build-push-action@v5
         with:
           context: .
-          platforms: linux/amd64
+          platforms: linux/amd64,linux/arm64
           push: true
           tags: pyfound/black:latest,pyfound/black:${{ env.GIT_TAG }}
 
@@ -50,7 +50,7 @@ jobs:
         uses: docker/build-push-action@v5
         with:
           context: .
-          platforms: linux/amd64
+          platforms: linux/amd64,linux/arm64
           push: true
           tags: pyfound/black:latest_release
 
@@ -61,7 +61,7 @@ jobs:
         uses: docker/build-push-action@v5
         with:
           context: .
-          platforms: linux/amd64
+          platforms: linux/amd64,linux/arm64
           push: true
           tags: pyfound/black:latest_prerelease
 
diff --git a/.github/workflows/docker_arm64.yml b/.github/workflows/docker_arm64.yml
deleted file mode 100644
index ddd554165af..00000000000
--- a/.github/workflows/docker_arm64.yml
+++ /dev/null
@@ -1,69 +0,0 @@
-name: docker arm64
-
-on:
-  push:
-    branches:
-      - "main"
-  release:
-    types: [published]
-
-permissions:
-  contents: read
-
-jobs:
-  docker:
-    if: github.repository == 'psf/black'
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Set up QEMU
-        uses: docker/setup-qemu-action@v3
-
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
-
-      - name: Login to DockerHub
-        uses: docker/login-action@v3
-        with:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-
-      - name: Check + set version tag
-        run:
-          echo "GIT_TAG=$(git describe --candidates=0 --tags 2> /dev/null || echo
-          latest_non_release)" >> $GITHUB_ENV
-
-      - name: Build and push
-        uses: docker/build-push-action@v5
-        with:
-          context: .
-          platforms: linux/arm64
-          push: true
-          tags: pyfound/black:latest,pyfound/black:${{ env.GIT_TAG }}
-
-      - name: Build and push latest_release tag
-        if:
-          ${{ github.event_name == 'release' && github.event.action == 'published' &&
-          !github.event.release.prerelease }}
-        uses: docker/build-push-action@v5
-        with:
-          context: .
-          platforms: linux/arm64
-          push: true
-          tags: pyfound/black:latest_release
-
-      - name: Build and push latest_prerelease tag
-        if:
-          ${{ github.event_name == 'release' && github.event.action == 'published' &&
-          github.event.release.prerelease }}
-        uses: docker/build-push-action@v5
-        with:
-          context: .
-          platforms: linux/arm64
-          push: true
-          tags: pyfound/black:latest_prerelease
-
-      - name: Image digest
-        run: echo ${{ steps.docker_build.outputs.digest }}

From 89e28ea66f50d4281cb9f624e31566aed9d5aab1 Mon Sep 17 00:00:00 2001
From: tungol <github@tungol.org>
Date: Mon, 20 Nov 2023 20:44:33 -0800
Subject: [PATCH 0943/1034] Permit standalone form feed characters at the
 module level (#4021)

Co-authored-by: Stephen Morton <git@tungol.org>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 CHANGES.md                                    |   2 +-
 .../reference/reference_functions.rst         |   4 +-
 docs/the_black_code_style/future_style.md     |  11 +
 src/black/comments.py                         |  39 ++-
 src/black/linegen.py                          |  25 +-
 src/black/lines.py                            |  14 +-
 src/black/mode.py                             |   1 +
 src/black/nodes.py                            |   7 +
 src/black/output.py                           |  23 +-
 src/blib2to3/pgen2/driver.py                  |   2 +
 tests/data/cases/preview_form_feeds.py        | 225 ++++++++++++++++++
 11 files changed, 318 insertions(+), 35 deletions(-)
 create mode 100644 tests/data/cases/preview_form_feeds.py

diff --git a/CHANGES.md b/CHANGES.md
index 8d0f10a2f3a..4c3fbf1afc8 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -12,7 +12,7 @@
 
 ### Preview style
 
-<!-- Changes that affect Black's preview style -->
+- Standalone form feed characters at the module level are no longer removed (#4021)
 
 - Additional cases of immediately nested tuples, lists, and dictionaries are now
   indented less (#4012)
diff --git a/docs/contributing/reference/reference_functions.rst b/docs/contributing/reference/reference_functions.rst
index dd92e37a7d4..ebadf6975a7 100644
--- a/docs/contributing/reference/reference_functions.rst
+++ b/docs/contributing/reference/reference_functions.rst
@@ -149,7 +149,7 @@ Utilities
 
 .. autofunction:: black.numerics.normalize_numeric_literal
 
-.. autofunction:: black.linegen.normalize_prefix
+.. autofunction:: black.comments.normalize_trailing_prefix
 
 .. autofunction:: black.strings.normalize_string_prefix
 
@@ -168,3 +168,5 @@ Utilities
 .. autofunction:: black.strings.sub_twice
 
 .. autofunction:: black.nodes.whitespace
+
+.. autofunction:: black.nodes.make_simple_prefix
diff --git a/docs/the_black_code_style/future_style.md b/docs/the_black_code_style/future_style.md
index 428bd87ab50..f55ea5f60a9 100644
--- a/docs/the_black_code_style/future_style.md
+++ b/docs/the_black_code_style/future_style.md
@@ -296,3 +296,14 @@ s = (  # Top comment
     # Bottom comment
 )
 ```
+
+=======
+
+### Form feed characters
+
+_Black_ will now retain form feed characters on otherwise empty lines at the module
+level. Only one form feed is retained for a group of consecutive empty lines. Where
+there are two empty lines in a row, the form feed will be placed on the second line.
+
+_Black_ already retained form feed literals inside a comment or inside a string. This
+remains the case.
diff --git a/src/black/comments.py b/src/black/comments.py
index 862fc7607cc..8a0e925fdc0 100644
--- a/src/black/comments.py
+++ b/src/black/comments.py
@@ -10,6 +10,7 @@
     WHITESPACE,
     container_of,
     first_leaf_of,
+    make_simple_prefix,
     preceding_leaf,
     syms,
 )
@@ -44,6 +45,7 @@ class ProtoComment:
     value: str  # content of the comment
     newlines: int  # how many newlines before the comment
     consumed: int  # how many characters of the original leaf's prefix did we consume
+    form_feed: bool  # is there a form feed before the comment
 
 
 def generate_comments(leaf: LN) -> Iterator[Leaf]:
@@ -65,8 +67,12 @@ def generate_comments(leaf: LN) -> Iterator[Leaf]:
     Inline comments are emitted as regular token.COMMENT leaves.  Standalone
     are emitted with a fake STANDALONE_COMMENT token identifier.
     """
+    total_consumed = 0
     for pc in list_comments(leaf.prefix, is_endmarker=leaf.type == token.ENDMARKER):
-        yield Leaf(pc.type, pc.value, prefix="\n" * pc.newlines)
+        total_consumed = pc.consumed
+        prefix = make_simple_prefix(pc.newlines, pc.form_feed)
+        yield Leaf(pc.type, pc.value, prefix=prefix)
+    normalize_trailing_prefix(leaf, total_consumed)
 
 
 @lru_cache(maxsize=4096)
@@ -79,11 +85,14 @@ def list_comments(prefix: str, *, is_endmarker: bool) -> List[ProtoComment]:
     consumed = 0
     nlines = 0
     ignored_lines = 0
-    for index, line in enumerate(re.split("\r?\n", prefix)):
-        consumed += len(line) + 1  # adding the length of the split '\n'
-        line = line.lstrip()
+    form_feed = False
+    for index, full_line in enumerate(re.split("\r?\n", prefix)):
+        consumed += len(full_line) + 1  # adding the length of the split '\n'
+        line = full_line.lstrip()
         if not line:
             nlines += 1
+            if "\f" in full_line:
+                form_feed = True
         if not line.startswith("#"):
             # Escaped newlines outside of a comment are not really newlines at
             # all. We treat a single-line comment following an escaped newline
@@ -99,13 +108,33 @@ def list_comments(prefix: str, *, is_endmarker: bool) -> List[ProtoComment]:
         comment = make_comment(line)
         result.append(
             ProtoComment(
-                type=comment_type, value=comment, newlines=nlines, consumed=consumed
+                type=comment_type,
+                value=comment,
+                newlines=nlines,
+                consumed=consumed,
+                form_feed=form_feed,
             )
         )
+        form_feed = False
         nlines = 0
     return result
 
 
+def normalize_trailing_prefix(leaf: LN, total_consumed: int) -> None:
+    """Normalize the prefix that's left over after generating comments.
+
+    Note: don't use backslashes for formatting or you'll lose your voting rights.
+    """
+    remainder = leaf.prefix[total_consumed:]
+    if "\\" not in remainder:
+        nl_count = remainder.count("\n")
+        form_feed = "\f" in remainder and remainder.endswith("\n")
+        leaf.prefix = make_simple_prefix(nl_count, form_feed)
+        return
+
+    leaf.prefix = ""
+
+
 def make_comment(content: str) -> str:
     """Return a consistently formatted comment from the given `content` string.
 
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 8a2cd4710b9..7fbbe290d7e 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -149,7 +149,8 @@ def visit_default(self, node: LN) -> Iterator[Line]:
                     self.current_line.append(comment)
                     yield from self.line()
 
-            normalize_prefix(node, inside_brackets=any_open_brackets)
+            if any_open_brackets:
+                node.prefix = ""
             if self.mode.string_normalization and node.type == token.STRING:
                 node.value = normalize_string_prefix(node.value)
                 node.value = normalize_string_quotes(node.value)
@@ -1035,8 +1036,6 @@ def bracket_split_build_line(
         result.inside_brackets = True
         result.depth += 1
         if leaves:
-            # Since body is a new indent level, remove spurious leading whitespace.
-            normalize_prefix(leaves[0], inside_brackets=True)
             # Ensure a trailing comma for imports and standalone function arguments, but
             # be careful not to add one after any comments or within type annotations.
             no_commas = (
@@ -1106,7 +1105,7 @@ def split_wrapper(
         line: Line, features: Collection[Feature], mode: Mode
     ) -> Iterator[Line]:
         for split_line in split_func(line, features, mode):
-            normalize_prefix(split_line.leaves[0], inside_brackets=True)
+            split_line.leaves[0].prefix = ""
             yield split_line
 
     return split_wrapper
@@ -1250,24 +1249,6 @@ def append_to_line(leaf: Leaf) -> Iterator[Line]:
         yield current_line
 
 
-def normalize_prefix(leaf: Leaf, *, inside_brackets: bool) -> None:
-    """Leave existing extra newlines if not `inside_brackets`. Remove everything
-    else.
-
-    Note: don't use backslashes for formatting or you'll lose your voting rights.
-    """
-    if not inside_brackets:
-        spl = leaf.prefix.split("#")
-        if "\\" not in spl[0]:
-            nl_count = spl[-1].count("\n")
-            if len(spl) > 1:
-                nl_count -= 1
-            leaf.prefix = "\n" * nl_count
-            return
-
-    leaf.prefix = ""
-
-
 def normalize_invisible_parens(  # noqa: C901
     node: Node, parens_after: Set[str], *, mode: Mode, features: Collection[Feature]
 ) -> None:
diff --git a/src/black/lines.py b/src/black/lines.py
index 3ade0a5f4a5..ec6145ff848 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -31,6 +31,7 @@
     is_type_comment,
     is_type_ignore_comment,
     is_with_or_async_with_stmt,
+    make_simple_prefix,
     replace_child,
     syms,
     whitespace,
@@ -520,12 +521,12 @@ class LinesBlock:
     before: int = 0
     content_lines: List[str] = field(default_factory=list)
     after: int = 0
+    form_feed: bool = False
 
     def all_lines(self) -> List[str]:
         empty_line = str(Line(mode=self.mode))
-        return (
-            [empty_line * self.before] + self.content_lines + [empty_line * self.after]
-        )
+        prefix = make_simple_prefix(self.before, self.form_feed, empty_line)
+        return [prefix] + self.content_lines + [empty_line * self.after]
 
 
 @dataclass
@@ -550,6 +551,12 @@ def maybe_empty_lines(self, current_line: Line) -> LinesBlock:
         This is for separating `def`, `async def` and `class` with extra empty
         lines (two on module-level).
         """
+        form_feed = (
+            Preview.allow_form_feeds in self.mode
+            and current_line.depth == 0
+            and bool(current_line.leaves)
+            and "\f\n" in current_line.leaves[0].prefix
+        )
         before, after = self._maybe_empty_lines(current_line)
         previous_after = self.previous_block.after if self.previous_block else 0
         before = (
@@ -575,6 +582,7 @@ def maybe_empty_lines(self, current_line: Line) -> LinesBlock:
             original_line=current_line,
             before=before,
             after=after,
+            form_feed=form_feed,
         )
 
         # Maintain the semantic_leading_comment state.
diff --git a/src/black/mode.py b/src/black/mode.py
index 1aa5cbecc86..04038f49627 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -194,6 +194,7 @@ class Preview(Enum):
     allow_empty_first_line_before_new_block_or_comment = auto()
     single_line_format_skip_with_multiple_comments = auto()
     long_case_block_line_splitting = auto()
+    allow_form_feeds = auto()
 
 
 class Deprecated(UserWarning):
diff --git a/src/black/nodes.py b/src/black/nodes.py
index 9251b0defb0..de53f8e36a3 100644
--- a/src/black/nodes.py
+++ b/src/black/nodes.py
@@ -407,6 +407,13 @@ def whitespace(leaf: Leaf, *, complex_subscript: bool, mode: Mode) -> str:  # no
     return SPACE
 
 
+def make_simple_prefix(nl_count: int, form_feed: bool, empty_line: str = "\n") -> str:
+    """Generate a normalized prefix string."""
+    if form_feed:
+        return (empty_line * (nl_count - 1)) + "\f" + empty_line
+    return empty_line * nl_count
+
+
 def preceding_leaf(node: Optional[LN]) -> Optional[Leaf]:
     """Return the first leaf that precedes `node`, if any."""
     while node:
diff --git a/src/black/output.py b/src/black/output.py
index f4c17f28ea4..7c7dd0fe14e 100644
--- a/src/black/output.py
+++ b/src/black/output.py
@@ -4,8 +4,9 @@
 """
 
 import json
+import re
 import tempfile
-from typing import Any, Optional
+from typing import Any, List, Optional
 
 from click import echo, style
 from mypy_extensions import mypyc_attr
@@ -55,12 +56,28 @@ def ipynb_diff(a: str, b: str, a_name: str, b_name: str) -> str:
     return "".join(diff_lines)
 
 
+_line_pattern = re.compile(r"(.*?(?:\r\n|\n|\r|$))")
+
+
+def _splitlines_no_ff(source: str) -> List[str]:
+    """Split a string into lines ignoring form feed and other chars.
+
+    This mimics how the Python parser splits source code.
+
+    A simplified version of the function with the same name in Lib/ast.py
+    """
+    result = [match[0] for match in _line_pattern.finditer(source)]
+    if result[-1] == "":
+        result.pop(-1)
+    return result
+
+
 def diff(a: str, b: str, a_name: str, b_name: str) -> str:
     """Return a unified diff string between strings `a` and `b`."""
     import difflib
 
-    a_lines = a.splitlines(keepends=True)
-    b_lines = b.splitlines(keepends=True)
+    a_lines = _splitlines_no_ff(a)
+    b_lines = _splitlines_no_ff(b)
     diff_lines = []
     for line in difflib.unified_diff(
         a_lines, b_lines, fromfile=a_name, tofile=b_name, n=5
diff --git a/src/blib2to3/pgen2/driver.py b/src/blib2to3/pgen2/driver.py
index e629843f8b9..be3984437a8 100644
--- a/src/blib2to3/pgen2/driver.py
+++ b/src/blib2to3/pgen2/driver.py
@@ -222,6 +222,8 @@ def _partially_consume_prefix(self, prefix: str, column: int) -> Tuple[str, str]
             elif char == "\n":
                 # unexpected empty line
                 current_column = 0
+            elif char == "\f":
+                current_column = 0
             else:
                 # indent is finished
                 wait_for_nl = True
diff --git a/tests/data/cases/preview_form_feeds.py b/tests/data/cases/preview_form_feeds.py
new file mode 100644
index 00000000000..2d8653a1f04
--- /dev/null
+++ b/tests/data/cases/preview_form_feeds.py
@@ -0,0 +1,225 @@
+# flags: --preview
+
+
+# Warning! This file contains form feeds (ASCII 0x0C, often represented by \f or ^L).
+# These may be invisible in your editor: ensure you can see them before making changes here.
+
+# There's one at the start that'll get stripped
+
+# Comment and statement processing is different enough that we'll test variations of both
+# contexts here
+
+#
+
+
+#
+
+
+#
+
+
+
+#
+
+
+
+#
+
+
+
+#
+
+
+#
+
+
+
+#
+
+#
+        
+#
+
+\
+#
+pass
+
+pass
+
+
+pass
+
+
+pass
+
+
+
+pass
+
+
+
+pass
+
+
+
+pass
+
+
+pass
+
+
+
+pass
+
+pass
+        
+pass
+
+
+# form feed after a dedent
+def foo():
+    pass
+
+pass
+
+
+# form feeds are prohibited inside blocks, or on a line with nonwhitespace
+defbar(a=1,b:bool=False):
+
+    
+    pass
+
+
+class Baz:
+
+    def __init__(self):
+        pass
+    
+    
+    def something(self):
+        pass
+    
+
+
+# 
+pass
+pass #
+a = 1
+#
+pass
+a = 1
+
+a = [
+
+]
+
+# as internal whitespace of a comment is allowed but why
+"form feed literal in a string is okay"
+
+# form feeds at the very end get removed.
+
+
+
+# output
+
+# Warning! This file contains form feeds (ASCII 0x0C, often represented by \f or ^L).
+# These may be invisible in your editor: ensure you can see them before making changes here.
+
+# There's one at the start that'll get stripped
+
+# Comment and statement processing is different enough that we'll test variations of both
+# contexts here
+
+#
+
+
+#
+
+
+#
+
+
+#
+
+
+#
+
+
+#
+
+
+#
+
+
+#
+
+#
+
+#
+
+#
+pass
+
+pass
+
+
+pass
+
+
+pass
+
+
+pass
+
+
+pass
+
+
+pass
+
+
+pass
+
+
+pass
+
+pass
+
+pass
+
+
+# form feed after a dedent
+def foo():
+    pass
+
+
+pass
+
+
+# form feeds are prohibited inside blocks, or on a line with nonwhitespace
+def bar(a=1, b: bool = False):
+    pass
+
+
+class Baz:
+    def __init__(self):
+        pass
+
+    def something(self):
+        pass
+
+
+#
+pass
+pass  #
+a = 1
+#
+pass
+a = 1
+
+a = []
+
+# as internal whitespace of a comment is allowed but why
+"form feed literal in a string is okay"
+
+# form feeds at the very end get removed.

From a8062983cd1f8ac8859297c870847906b10cf6a2 Mon Sep 17 00:00:00 2001
From: Yilei Yang <yileiyang@google.com>
Date: Mon, 20 Nov 2023 20:45:39 -0800
Subject: [PATCH 0944/1034] Disable the stability check with --line-ranges for
 now. (#4034)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 CHANGES.md                                    |  3 ++
 docs/usage_and_configuration/the_basics.md    |  6 ++++
 src/black/__init__.py                         |  9 ++++--
 .../data/cases/line_ranges_diff_edge_case.py  | 28 +++++++++++++++++++
 4 files changed, 44 insertions(+), 2 deletions(-)
 create mode 100644 tests/data/cases/line_ranges_diff_edge_case.py

diff --git a/CHANGES.md b/CHANGES.md
index 4c3fbf1afc8..18bab5131e6 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -21,6 +21,9 @@
 
 <!-- Changes to how Black can be configured -->
 
+- `--line-ranges` now skips _Black_'s internal stability check in `--safe` mode. This
+  avoids a crash on rare inputs that have many unformatted same-content lines. (#4034)
+
 ### Packaging
 
 - Upgrade to mypy 1.6.1 (#4049)
diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index 546fdc474e8..0c1a4d3b5a1 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -196,6 +196,12 @@ Example: `black --line-ranges=1-10 --line-ranges=21-30 test.py` will format line
 
 This option is mainly for editor integrations, such as "Format Selection".
 
+```{note}
+Due to [#4052](https://github.com/psf/black/issues/4052), `--line-ranges` might format
+extra lines outside of the ranges when ther are unformatted lines with the exact
+content. It also disables _Black_'s formatting stability check in `--safe` mode.
+```
+
 #### `--color` / `--no-color`
 
 Show (or do not show) colored diff. Only applies when `--diff` is given.
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 2455e8648fc..b33beeeeb23 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -1465,11 +1465,16 @@ def assert_stable(
     src: str, dst: str, mode: Mode, *, lines: Collection[Tuple[int, int]] = ()
 ) -> None:
     """Raise AssertionError if `dst` reformats differently the second time."""
+    if lines:
+        # Formatting specified lines requires `adjusted_lines` to map original lines
+        # to the formatted lines before re-formatting the previously formatted result.
+        # Due to less-ideal diff algorithm, some edge cases produce incorrect new line
+        # ranges. Hence for now, we skip the stable check.
+        # See https://github.com/psf/black/issues/4033 for context.
+        return
     # We shouldn't call format_str() here, because that formats the string
     # twice and may hide a bug where we bounce back and forth between two
     # versions.
-    if lines:
-        lines = adjusted_lines(lines, src, dst)
     newdst = _format_str_once(dst, mode=mode, lines=lines)
     if dst != newdst:
         log = dump_to_file(
diff --git a/tests/data/cases/line_ranges_diff_edge_case.py b/tests/data/cases/line_ranges_diff_edge_case.py
new file mode 100644
index 00000000000..f5cb2d0bb5f
--- /dev/null
+++ b/tests/data/cases/line_ranges_diff_edge_case.py
@@ -0,0 +1,28 @@
+# flags: --line-ranges=10-11
+# NOTE: If you need to modify this file, pay special attention to the --line-ranges=
+# flag above as it's formatting specifically these lines.
+
+# Reproducible example for https://github.com/psf/black/issues/4033.
+# This can be fixed in the future if we use a better diffing algorithm, or make Black
+# perform formatting in a single pass.
+
+print ( "format me" )
+print ( "format me" )
+print ( "format me" )
+print ( "format me" )
+print ( "format me" )
+
+# output
+# flags: --line-ranges=10-11
+# NOTE: If you need to modify this file, pay special attention to the --line-ranges=
+# flag above as it's formatting specifically these lines.
+
+# Reproducible example for https://github.com/psf/black/issues/4033.
+# This can be fixed in the future if we use a better diffing algorithm, or make Black
+# perform formatting in a single pass.
+
+print ( "format me" )
+print("format me")
+print("format me")
+print("format me")
+print("format me")

From be336bb67fb6c12667836f7fba4993f9be9c61dd Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Mon, 20 Nov 2023 22:33:16 -0800
Subject: [PATCH 0945/1034] Run lint job on Ubuntu only (#4061)

---
 .github/workflows/lint.yml | 6 +-----
 1 file changed, 1 insertion(+), 5 deletions(-)

diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index d1ad23bb2ab..9c7aca8f869 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -11,11 +11,7 @@ jobs:
       github.event_name == 'push' || github.event.pull_request.head.repo.full_name !=
       github.repository
 
-    runs-on: ${{ matrix.os }}
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [ubuntu-latest, macOS-latest, windows-latest]
+    runs-on: ubuntu-latest
 
     steps:
       - uses: actions/checkout@v4

From fb5e5d2be6367a0402a60da94f139dfb8943ed37 Mon Sep 17 00:00:00 2001
From: Henri Holopainen <henri.i.holopainen@gmail.com>
Date: Thu, 23 Nov 2023 05:11:49 +0200
Subject: [PATCH 0946/1034] Prefer more equal signs before a break when
 splitting chained assignments (#4010)

Fixes #4007
---
 CHANGES.md                                   |  2 +-
 src/black/linegen.py                         | 64 ++++++++++++++------
 src/black/lines.py                           |  5 ++
 tests/data/cases/preview_prefer_rhs_split.py | 21 +++++++
 4 files changed, 71 insertions(+), 21 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 18bab5131e6..6a8b97c75eb 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -12,8 +12,8 @@
 
 ### Preview style
 
+- Prefer more equal signs before a break when splitting chained assignments (#4010)
 - Standalone form feed characters at the module level are no longer removed (#4021)
-
 - Additional cases of immediately nested tuples, lists, and dictionaries are now
   indented less (#4012)
 
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 7fbbe290d7e..7152568783e 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -910,24 +910,32 @@ def _maybe_split_omitting_optional_parens(
         try:
             # The RHSResult Omitting Optional Parens.
             rhs_oop = _first_right_hand_split(line, omit=omit)
-            if not (
+            prefer_splitting_rhs_mode = (
                 Preview.prefer_splitting_right_hand_side_of_assignments in line.mode
-                # the split is right after `=`
-                and len(rhs.head.leaves) >= 2
-                and rhs.head.leaves[-2].type == token.EQUAL
-                # the left side of assignment contains brackets
-                and any(leaf.type in BRACKETS for leaf in rhs.head.leaves[:-1])
-                # the left side of assignment is short enough (the -1 is for the ending
-                # optional paren)
-                and is_line_short_enough(
-                    rhs.head, mode=replace(mode, line_length=mode.line_length - 1)
+            )
+            is_split_right_after_equal = (
+                len(rhs.head.leaves) >= 2 and rhs.head.leaves[-2].type == token.EQUAL
+            )
+            rhs_head_contains_brackets = any(
+                leaf.type in BRACKETS for leaf in rhs.head.leaves[:-1]
+            )
+            # the -1 is for the ending optional paren
+            rhs_head_short_enough = is_line_short_enough(
+                rhs.head, mode=replace(mode, line_length=mode.line_length - 1)
+            )
+            rhs_head_explode_blocked_by_magic_trailing_comma = (
+                rhs.head.magic_trailing_comma is None
+            )
+            if (
+                not (
+                    prefer_splitting_rhs_mode
+                    and is_split_right_after_equal
+                    and rhs_head_contains_brackets
+                    and rhs_head_short_enough
+                    and rhs_head_explode_blocked_by_magic_trailing_comma
                 )
-                # the left side of assignment won't explode further because of magic
-                # trailing comma
-                and rhs.head.magic_trailing_comma is None
-                # the split by omitting optional parens isn't preferred by some other
-                # reason
-                and not _prefer_split_rhs_oop(rhs_oop, mode)
+                # the omit optional parens split is preferred by some other reason
+                or _prefer_split_rhs_oop_over_rhs(rhs_oop, rhs, mode)
             ):
                 yield from _maybe_split_omitting_optional_parens(
                     rhs_oop, line, mode, features=features, omit=omit
@@ -935,8 +943,12 @@ def _maybe_split_omitting_optional_parens(
                 return
 
         except CannotSplit as e:
-            if not (
-                can_be_split(rhs.body) or is_line_short_enough(rhs.body, mode=mode)
+            # For chained assignments we want to use the previous successful split
+            if line.is_chained_assignment:
+                pass
+
+            elif not can_be_split(rhs.body) and not is_line_short_enough(
+                rhs.body, mode=mode
             ):
                 raise CannotSplit(
                     "Splitting failed, body is still too long and can't be split."
@@ -960,10 +972,22 @@ def _maybe_split_omitting_optional_parens(
             yield result
 
 
-def _prefer_split_rhs_oop(rhs_oop: RHSResult, mode: Mode) -> bool:
+def _prefer_split_rhs_oop_over_rhs(
+    rhs_oop: RHSResult, rhs: RHSResult, mode: Mode
+) -> bool:
     """
-    Returns whether we should prefer the result from a split omitting optional parens.
+    Returns whether we should prefer the result from a split omitting optional parens
+    (rhs_oop) over the original (rhs).
     """
+    # If we have multiple targets, we prefer more `=`s on the head vs pushing them to
+    # the body
+    rhs_head_equal_count = [leaf.type for leaf in rhs.head.leaves].count(token.EQUAL)
+    rhs_oop_head_equal_count = [leaf.type for leaf in rhs_oop.head.leaves].count(
+        token.EQUAL
+    )
+    if rhs_head_equal_count > 1 and rhs_head_equal_count > rhs_oop_head_equal_count:
+        return False
+
     has_closing_bracket_after_assign = False
     for leaf in reversed(rhs_oop.head.leaves):
         if leaf.type == token.EQUAL:
diff --git a/src/black/lines.py b/src/black/lines.py
index ec6145ff848..6e33ee57eab 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -209,6 +209,11 @@ def is_triple_quoted_string(self) -> bool:
             return True
         return False
 
+    @property
+    def is_chained_assignment(self) -> bool:
+        """Is the line a chained assignment"""
+        return [leaf.type for leaf in self.leaves].count(token.EQUAL) > 1
+
     @property
     def opens_block(self) -> bool:
         """Does this line open a new level of indentation."""
diff --git a/tests/data/cases/preview_prefer_rhs_split.py b/tests/data/cases/preview_prefer_rhs_split.py
index c732c33b53a..28d89c368c0 100644
--- a/tests/data/cases/preview_prefer_rhs_split.py
+++ b/tests/data/cases/preview_prefer_rhs_split.py
@@ -84,3 +84,24 @@
 ) or (
     isinstance(some_other_var, BaseClass) and table.something != table.some_other_thing
 )
+
+# Multiple targets
+a = b = (
+    ccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc
+)
+
+a = b = c = d = e = f = g = (
+    hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh
+) = i = j = (
+    kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk
+)
+
+a = (
+    bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
+) = c
+
+a = (
+    bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
+) = (
+    cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc
+) = ddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd

From 69d49c5a6fe064eb290dd6445745fdeb2643f54f Mon Sep 17 00:00:00 2001
From: Alex Waygood <Alex.Waygood@Gmail.com>
Date: Fri, 24 Nov 2023 14:19:54 +0000
Subject: [PATCH 0947/1034] Bump mypy to 1.7.1 (#4069)

---
 .pre-commit-config.yaml        | 2 +-
 CHANGES.md                     | 2 +-
 pyproject.toml                 | 4 ++--
 src/blib2to3/pgen2/tokenize.py | 7 ++-----
 4 files changed, 6 insertions(+), 9 deletions(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index c153746b621..2896489d724 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -39,7 +39,7 @@ repos:
         exclude: ^src/blib2to3/
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.6.1
+    rev: v1.7.1
     hooks:
       - id: mypy
         exclude: ^docs/conf.py
diff --git a/CHANGES.md b/CHANGES.md
index 6a8b97c75eb..f6fe69bac68 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -26,7 +26,7 @@
 
 ### Packaging
 
-- Upgrade to mypy 1.6.1 (#4049)
+- Upgrade to mypy 1.7.1 (#4049) (#4069)
 
 ### Parser
 
diff --git a/pyproject.toml b/pyproject.toml
index e63e0aea3ef..6b681e8226a 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -121,7 +121,7 @@ macos-max-compat = true
 enable-by-default = false
 dependencies = [
   "hatch-mypyc>=0.16.0",
-  "mypy==1.6.1",
+  "mypy==1.7.1",
   "click==8.1.3",  # avoid https://github.com/pallets/click/issues/2558
 ]
 require-runtime-dependencies = true
@@ -187,7 +187,7 @@ CC = "clang"
 build-frontend = { name = "build", args = ["--no-isolation"] }
 # Unfortunately, hatch doesn't respect MACOSX_DEPLOYMENT_TARGET
 before-build = [
-    "python -m pip install 'hatchling==1.18.0' hatch-vcs hatch-fancy-pypi-readme 'hatch-mypyc>=0.16.0' 'mypy==1.6.1' 'click==8.1.3'",
+    "python -m pip install 'hatchling==1.18.0' hatch-vcs hatch-fancy-pypi-readme 'hatch-mypyc>=0.16.0' 'mypy==1.7.1' 'click==8.1.3'",
     """sed -i '' -e "600,700s/'10_16'/os.environ['MACOSX_DEPLOYMENT_TARGET'].replace('.', '_')/" $(python -c 'import hatchling.builders.wheel as h; print(h.__file__)') """,
 ]
 
diff --git a/src/blib2to3/pgen2/tokenize.py b/src/blib2to3/pgen2/tokenize.py
index d0607f4b1e1..b04b18ba870 100644
--- a/src/blib2to3/pgen2/tokenize.py
+++ b/src/blib2to3/pgen2/tokenize.py
@@ -39,7 +39,6 @@
     Set,
     Tuple,
     Union,
-    cast,
 )
 
 from blib2to3.pgen2.grammar import Grammar
@@ -262,11 +261,9 @@ def add_whitespace(self, start: Coord) -> None:
     def untokenize(self, iterable: Iterable[TokenInfo]) -> str:
         for t in iterable:
             if len(t) == 2:
-                self.compat(cast(Tuple[int, str], t), iterable)
+                self.compat(t, iterable)
                 break
-            tok_type, token, start, end, line = cast(
-                Tuple[int, str, Coord, Coord, str], t
-            )
+            tok_type, token, start, end, line = t
             self.add_whitespace(start)
             self.tokens.append(token)
             self.prev_row, self.prev_col = end

From a0e270d0f246387202e676b25abbf7a02ddcbc71 Mon Sep 17 00:00:00 2001
From: Alex Waygood <Alex.Waygood@Gmail.com>
Date: Fri, 24 Nov 2023 18:05:59 +0000
Subject: [PATCH 0948/1034] Build mypycified wheels for Python 3.12 (#4070)

---
 .github/workflows/pypi_upload.yml | 2 +-
 CHANGES.md                        | 1 +
 pyproject.toml                    | 2 +-
 3 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/pypi_upload.yml b/.github/workflows/pypi_upload.yml
index 07273f09508..bbdcdf17a8f 100644
--- a/.github/workflows/pypi_upload.yml
+++ b/.github/workflows/pypi_upload.yml
@@ -73,7 +73,7 @@ jobs:
             | pyp 'json.dumps({"only": x, "os": "ubuntu-latest"})'
           } | pyp 'json.dumps(list(map(json.loads, lines)))' > /tmp/matrix
         env:
-          CIBW_BUILD: "cp38-* cp311-*"
+          CIBW_BUILD: "cp38-* cp312-*"
           CIBW_ARCHS_LINUX: x86_64
       - id: set-matrix
         run: echo "include=$(cat /tmp/matrix)" | tee -a $GITHUB_OUTPUT
diff --git a/CHANGES.md b/CHANGES.md
index f6fe69bac68..e9ffd6bb9f5 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -27,6 +27,7 @@
 ### Packaging
 
 - Upgrade to mypy 1.7.1 (#4049) (#4069)
+- Faster compiled wheels are now available for CPython 3.12 (#4070)
 
 ### Parser
 
diff --git a/pyproject.toml b/pyproject.toml
index 6b681e8226a..1098412981a 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -150,7 +150,7 @@ build-verbosity = 1
 # - Architecture (64-bit only): amd64 / x86_64, universal2, and arm64
 # - OS: Linux (no musl), Windows, and macOS
 build = "cp3*"
-skip = ["*-manylinux_i686", "*-musllinux_*", "*-win32", "pp*", "cp312-*"]
+skip = ["*-manylinux_i686", "*-musllinux_*", "*-win32", "pp*"]
 # This is the bare minimum needed to run the test suite. Pulling in the full
 # test_requirements.txt would download a bunch of other packages not necessary
 # here and would slow down the testing step a fair bit.

From 66ec056e39da957d3c82da5b7a86ef228606cfe6 Mon Sep 17 00:00:00 2001
From: exag <hukuti145@gmail.com>
Date: Mon, 4 Dec 2023 14:47:30 +0900
Subject: [PATCH 0949/1034] Fix minor typos in docstrings (#4085)

---
 src/black/numerics.py | 2 +-
 src/black/ranges.py   | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/black/numerics.py b/src/black/numerics.py
index 67ac8595fcc..3040de06fde 100644
--- a/src/black/numerics.py
+++ b/src/black/numerics.py
@@ -14,7 +14,7 @@ def format_hex(text: str) -> str:
 
 
 def format_scientific_notation(text: str) -> str:
-    """Formats a numeric string utilizing scentific notation"""
+    """Formats a numeric string utilizing scientific notation"""
     before, after = text.split("e")
     sign = ""
     if after.startswith("-"):
diff --git a/src/black/ranges.py b/src/black/ranges.py
index b0c312e6274..59e19242d47 100644
--- a/src/black/ranges.py
+++ b/src/black/ranges.py
@@ -172,7 +172,7 @@ class _TopLevelStatementsVisitor(Visitor[None]):
     A node visitor that converts unchanged top-level statements to
     STANDALONE_COMMENT.
 
-    This is used in addition to _convert_unchanged_lines_by_flatterning, to
+    This is used in addition to _convert_unchanged_line_by_line, to
     speed up formatting when there are unchanged top-level
     classes/functions/statements.
     """
@@ -302,7 +302,7 @@ def _convert_node_to_standalone_comment(node: LN) -> None:
     index = node.remove()
     if index is not None:
         # Remove the '\n', as STANDALONE_COMMENT will have '\n' appended when
-        # genearting the formatted code.
+        # generating the formatted code.
         value = str(node)[:-1]
         parent.insert_child(
             index,

From 3416b2c82d51f27ce55c31ef0bfe4a9e21816611 Mon Sep 17 00:00:00 2001
From: Riyazuddin Khan <riyaz489.rk@gmail.com>
Date: Mon, 4 Dec 2023 23:40:03 +0530
Subject: [PATCH 0950/1034] Fix:  --line-ranges dedents a # fmt: off in the
 middle of a decorator (#4084)

Fixes #4068
---
 CHANGES.md                                    |  3 ++-
 src/black/__init__.py                         |  2 +-
 src/black/comments.py                         | 23 ++++++++++++++----
 .../cases/line_ranges_fmt_off_decorator.py    | 24 +++++++++++++++++--
 4 files changed, 44 insertions(+), 8 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index e9ffd6bb9f5..f17cd7fdc9d 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -8,7 +8,8 @@
 
 ### Stable style
 
-<!-- Changes that affect Black's stable style -->
+- Fix bug where `# fmt: off` automatically dedents when used with the `--line-ranges`
+  option, even when it is not within the specified line range. (#4084)
 
 ### Preview style
 
diff --git a/src/black/__init__.py b/src/black/__init__.py
index b33beeeeb23..04f6d8c58de 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -1180,7 +1180,7 @@ def _format_str_once(
         for feature in {Feature.PARENTHESIZED_CONTEXT_MANAGERS}
         if supports_feature(versions, feature)
     }
-    normalize_fmt_off(src_node, mode)
+    normalize_fmt_off(src_node, mode, lines)
     if lines:
         # This should be called after normalize_fmt_off.
         convert_unchanged_lines(src_node, lines)
diff --git a/src/black/comments.py b/src/black/comments.py
index 8a0e925fdc0..25413121199 100644
--- a/src/black/comments.py
+++ b/src/black/comments.py
@@ -1,7 +1,7 @@
 import re
 from dataclasses import dataclass
 from functools import lru_cache
-from typing import Final, Iterator, List, Optional, Union
+from typing import Collection, Final, Iterator, List, Optional, Tuple, Union
 
 from black.mode import Mode, Preview
 from black.nodes import (
@@ -161,14 +161,18 @@ def make_comment(content: str) -> str:
     return "#" + content
 
 
-def normalize_fmt_off(node: Node, mode: Mode) -> None:
+def normalize_fmt_off(
+    node: Node, mode: Mode, lines: Collection[Tuple[int, int]]
+) -> None:
     """Convert content between `# fmt: off`/`# fmt: on` into standalone comments."""
     try_again = True
     while try_again:
-        try_again = convert_one_fmt_off_pair(node, mode)
+        try_again = convert_one_fmt_off_pair(node, mode, lines)
 
 
-def convert_one_fmt_off_pair(node: Node, mode: Mode) -> bool:
+def convert_one_fmt_off_pair(
+    node: Node, mode: Mode, lines: Collection[Tuple[int, int]]
+) -> bool:
     """Convert content of a single `# fmt: off`/`# fmt: on` into a standalone comment.
 
     Returns True if a pair was converted.
@@ -213,7 +217,18 @@ def convert_one_fmt_off_pair(node: Node, mode: Mode) -> bool:
                     prefix[:previous_consumed] + "\n" * comment.newlines
                 )
             hidden_value = "".join(str(n) for n in ignored_nodes)
+            comment_lineno = leaf.lineno - comment.newlines
             if comment.value in FMT_OFF:
+                fmt_off_prefix = ""
+                if len(lines) > 0 and not any(
+                    comment_lineno >= line[0] and comment_lineno <= line[1]
+                    for line in lines
+                ):
+                    # keeping indentation of comment by preserving original whitespaces.
+                    fmt_off_prefix = prefix.split(comment.value)[0]
+                    if "\n" in fmt_off_prefix:
+                        fmt_off_prefix = fmt_off_prefix.split("\n")[-1]
+                standalone_comment_prefix += fmt_off_prefix
                 hidden_value = comment.value + "\n" + hidden_value
             if _contains_fmt_skip_comment(comment.value, mode):
                 hidden_value += "  " + comment.value
diff --git a/tests/data/cases/line_ranges_fmt_off_decorator.py b/tests/data/cases/line_ranges_fmt_off_decorator.py
index 14aa1dda02d..065bf4328d7 100644
--- a/tests/data/cases/line_ranges_fmt_off_decorator.py
+++ b/tests/data/cases/line_ranges_fmt_off_decorator.py
@@ -1,4 +1,4 @@
-# flags: --line-ranges=12-12
+# flags: --line-ranges=12-12 --line-ranges=21-21
 # NOTE: If you need to modify this file, pay special attention to the --line-ranges=
 # flag above as it's formatting specifically these lines.
 
@@ -11,9 +11,19 @@ class MyClass:
     def method():
         print   ( "str" )
 
+    @decor(
+        a=1,
+        # fmt: off
+        b=(2,   3),
+        # fmt: on
+    )
+    def func():
+          pass
+
+
 # output
 
-# flags: --line-ranges=12-12
+# flags: --line-ranges=12-12 --line-ranges=21-21
 # NOTE: If you need to modify this file, pay special attention to the --line-ranges=
 # flag above as it's formatting specifically these lines.
 
@@ -25,3 +35,13 @@ class MyClass:
     # fmt: on
     def method():
         print("str")
+
+    @decor(
+        a=1,
+        # fmt: off
+        b=(2,   3),
+        # fmt: on
+    )
+    def func():
+        pass
+

From 50d5756e8e63b17e4523f096f312011273ce640f Mon Sep 17 00:00:00 2001
From: John Litborn <11260241+jakkdl@users.noreply.github.com>
Date: Tue, 5 Dec 2023 19:19:24 +0100
Subject: [PATCH 0951/1034] fix crash in preview mode with --line-length=1
 (#4086)

---
 CHANGES.md                                               | 1 +
 src/black/linegen.py                                     | 2 +-
 .../return_annotation_brackets_crash_line_length_1.py    | 9 +++++++++
 3 files changed, 11 insertions(+), 1 deletion(-)
 create mode 100644 tests/data/cases/return_annotation_brackets_crash_line_length_1.py

diff --git a/CHANGES.md b/CHANGES.md
index f17cd7fdc9d..8f0b75e7f10 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -17,6 +17,7 @@
 - Standalone form feed characters at the module level are no longer removed (#4021)
 - Additional cases of immediately nested tuples, lists, and dictionaries are now
   indented less (#4012)
+- Fix crash in preview mode when using a short `--line-length` (#4086)
 
 ### Configuration
 
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 7152568783e..073672a5ae7 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -744,7 +744,7 @@ def left_hand_split(
             if leaf.type in OPENING_BRACKETS:
                 matching_bracket = leaf
                 current_leaves = body_leaves
-    if not matching_bracket:
+    if not matching_bracket or not tail_leaves:
         raise CannotSplit("No brackets found")
 
     head = bracket_split_build_line(
diff --git a/tests/data/cases/return_annotation_brackets_crash_line_length_1.py b/tests/data/cases/return_annotation_brackets_crash_line_length_1.py
new file mode 100644
index 00000000000..9d96b4ab97a
--- /dev/null
+++ b/tests/data/cases/return_annotation_brackets_crash_line_length_1.py
@@ -0,0 +1,9 @@
+# flags: --preview --minimum-version=3.10 --line-length=1
+
+def foo() -> tuple[int, int,]:
+    ...
+# output
+def foo() -> tuple[
+    int,
+    int,
+]: ...

From e4ae213f06050e7f76ebcf01578c002e412dafdc Mon Sep 17 00:00:00 2001
From: John Litborn <11260241+jakkdl@users.noreply.github.com>
Date: Wed, 6 Dec 2023 16:17:33 +0100
Subject: [PATCH 0952/1034] test preview cases with line-length 1 unless
 explicitly skipped (#4087)

* Add new flag for tests, --no-preview-line-length-1, to be used for test cases known to not work in preview mode with line-length=1. Also split out the problematic cases in three cases to separate files. Removed now redundant file which explicitly tested preview annotations with line-length=1

* mode.preview -> preview_mode, mark pep_572_remove_parens as failing with ll1
---
 tests/data/cases/comment_type_hint.py         |   3 +
 tests/data/cases/comments2.py                 |   4 -
 tests/data/cases/fmtskip2.py                  |   5 +-
 tests/data/cases/pep_572_remove_parens.py     |   2 +-
 ..._parens_with_braces_and_square_brackets.py |  96 ----------------
 ..._with_braces_and_square_brackets_no_ll1.py | 106 ++++++++++++++++++
 ...annotation_brackets_crash_line_length_1.py |   9 --
 tests/test_format.py                          |   2 +
 tests/util.py                                 |  54 ++++++---
 9 files changed, 154 insertions(+), 127 deletions(-)
 create mode 100644 tests/data/cases/comment_type_hint.py
 create mode 100644 tests/data/cases/preview_hug_parens_with_braces_and_square_brackets_no_ll1.py
 delete mode 100644 tests/data/cases/return_annotation_brackets_crash_line_length_1.py

diff --git a/tests/data/cases/comment_type_hint.py b/tests/data/cases/comment_type_hint.py
new file mode 100644
index 00000000000..2992da88d90
--- /dev/null
+++ b/tests/data/cases/comment_type_hint.py
@@ -0,0 +1,3 @@
+# flags: --no-preview-line-length-1
+# split out from comments2 as it does not work with line-length=1, losing the comment
+a = "type comment with trailing space"  # type: str
diff --git a/tests/data/cases/comments2.py b/tests/data/cases/comments2.py
index 1487dc4b6e2..261c5e9f0a0 100644
--- a/tests/data/cases/comments2.py
+++ b/tests/data/cases/comments2.py
@@ -155,8 +155,6 @@ def _init_host(self, parsed) -> None:
             pass
 
 
-a = "type comment with trailing space"  # type: str   
-
 #######################
 ### SECTION COMMENT ###
 #######################
@@ -335,8 +333,6 @@ def _init_host(self, parsed) -> None:
             pass
 
 
-a = "type comment with trailing space"  # type: str
-
 #######################
 ### SECTION COMMENT ###
 #######################
diff --git a/tests/data/cases/fmtskip2.py b/tests/data/cases/fmtskip2.py
index e6248117aa9..0189d4e642d 100644
--- a/tests/data/cases/fmtskip2.py
+++ b/tests/data/cases/fmtskip2.py
@@ -1,9 +1,12 @@
+# flags: --no-preview-line-length-1
+# l2 loses the comment with line-length=1 in preview mode
 l1 = ["This list should be broken up", "into multiple lines", "because it is way too long"]
 l2 = ["But this list shouldn't", "even though it also has", "way too many characters in it"]  # fmt: skip
 l3 = ["I have", "trailing comma", "so I should be braked",]
 
 # output
 
+# l2 loses the comment with line-length=1 in preview mode
 l1 = [
     "This list should be broken up",
     "into multiple lines",
@@ -14,4 +17,4 @@
     "I have",
     "trailing comma",
     "so I should be braked",
-]
\ No newline at end of file
+]
diff --git a/tests/data/cases/pep_572_remove_parens.py b/tests/data/cases/pep_572_remove_parens.py
index 24f1ac29168..88774d81649 100644
--- a/tests/data/cases/pep_572_remove_parens.py
+++ b/tests/data/cases/pep_572_remove_parens.py
@@ -1,4 +1,4 @@
-# flags: --minimum-version=3.8
+# flags: --minimum-version=3.8 --no-preview-line-length-1
 if (foo := 0):
     pass
 
diff --git a/tests/data/cases/preview_hug_parens_with_braces_and_square_brackets.py b/tests/data/cases/preview_hug_parens_with_braces_and_square_brackets.py
index 9e5c9eb8546..47a6a0bcae6 100644
--- a/tests/data/cases/preview_hug_parens_with_braces_and_square_brackets.py
+++ b/tests/data/cases/preview_hug_parens_with_braces_and_square_brackets.py
@@ -125,23 +125,6 @@ def foo_square_brackets(request):
 func([x for x in "long line long line long line long line long line long line long line"])
 func([x for x in [x for x in "long line long line long line long line long line long line long line"]])
 
-func({"short line"})
-func({"long line", "long long line", "long long long line", "long long long long line", "long long long long long line"})
-func({{"long line", "long long line", "long long long line", "long long long long line", "long long long long long line"}})
-func(("long line", "long long line", "long long long line", "long long long long line", "long long long long long line"))
-func((("long line", "long long line", "long long long line", "long long long long line", "long long long long long line")))
-func([["long line", "long long line", "long long long line", "long long long long line", "long long long long long line"]])
-
-# Do not hug if the argument fits on a single line.
-func({"fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit line"})
-func(("fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit line"))
-func(["fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit line"])
-func(**{"fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit---"})
-func(*("fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit----"))
-array = [{"fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit line"}]
-array = [("fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit line")]
-array = [["fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit line"]]
-
 foooooooooooooooooooo(
     [{c: n + 1 for c in range(256)} for n in range(100)] + [{}], {size}
 )
@@ -151,14 +134,11 @@ def foo_square_brackets(request):
 )
 
 nested_mapping = {"key": [{"a very long key 1": "with a very long value", "a very long key 2": "with a very long value"}]}
-nested_array = [[["long line", "long long line", "long long long line", "long long long long line", "long long long long long line"]]]
 explicit_exploding = [[["short", "line",],],]
 single_item_do_not_explode = Context({
     "version": get_docs_version(),
 })
 
-foo(*["long long long long long line", "long long long long long line", "long long long long long line"])
-
 foo(*[str(i) for i in range(100000000000000000000000000000000000000000000000000000000000)])
 
 foo(
@@ -310,69 +290,6 @@ def foo_square_brackets(request):
     ]
 ])
 
-func({"short line"})
-func({
-    "long line",
-    "long long line",
-    "long long long line",
-    "long long long long line",
-    "long long long long long line",
-})
-func({{
-    "long line",
-    "long long line",
-    "long long long line",
-    "long long long long line",
-    "long long long long long line",
-}})
-func((
-    "long line",
-    "long long line",
-    "long long long line",
-    "long long long long line",
-    "long long long long long line",
-))
-func(((
-    "long line",
-    "long long line",
-    "long long long line",
-    "long long long long line",
-    "long long long long long line",
-)))
-func([[
-    "long line",
-    "long long line",
-    "long long long line",
-    "long long long long line",
-    "long long long long long line",
-]])
-
-# Do not hug if the argument fits on a single line.
-func(
-    {"fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit line"}
-)
-func(
-    ("fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit line")
-)
-func(
-    ["fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit line"]
-)
-func(
-    **{"fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit---"}
-)
-func(
-    *("fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit----")
-)
-array = [
-    {"fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit line"}
-]
-array = [
-    ("fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit line")
-]
-array = [
-    ["fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit line"]
-]
-
 foooooooooooooooooooo(
     [{c: n + 1 for c in range(256)} for n in range(100)] + [{}], {size}
 )
@@ -387,13 +304,6 @@ def foo_square_brackets(request):
         "a very long key 2": "with a very long value",
     }]
 }
-nested_array = [[[
-    "long line",
-    "long long line",
-    "long long long line",
-    "long long long long line",
-    "long long long long long line",
-]]]
 explicit_exploding = [
     [
         [
@@ -406,12 +316,6 @@ def foo_square_brackets(request):
     "version": get_docs_version(),
 })
 
-foo(*[
-    "long long long long long line",
-    "long long long long long line",
-    "long long long long long line",
-])
-
 foo(*[
     str(i) for i in range(100000000000000000000000000000000000000000000000000000000000)
 ])
diff --git a/tests/data/cases/preview_hug_parens_with_braces_and_square_brackets_no_ll1.py b/tests/data/cases/preview_hug_parens_with_braces_and_square_brackets_no_ll1.py
new file mode 100644
index 00000000000..fdebdf69c20
--- /dev/null
+++ b/tests/data/cases/preview_hug_parens_with_braces_and_square_brackets_no_ll1.py
@@ -0,0 +1,106 @@
+# flags: --preview --no-preview-line-length-1
+# split out from preview_hug_parens_with_brackes_and_square_brackets, as it produces
+# different code on the second pass with line-length 1 in many cases.
+# Seems to be about whether the last string in a sequence gets wrapped in parens or not.
+foo(*["long long long long long line", "long long long long long line", "long long long long long line"])
+func({"short line"})
+func({"long line", "long long line", "long long long line", "long long long long line", "long long long long long line"})
+func({{"long line", "long long line", "long long long line", "long long long long line", "long long long long long line"}})
+func(("long line", "long long line", "long long long line", "long long long long line", "long long long long long line"))
+func((("long line", "long long line", "long long long line", "long long long long line", "long long long long long line")))
+func([["long line", "long long line", "long long long line", "long long long long line", "long long long long long line"]])
+
+
+# Do not hug if the argument fits on a single line.
+func({"fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit line"})
+func(("fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit line"))
+func(["fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit line"])
+func(**{"fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit---"})
+func(*("fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit----"))
+array = [{"fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit line"}]
+array = [("fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit line")]
+array = [["fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit line"]]
+
+nested_array = [[["long line", "long long line", "long long long line", "long long long long line", "long long long long long line"]]]
+
+# output
+
+# split out from preview_hug_parens_with_brackes_and_square_brackets, as it produces
+# different code on the second pass with line-length 1 in many cases.
+# Seems to be about whether the last string in a sequence gets wrapped in parens or not.
+foo(*[
+    "long long long long long line",
+    "long long long long long line",
+    "long long long long long line",
+])
+func({"short line"})
+func({
+    "long line",
+    "long long line",
+    "long long long line",
+    "long long long long line",
+    "long long long long long line",
+})
+func({{
+    "long line",
+    "long long line",
+    "long long long line",
+    "long long long long line",
+    "long long long long long line",
+}})
+func((
+    "long line",
+    "long long line",
+    "long long long line",
+    "long long long long line",
+    "long long long long long line",
+))
+func(((
+    "long line",
+    "long long line",
+    "long long long line",
+    "long long long long line",
+    "long long long long long line",
+)))
+func([[
+    "long line",
+    "long long line",
+    "long long long line",
+    "long long long long line",
+    "long long long long long line",
+]])
+
+
+# Do not hug if the argument fits on a single line.
+func(
+    {"fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit line"}
+)
+func(
+    ("fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit line")
+)
+func(
+    ["fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit line"]
+)
+func(
+    **{"fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit---"}
+)
+func(
+    *("fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit----")
+)
+array = [
+    {"fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit line"}
+]
+array = [
+    ("fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit line")
+]
+array = [
+    ["fit line", "fit line", "fit line", "fit line", "fit line", "fit line", "fit line"]
+]
+
+nested_array = [[[
+    "long line",
+    "long long line",
+    "long long long line",
+    "long long long long line",
+    "long long long long long line",
+]]]
diff --git a/tests/data/cases/return_annotation_brackets_crash_line_length_1.py b/tests/data/cases/return_annotation_brackets_crash_line_length_1.py
deleted file mode 100644
index 9d96b4ab97a..00000000000
--- a/tests/data/cases/return_annotation_brackets_crash_line_length_1.py
+++ /dev/null
@@ -1,9 +0,0 @@
-# flags: --preview --minimum-version=3.10 --line-length=1
-
-def foo() -> tuple[int, int,]:
-    ...
-# output
-def foo() -> tuple[
-    int,
-    int,
-]: ...
diff --git a/tests/test_format.py b/tests/test_format.py
index 6c2eca8c618..9162c585c08 100644
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -30,6 +30,7 @@ def check_file(subdir: str, filename: str, *, data: bool = True) -> None:
         fast=args.fast,
         minimum_version=args.minimum_version,
         lines=args.lines,
+        no_preview_line_length_1=args.no_preview_line_length_1,
     )
     if args.minimum_version is not None:
         major, minor = args.minimum_version
@@ -42,6 +43,7 @@ def check_file(subdir: str, filename: str, *, data: bool = True) -> None:
             fast=args.fast,
             minimum_version=args.minimum_version,
             lines=args.lines,
+            no_preview_line_length_1=args.no_preview_line_length_1,
         )
 
 
diff --git a/tests/util.py b/tests/util.py
index c8699d335ab..9ea30e62fe3 100644
--- a/tests/util.py
+++ b/tests/util.py
@@ -46,6 +46,7 @@ class TestCaseArgs:
     fast: bool = False
     minimum_version: Optional[Tuple[int, int]] = None
     lines: Collection[Tuple[int, int]] = ()
+    no_preview_line_length_1: bool = False
 
 
 def _assert_format_equal(expected: str, actual: str) -> None:
@@ -96,6 +97,7 @@ def assert_format(
     fast: bool = False,
     minimum_version: Optional[Tuple[int, int]] = None,
     lines: Collection[Tuple[int, int]] = (),
+    no_preview_line_length_1: bool = False,
 ) -> None:
     """Convenience function to check that Black formats as expected.
 
@@ -124,21 +126,28 @@ def assert_format(
             f"Black crashed formatting this case in {text} mode."
         ) from e
     # Similarly, setting line length to 1 is a good way to catch
-    # stability bugs. But only in non-preview mode because preview mode
-    # currently has a lot of line length 1 bugs.
-    try:
-        _assert_format_inner(
-            source,
-            None,
-            replace(mode, preview=False, line_length=1),
-            fast=fast,
-            minimum_version=minimum_version,
-            lines=lines,
-        )
-    except Exception as e:
-        raise FormatFailure(
-            "Black crashed formatting this case with line-length set to 1."
-        ) from e
+    # stability bugs. Some tests are known to be broken in preview mode with line length
+    # of 1 though, and have marked that with a flag --no-preview-line-length-1
+    preview_modes = [False]
+    if not no_preview_line_length_1:
+        preview_modes.append(True)
+
+    for preview_mode in preview_modes:
+
+        try:
+            _assert_format_inner(
+                source,
+                None,
+                replace(mode, preview=preview_mode, line_length=1),
+                fast=fast,
+                minimum_version=minimum_version,
+                lines=lines,
+            )
+        except Exception as e:
+            text = "preview" if preview_mode else "non-preview"
+            raise FormatFailure(
+                f"Black crashed formatting this case in {text} mode with line-length=1."
+            ) from e
 
 
 def _assert_format_inner(
@@ -246,6 +255,15 @@ def get_flags_parser() -> argparse.ArgumentParser:
         ),
     )
     parser.add_argument("--line-ranges", action="append")
+    parser.add_argument(
+        "--no-preview-line-length-1",
+        default=False,
+        action="store_true",
+        help=(
+            "Don't run in preview mode with --line-length=1, as that's known to cause a"
+            " crash"
+        ),
+    )
     return parser
 
 
@@ -266,7 +284,11 @@ def parse_mode(flags_line: str) -> TestCaseArgs:
     else:
         lines = []
     return TestCaseArgs(
-        mode=mode, fast=args.fast, minimum_version=args.minimum_version, lines=lines
+        mode=mode,
+        fast=args.fast,
+        minimum_version=args.minimum_version,
+        lines=lines,
+        no_preview_line_length_1=args.no_preview_line_length_1,
     )
 
 

From 50e287cecea41ee32bd66ab1eee4827f6b8312ce Mon Sep 17 00:00:00 2001
From: cobalt <61329810+RedGuy12@users.noreply.github.com>
Date: Thu, 7 Dec 2023 10:38:57 -0600
Subject: [PATCH 0953/1034] docs: Clarify include/exclude documentation (#4072)

---
 docs/usage_and_configuration/the_basics.md | 22 +++++++--------
 src/black/__init__.py                      | 33 +++++++++++-----------
 2 files changed, 28 insertions(+), 27 deletions(-)

diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index 0c1a4d3b5a1..3739bcaefa1 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -241,24 +241,17 @@ Because of our [stability policy](../the_black_code_style/index.md), this will g
 stable formatting, but still allow you to take advantage of improvements that do not
 affect formatting.
 
-#### `--include`
-
-A regular expression that matches files and directories that should be included on
-recursive searches. An empty value means all files are included regardless of the name.
-Use forward slashes for directories on all platforms (Windows, too). Exclusions are
-calculated first, inclusions later.
-
 #### `--exclude`
 
 A regular expression that matches files and directories that should be excluded on
 recursive searches. An empty value means no paths are excluded. Use forward slashes for
-directories on all platforms (Windows, too). Exclusions are calculated first, inclusions
-later.
+directories on all platforms (Windows, too). By default, Black also ignores all paths
+listed in `.gitignore`. Changing this value will override all default exclusions.
 
 #### `--extend-exclude`
 
-Like `--exclude`, but adds additional files and directories on top of the excluded ones.
-Useful if you simply want to add to the default.
+Like `--exclude`, but adds additional files and directories on top of the default values
+instead of overriding them.
 
 #### `--force-exclude`
 
@@ -271,6 +264,13 @@ programmatically on changed files, such as in a pre-commit hook or editor plugin
 The name of the file when passing it through stdin. Useful to make sure Black will
 respect the `--force-exclude` option on some editors that rely on using stdin.
 
+#### `--include`
+
+A regular expression that matches files and directories that should be included on
+recursive searches. An empty value means all files are included regardless of the name.
+Use forward slashes for directories on all platforms (Windows, too). Overrides all
+exclusions, including from `.gitignore` and command line options.
+
 #### `-W`, `--workers`
 
 When _Black_ formats multiple files, it may use a process pool to speed up formatting.
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 04f6d8c58de..e7dac895a6a 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -344,19 +344,6 @@ def validate_regex(
         " either a major version number or an exact version."
     ),
 )
-@click.option(
-    "--include",
-    type=str,
-    default=DEFAULT_INCLUDES,
-    callback=validate_regex,
-    help=(
-        "A regular expression that matches files and directories that should be"
-        " included on recursive searches. An empty value means all files are included"
-        " regardless of the name. Use forward slashes for directories on all platforms"
-        " (Windows, too). Exclusions are calculated first, inclusions later."
-    ),
-    show_default=True,
-)
 @click.option(
     "--exclude",
     type=str,
@@ -365,8 +352,8 @@ def validate_regex(
         "A regular expression that matches files and directories that should be"
         " excluded on recursive searches. An empty value means no paths are excluded."
         " Use forward slashes for directories on all platforms (Windows, too)."
-        " Exclusions are calculated first, inclusions later. [default:"
-        f" {DEFAULT_EXCLUDES}]"
+        " By default, Black also ignores all paths listed in .gitignore. Changing this"
+        f" value will override all default exclusions. [default: {DEFAULT_EXCLUDES}]"
     ),
     show_default=False,
 )
@@ -376,7 +363,7 @@ def validate_regex(
     callback=validate_regex,
     help=(
         "Like --exclude, but adds additional files and directories on top of the"
-        " excluded ones. (Useful if you simply want to add to the default)"
+        " default values instead of overriding them."
     ),
 )
 @click.option(
@@ -398,6 +385,20 @@ def validate_regex(
         "editors that rely on using stdin."
     ),
 )
+@click.option(
+    "--include",
+    type=str,
+    default=DEFAULT_INCLUDES,
+    callback=validate_regex,
+    help=(
+        "A regular expression that matches files and directories that should be"
+        " included on recursive searches. An empty value means all files are included"
+        " regardless of the name. Use forward slashes for directories on all platforms"
+        " (Windows, too). Overrides all exclusions, including from .gitignore and"
+        " command line options."
+    ),
+    show_default=True,
+)
 @click.option(
     "-W",
     "--workers",

From 432d9050c3d1e35a36ffc97d4a9e0e0c9e5e4ecc Mon Sep 17 00:00:00 2001
From: cobalt <61329810+RedGuy12@users.noreply.github.com>
Date: Thu, 7 Dec 2023 11:32:06 -0600
Subject: [PATCH 0954/1034] docs: Unify option descriptions between `--help`
 and `the_basics.md` (#4076)

---
 docs/usage_and_configuration/the_basics.md | 45 +++++++------
 src/black/__init__.py                      | 75 +++++++++++++---------
 2 files changed, 69 insertions(+), 51 deletions(-)

diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index 3739bcaefa1..73c0d1323e3 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -35,6 +35,10 @@ are deliberately limited and rarely added.
 Note that all command-line options listed above can also be configured using a
 `pyproject.toml` file (more on that below).
 
+#### `-h`, `--help`
+
+Show available command-line options and exit.
+
 #### `-c`, `--code`
 
 Format the code passed in as a string.
@@ -109,6 +113,10 @@ useful when piping source on standard input.
 When processing Jupyter Notebooks, add the given magic to the list of known python-
 magics. Useful for formatting cells with custom python magics.
 
+#### `-x, --skip-source-first-line`
+
+Skip the first line of the source code.
+
 #### `-S, --skip-string-normalization`
 
 By default, _Black_ uses double quotes for all strings and normalizes string prefixes,
@@ -132,7 +140,7 @@ functionality in the next major release. Read more about
 
 #### `--check`
 
-Passing `--check` will make _Black_ exit with:
+Don't write the files back, just return the status. _Black_ will exit with:
 
 - code 0 if nothing would change;
 - code 1 if some files would be reformatted; or
@@ -162,8 +170,8 @@ $ echo $?
 
 #### `--diff`
 
-Passing `--diff` will make _Black_ print out diffs that indicate what changes _Black_
-would've made. They are printed to stdout so capturing them is simple.
+Don't write the files back, just output a diff to indicate what changes _Black_ would've
+made. They are printed to stdout so capturing them is simple.
 
 If you'd like colored diffs, you can enable them with `--color`.
 
@@ -179,6 +187,10 @@ All done! ✨ 🍰 ✨
 1 file would be reformatted.
 ```
 
+#### `--color` / `--no-color`
+
+Show (or do not show) colored diff. Only applies when `--diff` is given.
+
 ### `--line-ranges`
 
 When specified, _Black_ will try its best to only format these lines.
@@ -202,10 +214,6 @@ extra lines outside of the ranges when ther are unformatted lines with the exact
 content. It also disables _Black_'s formatting stability check in `--safe` mode.
 ```
 
-#### `--color` / `--no-color`
-
-Show (or do not show) colored diff. Only applies when `--diff` is given.
-
 #### `--fast` / `--safe`
 
 By default, _Black_ performs [an AST safety check](labels/ast-changes) after formatting
@@ -256,7 +264,7 @@ instead of overriding them.
 #### `--force-exclude`
 
 Like `--exclude`, but files and directories matching this regex will be excluded even
-when they are passed explicitly as arguments. This is useful when invoking _Black_
+when they are passed explicitly as arguments. This is useful when invoking Black
 programmatically on changed files, such as in a pre-commit hook or editor plugin.
 
 #### `--stdin-filename`
@@ -275,12 +283,12 @@ exclusions, including from `.gitignore` and command line options.
 
 When _Black_ formats multiple files, it may use a process pool to speed up formatting.
 This option controls the number of parallel workers. This can also be specified via the
-`BLACK_NUM_WORKERS` environment variable.
+`BLACK_NUM_WORKERS` environment variable. Defaults to the number of CPUs in the system.
 
 #### `-q`, `--quiet`
 
-Passing `-q` / `--quiet` will cause _Black_ to stop emitting all non-critical output.
-Error messages will still be emitted (which can silenced by `2>/dev/null`).
+Stop emitting all non-critical output. Error messages will still be emitted (which can
+silenced by `2>/dev/null`).
 
 ```console
 $ black src/ -q
@@ -289,9 +297,9 @@ error: cannot format src/black_primer/cli.py: Cannot parse: 5:6: mport asyncio
 
 #### `-v`, `--verbose`
 
-Passing `-v` / `--verbose` will cause _Black_ to also emit messages about files that
-were not changed or were ignored due to exclusion patterns. If _Black_ is using a
-configuration file, a blue message detailing which one it is using will be emitted.
+Emit messages about files that were not changed or were ignored due to exclusion
+patterns. If _Black_ is using a configuration file, a message detailing which one it is
+using will be emitted.
 
 ```console
 $ black src/ -v
@@ -321,10 +329,6 @@ black, 23.11.0
 Read configuration options from a configuration file. See
 [below](#configuration-via-a-file) for more details on the configuration file.
 
-#### `-h`, `--help`
-
-Show available command-line options and exit.
-
 ### Environment variable options
 
 _Black_ supports the following configuration via environment variables.
@@ -355,7 +359,7 @@ All done! ✨ 🍰 ✨
 use `--stdin-filename`. Useful to make sure _Black_ will respect the `--force-exclude`
 option on some editors that rely on using stdin.
 
-You can also pass code as a string using the `-c` / `--code` option.
+You can also pass code as a string using the `--code` option.
 
 ### Writeback and reporting
 
@@ -435,8 +439,7 @@ refers to the path to your home directory. On Windows, this will be something li
 You can also explicitly specify the path to a particular file that you want with
 `--config`. In this situation _Black_ will not look for any other file.
 
-If you're running with `--verbose`, you will see a blue message if a file was found and
-used.
+If you're running with `--verbose`, you will see a message if a file was found and used.
 
 Please note `blackd` will not use `pyproject.toml` configuration.
 
diff --git a/src/black/__init__.py b/src/black/__init__.py
index e7dac895a6a..5073fa748d5 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -235,25 +235,26 @@ def validate_regex(
     callback=target_version_option_callback,
     multiple=True,
     help=(
-        "Python versions that should be supported by Black's output. By default, Black"
-        " will try to infer this from the project metadata in pyproject.toml. If this"
-        " does not yield conclusive results, Black will use per-file auto-detection."
+        "Python versions that should be supported by Black's output. You should"
+        " include all versions that your code supports. By default, Black will infer"
+        " target versions from the project metadata in pyproject.toml. If this does"
+        " not yield conclusive results, Black will use per-file auto-detection."
     ),
 )
 @click.option(
     "--pyi",
     is_flag=True,
     help=(
-        "Format all input files like typing stubs regardless of file extension (useful"
-        " when piping source on standard input)."
+        "Format all input files like typing stubs regardless of file extension. This"
+        " is useful when piping source on standard input."
     ),
 )
 @click.option(
     "--ipynb",
     is_flag=True,
     help=(
-        "Format all input files like Jupyter Notebooks regardless of file extension "
-        "(useful when piping source on standard input)."
+        "Format all input files like Jupyter Notebooks regardless of file extension."
+        "This is useful when piping source on standard input."
     ),
 )
 @click.option(
@@ -310,14 +311,22 @@ def validate_regex(
 @click.option(
     "--diff",
     is_flag=True,
-    help="Don't write the files back, just output a diff for each file on stdout.",
+    help=(
+        "Don't write the files back, just output a diff to indicate what changes"
+        " Black would've made. They are printed to stdout so capturing them is simple."
+    ),
+)
+@click.option(
+    "--color/--no-color",
+    is_flag=True,
+    help="Show (or do not show) colored diff. Only applies when --diff is given.",
 )
 @click.option(
     "--line-ranges",
     multiple=True,
     metavar="START-END",
     help=(
-        "When specified, _Black_ will try its best to only format these lines. This"
+        "When specified, Black will try its best to only format these lines. This"
         " option can be specified multiple times, and a union of the lines will be"
         " formatted. Each range must be specified as two integers connected by a `-`:"
         " `<START>-<END>`. The `<START>` and `<END>` integer indices are 1-based and"
@@ -325,23 +334,24 @@ def validate_regex(
     ),
     default=(),
 )
-@click.option(
-    "--color/--no-color",
-    is_flag=True,
-    help="Show colored diff. Only applies when `--diff` is given.",
-)
 @click.option(
     "--fast/--safe",
     is_flag=True,
-    help="If --fast given, skip temporary sanity checks. [default: --safe]",
+    help=(
+        "By default, Black performs an AST safety check after formatting your code."
+        " The --fast flag turns off this check and the --safe flag explicitly enables"
+        " it. [default: --safe]"
+    ),
 )
 @click.option(
     "--required-version",
     type=str,
     help=(
-        "Require a specific version of Black to be running (useful for unifying results"
-        " across many environments e.g. with a pyproject.toml file). It can be"
-        " either a major version number or an exact version."
+        "Require a specific version of Black to be running. This is useful for"
+        " ensuring that all contributors to your project are using the same"
+        " version, because different versions of Black may format code a little"
+        " differently. This option can be set in a configuration file for consistent"
+        " results across environments."
     ),
 )
 @click.option(
@@ -371,8 +381,10 @@ def validate_regex(
     type=str,
     callback=validate_regex,
     help=(
-        "Like --exclude, but files and directories matching this regex will be "
-        "excluded even when they are passed explicitly as arguments."
+        "Like --exclude, but files and directories matching this regex will be excluded"
+        " even when they are passed explicitly as arguments. This is useful when"
+        " invoking Black programmatically on changed files, such as in a pre-commit"
+        " hook or editor plugin."
     ),
 )
 @click.option(
@@ -380,9 +392,9 @@ def validate_regex(
     type=str,
     is_eager=True,
     help=(
-        "The name of the file when passing it through stdin. Useful to make "
-        "sure Black will respect --force-exclude option on some "
-        "editors that rely on using stdin."
+        "The name of the file when passing it through stdin. Useful to make sure Black"
+        " will respect the --force-exclude option on some editors that rely on using"
+        " stdin."
     ),
 )
 @click.option(
@@ -405,8 +417,10 @@ def validate_regex(
     type=click.IntRange(min=1),
     default=None,
     help=(
-        "Number of parallel workers [default: BLACK_NUM_WORKERS environment variable "
-        "or number of CPUs in the system]"
+        "When Black formats multiple files, it may use a process pool to speed up"
+        " formatting. This option controls the number of parallel workers. This can"
+        " also be specified via the BLACK_NUM_WORKERS environment variable. Defaults"
+        " to the number of CPUs in the system."
     ),
 )
 @click.option(
@@ -414,8 +428,8 @@ def validate_regex(
     "--quiet",
     is_flag=True,
     help=(
-        "Don't emit non-error messages to stderr. Errors are still emitted; silence"
-        " those with 2>/dev/null."
+        "Stop emitting all non-critical output. Error messages will still be emitted"
+        " (which can silenced by 2>/dev/null)."
     ),
 )
 @click.option(
@@ -423,8 +437,9 @@ def validate_regex(
     "--verbose",
     is_flag=True,
     help=(
-        "Also emit messages to stderr about files that were not changed or were ignored"
-        " due to exclusion patterns."
+        "Emit messages about files that were not changed or were ignored due to"
+        " exclusion patterns. If Black is using a configuration file, a message"
+        " detailing which one it is using will be emitted."
     ),
 )
 @click.version_option(
@@ -455,7 +470,7 @@ def validate_regex(
     ),
     is_eager=True,
     callback=read_pyproject_toml,
-    help="Read configuration from FILE path.",
+    help="Read configuration options from a configuration file.",
 )
 @click.pass_context
 def main(  # noqa: C901

From e7e122e9ff27fc040a6e8ecd92f0e7603c87f92d Mon Sep 17 00:00:00 2001
From: cobalt <61329810+RedGuy12@users.noreply.github.com>
Date: Sat, 9 Dec 2023 19:44:15 -0600
Subject: [PATCH 0955/1034] docs: Move `fmt: off` docs (#4090)

---
 docs/the_black_code_style/current_style.md | 15 +++------------
 docs/usage_and_configuration/the_basics.md | 16 ++++++++++++++--
 2 files changed, 17 insertions(+), 14 deletions(-)

diff --git a/docs/the_black_code_style/current_style.md b/docs/the_black_code_style/current_style.md
index 2a5e10162f2..00bd81416dc 100644
--- a/docs/the_black_code_style/current_style.md
+++ b/docs/the_black_code_style/current_style.md
@@ -8,18 +8,9 @@ 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 contain
-`# fmt: skip` or blocks that start with `# fmt: off` and end with `# fmt: on`.
-`# 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
-running `black --preview`.
+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 running
+`black --preview`.
 
 ### How _Black_ wraps lines
 
diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index 73c0d1323e3..eb92887f64f 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -12,7 +12,8 @@ _Black_ is a well-behaved Unix-style command-line tool:
 
 ## Usage
 
-To get started right away with sensible defaults:
+_Black_ will reformat entire files in place. To get started right away with sensible
+defaults:
 
 ```sh
 black {source_file_or_directory}
@@ -24,6 +25,17 @@ You can run _Black_ as a package if running it as a script doesn't work:
 python -m black {source_file_or_directory}
 ```
 
+### Ignoring sections
+
+Black will not reformat lines that contain `# fmt: skip` or blocks that start with
+`# fmt: off` and end with `# fmt: on`. `# 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. Black also recognizes
+[YAPF](https://github.com/google/yapf)'s block comments to the same effect, as a
+courtesy for straddling code.
+
 ### Command line options
 
 The CLI options of _Black_ can be displayed by running `black --help`. All options are
@@ -191,7 +203,7 @@ All done! ✨ 🍰 ✨
 
 Show (or do not show) colored diff. Only applies when `--diff` is given.
 
-### `--line-ranges`
+#### `--line-ranges`
 
 When specified, _Black_ will try its best to only format these lines.
 

From 61b529b7d15400309379f36104885a1dfcd2d026 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Sat, 9 Dec 2023 18:29:09 -0800
Subject: [PATCH 0956/1034] Allow empty lines at beginning of blocks (again)
 (#4060)

---
 CHANGES.md                                    |  2 ++
 src/black/lines.py                            | 14 +++++-------
 src/black/mode.py                             |  2 +-
 ...s.py => preview_allow_empty_first_line.py} | 22 +++++++++++++++++++
 tests/data/cases/preview_form_feeds.py        |  1 +
 5 files changed, 31 insertions(+), 10 deletions(-)
 rename tests/data/cases/{preview_allow_empty_first_line_in_special_cases.py => preview_allow_empty_first_line.py} (87%)

diff --git a/CHANGES.md b/CHANGES.md
index 8f0b75e7f10..fa0d2494f67 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -17,6 +17,8 @@
 - Standalone form feed characters at the module level are no longer removed (#4021)
 - Additional cases of immediately nested tuples, lists, and dictionaries are now
   indented less (#4012)
+- Allow empty lines at the beginning of all blocks, except immediately before a
+  docstring (#4060)
 - Fix crash in preview mode when using a short `--line-length` (#4086)
 
 ### Configuration
diff --git a/src/black/lines.py b/src/black/lines.py
index 6e33ee57eab..4050f819757 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -689,18 +689,14 @@ def _maybe_empty_lines(self, current_line: Line) -> Tuple[int, int]:
                 return 0, 1
             return before, 1
 
+        # In preview mode, always allow blank lines, except right before a function
+        # docstring
         is_empty_first_line_ok = (
-            Preview.allow_empty_first_line_before_new_block_or_comment
-            in current_line.mode
+            Preview.allow_empty_first_line_in_block in current_line.mode
             and (
-                # If it's a standalone comment
-                current_line.leaves[0].type == STANDALONE_COMMENT
-                # If it opens a new block
-                or current_line.opens_block
-                # If it's a triple quote comment (but not at the start of a funcdef)
+                not is_docstring(current_line.leaves[0])
                 or (
-                    is_docstring(current_line.leaves[0])
-                    and self.previous_line
+                    self.previous_line
                     and self.previous_line.leaves[0]
                     and self.previous_line.leaves[0].parent
                     and not is_funcdef(self.previous_line.leaves[0].parent)
diff --git a/src/black/mode.py b/src/black/mode.py
index 04038f49627..9df19618363 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -191,7 +191,7 @@ class Preview(Enum):
     accept_raw_docstrings = auto()
     fix_power_op_line_length = auto()
     hug_parens_with_braces_and_square_brackets = auto()
-    allow_empty_first_line_before_new_block_or_comment = auto()
+    allow_empty_first_line_in_block = auto()
     single_line_format_skip_with_multiple_comments = auto()
     long_case_block_line_splitting = auto()
     allow_form_feeds = auto()
diff --git a/tests/data/cases/preview_allow_empty_first_line_in_special_cases.py b/tests/data/cases/preview_allow_empty_first_line.py
similarity index 87%
rename from tests/data/cases/preview_allow_empty_first_line_in_special_cases.py
rename to tests/data/cases/preview_allow_empty_first_line.py
index 96c1433c110..3e14fa15250 100644
--- a/tests/data/cases/preview_allow_empty_first_line_in_special_cases.py
+++ b/tests/data/cases/preview_allow_empty_first_line.py
@@ -51,6 +51,17 @@ def baz():
     if x:
         a = 123
 
+def quux():
+
+    new_line = here
+
+
+class Cls:
+
+    def method(self):
+
+        pass
+
 # output
 
 def foo():
@@ -104,3 +115,14 @@ def baz():
     # OK
     if x:
         a = 123
+
+
+def quux():
+
+    new_line = here
+
+
+class Cls:
+    def method(self):
+
+        pass
diff --git a/tests/data/cases/preview_form_feeds.py b/tests/data/cases/preview_form_feeds.py
index 2d8653a1f04..c236f177a95 100644
--- a/tests/data/cases/preview_form_feeds.py
+++ b/tests/data/cases/preview_form_feeds.py
@@ -198,6 +198,7 @@ def foo():
 
 # form feeds are prohibited inside blocks, or on a line with nonwhitespace
 def bar(a=1, b: bool = False):
+
     pass
 
 

From ce28be2705ab29f184ec4a00aa3d23340630796d Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Sat, 9 Dec 2023 21:14:25 -0800
Subject: [PATCH 0957/1034] Add dedicated preview feature for East Asian Width
 (#4097)

---
 src/black/lines.py | 2 +-
 src/black/mode.py  | 1 +
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/black/lines.py b/src/black/lines.py
index 4050f819757..2a41db173d4 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -851,7 +851,7 @@ def is_line_short_enough(  # noqa: C901
     if not line_str:
         line_str = line_to_string(line)
 
-    width = str_width if mode.preview else len
+    width = str_width if Preview.respect_east_asian_width in mode else len
 
     if Preview.multiline_string_handling not in mode:
         return (
diff --git a/src/black/mode.py b/src/black/mode.py
index 9df19618363..38b861e39ca 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -195,6 +195,7 @@ class Preview(Enum):
     single_line_format_skip_with_multiple_comments = auto()
     long_case_block_line_splitting = auto()
     allow_form_feeds = auto()
+    respect_east_asian_width = auto()
 
 
 class Deprecated(UserWarning):

From 67b23d71854c19921cc6092c695d3301ab99229c Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 11 Dec 2023 11:32:04 -0800
Subject: [PATCH 0958/1034] Bump actions/setup-python from 4 to 5 (#4101)

---
 .github/workflows/diff_shades.yml         | 4 ++--
 .github/workflows/diff_shades_comment.yml | 2 +-
 .github/workflows/doc.yml                 | 2 +-
 .github/workflows/fuzz.yml                | 2 +-
 .github/workflows/lint.yml                | 2 +-
 .github/workflows/pypi_upload.yml         | 2 +-
 .github/workflows/release_tests.yml       | 2 +-
 .github/workflows/test.yml                | 4 ++--
 .github/workflows/upload_binary.yml       | 2 +-
 9 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/.github/workflows/diff_shades.yml b/.github/workflows/diff_shades.yml
index 6bfc6ca9ed8..8d8be2550b0 100644
--- a/.github/workflows/diff_shades.yml
+++ b/.github/workflows/diff_shades.yml
@@ -20,7 +20,7 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/setup-python@v4
+      - uses: actions/setup-python@v5
         with:
           python-version: "3.11"
 
@@ -57,7 +57,7 @@ jobs:
           # The baseline revision could be rather old so a full clone is ideal.
           fetch-depth: 0
 
-      - uses: actions/setup-python@v4
+      - uses: actions/setup-python@v5
         with:
           python-version: "3.11"
 
diff --git a/.github/workflows/diff_shades_comment.yml b/.github/workflows/diff_shades_comment.yml
index 49fd376d85e..9b3b4b579da 100644
--- a/.github/workflows/diff_shades_comment.yml
+++ b/.github/workflows/diff_shades_comment.yml
@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/setup-python@v4
+      - uses: actions/setup-python@v5
         with:
           python-version: "*"
 
diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml
index fa3d87c70f5..006991a16d8 100644
--- a/.github/workflows/doc.yml
+++ b/.github/workflows/doc.yml
@@ -24,7 +24,7 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: Set up latest Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: "*"
 
diff --git a/.github/workflows/fuzz.yml b/.github/workflows/fuzz.yml
index 48c26452c54..42a399fd0aa 100644
--- a/.github/workflows/fuzz.yml
+++ b/.github/workflows/fuzz.yml
@@ -28,7 +28,7 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
 
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index 9c7aca8f869..2d016cef7a6 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -24,7 +24,7 @@ jobs:
           fi
 
       - name: Set up latest Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: "*"
 
diff --git a/.github/workflows/pypi_upload.yml b/.github/workflows/pypi_upload.yml
index bbdcdf17a8f..8e3eb67a10d 100644
--- a/.github/workflows/pypi_upload.yml
+++ b/.github/workflows/pypi_upload.yml
@@ -21,7 +21,7 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: Set up latest Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: "*"
 
diff --git a/.github/workflows/release_tests.yml b/.github/workflows/release_tests.yml
index 74729445052..192ba004f81 100644
--- a/.github/workflows/release_tests.yml
+++ b/.github/workflows/release_tests.yml
@@ -34,7 +34,7 @@ jobs:
           # Give us all history, branches and tags
           fetch-depth: 0
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
           allow-prereleases: true
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 3f8928cc42a..55359a23303 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -38,7 +38,7 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
 
@@ -96,7 +96,7 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: Set up latest Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: "*"
 
diff --git a/.github/workflows/upload_binary.yml b/.github/workflows/upload_binary.yml
index bb19d48158c..06e55cfe93a 100644
--- a/.github/workflows/upload_binary.yml
+++ b/.github/workflows/upload_binary.yml
@@ -32,7 +32,7 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: Set up latest Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: "*"
 

From 9aea9768cb60d23f2f4d331e94c4ee07ef1683a5 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Mon, 11 Dec 2023 13:19:02 -0800
Subject: [PATCH 0959/1034] Only use dummy implementation logic for functions
 and classes (#4066)

Fixes #4063
---
 CHANGES.md                                    |  2 ++
 src/black/linegen.py                          |  4 ++--
 src/black/nodes.py                            |  9 +++++++-
 .../cases/preview_dummy_implementations.py    | 22 +++++++++++++++++--
 4 files changed, 32 insertions(+), 5 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index fa0d2494f67..62caea41c31 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -20,6 +20,8 @@
 - Allow empty lines at the beginning of all blocks, except immediately before a
   docstring (#4060)
 - Fix crash in preview mode when using a short `--line-length` (#4086)
+- Keep suites consisting of only an ellipsis on their own lines if they are not
+  functions or class definitions (#4066)
 
 ### Configuration
 
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 073672a5ae7..6934823d340 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -286,7 +286,7 @@ def visit_suite(self, node: Node) -> Iterator[Line]:
         """Visit a suite."""
         if (
             self.mode.is_pyi or Preview.dummy_implementations in self.mode
-        ) and is_stub_suite(node):
+        ) and is_stub_suite(node, self.mode):
             yield from self.visit(node.children[2])
         else:
             yield from self.visit_default(node)
@@ -314,7 +314,7 @@ def visit_simple_stmt(self, node: Node) -> Iterator[Line]:
             if (
                 not (self.mode.is_pyi or Preview.dummy_implementations in self.mode)
                 or not node.parent
-                or not is_stub_suite(node.parent)
+                or not is_stub_suite(node.parent, self.mode)
             ):
                 yield from self.line()
             yield from self.visit_default(node)
diff --git a/src/black/nodes.py b/src/black/nodes.py
index de53f8e36a3..9b8d9a97835 100644
--- a/src/black/nodes.py
+++ b/src/black/nodes.py
@@ -736,8 +736,15 @@ def is_funcdef(node: Node) -> bool:
     return node.type == syms.funcdef
 
 
-def is_stub_suite(node: Node) -> bool:
+def is_stub_suite(node: Node, mode: Mode) -> bool:
     """Return True if `node` is a suite with a stub body."""
+    if node.parent is not None:
+        if Preview.dummy_implementations in mode and node.parent.type not in (
+            syms.funcdef,
+            syms.async_funcdef,
+            syms.classdef,
+        ):
+            return False
 
     # If there is a comment, we want to keep it.
     if node.prefix.strip():
diff --git a/tests/data/cases/preview_dummy_implementations.py b/tests/data/cases/preview_dummy_implementations.py
index 98b69bf87b2..113ac36cdc5 100644
--- a/tests/data/cases/preview_dummy_implementations.py
+++ b/tests/data/cases/preview_dummy_implementations.py
@@ -1,9 +1,11 @@
 # flags: --preview
 from typing import NoReturn, Protocol, Union, overload
 
+class Empty:
+    ...
 
 def dummy(a): ...
-def other(b): ...
+async def other(b): ...
 
 
 @overload
@@ -48,13 +50,22 @@ def b(arg: Union[int, str, object]) -> Union[int, str]:
         raise TypeError
     return arg
 
+def has_comment():
+    ...  # still a dummy
+
+if some_condition:
+    ...
+
 # output
 
 from typing import NoReturn, Protocol, Union, overload
 
 
+class Empty: ...
+
+
 def dummy(a): ...
-def other(b): ...
+async def other(b): ...
 
 
 @overload
@@ -98,3 +109,10 @@ def b(arg: Union[int, str, object]) -> Union[int, str]:
     if not isinstance(arg, (int, str)):
         raise TypeError
     return arg
+
+
+def has_comment(): ...  # still a dummy
+
+
+if some_condition:
+    ...

From 0c9899956d890a9dc9c3adbc80b478a47846ced9 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Mon, 11 Dec 2023 14:29:33 -0800
Subject: [PATCH 0960/1034] Fix path in test message (#4102)

---
 tests/test_black.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tests/test_black.py b/tests/test_black.py
index 899cbeb111d..23815da9042 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -317,7 +317,7 @@ def test_expression_diff(self) -> None:
             msg = (
                 "Expected diff isn't equal to the actual. If you made changes to"
                 " expression.py and this is an anticipated difference, overwrite"
-                f" tests/data/expression.diff with {dump}"
+                f" tests/data/cases/expression.diff with {dump}"
             )
             self.assertEqual(expected, actual, msg)
 

From eb7661f8ab9bff344835693c7c08789bb195137e Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Mon, 11 Dec 2023 14:41:41 -0800
Subject: [PATCH 0961/1034] Fix another case where we format dummy
 implementation for non-functions/classes (#4103)

---
 CHANGES.md                                      |  2 +-
 src/black/linegen.py                            | 12 +++++++-----
 src/black/nodes.py                              | 17 ++++++++++-------
 .../data/cases/preview_dummy_implementations.py |  5 +++++
 4 files changed, 23 insertions(+), 13 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 62caea41c31..dcf6613b70c 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -21,7 +21,7 @@
   docstring (#4060)
 - Fix crash in preview mode when using a short `--line-length` (#4086)
 - Keep suites consisting of only an ellipsis on their own lines if they are not
-  functions or class definitions (#4066)
+  functions or class definitions (#4066) (#4103)
 
 ### Configuration
 
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 6934823d340..245be235231 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -42,6 +42,7 @@
     is_atom_with_invisible_parens,
     is_docstring,
     is_empty_tuple,
+    is_function_or_class,
     is_lpar_token,
     is_multiline_string,
     is_name_token,
@@ -299,11 +300,12 @@ def visit_simple_stmt(self, node: Node) -> Iterator[Line]:
                 wrap_in_parentheses(node, child, visible=False)
             prev_type = child.type
 
-        is_suite_like = node.parent and node.parent.type in STATEMENT
-        if is_suite_like:
-            if (
-                self.mode.is_pyi or Preview.dummy_implementations in self.mode
-            ) and is_stub_body(node):
+        if node.parent and node.parent.type in STATEMENT:
+            if Preview.dummy_implementations in self.mode:
+                condition = is_function_or_class(node.parent)
+            else:
+                condition = self.mode.is_pyi
+            if condition and is_stub_body(node):
                 yield from self.visit_default(node)
             else:
                 yield from self.line(+1)
diff --git a/src/black/nodes.py b/src/black/nodes.py
index 9b8d9a97835..a4f555b4032 100644
--- a/src/black/nodes.py
+++ b/src/black/nodes.py
@@ -736,15 +736,18 @@ def is_funcdef(node: Node) -> bool:
     return node.type == syms.funcdef
 
 
+def is_function_or_class(node: Node) -> bool:
+    return node.type in {syms.funcdef, syms.classdef, syms.async_funcdef}
+
+
 def is_stub_suite(node: Node, mode: Mode) -> bool:
     """Return True if `node` is a suite with a stub body."""
-    if node.parent is not None:
-        if Preview.dummy_implementations in mode and node.parent.type not in (
-            syms.funcdef,
-            syms.async_funcdef,
-            syms.classdef,
-        ):
-            return False
+    if (
+        node.parent is not None
+        and Preview.dummy_implementations in mode
+        and not is_function_or_class(node.parent)
+    ):
+        return False
 
     # If there is a comment, we want to keep it.
     if node.prefix.strip():
diff --git a/tests/data/cases/preview_dummy_implementations.py b/tests/data/cases/preview_dummy_implementations.py
index 113ac36cdc5..28b23bb8609 100644
--- a/tests/data/cases/preview_dummy_implementations.py
+++ b/tests/data/cases/preview_dummy_implementations.py
@@ -56,6 +56,8 @@ def has_comment():
 if some_condition:
     ...
 
+if already_dummy: ...
+
 # output
 
 from typing import NoReturn, Protocol, Union, overload
@@ -116,3 +118,6 @@ def has_comment(): ...  # still a dummy
 
 if some_condition:
     ...
+
+if already_dummy:
+    ...

From ebd543c0ac9b8a5f17636d0a42c425e5f693860e Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Mon, 11 Dec 2023 21:37:15 -0800
Subject: [PATCH 0962/1034] Fix feature detection for parenthesized context
 managers (#4104)

---
 CHANGES.md                                |   1 +
 src/black/__init__.py                     |  18 ++-
 tests/data/cases/pep_572_remove_parens.py |   2 +-
 tests/test_black.py                       | 130 ++++++++++++----------
 4 files changed, 93 insertions(+), 58 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index dcf6613b70c..e3b5b7392b9 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -10,6 +10,7 @@
 
 - Fix bug where `# fmt: off` automatically dedents when used with the `--line-ranges`
   option, even when it is not within the specified line range. (#4084)
+- Fix feature detection for parenthesized context managers (#4104)
 
 ### Preview style
 
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 5073fa748d5..735ba713b8f 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -1351,7 +1351,7 @@ def get_features_used(  # noqa: C901
             if (
                 len(atom_children) == 3
                 and atom_children[0].type == token.LPAR
-                and atom_children[1].type == syms.testlist_gexp
+                and _contains_asexpr(atom_children[1])
                 and atom_children[2].type == token.RPAR
             ):
                 features.add(Feature.PARENTHESIZED_CONTEXT_MANAGERS)
@@ -1384,6 +1384,22 @@ def get_features_used(  # noqa: C901
     return features
 
 
+def _contains_asexpr(node: Union[Node, Leaf]) -> bool:
+    """Return True if `node` contains an as-pattern."""
+    if node.type == syms.asexpr_test:
+        return True
+    elif node.type == syms.atom:
+        if (
+            len(node.children) == 3
+            and node.children[0].type == token.LPAR
+            and node.children[2].type == token.RPAR
+        ):
+            return _contains_asexpr(node.children[1])
+    elif node.type == syms.testlist_gexp:
+        return any(_contains_asexpr(child) for child in node.children)
+    return False
+
+
 def detect_target_versions(
     node: Node, *, future_imports: Optional[Set[str]] = None
 ) -> Set[TargetVersion]:
diff --git a/tests/data/cases/pep_572_remove_parens.py b/tests/data/cases/pep_572_remove_parens.py
index 88774d81649..24f1ac29168 100644
--- a/tests/data/cases/pep_572_remove_parens.py
+++ b/tests/data/cases/pep_572_remove_parens.py
@@ -1,4 +1,4 @@
-# flags: --minimum-version=3.8 --no-preview-line-length-1
+# flags: --minimum-version=3.8
 if (foo := 0):
     pass
 
diff --git a/tests/test_black.py b/tests/test_black.py
index 23815da9042..0af5fd2a1f4 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -25,6 +25,7 @@
     List,
     Optional,
     Sequence,
+    Set,
     Type,
     TypeVar,
     Union,
@@ -874,71 +875,88 @@ def test_get_features_used_decorator(self) -> None:
             )
 
     def test_get_features_used(self) -> None:
-        node = black.lib2to3_parse("def f(*, arg): ...\n")
-        self.assertEqual(black.get_features_used(node), set())
-        node = black.lib2to3_parse("def f(*, arg,): ...\n")
-        self.assertEqual(black.get_features_used(node), {Feature.TRAILING_COMMA_IN_DEF})
-        node = black.lib2to3_parse("f(*arg,)\n")
-        self.assertEqual(
-            black.get_features_used(node), {Feature.TRAILING_COMMA_IN_CALL}
+        self.check_features_used("def f(*, arg): ...\n", set())
+        self.check_features_used(
+            "def f(*, arg,): ...\n", {Feature.TRAILING_COMMA_IN_DEF}
         )
-        node = black.lib2to3_parse("def f(*, arg): f'string'\n")
-        self.assertEqual(black.get_features_used(node), {Feature.F_STRINGS})
-        node = black.lib2to3_parse("123_456\n")
-        self.assertEqual(black.get_features_used(node), {Feature.NUMERIC_UNDERSCORES})
-        node = black.lib2to3_parse("123456\n")
-        self.assertEqual(black.get_features_used(node), set())
+        self.check_features_used("f(*arg,)\n", {Feature.TRAILING_COMMA_IN_CALL})
+        self.check_features_used("def f(*, arg): f'string'\n", {Feature.F_STRINGS})
+        self.check_features_used("123_456\n", {Feature.NUMERIC_UNDERSCORES})
+        self.check_features_used("123456\n", set())
+
         source, expected = read_data("cases", "function")
-        node = black.lib2to3_parse(source)
         expected_features = {
             Feature.TRAILING_COMMA_IN_CALL,
             Feature.TRAILING_COMMA_IN_DEF,
             Feature.F_STRINGS,
         }
-        self.assertEqual(black.get_features_used(node), expected_features)
-        node = black.lib2to3_parse(expected)
-        self.assertEqual(black.get_features_used(node), expected_features)
+        self.check_features_used(source, expected_features)
+        self.check_features_used(expected, expected_features)
+
         source, expected = read_data("cases", "expression")
-        node = black.lib2to3_parse(source)
-        self.assertEqual(black.get_features_used(node), set())
-        node = black.lib2to3_parse(expected)
-        self.assertEqual(black.get_features_used(node), set())
-        node = black.lib2to3_parse("lambda a, /, b: ...")
-        self.assertEqual(black.get_features_used(node), {Feature.POS_ONLY_ARGUMENTS})
-        node = black.lib2to3_parse("def fn(a, /, b): ...")
-        self.assertEqual(black.get_features_used(node), {Feature.POS_ONLY_ARGUMENTS})
-        node = black.lib2to3_parse("def fn(): yield a, b")
-        self.assertEqual(black.get_features_used(node), set())
-        node = black.lib2to3_parse("def fn(): return a, b")
-        self.assertEqual(black.get_features_used(node), set())
-        node = black.lib2to3_parse("def fn(): yield *b, c")
-        self.assertEqual(black.get_features_used(node), {Feature.UNPACKING_ON_FLOW})
-        node = black.lib2to3_parse("def fn(): return a, *b, c")
-        self.assertEqual(black.get_features_used(node), {Feature.UNPACKING_ON_FLOW})
-        node = black.lib2to3_parse("x = a, *b, c")
-        self.assertEqual(black.get_features_used(node), set())
-        node = black.lib2to3_parse("x: Any = regular")
-        self.assertEqual(black.get_features_used(node), set())
-        node = black.lib2to3_parse("x: Any = (regular, regular)")
-        self.assertEqual(black.get_features_used(node), set())
-        node = black.lib2to3_parse("x: Any = Complex(Type(1))[something]")
-        self.assertEqual(black.get_features_used(node), set())
-        node = black.lib2to3_parse("x: Tuple[int, ...] = a, b, c")
-        self.assertEqual(
-            black.get_features_used(node), {Feature.ANN_ASSIGN_EXTENDED_RHS}
+        self.check_features_used(source, set())
+        self.check_features_used(expected, set())
+
+        self.check_features_used("lambda a, /, b: ...\n", {Feature.POS_ONLY_ARGUMENTS})
+        self.check_features_used("def fn(a, /, b): ...", {Feature.POS_ONLY_ARGUMENTS})
+
+        self.check_features_used("def fn(): yield a, b", set())
+        self.check_features_used("def fn(): return a, b", set())
+        self.check_features_used("def fn(): yield *b, c", {Feature.UNPACKING_ON_FLOW})
+        self.check_features_used(
+            "def fn(): return a, *b, c", {Feature.UNPACKING_ON_FLOW}
         )
-        node = black.lib2to3_parse("try: pass\nexcept Something: pass")
-        self.assertEqual(black.get_features_used(node), set())
-        node = black.lib2to3_parse("try: pass\nexcept (*Something,): pass")
-        self.assertEqual(black.get_features_used(node), set())
-        node = black.lib2to3_parse("try: pass\nexcept *Group: pass")
-        self.assertEqual(black.get_features_used(node), {Feature.EXCEPT_STAR})
-        node = black.lib2to3_parse("a[*b]")
-        self.assertEqual(black.get_features_used(node), {Feature.VARIADIC_GENERICS})
-        node = black.lib2to3_parse("a[x, *y(), z] = t")
-        self.assertEqual(black.get_features_used(node), {Feature.VARIADIC_GENERICS})
-        node = black.lib2to3_parse("def fn(*args: *T): pass")
-        self.assertEqual(black.get_features_used(node), {Feature.VARIADIC_GENERICS})
+        self.check_features_used("x = a, *b, c", set())
+
+        self.check_features_used("x: Any = regular", set())
+        self.check_features_used("x: Any = (regular, regular)", set())
+        self.check_features_used("x: Any = Complex(Type(1))[something]", set())
+        self.check_features_used(
+            "x: Tuple[int, ...] = a, b, c", {Feature.ANN_ASSIGN_EXTENDED_RHS}
+        )
+
+        self.check_features_used("try: pass\nexcept Something: pass", set())
+        self.check_features_used("try: pass\nexcept (*Something,): pass", set())
+        self.check_features_used(
+            "try: pass\nexcept *Group: pass", {Feature.EXCEPT_STAR}
+        )
+
+        self.check_features_used("a[*b]", {Feature.VARIADIC_GENERICS})
+        self.check_features_used("a[x, *y(), z] = t", {Feature.VARIADIC_GENERICS})
+        self.check_features_used("def fn(*args: *T): pass", {Feature.VARIADIC_GENERICS})
+
+        self.check_features_used("with a: pass", set())
+        self.check_features_used("with a, b: pass", set())
+        self.check_features_used("with a as b: pass", set())
+        self.check_features_used("with a as b, c as d: pass", set())
+        self.check_features_used("with (a): pass", set())
+        self.check_features_used("with (a, b): pass", set())
+        self.check_features_used("with (a, b) as (c, d): pass", set())
+        self.check_features_used(
+            "with (a as b): pass", {Feature.PARENTHESIZED_CONTEXT_MANAGERS}
+        )
+        self.check_features_used(
+            "with ((a as b)): pass", {Feature.PARENTHESIZED_CONTEXT_MANAGERS}
+        )
+        self.check_features_used(
+            "with (a, b as c): pass", {Feature.PARENTHESIZED_CONTEXT_MANAGERS}
+        )
+        self.check_features_used(
+            "with (a, (b as c)): pass", {Feature.PARENTHESIZED_CONTEXT_MANAGERS}
+        )
+        self.check_features_used(
+            "with ((a, ((b as c)))): pass", {Feature.PARENTHESIZED_CONTEXT_MANAGERS}
+        )
+
+    def check_features_used(self, source: str, expected: Set[Feature]) -> None:
+        node = black.lib2to3_parse(source)
+        actual = black.get_features_used(node)
+        msg = f"Expected {expected} but got {actual} for {source!r}"
+        try:
+            self.assertEqual(actual, expected, msg=msg)
+        except AssertionError:
+            DebugVisitor.show(node)
+            raise
 
     def test_get_features_used_for_future_flags(self) -> None:
         for src, features in [

From d9ad09a32b0e0481bb4fef548d35b7a49cc03c5d Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Mon, 11 Dec 2023 21:55:28 -0800
Subject: [PATCH 0963/1034] Prepare release 23.12.0 (#4105)

---
 CHANGES.md                                  | 33 +++++----------------
 docs/integrations/source_version_control.md |  4 +--
 docs/usage_and_configuration/the_basics.md  |  6 ++--
 3 files changed, 13 insertions(+), 30 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index e3b5b7392b9..223d7d2c819 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,10 +1,16 @@
 # Change Log
 
-## Unreleased
+## 23.12.0
 
 ### Highlights
 
-<!-- Include any especially major or disruptive changes here -->
+It's almost 2024, which means it's time for a new edition of _Black_'s stable style!
+Together with this release, we'll put out an alpha release 24.1a1 showcasing the draft
+2024 stable style, which we'll finalize in the January release. Please try it out and
+[share your feedback](https://github.com/psf/black/issues/4042).
+
+This release (23.12.0) will still produce the 2023 style. Most but not all of the
+changes in `--preview` mode will be in the 2024 stable style.
 
 ### Stable style
 
@@ -26,8 +32,6 @@
 
 ### Configuration
 
-<!-- Changes to how Black can be configured -->
-
 - `--line-ranges` now skips _Black_'s internal stability check in `--safe` mode. This
   avoids a crash on rare inputs that have many unformatted same-content lines. (#4034)
 
@@ -36,33 +40,12 @@
 - Upgrade to mypy 1.7.1 (#4049) (#4069)
 - Faster compiled wheels are now available for CPython 3.12 (#4070)
 
-### Parser
-
-<!-- Changes to the parser or to version autodetection -->
-
-### Performance
-
-<!-- Changes that improve Black's performance. -->
-
-### Output
-
-<!-- Changes to Black's terminal output and error messages -->
-
-### _Blackd_
-
-<!-- Changes to blackd -->
-
 ### Integrations
 
 - Enable 3.12 CI (#4035)
 - Build docker images in parallel (#4054)
 - Build docker images with 3.12 (#4055)
 
-### Documentation
-
-<!-- Major changes to documentation and policies. Small docs changes
-     don't need a changelog entry. -->
-
 ## 23.11.0
 
 ### Highlights
diff --git a/docs/integrations/source_version_control.md b/docs/integrations/source_version_control.md
index 3c7ef89918f..ca810f1d8f6 100644
--- a/docs/integrations/source_version_control.md
+++ b/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.11.0
+    rev: 23.12.0
     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.11.0
+    rev: 23.12.0
     hooks:
       - id: black-jupyter
         # It is recommended to specify the latest version of Python
diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index eb92887f64f..2dbb573803c 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -241,8 +241,8 @@ configuration file for consistent results across environments.
 
 ```console
 $ black --version
-black, 23.11.0 (compiled: yes)
-$ black --required-version 23.11.0 -c "format = 'this'"
+black, 23.12.0 (compiled: yes)
+$ black --required-version 23.12.0 -c "format = 'this'"
 format = "this"
 $ black --required-version 31.5b2 -c "still = 'beta?!'"
 Oh no! 💥 💔 💥 The required version does not match the running version!
@@ -333,7 +333,7 @@ You can check the version of _Black_ you have installed using the `--version` fl
 
 ```console
 $ black --version
-black, 23.11.0
+black, 23.12.0
 ```
 
 #### `--config`

From 35ce37ded7bd8fdd3950af19e7c11f311ee7b8d8 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Mon, 11 Dec 2023 22:28:46 -0800
Subject: [PATCH 0964/1034] Add new changelog template

---
 CHANGES.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/CHANGES.md b/CHANGES.md
index 223d7d2c819..9d79b0fb61a 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,5 +1,52 @@
 # Change Log
 
+## Unreleased
+
+### Highlights
+
+<!-- Include any especially major or disruptive changes here -->
+
+### Stable style
+
+<!-- Changes that affect Black's stable style -->
+
+### Preview style
+
+<!-- Changes that affect Black's preview style -->
+
+### Configuration
+
+<!-- Changes to how Black can be configured -->
+
+### Packaging
+
+<!-- Changes to how Black is packaged, such as dependency requirements -->
+
+### Parser
+
+<!-- Changes to the parser or to version autodetection -->
+
+### Performance
+
+<!-- Changes that improve Black's performance. -->
+
+### Output
+
+<!-- Changes to Black's terminal output and error messages -->
+
+### _Blackd_
+
+<!-- Changes to blackd -->
+
+### Integrations
+
+<!-- For example, Docker, GitHub Actions, pre-commit, editors -->
+
+### Documentation
+
+<!-- Major changes to documentation and policies. Small docs changes
+     don't need a changelog entry. -->
+
 ## 23.12.0
 
 ### Highlights

From 8fec1c30855890cc9cfce5ae6d633a1c1a21d724 Mon Sep 17 00:00:00 2001
From: Bryce Willey <Bryce.Steven.Willey@gmail.com>
Date: Thu, 14 Dec 2023 03:28:28 -0500
Subject: [PATCH 0965/1034] Adds paren to deps for hidden extra constraint
 (#4108)

Fix #4107
---
 CHANGES.md     | 2 ++
 pyproject.toml | 4 ++--
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 9d79b0fb61a..69fe34a5052 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -22,6 +22,8 @@
 
 <!-- Changes to how Black is packaged, such as dependency requirements -->
 
+- Fixed a bug that included dependencies from the `d` extra by default (#4108)
+
 ### Parser
 
 <!-- Changes to the parser or to version autodetection -->
diff --git a/pyproject.toml b/pyproject.toml
index 1098412981a..24b9c07674d 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -25,7 +25,7 @@ preview = true
 # NOTE: You don't need this in your own Black configuration.
 
 [build-system]
-requires = ["hatchling>=1.8.0", "hatch-vcs", "hatch-fancy-pypi-readme"]
+requires = ["hatchling>=1.20.0", "hatch-vcs", "hatch-fancy-pypi-readme"]
 build-backend = "hatchling.build"
 
 [project]
@@ -187,7 +187,7 @@ CC = "clang"
 build-frontend = { name = "build", args = ["--no-isolation"] }
 # Unfortunately, hatch doesn't respect MACOSX_DEPLOYMENT_TARGET
 before-build = [
-    "python -m pip install 'hatchling==1.18.0' hatch-vcs hatch-fancy-pypi-readme 'hatch-mypyc>=0.16.0' 'mypy==1.7.1' 'click==8.1.3'",
+    "python -m pip install 'hatchling==1.20.0' hatch-vcs hatch-fancy-pypi-readme 'hatch-mypyc>=0.16.0' 'mypy==1.7.1' 'click==8.1.3'",
     """sed -i '' -e "600,700s/'10_16'/os.environ['MACOSX_DEPLOYMENT_TARGET'].replace('.', '_')/" $(python -c 'import hatchling.builders.wheel as h; print(h.__file__)') """,
 ]
 

From ec91a2be3c44d88e1a3960a4937ad6ed3b63464e Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Fri, 22 Dec 2023 17:04:32 -0600
Subject: [PATCH 0966/1034] Prepare release 23.12.1 (#4124)

---
 CHANGES.md                                  | 45 +--------------------
 docs/integrations/source_version_control.md |  4 +-
 docs/usage_and_configuration/the_basics.md  |  6 +--
 3 files changed, 6 insertions(+), 49 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 69fe34a5052..d0c9e567457 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,54 +1,11 @@
 # Change Log
 
-## Unreleased
-
-### Highlights
-
-<!-- Include any especially major or disruptive changes here -->
-
-### Stable style
-
-<!-- Changes that affect Black's stable style -->
-
-### Preview style
-
-<!-- Changes that affect Black's preview style -->
-
-### Configuration
-
-<!-- Changes to how Black can be configured -->
+## 23.12.1
 
 ### Packaging
 
-<!-- Changes to how Black is packaged, such as dependency requirements -->
-
 - Fixed a bug that included dependencies from the `d` extra by default (#4108)
 
-### Parser
-
-<!-- Changes to the parser or to version autodetection -->
-
-### Performance
-
-<!-- Changes that improve Black's performance. -->
-
-### Output
-
-<!-- Changes to Black's terminal output and error messages -->
-
-### _Blackd_
-
-<!-- Changes to blackd -->
-
-### Integrations
-
-<!-- For example, Docker, GitHub Actions, pre-commit, editors -->
-
-### Documentation
-
-<!-- Major changes to documentation and policies. Small docs changes
-     don't need a changelog entry. -->
-
 ## 23.12.0
 
 ### Highlights
diff --git a/docs/integrations/source_version_control.md b/docs/integrations/source_version_control.md
index ca810f1d8f6..3b895193941 100644
--- a/docs/integrations/source_version_control.md
+++ b/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.12.0
+    rev: 23.12.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.12.0
+    rev: 23.12.1
     hooks:
       - id: black-jupyter
         # It is recommended to specify the latest version of Python
diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index 2dbb573803c..4f9856c6a47 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -241,8 +241,8 @@ configuration file for consistent results across environments.
 
 ```console
 $ black --version
-black, 23.12.0 (compiled: yes)
-$ black --required-version 23.12.0 -c "format = 'this'"
+black, 23.12.1 (compiled: yes)
+$ black --required-version 23.12.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!
@@ -333,7 +333,7 @@ You can check the version of _Black_ you have installed using the `--version` fl
 
 ```console
 $ black --version
-black, 23.12.0
+black, 23.12.1
 ```
 
 #### `--config`

From 1b831f214a111dfb45a571fc40f4404bb6b5b62c Mon Sep 17 00:00:00 2001
From: Cooper Lees <me@cooperlees.com>
Date: Fri, 22 Dec 2023 17:46:06 -0600
Subject: [PATCH 0967/1034] Add new changelog template (#4125)

---
 CHANGES.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/CHANGES.md b/CHANGES.md
index d0c9e567457..526cbd12123 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,5 +1,52 @@
 # Change Log
 
+## Unreleased
+
+### Highlights
+
+<!-- Include any especially major or disruptive changes here -->
+
+### Stable style
+
+<!-- Changes that affect Black's stable style -->
+
+### Preview style
+
+<!-- Changes that affect Black's preview style -->
+
+### Configuration
+
+<!-- Changes to how Black can be configured -->
+
+### Packaging
+
+<!-- Changes to how Black is packaged, such as dependency requirements -->
+
+### Parser
+
+<!-- Changes to the parser or to version autodetection -->
+
+### Performance
+
+<!-- Changes that improve Black's performance. -->
+
+### Output
+
+<!-- Changes to Black's terminal output and error messages -->
+
+### _Blackd_
+
+<!-- Changes to blackd -->
+
+### Integrations
+
+<!-- For example, Docker, GitHub Actions, pre-commit, editors -->
+
+### Documentation
+
+<!-- Major changes to documentation and policies. Small docs changes
+     don't need a changelog entry. -->
+
 ## 23.12.1
 
 ### Packaging

From 51786141cc4eb3c212be76638e66b91648d0e5f8 Mon Sep 17 00:00:00 2001
From: Anupya Pamidimukkala <anupya@hotmail.ca>
Date: Thu, 28 Dec 2023 01:23:42 -0500
Subject: [PATCH 0968/1034] Fix nits, chain comparisons, unused params, hyphens
 (#4114)

---
 src/black/brackets.py |  4 ++--
 src/black/cache.py    |  4 ++--
 src/black/comments.py |  3 +--
 src/black/linegen.py  |  2 +-
 src/black/lines.py    |  4 ++--
 src/black/ranges.py   |  5 +----
 src/black/trans.py    | 21 ++++++++++-----------
 7 files changed, 19 insertions(+), 24 deletions(-)

diff --git a/src/black/brackets.py b/src/black/brackets.py
index 3020cc0d390..37e6b2590eb 100644
--- a/src/black/brackets.py
+++ b/src/black/brackets.py
@@ -115,7 +115,7 @@ def mark(self, leaf: Leaf) -> None:
             if delim and self.previous is not None:
                 self.delimiters[id(self.previous)] = delim
             else:
-                delim = is_split_after_delimiter(leaf, self.previous)
+                delim = is_split_after_delimiter(leaf)
                 if delim:
                     self.delimiters[id(leaf)] = delim
         if leaf.type in OPENING_BRACKETS:
@@ -215,7 +215,7 @@ def get_open_lsqb(self) -> Optional[Leaf]:
         return self.bracket_match.get((self.depth - 1, token.RSQB))
 
 
-def is_split_after_delimiter(leaf: Leaf, previous: Optional[Leaf] = None) -> Priority:
+def is_split_after_delimiter(leaf: Leaf) -> Priority:
     """Return the priority of the `leaf` delimiter, given a line break after it.
 
     The delimiter priorities returned here are from those delimiters that would
diff --git a/src/black/cache.py b/src/black/cache.py
index 6baa096baca..c844c37b6f8 100644
--- a/src/black/cache.py
+++ b/src/black/cache.py
@@ -58,9 +58,9 @@ class Cache:
 
     @classmethod
     def read(cls, mode: Mode) -> Self:
-        """Read the cache if it exists and is well formed.
+        """Read the cache if it exists and is well-formed.
 
-        If it is not well formed, the call to write later should
+        If it is not well-formed, the call to write later should
         resolve the issue.
         """
         cache_file = get_cache_file(mode)
diff --git a/src/black/comments.py b/src/black/comments.py
index 25413121199..52bb024a799 100644
--- a/src/black/comments.py
+++ b/src/black/comments.py
@@ -221,8 +221,7 @@ def convert_one_fmt_off_pair(
             if comment.value in FMT_OFF:
                 fmt_off_prefix = ""
                 if len(lines) > 0 and not any(
-                    comment_lineno >= line[0] and comment_lineno <= line[1]
-                    for line in lines
+                    line[0] <= comment_lineno <= line[1] for line in lines
                 ):
                     # keeping indentation of comment by preserving original whitespaces.
                     fmt_off_prefix = prefix.split(comment.value)[0]
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 245be235231..0fd4a8d9c96 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -1635,7 +1635,7 @@ def generate_trailers_to_omit(line: Line, line_length: int) -> Iterator[Set[Leaf
     opening_bracket: Optional[Leaf] = None
     closing_bracket: Optional[Leaf] = None
     inner_brackets: Set[LeafID] = set()
-    for index, leaf, leaf_length in line.enumerate_with_length(reversed=True):
+    for index, leaf, leaf_length in line.enumerate_with_length(is_reversed=True):
         length += leaf_length
         if length > line_length:
             break
diff --git a/src/black/lines.py b/src/black/lines.py
index 2a41db173d4..0cd4189a778 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -451,7 +451,7 @@ def is_complex_subscript(self, leaf: Leaf) -> bool:
         )
 
     def enumerate_with_length(
-        self, reversed: bool = False
+        self, is_reversed: bool = False
     ) -> Iterator[Tuple[Index, Leaf, int]]:
         """Return an enumeration of leaves with their length.
 
@@ -459,7 +459,7 @@ def enumerate_with_length(
         """
         op = cast(
             Callable[[Sequence[Leaf]], Iterator[Tuple[Index, Leaf]]],
-            enumerate_reversed if reversed else enumerate,
+            enumerate_reversed if is_reversed else enumerate,
         )
         for index, leaf in op(self.leaves):
             length = len(leaf.prefix) + len(leaf.value)
diff --git a/src/black/ranges.py b/src/black/ranges.py
index 59e19242d47..06fa8790554 100644
--- a/src/black/ranges.py
+++ b/src/black/ranges.py
@@ -487,10 +487,7 @@ def _find_lines_mapping_index(
     index = start_index
     while index < len(lines_mappings):
         mapping = lines_mappings[index]
-        if (
-            mapping.original_start <= original_line
-            and original_line <= mapping.original_end
-        ):
+        if mapping.original_start <= original_line <= mapping.original_end:
             return index
         index += 1
     return index
diff --git a/src/black/trans.py b/src/black/trans.py
index ab3197fa6df..7c7335a005b 100644
--- a/src/black/trans.py
+++ b/src/black/trans.py
@@ -1273,7 +1273,7 @@ def iter_fexpr_spans(s: str) -> Iterator[Tuple[int, int]]:
             i += 1
             continue
 
-        # if we're in an expression part of the f-string, fast forward through strings
+        # if we're in an expression part of the f-string, fast-forward through strings
         # note that backslashes are not legal in the expression portion of f-strings
         if stack:
             delim = None
@@ -1740,7 +1740,7 @@ def passes_all_checks(i: Index) -> bool:
             """
             Returns:
                 True iff ALL of the conditions listed in the 'Transformations'
-                section of this classes' docstring would be be met by returning @i.
+                section of this classes' docstring would be met by returning @i.
             """
             is_space = string[i] == " "
             is_split_safe = is_valid_index(i - 1) and string[i - 1] in SPLIT_SAFE_CHARS
@@ -1932,7 +1932,7 @@ def _return_match(LL: List[Leaf]) -> Optional[int]:
                 OR
             None, otherwise.
         """
-        # If this line is apart of a return/yield statement and the first leaf
+        # If this line is a part of a return/yield statement and the first leaf
         # contains either the "return" or "yield" keywords...
         if parent_type(LL[0]) in [syms.return_stmt, syms.yield_expr] and LL[
             0
@@ -1957,7 +1957,7 @@ def _else_match(LL: List[Leaf]) -> Optional[int]:
                 OR
             None, otherwise.
         """
-        # If this line is apart of a ternary expression and the first leaf
+        # If this line is a part of a ternary expression and the first leaf
         # contains the "else" keyword...
         if (
             parent_type(LL[0]) == syms.test
@@ -1984,7 +1984,7 @@ def _assert_match(LL: List[Leaf]) -> Optional[int]:
                 OR
             None, otherwise.
         """
-        # If this line is apart of an assert statement and the first leaf
+        # If this line is a part of an assert statement and the first leaf
         # contains the "assert" keyword...
         if parent_type(LL[0]) == syms.assert_stmt and LL[0].value == "assert":
             is_valid_index = is_valid_index_factory(LL)
@@ -2019,7 +2019,7 @@ def _assign_match(LL: List[Leaf]) -> Optional[int]:
                 OR
             None, otherwise.
         """
-        # If this line is apart of an expression statement or is a function
+        # If this line is a part of an expression statement or is a function
         # argument AND the first leaf contains a variable name...
         if (
             parent_type(LL[0]) in [syms.expr_stmt, syms.argument, syms.power]
@@ -2040,7 +2040,7 @@ def _assign_match(LL: List[Leaf]) -> Optional[int]:
                         string_parser = StringParser()
                         idx = string_parser.parse(LL, string_idx)
 
-                        # The next leaf MAY be a comma iff this line is apart
+                        # The next leaf MAY be a comma iff this line is a part
                         # of a function argument...
                         if (
                             parent_type(LL[0]) == syms.argument
@@ -2187,8 +2187,7 @@ def do_transform(
                 if opening_bracket is not None and opening_bracket in left_leaves:
                     index = left_leaves.index(opening_bracket)
                     if (
-                        index > 0
-                        and index < len(left_leaves) - 1
+                        0 < index < len(left_leaves) - 1
                         and left_leaves[index - 1].type == token.COLON
                         and left_leaves[index + 1].value == "lambda"
                     ):
@@ -2297,7 +2296,7 @@ def parse(self, leaves: List[Leaf], string_idx: int) -> int:
             * @leaves[@string_idx].type == token.STRING
 
         Returns:
-            The index directly after the last leaf which is apart of the string
+            The index directly after the last leaf which is a part of the string
             trailer, if a "trailer" exists.
             OR
             @string_idx + 1, if no string "trailer" exists.
@@ -2320,7 +2319,7 @@ def _next_state(self, leaf: Leaf) -> bool:
               MUST be the leaf directly following @leaf.
 
         Returns:
-            True iff @leaf is apart of the string's trailer.
+            True iff @leaf is a part of the string's trailer.
         """
         # We ignore empty LPAR or RPAR leaves.
         if is_empty_par(leaf):

From c80685f36183f146f831a5737510cf105f947745 Mon Sep 17 00:00:00 2001
From: cobalt <61329810+RedGuy12@users.noreply.github.com>
Date: Thu, 28 Dec 2023 00:24:25 -0600
Subject: [PATCH 0969/1034] Treat walruses like other binary operators in
 subscripts (#4109)

Fixes #4078
---
 CHANGES.md                          | 3 +++
 src/black/lines.py                  | 9 ++++++++-
 tests/data/cases/preview_pep_572.py | 4 ++--
 3 files changed, 13 insertions(+), 3 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 526cbd12123..1444463050f 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -14,6 +14,9 @@
 
 <!-- Changes that affect Black's preview style -->
 
+- Fix bug where spaces were not added around parenthesized walruses in subscripts,
+  unlike other binary operators (#4109)
+
 ### Configuration
 
 <!-- Changes to how Black can be configured -->
diff --git a/src/black/lines.py b/src/black/lines.py
index 0cd4189a778..d153b8c2e1b 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -446,8 +446,15 @@ def is_complex_subscript(self, leaf: Leaf) -> bool:
 
             if subscript_start.type == syms.subscriptlist:
                 subscript_start = child_towards(subscript_start, leaf)
+
+        # When this is moved out of preview, add syms.namedexpr_test directly to
+        # TEST_DESCENDANTS in nodes.py
+        if Preview.walrus_subscript in self.mode:
+            test_decendants = TEST_DESCENDANTS | {syms.namedexpr_test}
+        else:
+            test_decendants = TEST_DESCENDANTS
         return subscript_start is not None and any(
-            n.type in TEST_DESCENDANTS for n in subscript_start.pre_order()
+            n.type in test_decendants for n in subscript_start.pre_order()
         )
 
     def enumerate_with_length(
diff --git a/tests/data/cases/preview_pep_572.py b/tests/data/cases/preview_pep_572.py
index 8e801ff6cdc..75ad0cc4176 100644
--- a/tests/data/cases/preview_pep_572.py
+++ b/tests/data/cases/preview_pep_572.py
@@ -3,5 +3,5 @@
 x[:(a:=0)]
 
 # output
-x[(a := 0):]
-x[:(a := 0)]
+x[(a := 0) :]
+x[: (a := 0)]

From bf6cabc8049cbdf4d0b8af33134317a0190a614f Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Wed, 27 Dec 2023 22:24:57 -0800
Subject: [PATCH 0970/1034] Do not round cache mtimes (#4128)

Fixes #4116

This logic was introduced in #3821, I believe as a result of copying
logic inside mypy that I think isn't relevant to Black
---
 CHANGES.md         | 2 ++
 src/black/cache.py | 2 +-
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index 1444463050f..2389f6d39fd 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -21,6 +21,8 @@
 
 <!-- Changes to how Black can be configured -->
 
+- Fix cache mtime logic that resulted in false positive cache hits (#4128)
+
 ### Packaging
 
 <!-- Changes to how Black is packaged, such as dependency requirements -->
diff --git a/src/black/cache.py b/src/black/cache.py
index c844c37b6f8..cfdbc21e92a 100644
--- a/src/black/cache.py
+++ b/src/black/cache.py
@@ -101,7 +101,7 @@ def is_changed(self, source: Path) -> bool:
         st = res_src.stat()
         if st.st_size != old.st_size:
             return True
-        if int(st.st_mtime) != int(old.st_mtime):
+        if st.st_mtime != old.st_mtime:
             new_hash = Cache.hash_digest(res_src)
             if new_hash != old.hash:
                 return True

From db9c592967b976a16eccd500f3e2676cfff7f29d Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Wed, 27 Dec 2023 22:59:30 -0800
Subject: [PATCH 0971/1034] Unify docstring detection (#4095)

Co-authored-by: hauntsaninja <hauntsaninja@gmail.com>
---
 CHANGES.md                                        |  1 +
 src/black/linegen.py                              |  4 ++--
 src/black/lines.py                                | 15 +++++++++++----
 src/black/mode.py                                 |  1 +
 src/black/nodes.py                                | 12 +++++++++++-
 src/black/strings.py                              |  2 ++
 tests/data/cases/module_docstring_2.py            |  2 ++
 .../preview_no_blank_line_before_docstring.py     |  7 +++++++
 8 files changed, 37 insertions(+), 7 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 2389f6d39fd..a6587cc5ceb 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -14,6 +14,7 @@
 
 <!-- Changes that affect Black's preview style -->
 
+- Format module docstrings the same as class and function docstrings (#4095)
 - Fix bug where spaces were not added around parenthesized walruses in subscripts,
   unlike other binary operators (#4109)
 
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 0fd4a8d9c96..0972cf432e1 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -424,7 +424,7 @@ def visit_STRING(self, leaf: Leaf) -> Iterator[Line]:
         if Preview.hex_codes_in_unicode_sequences in self.mode:
             normalize_unicode_escape_sequences(leaf)
 
-        if is_docstring(leaf) and not re.search(r"\\\s*\n", leaf.value):
+        if is_docstring(leaf, self.mode) and not re.search(r"\\\s*\n", leaf.value):
             # We're ignoring docstrings with backslash newline escapes because changing
             # indentation of those changes the AST representation of the code.
             if self.mode.string_normalization:
@@ -477,7 +477,7 @@ def visit_STRING(self, leaf: Leaf) -> Iterator[Line]:
             quote = quote_char * quote_len
 
             # It's invalid to put closing single-character quotes on a new line.
-            if self.mode and quote_len == 3:
+            if quote_len == 3:
                 # We need to find the length of the last line of the docstring
                 # to find if we can add the closing quotes to the line without
                 # exceeding the maximum line length.
diff --git a/src/black/lines.py b/src/black/lines.py
index d153b8c2e1b..8d02267a85b 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -196,7 +196,7 @@ def is_class_paren_empty(self) -> bool:
         )
 
     @property
-    def is_triple_quoted_string(self) -> bool:
+    def _is_triple_quoted_string(self) -> bool:
         """Is the line a triple quoted string?"""
         if not self or self.leaves[0].type != token.STRING:
             return False
@@ -209,6 +209,13 @@ def is_triple_quoted_string(self) -> bool:
             return True
         return False
 
+    @property
+    def is_docstring(self) -> bool:
+        """Is the line a docstring?"""
+        if Preview.unify_docstring_detection not in self.mode:
+            return self._is_triple_quoted_string
+        return bool(self) and is_docstring(self.leaves[0], self.mode)
+
     @property
     def is_chained_assignment(self) -> bool:
         """Is the line a chained assignment"""
@@ -583,7 +590,7 @@ def maybe_empty_lines(self, current_line: Line) -> LinesBlock:
             and self.previous_block
             and self.previous_block.previous_block is None
             and len(self.previous_block.original_line.leaves) == 1
-            and self.previous_block.original_line.is_triple_quoted_string
+            and self.previous_block.original_line.is_docstring
             and not (current_line.is_class or current_line.is_def)
         ):
             before = 1
@@ -690,7 +697,7 @@ def _maybe_empty_lines(self, current_line: Line) -> Tuple[int, int]:
         if (
             self.previous_line
             and self.previous_line.is_class
-            and current_line.is_triple_quoted_string
+            and current_line.is_docstring
         ):
             if Preview.no_blank_line_before_class_docstring in current_line.mode:
                 return 0, 1
@@ -701,7 +708,7 @@ def _maybe_empty_lines(self, current_line: Line) -> Tuple[int, int]:
         is_empty_first_line_ok = (
             Preview.allow_empty_first_line_in_block in current_line.mode
             and (
-                not is_docstring(current_line.leaves[0])
+                not is_docstring(current_line.leaves[0], current_line.mode)
                 or (
                     self.previous_line
                     and self.previous_line.leaves[0]
diff --git a/src/black/mode.py b/src/black/mode.py
index 38b861e39ca..466b78228fc 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -195,6 +195,7 @@ class Preview(Enum):
     single_line_format_skip_with_multiple_comments = auto()
     long_case_block_line_splitting = auto()
     allow_form_feeds = auto()
+    unify_docstring_detection = auto()
     respect_east_asian_width = auto()
 
 
diff --git a/src/black/nodes.py b/src/black/nodes.py
index a4f555b4032..8e0f27e3ded 100644
--- a/src/black/nodes.py
+++ b/src/black/nodes.py
@@ -531,7 +531,7 @@ def is_arith_like(node: LN) -> bool:
     }
 
 
-def is_docstring(leaf: Leaf) -> bool:
+def is_docstring(leaf: Leaf, mode: Mode) -> bool:
     if leaf.type != token.STRING:
         return False
 
@@ -539,6 +539,16 @@ def is_docstring(leaf: Leaf) -> bool:
     if set(prefix).intersection("bBfF"):
         return False
 
+    if (
+        Preview.unify_docstring_detection in mode
+        and leaf.parent
+        and leaf.parent.type == syms.simple_stmt
+        and not leaf.parent.prev_sibling
+        and leaf.parent.parent
+        and leaf.parent.parent.type == syms.file_input
+    ):
+        return True
+
     if prev_siblings_are(
         leaf.parent, [None, token.NEWLINE, token.INDENT, syms.simple_stmt]
     ):
diff --git a/src/black/strings.py b/src/black/strings.py
index 0d30f09ed11..0e0f968824b 100644
--- a/src/black/strings.py
+++ b/src/black/strings.py
@@ -63,6 +63,8 @@ def lines_with_leading_tabs_expanded(s: str) -> List[str]:
             )
         else:
             lines.append(line)
+    if s.endswith("\n"):
+        lines.append("")
     return lines
 
 
diff --git a/tests/data/cases/module_docstring_2.py b/tests/data/cases/module_docstring_2.py
index e1f81b4d76b..1cc9aea9aea 100644
--- a/tests/data/cases/module_docstring_2.py
+++ b/tests/data/cases/module_docstring_2.py
@@ -1,6 +1,7 @@
 # flags: --preview
 """I am a very helpful module docstring.
 
+With trailing spaces:      
 Lorem ipsum dolor sit amet, consectetur adipiscing elit,
 sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
 Ut enim ad minim veniam,
@@ -38,6 +39,7 @@
 # output
 """I am a very helpful module docstring.
 
+With trailing spaces:
 Lorem ipsum dolor sit amet, consectetur adipiscing elit,
 sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
 Ut enim ad minim veniam,
diff --git a/tests/data/cases/preview_no_blank_line_before_docstring.py b/tests/data/cases/preview_no_blank_line_before_docstring.py
index 303035a7efb..faeaa1e46e4 100644
--- a/tests/data/cases/preview_no_blank_line_before_docstring.py
+++ b/tests/data/cases/preview_no_blank_line_before_docstring.py
@@ -29,6 +29,9 @@ class MultilineDocstringsAsWell:
     and on so many lines...
     """
 
+class SingleQuotedDocstring:
+
+    "I'm a docstring but I don't even get triple quotes."
 
 # output
 
@@ -57,3 +60,7 @@ class MultilineDocstringsAsWell:
 
     and on so many lines...
     """
+
+
+class SingleQuotedDocstring:
+    "I'm a docstring but I don't even get triple quotes."

From c35924663cff4f696f9bb91ca9c7775487d95ac6 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 1 Jan 2024 15:12:18 -0800
Subject: [PATCH 0972/1034] [pre-commit.ci] pre-commit autoupdate (#4139)

---
 .pre-commit-config.yaml | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 2896489d724..13479565527 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -24,7 +24,7 @@ repos:
         additional_dependencies: *version_check_dependencies
 
   - repo: https://github.com/pycqa/isort
-    rev: 5.12.0
+    rev: 5.13.2
     hooks:
       - id: isort
 
@@ -39,7 +39,7 @@ repos:
         exclude: ^src/blib2to3/
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.7.1
+    rev: v1.8.0
     hooks:
       - id: mypy
         exclude: ^docs/conf.py
@@ -58,13 +58,13 @@ repos:
           - hypothesmith
 
   - repo: https://github.com/pre-commit/mirrors-prettier
-    rev: v3.0.3
+    rev: v4.0.0-alpha.8
     hooks:
       - id: prettier
         exclude: \.github/workflows/diff_shades\.yml
 
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.4.0
+    rev: v4.5.0
     hooks:
       - id: end-of-file-fixer
       - id: trailing-whitespace

From fe3376141c333271d3c64d7fa0e433652e2b48ff Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Mon, 1 Jan 2024 15:46:09 -0800
Subject: [PATCH 0973/1034] Allow empty lines at beginnings of more blocks
 (#4130)

Fixes #4043, fixes #619

These include nested functions and methods.

I think the nested function case quite clearly improves readability. I
think the method case improves consistency, adherence to PEP 8 and
resolves a point of contention.
---
 CHANGES.md                                    |  2 ++
 src/black/lines.py                            |  5 ++++-
 tests/data/cases/class_blank_parentheses.py   |  1 +
 .../cases/preview_allow_empty_first_line.py   | 19 +++++++++++++++++++
 tests/data/cases/preview_form_feeds.py        |  1 +
 5 files changed, 27 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index a6587cc5ceb..fca88612afe 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -17,6 +17,8 @@
 - Format module docstrings the same as class and function docstrings (#4095)
 - Fix bug where spaces were not added around parenthesized walruses in subscripts,
   unlike other binary operators (#4109)
+- Address a missing case in the change to allow empty lines at the beginning of all
+  blocks, except immediately before a docstring (#4130)
 
 ### Configuration
 
diff --git a/src/black/lines.py b/src/black/lines.py
index 8d02267a85b..4d4f47a44e8 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -745,7 +745,10 @@ def _maybe_empty_lines_for_class_or_def(  # noqa: C901
         if self.previous_line.depth < current_line.depth and (
             self.previous_line.is_class or self.previous_line.is_def
         ):
-            return 0, 0
+            if self.mode.is_pyi or not Preview.allow_empty_first_line_in_block:
+                return 0, 0
+            else:
+                return 1 if user_had_newline else 0, 0
 
         comment_to_add_newlines: Optional[LinesBlock] = None
         if (
diff --git a/tests/data/cases/class_blank_parentheses.py b/tests/data/cases/class_blank_parentheses.py
index 1a5721a2889..3c460d9bd79 100644
--- a/tests/data/cases/class_blank_parentheses.py
+++ b/tests/data/cases/class_blank_parentheses.py
@@ -39,6 +39,7 @@ def test_func(self):
 
 
 class ClassWithEmptyFunc(object):
+
     def func_with_blank_parentheses():
         return 5
 
diff --git a/tests/data/cases/preview_allow_empty_first_line.py b/tests/data/cases/preview_allow_empty_first_line.py
index 3e14fa15250..daf78344ad7 100644
--- a/tests/data/cases/preview_allow_empty_first_line.py
+++ b/tests/data/cases/preview_allow_empty_first_line.py
@@ -62,6 +62,15 @@ def method(self):
 
         pass
 
+
+def top_level(
+    a: int,
+    b: str,
+) -> Whatever[Generic, Something]:
+
+    def nested(x: int) -> int:
+        pass
+
 # output
 
 def foo():
@@ -123,6 +132,16 @@ def quux():
 
 
 class Cls:
+
     def method(self):
 
         pass
+
+
+def top_level(
+    a: int,
+    b: str,
+) -> Whatever[Generic, Something]:
+
+    def nested(x: int) -> int:
+        pass
diff --git a/tests/data/cases/preview_form_feeds.py b/tests/data/cases/preview_form_feeds.py
index c236f177a95..dc3bd6cfe2e 100644
--- a/tests/data/cases/preview_form_feeds.py
+++ b/tests/data/cases/preview_form_feeds.py
@@ -203,6 +203,7 @@ def bar(a=1, b: bool = False):
 
 
 class Baz:
+
     def __init__(self):
         pass
 

From b9ad4da2e81f6ec66d292b85f284889211e052b4 Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Mon, 1 Jan 2024 16:55:25 -0800
Subject: [PATCH 0974/1034] Revert "confine pre-commit to stages (#3940)"
 (#4137)

This reverts commit 7686989fc89aad5ea235a34977ebf8c81c26c4eb.
---
 .pre-commit-hooks.yaml | 2 --
 CHANGES.md             | 3 +++
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/.pre-commit-hooks.yaml b/.pre-commit-hooks.yaml
index 54a03efe7a1..a1ff41fded8 100644
--- a/.pre-commit-hooks.yaml
+++ b/.pre-commit-hooks.yaml
@@ -4,7 +4,6 @@
   name: black
   description: "Black: The uncompromising Python code formatter"
   entry: black
-  stages: [pre-commit, pre-merge-commit, pre-push, manual]
   language: python
   minimum_pre_commit_version: 2.9.2
   require_serial: true
@@ -14,7 +13,6 @@
   description:
     "Black: The uncompromising Python code formatter (with Jupyter Notebook support)"
   entry: black
-  stages: [pre-commit, pre-merge-commit, pre-push, manual]
   language: python
   minimum_pre_commit_version: 2.9.2
   require_serial: true
diff --git a/CHANGES.md b/CHANGES.md
index fca88612afe..360319ac964 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -50,6 +50,9 @@
 
 <!-- For example, Docker, GitHub Actions, pre-commit, editors -->
 
+- Revert the change to run Black's pre-commit integration only on specific git hooks
+  (#3940) for better compatibility with older versions of pre-commit (#4137)
+
 ### Documentation
 
 <!-- Major changes to documentation and policies. Small docs changes

From 8e0a9dee1bc5afa1ac089e1cffe2b4417f9a719c Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Mon, 1 Jan 2024 16:56:39 -0800
Subject: [PATCH 0975/1034] Remove empty lines before docstrings in async
 functions (#4132)

---
 CHANGES.md                                    |  1 +
 src/black/lines.py                            | 10 ++--------
 src/black/nodes.py                            |  4 ----
 .../cases/preview_allow_empty_first_line.py   | 20 +++++++++++++++++++
 4 files changed, 23 insertions(+), 12 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 360319ac964..0e3ba58014b 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -17,6 +17,7 @@
 - Format module docstrings the same as class and function docstrings (#4095)
 - Fix bug where spaces were not added around parenthesized walruses in subscripts,
   unlike other binary operators (#4109)
+- Remove empty lines before docstrings in async functions (#4132)
 - Address a missing case in the change to allow empty lines at the beginning of all
   blocks, except immediately before a docstring (#4130)
 
diff --git a/src/black/lines.py b/src/black/lines.py
index 4d4f47a44e8..0c3f1666d1f 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -24,7 +24,6 @@
     TEST_DESCENDANTS,
     child_towards,
     is_docstring,
-    is_funcdef,
     is_import,
     is_multiline_string,
     is_one_sequence_between,
@@ -708,13 +707,8 @@ def _maybe_empty_lines(self, current_line: Line) -> Tuple[int, int]:
         is_empty_first_line_ok = (
             Preview.allow_empty_first_line_in_block in current_line.mode
             and (
-                not is_docstring(current_line.leaves[0], current_line.mode)
-                or (
-                    self.previous_line
-                    and self.previous_line.leaves[0]
-                    and self.previous_line.leaves[0].parent
-                    and not is_funcdef(self.previous_line.leaves[0].parent)
-                )
+                not current_line.is_docstring
+                or (self.previous_line and not self.previous_line.is_def)
             )
         )
 
diff --git a/src/black/nodes.py b/src/black/nodes.py
index 8e0f27e3ded..d45d40c01c2 100644
--- a/src/black/nodes.py
+++ b/src/black/nodes.py
@@ -742,10 +742,6 @@ def is_multiline_string(leaf: Leaf) -> bool:
     return has_triple_quotes(leaf.value) and "\n" in leaf.value
 
 
-def is_funcdef(node: Node) -> bool:
-    return node.type == syms.funcdef
-
-
 def is_function_or_class(node: Node) -> bool:
     return node.type in {syms.funcdef, syms.classdef, syms.async_funcdef}
 
diff --git a/tests/data/cases/preview_allow_empty_first_line.py b/tests/data/cases/preview_allow_empty_first_line.py
index daf78344ad7..4269987305d 100644
--- a/tests/data/cases/preview_allow_empty_first_line.py
+++ b/tests/data/cases/preview_allow_empty_first_line.py
@@ -63,6 +63,17 @@ def method(self):
         pass
 
 
+async def async_fn():
+
+    """Docstring."""
+
+
+@decorated
+async def async_fn():
+
+    """Docstring."""
+
+    
 def top_level(
     a: int,
     b: str,
@@ -138,6 +149,15 @@ def method(self):
         pass
 
 
+async def async_fn():
+    """Docstring."""
+
+
+@decorated
+async def async_fn():
+    """Docstring."""
+
+
 def top_level(
     a: int,
     b: str,

From 269190274b8dc134c9c107ada8f386594a8c62cf Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Mon, 1 Jan 2024 17:29:21 -0800
Subject: [PATCH 0976/1034] Clean up dead code in magic trailing comma logic
 (#4131)

---
 src/black/lines.py | 13 +++++--------
 1 file changed, 5 insertions(+), 8 deletions(-)

diff --git a/src/black/lines.py b/src/black/lines.py
index 0c3f1666d1f..b544c5e0035 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -91,7 +91,7 @@ def append(
             if self.mode.magic_trailing_comma:
                 if self.has_magic_trailing_comma(leaf):
                     self.magic_trailing_comma = leaf
-            elif self.has_magic_trailing_comma(leaf, ensure_removable=True):
+            elif self.has_magic_trailing_comma(leaf):
                 self.remove_trailing_comma()
         if not self.append_comment(leaf):
             self.leaves.append(leaf)
@@ -342,16 +342,11 @@ def contains_unsplittable_type_ignore(self) -> bool:
     def contains_multiline_strings(self) -> bool:
         return any(is_multiline_string(leaf) for leaf in self.leaves)
 
-    def has_magic_trailing_comma(
-        self, closing: Leaf, ensure_removable: bool = False
-    ) -> bool:
+    def has_magic_trailing_comma(self, closing: Leaf) -> bool:
         """Return True if we have a magic trailing comma, that is when:
         - there's a trailing comma here
+        - it's not from single-element square bracket indexing
         - it's not a one-tuple
-        - it's not a single-element subscript
-        Additionally, if ensure_removable:
-        - it's not from square bracket indexing
-        (specifically, single-element square bracket indexing)
         """
         if not (
             closing.type in CLOSING_BRACKETS
@@ -375,6 +370,8 @@ def has_magic_trailing_comma(
                     brackets=(token.LSQB, token.RSQB),
                 )
             ):
+                assert closing.prev_sibling is not None
+                assert closing.prev_sibling.type == syms.subscriptlist
                 return False
 
             return True

From 4ceed0b95803abd999da7d89df2821346a94571a Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Mon, 1 Jan 2024 17:36:49 -0800
Subject: [PATCH 0977/1034] Remove is_function_or_class helper footgun (#4133)

This is a no-op change.

That function was not a good way to tell if something is a function or a
class, since it basically only worked for async functions by accident
(the parent of a suite / simple_stmt of async function body is a
funcdef).
---
 src/black/linegen.py                          |  4 ++--
 src/black/nodes.py                            |  9 +++++++-
 .../cases/preview_dummy_implementations.py    | 22 +++++++++++++++++++
 3 files changed, 32 insertions(+), 3 deletions(-)

diff --git a/src/black/linegen.py b/src/black/linegen.py
index 0972cf432e1..574c89b880c 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -42,12 +42,12 @@
     is_atom_with_invisible_parens,
     is_docstring,
     is_empty_tuple,
-    is_function_or_class,
     is_lpar_token,
     is_multiline_string,
     is_name_token,
     is_one_sequence_between,
     is_one_tuple,
+    is_parent_function_or_class,
     is_rpar_token,
     is_stub_body,
     is_stub_suite,
@@ -302,7 +302,7 @@ def visit_simple_stmt(self, node: Node) -> Iterator[Line]:
 
         if node.parent and node.parent.type in STATEMENT:
             if Preview.dummy_implementations in self.mode:
-                condition = is_function_or_class(node.parent)
+                condition = is_parent_function_or_class(node)
             else:
                 condition = self.mode.is_pyi
             if condition and is_stub_body(node):
diff --git a/src/black/nodes.py b/src/black/nodes.py
index d45d40c01c2..7ee2df2e061 100644
--- a/src/black/nodes.py
+++ b/src/black/nodes.py
@@ -742,6 +742,13 @@ def is_multiline_string(leaf: Leaf) -> bool:
     return has_triple_quotes(leaf.value) and "\n" in leaf.value
 
 
+def is_parent_function_or_class(node: Node) -> bool:
+    assert node.type in {syms.suite, syms.simple_stmt}
+    assert node.parent is not None
+    # Note this works for suites / simple_stmts in async def as well
+    return node.parent.type in {syms.funcdef, syms.classdef}
+
+
 def is_function_or_class(node: Node) -> bool:
     return node.type in {syms.funcdef, syms.classdef, syms.async_funcdef}
 
@@ -751,7 +758,7 @@ def is_stub_suite(node: Node, mode: Mode) -> bool:
     if (
         node.parent is not None
         and Preview.dummy_implementations in mode
-        and not is_function_or_class(node.parent)
+        and not is_parent_function_or_class(node)
     ):
         return False
 
diff --git a/tests/data/cases/preview_dummy_implementations.py b/tests/data/cases/preview_dummy_implementations.py
index 28b23bb8609..3cd392c9587 100644
--- a/tests/data/cases/preview_dummy_implementations.py
+++ b/tests/data/cases/preview_dummy_implementations.py
@@ -58,6 +58,17 @@ def has_comment():
 
 if already_dummy: ...
 
+class AsyncCls:
+    async def async_method(self):
+        ...
+
+async def async_function(self):
+    ...
+
+@decorated
+async def async_function(self):
+    ...
+
 # output
 
 from typing import NoReturn, Protocol, Union, overload
@@ -121,3 +132,14 @@ def has_comment(): ...  # still a dummy
 
 if already_dummy:
     ...
+
+
+class AsyncCls:
+    async def async_method(self): ...
+
+
+async def async_function(self): ...
+
+
+@decorated
+async def async_function(self): ...

From b1d17ef9a2579d10e5e31d3bb9e0a31dee95d7e9 Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Mon, 1 Jan 2024 17:55:11 -0800
Subject: [PATCH 0978/1034] Fix comment handling when parenthesising
 conditional expressions (#4134)

Fixes #3555
---
 CHANGES.md                                 |  1 +
 src/black/linegen.py                       |  4 +++
 tests/data/cases/conditional_expression.py | 42 ++++++++++++++++++++++
 3 files changed, 47 insertions(+)

diff --git a/CHANGES.md b/CHANGES.md
index 0e3ba58014b..3dc0c87f89a 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -14,6 +14,7 @@
 
 <!-- Changes that affect Black's preview style -->
 
+- Fix comment handling when parenthesising conditional expressions (#4134)
 - Format module docstrings the same as class and function docstrings (#4095)
 - Fix bug where spaces were not added around parenthesized walruses in subscripts,
   unlike other binary operators (#4109)
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 574c89b880c..4d468ce0f2e 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -170,8 +170,12 @@ def visit_test(self, node: Node) -> Iterator[Line]:
             )
 
             if not already_parenthesized:
+                # Similar to logic in wrap_in_parentheses
                 lpar = Leaf(token.LPAR, "")
                 rpar = Leaf(token.RPAR, "")
+                prefix = node.prefix
+                node.prefix = ""
+                lpar.prefix = prefix
                 node.insert_child(0, lpar)
                 node.append_child(rpar)
 
diff --git a/tests/data/cases/conditional_expression.py b/tests/data/cases/conditional_expression.py
index c30cd76c791..76251bd9318 100644
--- a/tests/data/cases/conditional_expression.py
+++ b/tests/data/cases/conditional_expression.py
@@ -67,6 +67,28 @@ def something():
         else ValuesListIterable
     )
 
+
+def foo(wait: bool = True):
+    # This comment is two
+    # lines long
+
+    # This is only one
+    time.sleep(1) if wait else None
+    time.sleep(1) if wait else None
+
+    # With newline above
+    time.sleep(1) if wait else None
+    # Without newline above
+    time.sleep(1) if wait else None
+
+
+a = "".join(
+    (
+        "",  # comment
+        "" if True else "",
+    )
+)
+
 # output
 
 long_kwargs_single_line = my_function(
@@ -159,3 +181,23 @@ def something():
         if named
         else FlatValuesListIterable if flat else ValuesListIterable
     )
+
+
+def foo(wait: bool = True):
+    # This comment is two
+    # lines long
+
+    # This is only one
+    time.sleep(1) if wait else None
+    time.sleep(1) if wait else None
+
+    # With newline above
+    time.sleep(1) if wait else None
+    # Without newline above
+    time.sleep(1) if wait else None
+
+
+a = "".join((
+    "",  # comment
+    "" if True else "",
+))

From e11eaf2f44d3db5713fb99bdec966ba974b60c8c Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Mon, 1 Jan 2024 20:14:57 -0800
Subject: [PATCH 0979/1034] Make `blank_line_after_nested_stub_class` work for
 methods (#4141)

Fixes #4113

Authored by dhruvmanila
---
 CHANGES.md                      |  1 +
 src/black/lines.py              |  8 ++++----
 tests/data/cases/nested_stub.py | 27 ++++++++++++++++++++++++++-
 3 files changed, 31 insertions(+), 5 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 3dc0c87f89a..8fb8677dd77 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -21,6 +21,7 @@
 - Remove empty lines before docstrings in async functions (#4132)
 - Address a missing case in the change to allow empty lines at the beginning of all
   blocks, except immediately before a docstring (#4130)
+- For stubs, fix logic to enforce empty line after nested classes with bodies (#4141)
 
 ### Configuration
 
diff --git a/src/black/lines.py b/src/black/lines.py
index b544c5e0035..9eb5785da57 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -640,15 +640,15 @@ def _maybe_empty_lines(self, current_line: Line) -> Tuple[int, int]:
         if previous_def is not None:
             assert self.previous_line is not None
             if self.mode.is_pyi:
-                if depth and not current_line.is_def and self.previous_line.is_def:
-                    # Empty lines between attributes and methods should be preserved.
-                    before = 1 if user_had_newline else 0
-                elif (
+                if (
                     Preview.blank_line_after_nested_stub_class in self.mode
                     and previous_def.is_class
                     and not previous_def.is_stub_class
                 ):
                     before = 1
+                elif depth and not current_line.is_def and self.previous_line.is_def:
+                    # Empty lines between attributes and methods should be preserved.
+                    before = 1 if user_had_newline else 0
                 elif depth:
                     before = 0
                 else:
diff --git a/tests/data/cases/nested_stub.py b/tests/data/cases/nested_stub.py
index b81549ec115..ef13c588ce6 100644
--- a/tests/data/cases/nested_stub.py
+++ b/tests/data/cases/nested_stub.py
@@ -18,6 +18,18 @@ def function_definition(self): ...
         assignment = 1
     def f2(self) -> str: ...
 
+
+class TopLevel:
+    class Nested1:
+        foo: int
+        def bar(self): ...
+    field = 1
+
+    class Nested2:
+        def bar(self): ...
+        foo: int
+    field = 1
+
 # output
 
 import sys
@@ -41,4 +53,17 @@ def f1(self) -> str: ...
         def function_definition(self): ...
         assignment = 1
 
-    def f2(self) -> str: ...
\ No newline at end of file
+    def f2(self) -> str: ...
+
+class TopLevel:
+    class Nested1:
+        foo: int
+        def bar(self): ...
+
+    field = 1
+
+    class Nested2:
+        def bar(self): ...
+        foo: int
+
+    field = 1

From b7c3a9fedd4cfcc6a6a88aacc7b0f599b63d4716 Mon Sep 17 00:00:00 2001
From: Dragorn421 <Dragorn421@users.noreply.github.com>
Date: Thu, 11 Jan 2024 16:46:17 +0100
Subject: [PATCH 0980/1034] Docs: Add note on `--exclude` about possibly
 verbose regex (#4145)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 docs/usage_and_configuration/the_basics.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index 4f9856c6a47..b541f07907c 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -268,6 +268,11 @@ recursive searches. An empty value means no paths are excluded. Use forward slas
 directories on all platforms (Windows, too). By default, Black also ignores all paths
 listed in `.gitignore`. Changing this value will override all default exclusions.
 
+If the regular expression contains newlines, it is treated as a
+[verbose regular expression](https://docs.python.org/3/library/re.html#re.VERBOSE). This
+is typically useful when setting these options in a `pyproject.toml` configuration file;
+see [Configuration format](#configuration-format) for more information.
+
 #### `--extend-exclude`
 
 Like `--exclude`, but adds additional files and directories on top of the default values

From 9a331d606f3fd60cac19bfbfc3f98cbe8be2517d Mon Sep 17 00:00:00 2001
From: cobalt <61329810+RedGuy12@users.noreply.github.com>
Date: Wed, 17 Jan 2024 13:04:15 -0600
Subject: [PATCH 0981/1034] fix: Don't allow unparenthesizing walruses (#4155)

Signed-off-by: RedGuy12 <61329810+RedGuy12@users.noreply.github.com>
Signed-off-by: RedGuy12 <paul@reid-family.org>
---
 CHANGES.md                         | 1 +
 src/black/linegen.py               | 6 +++++-
 tests/data/cases/walrus_in_dict.py | 7 +++++++
 3 files changed, 13 insertions(+), 1 deletion(-)
 create mode 100644 tests/data/cases/walrus_in_dict.py

diff --git a/CHANGES.md b/CHANGES.md
index 8fb8677dd77..2bd58ed49ff 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -22,6 +22,7 @@
 - Address a missing case in the change to allow empty lines at the beginning of all
   blocks, except immediately before a docstring (#4130)
 - For stubs, fix logic to enforce empty line after nested classes with bodies (#4141)
+- Fix crash when using a walrus in a dictionary (#4155)
 
 ### Configuration
 
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 4d468ce0f2e..9a3eb0ce73f 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -242,7 +242,11 @@ def visit_dictsetmaker(self, node: Node) -> Iterator[Line]:
                 if i == 0:
                     continue
                 if node.children[i - 1].type == token.COLON:
-                    if child.type == syms.atom and child.children[0].type == token.LPAR:
+                    if (
+                        child.type == syms.atom
+                        and child.children[0].type == token.LPAR
+                        and not is_walrus_assignment(child)
+                    ):
                         if maybe_make_parens_invisible_in_atom(
                             child,
                             parent=node,
diff --git a/tests/data/cases/walrus_in_dict.py b/tests/data/cases/walrus_in_dict.py
new file mode 100644
index 00000000000..c33eecd84a6
--- /dev/null
+++ b/tests/data/cases/walrus_in_dict.py
@@ -0,0 +1,7 @@
+# flags: --preview
+{
+    "is_update": (up := commit.hash in update_hashes)
+}
+
+# output
+{"is_update": (up := commit.hash in update_hashes)}

From 7f60f3dbd7d2d36011fbae6c140b35802932952b Mon Sep 17 00:00:00 2001
From: Kevin Paulson <kevin.paulson@mindbridge.ai>
Date: Fri, 19 Jan 2024 18:54:32 -0500
Subject: [PATCH 0982/1034] Update using_black_with_other_tools.md to ensure
 flake8 configuration examples are consistant (#4157)

---
 docs/guides/using_black_with_other_tools.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/guides/using_black_with_other_tools.md b/docs/guides/using_black_with_other_tools.md
index 22c641a7420..e642a1aef33 100644
--- a/docs/guides/using_black_with_other_tools.md
+++ b/docs/guides/using_black_with_other_tools.md
@@ -145,7 +145,7 @@ There are a few deviations that cause incompatibilities with _Black_.
 
 ```
 max-line-length = 88
-extend-ignore = E203
+extend-ignore = E203, E704
 ```
 
 #### Why those options above?
@@ -184,7 +184,7 @@ extend-ignore = E203, E704
 ```ini
 [flake8]
 max-line-length = 88
-extend-ignore = E203
+extend-ignore = E203, E704
 ```
 
 </details>
@@ -195,7 +195,7 @@ extend-ignore = E203
 ```ini
 [flake8]
 max-line-length = 88
-extend-ignore = E203
+extend-ignore = E203, E704
 ```
 
 </details>

From 995e4ada14d63a9bec39c5fc83275d0e49742618 Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Fri, 19 Jan 2024 17:13:26 -0800
Subject: [PATCH 0983/1034] Fix unnecessary nesting when wrapping long dict
 (#4135)

Fixes #4129
---
 CHANGES.md                                   |  1 +
 src/black/linegen.py                         |  7 ++--
 tests/data/cases/preview_long_dict_values.py | 38 ++++++++++++++++++++
 3 files changed, 42 insertions(+), 4 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 2bd58ed49ff..1e75fb58563 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -23,6 +23,7 @@
   blocks, except immediately before a docstring (#4130)
 - For stubs, fix logic to enforce empty line after nested classes with bodies (#4141)
 - Fix crash when using a walrus in a dictionary (#4155)
+- Fix unnecessary parentheses when wrapping long dicts (#4135)
 
 ### Configuration
 
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 9a3eb0ce73f..dd296eb801d 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -244,15 +244,14 @@ def visit_dictsetmaker(self, node: Node) -> Iterator[Line]:
                 if node.children[i - 1].type == token.COLON:
                     if (
                         child.type == syms.atom
-                        and child.children[0].type == token.LPAR
+                        and child.children[0].type in OPENING_BRACKETS
                         and not is_walrus_assignment(child)
                     ):
-                        if maybe_make_parens_invisible_in_atom(
+                        maybe_make_parens_invisible_in_atom(
                             child,
                             parent=node,
                             remove_brackets_around_comma=False,
-                        ):
-                            wrap_in_parentheses(node, child, visible=False)
+                        )
                     else:
                         wrap_in_parentheses(node, child, visible=False)
         yield from self.visit_default(node)
diff --git a/tests/data/cases/preview_long_dict_values.py b/tests/data/cases/preview_long_dict_values.py
index fbbacd13d1d..54da76038dc 100644
--- a/tests/data/cases/preview_long_dict_values.py
+++ b/tests/data/cases/preview_long_dict_values.py
@@ -37,6 +37,26 @@
 }
 
 
+class Random:
+    def func():
+        random_service.status.active_states.inactive = (
+            make_new_top_level_state_from_dict(
+                {
+                    "topLevelBase": {
+                        "secondaryBase": {
+                            "timestamp": 1234,
+                            "latitude": 1,
+                            "longitude": 2,
+                            "actionTimestamp": Timestamp(
+                                seconds=1530584000, nanos=0
+                            ).ToJsonString(),
+                        }
+                    },
+                }
+            )
+        )
+
+
 # output
 
 
@@ -89,3 +109,21 @@
         }
     ),
 }
+
+
+class Random:
+    def func():
+        random_service.status.active_states.inactive = (
+            make_new_top_level_state_from_dict({
+                "topLevelBase": {
+                    "secondaryBase": {
+                        "timestamp": 1234,
+                        "latitude": 1,
+                        "longitude": 2,
+                        "actionTimestamp": (
+                            Timestamp(seconds=1530584000, nanos=0).ToJsonString()
+                        ),
+                    }
+                },
+            })
+        )

From 6f3fb78444655f883780dcc19349226833c677c1 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 22 Jan 2024 09:22:56 -0800
Subject: [PATCH 0984/1034] Bump actions/cache from 3 to 4 (#4162)

Bumps [actions/cache](https://github.com/actions/cache) from 3 to 4.
- [Release notes](https://github.com/actions/cache/releases)
- [Changelog](https://github.com/actions/cache/blob/main/RELEASES.md)
- [Commits](https://github.com/actions/cache/compare/v3...v4)

---
updated-dependencies:
- dependency-name: actions/cache
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/diff_shades.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/diff_shades.yml b/.github/workflows/diff_shades.yml
index 8d8be2550b0..0e1aab00e34 100644
--- a/.github/workflows/diff_shades.yml
+++ b/.github/workflows/diff_shades.yml
@@ -72,7 +72,7 @@ jobs:
 
       - name: Attempt to use cached baseline analysis
         id: baseline-cache
-        uses: actions/cache@v3
+        uses: actions/cache@v4
         with:
           path: ${{ matrix.baseline-analysis }}
           key: ${{ matrix.baseline-cache-key }}

From 8fe602b1fa91dc6db682d1dba79a8a7341597271 Mon Sep 17 00:00:00 2001
From: Daniel Krzeminski <dankrzeminski32@gmail.com>
Date: Mon, 22 Jan 2024 11:46:57 -0600
Subject: [PATCH 0985/1034] fix pathlib exception handling with symlinks
 (#4161)

Fixes #4077
---
 CHANGES.md            |  2 ++
 src/black/__init__.py |  6 +++++-
 src/black/files.py    | 24 ++++++++++++++++--------
 tests/test_black.py   | 14 ++++++++++++++
 4 files changed, 37 insertions(+), 9 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 1e75fb58563..f29834a3f7f 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -29,6 +29,8 @@
 
 <!-- Changes to how Black can be configured -->
 
+- Fix symlink handling, properly catch and ignore symlinks that point outside of root
+  (#4161)
 - Fix cache mtime logic that resulted in false positive cache hits (#4128)
 
 ### Packaging
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 735ba713b8f..e3cbaab5f1d 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -49,6 +49,7 @@
     find_user_pyproject_toml,
     gen_python_files,
     get_gitignore,
+    get_root_relative_path,
     normalize_path_maybe_ignore,
     parse_pyproject_toml,
     path_is_excluded,
@@ -700,7 +701,10 @@ def get_sources(
 
         # Compare the logic here to the logic in `gen_python_files`.
         if is_stdin or path.is_file():
-            root_relative_path = path.absolute().relative_to(root).as_posix()
+            root_relative_path = get_root_relative_path(path, root, report)
+
+            if root_relative_path is None:
+                continue
 
             root_relative_path = "/" + root_relative_path
 
diff --git a/src/black/files.py b/src/black/files.py
index 858303ca1a3..65951efdbe8 100644
--- a/src/black/files.py
+++ b/src/black/files.py
@@ -259,14 +259,7 @@ def normalize_path_maybe_ignore(
     try:
         abspath = path if path.is_absolute() else Path.cwd() / path
         normalized_path = abspath.resolve()
-        try:
-            root_relative_path = normalized_path.relative_to(root).as_posix()
-        except ValueError:
-            if report:
-                report.path_ignored(
-                    path, f"is a symbolic link that points outside {root}"
-                )
-            return None
+        root_relative_path = get_root_relative_path(normalized_path, root, report)
 
     except OSError as e:
         if report:
@@ -276,6 +269,21 @@ def normalize_path_maybe_ignore(
     return root_relative_path
 
 
+def get_root_relative_path(
+    path: Path,
+    root: Path,
+    report: Optional[Report] = None,
+) -> Optional[str]:
+    """Returns the file path relative to the 'root' directory"""
+    try:
+        root_relative_path = path.absolute().relative_to(root).as_posix()
+    except ValueError:
+        if report:
+            report.path_ignored(path, f"is a symbolic link that points outside {root}")
+        return None
+    return root_relative_path
+
+
 def _path_is_ignored(
     root_relative_path: str,
     root: Path,
diff --git a/tests/test_black.py b/tests/test_black.py
index 0af5fd2a1f4..2b5fab5d28d 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -2592,6 +2592,20 @@ def test_symlinks(self) -> None:
         outside_root_symlink.resolve.assert_called_once()
         ignored_symlink.resolve.assert_not_called()
 
+    def test_get_sources_with_stdin_symlink_outside_root(
+        self,
+    ) -> None:
+        path = THIS_DIR / "data" / "include_exclude_tests"
+        stdin_filename = str(path / "b/exclude/a.py")
+        outside_root_symlink = Path("/target_directory/a.py")
+        with patch("pathlib.Path.resolve", return_value=outside_root_symlink):
+            assert_collected_sources(
+                root=Path("target_directory/"),
+                src=["-"],
+                expected=[],
+                stdin_filename=stdin_filename,
+            )
+
     @patch("black.find_project_root", lambda *args: (THIS_DIR.resolve(), None))
     def test_get_sources_with_stdin(self) -> None:
         src = ["-"]

From 59b9d858a30de56801e84c31f57b53337c61647c Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Wed, 24 Jan 2024 17:06:14 -0800
Subject: [PATCH 0986/1034] Create the 2024 stable style (#4106)

---
 CHANGES.md                                    | 40 +++++++-
 src/black/comments.py                         | 32 +++----
 src/black/linegen.py                          | 95 +++++--------------
 src/black/lines.py                            | 63 +++---------
 src/black/mode.py                             | 25 +----
 src/black/nodes.py                            | 14 +--
 ...irst_line.py => allow_empty_first_line.py} |  1 -
 ...{preview_async_stmts.py => async_stmts.py} |  1 -
 tests/data/cases/comments5.py                 |  9 +-
 tests/data/cases/conditional_expression.py    | 11 ++-
 ..._managers_38.py => context_managers_38.py} |  2 +-
 ..._managers_39.py => context_managers_39.py} |  2 +-
 ....py => context_managers_autodetect_310.py} |  2 +-
 ....py => context_managers_autodetect_311.py} |  2 +-
 ...8.py => context_managers_autodetect_38.py} |  1 -
 ...9.py => context_managers_autodetect_39.py} |  2 +-
 ...mentations.py => dummy_implementations.py} |  1 -
 tests/data/cases/empty_lines.py               |  1 +
 tests/data/cases/fmtonoff.py                  |  8 +-
 tests/data/cases/fmtonoff5.py                 |  3 +-
 .../{preview_form_feeds.py => form_feeds.py}  |  1 -
 tests/data/cases/function.py                  |  5 +-
 ...r_match.py => keep_newline_after_match.py} |  6 ++
 .../data/cases/long_strings_flag_disabled.py  | 16 ++--
 tests/data/cases/module_docstring_1.py        |  1 -
 tests/data/cases/module_docstring_2.py        |  4 +-
 tests/data/cases/module_docstring_3.py        |  1 -
 tests/data/cases/module_docstring_4.py        |  1 -
 .../module_docstring_followed_by_class.py     |  1 -
 .../module_docstring_followed_by_function.py  |  1 -
 tests/data/cases/nested_stub.py               |  2 +-
 ...g.py => no_blank_line_before_docstring.py} |  2 +-
 ...ching_long.py => pattern_matching_long.py} |  2 +-
 ....py => pattern_matching_trailing_comma.py} |  2 +-
 .../cases/pep604_union_types_line_breaks.py   |  2 +-
 tests/data/cases/pep_572_py310.py             |  6 +-
 tests/data/cases/pep_572_remove_parens.py     |  8 +-
 .../{preview_pep_572.py => pep_572_slices.py} |  1 -
 ...nt_precedence.py => percent_precedence.py} |  5 +-
 ...op_spacing.py => power_op_spacing_long.py} |  1 -
 ...refer_rhs_split.py => prefer_rhs_split.py} |  1 -
 tests/data/cases/py310_pep572.py              |  2 +-
 tests/data/cases/python39.py                  |  9 +-
 tests/data/cases/raw_docstring.py             |  2 +-
 ... raw_docstring_no_string_normalization.py} |  2 +-
 .../remove_newline_after_code_block_open.py   | 79 +++++++++------
 .../data/cases/return_annotation_brackets.py  | 34 +++----
 ...ine_format_skip_with_multiple_comments.py} |  1 -
 ...ew_trailing_comma.py => trailing_comma.py} |  1 -
 tests/data/cases/walrus_in_dict.py            |  2 +
 50 files changed, 222 insertions(+), 294 deletions(-)
 rename tests/data/cases/{preview_allow_empty_first_line.py => allow_empty_first_line.py} (98%)
 rename tests/data/cases/{preview_async_stmts.py => async_stmts.py} (93%)
 rename tests/data/cases/{preview_context_managers_38.py => context_managers_38.py} (96%)
 rename tests/data/cases/{preview_context_managers_39.py => context_managers_39.py} (98%)
 rename tests/data/cases/{preview_context_managers_autodetect_310.py => context_managers_autodetect_310.py} (93%)
 rename tests/data/cases/{preview_context_managers_autodetect_311.py => context_managers_autodetect_311.py} (92%)
 rename tests/data/cases/{preview_context_managers_autodetect_38.py => context_managers_autodetect_38.py} (98%)
 rename tests/data/cases/{preview_context_managers_autodetect_39.py => context_managers_autodetect_39.py} (93%)
 rename tests/data/cases/{preview_dummy_implementations.py => dummy_implementations.py} (99%)
 rename tests/data/cases/{preview_form_feeds.py => form_feeds.py} (99%)
 rename tests/data/cases/{remove_newline_after_match.py => keep_newline_after_match.py} (98%)
 rename tests/data/cases/{preview_no_blank_line_before_docstring.py => no_blank_line_before_docstring.py} (98%)
 rename tests/data/cases/{preview_pattern_matching_long.py => pattern_matching_long.py} (94%)
 rename tests/data/cases/{preview_pattern_matching_trailing_comma.py => pattern_matching_trailing_comma.py} (92%)
 rename tests/data/cases/{preview_pep_572.py => pep_572_slices.py} (75%)
 rename tests/data/cases/{preview_percent_precedence.py => percent_precedence.py} (91%)
 rename tests/data/cases/{preview_power_op_spacing.py => power_op_spacing_long.py} (99%)
 rename tests/data/cases/{preview_prefer_rhs_split.py => prefer_rhs_split.py} (99%)
 rename tests/data/cases/{preview_docstring_no_string_normalization.py => raw_docstring_no_string_normalization.py} (88%)
 rename tests/data/cases/{preview_single_line_format_skip_with_multiple_comments.py => single_line_format_skip_with_multiple_comments.py} (97%)
 rename tests/data/cases/{preview_trailing_comma.py => trailing_comma.py} (97%)

diff --git a/CHANGES.md b/CHANGES.md
index f29834a3f7f..0e2974d706e 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -6,22 +6,54 @@
 
 <!-- Include any especially major or disruptive changes here -->
 
+This release introduces the new 2024 stable style (#4106), stabilizing the following
+changes:
+
+- Add parentheses around `if`-`else` expressions (#2278)
+- Dummy class and function implementations consisting only of `...` are formatted more
+  compactly (#3796)
+- If an assignment statement is too long, we now prefer splitting on the right-hand side
+  (#3368)
+- Hex codes in Unicode escape sequences are now standardized to lowercase (#2916)
+- Allow empty first lines at the beginning of most blocks (#3967, #4061)
+- Add parentheses around long type annotations (#3899)
+- Standardize on a single newline after module docstrings (#3932)
+- Fix incorrect magic trailing comma handling in return types (#3916)
+- Remove blank lines before class docstrings (#3692)
+- Wrap multiple context managers in parentheses if combined in a single `with` statement
+  (#3489)
+- Fix bug in line length calculations for power operations (#3942)
+- Add trailing commas to collection literals even if there's a comment after the last
+  entry (#3393)
+- When using `--skip-magic-trailing-comma` or `-C`, trailing commas are stripped from
+  subscript expressions with more than 1 element (#3209)
+- Add extra blank lines in stubs in a few cases (#3564, #3862)
+- Accept raw strings as docstrings (#3947)
+- Split long lines in case blocks (#4024)
+- Stop removing spaces from walrus operators within subscripts (#3823)
+- Fix incorrect formatting of certain async statements (#3609)
+- Allow combining `# fmt: skip` with other comments (#3959)
+
 ### Stable style
 
 <!-- Changes that affect Black's stable style -->
 
-### Preview style
-
-<!-- Changes that affect Black's preview style -->
+Several bug fixes were made in features that are moved to the stable style in this
+release:
 
 - Fix comment handling when parenthesising conditional expressions (#4134)
-- Format module docstrings the same as class and function docstrings (#4095)
 - Fix bug where spaces were not added around parenthesized walruses in subscripts,
   unlike other binary operators (#4109)
 - Remove empty lines before docstrings in async functions (#4132)
 - Address a missing case in the change to allow empty lines at the beginning of all
   blocks, except immediately before a docstring (#4130)
 - For stubs, fix logic to enforce empty line after nested classes with bodies (#4141)
+
+### Preview style
+
+<!-- Changes that affect Black's preview style -->
+
+- Format module docstrings the same as class and function docstrings (#4095)
 - Fix crash when using a walrus in a dictionary (#4155)
 - Fix unnecessary parentheses when wrapping long dicts (#4135)
 
diff --git a/src/black/comments.py b/src/black/comments.py
index 52bb024a799..910e1b760f0 100644
--- a/src/black/comments.py
+++ b/src/black/comments.py
@@ -3,7 +3,7 @@
 from functools import lru_cache
 from typing import Collection, Final, Iterator, List, Optional, Tuple, Union
 
-from black.mode import Mode, Preview
+from black.mode import Mode
 from black.nodes import (
     CLOSING_BRACKETS,
     STANDALONE_COMMENT,
@@ -390,22 +390,18 @@ def _contains_fmt_skip_comment(comment_line: str, mode: Mode) -> bool:
       # noqa:XXX # fmt:skip # a nice line  <-- multiple comments (Preview)
       # pylint:XXX; fmt:skip               <-- list of comments (; separated, Preview)
     """
-    semantic_comment_blocks = (
-        [
-            comment_line,
-            *[
-                _COMMENT_PREFIX + comment.strip()
-                for comment in comment_line.split(_COMMENT_PREFIX)[1:]
-            ],
-            *[
-                _COMMENT_PREFIX + comment.strip()
-                for comment in comment_line.strip(_COMMENT_PREFIX).split(
-                    _COMMENT_LIST_SEPARATOR
-                )
-            ],
-        ]
-        if Preview.single_line_format_skip_with_multiple_comments in mode
-        else [comment_line]
-    )
+    semantic_comment_blocks = [
+        comment_line,
+        *[
+            _COMMENT_PREFIX + comment.strip()
+            for comment in comment_line.split(_COMMENT_PREFIX)[1:]
+        ],
+        *[
+            _COMMENT_PREFIX + comment.strip()
+            for comment in comment_line.strip(_COMMENT_PREFIX).split(
+                _COMMENT_LIST_SEPARATOR
+            )
+        ],
+    ]
 
     return any(comment in FMT_SKIP for comment in semantic_comment_blocks)
diff --git a/src/black/linegen.py b/src/black/linegen.py
index dd296eb801d..a276805f2fe 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -115,10 +115,8 @@ def line(self, indent: int = 0) -> Iterator[Line]:
             self.current_line.depth += indent
             return  # Line is empty, don't emit. Creating a new one unnecessary.
 
-        if (
-            Preview.improved_async_statements_handling in self.mode
-            and len(self.current_line.leaves) == 1
-            and is_async_stmt_or_funcdef(self.current_line.leaves[0])
+        if len(self.current_line.leaves) == 1 and is_async_stmt_or_funcdef(
+            self.current_line.leaves[0]
         ):
             # Special case for async def/for/with statements. `visit_async_stmt`
             # adds an `ASYNC` leaf then visits the child def/for/with statement
@@ -164,20 +162,19 @@ def visit_default(self, node: LN) -> Iterator[Line]:
     def visit_test(self, node: Node) -> Iterator[Line]:
         """Visit an `x if y else z` test"""
 
-        if Preview.parenthesize_conditional_expressions in self.mode:
-            already_parenthesized = (
-                node.prev_sibling and node.prev_sibling.type == token.LPAR
-            )
+        already_parenthesized = (
+            node.prev_sibling and node.prev_sibling.type == token.LPAR
+        )
 
-            if not already_parenthesized:
-                # Similar to logic in wrap_in_parentheses
-                lpar = Leaf(token.LPAR, "")
-                rpar = Leaf(token.RPAR, "")
-                prefix = node.prefix
-                node.prefix = ""
-                lpar.prefix = prefix
-                node.insert_child(0, lpar)
-                node.append_child(rpar)
+        if not already_parenthesized:
+            # Similar to logic in wrap_in_parentheses
+            lpar = Leaf(token.LPAR, "")
+            rpar = Leaf(token.RPAR, "")
+            prefix = node.prefix
+            node.prefix = ""
+            lpar.prefix = prefix
+            node.insert_child(0, lpar)
+            node.append_child(rpar)
 
         yield from self.visit_default(node)
 
@@ -292,9 +289,7 @@ def visit_match_case(self, node: Node) -> Iterator[Line]:
 
     def visit_suite(self, node: Node) -> Iterator[Line]:
         """Visit a suite."""
-        if (
-            self.mode.is_pyi or Preview.dummy_implementations in self.mode
-        ) and is_stub_suite(node, self.mode):
+        if is_stub_suite(node):
             yield from self.visit(node.children[2])
         else:
             yield from self.visit_default(node)
@@ -308,11 +303,7 @@ def visit_simple_stmt(self, node: Node) -> Iterator[Line]:
             prev_type = child.type
 
         if node.parent and node.parent.type in STATEMENT:
-            if Preview.dummy_implementations in self.mode:
-                condition = is_parent_function_or_class(node)
-            else:
-                condition = self.mode.is_pyi
-            if condition and is_stub_body(node):
+            if is_parent_function_or_class(node) and is_stub_body(node):
                 yield from self.visit_default(node)
             else:
                 yield from self.line(+1)
@@ -320,11 +311,7 @@ def visit_simple_stmt(self, node: Node) -> Iterator[Line]:
                 yield from self.line(-1)
 
         else:
-            if (
-                not (self.mode.is_pyi or Preview.dummy_implementations in self.mode)
-                or not node.parent
-                or not is_stub_suite(node.parent, self.mode)
-            ):
+            if not node.parent or not is_stub_suite(node.parent):
                 yield from self.line()
             yield from self.visit_default(node)
 
@@ -342,11 +329,7 @@ def visit_async_stmt(self, node: Node) -> Iterator[Line]:
                 break
 
         internal_stmt = next(children)
-        if Preview.improved_async_statements_handling in self.mode:
-            yield from self.visit(internal_stmt)
-        else:
-            for child in internal_stmt.children:
-                yield from self.visit(child)
+        yield from self.visit(internal_stmt)
 
     def visit_decorators(self, node: Node) -> Iterator[Line]:
         """Visit decorators."""
@@ -420,10 +403,9 @@ def foo(a: int, b: float = 7): ...
 
         def foo(a: (int), b: (float) = 7): ...
         """
-        if Preview.parenthesize_long_type_hints in self.mode:
-            assert len(node.children) == 3
-            if maybe_make_parens_invisible_in_atom(node.children[2], parent=node):
-                wrap_in_parentheses(node, node.children[2], visible=False)
+        assert len(node.children) == 3
+        if maybe_make_parens_invisible_in_atom(node.children[2], parent=node):
+            wrap_in_parentheses(node, node.children[2], visible=False)
 
         yield from self.visit_default(node)
 
@@ -529,13 +511,7 @@ def __post_init__(self) -> None:
         self.visit_with_stmt = partial(v, keywords={"with"}, parens={"with"})
         self.visit_classdef = partial(v, keywords={"class"}, parens=Ø)
 
-        # When this is moved out of preview, add ":" directly to ASSIGNMENTS in nodes.py
-        if Preview.parenthesize_long_type_hints in self.mode:
-            assignments = ASSIGNMENTS | {":"}
-        else:
-            assignments = ASSIGNMENTS
-        self.visit_expr_stmt = partial(v, keywords=Ø, parens=assignments)
-
+        self.visit_expr_stmt = partial(v, keywords=Ø, parens=ASSIGNMENTS)
         self.visit_return_stmt = partial(v, keywords={"return"}, parens={"return"})
         self.visit_import_from = partial(v, keywords=Ø, parens={"import"})
         self.visit_del_stmt = partial(v, keywords=Ø, parens={"del"})
@@ -576,9 +552,7 @@ def transform_line(
     # We need the line string when power operators are hugging to determine if we should
     # split the line. Default to line_str, if no power operator are present on the line.
     line_str_hugging_power_ops = (
-        (_hugging_power_ops_line_to_string(line, features, mode) or line_str)
-        if Preview.fix_power_op_line_length in mode
-        else line_str
+        _hugging_power_ops_line_to_string(line, features, mode) or line_str
     )
 
     ll = mode.line_length
@@ -688,9 +662,6 @@ def should_split_funcdef_with_rhs(line: Line, mode: Mode) -> bool:
     """If a funcdef has a magic trailing comma in the return type, then we should first
     split the line with rhs to respect the comma.
     """
-    if Preview.respect_magic_trailing_comma_in_return_type not in mode:
-        return False
-
     return_type_leaves: List[Leaf] = []
     in_return_type = False
 
@@ -919,9 +890,6 @@ def _maybe_split_omitting_optional_parens(
         try:
             # The RHSResult Omitting Optional Parens.
             rhs_oop = _first_right_hand_split(line, omit=omit)
-            prefer_splitting_rhs_mode = (
-                Preview.prefer_splitting_right_hand_side_of_assignments in line.mode
-            )
             is_split_right_after_equal = (
                 len(rhs.head.leaves) >= 2 and rhs.head.leaves[-2].type == token.EQUAL
             )
@@ -937,8 +905,7 @@ def _maybe_split_omitting_optional_parens(
             )
             if (
                 not (
-                    prefer_splitting_rhs_mode
-                    and is_split_right_after_equal
+                    is_split_right_after_equal
                     and rhs_head_contains_brackets
                     and rhs_head_short_enough
                     and rhs_head_explode_blocked_by_magic_trailing_comma
@@ -1224,11 +1191,7 @@ def append_to_line(leaf: Leaf) -> Iterator[Line]:
                     trailing_comma_safe and Feature.TRAILING_COMMA_IN_CALL in features
                 )
 
-        if (
-            Preview.add_trailing_comma_consistently in mode
-            and last_leaf.type == STANDALONE_COMMENT
-            and leaf_idx == last_non_comment_leaf
-        ):
+        if last_leaf.type == STANDALONE_COMMENT and leaf_idx == last_non_comment_leaf:
             current_line = _safe_add_trailing_comma(
                 trailing_comma_safe, delimiter_priority, current_line
             )
@@ -1315,11 +1278,7 @@ def normalize_invisible_parens(  # noqa: C901
 
         # Fixes a bug where invisible parens are not properly wrapped around
         # case blocks.
-        if (
-            isinstance(child, Node)
-            and child.type == syms.case_block
-            and Preview.long_case_block_line_splitting in mode
-        ):
+        if isinstance(child, Node) and child.type == syms.case_block:
             normalize_invisible_parens(
                 child, parens_after={"case"}, mode=mode, features=features
             )
@@ -1374,7 +1333,6 @@ def normalize_invisible_parens(  # noqa: C901
                 and child.next_sibling is not None
                 and child.next_sibling.type == token.COLON
                 and child.value == "case"
-                and Preview.long_case_block_line_splitting in mode
             ):
                 # A special patch for "case case:" scenario, the second occurrence
                 # of case will be not parsed as a Python keyword.
@@ -1448,7 +1406,6 @@ def _maybe_wrap_cms_in_parens(
     """
     if (
         Feature.PARENTHESIZED_CONTEXT_MANAGERS not in features
-        or Preview.wrap_multiple_context_managers_in_parens not in mode
         or len(node.children) <= 2
         # If it's an atom, it's already wrapped in parens.
         or node.children[1].type == syms.atom
diff --git a/src/black/lines.py b/src/black/lines.py
index 9eb5785da57..29f87137614 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -202,9 +202,7 @@ def _is_triple_quoted_string(self) -> bool:
         value = self.leaves[0].value
         if value.startswith(('"""', "'''")):
             return True
-        if Preview.accept_raw_docstrings in self.mode and value.startswith(
-            ("r'''", 'r"""', "R'''", 'R"""')
-        ):
+        if value.startswith(("r'''", 'r"""', "R'''", 'R"""')):
             return True
         return False
 
@@ -450,14 +448,8 @@ def is_complex_subscript(self, leaf: Leaf) -> bool:
             if subscript_start.type == syms.subscriptlist:
                 subscript_start = child_towards(subscript_start, leaf)
 
-        # When this is moved out of preview, add syms.namedexpr_test directly to
-        # TEST_DESCENDANTS in nodes.py
-        if Preview.walrus_subscript in self.mode:
-            test_decendants = TEST_DESCENDANTS | {syms.namedexpr_test}
-        else:
-            test_decendants = TEST_DESCENDANTS
         return subscript_start is not None and any(
-            n.type in test_decendants for n in subscript_start.pre_order()
+            n.type in TEST_DESCENDANTS for n in subscript_start.pre_order()
         )
 
     def enumerate_with_length(
@@ -567,8 +559,7 @@ def maybe_empty_lines(self, current_line: Line) -> LinesBlock:
         lines (two on module-level).
         """
         form_feed = (
-            Preview.allow_form_feeds in self.mode
-            and current_line.depth == 0
+            current_line.depth == 0
             and bool(current_line.leaves)
             and "\f\n" in current_line.leaves[0].prefix
         )
@@ -582,8 +573,7 @@ def maybe_empty_lines(self, current_line: Line) -> LinesBlock:
             else before - previous_after
         )
         if (
-            Preview.module_docstring_newlines in current_line.mode
-            and self.previous_block
+            self.previous_block
             and self.previous_block.previous_block is None
             and len(self.previous_block.original_line.leaves) == 1
             and self.previous_block.original_line.is_docstring
@@ -640,11 +630,7 @@ def _maybe_empty_lines(self, current_line: Line) -> Tuple[int, int]:
         if previous_def is not None:
             assert self.previous_line is not None
             if self.mode.is_pyi:
-                if (
-                    Preview.blank_line_after_nested_stub_class in self.mode
-                    and previous_def.is_class
-                    and not previous_def.is_stub_class
-                ):
+                if previous_def.is_class and not previous_def.is_stub_class:
                     before = 1
                 elif depth and not current_line.is_def and self.previous_line.is_def:
                     # Empty lines between attributes and methods should be preserved.
@@ -695,18 +681,12 @@ def _maybe_empty_lines(self, current_line: Line) -> Tuple[int, int]:
             and self.previous_line.is_class
             and current_line.is_docstring
         ):
-            if Preview.no_blank_line_before_class_docstring in current_line.mode:
-                return 0, 1
-            return before, 1
+            return 0, 1
 
         # In preview mode, always allow blank lines, except right before a function
         # docstring
-        is_empty_first_line_ok = (
-            Preview.allow_empty_first_line_in_block in current_line.mode
-            and (
-                not current_line.is_docstring
-                or (self.previous_line and not self.previous_line.is_def)
-            )
+        is_empty_first_line_ok = not current_line.is_docstring or (
+            self.previous_line and not self.previous_line.is_def
         )
 
         if (
@@ -736,7 +716,7 @@ def _maybe_empty_lines_for_class_or_def(  # noqa: C901
         if self.previous_line.depth < current_line.depth and (
             self.previous_line.is_class or self.previous_line.is_def
         ):
-            if self.mode.is_pyi or not Preview.allow_empty_first_line_in_block:
+            if self.mode.is_pyi:
                 return 0, 0
             else:
                 return 1 if user_had_newline else 0, 0
@@ -776,10 +756,7 @@ def _maybe_empty_lines_for_class_or_def(  # noqa: C901
             # Don't inspect the previous line if it's part of the body of the previous
             # statement in the same level, we always want a blank line if there's
             # something with a body preceding.
-            elif (
-                Preview.blank_line_between_nested_and_def_stub_file in current_line.mode
-                and self.previous_line.depth > current_line.depth
-            ):
+            elif self.previous_line.depth > current_line.depth:
                 newlines = 1
             elif (
                 current_line.is_def or current_line.is_decorator
@@ -800,11 +777,7 @@ def _maybe_empty_lines_for_class_or_def(  # noqa: C901
             newlines = 1 if current_line.depth else 2
             # If a user has left no space after a dummy implementation, don't insert
             # new lines. This is useful for instance for @overload or Protocols.
-            if (
-                Preview.dummy_implementations in self.mode
-                and self.previous_line.is_stub_def
-                and not user_had_newline
-            ):
+            if self.previous_line.is_stub_def and not user_had_newline:
                 newlines = 0
         if comment_to_add_newlines is not None:
             previous_block = comment_to_add_newlines.previous_block
@@ -859,11 +832,9 @@ def is_line_short_enough(  # noqa: C901
     if not line_str:
         line_str = line_to_string(line)
 
-    width = str_width if Preview.respect_east_asian_width in mode else len
-
     if Preview.multiline_string_handling not in mode:
         return (
-            width(line_str) <= mode.line_length
+            str_width(line_str) <= mode.line_length
             and "\n" not in line_str  # multiline strings
             and not line.contains_standalone_comments()
         )
@@ -872,10 +843,10 @@ def is_line_short_enough(  # noqa: C901
         return False
     if "\n" not in line_str:
         # No multiline strings (MLS) present
-        return width(line_str) <= mode.line_length
+        return str_width(line_str) <= mode.line_length
 
     first, *_, last = line_str.split("\n")
-    if width(first) > mode.line_length or width(last) > mode.line_length:
+    if str_width(first) > mode.line_length or str_width(last) > mode.line_length:
         return False
 
     # Traverse the AST to examine the context of the multiline string (MLS),
@@ -1015,11 +986,7 @@ def can_omit_invisible_parens(
         return False
 
     if delimiter_count == 1:
-        if (
-            Preview.wrap_multiple_context_managers_in_parens in line.mode
-            and max_priority == COMMA_PRIORITY
-            and rhs.head.is_with_or_async_with_stmt
-        ):
+        if max_priority == COMMA_PRIORITY and rhs.head.is_with_or_async_with_stmt:
             # For two context manager with statements, the optional parentheses read
             # better. In this case, `rhs.body` is the context managers part of
             # the with statement. `rhs.head` is the `with (` part on the previous
diff --git a/src/black/mode.py b/src/black/mode.py
index 466b78228fc..1b97f3508ee 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -168,35 +168,14 @@ def supports_feature(target_versions: Set[TargetVersion], feature: Feature) -> b
 class Preview(Enum):
     """Individual preview style features."""
 
-    add_trailing_comma_consistently = auto()
-    blank_line_after_nested_stub_class = auto()
-    blank_line_between_nested_and_def_stub_file = auto()
     hex_codes_in_unicode_sequences = auto()
-    improved_async_statements_handling = auto()
-    multiline_string_handling = auto()
-    no_blank_line_before_class_docstring = auto()
-    prefer_splitting_right_hand_side_of_assignments = auto()
     # NOTE: string_processing requires wrap_long_dict_values_in_parens
     # for https://github.com/psf/black/issues/3117 to be fixed.
     string_processing = auto()
-    parenthesize_conditional_expressions = auto()
-    parenthesize_long_type_hints = auto()
-    respect_magic_trailing_comma_in_return_type = auto()
-    skip_magic_trailing_comma_in_subscript = auto()
-    wrap_long_dict_values_in_parens = auto()
-    wrap_multiple_context_managers_in_parens = auto()
-    dummy_implementations = auto()
-    walrus_subscript = auto()
-    module_docstring_newlines = auto()
-    accept_raw_docstrings = auto()
-    fix_power_op_line_length = auto()
     hug_parens_with_braces_and_square_brackets = auto()
-    allow_empty_first_line_in_block = auto()
-    single_line_format_skip_with_multiple_comments = auto()
-    long_case_block_line_splitting = auto()
-    allow_form_feeds = auto()
     unify_docstring_detection = auto()
-    respect_east_asian_width = auto()
+    wrap_long_dict_values_in_parens = auto()
+    multiline_string_handling = auto()
 
 
 class Deprecated(UserWarning):
diff --git a/src/black/nodes.py b/src/black/nodes.py
index 7ee2df2e061..a8869cba234 100644
--- a/src/black/nodes.py
+++ b/src/black/nodes.py
@@ -104,6 +104,7 @@
     syms.trailer,
     syms.term,
     syms.power,
+    syms.namedexpr_test,
 }
 TYPED_NAMES: Final = {syms.tname, syms.tname_star}
 ASSIGNMENTS: Final = {
@@ -121,6 +122,7 @@
     ">>=",
     "**=",
     "//=",
+    ":",
 }
 
 IMPLICIT_TUPLE: Final = {syms.testlist, syms.testlist_star_expr, syms.exprlist}
@@ -346,9 +348,7 @@ def whitespace(leaf: Leaf, *, complex_subscript: bool, mode: Mode) -> str:  # no
 
             return NO
 
-        elif Preview.walrus_subscript in mode and (
-            t == token.COLONEQUAL or prev.type == token.COLONEQUAL
-        ):
+        elif t == token.COLONEQUAL or prev.type == token.COLONEQUAL:
             return SPACE
 
         elif not complex_subscript:
@@ -753,13 +753,9 @@ def is_function_or_class(node: Node) -> bool:
     return node.type in {syms.funcdef, syms.classdef, syms.async_funcdef}
 
 
-def is_stub_suite(node: Node, mode: Mode) -> bool:
+def is_stub_suite(node: Node) -> bool:
     """Return True if `node` is a suite with a stub body."""
-    if (
-        node.parent is not None
-        and Preview.dummy_implementations in mode
-        and not is_parent_function_or_class(node)
-    ):
+    if node.parent is not None and not is_parent_function_or_class(node):
         return False
 
     # If there is a comment, we want to keep it.
diff --git a/tests/data/cases/preview_allow_empty_first_line.py b/tests/data/cases/allow_empty_first_line.py
similarity index 98%
rename from tests/data/cases/preview_allow_empty_first_line.py
rename to tests/data/cases/allow_empty_first_line.py
index 4269987305d..32a170a97d0 100644
--- a/tests/data/cases/preview_allow_empty_first_line.py
+++ b/tests/data/cases/allow_empty_first_line.py
@@ -1,4 +1,3 @@
-# flags: --preview
 def foo():
     """
     Docstring
diff --git a/tests/data/cases/preview_async_stmts.py b/tests/data/cases/async_stmts.py
similarity index 93%
rename from tests/data/cases/preview_async_stmts.py
rename to tests/data/cases/async_stmts.py
index 0a7671be5a6..fe9594b2164 100644
--- a/tests/data/cases/preview_async_stmts.py
+++ b/tests/data/cases/async_stmts.py
@@ -1,4 +1,3 @@
-# flags: --preview
 async def func() -> (int):
     return 0
 
diff --git a/tests/data/cases/comments5.py b/tests/data/cases/comments5.py
index bda40619f62..4270d3a09a2 100644
--- a/tests/data/cases/comments5.py
+++ b/tests/data/cases/comments5.py
@@ -45,8 +45,7 @@ def wat():
 @deco2(with_args=True)
 # leading 3
 @deco3
-def decorated1():
-    ...
+def decorated1(): ...
 
 
 # leading 1
@@ -54,8 +53,7 @@ def decorated1():
 # leading 2
 @deco2(with_args=True)
 # leading function comment
-def decorated1():
-    ...
+def decorated1(): ...
 
 
 # Note: this is fixed in
@@ -65,8 +63,7 @@ def decorated1():
 
 
 # This comment should be split from `some_instruction` by two lines but isn't.
-def g():
-    ...
+def g(): ...
 
 
 if __name__ == "__main__":
diff --git a/tests/data/cases/conditional_expression.py b/tests/data/cases/conditional_expression.py
index 76251bd9318..f65d6fb00e7 100644
--- a/tests/data/cases/conditional_expression.py
+++ b/tests/data/cases/conditional_expression.py
@@ -1,4 +1,3 @@
-# flags: --preview
 long_kwargs_single_line = my_function(
     foo="test, this is a sample value",
     bar=some_long_value_name_foo_bar_baz if some_boolean_variable else some_fallback_value_foo_bar_baz,
@@ -197,7 +196,9 @@ def foo(wait: bool = True):
     time.sleep(1) if wait else None
 
 
-a = "".join((
-    "",  # comment
-    "" if True else "",
-))
+a = "".join(
+    (
+        "",  # comment
+        "" if True else "",
+    )
+)
diff --git a/tests/data/cases/preview_context_managers_38.py b/tests/data/cases/context_managers_38.py
similarity index 96%
rename from tests/data/cases/preview_context_managers_38.py
rename to tests/data/cases/context_managers_38.py
index 719d94fdcc5..54fb97c708b 100644
--- a/tests/data/cases/preview_context_managers_38.py
+++ b/tests/data/cases/context_managers_38.py
@@ -1,4 +1,4 @@
-# flags: --preview --minimum-version=3.8
+# flags: --minimum-version=3.8
 with \
      make_context_manager1() as cm1, \
      make_context_manager2() as cm2, \
diff --git a/tests/data/cases/preview_context_managers_39.py b/tests/data/cases/context_managers_39.py
similarity index 98%
rename from tests/data/cases/preview_context_managers_39.py
rename to tests/data/cases/context_managers_39.py
index 589e00ad187..60fd1a56409 100644
--- a/tests/data/cases/preview_context_managers_39.py
+++ b/tests/data/cases/context_managers_39.py
@@ -1,4 +1,4 @@
-# flags: --preview --minimum-version=3.9
+# flags: --minimum-version=3.9
 with \
      make_context_manager1() as cm1, \
      make_context_manager2() as cm2, \
diff --git a/tests/data/cases/preview_context_managers_autodetect_310.py b/tests/data/cases/context_managers_autodetect_310.py
similarity index 93%
rename from tests/data/cases/preview_context_managers_autodetect_310.py
rename to tests/data/cases/context_managers_autodetect_310.py
index a9e31076f03..80f211032e5 100644
--- a/tests/data/cases/preview_context_managers_autodetect_310.py
+++ b/tests/data/cases/context_managers_autodetect_310.py
@@ -1,4 +1,4 @@
-# flags: --preview --minimum-version=3.10
+# flags: --minimum-version=3.10
 # This file uses pattern matching introduced in Python 3.10.
 
 
diff --git a/tests/data/cases/preview_context_managers_autodetect_311.py b/tests/data/cases/context_managers_autodetect_311.py
similarity index 92%
rename from tests/data/cases/preview_context_managers_autodetect_311.py
rename to tests/data/cases/context_managers_autodetect_311.py
index af1e83fe74c..020c4cea967 100644
--- a/tests/data/cases/preview_context_managers_autodetect_311.py
+++ b/tests/data/cases/context_managers_autodetect_311.py
@@ -1,4 +1,4 @@
-# flags: --preview --minimum-version=3.11
+# flags: --minimum-version=3.11
 # This file uses except* clause in Python 3.11.
 
 
diff --git a/tests/data/cases/preview_context_managers_autodetect_38.py b/tests/data/cases/context_managers_autodetect_38.py
similarity index 98%
rename from tests/data/cases/preview_context_managers_autodetect_38.py
rename to tests/data/cases/context_managers_autodetect_38.py
index 25217a40604..79e438b995e 100644
--- a/tests/data/cases/preview_context_managers_autodetect_38.py
+++ b/tests/data/cases/context_managers_autodetect_38.py
@@ -1,4 +1,3 @@
-# flags: --preview
 # This file doesn't use any Python 3.9+ only grammars.
 
 
diff --git a/tests/data/cases/preview_context_managers_autodetect_39.py b/tests/data/cases/context_managers_autodetect_39.py
similarity index 93%
rename from tests/data/cases/preview_context_managers_autodetect_39.py
rename to tests/data/cases/context_managers_autodetect_39.py
index 3f72e48db9d..98e674b2f9d 100644
--- a/tests/data/cases/preview_context_managers_autodetect_39.py
+++ b/tests/data/cases/context_managers_autodetect_39.py
@@ -1,4 +1,4 @@
-# flags: --preview --minimum-version=3.9
+# flags: --minimum-version=3.9
 # This file uses parenthesized context managers introduced in Python 3.9.
 
 
diff --git a/tests/data/cases/preview_dummy_implementations.py b/tests/data/cases/dummy_implementations.py
similarity index 99%
rename from tests/data/cases/preview_dummy_implementations.py
rename to tests/data/cases/dummy_implementations.py
index 3cd392c9587..0a52c081bcc 100644
--- a/tests/data/cases/preview_dummy_implementations.py
+++ b/tests/data/cases/dummy_implementations.py
@@ -1,4 +1,3 @@
-# flags: --preview
 from typing import NoReturn, Protocol, Union, overload
 
 class Empty:
diff --git a/tests/data/cases/empty_lines.py b/tests/data/cases/empty_lines.py
index 4fd47b93dca..4c03e432383 100644
--- a/tests/data/cases/empty_lines.py
+++ b/tests/data/cases/empty_lines.py
@@ -119,6 +119,7 @@ def f():
     if not prev:
         prevp = preceding_leaf(p)
         if not prevp or prevp.type in OPENING_BRACKETS:
+
             return NO
 
         if prevp.type == token.EQUAL:
diff --git a/tests/data/cases/fmtonoff.py b/tests/data/cases/fmtonoff.py
index d1f15cd5c8b..8af94563af8 100644
--- a/tests/data/cases/fmtonoff.py
+++ b/tests/data/cases/fmtonoff.py
@@ -243,12 +243,8 @@ def spaces_types(
     g: int = 1 if False else 2,
     h: str = "",
     i: str = r"",
-):
-    ...
-
-
-def spaces2(result=_core.Value(None)):
-    ...
+): ...
+def spaces2(result=_core.Value(None)): ...
 
 
 something = {
diff --git a/tests/data/cases/fmtonoff5.py b/tests/data/cases/fmtonoff5.py
index 181151b6bd6..4c134a9eea3 100644
--- a/tests/data/cases/fmtonoff5.py
+++ b/tests/data/cases/fmtonoff5.py
@@ -161,8 +161,7 @@ def  this_wont_be_formatted ( self ) -> str: ...
 
 
 class Factory(t.Protocol):
-    def this_will_be_formatted(self, **kwargs) -> Named:
-        ...
+    def this_will_be_formatted(self, **kwargs) -> Named: ...
 
     # fmt: on
 
diff --git a/tests/data/cases/preview_form_feeds.py b/tests/data/cases/form_feeds.py
similarity index 99%
rename from tests/data/cases/preview_form_feeds.py
rename to tests/data/cases/form_feeds.py
index dc3bd6cfe2e..48ffc98106b 100644
--- a/tests/data/cases/preview_form_feeds.py
+++ b/tests/data/cases/form_feeds.py
@@ -1,4 +1,3 @@
-# flags: --preview
 
 
 # Warning! This file contains form feeds (ASCII 0x0C, often represented by \f or ^L).
diff --git a/tests/data/cases/function.py b/tests/data/cases/function.py
index 2d642c8731b..4e3f91fd8b1 100644
--- a/tests/data/cases/function.py
+++ b/tests/data/cases/function.py
@@ -158,10 +158,7 @@ def spaces_types(
     g: int = 1 if False else 2,
     h: str = "",
     i: str = r"",
-):
-    ...
-
-
+): ...
 def spaces2(result=_core.Value(None)):
     assert fut is self._read_fut, (fut, self._read_fut)
 
diff --git a/tests/data/cases/remove_newline_after_match.py b/tests/data/cases/keep_newline_after_match.py
similarity index 98%
rename from tests/data/cases/remove_newline_after_match.py
rename to tests/data/cases/keep_newline_after_match.py
index fe6592b664d..dbeccce6264 100644
--- a/tests/data/cases/remove_newline_after_match.py
+++ b/tests/data/cases/keep_newline_after_match.py
@@ -21,15 +21,21 @@ def http_status(status):
 
 # output
 def http_status(status):
+
     match status:
+
         case 400:
+
             return "Bad request"
 
         case 401:
+
             return "Unauthorized"
 
         case 403:
+
             return "Forbidden"
 
         case 404:
+
             return "Not found"
\ No newline at end of file
diff --git a/tests/data/cases/long_strings_flag_disabled.py b/tests/data/cases/long_strings_flag_disabled.py
index db3954e3abd..d81c331cab2 100644
--- a/tests/data/cases/long_strings_flag_disabled.py
+++ b/tests/data/cases/long_strings_flag_disabled.py
@@ -43,8 +43,10 @@
     % (
         "formatted",
         "string",
-    ): "This is a really really really long string that has to go inside of a dictionary. It is %s bad (#%d)."
-    % ("soooo", 2),
+    ): (
+        "This is a really really really long string that has to go inside of a dictionary. It is %s bad (#%d)."
+        % ("soooo", 2)
+    ),
 }
 
 func_with_keywords(
@@ -254,10 +256,12 @@
     + CONCATENATED
     + "using the '+' operator."
 )
-annotated_variable: Final = "This is a large string that has a type annotation attached to it. A type annotation should NOT stop a long string from being wrapped."
-annotated_variable: Literal[
-    "fakse_literal"
-] = "This is a large string that has a type annotation attached to it. A type annotation should NOT stop a long string from being wrapped."
+annotated_variable: Final = (
+    "This is a large string that has a type annotation attached to it. A type annotation should NOT stop a long string from being wrapped."
+)
+annotated_variable: Literal["fakse_literal"] = (
+    "This is a large string that has a type annotation attached to it. A type annotation should NOT stop a long string from being wrapped."
+)
 
 backslashes = "This is a really long string with \"embedded\" double quotes and 'single' quotes that also handles checking for an even number of backslashes \\"
 backslashes = "This is a really long string with \"embedded\" double quotes and 'single' quotes that also handles checking for an even number of backslashes \\\\"
diff --git a/tests/data/cases/module_docstring_1.py b/tests/data/cases/module_docstring_1.py
index d5897b4db60..5751154f7f0 100644
--- a/tests/data/cases/module_docstring_1.py
+++ b/tests/data/cases/module_docstring_1.py
@@ -1,4 +1,3 @@
-# flags: --preview
 """Single line module-level docstring should be followed by single newline."""
 
 
diff --git a/tests/data/cases/module_docstring_2.py b/tests/data/cases/module_docstring_2.py
index 1cc9aea9aea..ac486096c02 100644
--- a/tests/data/cases/module_docstring_2.py
+++ b/tests/data/cases/module_docstring_2.py
@@ -1,7 +1,7 @@
 # flags: --preview
 """I am a very helpful module docstring.
 
-With trailing spaces:      
+With trailing spaces (only removed with unify_docstring_detection on):      
 Lorem ipsum dolor sit amet, consectetur adipiscing elit,
 sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
 Ut enim ad minim veniam,
@@ -39,7 +39,7 @@
 # output
 """I am a very helpful module docstring.
 
-With trailing spaces:
+With trailing spaces (only removed with unify_docstring_detection on):
 Lorem ipsum dolor sit amet, consectetur adipiscing elit,
 sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
 Ut enim ad minim veniam,
diff --git a/tests/data/cases/module_docstring_3.py b/tests/data/cases/module_docstring_3.py
index 0631e136a3d..3d0058dd554 100644
--- a/tests/data/cases/module_docstring_3.py
+++ b/tests/data/cases/module_docstring_3.py
@@ -1,4 +1,3 @@
-# flags: --preview
 """Single line module-level docstring should be followed by single newline."""
 a = 1
 
diff --git a/tests/data/cases/module_docstring_4.py b/tests/data/cases/module_docstring_4.py
index 515174dcc04..b1720078f71 100644
--- a/tests/data/cases/module_docstring_4.py
+++ b/tests/data/cases/module_docstring_4.py
@@ -1,4 +1,3 @@
-# flags: --preview
 """Single line module-level docstring should be followed by single newline."""
 
 a = 1
diff --git a/tests/data/cases/module_docstring_followed_by_class.py b/tests/data/cases/module_docstring_followed_by_class.py
index 6fdbfc8c240..c291e61b960 100644
--- a/tests/data/cases/module_docstring_followed_by_class.py
+++ b/tests/data/cases/module_docstring_followed_by_class.py
@@ -1,4 +1,3 @@
-# flags: --preview
 """Two blank lines between module docstring and a class."""
 class MyClass:
     pass
diff --git a/tests/data/cases/module_docstring_followed_by_function.py b/tests/data/cases/module_docstring_followed_by_function.py
index 5913a59e1fe..fd29b98da8e 100644
--- a/tests/data/cases/module_docstring_followed_by_function.py
+++ b/tests/data/cases/module_docstring_followed_by_function.py
@@ -1,4 +1,3 @@
-# flags: --preview
 """Two blank lines between module docstring and a function def."""
 def function():
     pass
diff --git a/tests/data/cases/nested_stub.py b/tests/data/cases/nested_stub.py
index ef13c588ce6..40ca11e9330 100644
--- a/tests/data/cases/nested_stub.py
+++ b/tests/data/cases/nested_stub.py
@@ -1,4 +1,4 @@
-# flags: --pyi --preview
+# flags: --pyi
 import sys
 
 class Outer:
diff --git a/tests/data/cases/preview_no_blank_line_before_docstring.py b/tests/data/cases/no_blank_line_before_docstring.py
similarity index 98%
rename from tests/data/cases/preview_no_blank_line_before_docstring.py
rename to tests/data/cases/no_blank_line_before_docstring.py
index faeaa1e46e4..ced125fef78 100644
--- a/tests/data/cases/preview_no_blank_line_before_docstring.py
+++ b/tests/data/cases/no_blank_line_before_docstring.py
@@ -1,4 +1,3 @@
-# flags: --preview
 def line_before_docstring():
 
     """Please move me up"""
@@ -63,4 +62,5 @@ class MultilineDocstringsAsWell:
 
 
 class SingleQuotedDocstring:
+
     "I'm a docstring but I don't even get triple quotes."
diff --git a/tests/data/cases/preview_pattern_matching_long.py b/tests/data/cases/pattern_matching_long.py
similarity index 94%
rename from tests/data/cases/preview_pattern_matching_long.py
rename to tests/data/cases/pattern_matching_long.py
index df849fdc4f2..9a944c9d0c9 100644
--- a/tests/data/cases/preview_pattern_matching_long.py
+++ b/tests/data/cases/pattern_matching_long.py
@@ -1,4 +1,4 @@
-# flags: --preview --minimum-version=3.10
+# flags: --minimum-version=3.10
 match x:
     case "abcd" | "abcd" | "abcd" :
         pass
diff --git a/tests/data/cases/preview_pattern_matching_trailing_comma.py b/tests/data/cases/pattern_matching_trailing_comma.py
similarity index 92%
rename from tests/data/cases/preview_pattern_matching_trailing_comma.py
rename to tests/data/cases/pattern_matching_trailing_comma.py
index e6c0d88bb80..5660b0f6a14 100644
--- a/tests/data/cases/preview_pattern_matching_trailing_comma.py
+++ b/tests/data/cases/pattern_matching_trailing_comma.py
@@ -1,4 +1,4 @@
-# flags: --preview --minimum-version=3.10
+# flags: --minimum-version=3.10
 match maybe, multiple:
     case perhaps, 5:
         pass
diff --git a/tests/data/cases/pep604_union_types_line_breaks.py b/tests/data/cases/pep604_union_types_line_breaks.py
index fee2b840494..745bc9e8b02 100644
--- a/tests/data/cases/pep604_union_types_line_breaks.py
+++ b/tests/data/cases/pep604_union_types_line_breaks.py
@@ -1,4 +1,4 @@
-# flags: --preview --minimum-version=3.10
+# flags: --minimum-version=3.10
 # This has always worked
 z= Loooooooooooooooooooooooong | Loooooooooooooooooooooooong | Loooooooooooooooooooooooong | Loooooooooooooooooooooooong
 
diff --git a/tests/data/cases/pep_572_py310.py b/tests/data/cases/pep_572_py310.py
index 9f999deeb89..ba488d4741c 100644
--- a/tests/data/cases/pep_572_py310.py
+++ b/tests/data/cases/pep_572_py310.py
@@ -1,8 +1,8 @@
 # flags: --minimum-version=3.10
 # Unparenthesized walruses are now allowed in indices since Python 3.10.
-x[a:=0]
-x[a:=0, b:=1]
-x[5, b:=0]
+x[a := 0]
+x[a := 0, b := 1]
+x[5, b := 0]
 
 # Walruses are allowed inside generator expressions on function calls since 3.10.
 if any(match := pattern_error.match(s) for s in buffer):
diff --git a/tests/data/cases/pep_572_remove_parens.py b/tests/data/cases/pep_572_remove_parens.py
index 24f1ac29168..f0026ceb032 100644
--- a/tests/data/cases/pep_572_remove_parens.py
+++ b/tests/data/cases/pep_572_remove_parens.py
@@ -96,18 +96,16 @@ async def await_the_walrus():
 foo(x=(y := f(x)))
 
 
-def foo(answer=(p := 42)):
-    ...
+def foo(answer=(p := 42)): ...
 
 
-def foo2(answer: (p := 42) = 5):
-    ...
+def foo2(answer: (p := 42) = 5): ...
 
 
 lambda: (x := 1)
 
 a[(x := 12)]
-a[:(x := 13)]
+a[: (x := 13)]
 
 # we don't touch expressions in f-strings but if we do one day, don't break 'em
 f"{(x:=10)}"
diff --git a/tests/data/cases/preview_pep_572.py b/tests/data/cases/pep_572_slices.py
similarity index 75%
rename from tests/data/cases/preview_pep_572.py
rename to tests/data/cases/pep_572_slices.py
index 75ad0cc4176..aa772b1f1f5 100644
--- a/tests/data/cases/preview_pep_572.py
+++ b/tests/data/cases/pep_572_slices.py
@@ -1,4 +1,3 @@
-# flags: --preview
 x[(a:=0):]
 x[:(a:=0)]
 
diff --git a/tests/data/cases/preview_percent_precedence.py b/tests/data/cases/percent_precedence.py
similarity index 91%
rename from tests/data/cases/preview_percent_precedence.py
rename to tests/data/cases/percent_precedence.py
index aeaf450ff5e..7822e42c69d 100644
--- a/tests/data/cases/preview_percent_precedence.py
+++ b/tests/data/cases/percent_precedence.py
@@ -1,4 +1,3 @@
-# flags: --preview
 ("" % a) ** 2
 ("" % a)[0]
 ("" % a)()
@@ -31,9 +30,9 @@
 2 // ("" % a)
 2 % ("" % a)
 +("" % a)
-b + "" % a
+b + ("" % a)
 -("" % a)
-b - "" % a
+b - ("" % a)
 b + -("" % a)
 ~("" % a)
 2 ** ("" % a)
diff --git a/tests/data/cases/preview_power_op_spacing.py b/tests/data/cases/power_op_spacing_long.py
similarity index 99%
rename from tests/data/cases/preview_power_op_spacing.py
rename to tests/data/cases/power_op_spacing_long.py
index 650c6fecb20..30e6eb788b3 100644
--- a/tests/data/cases/preview_power_op_spacing.py
+++ b/tests/data/cases/power_op_spacing_long.py
@@ -1,4 +1,3 @@
-# flags: --preview
 a = 1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1
 b = 1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1**1
 c = 1 ** 1 ** 1 ** 1 ** 1 ** 1 ** 1 ** 1 ** 1 ** 1 ** 1 ** 1 ** 1 ** 1 ** 1 ** 1 ** 1 ** 1 ** 1 ** 1 ** 1 ** 1 ** 1 ** 1 ** 1 ** 1 ** 1 ** 1
diff --git a/tests/data/cases/preview_prefer_rhs_split.py b/tests/data/cases/prefer_rhs_split.py
similarity index 99%
rename from tests/data/cases/preview_prefer_rhs_split.py
rename to tests/data/cases/prefer_rhs_split.py
index 28d89c368c0..f3d9fd67251 100644
--- a/tests/data/cases/preview_prefer_rhs_split.py
+++ b/tests/data/cases/prefer_rhs_split.py
@@ -1,4 +1,3 @@
-# flags: --preview
 first_item, second_item = (
     some_looooooooong_module.some_looooooooooooooong_function_name(
         first_argument, second_argument, third_argument
diff --git a/tests/data/cases/py310_pep572.py b/tests/data/cases/py310_pep572.py
index 172be3898d6..73fbe44d42c 100644
--- a/tests/data/cases/py310_pep572.py
+++ b/tests/data/cases/py310_pep572.py
@@ -1,4 +1,4 @@
-# flags: --preview --minimum-version=3.10
+# flags: --minimum-version=3.10
 x[a:=0]
 x[a := 0]
 x[a := 0, b := 1]
diff --git a/tests/data/cases/python39.py b/tests/data/cases/python39.py
index 1b9536c1529..85eddc38e00 100644
--- a/tests/data/cases/python39.py
+++ b/tests/data/cases/python39.py
@@ -15,19 +15,16 @@ def f():
 # output
 
 @relaxed_decorator[0]
-def f():
-    ...
+def f(): ...
 
 
 @relaxed_decorator[
     extremely_long_name_that_definitely_will_not_fit_on_one_line_of_standard_length
 ]
-def f():
-    ...
+def f(): ...
 
 
 @extremely_long_variable_name_that_doesnt_fit := complex.expression(
     with_long="arguments_value_that_wont_fit_at_the_end_of_the_line"
 )
-def f():
-    ...
\ No newline at end of file
+def f(): ...
\ No newline at end of file
diff --git a/tests/data/cases/raw_docstring.py b/tests/data/cases/raw_docstring.py
index 751fd3201df..7f88bb2de86 100644
--- a/tests/data/cases/raw_docstring.py
+++ b/tests/data/cases/raw_docstring.py
@@ -1,4 +1,4 @@
-# flags: --preview --skip-string-normalization
+# flags: --skip-string-normalization
 class C:
 
     r"""Raw"""
diff --git a/tests/data/cases/preview_docstring_no_string_normalization.py b/tests/data/cases/raw_docstring_no_string_normalization.py
similarity index 88%
rename from tests/data/cases/preview_docstring_no_string_normalization.py
rename to tests/data/cases/raw_docstring_no_string_normalization.py
index 712c7364f51..a201c1e8fae 100644
--- a/tests/data/cases/preview_docstring_no_string_normalization.py
+++ b/tests/data/cases/raw_docstring_no_string_normalization.py
@@ -1,4 +1,4 @@
-# flags: --preview --skip-string-normalization
+# flags: --skip-string-normalization
 def do_not_touch_this_prefix():
     R"""There was a bug where docstring prefixes would be normalized even with -S."""
 
diff --git a/tests/data/cases/remove_newline_after_code_block_open.py b/tests/data/cases/remove_newline_after_code_block_open.py
index ef2e5c2f6f5..6622e8afb7d 100644
--- a/tests/data/cases/remove_newline_after_code_block_open.py
+++ b/tests/data/cases/remove_newline_after_code_block_open.py
@@ -3,14 +3,14 @@
 
 def foo1():
 
-    print("The newline above me should be deleted!")
+    print("The newline above me should be kept!")
 
 
 def foo2():
 
 
 
-    print("All the newlines above me should be deleted!")
+    print("All the newlines above me should be kept!")
 
 
 def foo3():
@@ -30,31 +30,31 @@ def foo4():
 class Foo:
     def bar(self):
 
-        print("The newline above me should be deleted!")
+        print("The newline above me should be kept!")
 
 
 for i in range(5):
 
-    print(f"{i}) The line above me should be removed!")
+    print(f"{i}) The line above me should be kept!")
 
 
 for i in range(5):
 
 
 
-    print(f"{i}) The lines above me should be removed!")
+    print(f"{i}) The lines above me should be kept!")
 
 
 for i in range(5):
 
     for j in range(7):
 
-        print(f"{i}) The lines above me should be removed!")
+        print(f"{i}) The lines above me should be kept!")
 
 
 if random.randint(0, 3) == 0:
 
-    print("The new line above me is about to be removed!")
+    print("The new line above me will be kept!")
 
 
 if random.randint(0, 3) == 0:
@@ -62,43 +62,45 @@ def bar(self):
 
 
 
-    print("The new lines above me is about to be removed!")
+    print("The new lines above me will be kept!")
 
 
 if random.randint(0, 3) == 0:
+
     if random.uniform(0, 1) > 0.5:
-        print("Two lines above me are about to be removed!")
+
+        print("Two lines above me will be kept!")
 
 
 while True:
 
-    print("The newline above me should be deleted!")
+    print("The newline above me should be kept!")
 
 
 while True:
 
 
 
-    print("The newlines above me should be deleted!")
+    print("The newlines above me should be kept!")
 
 
 while True:
 
     while False:
 
-        print("The newlines above me should be deleted!")
+        print("The newlines above me should be kept!")
 
 
 with open("/path/to/file.txt", mode="w") as file:
 
-    file.write("The new line above me is about to be removed!")
+    file.write("The new line above me will be kept!")
 
 
 with open("/path/to/file.txt", mode="w") as file:
 
 
 
-    file.write("The new lines above me is about to be removed!")
+    file.write("The new lines above me will be kept!")
 
 
 with open("/path/to/file.txt", mode="r") as read_file:
@@ -113,20 +115,24 @@ def bar(self):
 
 
 def foo1():
-    print("The newline above me should be deleted!")
+
+    print("The newline above me should be kept!")
 
 
 def foo2():
-    print("All the newlines above me should be deleted!")
+
+    print("All the newlines above me should be kept!")
 
 
 def foo3():
+
     print("No newline above me!")
 
     print("There is a newline above me, and that's OK!")
 
 
 def foo4():
+
     # There is a comment here
 
     print("The newline above me should not be deleted!")
@@ -134,56 +140,73 @@ def foo4():
 
 class Foo:
     def bar(self):
-        print("The newline above me should be deleted!")
+
+        print("The newline above me should be kept!")
 
 
 for i in range(5):
-    print(f"{i}) The line above me should be removed!")
+
+    print(f"{i}) The line above me should be kept!")
 
 
 for i in range(5):
-    print(f"{i}) The lines above me should be removed!")
+
+    print(f"{i}) The lines above me should be kept!")
 
 
 for i in range(5):
+
     for j in range(7):
-        print(f"{i}) The lines above me should be removed!")
+
+        print(f"{i}) The lines above me should be kept!")
 
 
 if random.randint(0, 3) == 0:
-    print("The new line above me is about to be removed!")
+
+    print("The new line above me will be kept!")
 
 
 if random.randint(0, 3) == 0:
-    print("The new lines above me is about to be removed!")
+
+    print("The new lines above me will be kept!")
 
 
 if random.randint(0, 3) == 0:
+
     if random.uniform(0, 1) > 0.5:
-        print("Two lines above me are about to be removed!")
+
+        print("Two lines above me will be kept!")
 
 
 while True:
-    print("The newline above me should be deleted!")
+
+    print("The newline above me should be kept!")
 
 
 while True:
-    print("The newlines above me should be deleted!")
+
+    print("The newlines above me should be kept!")
 
 
 while True:
+
     while False:
-        print("The newlines above me should be deleted!")
+
+        print("The newlines above me should be kept!")
 
 
 with open("/path/to/file.txt", mode="w") as file:
-    file.write("The new line above me is about to be removed!")
+
+    file.write("The new line above me will be kept!")
 
 
 with open("/path/to/file.txt", mode="w") as file:
-    file.write("The new lines above me is about to be removed!")
+
+    file.write("The new lines above me will be kept!")
 
 
 with open("/path/to/file.txt", mode="r") as read_file:
+
     with open("/path/to/output_file.txt", mode="w") as write_file:
+
         write_file.writelines(read_file.readlines())
diff --git a/tests/data/cases/return_annotation_brackets.py b/tests/data/cases/return_annotation_brackets.py
index 8509ecdb92c..ed05bed61f4 100644
--- a/tests/data/cases/return_annotation_brackets.py
+++ b/tests/data/cases/return_annotation_brackets.py
@@ -88,7 +88,6 @@ def foo() -> tuple[int, int, int,]:
     return 2
 
 # Magic trailing comma example, with params
-# this is broken - the trailing comma is transferred to the param list. Fixed in preview
 def foo(a,b) -> tuple[int, int, int,]:
     return 2
 
@@ -194,30 +193,27 @@ def foo() -> tuple[int, int, int]:
     return 2
 
 
-def foo() -> (
-    tuple[
-        loooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong,
-        loooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong,
-        loooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong,
-    ]
-):
+def foo() -> tuple[
+    loooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong,
+    loooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong,
+    loooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong,
+]:
     return 2
 
 
 # Magic trailing comma example
-def foo() -> (
-    tuple[
-        int,
-        int,
-        int,
-    ]
-):
+def foo() -> tuple[
+    int,
+    int,
+    int,
+]:
     return 2
 
 
 # Magic trailing comma example, with params
-# this is broken - the trailing comma is transferred to the param list. Fixed in preview
-def foo(
-    a, b
-) -> tuple[int, int, int,]:
+def foo(a, b) -> tuple[
+    int,
+    int,
+    int,
+]:
     return 2
diff --git a/tests/data/cases/preview_single_line_format_skip_with_multiple_comments.py b/tests/data/cases/single_line_format_skip_with_multiple_comments.py
similarity index 97%
rename from tests/data/cases/preview_single_line_format_skip_with_multiple_comments.py
rename to tests/data/cases/single_line_format_skip_with_multiple_comments.py
index efde662baa8..7212740fc42 100644
--- a/tests/data/cases/preview_single_line_format_skip_with_multiple_comments.py
+++ b/tests/data/cases/single_line_format_skip_with_multiple_comments.py
@@ -1,4 +1,3 @@
-# flags: --preview
 foo =  123  # fmt: skip # noqa: E501 # pylint
 bar =    (
     123   ,
diff --git a/tests/data/cases/preview_trailing_comma.py b/tests/data/cases/trailing_comma.py
similarity index 97%
rename from tests/data/cases/preview_trailing_comma.py
rename to tests/data/cases/trailing_comma.py
index bba7e7ad16d..5b09c664606 100644
--- a/tests/data/cases/preview_trailing_comma.py
+++ b/tests/data/cases/trailing_comma.py
@@ -1,4 +1,3 @@
-# flags: --preview
 e = {
     "a": fun(msg, "ts"),
     "longggggggggggggggid": ...,
diff --git a/tests/data/cases/walrus_in_dict.py b/tests/data/cases/walrus_in_dict.py
index c33eecd84a6..c91ad9e8611 100644
--- a/tests/data/cases/walrus_in_dict.py
+++ b/tests/data/cases/walrus_in_dict.py
@@ -1,7 +1,9 @@
 # flags: --preview
+# This is testing an issue that is specific to the preview style
 {
     "is_update": (up := commit.hash in update_hashes)
 }
 
 # output
+# This is testing an issue that is specific to the preview style
 {"is_update": (up := commit.hash in update_hashes)}

From a5196e6f1f450e4c8da0e514e01873a0cc1e1a3c Mon Sep 17 00:00:00 2001
From: cobalt <61329810+RedGuy12@users.noreply.github.com>
Date: Thu, 25 Jan 2024 03:31:49 -0600
Subject: [PATCH 0987/1034] fix: Don't normalize whitespace before fmt:skip
 comments (#4146)

Signed-off-by: RedGuy12 <paul@reid-family.org>
---
 CHANGES.md                   |  1 +
 src/black/comments.py        | 14 +++++++++++---
 src/black/mode.py            |  1 +
 tests/data/cases/fmtskip9.py |  9 +++++++++
 4 files changed, 22 insertions(+), 3 deletions(-)
 create mode 100644 tests/data/cases/fmtskip9.py

diff --git a/CHANGES.md b/CHANGES.md
index 0e2974d706e..2fe14cd5246 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -56,6 +56,7 @@ release:
 - Format module docstrings the same as class and function docstrings (#4095)
 - Fix crash when using a walrus in a dictionary (#4155)
 - Fix unnecessary parentheses when wrapping long dicts (#4135)
+- Stop normalizing spaces before `# fmt: skip` comments (#4146)
 
 ### Configuration
 
diff --git a/src/black/comments.py b/src/black/comments.py
index 910e1b760f0..ea54e2468c9 100644
--- a/src/black/comments.py
+++ b/src/black/comments.py
@@ -3,7 +3,7 @@
 from functools import lru_cache
 from typing import Collection, Final, Iterator, List, Optional, Tuple, Union
 
-from black.mode import Mode
+from black.mode import Mode, Preview
 from black.nodes import (
     CLOSING_BRACKETS,
     STANDALONE_COMMENT,
@@ -46,6 +46,7 @@ class ProtoComment:
     newlines: int  # how many newlines before the comment
     consumed: int  # how many characters of the original leaf's prefix did we consume
     form_feed: bool  # is there a form feed before the comment
+    leading_whitespace: str  # leading whitespace before the comment, if any
 
 
 def generate_comments(leaf: LN) -> Iterator[Leaf]:
@@ -88,7 +89,9 @@ def list_comments(prefix: str, *, is_endmarker: bool) -> List[ProtoComment]:
     form_feed = False
     for index, full_line in enumerate(re.split("\r?\n", prefix)):
         consumed += len(full_line) + 1  # adding the length of the split '\n'
-        line = full_line.lstrip()
+        match = re.match(r"^(\s*)(\S.*|)$", full_line)
+        assert match
+        whitespace, line = match.groups()
         if not line:
             nlines += 1
             if "\f" in full_line:
@@ -113,6 +116,7 @@ def list_comments(prefix: str, *, is_endmarker: bool) -> List[ProtoComment]:
                 newlines=nlines,
                 consumed=consumed,
                 form_feed=form_feed,
+                leading_whitespace=whitespace,
             )
         )
         form_feed = False
@@ -230,7 +234,11 @@ def convert_one_fmt_off_pair(
                 standalone_comment_prefix += fmt_off_prefix
                 hidden_value = comment.value + "\n" + hidden_value
             if _contains_fmt_skip_comment(comment.value, mode):
-                hidden_value += "  " + comment.value
+                hidden_value += (
+                    comment.leading_whitespace
+                    if Preview.no_normalize_fmt_skip_whitespace in mode
+                    else "  "
+                ) + comment.value
             if hidden_value.endswith("\n"):
                 # That happens when one of the `ignored_nodes` ended with a NEWLINE
                 # leaf (possibly followed by a DEDENT).
diff --git a/src/black/mode.py b/src/black/mode.py
index 1b97f3508ee..a1519f17bcc 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -174,6 +174,7 @@ class Preview(Enum):
     string_processing = auto()
     hug_parens_with_braces_and_square_brackets = auto()
     unify_docstring_detection = auto()
+    no_normalize_fmt_skip_whitespace = auto()
     wrap_long_dict_values_in_parens = auto()
     multiline_string_handling = auto()
 
diff --git a/tests/data/cases/fmtskip9.py b/tests/data/cases/fmtskip9.py
new file mode 100644
index 00000000000..30085bdd973
--- /dev/null
+++ b/tests/data/cases/fmtskip9.py
@@ -0,0 +1,9 @@
+# flags: --preview
+print () # fmt: skip
+print () # fmt:skip
+
+
+# output
+
+print () # fmt: skip
+print () # fmt:skip

From f7d552d9b7bd33f43edd0867757c27b1aa36c651 Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Thu, 25 Jan 2024 13:11:26 -0800
Subject: [PATCH 0988/1034] Remove reference (#4169)

This is out-of-date and just a chore. I don't think this is useful to
contributors and Black doesn't even have a public API.
---
 docs/contributing/index.md                    |   5 -
 .../reference/reference_classes.rst           | 234 ------------------
 .../reference/reference_exceptions.rst        |  18 --
 .../reference/reference_functions.rst         | 172 -------------
 .../reference/reference_summary.rst           |  19 --
 5 files changed, 448 deletions(-)
 delete mode 100644 docs/contributing/reference/reference_classes.rst
 delete mode 100644 docs/contributing/reference/reference_exceptions.rst
 delete mode 100644 docs/contributing/reference/reference_functions.rst
 delete mode 100644 docs/contributing/reference/reference_summary.rst

diff --git a/docs/contributing/index.md b/docs/contributing/index.md
index 3314c8eaa39..f15afa318d4 100644
--- a/docs/contributing/index.md
+++ b/docs/contributing/index.md
@@ -9,7 +9,6 @@ the_basics
 gauging_changes
 issue_triage
 release_process
-reference/reference_summary
 ```
 
 Welcome! Happy to see you willing to make the project better. Have you read the entire
@@ -42,9 +41,5 @@ This section covers the following topics:
 - {doc}`the_basics`
 - {doc}`gauging_changes`
 - {doc}`release_process`
-- {doc}`reference/reference_summary`
 
 For an overview on contributing to the _Black_, please checkout {doc}`the_basics`.
-
-If you need a reference of the functions, classes, etc. available to you while
-developing _Black_, there's the {doc}`reference/reference_summary` docs.
diff --git a/docs/contributing/reference/reference_classes.rst b/docs/contributing/reference/reference_classes.rst
deleted file mode 100644
index dc615579e30..00000000000
--- a/docs/contributing/reference/reference_classes.rst
+++ /dev/null
@@ -1,234 +0,0 @@
-*Black* classes
-===============
-
-*Contents are subject to change.*
-
-Black Classes
-~~~~~~~~~~~~~~
-
-.. currentmodule:: black
-
-:class:`BracketTracker`
------------------------
-
-.. autoclass:: black.brackets.BracketTracker
-    :members:
-
-:class:`Line`
--------------
-
-.. autoclass:: black.lines.Line
-    :members:
-    :special-members: __str__, __bool__
-
-:class:`RHSResult`
--------------------------
-
-.. autoclass:: black.lines.RHSResult
-    :members:
-
-:class:`LinesBlock`
--------------------------
-
-.. autoclass:: black.lines.LinesBlock
-    :members:
-
-:class:`EmptyLineTracker`
--------------------------
-
-.. autoclass:: black.lines.EmptyLineTracker
-    :members:
-
-:class:`LineGenerator`
-----------------------
-
-.. autoclass:: black.linegen.LineGenerator
-    :show-inheritance:
-    :members:
-
-:class:`ProtoComment`
----------------------
-
-.. 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:
-
-:class:`StringTransformer`
-----------------------------
-
-.. autoclass:: black.trans.StringTransformer
-    :show-inheritance:
-    :members:
-
-:class:`CustomSplit`
-----------------------------
-
-.. autoclass:: black.trans.CustomSplit
-    :members:
-
-:class:`CustomSplitMapMixin`
------------------------------
-
-.. autoclass:: black.trans.CustomSplitMapMixin
-    :show-inheritance:
-    :members:
-
-:class:`StringMerger`
-----------------------
-
-.. 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:
-
-:class:`Cache`
-------------------------
-
-.. autoclass:: black.cache.Cache
-    :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:
-
-:class:`WriteBack`
-------------------
-
-.. 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:
diff --git a/docs/contributing/reference/reference_exceptions.rst b/docs/contributing/reference/reference_exceptions.rst
deleted file mode 100644
index ab46ebdb628..00000000000
--- a/docs/contributing/reference/reference_exceptions.rst
+++ /dev/null
@@ -1,18 +0,0 @@
-*Black* exceptions
-==================
-
-*Contents are subject to change.*
-
-.. currentmodule:: black
-
-.. autoexception:: black.trans.CannotTransform
-
-.. autoexception:: black.linegen.CannotSplit
-
-.. autoexception:: black.brackets.BracketMatchError
-
-.. autoexception:: black.report.NothingChanged
-
-.. autoexception:: black.parsing.InvalidInput
-
-.. autoexception:: black.mode.Deprecated
diff --git a/docs/contributing/reference/reference_functions.rst b/docs/contributing/reference/reference_functions.rst
deleted file mode 100644
index ebadf6975a7..00000000000
--- a/docs/contributing/reference/reference_functions.rst
+++ /dev/null
@@ -1,172 +0,0 @@
-*Black* functions
-=================
-
-*Contents are subject to change.*
-
-.. currentmodule:: black
-
-Assertions and checks
----------------------
-
-.. autofunction:: black.assert_equivalent
-
-.. autofunction:: black.assert_stable
-
-.. autofunction:: black.lines.can_be_split
-
-.. autofunction:: black.lines.can_omit_invisible_parens
-
-.. autofunction:: black.nodes.is_empty_tuple
-
-.. autofunction:: black.nodes.is_import
-
-.. autofunction:: black.lines.is_line_short_enough
-
-.. autofunction:: black.nodes.is_multiline_string
-
-.. autofunction:: black.nodes.is_one_tuple
-
-.. autofunction:: black.brackets.is_split_after_delimiter
-
-.. autofunction:: black.brackets.is_split_before_delimiter
-
-.. autofunction:: black.nodes.is_stub_body
-
-.. autofunction:: black.nodes.is_stub_suite
-
-.. autofunction:: black.nodes.is_vararg
-
-.. autofunction:: black.nodes.is_yield
-
-
-Formatting
-----------
-
-.. autofunction:: black.format_file_contents
-
-.. autofunction:: black.format_file_in_place
-
-.. autofunction:: black.format_stdin_to_stdout
-
-.. autofunction:: black.format_str
-
-.. autofunction:: black.reformat_one
-
-.. autofunction:: black.concurrency.schedule_formatting
-
-File operations
----------------
-
-.. autofunction:: black.dump_to_file
-
-.. autofunction:: black.find_project_root
-
-.. autofunction:: black.gen_python_files
-
-.. autofunction:: black.read_pyproject_toml
-
-Parsing
--------
-
-.. autofunction:: black.decode_bytes
-
-.. autofunction:: black.parsing.lib2to3_parse
-
-.. autofunction:: black.parsing.lib2to3_unparse
-
-Split functions
----------------
-
-.. autofunction:: black.linegen.bracket_split_build_line
-
-.. autofunction:: black.linegen.bracket_split_succeeded_or_raise
-
-.. autofunction:: black.linegen.delimiter_split
-
-.. autofunction:: black.linegen.left_hand_split
-
-.. autofunction:: black.linegen.right_hand_split
-
-.. autofunction:: black.linegen.standalone_comment_split
-
-.. autofunction:: black.linegen.transform_line
-
-Caching
--------
-
-.. autofunction:: black.cache.get_cache_dir
-
-.. autofunction:: black.cache.get_cache_file
-
-Utilities
----------
-
-.. py:function:: black.debug.DebugVisitor.show(code: str) -> None
-
-    Pretty-print the lib2to3 AST of a given string of `code`.
-
-.. autofunction:: black.concurrency.cancel
-
-.. autofunction:: black.nodes.child_towards
-
-.. autofunction:: black.nodes.container_of
-
-.. autofunction:: black.comments.convert_one_fmt_off_pair
-
-.. autofunction:: black.diff
-
-.. autofunction:: black.linegen.dont_increase_indentation
-
-.. autofunction:: black.numerics.format_float_or_int_string
-
-.. autofunction:: black.nodes.ensure_visible
-
-.. autofunction:: black.lines.enumerate_reversed
-
-.. autofunction:: black.comments.generate_comments
-
-.. autofunction:: black.comments.generate_ignored_nodes
-
-.. autofunction:: black.comments.is_fmt_on
-
-.. autofunction:: black.comments.children_contains_fmt_on
-
-.. autofunction:: black.nodes.first_leaf_of
-
-.. autofunction:: black.linegen.generate_trailers_to_omit
-
-.. autofunction:: black.get_future_imports
-
-.. autofunction:: black.comments.list_comments
-
-.. autofunction:: black.comments.make_comment
-
-.. autofunction:: black.linegen.maybe_make_parens_invisible_in_atom
-
-.. autofunction:: black.brackets.max_delimiter_priority_in_atom
-
-.. autofunction:: black.normalize_fmt_off
-
-.. autofunction:: black.numerics.normalize_numeric_literal
-
-.. autofunction:: black.comments.normalize_trailing_prefix
-
-.. autofunction:: black.strings.normalize_string_prefix
-
-.. autofunction:: black.strings.normalize_string_quotes
-
-.. autofunction:: black.linegen.normalize_invisible_parens
-
-.. autofunction:: black.nodes.preceding_leaf
-
-.. autofunction:: black.re_compile_maybe_verbose
-
-.. autofunction:: black.linegen.should_split_line
-
-.. autofunction:: black.concurrency.shutdown
-
-.. autofunction:: black.strings.sub_twice
-
-.. autofunction:: black.nodes.whitespace
-
-.. autofunction:: black.nodes.make_simple_prefix
diff --git a/docs/contributing/reference/reference_summary.rst b/docs/contributing/reference/reference_summary.rst
deleted file mode 100644
index c6163d897b6..00000000000
--- a/docs/contributing/reference/reference_summary.rst
+++ /dev/null
@@ -1,19 +0,0 @@
-Developer reference
-===================
-
-.. note::
-
-  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.*
-
-.. toctree::
-   :maxdepth: 2
-
-   reference_classes
-   reference_functions
-   reference_exceptions

From 17f7f297efd29a9b4187af8420e88ca156c1d221 Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Thu, 25 Jan 2024 13:41:45 -0800
Subject: [PATCH 0989/1034] Simplify code in lines.py (#4167)

This has been getting a little messy. These changes neaten things up, we
don't have to keep guarding against `self.previous_line is not None`, we
make it clearer what logic has side effects, we reduce the amount of
code that tricky `before` could touch, etc
---
 src/black/lines.py | 62 +++++++++++++++-------------------------------
 1 file changed, 20 insertions(+), 42 deletions(-)

diff --git a/src/black/lines.py b/src/black/lines.py
index 29f87137614..72634fd36d2 100644
--- a/src/black/lines.py
+++ b/src/black/lines.py
@@ -565,14 +565,9 @@ def maybe_empty_lines(self, current_line: Line) -> LinesBlock:
         )
         before, after = self._maybe_empty_lines(current_line)
         previous_after = self.previous_block.after if self.previous_block else 0
-        before = (
-            # Black should not insert empty lines at the beginning
-            # of the file
-            0
-            if self.previous_line is None
-            else before - previous_after
-        )
+        before = max(0, before - previous_after)
         if (
+            # Always have one empty line after a module docstring
             self.previous_block
             and self.previous_block.previous_block is None
             and len(self.previous_block.original_line.leaves) == 1
@@ -607,10 +602,11 @@ def maybe_empty_lines(self, current_line: Line) -> LinesBlock:
         self.previous_block = block
         return block
 
-    def _maybe_empty_lines(self, current_line: Line) -> Tuple[int, int]:
+    def _maybe_empty_lines(self, current_line: Line) -> Tuple[int, int]:  # noqa: C901
         max_allowed = 1
         if current_line.depth == 0:
             max_allowed = 1 if self.mode.is_pyi else 2
+
         if current_line.leaves:
             # Consume the first leaf's extra newlines.
             first_leaf = current_line.leaves[0]
@@ -623,9 +619,22 @@ def _maybe_empty_lines(self, current_line: Line) -> Tuple[int, int]:
         user_had_newline = bool(before)
         depth = current_line.depth
 
+        # Mutate self.previous_defs, remainder of this function should be pure
         previous_def = None
         while self.previous_defs and self.previous_defs[-1].depth >= depth:
             previous_def = self.previous_defs.pop()
+        if current_line.is_def or current_line.is_class:
+            self.previous_defs.append(current_line)
+
+        if self.previous_line is None:
+            # Don't insert empty lines before the first line in the file.
+            return 0, 0
+
+        if current_line.is_docstring:
+            if self.previous_line.is_class:
+                return 0, 1
+            if self.previous_line.opens_block and self.previous_line.is_def:
+                return 0, 0
 
         if previous_def is not None:
             assert self.previous_line is not None
@@ -668,49 +677,24 @@ def _maybe_empty_lines(self, current_line: Line) -> Tuple[int, int]:
             )
 
         if (
-            self.previous_line
-            and self.previous_line.is_import
+            self.previous_line.is_import
             and not current_line.is_import
             and not current_line.is_fmt_pass_converted(first_leaf_matches=is_import)
             and depth == self.previous_line.depth
         ):
             return (before or 1), 0
 
-        if (
-            self.previous_line
-            and self.previous_line.is_class
-            and current_line.is_docstring
-        ):
-            return 0, 1
-
-        # In preview mode, always allow blank lines, except right before a function
-        # docstring
-        is_empty_first_line_ok = not current_line.is_docstring or (
-            self.previous_line and not self.previous_line.is_def
-        )
-
-        if (
-            self.previous_line
-            and self.previous_line.opens_block
-            and not is_empty_first_line_ok
-        ):
-            return 0, 0
         return before, 0
 
     def _maybe_empty_lines_for_class_or_def(  # noqa: C901
         self, current_line: Line, before: int, user_had_newline: bool
     ) -> Tuple[int, int]:
-        if not current_line.is_decorator:
-            self.previous_defs.append(current_line)
-        if self.previous_line is None:
-            # Don't insert empty lines before the first line in the file.
-            return 0, 0
+        assert self.previous_line is not None
 
         if self.previous_line.is_decorator:
             if self.mode.is_pyi and current_line.is_stub_class:
                 # Insert an empty line after a decorated stub class
                 return 0, 1
-
             return 0, 0
 
         if self.previous_line.depth < current_line.depth and (
@@ -718,8 +702,7 @@ def _maybe_empty_lines_for_class_or_def(  # noqa: C901
         ):
             if self.mode.is_pyi:
                 return 0, 0
-            else:
-                return 1 if user_had_newline else 0, 0
+            return 1 if user_had_newline else 0, 0
 
         comment_to_add_newlines: Optional[LinesBlock] = None
         if (
@@ -750,9 +733,6 @@ def _maybe_empty_lines_for_class_or_def(  # noqa: C901
                     newlines = 0
                 else:
                     newlines = 1
-            # Remove case `self.previous_line.depth > current_line.depth` below when
-            # this becomes stable.
-            #
             # Don't inspect the previous line if it's part of the body of the previous
             # statement in the same level, we always want a blank line if there's
             # something with a body preceding.
@@ -769,8 +749,6 @@ def _maybe_empty_lines_for_class_or_def(  # noqa: C901
                     # Blank line between a block of functions (maybe with preceding
                     # decorators) and a block of non-functions
                     newlines = 1
-            elif self.previous_line.depth > current_line.depth:
-                newlines = 1
             else:
                 newlines = 0
         else:

From 7d789469ed947022f183962b823f5862511272ac Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Thu, 25 Jan 2024 16:15:18 -0800
Subject: [PATCH 0990/1034] Describe 2024 module docstring more accurately
 (#4168)

---
 CHANGES.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index 2fe14cd5246..95ef0095102 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -17,7 +17,7 @@ changes:
 - Hex codes in Unicode escape sequences are now standardized to lowercase (#2916)
 - Allow empty first lines at the beginning of most blocks (#3967, #4061)
 - Add parentheses around long type annotations (#3899)
-- Standardize on a single newline after module docstrings (#3932)
+- Enforce newline after module docstrings (#3932, #4028)
 - Fix incorrect magic trailing comma handling in return types (#3916)
 - Remove blank lines before class docstrings (#3692)
 - Wrap multiple context managers in parentheses if combined in a single `with` statement

From bccec8adfbed2bbc24c0859e8758d5e7809d42b7 Mon Sep 17 00:00:00 2001
From: Daniel Krzeminski <dankrzeminski32@gmail.com>
Date: Thu, 25 Jan 2024 18:41:37 -0600
Subject: [PATCH 0991/1034] Show warning on invalid toml configuration (#4165)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 CHANGES.md                         |  1 +
 src/black/__init__.py              | 17 +++++++++++++++++
 tests/data/incorrect_spelling.toml |  5 +++++
 tests/test_black.py                | 17 +++++++++++++++++
 4 files changed, 40 insertions(+)
 create mode 100644 tests/data/incorrect_spelling.toml

diff --git a/CHANGES.md b/CHANGES.md
index 95ef0095102..45cb967e74a 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -62,6 +62,7 @@ release:
 
 <!-- Changes to how Black can be configured -->
 
+- Print warning when toml config contains an invalid key (#4165)
 - Fix symlink handling, properly catch and ignore symlinks that point outside of root
   (#4161)
 - Fix cache mtime logic that resulted in false positive cache hits (#4128)
diff --git a/src/black/__init__.py b/src/black/__init__.py
index e3cbaab5f1d..961ed9479a8 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -142,6 +142,7 @@ def read_pyproject_toml(
     if not config:
         return None
     else:
+        spellcheck_pyproject_toml_keys(ctx, list(config), value)
         # Sanitize the values to be Click friendly. For more information please see:
         # https://github.com/psf/black/issues/1458
         # https://github.com/pallets/click/issues/1567
@@ -181,6 +182,22 @@ def read_pyproject_toml(
     return value
 
 
+def spellcheck_pyproject_toml_keys(
+    ctx: click.Context, config_keys: List[str], config_file_path: str
+) -> None:
+    invalid_keys: List[str] = []
+    available_config_options = {param.name for param in ctx.command.params}
+    for key in config_keys:
+        if key not in available_config_options:
+            invalid_keys.append(key)
+    if invalid_keys:
+        keys_str = ", ".join(map(repr, invalid_keys))
+        out(
+            f"Invalid config keys detected: {keys_str} (in {config_file_path})",
+            fg="red",
+        )
+
+
 def target_version_option_callback(
     c: click.Context, p: Union[click.Option, click.Parameter], v: Tuple[str, ...]
 ) -> List[TargetVersion]:
diff --git a/tests/data/incorrect_spelling.toml b/tests/data/incorrect_spelling.toml
new file mode 100644
index 00000000000..560c9e27be2
--- /dev/null
+++ b/tests/data/incorrect_spelling.toml
@@ -0,0 +1,5 @@
+[tool.black]
+ine_length = 50
+target-ersion = ['py37']
+exclude='\.pyi?$'
+include='\.py?$'
\ No newline at end of file
diff --git a/tests/test_black.py b/tests/test_black.py
index 2b5fab5d28d..a979a95b674 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -106,6 +106,7 @@ class FakeContext(click.Context):
     def __init__(self) -> None:
         self.default_map: Dict[str, Any] = {}
         self.params: Dict[str, Any] = {}
+        self.command: click.Command = black.main
         # Dummy root, since most of the tests don't care about it
         self.obj: Dict[str, Any] = {"root": PROJECT_ROOT}
 
@@ -1538,6 +1539,22 @@ def test_parse_pyproject_toml(self) -> None:
         self.assertEqual(config["exclude"], r"\.pyi?$")
         self.assertEqual(config["include"], r"\.py?$")
 
+    def test_spellcheck_pyproject_toml(self) -> None:
+        test_toml_file = THIS_DIR / "data" / "incorrect_spelling.toml"
+        result = BlackRunner().invoke(
+            black.main,
+            [
+                "--code=print('hello world')",
+                "--verbose",
+                f"--config={str(test_toml_file)}",
+            ],
+        )
+
+        assert (
+            r"Invalid config keys detected: 'ine_length', 'target_ersion' (in"
+            rf" {test_toml_file})" in result.stderr
+        )
+
     def test_parse_pyproject_toml_project_metadata(self) -> None:
         for test_toml, expected in [
             ("only_black_pyproject.toml", ["py310"]),

From 4f47cac1925a2232892ceae438e2c62f81517714 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Thu, 25 Jan 2024 17:00:47 -0800
Subject: [PATCH 0992/1034] Add --unstable flag (#4096)

---
 CHANGES.md                                    |  17 ++
 docs/faq.md                                   |   7 +-
 docs/the_black_code_style/current_style.md    |   6 +
 docs/the_black_code_style/future_style.md     | 217 +++++++++---------
 docs/the_black_code_style/index.md            |   8 +-
 .../black_as_a_server.md                      |   6 +
 docs/usage_and_configuration/the_basics.md    |  31 ++-
 pyproject.toml                                |   9 +-
 src/black/__init__.py                         |  49 +++-
 src/black/mode.py                             |  39 ++--
 src/blackd/__init__.py                        | 104 +++++----
 tests/data/cases/preview_cantfit.py           |  14 --
 tests/data/cases/preview_cantfit_string.py    |  18 ++
 tests/data/cases/preview_comments7.py         |   2 +-
 tests/data/cases/preview_long_dict_values.py  |   2 +-
 tests/data/cases/preview_long_strings.py      |   2 +-
 .../preview_long_strings__east_asian_width.py |   2 +-
 .../cases/preview_long_strings__edge_case.py  |   2 +-
 .../cases/preview_long_strings__regression.py |   2 +-
 tests/data/cases/preview_multiline_strings.py |   2 +-
 ...eview_return_annotation_brackets_string.py |   2 +-
 tests/test_black.py                           |  63 ++---
 tests/util.py                                 |  16 +-
 23 files changed, 368 insertions(+), 252 deletions(-)
 create mode 100644 tests/data/cases/preview_cantfit_string.py

diff --git a/CHANGES.md b/CHANGES.md
index 45cb967e74a..0496603e2c0 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -34,6 +34,14 @@ changes:
 - Fix incorrect formatting of certain async statements (#3609)
 - Allow combining `# fmt: skip` with other comments (#3959)
 
+There are already a few improvements in the `--preview` style, which are slated for the
+2025 stable style. Try them out and
+[share your feedback](https://github.com/psf/black/issues). In the past, the preview
+style has included some features that we were not able to stabilize. This year, we're
+adding a separate `--unstable` style for features with known problems. Now, the
+`--preview` style only includes features that we actually expect to make it into next
+year's stable style.
+
 ### Stable style
 
 <!-- Changes that affect Black's stable style -->
@@ -53,6 +61,12 @@ release:
 
 <!-- Changes that affect Black's preview style -->
 
+- Add `--unstable` style, covering preview features that have known problems that would
+  block them from going into the stable style. Also add the `--enable-unstable-feature`
+  flag; for example, use
+  `--enable-unstable-feature hug_parens_with_braces_and_square_brackets` to apply this
+  preview style throughout 2024, even if a later Black release downgrades the feature to
+  unstable (#4096)
 - Format module docstrings the same as class and function docstrings (#4095)
 - Fix crash when using a walrus in a dictionary (#4155)
 - Fix unnecessary parentheses when wrapping long dicts (#4135)
@@ -66,6 +80,9 @@ release:
 - Fix symlink handling, properly catch and ignore symlinks that point outside of root
   (#4161)
 - Fix cache mtime logic that resulted in false positive cache hits (#4128)
+- Remove the long-deprecated `--experimental-string-processing` flag. This feature can
+  currently be enabled with `--preview --enable-unstable-feature string_processing`.
+  (#4096)
 
 ### Packaging
 
diff --git a/docs/faq.md b/docs/faq.md
index c62e1b504b5..124a096efac 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -41,9 +41,10 @@ other tools, such as `# noqa`, may be moved by _Black_. See below for more detai
 Stable. _Black_ aims to enforce one style and one style only, with some room for
 pragmatism. See [The Black Code Style](the_black_code_style/index.md) for more details.
 
-Starting in 2022, the formatting output will be stable for the releases made in the same
-year (other than unintentional bugs). It is possible to opt-in to the latest formatting
-styles, using the `--preview` flag.
+Starting in 2022, the formatting output is stable for the releases made in the same year
+(other than unintentional bugs). At the beginning of every year, the first release will
+make changes to the stable style. It is possible to opt in to the latest formatting
+styles using the `--preview` flag.
 
 ## Why is my file not formatted?
 
diff --git a/docs/the_black_code_style/current_style.md b/docs/the_black_code_style/current_style.md
index 00bd81416dc..ca5d1d4a701 100644
--- a/docs/the_black_code_style/current_style.md
+++ b/docs/the_black_code_style/current_style.md
@@ -449,6 +449,12 @@ file that are not enforced yet but might be in a future version of the formatter
 _Black_ will normalize line endings (`\n` or `\r\n`) based on the first line ending of
 the file.
 
+### Form feed characters
+
+_Black_ will retain form feed characters on otherwise empty lines at the module level.
+Only one form feed is retained for a group of consecutive empty lines. Where there are
+two empty lines in a row, the form feed is placed on the second line.
+
 ## Pragmatism
 
 Early versions of _Black_ used to be absolutist in some respects. They took after its
diff --git a/docs/the_black_code_style/future_style.md b/docs/the_black_code_style/future_style.md
index f55ea5f60a9..1cdd25fdb7c 100644
--- a/docs/the_black_code_style/future_style.md
+++ b/docs/the_black_code_style/future_style.md
@@ -1,54 +1,5 @@
 # The (future of the) Black code style
 
-```{warning}
-Changes to this document often aren't tied and don't relate to releases of
-_Black_. It's recommended that you read the latest version available.
-```
-
-## Using backslashes for with statements
-
-[Backslashes are bad and should be never be used](labels/why-no-backslashes) however
-there is one exception: `with` statements using multiple context managers. Before Python
-3.9 Python's grammar does not allow organizing parentheses around the series of context
-managers.
-
-We don't want formatting like:
-
-```py3
-with make_context_manager1() as cm1, make_context_manager2() as cm2, make_context_manager3() as cm3, make_context_manager4() as cm4:
-    ...  # nothing to split on - line too long
-```
-
-So _Black_ will, when we implement this, format it like this:
-
-```py3
-with \
-     make_context_manager1() as cm1, \
-     make_context_manager2() as cm2, \
-     make_context_manager3() as cm3, \
-     make_context_manager4() as cm4 \
-:
-    ...  # backslashes and an ugly stranded colon
-```
-
-Although when the target version is Python 3.9 or higher, _Black_ uses parentheses
-instead in `--preview` mode (see below) since they're allowed in Python 3.9 and higher.
-
-An alternative to consider if the backslashes in the above formatting are undesirable is
-to use {external:py:obj}`contextlib.ExitStack` to combine context managers in the
-following way:
-
-```python
-with contextlib.ExitStack() as exit_stack:
-    cm1 = exit_stack.enter_context(make_context_manager1())
-    cm2 = exit_stack.enter_context(make_context_manager2())
-    cm3 = exit_stack.enter_context(make_context_manager3())
-    cm4 = exit_stack.enter_context(make_context_manager4())
-    ...
-```
-
-(labels/preview-style)=
-
 ## Preview style
 
 Experimental, potentially disruptive style changes are gathered under the `--preview`
@@ -56,62 +7,38 @@ CLI flag. At the end of each year, these changes may be adopted into the default
 as described in [The Black Code Style](index.md). Because the functionality is
 experimental, feedback and issue reports are highly encouraged!
 
-### Improved string processing
-
-_Black_ will split long string literals and merge short ones. Parentheses are used where
-appropriate. When split, parts of f-strings that don't need formatting are converted to
-plain strings. User-made splits are respected when they do not exceed the line length
-limit. Line continuation backslashes are converted into parenthesized strings.
-Unnecessary parentheses are stripped. The stability and status of this feature is
-tracked in [this issue](https://github.com/psf/black/issues/2188).
-
-### Improved line breaks
-
-For assignment expressions, _Black_ now prefers to split and wrap the right side of the
-assignment instead of left side. For example:
-
-```python
-some_dict[
-    "with_a_long_key"
-] = some_looooooooong_module.some_looooooooooooooong_function_name(
-    first_argument, second_argument, third_argument
-)
-```
-
-will be changed to:
+In the past, the preview style included some features with known bugs, so that we were
+unable to move these features to the stable style. Therefore, such features are now
+moved to the `--unstable` style. All features in the `--preview` style are expected to
+make it to next year's stable style; features in the `--unstable` style will be
+stabilized only if issues with them are fixed. If bugs are discovered in a `--preview`
+feature, it is demoted to the `--unstable` style. To avoid thrash when a feature is
+demoted from the `--preview` to the `--unstable` style, users can use the
+`--enable-unstable-feature` flag to enable specific unstable features.
 
-```python
-some_dict["with_a_long_key"] = (
-    some_looooooooong_module.some_looooooooooooooong_function_name(
-        first_argument, second_argument, third_argument
-    )
-)
-```
+Currently, the following features are included in the preview style:
 
-### Improved parentheses management
+- `hex_codes_in_unicode_sequences`: normalize casing of Unicode escape characters in
+  strings
+- `unify_docstring_detection`: fix inconsistencies in whether certain strings are
+  detected as docstrings
+- `hug_parens_with_braces_and_square_brackets`: more compact formatting of nested
+  brackets ([see below](labels/hug-parens))
+- `no_normalize_fmt_skip_whitespace`: whitespace before `# fmt: skip` comments is no
+  longer normalized
 
-For dict literals with long values, they are now wrapped in parentheses. Unnecessary
-parentheses are now removed. For example:
+(labels/unstable-features)=
 
-```python
-my_dict = {
-    "a key in my dict": a_very_long_variable
-    * and_a_very_long_function_call()
-    / 100000.0,
-    "another key": (short_value),
-}
-```
+The unstable style additionally includes the following features:
 
-will be changed to:
+- `string_processing`: split long string literals and related changes
+  ([see below](labels/string-processing))
+- `wrap_long_dict_values_in_parens`: add parentheses to long values in dictionaries
+  ([see below](labels/wrap-long-dict-values))
+- `multiline_string_handling`: more compact formatting of expressions involving
+  multiline strings ([see below](labels/multiline-string-handling))
 
-```python
-my_dict = {
-    "a key in my dict": (
-        a_very_long_variable * and_a_very_long_function_call() / 100000.0
-    ),
-    "another key": short_value,
-}
-```
+(labels/hug-parens)=
 
 ### Improved multiline dictionary and list indentation for sole function parameter
 
@@ -185,6 +112,46 @@ foo(
 )
 ```
 
+(labels/string-processing)=
+
+### Improved string processing
+
+_Black_ will split long string literals and merge short ones. Parentheses are used where
+appropriate. When split, parts of f-strings that don't need formatting are converted to
+plain strings. User-made splits are respected when they do not exceed the line length
+limit. Line continuation backslashes are converted into parenthesized strings.
+Unnecessary parentheses are stripped. The stability and status of this feature is
+tracked in [this issue](https://github.com/psf/black/issues/2188).
+
+(labels/wrap-long-dict-values)=
+
+### Improved parentheses management in dicts
+
+For dict literals with long values, they are now wrapped in parentheses. Unnecessary
+parentheses are now removed. For example:
+
+```python
+my_dict = {
+    "a key in my dict": a_very_long_variable
+    * and_a_very_long_function_call()
+    / 100000.0,
+    "another key": (short_value),
+}
+```
+
+will be changed to:
+
+```python
+my_dict = {
+    "a key in my dict": (
+        a_very_long_variable * and_a_very_long_function_call() / 100000.0
+    ),
+    "another key": short_value,
+}
+```
+
+(labels/multiline-string-handling)=
+
 ### Improved multiline string handling
 
 _Black_ is smarter when formatting multiline strings, especially in function arguments,
@@ -297,13 +264,51 @@ s = (  # Top comment
 )
 ```
 
-=======
+## Potential future changes
+
+This section lists changes that we may want to make in the future, but that aren't
+implemented yet.
+
+### Using backslashes for with statements
+
+[Backslashes are bad and should be never be used](labels/why-no-backslashes) however
+there is one exception: `with` statements using multiple context managers. Before Python
+3.9 Python's grammar does not allow organizing parentheses around the series of context
+managers.
+
+We don't want formatting like:
+
+```py3
+with make_context_manager1() as cm1, make_context_manager2() as cm2, make_context_manager3() as cm3, make_context_manager4() as cm4:
+    ...  # nothing to split on - line too long
+```
+
+So _Black_ will, when we implement this, format it like this:
+
+```py3
+with \
+     make_context_manager1() as cm1, \
+     make_context_manager2() as cm2, \
+     make_context_manager3() as cm3, \
+     make_context_manager4() as cm4 \
+:
+    ...  # backslashes and an ugly stranded colon
+```
+
+Although when the target version is Python 3.9 or higher, _Black_ uses parentheses
+instead in `--preview` mode (see below) since they're allowed in Python 3.9 and higher.
 
-### Form feed characters
+An alternative to consider if the backslashes in the above formatting are undesirable is
+to use {external:py:obj}`contextlib.ExitStack` to combine context managers in the
+following way:
 
-_Black_ will now retain form feed characters on otherwise empty lines at the module
-level. Only one form feed is retained for a group of consecutive empty lines. Where
-there are two empty lines in a row, the form feed will be placed on the second line.
+```python
+with contextlib.ExitStack() as exit_stack:
+    cm1 = exit_stack.enter_context(make_context_manager1())
+    cm2 = exit_stack.enter_context(make_context_manager2())
+    cm3 = exit_stack.enter_context(make_context_manager3())
+    cm4 = exit_stack.enter_context(make_context_manager4())
+    ...
+```
 
-_Black_ already retained form feed literals inside a comment or inside a string. This
-remains the case.
+(labels/preview-style)=
diff --git a/docs/the_black_code_style/index.md b/docs/the_black_code_style/index.md
index 1719347eec8..58f28673022 100644
--- a/docs/the_black_code_style/index.md
+++ b/docs/the_black_code_style/index.md
@@ -42,9 +42,11 @@ _Black_:
   enabled by newer Python language syntax as well as due to improvements in the
   formatting logic.
 
-- The `--preview` flag is exempt from this policy. There are no guarantees around the
-  stability of the output with that flag passed into _Black_. This flag is intended for
-  allowing experimentation with the proposed changes to the _Black_ code style.
+- The `--preview` and `--unstable` flags are exempt from this policy. There are no
+  guarantees around the stability of the output with these flags passed into _Black_.
+  They are intended for allowing experimentation with proposed changes to the _Black_
+  code style. The `--preview` style at the end of a year should closely match the stable
+  style for the next year, but we may always make changes.
 
 Documentation for both the current and future styles can be found:
 
diff --git a/docs/usage_and_configuration/black_as_a_server.md b/docs/usage_and_configuration/black_as_a_server.md
index f24fb34d915..0a7edb57fd7 100644
--- a/docs/usage_and_configuration/black_as_a_server.md
+++ b/docs/usage_and_configuration/black_as_a_server.md
@@ -62,6 +62,12 @@ The headers controlling how source code is formatted are:
 - `X-Preview`: corresponds to the `--preview` command line flag. If present and its
   value is not an empty string, experimental and potentially disruptive style changes
   will be used.
+- `X-Unstable`: corresponds to the `--unstable` command line flag. If present and its
+  value is not an empty string, experimental style changes that are known to be buggy
+  will be used.
+- `X-Enable-Unstable-Feature`: corresponds to the `--enable-unstable-feature` flag. The
+  contents of the flag must be a comma-separated list of unstable features to be
+  enabled. Example: `X-Enable-Unstable-Feature: feature1, feature2`.
 - `X-Fast-Or-Safe`: if set to `fast`, `blackd` will act as _Black_ does when passed the
   `--fast` command line flag.
 - `X-Python-Variant`: if set to `pyi`, `blackd` will act as _Black_ does when passed the
diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index b541f07907c..a42e093155b 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -144,9 +144,34 @@ magic trailing comma is ignored.
 
 #### `--preview`
 
-Enable potentially disruptive style changes that may be added to Black's main
-functionality in the next major release. Read more about
-[our preview style](labels/preview-style).
+Enable potentially disruptive style changes that we expect to add to Black's main
+functionality in the next major release. Use this if you want a taste of what next
+year's style will look like.
+
+Read more about [our preview style](labels/preview-style).
+
+There is no guarantee on the code style produced by this flag across releases.
+
+#### `--unstable`
+
+Enable all style changes in `--preview`, plus additional changes that we would like to
+make eventually, but that have known issues that need to be fixed before they can move
+back to the `--preview` style. Use this if you want to experiment with these changes and
+help fix issues with them.
+
+There is no guarantee on the code style produced by this flag across releases.
+
+#### `--enable-unstable-feature`
+
+Enable specific features from the `--unstable` style. See
+[the preview style documentation](labels/unstable-features) for the list of supported
+features. This flag can only be used when `--preview` is enabled. Users are encouraged
+to use this flag if they use `--preview` style and a feature that affects their code is
+moved from the `--preview` to the `--unstable` style, but they want to avoid the thrash
+from undoing this change.
+
+There are no guarantees on the behavior of these features, or even their existence,
+across releases.
 
 (labels/exit-code)=
 
diff --git a/pyproject.toml b/pyproject.toml
index 24b9c07674d..fa3654b8d67 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -16,10 +16,11 @@ extend-exclude = '''
   | profiling
 )/
 '''
-# We use preview style for formatting Black itself. If you
-# want stable formatting across releases, you should keep
-# this off.
-preview = true
+# We use the unstable style for formatting Black itself. If you
+# want bug-free formatting, you should keep this off. If you want
+# stable formatting across releases, you should also keep `preview = true`
+# (which is implied by this flag) off.
+unstable = true
 
 # Build system information and other project-specific configuration below.
 # NOTE: You don't need this in your own Black configuration.
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 961ed9479a8..ebc7ac8eda5 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -68,7 +68,7 @@
 from black.lines import EmptyLineTracker, LinesBlock
 from black.mode import FUTURE_FLAG_TO_FEATURE, VERSION_TO_FEATURES, Feature
 from black.mode import Mode as Mode  # re-exported
-from black.mode import TargetVersion, supports_feature
+from black.mode import Preview, TargetVersion, supports_feature
 from black.nodes import (
     STARS,
     is_number_token,
@@ -209,6 +209,13 @@ def target_version_option_callback(
     return [TargetVersion[val.upper()] for val in v]
 
 
+def enable_unstable_feature_callback(
+    c: click.Context, p: Union[click.Option, click.Parameter], v: Tuple[str, ...]
+) -> List[Preview]:
+    """Compute the features from an --enable-unstable-feature flag."""
+    return [Preview[val] for val in v]
+
+
 def re_compile_maybe_verbose(regex: str) -> Pattern[str]:
     """Compile a regular expression string in `regex`.
 
@@ -303,12 +310,6 @@ def validate_regex(
     is_flag=True,
     help="Don't use trailing commas as a reason to split lines.",
 )
-@click.option(
-    "--experimental-string-processing",
-    is_flag=True,
-    hidden=True,
-    help="(DEPRECATED and now included in --preview) Normalize string literals.",
-)
 @click.option(
     "--preview",
     is_flag=True,
@@ -317,6 +318,26 @@ def validate_regex(
         " functionality in the next major release."
     ),
 )
+@click.option(
+    "--unstable",
+    is_flag=True,
+    help=(
+        "Enable potentially disruptive style changes that have known bugs or are not"
+        " currently expected to make it into the stable style Black's next major"
+        " release. Implies --preview."
+    ),
+)
+@click.option(
+    "--enable-unstable-feature",
+    type=click.Choice([v.name for v in Preview]),
+    callback=enable_unstable_feature_callback,
+    multiple=True,
+    help=(
+        "Enable specific features included in the `--unstable` style. Requires"
+        " `--preview`. No compatibility guarantees are provided on the behavior"
+        " or existence of any unstable features."
+    ),
+)
 @click.option(
     "--check",
     is_flag=True,
@@ -507,8 +528,9 @@ def main(  # noqa: C901
     skip_source_first_line: bool,
     skip_string_normalization: bool,
     skip_magic_trailing_comma: bool,
-    experimental_string_processing: bool,
     preview: bool,
+    unstable: bool,
+    enable_unstable_feature: List[Preview],
     quiet: bool,
     verbose: bool,
     required_version: Optional[str],
@@ -534,6 +556,14 @@ def main(  # noqa: C901
         out(main.get_usage(ctx) + "\n\nOne of 'SRC' or 'code' is required.")
         ctx.exit(1)
 
+    # It doesn't do anything if --unstable is also passed, so just allow it.
+    if enable_unstable_feature and not (preview or unstable):
+        out(
+            main.get_usage(ctx)
+            + "\n\n'--enable-unstable-feature' requires '--preview'."
+        )
+        ctx.exit(1)
+
     root, method = (
         find_project_root(src, stdin_filename) if code is None else (None, None)
     )
@@ -595,9 +625,10 @@ def main(  # noqa: C901
         skip_source_first_line=skip_source_first_line,
         string_normalization=not skip_string_normalization,
         magic_trailing_comma=not skip_magic_trailing_comma,
-        experimental_string_processing=experimental_string_processing,
         preview=preview,
+        unstable=unstable,
         python_cell_magics=set(python_cell_magics),
+        enabled_features=set(enable_unstable_feature),
     )
 
     lines: List[Tuple[int, int]] = []
diff --git a/src/black/mode.py b/src/black/mode.py
index a1519f17bcc..68919fb4901 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -9,7 +9,6 @@
 from hashlib import sha256
 from operator import attrgetter
 from typing import Dict, Final, Set
-from warnings import warn
 
 from black.const import DEFAULT_LINE_LENGTH
 
@@ -179,6 +178,16 @@ class Preview(Enum):
     multiline_string_handling = auto()
 
 
+UNSTABLE_FEATURES: Set[Preview] = {
+    # Many issues, see summary in https://github.com/psf/black/issues/4042
+    Preview.string_processing,
+    # See issues #3452 and #4158
+    Preview.wrap_long_dict_values_in_parens,
+    # See issue #4159
+    Preview.multiline_string_handling,
+}
+
+
 class Deprecated(UserWarning):
     """Visible deprecation warning."""
 
@@ -192,28 +201,24 @@ class Mode:
     is_ipynb: bool = False
     skip_source_first_line: bool = False
     magic_trailing_comma: bool = True
-    experimental_string_processing: bool = False
     python_cell_magics: Set[str] = field(default_factory=set)
     preview: bool = False
-
-    def __post_init__(self) -> None:
-        if self.experimental_string_processing:
-            warn(
-                "`experimental string processing` has been included in `preview`"
-                " and deprecated. Use `preview` instead.",
-                Deprecated,
-            )
+    unstable: bool = False
+    enabled_features: Set[Preview] = field(default_factory=set)
 
     def __contains__(self, feature: Preview) -> bool:
         """
         Provide `Preview.FEATURE in Mode` syntax that mirrors the ``preview`` flag.
 
-        The argument is not checked and features are not differentiated.
-        They only exist to make development easier by clarifying intent.
+        In unstable mode, all features are enabled. In preview mode, all features
+        except those in UNSTABLE_FEATURES are enabled. Any features in
+        `self.enabled_features` are also enabled.
         """
-        if feature is Preview.string_processing:
-            return self.preview or self.experimental_string_processing
-        return self.preview
+        if self.unstable:
+            return True
+        if feature in self.enabled_features:
+            return True
+        return self.preview and feature not in UNSTABLE_FEATURES
 
     def get_cache_key(self) -> str:
         if self.target_versions:
@@ -231,7 +236,9 @@ def get_cache_key(self) -> str:
             str(int(self.is_ipynb)),
             str(int(self.skip_source_first_line)),
             str(int(self.magic_trailing_comma)),
-            str(int(self.experimental_string_processing)),
+            sha256(
+                (",".join(sorted(f.name for f in self.enabled_features))).encode()
+            ).hexdigest(),
             str(int(self.preview)),
             sha256((",".join(sorted(self.python_cell_magics))).encode()).hexdigest(),
         ]
diff --git a/src/blackd/__init__.py b/src/blackd/__init__.py
index 6b0f3d33295..7041671f596 100644
--- a/src/blackd/__init__.py
+++ b/src/blackd/__init__.py
@@ -8,6 +8,7 @@
 
 try:
     from aiohttp import web
+    from multidict import MultiMapping
 
     from .middlewares import cors
 except ImportError as ie:
@@ -34,6 +35,8 @@
 SKIP_STRING_NORMALIZATION_HEADER = "X-Skip-String-Normalization"
 SKIP_MAGIC_TRAILING_COMMA = "X-Skip-Magic-Trailing-Comma"
 PREVIEW = "X-Preview"
+UNSTABLE = "X-Unstable"
+ENABLE_UNSTABLE_FEATURE = "X-Enable-Unstable-Feature"
 FAST_OR_SAFE_HEADER = "X-Fast-Or-Safe"
 DIFF_HEADER = "X-Diff"
 
@@ -45,6 +48,8 @@
     SKIP_STRING_NORMALIZATION_HEADER,
     SKIP_MAGIC_TRAILING_COMMA,
     PREVIEW,
+    UNSTABLE,
+    ENABLE_UNSTABLE_FEATURE,
     FAST_OR_SAFE_HEADER,
     DIFF_HEADER,
 ]
@@ -53,6 +58,10 @@
 BLACK_VERSION_HEADER = "X-Black-Version"
 
 
+class HeaderError(Exception):
+    pass
+
+
 class InvalidVariantHeader(Exception):
     pass
 
@@ -93,55 +102,21 @@ async def handle(request: web.Request, executor: Executor) -> web.Response:
             return web.Response(
                 status=501, text="This server only supports protocol version 1"
             )
-        try:
-            line_length = int(
-                request.headers.get(LINE_LENGTH_HEADER, black.DEFAULT_LINE_LENGTH)
-            )
-        except ValueError:
-            return web.Response(status=400, text="Invalid line length header value")
 
-        if PYTHON_VARIANT_HEADER in request.headers:
-            value = request.headers[PYTHON_VARIANT_HEADER]
-            try:
-                pyi, versions = parse_python_variant_header(value)
-            except InvalidVariantHeader as e:
-                return web.Response(
-                    status=400,
-                    text=f"Invalid value for {PYTHON_VARIANT_HEADER}: {e.args[0]}",
-                )
-        else:
-            pyi = False
-            versions = set()
-
-        skip_string_normalization = bool(
-            request.headers.get(SKIP_STRING_NORMALIZATION_HEADER, False)
-        )
-        skip_magic_trailing_comma = bool(
-            request.headers.get(SKIP_MAGIC_TRAILING_COMMA, False)
-        )
-        skip_source_first_line = bool(
-            request.headers.get(SKIP_SOURCE_FIRST_LINE, False)
-        )
-        preview = bool(request.headers.get(PREVIEW, False))
         fast = False
         if request.headers.get(FAST_OR_SAFE_HEADER, "safe") == "fast":
             fast = True
-        mode = black.FileMode(
-            target_versions=versions,
-            is_pyi=pyi,
-            line_length=line_length,
-            skip_source_first_line=skip_source_first_line,
-            string_normalization=not skip_string_normalization,
-            magic_trailing_comma=not skip_magic_trailing_comma,
-            preview=preview,
-        )
+        try:
+            mode = parse_mode(request.headers)
+        except HeaderError as e:
+            return web.Response(status=400, text=e.args[0])
         req_bytes = await request.content.read()
         charset = request.charset if request.charset is not None else "utf8"
         req_str = req_bytes.decode(charset)
         then = datetime.now(timezone.utc)
 
         header = ""
-        if skip_source_first_line:
+        if mode.skip_source_first_line:
             first_newline_position: int = req_str.find("\n") + 1
             header = req_str[:first_newline_position]
             req_str = req_str[first_newline_position:]
@@ -190,6 +165,57 @@ async def handle(request: web.Request, executor: Executor) -> web.Response:
         return web.Response(status=500, headers=headers, text=str(e))
 
 
+def parse_mode(headers: MultiMapping[str]) -> black.Mode:
+    try:
+        line_length = int(headers.get(LINE_LENGTH_HEADER, black.DEFAULT_LINE_LENGTH))
+    except ValueError:
+        raise HeaderError("Invalid line length header value") from None
+
+    if PYTHON_VARIANT_HEADER in headers:
+        value = headers[PYTHON_VARIANT_HEADER]
+        try:
+            pyi, versions = parse_python_variant_header(value)
+        except InvalidVariantHeader as e:
+            raise HeaderError(
+                f"Invalid value for {PYTHON_VARIANT_HEADER}: {e.args[0]}",
+            ) from None
+    else:
+        pyi = False
+        versions = set()
+
+    skip_string_normalization = bool(
+        headers.get(SKIP_STRING_NORMALIZATION_HEADER, False)
+    )
+    skip_magic_trailing_comma = bool(headers.get(SKIP_MAGIC_TRAILING_COMMA, False))
+    skip_source_first_line = bool(headers.get(SKIP_SOURCE_FIRST_LINE, False))
+
+    preview = bool(headers.get(PREVIEW, False))
+    unstable = bool(headers.get(UNSTABLE, False))
+    enable_features: Set[black.Preview] = set()
+    enable_unstable_features = headers.get(ENABLE_UNSTABLE_FEATURE, "").split(",")
+    for piece in enable_unstable_features:
+        piece = piece.strip()
+        if piece:
+            try:
+                enable_features.add(black.Preview[piece])
+            except KeyError:
+                raise HeaderError(
+                    f"Invalid value for {ENABLE_UNSTABLE_FEATURE}: {piece}",
+                ) from None
+
+    return black.FileMode(
+        target_versions=versions,
+        is_pyi=pyi,
+        line_length=line_length,
+        skip_source_first_line=skip_source_first_line,
+        string_normalization=not skip_string_normalization,
+        magic_trailing_comma=not skip_magic_trailing_comma,
+        preview=preview,
+        unstable=unstable,
+        enabled_features=enable_features,
+    )
+
+
 def parse_python_variant_header(value: str) -> Tuple[bool, Set[black.TargetVersion]]:
     if value == "pyi":
         return True, set()
diff --git a/tests/data/cases/preview_cantfit.py b/tests/data/cases/preview_cantfit.py
index d5da6654f0c..29789c7e653 100644
--- a/tests/data/cases/preview_cantfit.py
+++ b/tests/data/cases/preview_cantfit.py
@@ -20,12 +20,6 @@
 normal_name = but_the_function_name_is_now_ridiculously_long_and_it_is_still_super_annoying(
     [1, 2, 3], arg1, [1, 2, 3], arg2, [1, 2, 3], arg3
 )
-# long arguments
-normal_name = normal_function_name(
-    "but with super long string arguments that on their own exceed the line limit so there's no way it can ever fit",
-    "eggs with spam and eggs and spam with eggs with spam and eggs and spam with eggs with spam and eggs and spam with eggs",
-    this_is_a_ridiculously_long_name_and_nobody_in_their_right_mind_would_use_one_like_it=0,
-)
 string_variable_name = (
     "a string that is waaaaaaaayyyyyyyy too long, even in parens, there's nothing you can do"  # noqa
 )
@@ -78,14 +72,6 @@
         [1, 2, 3], arg1, [1, 2, 3], arg2, [1, 2, 3], arg3
     )
 )
-# long arguments
-normal_name = normal_function_name(
-    "but with super long string arguments that on their own exceed the line limit so"
-    " there's no way it can ever fit",
-    "eggs with spam and eggs and spam with eggs with spam and eggs and spam with eggs"
-    " with spam and eggs and spam with eggs",
-    this_is_a_ridiculously_long_name_and_nobody_in_their_right_mind_would_use_one_like_it=0,
-)
 string_variable_name = "a string that is waaaaaaaayyyyyyyy too long, even in parens, there's nothing you can do"  # noqa
 for key in """
     hostname
diff --git a/tests/data/cases/preview_cantfit_string.py b/tests/data/cases/preview_cantfit_string.py
new file mode 100644
index 00000000000..3b48e318ade
--- /dev/null
+++ b/tests/data/cases/preview_cantfit_string.py
@@ -0,0 +1,18 @@
+# flags: --unstable
+# long arguments
+normal_name = normal_function_name(
+    "but with super long string arguments that on their own exceed the line limit so there's no way it can ever fit",
+    "eggs with spam and eggs and spam with eggs with spam and eggs and spam with eggs with spam and eggs and spam with eggs",
+    this_is_a_ridiculously_long_name_and_nobody_in_their_right_mind_would_use_one_like_it=0,
+)
+
+# output
+
+# long arguments
+normal_name = normal_function_name(
+    "but with super long string arguments that on their own exceed the line limit so"
+    " there's no way it can ever fit",
+    "eggs with spam and eggs and spam with eggs with spam and eggs and spam with eggs"
+    " with spam and eggs and spam with eggs",
+    this_is_a_ridiculously_long_name_and_nobody_in_their_right_mind_would_use_one_like_it=0,
+)
diff --git a/tests/data/cases/preview_comments7.py b/tests/data/cases/preview_comments7.py
index 006d4f7266f..e4d547138db 100644
--- a/tests/data/cases/preview_comments7.py
+++ b/tests/data/cases/preview_comments7.py
@@ -1,4 +1,4 @@
-# flags: --preview
+# flags: --unstable
 from .config import (
     Any,
     Bool,
diff --git a/tests/data/cases/preview_long_dict_values.py b/tests/data/cases/preview_long_dict_values.py
index 54da76038dc..a19210605f6 100644
--- a/tests/data/cases/preview_long_dict_values.py
+++ b/tests/data/cases/preview_long_dict_values.py
@@ -1,4 +1,4 @@
-# flags: --preview
+# flags: --unstable
 my_dict = {
     "something_something":
         r"Lorem ipsum dolor sit amet, an sed convenire eloquentiam \t"
diff --git a/tests/data/cases/preview_long_strings.py b/tests/data/cases/preview_long_strings.py
index 19ac47a7032..86fa1b0c7e1 100644
--- a/tests/data/cases/preview_long_strings.py
+++ b/tests/data/cases/preview_long_strings.py
@@ -1,4 +1,4 @@
-# flags: --preview
+# flags: --unstable
 x = "This is a really long string that can't possibly be expected to fit all together on one line. In fact it may even take up three or more lines... like four or five... but probably just three."
 
 x += "This is a really long string that can't possibly be expected to fit all together on one line. In fact it may even take up three or more lines... like four or five... but probably just three."
diff --git a/tests/data/cases/preview_long_strings__east_asian_width.py b/tests/data/cases/preview_long_strings__east_asian_width.py
index d190f422a60..022b0452522 100644
--- a/tests/data/cases/preview_long_strings__east_asian_width.py
+++ b/tests/data/cases/preview_long_strings__east_asian_width.py
@@ -1,4 +1,4 @@
-# flags: --preview
+# flags: --unstable
 # The following strings do not have not-so-many chars, but are long enough
 # when these are rendered in a monospace font (if the renderer respects
 # Unicode East Asian Width properties).
diff --git a/tests/data/cases/preview_long_strings__edge_case.py b/tests/data/cases/preview_long_strings__edge_case.py
index a8e8971968c..28497e731bc 100644
--- a/tests/data/cases/preview_long_strings__edge_case.py
+++ b/tests/data/cases/preview_long_strings__edge_case.py
@@ -1,4 +1,4 @@
-# flags: --preview
+# flags: --unstable
 some_variable = "This string is long but not so long that it needs to be split just yet"
 some_variable = 'This string is long but not so long that it needs to be split just yet'
 some_variable = "This string is long, just long enough that it needs to be split, u get?"
diff --git a/tests/data/cases/preview_long_strings__regression.py b/tests/data/cases/preview_long_strings__regression.py
index 5e76a8cf61c..afe2b311cf4 100644
--- a/tests/data/cases/preview_long_strings__regression.py
+++ b/tests/data/cases/preview_long_strings__regression.py
@@ -1,4 +1,4 @@
-# flags: --preview
+# flags: --unstable
 class A:
     def foo():
         result = type(message)("")
diff --git a/tests/data/cases/preview_multiline_strings.py b/tests/data/cases/preview_multiline_strings.py
index 3ff643610b7..9288f6991bd 100644
--- a/tests/data/cases/preview_multiline_strings.py
+++ b/tests/data/cases/preview_multiline_strings.py
@@ -1,4 +1,4 @@
-# flags: --preview
+# flags: --unstable
 """cow
 say""",
 call(3, "dogsay", textwrap.dedent("""dove
diff --git a/tests/data/cases/preview_return_annotation_brackets_string.py b/tests/data/cases/preview_return_annotation_brackets_string.py
index fea0ea6839a..2f937cf54ef 100644
--- a/tests/data/cases/preview_return_annotation_brackets_string.py
+++ b/tests/data/cases/preview_return_annotation_brackets_string.py
@@ -1,4 +1,4 @@
-# flags: --preview
+# flags: --unstable
 # Long string example
 def frobnicate() -> "ThisIsTrulyUnreasonablyExtremelyLongClassName | list[ThisIsTrulyUnreasonablyExtremelyLongClassName]":
     pass
diff --git a/tests/test_black.py b/tests/test_black.py
index a979a95b674..6dbe25a90b6 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -158,13 +158,11 @@ def test_empty_ff(self) -> None:
 
     @patch("black.dump_to_file", dump_to_stderr)
     def test_one_empty_line(self) -> None:
-        mode = black.Mode(preview=True)
         for nl in ["\n", "\r\n"]:
             source = expected = nl
-            assert_format(source, expected, mode=mode)
+            assert_format(source, expected)
 
     def test_one_empty_line_ff(self) -> None:
-        mode = black.Mode(preview=True)
         for nl in ["\n", "\r\n"]:
             expected = nl
             tmp_file = Path(black.dump_to_file(nl))
@@ -175,20 +173,13 @@ def test_one_empty_line_ff(self) -> None:
                 with open(tmp_file, "wb") as f:
                     f.write(nl.encode("utf-8"))
             try:
-                self.assertFalse(
-                    ff(tmp_file, mode=mode, write_back=black.WriteBack.YES)
-                )
+                self.assertFalse(ff(tmp_file, write_back=black.WriteBack.YES))
                 with open(tmp_file, "rb") as f:
                     actual = f.read().decode("utf-8")
             finally:
                 os.unlink(tmp_file)
             self.assertFormatEqual(expected, actual)
 
-    def test_experimental_string_processing_warns(self) -> None:
-        self.assertWarns(
-            black.mode.Deprecated, black.Mode, experimental_string_processing=True
-        )
-
     def test_piping(self) -> None:
         _, source, expected = read_data_from_file(
             PROJECT_ROOT / "src/black/__init__.py"
@@ -252,21 +243,6 @@ def test_piping_diff_with_color(self) -> None:
         self.assertIn("\033[31m", actual)
         self.assertIn("\033[0m", actual)
 
-    @patch("black.dump_to_file", dump_to_stderr)
-    def _test_wip(self) -> None:
-        source, expected = read_data("miscellaneous", "wip")
-        sys.settrace(tracefunc)
-        mode = replace(
-            DEFAULT_MODE,
-            experimental_string_processing=False,
-            target_versions={black.TargetVersion.PY38},
-        )
-        actual = fs(source, mode=mode)
-        sys.settrace(None)
-        self.assertFormatEqual(expected, actual)
-        black.assert_equivalent(source, actual)
-        black.assert_stable(source, actual, black.FileMode())
-
     def test_pep_572_version_detection(self) -> None:
         source, _ = read_data("cases", "pep_572")
         root = black.lib2to3_parse(source)
@@ -374,7 +350,7 @@ def test_detect_debug_f_strings(self) -> None:
     @patch("black.dump_to_file", dump_to_stderr)
     def test_string_quotes(self) -> None:
         source, expected = read_data("miscellaneous", "string_quotes")
-        mode = black.Mode(preview=True)
+        mode = black.Mode(unstable=True)
         assert_format(source, expected, mode)
         mode = replace(mode, string_normalization=False)
         not_normalized = fs(source, mode=mode)
@@ -1052,7 +1028,6 @@ def test_format_file_contents(self) -> None:
             black.format_file_contents(invalid, mode=mode, fast=False)
         self.assertEqual(str(e.exception), "Cannot parse: 1:7: return if you can")
 
-        mode = black.Mode(preview=True)
         just_crlf = "\r\n"
         with self.assertRaises(black.NothingChanged):
             black.format_file_contents(just_crlf, mode=mode, fast=False)
@@ -1396,7 +1371,6 @@ def get_output(*args: Any, **kwargs: Any) -> io.TextIOWrapper:
 
             return get_output
 
-        mode = black.Mode(preview=True)
         for content, expected in cases:
             output = io.StringIO()
             io_TextIOWrapper = io.TextIOWrapper
@@ -1407,26 +1381,27 @@ def get_output(*args: Any, **kwargs: Any) -> io.TextIOWrapper:
                         fast=True,
                         content=content,
                         write_back=black.WriteBack.YES,
-                        mode=mode,
+                        mode=DEFAULT_MODE,
                     )
                 except io.UnsupportedOperation:
                     pass  # StringIO does not support detach
                 assert output.getvalue() == expected
 
-        # An empty string is the only test case for `preview=False`
-        output = io.StringIO()
-        io_TextIOWrapper = io.TextIOWrapper
-        with patch("io.TextIOWrapper", _new_wrapper(output, io_TextIOWrapper)):
-            try:
-                black.format_stdin_to_stdout(
-                    fast=True,
-                    content="",
-                    write_back=black.WriteBack.YES,
-                    mode=DEFAULT_MODE,
-                )
-            except io.UnsupportedOperation:
-                pass  # StringIO does not support detach
-            assert output.getvalue() == ""
+    def test_cli_unstable(self) -> None:
+        self.invokeBlack(["--unstable", "-c", "0"], exit_code=0)
+        self.invokeBlack(["--preview", "-c", "0"], exit_code=0)
+        # Must also pass --preview
+        self.invokeBlack(
+            ["--enable-unstable-feature", "string_processing", "-c", "0"], exit_code=1
+        )
+        self.invokeBlack(
+            ["--preview", "--enable-unstable-feature", "string_processing", "-c", "0"],
+            exit_code=0,
+        )
+        self.invokeBlack(
+            ["--unstable", "--enable-unstable-feature", "string_processing", "-c", "0"],
+            exit_code=0,
+        )
 
     def test_invalid_cli_regex(self) -> None:
         for option in ["--include", "--exclude", "--extend-exclude", "--force-exclude"]:
diff --git a/tests/util.py b/tests/util.py
index 9ea30e62fe3..d5425f1f743 100644
--- a/tests/util.py
+++ b/tests/util.py
@@ -112,16 +112,24 @@ def assert_format(
     # For both preview and non-preview tests, ensure that Black doesn't crash on
     # this code, but don't pass "expected" because the precise output may differ.
     try:
+        if mode.unstable:
+            new_mode = replace(mode, unstable=False, preview=False)
+        else:
+            new_mode = replace(mode, preview=not mode.preview)
         _assert_format_inner(
             source,
             None,
-            replace(mode, preview=not mode.preview),
+            new_mode,
             fast=fast,
             minimum_version=minimum_version,
             lines=lines,
         )
     except Exception as e:
-        text = "non-preview" if mode.preview else "preview"
+        text = (
+            "unstable"
+            if mode.unstable
+            else "non-preview" if mode.preview else "preview"
+        )
         raise FormatFailure(
             f"Black crashed formatting this case in {text} mode."
         ) from e
@@ -138,7 +146,7 @@ def assert_format(
             _assert_format_inner(
                 source,
                 None,
-                replace(mode, preview=preview_mode, line_length=1),
+                replace(mode, preview=preview_mode, line_length=1, unstable=False),
                 fast=fast,
                 minimum_version=minimum_version,
                 lines=lines,
@@ -241,6 +249,7 @@ def get_flags_parser() -> argparse.ArgumentParser:
         "--skip-magic-trailing-comma", default=False, action="store_true"
     )
     parser.add_argument("--preview", default=False, action="store_true")
+    parser.add_argument("--unstable", default=False, action="store_true")
     parser.add_argument("--fast", default=False, action="store_true")
     parser.add_argument(
         "--minimum-version",
@@ -278,6 +287,7 @@ def parse_mode(flags_line: str) -> TestCaseArgs:
         is_ipynb=args.ipynb,
         magic_trailing_comma=not args.skip_magic_trailing_comma,
         preview=args.preview,
+        unstable=args.unstable,
     )
     if args.line_ranges:
         lines = parse_line_ranges(args.line_ranges)

From 0e6e46b9eb45f5a22062fe84c2c2ff46bd0d738e Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Thu, 25 Jan 2024 20:35:21 -0800
Subject: [PATCH 0993/1034] Prepare release 24.1.0 (#4170)

---
 CHANGES.md                                  | 46 +++------------------
 docs/integrations/source_version_control.md |  4 +-
 docs/usage_and_configuration/the_basics.md  |  6 +--
 scripts/release.py                          |  4 +-
 4 files changed, 13 insertions(+), 47 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 0496603e2c0..ff921de69eb 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,11 +1,9 @@
 # Change Log
 
-## Unreleased
+## 24.1.0
 
 ### Highlights
 
-<!-- Include any especially major or disruptive changes here -->
-
 This release introduces the new 2024 stable style (#4106), stabilizing the following
 changes:
 
@@ -44,8 +42,6 @@ year's stable style.
 
 ### Stable style
 
-<!-- Changes that affect Black's stable style -->
-
 Several bug fixes were made in features that are moved to the stable style in this
 release:
 
@@ -59,14 +55,12 @@ release:
 
 ### Preview style
 
-<!-- Changes that affect Black's preview style -->
-
 - Add `--unstable` style, covering preview features that have known problems that would
   block them from going into the stable style. Also add the `--enable-unstable-feature`
   flag; for example, use
   `--enable-unstable-feature hug_parens_with_braces_and_square_brackets` to apply this
-  preview style throughout 2024, even if a later Black release downgrades the feature to
-  unstable (#4096)
+  preview feature throughout 2024, even if a later Black release downgrades the feature
+  to unstable (#4096)
 - Format module docstrings the same as class and function docstrings (#4095)
 - Fix crash when using a walrus in a dictionary (#4155)
 - Fix unnecessary parentheses when wrapping long dicts (#4135)
@@ -74,48 +68,18 @@ release:
 
 ### Configuration
 
-<!-- Changes to how Black can be configured -->
-
-- Print warning when toml config contains an invalid key (#4165)
-- Fix symlink handling, properly catch and ignore symlinks that point outside of root
-  (#4161)
+- Print warning when configuration in `pyproject.toml` contains an invalid key (#4165)
+- Fix symlink handling, properly ignoring symlinks that point outside of root (#4161)
 - Fix cache mtime logic that resulted in false positive cache hits (#4128)
 - Remove the long-deprecated `--experimental-string-processing` flag. This feature can
   currently be enabled with `--preview --enable-unstable-feature string_processing`.
   (#4096)
 
-### Packaging
-
-<!-- Changes to how Black is packaged, such as dependency requirements -->
-
-### Parser
-
-<!-- Changes to the parser or to version autodetection -->
-
-### Performance
-
-<!-- Changes that improve Black's performance. -->
-
-### Output
-
-<!-- Changes to Black's terminal output and error messages -->
-
-### _Blackd_
-
-<!-- Changes to blackd -->
-
 ### Integrations
 
-<!-- For example, Docker, GitHub Actions, pre-commit, editors -->
-
 - Revert the change to run Black's pre-commit integration only on specific git hooks
   (#3940) for better compatibility with older versions of pre-commit (#4137)
 
-### Documentation
-
-<!-- Major changes to documentation and policies. Small docs changes
-     don't need a changelog entry. -->
-
 ## 23.12.1
 
 ### Packaging
diff --git a/docs/integrations/source_version_control.md b/docs/integrations/source_version_control.md
index 3b895193941..259c1c1eaf3 100644
--- a/docs/integrations/source_version_control.md
+++ b/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.12.1
+    rev: 24.1.0
     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.12.1
+    rev: 24.1.0
     hooks:
       - id: black-jupyter
         # It is recommended to specify the latest version of Python
diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index a42e093155b..562fd7d5905 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -266,8 +266,8 @@ configuration file for consistent results across environments.
 
 ```console
 $ black --version
-black, 23.12.1 (compiled: yes)
-$ black --required-version 23.12.1 -c "format = 'this'"
+black, 24.1.0 (compiled: yes)
+$ black --required-version 24.1.0 -c "format = 'this'"
 format = "this"
 $ black --required-version 31.5b2 -c "still = 'beta?!'"
 Oh no! 💥 💔 💥 The required version does not match the running version!
@@ -363,7 +363,7 @@ You can check the version of _Black_ you have installed using the `--version` fl
 
 ```console
 $ black --version
-black, 23.12.1
+black, 24.1.0
 ```
 
 #### `--config`
diff --git a/scripts/release.py b/scripts/release.py
index d588429c2d3..c5336506396 100755
--- a/scripts/release.py
+++ b/scripts/release.py
@@ -169,7 +169,9 @@ def get_next_version(self) -> str:
         calver_parts = base_calver.split(".")
         base_calver = f"{calver_parts[0]}.{int(calver_parts[1])}"  # Remove leading 0
         git_tags = get_git_tags()
-        same_month_releases = [t for t in git_tags if t.startswith(base_calver)]
+        same_month_releases = [
+            t for t in git_tags if t.startswith(base_calver) and "a" not in t
+        ]
         if len(same_month_releases) < 1:
             return f"{base_calver}.0"
         same_month_version = same_month_releases[-1].split(".", 2)[-1]

From 659c29a41c7c686687aef21f57b95bcfa236b03b Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Thu, 25 Jan 2024 21:12:38 -0800
Subject: [PATCH 0994/1034] New changelog

---
 CHANGES.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/CHANGES.md b/CHANGES.md
index ff921de69eb..9a9be4bbeae 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,5 +1,52 @@
 # Change Log
 
+## Unreleased
+
+### Highlights
+
+<!-- Include any especially major or disruptive changes here -->
+
+### Stable style
+
+<!-- Changes that affect Black's stable style -->
+
+### Preview style
+
+<!-- Changes that affect Black's preview style -->
+
+### Configuration
+
+<!-- Changes to how Black can be configured -->
+
+### Packaging
+
+<!-- Changes to how Black is packaged, such as dependency requirements -->
+
+### Parser
+
+<!-- Changes to the parser or to version autodetection -->
+
+### Performance
+
+<!-- Changes that improve Black's performance. -->
+
+### Output
+
+<!-- Changes to Black's terminal output and error messages -->
+
+### _Blackd_
+
+<!-- Changes to blackd -->
+
+### Integrations
+
+<!-- For example, Docker, GitHub Actions, pre-commit, editors -->
+
+### Documentation
+
+<!-- Major changes to documentation and policies. Small docs changes
+     don't need a changelog entry. -->
+
 ## 24.1.0
 
 ### Highlights

From ed770ba4dd50c419148a0fca2b43937a7447e1f9 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Fri, 26 Jan 2024 11:54:49 -0800
Subject: [PATCH 0995/1034] Fix cache file length (#4176)

- Ensure total file length stays under 96
- Hash the path only if it's too long
- Proceed normally (with a warning) if the cache can't be read

Fixes #4172
---
 CHANGES.md          |  3 +++
 src/black/cache.py  |  9 ++++++++-
 src/black/mode.py   | 21 +++++++++++++++++----
 tests/test_black.py | 25 +++++++++++++++++++++++++
 4 files changed, 53 insertions(+), 5 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 9a9be4bbeae..e4240eacfca 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -18,6 +18,9 @@
 
 <!-- Changes to how Black can be configured -->
 
+- Shorten the length of the name of the cache file to fix crashes on file systems that
+  do not support long paths (#4176)
+
 ### Packaging
 
 <!-- Changes to how Black is packaged, such as dependency requirements -->
diff --git a/src/black/cache.py b/src/black/cache.py
index cfdbc21e92a..35bddb573d2 100644
--- a/src/black/cache.py
+++ b/src/black/cache.py
@@ -13,6 +13,7 @@
 
 from _black_version import version as __version__
 from black.mode import Mode
+from black.output import err
 
 if sys.version_info >= (3, 11):
     from typing import Self
@@ -64,7 +65,13 @@ def read(cls, mode: Mode) -> Self:
         resolve the issue.
         """
         cache_file = get_cache_file(mode)
-        if not cache_file.exists():
+        try:
+            exists = cache_file.exists()
+        except OSError as e:
+            # Likely file too long; see #4172 and #4174
+            err(f"Unable to read cache file {cache_file} due to {e}")
+            return cls(mode, cache_file)
+        if not exists:
             return cls(mode, cache_file)
 
         with cache_file.open("rb") as fobj:
diff --git a/src/black/mode.py b/src/black/mode.py
index 68919fb4901..128d2b9f108 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -192,6 +192,9 @@ class Deprecated(UserWarning):
     """Visible deprecation warning."""
 
 
+_MAX_CACHE_KEY_PART_LENGTH: Final = 32
+
+
 @dataclass
 class Mode:
     target_versions: Set[TargetVersion] = field(default_factory=set)
@@ -228,6 +231,19 @@ def get_cache_key(self) -> str:
             )
         else:
             version_str = "-"
+        if len(version_str) > _MAX_CACHE_KEY_PART_LENGTH:
+            version_str = sha256(version_str.encode()).hexdigest()[
+                :_MAX_CACHE_KEY_PART_LENGTH
+            ]
+        features_and_magics = (
+            ",".join(sorted(f.name for f in self.enabled_features))
+            + "@"
+            + ",".join(sorted(self.python_cell_magics))
+        )
+        if len(features_and_magics) > _MAX_CACHE_KEY_PART_LENGTH:
+            features_and_magics = sha256(features_and_magics.encode()).hexdigest()[
+                :_MAX_CACHE_KEY_PART_LENGTH
+            ]
         parts = [
             version_str,
             str(self.line_length),
@@ -236,10 +252,7 @@ def get_cache_key(self) -> str:
             str(int(self.is_ipynb)),
             str(int(self.skip_source_first_line)),
             str(int(self.magic_trailing_comma)),
-            sha256(
-                (",".join(sorted(f.name for f in self.enabled_features))).encode()
-            ).hexdigest(),
             str(int(self.preview)),
-            sha256((",".join(sorted(self.python_cell_magics))).encode()).hexdigest(),
+            features_and_magics,
         ]
         return ".".join(parts)
diff --git a/tests/test_black.py b/tests/test_black.py
index 6dbe25a90b6..123ea0bb88a 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -44,6 +44,7 @@
 from black import re_compile_maybe_verbose as compile_pattern
 from black.cache import FileData, get_cache_dir, get_cache_file
 from black.debug import DebugVisitor
+from black.mode import Mode, Preview
 from black.output import color_diff, diff
 from black.report import Report
 
@@ -2065,6 +2066,30 @@ def test_get_cache_dir(
         monkeypatch.setenv("BLACK_CACHE_DIR", str(workspace2))
         assert get_cache_dir().parent == workspace2
 
+    def test_cache_file_length(self) -> None:
+        cases = [
+            DEFAULT_MODE,
+            # all of the target versions
+            Mode(target_versions=set(TargetVersion)),
+            # all of the features
+            Mode(enabled_features=set(Preview)),
+            # all of the magics
+            Mode(python_cell_magics={f"magic{i}" for i in range(500)}),
+            # all of the things
+            Mode(
+                target_versions=set(TargetVersion),
+                enabled_features=set(Preview),
+                python_cell_magics={f"magic{i}" for i in range(500)},
+            ),
+        ]
+        for case in cases:
+            cache_file = get_cache_file(case)
+            # Some common file systems enforce a maximum path length
+            # of 143 (issue #4174). We can't do anything if the directory
+            # path is too long, but ensure the name of the cache file itself
+            # doesn't get too crazy.
+            assert len(cache_file.name) <= 96
+
     def test_cache_broken_file(self) -> None:
         mode = DEFAULT_MODE
         with cache_dir() as workspace:

From 1607e9ab20ad550cf940482d0d361ca31fc03189 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Sat, 27 Jan 2024 12:34:02 -0800
Subject: [PATCH 0996/1034] Fix missing space in option description (#4182)

---
 src/black/__init__.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index ebc7ac8eda5..8ab5b47f974 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -279,7 +279,7 @@ def validate_regex(
     is_flag=True,
     help=(
         "Format all input files like Jupyter Notebooks regardless of file extension."
-        "This is useful when piping source on standard input."
+        " This is useful when piping source on standard input."
     ),
 )
 @click.option(

From 8bf04549ffd276a1bad6eb110e66e6557ee630d9 Mon Sep 17 00:00:00 2001
From: cobalt <61329810+RedGuy12@users.noreply.github.com>
Date: Sat, 27 Jan 2024 15:55:22 -0600
Subject: [PATCH 0997/1034] Consistently add trailing comma on typed parameters
 (#4164)

Signed-off-by: RedGuy12 <61329810+RedGuy12@users.noreply.github.com>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 CHANGES.md                                    |  2 ++
 docs/the_black_code_style/future_style.md     |  2 ++
 src/black/files.py                            |  2 +-
 src/black/linegen.py                          | 10 +++++++-
 src/black/mode.py                             |  1 +
 src/blib2to3/pgen2/parse.py                   |  2 +-
 .../data/cases/typed_params_trailing_comma.py | 24 +++++++++++++++++++
 7 files changed, 40 insertions(+), 3 deletions(-)
 create mode 100644 tests/data/cases/typed_params_trailing_comma.py

diff --git a/CHANGES.md b/CHANGES.md
index e4240eacfca..6278aed77d8 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -14,6 +14,8 @@
 
 <!-- Changes that affect Black's preview style -->
 
+- Consistently add trailing comma on typed parameters (#4164)
+
 ### Configuration
 
 <!-- Changes to how Black can be configured -->
diff --git a/docs/the_black_code_style/future_style.md b/docs/the_black_code_style/future_style.md
index 1cdd25fdb7c..d5faae36911 100644
--- a/docs/the_black_code_style/future_style.md
+++ b/docs/the_black_code_style/future_style.md
@@ -26,6 +26,8 @@ Currently, the following features are included in the preview style:
   brackets ([see below](labels/hug-parens))
 - `no_normalize_fmt_skip_whitespace`: whitespace before `# fmt: skip` comments is no
   longer normalized
+- `typed_params_trailing_comma`: consistently add trailing commas to typed function
+  parameters
 
 (labels/unstable-features)=
 
diff --git a/src/black/files.py b/src/black/files.py
index 65951efdbe8..1eb8745572b 100644
--- a/src/black/files.py
+++ b/src/black/files.py
@@ -131,7 +131,7 @@ def parse_pyproject_toml(path_config: str) -> Dict[str, Any]:
 
 
 def infer_target_version(
-    pyproject_toml: Dict[str, Any]
+    pyproject_toml: Dict[str, Any],
 ) -> Optional[List[TargetVersion]]:
     """Infer Black's target version from the project metadata in pyproject.toml.
 
diff --git a/src/black/linegen.py b/src/black/linegen.py
index a276805f2fe..c74ff9c0b4b 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -48,6 +48,7 @@
     is_one_sequence_between,
     is_one_tuple,
     is_parent_function_or_class,
+    is_part_of_annotation,
     is_rpar_token,
     is_stub_body,
     is_stub_suite,
@@ -1041,7 +1042,14 @@ def bracket_split_build_line(
             no_commas = (
                 original.is_def
                 and opening_bracket.value == "("
-                and not any(leaf.type == token.COMMA for leaf in leaves)
+                and not any(
+                    leaf.type == token.COMMA
+                    and (
+                        Preview.typed_params_trailing_comma not in original.mode
+                        or not is_part_of_annotation(leaf)
+                    )
+                    for leaf in leaves
+                )
                 # In particular, don't add one within a parenthesized return annotation.
                 # Unfortunately the indicator we're in a return annotation (RARROW) may
                 # be defined directly in the parent node, the parent of the parent ...
diff --git a/src/black/mode.py b/src/black/mode.py
index 128d2b9f108..22352e7c6a8 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -176,6 +176,7 @@ class Preview(Enum):
     no_normalize_fmt_skip_whitespace = auto()
     wrap_long_dict_values_in_parens = auto()
     multiline_string_handling = auto()
+    typed_params_trailing_comma = auto()
 
 
 UNSTABLE_FEATURES: Set[Preview] = {
diff --git a/src/blib2to3/pgen2/parse.py b/src/blib2to3/pgen2/parse.py
index ad51a3dad08..ad1d795b51a 100644
--- a/src/blib2to3/pgen2/parse.py
+++ b/src/blib2to3/pgen2/parse.py
@@ -50,7 +50,7 @@ def lam_sub(grammar: Grammar, node: RawNode) -> NL:
 
 
 def stack_copy(
-    stack: List[Tuple[DFAS, int, RawNode]]
+    stack: List[Tuple[DFAS, int, RawNode]],
 ) -> List[Tuple[DFAS, int, RawNode]]:
     """Nodeless stack copy."""
     return [(dfa, label, DUMMY_NODE) for dfa, label, _ in stack]
diff --git a/tests/data/cases/typed_params_trailing_comma.py b/tests/data/cases/typed_params_trailing_comma.py
new file mode 100644
index 00000000000..a53b908b18b
--- /dev/null
+++ b/tests/data/cases/typed_params_trailing_comma.py
@@ -0,0 +1,24 @@
+# flags: --preview
+def long_function_name_goes_here(
+    x: Callable[List[int]]
+) -> Union[List[int], float, str, bytes, Tuple[int]]:
+    pass
+
+
+def long_function_name_goes_here(
+    x: Callable[[str, Any], int]
+) -> Union[List[int], float, str, bytes, Tuple[int]]:
+    pass
+
+
+# output
+def long_function_name_goes_here(
+    x: Callable[List[int]],
+) -> Union[List[int], float, str, bytes, Tuple[int]]:
+    pass
+
+
+def long_function_name_goes_here(
+    x: Callable[[str, Any], int],
+) -> Union[List[int], float, str, bytes, Tuple[int]]:
+    pass

From 79fc1158a98281dac798feb14b8fddb4051e4a42 Mon Sep 17 00:00:00 2001
From: Henry Schreiner <HenrySchreinerIII@gmail.com>
Date: Sat, 27 Jan 2024 23:24:36 -0500
Subject: [PATCH 0998/1034] chore: ignore node_modules (produced by a
 pre-commit check) (#4184)

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>
---
 .gitignore | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.gitignore b/.gitignore
index 4a4f1b738ad..6e23797d110 100644
--- a/.gitignore
+++ b/.gitignore
@@ -25,3 +25,4 @@ src/_black_version.py
 .hypothesis/
 venv/
 .ipynb_checkpoints/
+node_modules/

From e026c93888f91a47a9c9f4e029f3eb07d96375e6 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Sat, 27 Jan 2024 20:51:32 -0800
Subject: [PATCH 0999/1034] Prepare release 24.1.1 (#4186)

---
 CHANGES.md                                  | 44 ++-------------------
 docs/integrations/source_version_control.md |  4 +-
 docs/usage_and_configuration/the_basics.md  |  6 +--
 3 files changed, 8 insertions(+), 46 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 6278aed77d8..a794f421694 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,57 +1,19 @@
 # Change Log
 
-## Unreleased
+## 24.1.1
 
-### Highlights
-
-<!-- Include any especially major or disruptive changes here -->
-
-### Stable style
-
-<!-- Changes that affect Black's stable style -->
+Bugfix release to fix a bug that made Black unusable on certain file systems with strict
+limits on path length.
 
 ### Preview style
 
-<!-- Changes that affect Black's preview style -->
-
 - Consistently add trailing comma on typed parameters (#4164)
 
 ### Configuration
 
-<!-- Changes to how Black can be configured -->
-
 - Shorten the length of the name of the cache file to fix crashes on file systems that
   do not support long paths (#4176)
 
-### Packaging
-
-<!-- Changes to how Black is packaged, such as dependency requirements -->
-
-### Parser
-
-<!-- Changes to the parser or to version autodetection -->
-
-### Performance
-
-<!-- Changes that improve Black's performance. -->
-
-### Output
-
-<!-- Changes to Black's terminal output and error messages -->
-
-### _Blackd_
-
-<!-- Changes to blackd -->
-
-### Integrations
-
-<!-- For example, Docker, GitHub Actions, pre-commit, editors -->
-
-### Documentation
-
-<!-- Major changes to documentation and policies. Small docs changes
-     don't need a changelog entry. -->
-
 ## 24.1.0
 
 ### Highlights
diff --git a/docs/integrations/source_version_control.md b/docs/integrations/source_version_control.md
index 259c1c1eaf3..92279707d84 100644
--- a/docs/integrations/source_version_control.md
+++ b/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.1.0
+    rev: 24.1.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: 24.1.0
+    rev: 24.1.1
     hooks:
       - id: black-jupyter
         # It is recommended to specify the latest version of Python
diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index 562fd7d5905..dc9d9a64c68 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -266,8 +266,8 @@ configuration file for consistent results across environments.
 
 ```console
 $ black --version
-black, 24.1.0 (compiled: yes)
-$ black --required-version 24.1.0 -c "format = 'this'"
+black, 24.1.1 (compiled: yes)
+$ black --required-version 24.1.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!
@@ -363,7 +363,7 @@ You can check the version of _Black_ you have installed using the `--version` fl
 
 ```console
 $ black --version
-black, 24.1.0
+black, 24.1.1
 ```
 
 #### `--config`

From 0b4364b7e38356428565fceb706a76ebf9a373e5 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Sun, 28 Jan 2024 05:37:12 -0800
Subject: [PATCH 1000/1034] Add new release template

---
 CHANGES.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/CHANGES.md b/CHANGES.md
index a794f421694..5ee1394282e 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,5 +1,52 @@
 # Change Log
 
+## Unreleased
+
+### Highlights
+
+<!-- Include any especially major or disruptive changes here -->
+
+### Stable style
+
+<!-- Changes that affect Black's stable style -->
+
+### Preview style
+
+<!-- Changes that affect Black's preview style -->
+
+### Configuration
+
+<!-- Changes to how Black can be configured -->
+
+### Packaging
+
+<!-- Changes to how Black is packaged, such as dependency requirements -->
+
+### Parser
+
+<!-- Changes to the parser or to version autodetection -->
+
+### Performance
+
+<!-- Changes that improve Black's performance. -->
+
+### Output
+
+<!-- Changes to Black's terminal output and error messages -->
+
+### _Blackd_
+
+<!-- Changes to blackd -->
+
+### Integrations
+
+<!-- For example, Docker, GitHub Actions, pre-commit, editors -->
+
+### Documentation
+
+<!-- Major changes to documentation and policies. Small docs changes
+     don't need a changelog entry. -->
+
 ## 24.1.1
 
 Bugfix release to fix a bug that made Black unusable on certain file systems with strict

From d919746fae2ba47442fc33699a5569fa04db305d Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Sun, 28 Jan 2024 07:05:56 -0800
Subject: [PATCH 1001/1034] Swallow warnings when performing AST checks (#4189)

Fixes #4188
---
 CHANGES.md           |  3 +++
 src/black/parsing.py | 16 ++++++++++------
 2 files changed, 13 insertions(+), 6 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 5ee1394282e..6da30afc707 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -34,6 +34,9 @@
 
 <!-- Changes to Black's terminal output and error messages -->
 
+- Black will swallow any `SyntaxWarning`s or `DeprecationWarning`s produced by the `ast`
+  module when performing equivalence checks (#4189)
+
 ### _Blackd_
 
 <!-- Changes to blackd -->
diff --git a/src/black/parsing.py b/src/black/parsing.py
index 178a7ef10e2..63c5e71a0fe 100644
--- a/src/black/parsing.py
+++ b/src/black/parsing.py
@@ -4,6 +4,7 @@
 
 import ast
 import sys
+import warnings
 from typing import Iterable, Iterator, List, Set, Tuple
 
 from black.mode import VERSION_TO_FEATURES, Feature, TargetVersion, supports_feature
@@ -109,13 +110,16 @@ def lib2to3_unparse(node: Node) -> str:
     return code
 
 
-def parse_single_version(
+def _parse_single_version(
     src: str, version: Tuple[int, int], *, type_comments: bool
 ) -> ast.AST:
     filename = "<unknown>"
-    return ast.parse(
-        src, filename, feature_version=version, type_comments=type_comments
-    )
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", SyntaxWarning)
+        warnings.simplefilter("ignore", DeprecationWarning)
+        return ast.parse(
+            src, filename, feature_version=version, type_comments=type_comments
+        )
 
 
 def parse_ast(src: str) -> ast.AST:
@@ -125,7 +129,7 @@ def parse_ast(src: str) -> ast.AST:
     first_error = ""
     for version in sorted(versions, reverse=True):
         try:
-            return parse_single_version(src, version, type_comments=True)
+            return _parse_single_version(src, version, type_comments=True)
         except SyntaxError as e:
             if not first_error:
                 first_error = str(e)
@@ -133,7 +137,7 @@ def parse_ast(src: str) -> ast.AST:
     # Try to parse without type comments
     for version in sorted(versions, reverse=True):
         try:
-            return parse_single_version(src, version, type_comments=False)
+            return _parse_single_version(src, version, type_comments=False)
         except SyntaxError:
             pass
 

From 177e306363b9da5fcef621d15c205453ad1cfc74 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Sun, 28 Jan 2024 23:07:34 -0800
Subject: [PATCH 1002/1034] Bump pypa/cibuildwheel from 2.16.2 to 2.16.4
 (#4191)

Bumps [pypa/cibuildwheel](https://github.com/pypa/cibuildwheel) from 2.16.2 to 2.16.4.
- [Release notes](https://github.com/pypa/cibuildwheel/releases)
- [Changelog](https://github.com/pypa/cibuildwheel/blob/main/docs/changelog.md)
- [Commits](https://github.com/pypa/cibuildwheel/compare/v2.16.2...v2.16.4)
---
 .github/workflows/pypi_upload.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/pypi_upload.yml b/.github/workflows/pypi_upload.yml
index 8e3eb67a10d..52525419f0a 100644
--- a/.github/workflows/pypi_upload.yml
+++ b/.github/workflows/pypi_upload.yml
@@ -89,7 +89,7 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
-      - uses: pypa/cibuildwheel@v2.16.2
+      - uses: pypa/cibuildwheel@v2.16.4
         with:
           only: ${{ matrix.only }}
 

From 2bc5ce8ae1f1ad52909b4656444c1e9988e23cab Mon Sep 17 00:00:00 2001
From: Henry Schreiner <HenrySchreinerIII@gmail.com>
Date: Mon, 29 Jan 2024 10:56:48 -0500
Subject: [PATCH 1003/1034] feat: add schema and validate-pyproject support
 (#4181)

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 .github/workflows/lint.yml            |   5 +
 .github/workflows/test.yml            |   2 +-
 .pre-commit-config.yaml               |  11 +-
 CHANGES.md                            |   2 +
 pyproject.toml                        |   3 +
 scripts/generate_schema.py            |  74 +++++++++++++
 src/black/resources/__init__.py       |   0
 src/black/resources/black.schema.json | 149 ++++++++++++++++++++++++++
 src/black/schema.py                   |  20 ++++
 tests/test_schema.py                  |  17 +++
 tox.ini                               |  10 +-
 11 files changed, 288 insertions(+), 5 deletions(-)
 create mode 100644 scripts/generate_schema.py
 create mode 100644 src/black/resources/__init__.py
 create mode 100644 src/black/resources/black.schema.json
 create mode 100644 src/black/schema.py
 create mode 100644 tests/test_schema.py

diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index 2d016cef7a6..8cb335bffb5 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -40,3 +40,8 @@ jobs:
       - name: Format ourselves
         run: |
           tox -e run_self
+
+      - name: Regenerate schema
+        run: |
+          tox -e generate_schema
+          git diff --exit-code
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 55359a23303..fc274208258 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -106,4 +106,4 @@ jobs:
           python -m pip install -e ".[uvloop]"
 
       - name: Format ourselves
-        run: python -m black --check .
+        run: python -m black --check src/ tests/
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 13479565527..05569eed8db 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -42,9 +42,9 @@ repos:
     rev: v1.8.0
     hooks:
       - id: mypy
-        exclude: ^docs/conf.py
-        args: ["--config-file", "pyproject.toml"]
-        additional_dependencies:
+        exclude: ^(docs/conf.py|scripts/generate_schema.py)$
+        args: []
+        additional_dependencies: &mypy_deps
           - types-PyYAML
           - tomli >= 0.2.6, < 2.0.0
           - click >= 8.1.0, != 8.1.4, != 8.1.5
@@ -56,6 +56,11 @@ repos:
           - types-commonmark
           - urllib3
           - hypothesmith
+      - id: mypy
+        name: mypy (Python 3.10)
+        files: scripts/generate_schema.py
+        args: ["--python-version=3.10"]
+        additional_dependencies: *mypy_deps
 
   - repo: https://github.com/pre-commit/mirrors-prettier
     rev: v4.0.0-alpha.8
diff --git a/CHANGES.md b/CHANGES.md
index 6da30afc707..4fd030df6df 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -45,6 +45,8 @@
 
 <!-- For example, Docker, GitHub Actions, pre-commit, editors -->
 
+- Add a JSONSchema and provide a validate-pyproject entry-point (#4181)
+
 ### Documentation
 
 <!-- Major changes to documentation and policies. Small docs changes
diff --git a/pyproject.toml b/pyproject.toml
index fa3654b8d67..143c4845a94 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -89,6 +89,9 @@ jupyter = [
 black = "black:patched_main"
 blackd = "blackd:patched_main [d]"
 
+[project.entry-points."validate_pyproject.tool_schema"]
+black = "black.schema:get_schema"
+
 [project.urls]
 Changelog = "https://github.com/psf/black/blob/main/CHANGES.md"
 Homepage = "https://github.com/psf/black"
diff --git a/scripts/generate_schema.py b/scripts/generate_schema.py
new file mode 100644
index 00000000000..f3437cc8fee
--- /dev/null
+++ b/scripts/generate_schema.py
@@ -0,0 +1,74 @@
+import json
+from typing import IO, Any
+
+import click
+
+import black
+
+
+def generate_schema_from_click(
+    cmd: click.Command,
+) -> dict[str, Any]:
+    result: dict[str, dict[str, Any]] = {}
+    for param in cmd.params:
+        if not isinstance(param, click.Option) or param.is_eager:
+            continue
+
+        assert param.name
+        name = param.name.replace("_", "-")
+
+        result[name] = {}
+
+        match param.type:
+            case click.types.IntParamType():
+                result[name]["type"] = "integer"
+            case click.types.StringParamType() | click.types.Path():
+                result[name]["type"] = "string"
+            case click.types.Choice(choices=choices):
+                result[name]["enum"] = choices
+            case click.types.BoolParamType():
+                result[name]["type"] = "boolean"
+            case _:
+                msg = f"{param.type!r} not a known type for {param}"
+                raise TypeError(msg)
+
+        if param.multiple:
+            result[name] = {"type": "array", "items": result[name]}
+
+        result[name]["description"] = param.help
+
+        if param.default is not None and not param.multiple:
+            result[name]["default"] = param.default
+
+    return result
+
+
+@click.command(context_settings={"help_option_names": ["-h", "--help"]})
+@click.option("--schemastore", is_flag=True, help="SchemaStore format")
+@click.option("--outfile", type=click.File(mode="w"), help="Write to file")
+def main(schemastore: bool, outfile: IO[str]) -> None:
+    properties = generate_schema_from_click(black.main)
+    del properties["line-ranges"]
+
+    schema: dict[str, Any] = {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "$id": (
+            "https://github.com/psf/black/blob/main/black/resources/black.schema.json"
+        ),
+        "$comment": "tool.black table in pyproject.toml",
+        "type": "object",
+        "additionalProperties": False,
+        "properties": properties,
+    }
+
+    if schemastore:
+        schema["$id"] = ("https://json.schemastore.org/partial-black.json",)
+        # The precise list of unstable features may change frequently, so don't
+        # bother putting it in SchemaStore
+        schema["properties"]["enable-unstable-feature"]["items"] = {"type": "string"}
+
+    print(json.dumps(schema, indent=2), file=outfile)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/src/black/resources/__init__.py b/src/black/resources/__init__.py
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/src/black/resources/black.schema.json b/src/black/resources/black.schema.json
new file mode 100644
index 00000000000..40bf39137f7
--- /dev/null
+++ b/src/black/resources/black.schema.json
@@ -0,0 +1,149 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/psf/black/blob/main/black/resources/black.schema.json",
+  "$comment": "tool.black table in pyproject.toml",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "code": {
+      "type": "string",
+      "description": "Format the code passed in as a string."
+    },
+    "line-length": {
+      "type": "integer",
+      "description": "How many characters per line to allow.",
+      "default": 88
+    },
+    "target-version": {
+      "type": "array",
+      "items": {
+        "enum": [
+          "py33",
+          "py34",
+          "py35",
+          "py36",
+          "py37",
+          "py38",
+          "py39",
+          "py310",
+          "py311",
+          "py312"
+        ]
+      },
+      "description": "Python versions that should be supported by Black's output. You should include all versions that your code supports. By default, Black will infer target versions from the project metadata in pyproject.toml. If this does not yield conclusive results, Black will use per-file auto-detection."
+    },
+    "pyi": {
+      "type": "boolean",
+      "description": "Format all input files like typing stubs regardless of file extension. This is useful when piping source on standard input.",
+      "default": false
+    },
+    "ipynb": {
+      "type": "boolean",
+      "description": "Format all input files like Jupyter Notebooks regardless of file extension. This is useful when piping source on standard input.",
+      "default": false
+    },
+    "python-cell-magics": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "When processing Jupyter Notebooks, add the given magic to the list of known python-magics (capture, prun, pypy, python, python3, time, timeit). Useful for formatting cells with custom python magics."
+    },
+    "skip-source-first-line": {
+      "type": "boolean",
+      "description": "Skip the first line of the source code.",
+      "default": false
+    },
+    "skip-string-normalization": {
+      "type": "boolean",
+      "description": "Don't normalize string quotes or prefixes.",
+      "default": false
+    },
+    "skip-magic-trailing-comma": {
+      "type": "boolean",
+      "description": "Don't use trailing commas as a reason to split lines.",
+      "default": false
+    },
+    "preview": {
+      "type": "boolean",
+      "description": "Enable potentially disruptive style changes that may be added to Black's main functionality in the next major release.",
+      "default": false
+    },
+    "unstable": {
+      "type": "boolean",
+      "description": "Enable potentially disruptive style changes that have known bugs or are not currently expected to make it into the stable style Black's next major release. Implies --preview.",
+      "default": false
+    },
+    "enable-unstable-feature": {
+      "type": "array",
+      "items": {
+        "enum": [
+          "hex_codes_in_unicode_sequences",
+          "string_processing",
+          "hug_parens_with_braces_and_square_brackets",
+          "unify_docstring_detection",
+          "no_normalize_fmt_skip_whitespace",
+          "wrap_long_dict_values_in_parens",
+          "multiline_string_handling",
+          "typed_params_trailing_comma"
+        ]
+      },
+      "description": "Enable specific features included in the `--unstable` style. Requires `--preview`. No compatibility guarantees are provided on the behavior or existence of any unstable features."
+    },
+    "check": {
+      "type": "boolean",
+      "description": "Don't write the files back, just return the status. Return code 0 means nothing would change. Return code 1 means some files would be reformatted. Return code 123 means there was an internal error.",
+      "default": false
+    },
+    "diff": {
+      "type": "boolean",
+      "description": "Don't write the files back, just output a diff to indicate what changes Black would've made. They are printed to stdout so capturing them is simple.",
+      "default": false
+    },
+    "color": {
+      "type": "boolean",
+      "description": "Show (or do not show) colored diff. Only applies when --diff is given.",
+      "default": false
+    },
+    "fast": {
+      "type": "boolean",
+      "description": "By default, Black performs an AST safety check after formatting your code. The --fast flag turns off this check and the --safe flag explicitly enables it. [default: --safe]",
+      "default": false
+    },
+    "required-version": {
+      "type": "string",
+      "description": "Require a specific version of Black to be running. This is useful for ensuring that all contributors to your project are using the same version, because different versions of Black may format code a little differently. This option can be set in a configuration file for consistent results across environments."
+    },
+    "exclude": {
+      "type": "string",
+      "description": "A regular expression that matches files and directories that should be excluded on recursive searches. An empty value means no paths are excluded. Use forward slashes for directories on all platforms (Windows, too). By default, Black also ignores all paths listed in .gitignore. Changing this value will override all default exclusions. [default: /(\\.direnv|\\.eggs|\\.git|\\.hg|\\.ipynb_checkpoints|\\.mypy_cache|\\.nox|\\.pytest_cache|\\.ruff_cache|\\.tox|\\.svn|\\.venv|\\.vscode|__pypackages__|_build|buck-out|build|dist|venv)/]"
+    },
+    "extend-exclude": {
+      "type": "string",
+      "description": "Like --exclude, but adds additional files and directories on top of the default values instead of overriding them."
+    },
+    "force-exclude": {
+      "type": "string",
+      "description": "Like --exclude, but files and directories matching this regex will be excluded even when they are passed explicitly as arguments. This is useful when invoking Black programmatically on changed files, such as in a pre-commit hook or editor plugin."
+    },
+    "include": {
+      "type": "string",
+      "description": "A regular expression that matches files and directories that should be included on recursive searches. An empty value means all files are included regardless of the name. Use forward slashes for directories on all platforms (Windows, too). Overrides all exclusions, including from .gitignore and command line options.",
+      "default": "(\\.pyi?|\\.ipynb)$"
+    },
+    "workers": {
+      "type": "integer",
+      "description": "When Black formats multiple files, it may use a process pool to speed up formatting. This option controls the number of parallel workers. This can also be specified via the BLACK_NUM_WORKERS environment variable. Defaults to the number of CPUs in the system."
+    },
+    "quiet": {
+      "type": "boolean",
+      "description": "Stop emitting all non-critical output. Error messages will still be emitted (which can silenced by 2>/dev/null).",
+      "default": false
+    },
+    "verbose": {
+      "type": "boolean",
+      "description": "Emit messages about files that were not changed or were ignored due to exclusion patterns. If Black is using a configuration file, a message detailing which one it is using will be emitted.",
+      "default": false
+    }
+  }
+}
diff --git a/src/black/schema.py b/src/black/schema.py
new file mode 100644
index 00000000000..78e9564cdbc
--- /dev/null
+++ b/src/black/schema.py
@@ -0,0 +1,20 @@
+import importlib.resources
+import json
+import sys
+from typing import Any
+
+
+def get_schema(tool_name: str = "black") -> Any:
+    """Get the stored complete schema for black's settings."""
+    assert tool_name == "black", "Only black is supported."
+
+    pkg = "black.resources"
+    fname = "black.schema.json"
+
+    if sys.version_info < (3, 9):
+        with importlib.resources.open_text(pkg, fname, encoding="utf-8") as f:
+            return json.load(f)
+
+    schema = importlib.resources.files(pkg).joinpath(fname)  # type: ignore[unreachable]
+    with schema.open(encoding="utf-8") as f:
+        return json.load(f)
diff --git a/tests/test_schema.py b/tests/test_schema.py
new file mode 100644
index 00000000000..1ea95130f86
--- /dev/null
+++ b/tests/test_schema.py
@@ -0,0 +1,17 @@
+import importlib.metadata
+import sys
+
+
+def test_schema_entrypoint() -> None:
+    if sys.version_info < (3, 10):
+        eps = importlib.metadata.entry_points()["validate_pyproject.tool_schema"]
+        (black_ep,) = [ep for ep in eps if ep.name == "black"]
+    else:
+        (black_ep,) = importlib.metadata.entry_points(
+            group="validate_pyproject.tool_schema", name="black"
+        )
+
+    black_fn = black_ep.load()
+    schema = black_fn()
+    assert schema == black_fn("black")
+    assert schema["properties"]["line-length"]["type"] == "integer"
diff --git a/tox.ini b/tox.ini
index 8b4175d23fe..f7357e3b8af 100644
--- a/tox.ini
+++ b/tox.ini
@@ -1,6 +1,6 @@
 [tox]
 isolated_build = true
-envlist = {,ci-}py{38,39,310,311,py3},fuzz,run_self
+envlist = {,ci-}py{38,39,310,311,py3},fuzz,run_self,generate_schema
 
 [testenv]
 setenv =
@@ -96,3 +96,11 @@ skip_install = True
 commands =
     pip install -e .
     black --check {toxinidir}/src {toxinidir}/tests
+
+[testenv:generate_schema]
+setenv = PYTHONWARNDEFAULTENCODING =
+skip_install = True
+deps =
+commands =
+    pip install -e .
+    python {toxinidir}/scripts/generate_schema.py --outfile {toxinidir}/src/black/resources/black.schema.json

From 8912a333213cd11b676d1fe0879a5abd55d393e9 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 29 Jan 2024 08:21:00 -0800
Subject: [PATCH 1004/1034] Bump peter-evans/create-or-update-comment from
 3.1.0 to 4.0.0 (#4192)

Bumps [peter-evans/create-or-update-comment](https://github.com/peter-evans/create-or-update-comment) from 3.1.0 to 4.0.0.
- [Release notes](https://github.com/peter-evans/create-or-update-comment/releases)
- [Commits](https://github.com/peter-evans/create-or-update-comment/compare/23ff15729ef2fc348714a3bb66d2f655ca9066f2...71345be0265236311c031f5c7866368bd1eff043)

---
updated-dependencies:
- dependency-name: peter-evans/create-or-update-comment
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/diff_shades_comment.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/diff_shades_comment.yml b/.github/workflows/diff_shades_comment.yml
index 9b3b4b579da..f31b2a26d79 100644
--- a/.github/workflows/diff_shades_comment.yml
+++ b/.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@23ff15729ef2fc348714a3bb66d2f655ca9066f2
+        uses: peter-evans/create-or-update-comment@71345be0265236311c031f5c7866368bd1eff043
         with:
           comment-id: ${{ steps.find-comment.outputs.comment-id }}
           issue-number: ${{ steps.metadata.outputs.pr-number }}

From d6e11ca399ff46d30279b88d71f2c0bf0036de59 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 29 Jan 2024 08:27:21 -0800
Subject: [PATCH 1005/1034] Bump peter-evans/find-comment from 2.4.0 to 3.0.0
 (#4190)

Bumps [peter-evans/find-comment](https://github.com/peter-evans/find-comment) from 2.4.0 to 3.0.0.
- [Release notes](https://github.com/peter-evans/find-comment/releases)
- [Commits](https://github.com/peter-evans/find-comment/compare/a54c31d7fa095754bfef525c0c8e5e5674c4b4b1...d5fe37641ad8451bdd80312415672ba26c86575e)

---
updated-dependencies:
- dependency-name: peter-evans/find-comment
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/diff_shades_comment.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/diff_shades_comment.yml b/.github/workflows/diff_shades_comment.yml
index f31b2a26d79..4a9c292d415 100644
--- a/.github/workflows/diff_shades_comment.yml
+++ b/.github/workflows/diff_shades_comment.yml
@@ -33,7 +33,7 @@ jobs:
       - name: Try to find pre-existing PR comment
         if: steps.metadata.outputs.needs-comment == 'true'
         id: find-comment
-        uses: peter-evans/find-comment@a54c31d7fa095754bfef525c0c8e5e5674c4b4b1
+        uses: peter-evans/find-comment@d5fe37641ad8451bdd80312415672ba26c86575e
         with:
           issue-number: ${{ steps.metadata.outputs.pr-number }}
           comment-author: "github-actions[bot]"

From cca3c0fd9f7f1097b93f0f14c08b1b8cd0103929 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Tue, 30 Jan 2024 22:22:38 -0800
Subject: [PATCH 1006/1034] Test that preview/unstable features are documented
 (#4187)

In #4096 I added a list of current preview/unstable features to the docs. I think
this is important for publicizing what's in our preview style. This PR adds an
automated test to ensure the list stays up to date in the future.
---
 docs/the_black_code_style/future_style.md |  2 +
 tests/test_docs.py                        | 74 +++++++++++++++++++++++
 2 files changed, 76 insertions(+)
 create mode 100644 tests/test_docs.py

diff --git a/docs/the_black_code_style/future_style.md b/docs/the_black_code_style/future_style.md
index d5faae36911..1c11186f811 100644
--- a/docs/the_black_code_style/future_style.md
+++ b/docs/the_black_code_style/future_style.md
@@ -16,6 +16,8 @@ feature, it is demoted to the `--unstable` style. To avoid thrash when a feature
 demoted from the `--preview` to the `--unstable` style, users can use the
 `--enable-unstable-feature` flag to enable specific unstable features.
 
+(labels/preview-features)=
+
 Currently, the following features are included in the preview style:
 
 - `hex_codes_in_unicode_sequences`: normalize casing of Unicode escape characters in
diff --git a/tests/test_docs.py b/tests/test_docs.py
new file mode 100644
index 00000000000..8050e0f73c6
--- /dev/null
+++ b/tests/test_docs.py
@@ -0,0 +1,74 @@
+"""
+
+Test that the docs are up to date.
+
+"""
+
+import re
+from itertools import islice
+from pathlib import Path
+from typing import Optional, Sequence, Set
+
+import pytest
+
+from black.mode import UNSTABLE_FEATURES, Preview
+
+DOCS_PATH = Path("docs/the_black_code_style/future_style.md")
+
+
+def check_feature_list(
+    lines: Sequence[str], expected_feature_names: Set[str], label: str
+) -> Optional[str]:
+    start_index = lines.index(f"(labels/{label}-features)=\n")
+    if start_index == -1:
+        return (
+            f"Could not find the {label} features list in {DOCS_PATH}. Ensure the"
+            " preview-features label is present."
+        )
+    num_blank_lines_seen = 0
+    seen_preview_feature_names = set()
+    for line in islice(lines, start_index + 1, None):
+        if not line.strip():
+            num_blank_lines_seen += 1
+            if num_blank_lines_seen == 3:
+                break
+            continue
+        if line.startswith("- "):
+            match = re.search(r"^- `([a-z\d_]+)`", line)
+            if match:
+                seen_preview_feature_names.add(match.group(1))
+
+    if seen_preview_feature_names - expected_feature_names:
+        extra = ", ".join(sorted(seen_preview_feature_names - expected_feature_names))
+        return (
+            f"The following features should not be in the list of {label} features:"
+            f" {extra}. Please remove them from the {label}-features label in"
+            f" {DOCS_PATH}"
+        )
+    elif expected_feature_names - seen_preview_feature_names:
+        missing = ", ".join(sorted(expected_feature_names - seen_preview_feature_names))
+        return (
+            f"The following features are missing from the list of {label} features:"
+            f" {missing}. Please document them under the {label}-features label in"
+            f" {DOCS_PATH}"
+        )
+    else:
+        return None
+
+
+def test_feature_lists_are_up_to_date() -> None:
+    repo_root = Path(__file__).parent.parent
+    if not (repo_root / "docs").exists():
+        pytest.skip("docs not found")
+    with (repo_root / DOCS_PATH).open(encoding="utf-8") as f:
+        future_style = f.readlines()
+    preview_error = check_feature_list(
+        future_style,
+        {feature.name for feature in set(Preview) - UNSTABLE_FEATURES},
+        "preview",
+    )
+    assert preview_error is None, preview_error
+    unstable_error = check_feature_list(
+        future_style, {feature.name for feature in UNSTABLE_FEATURES}, "unstable"
+    )
+    assert unstable_error is None, unstable_error

From 24c9c01e910eb566223961b00d3e2c3602c99a23 Mon Sep 17 00:00:00 2001
From: Henry Schreiner <HenrySchreinerIII@gmail.com>
Date: Thu, 1 Feb 2024 12:25:38 -0500
Subject: [PATCH 1007/1034] fix: minor issue with schemastore part of script
 (#4195)

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>
---
 scripts/generate_schema.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
 mode change 100644 => 100755 scripts/generate_schema.py

diff --git a/scripts/generate_schema.py b/scripts/generate_schema.py
old mode 100644
new mode 100755
index f3437cc8fee..35765750091
--- a/scripts/generate_schema.py
+++ b/scripts/generate_schema.py
@@ -62,7 +62,7 @@ def main(schemastore: bool, outfile: IO[str]) -> None:
     }
 
     if schemastore:
-        schema["$id"] = ("https://json.schemastore.org/partial-black.json",)
+        schema["$id"] = "https://json.schemastore.org/partial-black.json"
         # The precise list of unstable features may change frequently, so don't
         # bother putting it in SchemaStore
         schema["properties"]["enable-unstable-feature"]["items"] = {"type": "string"}

From 2623269dab4de9d47750b1a8af5ae44240e13cf6 Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Thu, 1 Feb 2024 21:50:45 -0800
Subject: [PATCH 1008/1034] Ignore pyproject.toml missing tool.black section
 (#4204)

Fixes #2863

This is pretty desirable in a monorepo situation where you have
configuration in the root since it will mean you don't have to
reconfigure every project.

The good news for backward compatibility is that `find_project_root`
continues to stop at any git or hg root, so in all cases repo root
coincides with a pyproject.toml missing tool.black, we'll continue to
have the project root as before and end up using default config
(i.e. we're unlikely to randomly start using the user config).

The other thing we need to be a little careful about is that changing
find_project_root logic affects what `exclude` is relative to.  Since we
only change in cases where there is no config, this only applies where
users were using `exclude` via command line arg (and had pyproject.toml
missing tool.black in a dir that was not repo root).

Finally, for the few who could be affected, the fix is to put an empty
`[tool.black]` in pyproject.toml
---
 CHANGES.md                                 |  7 ++++++-
 docs/usage_and_configuration/the_basics.md |  9 +++++----
 src/black/files.py                         | 13 ++++++++++---
 tests/test_black.py                        | 18 ++++++++++++++++--
 4 files changed, 37 insertions(+), 10 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 4fd030df6df..a3ffba610d9 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -16,7 +16,12 @@
 
 ### Configuration
 
-<!-- Changes to how Black can be configured -->
+- _Black_ now ignores `pyproject.toml` that is missing a `tool.black` section when
+  discovering project root and configuration. Since _Black_ continues to use version
+  control as an indicator of project root, this is expected to primarily change behavior
+  for users in a monorepo setup (desirably). If you wish to preserve previous behavior,
+  simply add an empty `[tool.black]` to the previously discovered `pyproject.toml`
+  (#4204)
 
 ### Packaging
 
diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index dc9d9a64c68..61c52450165 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -456,10 +456,11 @@ of tools like [Poetry](https://python-poetry.org/),
 
 ### Where _Black_ looks for the file
 
-By default _Black_ looks for `pyproject.toml` starting from the common base directory of
-all files and directories passed on the command line. If it's not there, it looks in
-parent directories. It stops looking when it finds the file, or a `.git` directory, or a
-`.hg` directory, or the root of the file system, whichever comes first.
+By default _Black_ looks for `pyproject.toml` containing a `[tool.black]` section
+starting from the common base directory of all files and directories passed on the
+command line. If it's not there, it looks in parent directories. It stops looking when
+it finds the file, or a `.git` directory, or a `.hg` directory, or the root of the file
+system, whichever comes first.
 
 If you're formatting standard input, _Black_ will look for configuration starting from
 the current working directory.
diff --git a/src/black/files.py b/src/black/files.py
index 1eb8745572b..960f13ee270 100644
--- a/src/black/files.py
+++ b/src/black/files.py
@@ -42,6 +42,12 @@
     import colorama  # noqa: F401
 
 
+@lru_cache
+def _load_toml(path: Union[Path, str]) -> Dict[str, Any]:
+    with open(path, "rb") as f:
+        return tomllib.load(f)
+
+
 @lru_cache
 def find_project_root(
     srcs: Sequence[str], stdin_filename: Optional[str] = None
@@ -84,7 +90,9 @@ def find_project_root(
             return directory, ".hg directory"
 
         if (directory / "pyproject.toml").is_file():
-            return directory, "pyproject.toml"
+            pyproject_toml = _load_toml(directory / "pyproject.toml")
+            if "black" in pyproject_toml.get("tool", {}):
+                return directory, "pyproject.toml"
 
     return directory, "file system root"
 
@@ -117,8 +125,7 @@ def parse_pyproject_toml(path_config: str) -> Dict[str, Any]:
 
     If parsing fails, will raise a tomllib.TOMLDecodeError.
     """
-    with open(path_config, "rb") as f:
-        pyproject_toml = tomllib.load(f)
+    pyproject_toml = _load_toml(path_config)
     config: Dict[str, Any] = pyproject_toml.get("tool", {}).get("black", {})
     config = {k.replace("--", "").replace("-", "_"): v for k, v in config.items()}
 
diff --git a/tests/test_black.py b/tests/test_black.py
index 123ea0bb88a..f876d365b12 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -1668,9 +1668,9 @@ def test_find_project_root(self) -> None:
             src_dir.mkdir()
 
             root_pyproject = root / "pyproject.toml"
-            root_pyproject.touch()
+            root_pyproject.write_text("[tool.black]", encoding="utf-8")
             src_pyproject = src_dir / "pyproject.toml"
-            src_pyproject.touch()
+            src_pyproject.write_text("[tool.black]", encoding="utf-8")
             src_python = src_dir / "foo.py"
             src_python.touch()
 
@@ -1693,6 +1693,20 @@ def test_find_project_root(self) -> None:
                     (src_dir.resolve(), "pyproject.toml"),
                 )
 
+            src_sub = src_dir / "sub"
+            src_sub.mkdir()
+
+            src_sub_pyproject = src_sub / "pyproject.toml"
+            src_sub_pyproject.touch()  # empty
+
+            src_sub_python = src_sub / "bar.py"
+
+            # we skip src_sub_pyproject since it is missing the [tool.black] section
+            self.assertEqual(
+                black.find_project_root((src_sub_python,)),
+                (src_dir.resolve(), "pyproject.toml"),
+            )
+
     @patch(
         "black.files.find_user_pyproject_toml",
     )

From 9728b8e9b8720b5e401249c077e32de46a479161 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Thu, 1 Feb 2024 21:58:51 -0800
Subject: [PATCH 1009/1034] Move hug_parens_with_braces_and_square_brackets
 into the unstable style (#4198)

Primarily because of #4036 (a crash) but also because of the feedback
in #4098 and #4099.
---
 CHANGES.md                                                    | 3 +++
 docs/the_black_code_style/future_style.md                     | 4 ++--
 src/black/mode.py                                             | 2 ++
 .../preview_hug_parens_with_braces_and_square_brackets.py     | 2 +-
 ...eview_hug_parens_with_braces_and_square_brackets_no_ll1.py | 2 +-
 5 files changed, 9 insertions(+), 4 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index a3ffba610d9..4d646a2779e 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -14,6 +14,9 @@
 
 <!-- Changes that affect Black's preview style -->
 
+- Move the `hug_parens_with_braces_and_square_brackets` feature to the unstable style
+  due to an outstanding crash and proposed formatting tweaks (#4198)
+
 ### Configuration
 
 - _Black_ now ignores `pyproject.toml` that is missing a `tool.black` section when
diff --git a/docs/the_black_code_style/future_style.md b/docs/the_black_code_style/future_style.md
index 1c11186f811..86e5aa806b2 100644
--- a/docs/the_black_code_style/future_style.md
+++ b/docs/the_black_code_style/future_style.md
@@ -24,8 +24,6 @@ Currently, the following features are included in the preview style:
   strings
 - `unify_docstring_detection`: fix inconsistencies in whether certain strings are
   detected as docstrings
-- `hug_parens_with_braces_and_square_brackets`: more compact formatting of nested
-  brackets ([see below](labels/hug-parens))
 - `no_normalize_fmt_skip_whitespace`: whitespace before `# fmt: skip` comments is no
   longer normalized
 - `typed_params_trailing_comma`: consistently add trailing commas to typed function
@@ -41,6 +39,8 @@ The unstable style additionally includes the following features:
   ([see below](labels/wrap-long-dict-values))
 - `multiline_string_handling`: more compact formatting of expressions involving
   multiline strings ([see below](labels/multiline-string-handling))
+- `hug_parens_with_braces_and_square_brackets`: more compact formatting of nested
+  brackets ([see below](labels/hug-parens))
 
 (labels/hug-parens)=
 
diff --git a/src/black/mode.py b/src/black/mode.py
index 22352e7c6a8..5738bd6b793 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -186,6 +186,8 @@ class Preview(Enum):
     Preview.wrap_long_dict_values_in_parens,
     # See issue #4159
     Preview.multiline_string_handling,
+    # See issue #4036 (crash), #4098, #4099 (proposed tweaks)
+    Preview.hug_parens_with_braces_and_square_brackets,
 }
 
 
diff --git a/tests/data/cases/preview_hug_parens_with_braces_and_square_brackets.py b/tests/data/cases/preview_hug_parens_with_braces_and_square_brackets.py
index 47a6a0bcae6..cbbcf16d3bd 100644
--- a/tests/data/cases/preview_hug_parens_with_braces_and_square_brackets.py
+++ b/tests/data/cases/preview_hug_parens_with_braces_and_square_brackets.py
@@ -1,4 +1,4 @@
-# flags: --preview
+# flags: --unstable
 def foo_brackets(request):
     return JsonResponse(
         {
diff --git a/tests/data/cases/preview_hug_parens_with_braces_and_square_brackets_no_ll1.py b/tests/data/cases/preview_hug_parens_with_braces_and_square_brackets_no_ll1.py
index fdebdf69c20..16ebea379bc 100644
--- a/tests/data/cases/preview_hug_parens_with_braces_and_square_brackets_no_ll1.py
+++ b/tests/data/cases/preview_hug_parens_with_braces_and_square_brackets_no_ll1.py
@@ -1,4 +1,4 @@
-# flags: --preview --no-preview-line-length-1
+# flags: --unstable --no-preview-line-length-1
 # split out from preview_hug_parens_with_brackes_and_square_brackets, as it produces
 # different code on the second pass with line-length 1 in many cases.
 # Seems to be about whether the last string in a sequence gets wrapped in parens or not.

From 632f44bd68b818cbc9dfd57e7485f0e5c3863b76 Mon Sep 17 00:00:00 2001
From: cobalt <61329810+RedGuy12@users.noreply.github.com>
Date: Fri, 2 Feb 2024 00:00:41 -0600
Subject: [PATCH 1010/1034] docs: Refactor pycodestyle/Flake8 compatibility
 docs (#4194)

Signed-off-by: RedGuy12 <61329810+RedGuy12@users.noreply.github.com>
Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 .flake8                                       |   4 +-
 docs/compatible_configs/flake8/.flake8        |   2 +-
 docs/compatible_configs/flake8/setup.cfg      |   2 +-
 docs/compatible_configs/flake8/tox.ini        |   2 +-
 docs/compatible_configs/pycodestyle/.flake8   |   3 +
 docs/compatible_configs/pycodestyle/setup.cfg |   3 +
 docs/compatible_configs/pycodestyle/tox.ini   |   3 +
 docs/faq.md                                   |   9 +-
 docs/guides/using_black_with_other_tools.md   | 130 ++++++++++--------
 docs/the_black_code_style/current_style.md    |  33 +----
 10 files changed, 94 insertions(+), 97 deletions(-)
 create mode 100644 docs/compatible_configs/pycodestyle/.flake8
 create mode 100644 docs/compatible_configs/pycodestyle/setup.cfg
 create mode 100644 docs/compatible_configs/pycodestyle/tox.ini

diff --git a/.flake8 b/.flake8
index 85f51cf9f05..f8dca18e7cf 100644
--- a/.flake8
+++ b/.flake8
@@ -1,8 +1,8 @@
 [flake8]
 # B905 should be enabled when we drop support for 3.9
-ignore = E203, E266, E501, E704, W503, B905, B907
+ignore = E203, E266, E501, E701, E704, W503, B905, B907
 # line length is intentionally set to 80 here because black uses Bugbear
-# See https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#line-length for more details
+# See https://black.readthedocs.io/en/stable/guides/using_black_with_other_tools.html#bugbear for more details
 max-line-length = 80
 max-complexity = 18
 select = B,C,E,F,W,T4,B9
diff --git a/docs/compatible_configs/flake8/.flake8 b/docs/compatible_configs/flake8/.flake8
index 8dd399ab55b..0d4ade348d6 100644
--- a/docs/compatible_configs/flake8/.flake8
+++ b/docs/compatible_configs/flake8/.flake8
@@ -1,3 +1,3 @@
 [flake8]
 max-line-length = 88
-extend-ignore = E203
+extend-ignore = E203,E701
diff --git a/docs/compatible_configs/flake8/setup.cfg b/docs/compatible_configs/flake8/setup.cfg
index 8dd399ab55b..0d4ade348d6 100644
--- a/docs/compatible_configs/flake8/setup.cfg
+++ b/docs/compatible_configs/flake8/setup.cfg
@@ -1,3 +1,3 @@
 [flake8]
 max-line-length = 88
-extend-ignore = E203
+extend-ignore = E203,E701
diff --git a/docs/compatible_configs/flake8/tox.ini b/docs/compatible_configs/flake8/tox.ini
index 8dd399ab55b..0d4ade348d6 100644
--- a/docs/compatible_configs/flake8/tox.ini
+++ b/docs/compatible_configs/flake8/tox.ini
@@ -1,3 +1,3 @@
 [flake8]
 max-line-length = 88
-extend-ignore = E203
+extend-ignore = E203,E701
diff --git a/docs/compatible_configs/pycodestyle/.flake8 b/docs/compatible_configs/pycodestyle/.flake8
new file mode 100644
index 00000000000..34225907524
--- /dev/null
+++ b/docs/compatible_configs/pycodestyle/.flake8
@@ -0,0 +1,3 @@
+[pycodestyle]
+max-line-length = 88
+ignore = E203,E701
diff --git a/docs/compatible_configs/pycodestyle/setup.cfg b/docs/compatible_configs/pycodestyle/setup.cfg
new file mode 100644
index 00000000000..34225907524
--- /dev/null
+++ b/docs/compatible_configs/pycodestyle/setup.cfg
@@ -0,0 +1,3 @@
+[pycodestyle]
+max-line-length = 88
+ignore = E203,E701
diff --git a/docs/compatible_configs/pycodestyle/tox.ini b/docs/compatible_configs/pycodestyle/tox.ini
new file mode 100644
index 00000000000..34225907524
--- /dev/null
+++ b/docs/compatible_configs/pycodestyle/tox.ini
@@ -0,0 +1,3 @@
+[pycodestyle]
+max-line-length = 88
+ignore = E203,E701
diff --git a/docs/faq.md b/docs/faq.md
index 124a096efac..d19ff8e7ace 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -77,13 +77,10 @@ following will not be formatted:
 - invalid syntax, as it can't be safely distinguished from automagics in the absence of
   a running `IPython` kernel.
 
-## Why are Flake8's E203 and W503 violated?
+## Why does Flake8 report warnings?
 
-Because they go against PEP 8. E203 falsely triggers on list
-[slices](the_black_code_style/current_style.md#slices), and adhering to W503 hinders
-readability because operators are misaligned. Disable W503 and enable the
-disabled-by-default counterpart W504. E203 should be disabled while changes are still
-[discussed](https://github.com/PyCQA/pycodestyle/issues/373).
+Some of Flake8's rules conflict with Black's style. We recommend disabling these rules.
+See [Using _Black_ with other tools](labels/why-pycodestyle-warnings).
 
 ## Which Python versions does Black support?
 
diff --git a/docs/guides/using_black_with_other_tools.md b/docs/guides/using_black_with_other_tools.md
index e642a1aef33..187e3a3e6f5 100644
--- a/docs/guides/using_black_with_other_tools.md
+++ b/docs/guides/using_black_with_other_tools.md
@@ -134,10 +134,10 @@ profile = black
 
 </details>
 
-### Flake8
+### pycodestyle
 
-[Flake8](https://pypi.org/p/flake8/) is a code linter. It warns you of syntax errors,
-possible bugs, stylistic errors, etc. For the most part, Flake8 follows
+[pycodestyle](https://pycodestyle.pycqa.org/) is a code linter. It warns you of syntax
+errors, possible bugs, stylistic errors, etc. For the most part, pycodestyle follows
 [PEP 8](https://www.python.org/dev/peps/pep-0008/) when warning about stylistic errors.
 There are a few deviations that cause incompatibilities with _Black_.
 
@@ -145,67 +145,115 @@ There are a few deviations that cause incompatibilities with _Black_.
 
 ```
 max-line-length = 88
-extend-ignore = E203, E704
+ignore = E203,E701
 ```
 
+(labels/why-pycodestyle-warnings)=
+
 #### Why those options above?
 
+##### `max-line-length`
+
+As with isort, pycodestyle should be configured to allow lines up to the length limit of
+`88`, _Black_'s default.
+
+##### `E203`
+
 In some cases, as determined by PEP 8, _Black_ will enforce an equal amount of
-whitespace around slice operators. Due to this, Flake8 will raise
-`E203 whitespace before ':'` warnings. Since this warning is not PEP 8 compliant, Flake8
-should be configured to ignore it via `extend-ignore = E203`.
+whitespace around slice operators. Due to this, pycodestyle will raise
+`E203 whitespace before ':'` warnings. Since this warning is not PEP 8 compliant, it
+should be disabled.
+
+##### `E701` / `E704`
+
+_Black_ will collapse implementations of classes and functions consisting solely of `..`
+to a single line. This matches how such examples are formatted in PEP 8. It remains true
+that in all other cases Black will prevent multiple statements on the same line, in
+accordance with PEP 8 generally discouraging this.
+
+However, `pycodestyle` does not mirror this logic and may raise
+`E701 multiple statements on one line (colon)` in this situation. Its
+disabled-by-default `E704 multiple statements on one line (def)` rule may also raise
+warnings and should not be enabled.
+
+##### `W503`
 
 When breaking a line, _Black_ will break it before a binary operator. This is compliant
 with PEP 8 as of
 [April 2016](https://github.com/python/peps/commit/c59c4376ad233a62ca4b3a6060c81368bd21e85b#diff-64ec08cc46db7540f18f2af46037f599).
 There's a disabled-by-default warning in Flake8 which goes against this PEP 8
 recommendation called `W503 line break before binary operator`. It should not be enabled
-in your configuration.
-
-Also, as like with isort, flake8 should be configured to allow lines up to the length
-limit of `88`, _Black_'s default. This explains `max-line-length = 88`.
+in your configuration. You can use its counterpart
+`W504 line break after binary operator` instead.
 
 #### Formats
 
 <details>
-<summary>.flake8</summary>
+<summary>setup.cfg, .pycodestyle, tox.ini</summary>
 
 ```ini
-[flake8]
+[pycodestyle]
 max-line-length = 88
-extend-ignore = E203, E704
+ignore = E203,E701
 ```
 
 </details>
 
-<details>
-<summary>setup.cfg</summary>
+### Flake8
 
-```ini
+[Flake8](https://pypi.org/p/flake8/) is a wrapper around multiple linters, including
+pycodestyle. As such, it has many of the same issues.
+
+#### Bugbear
+
+It's recommended to use [the Bugbear plugin](https://github.com/PyCQA/flake8-bugbear)
+and enable
+[its B950 check](https://github.com/PyCQA/flake8-bugbear#opinionated-warnings#:~:text=you%20expect%20it.-,B950,-%3A%20Line%20too%20long)
+instead of using Flake8's E501, because it aligns with
+[Black's 10% rule](labels/line-length).
+
+Install Bugbear and use the following config:
+
+```
+[flake8]
+max-line-length = 80
+extend-select = B950
+extend-ignore = E203,E501,E701
+```
+
+#### Minimal Configuration
+
+In cases where you can't or don't want to install Bugbear, you can use this minimally
+compatible config:
+
+```
 [flake8]
 max-line-length = 88
-extend-ignore = E203, E704
+extend-ignore = E203,E701
 ```
 
-</details>
+#### Why those options above?
+
+See [the pycodestyle section](labels/why-pycodestyle-warnings) above.
+
+#### Formats
 
 <details>
-<summary>tox.ini</summary>
+<summary>.flake8, setup.cfg, tox.ini</summary>
 
 ```ini
 [flake8]
 max-line-length = 88
-extend-ignore = E203, E704
+extend-ignore = E203,E701
 ```
 
 </details>
 
 ### Pylint
 
-[Pylint](https://pypi.org/p/pylint/) is also a code linter like Flake8. It has the same
-checks as flake8 and more. In particular, it has more formatting checks regarding style
-conventions like variable naming. With so many checks, Pylint is bound to have some
-mixed feelings about _Black_'s formatting style.
+[Pylint](https://pypi.org/p/pylint/) is also a code linter like Flake8. It has many of
+the same checks as Flake8 and more. It particularly has more formatting checks regarding
+style conventions like variable naming.
 
 #### Configuration
 
@@ -252,35 +300,3 @@ max-line-length = "88"
 ```
 
 </details>
-
-### pycodestyle
-
-[pycodestyle](https://pycodestyle.pycqa.org/) is also a code linter like Flake8.
-
-#### Configuration
-
-```
-max-line-length = 88
-ignore = E203
-```
-
-#### Why those options above?
-
-pycodestyle should be configured to only complain about lines that surpass `88`
-characters via `max_line_length = 88`.
-
-See
-[Why are Flake8’s E203 and W503 violated?](https://black.readthedocs.io/en/stable/faq.html#why-are-flake8-s-e203-and-w503-violated)
-
-#### Formats
-
-<details>
-<summary>setup.cfg</summary>
-
-```cfg
-[pycodestyle]
-ignore = E203
-max_line_length = 88
-```
-
-</details>
diff --git a/docs/the_black_code_style/current_style.md b/docs/the_black_code_style/current_style.md
index ca5d1d4a701..586c79074af 100644
--- a/docs/the_black_code_style/current_style.md
+++ b/docs/the_black_code_style/current_style.md
@@ -143,7 +143,7 @@ significantly shorter files than sticking with 80 (the most popular), or even 79
 by the standard library). In general,
 [90-ish seems like the wise choice](https://youtu.be/wf-BqAjZb8M?t=260).
 
-If you're paid by the line of code you write, you can pass `--line-length` with a lower
+If you're paid by the lines of code you write, you can pass `--line-length` with a lower
 number. _Black_ will try to respect that. However, sometimes it won't be able to without
 breaking other rules. In those rare cases, auto-formatted code will exceed your allotted
 limit.
@@ -153,35 +153,10 @@ harder to work with line lengths exceeding 100 characters. It also adversely aff
 side-by-side diff review on typical screen resolutions. Long lines also make it harder
 to present code neatly in documentation or talk slides.
 
-#### Flake8
+#### Flake8 and other linters
 
-If you use Flake8, you have a few options:
-
-1. Recommended is using [Bugbear](https://github.com/PyCQA/flake8-bugbear) and enabling
-   its B950 check instead of using Flake8's E501, because it aligns with Black's 10%
-   rule. Install Bugbear and use the following config:
-
-   ```ini
-   [flake8]
-   max-line-length = 80
-   ...
-   select = C,E,F,W,B,B950
-   extend-ignore = E203, E501, E704
-   ```
-
-   The rationale for B950 is explained in
-   [Bugbear's documentation](https://github.com/PyCQA/flake8-bugbear#opinionated-warnings).
-
-2. For a minimally compatible config:
-
-   ```ini
-   [flake8]
-   max-line-length = 88
-   extend-ignore = E203, E704
-   ```
-
-An explanation of why E203 is disabled can be found in the [Slices section](#slices) of
-this page.
+See [Using _Black_ with other tools](../guides/using_black_with_other_tools.md) about
+linter compatibility.
 
 ### Empty lines
 

From a08b480a2f39fb4fc7b210d8b450e33d3879f77d Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 5 Feb 2024 01:09:21 -0800
Subject: [PATCH 1011/1034] Bump pypa/cibuildwheel from 2.16.4 to 2.16.5
 (#4212)

---
 .github/workflows/pypi_upload.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/pypi_upload.yml b/.github/workflows/pypi_upload.yml
index 52525419f0a..3c99f66cc7b 100644
--- a/.github/workflows/pypi_upload.yml
+++ b/.github/workflows/pypi_upload.yml
@@ -89,7 +89,7 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
-      - uses: pypa/cibuildwheel@v2.16.4
+      - uses: pypa/cibuildwheel@v2.16.5
         with:
           only: ${{ matrix.only }}
 

From 3e80de3447dee272e9977ab58b1560a669b7b848 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 5 Feb 2024 04:47:35 -0800
Subject: [PATCH 1012/1034] Bump furo from 2023.9.10 to 2024.1.29 in /docs
 (#4211)

Bumps [furo](https://github.com/pradyunsg/furo) from 2023.9.10 to 2024.1.29.
- [Release notes](https://github.com/pradyunsg/furo/releases)
- [Changelog](https://github.com/pradyunsg/furo/blob/main/docs/changelog.md)
- [Commits](https://github.com/pradyunsg/furo/compare/2023.09.10...2024.01.29)

---
updated-dependencies:
- dependency-name: furo
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 docs/requirements.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index b5b9e22fc84..3bc058a0721 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -6,4 +6,4 @@ Sphinx==7.2.6
 docutils==0.20.1
 sphinxcontrib-programoutput==0.17
 sphinx_copybutton==0.5.2
-furo==2023.9.10
+furo==2024.1.29

From 7edb50f5a0afc56bb648dc14640ced144366b43a Mon Sep 17 00:00:00 2001
From: Brandon J <153339574+veryslowcode@users.noreply.github.com>
Date: Mon, 5 Feb 2024 05:56:07 -0700
Subject: [PATCH 1013/1034] fix: additional newline added to docstring when the
 previous line length is less than the line length limit minus 1 (#4185)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 CHANGES.md                                    |  2 ++
 docs/the_black_code_style/future_style.md     |  2 ++
 src/black/linegen.py                          | 13 ++++++++++---
 src/black/mode.py                             |  1 +
 src/black/resources/black.schema.json         |  3 ++-
 tests/data/cases/docstring_newline_preview.py |  4 ++++
 6 files changed, 21 insertions(+), 4 deletions(-)
 create mode 100644 tests/data/cases/docstring_newline_preview.py

diff --git a/CHANGES.md b/CHANGES.md
index 4d646a2779e..a726a91457a 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -16,6 +16,8 @@
 
 - Move the `hug_parens_with_braces_and_square_brackets` feature to the unstable style
   due to an outstanding crash and proposed formatting tweaks (#4198)
+- Checking for newline before adding one on docstring that is almost at the line limit
+  (#4185)
 
 ### Configuration
 
diff --git a/docs/the_black_code_style/future_style.md b/docs/the_black_code_style/future_style.md
index 86e5aa806b2..d7640765b30 100644
--- a/docs/the_black_code_style/future_style.md
+++ b/docs/the_black_code_style/future_style.md
@@ -28,6 +28,8 @@ Currently, the following features are included in the preview style:
   longer normalized
 - `typed_params_trailing_comma`: consistently add trailing commas to typed function
   parameters
+- `docstring_check_for_newline`: checks if there is a newline before the terminating
+  quotes of a docstring
 
 (labels/unstable-features)=
 
diff --git a/src/black/linegen.py b/src/black/linegen.py
index c74ff9c0b4b..c45a1308013 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -477,15 +477,22 @@ def visit_STRING(self, leaf: Leaf) -> Iterator[Line]:
                 last_line_length = len(lines[-1]) if docstring else 0
 
                 # If adding closing quotes would cause the last line to exceed
-                # the maximum line length then put a line break before the
-                # closing quotes
+                # the maximum line length, and the closing quote is not
+                # prefixed by a newline then put a line break before
+                # the closing quotes
                 if (
                     len(lines) > 1
                     and last_line_length + quote_len > self.mode.line_length
                     and len(indent) + quote_len <= self.mode.line_length
                     and not has_trailing_backslash
                 ):
-                    leaf.value = prefix + quote + docstring + "\n" + indent + quote
+                    if (
+                        Preview.docstring_check_for_newline in self.mode
+                        and leaf.value[-1 - quote_len] == "\n"
+                    ):
+                        leaf.value = prefix + quote + docstring + quote
+                    else:
+                        leaf.value = prefix + quote + docstring + "\n" + indent + quote
                 else:
                     leaf.value = prefix + quote + docstring + quote
             else:
diff --git a/src/black/mode.py b/src/black/mode.py
index 5738bd6b793..9593a90d170 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -177,6 +177,7 @@ class Preview(Enum):
     wrap_long_dict_values_in_parens = auto()
     multiline_string_handling = auto()
     typed_params_trailing_comma = auto()
+    docstring_check_for_newline = auto()
 
 
 UNSTABLE_FEATURES: Set[Preview] = {
diff --git a/src/black/resources/black.schema.json b/src/black/resources/black.schema.json
index 40bf39137f7..5b1b1320eb4 100644
--- a/src/black/resources/black.schema.json
+++ b/src/black/resources/black.schema.json
@@ -85,7 +85,8 @@
           "no_normalize_fmt_skip_whitespace",
           "wrap_long_dict_values_in_parens",
           "multiline_string_handling",
-          "typed_params_trailing_comma"
+          "typed_params_trailing_comma",
+          "docstring_check_for_newline"
         ]
       },
       "description": "Enable specific features included in the `--unstable` style. Requires `--preview`. No compatibility guarantees are provided on the behavior or existence of any unstable features."
diff --git a/tests/data/cases/docstring_newline_preview.py b/tests/data/cases/docstring_newline_preview.py
new file mode 100644
index 00000000000..5c129ca5f80
--- /dev/null
+++ b/tests/data/cases/docstring_newline_preview.py
@@ -0,0 +1,4 @@
+# flags: --preview
+"""
+87 characters ............................................................................
+"""

From 32230e6f5c4bc6bb5c469451e15f3f54d9884b51 Mon Sep 17 00:00:00 2001
From: Seung Wan Yoo <74849806+wannieman98@users.noreply.github.com>
Date: Mon, 5 Feb 2024 22:33:11 +0900
Subject: [PATCH 1014/1034] fix: bug where the doublestar operation had
 inconsistent formatting. (#4154)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 CHANGES.md                                    |   2 +
 docs/the_black_code_style/future_style.md     |   2 +
 src/black/mode.py                             |   1 +
 src/black/resources/black.schema.json         |   1 +
 src/black/trans.py                            | 138 ++++++++++++++----
 ...simple_lookup_for_doublestar_expression.py |  14 ++
 6 files changed, 132 insertions(+), 26 deletions(-)
 create mode 100644 tests/data/cases/is_simple_lookup_for_doublestar_expression.py

diff --git a/CHANGES.md b/CHANGES.md
index a726a91457a..5d4858da811 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -16,6 +16,8 @@
 
 - Move the `hug_parens_with_braces_and_square_brackets` feature to the unstable style
   due to an outstanding crash and proposed formatting tweaks (#4198)
+- Fixed a bug where base expressions caused inconsistent formatting of \*\* in tenary
+  expression (#4154)
 - Checking for newline before adding one on docstring that is almost at the line limit
   (#4185)
 
diff --git a/docs/the_black_code_style/future_style.md b/docs/the_black_code_style/future_style.md
index d7640765b30..f4534680645 100644
--- a/docs/the_black_code_style/future_style.md
+++ b/docs/the_black_code_style/future_style.md
@@ -28,6 +28,8 @@ Currently, the following features are included in the preview style:
   longer normalized
 - `typed_params_trailing_comma`: consistently add trailing commas to typed function
   parameters
+- `is_simple_lookup_for_doublestar_expression`: fix line length computation for certain
+  expressions that involve the power operator
 - `docstring_check_for_newline`: checks if there is a newline before the terminating
   quotes of a docstring
 
diff --git a/src/black/mode.py b/src/black/mode.py
index 9593a90d170..f9fad082e03 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -177,6 +177,7 @@ class Preview(Enum):
     wrap_long_dict_values_in_parens = auto()
     multiline_string_handling = auto()
     typed_params_trailing_comma = auto()
+    is_simple_lookup_for_doublestar_expression = auto()
     docstring_check_for_newline = auto()
 
 
diff --git a/src/black/resources/black.schema.json b/src/black/resources/black.schema.json
index 5b1b1320eb4..04ddb32e087 100644
--- a/src/black/resources/black.schema.json
+++ b/src/black/resources/black.schema.json
@@ -86,6 +86,7 @@
           "wrap_long_dict_values_in_parens",
           "multiline_string_handling",
           "typed_params_trailing_comma",
+          "is_simple_lookup_for_doublestar_expression",
           "docstring_check_for_newline"
         ]
       },
diff --git a/src/black/trans.py b/src/black/trans.py
index 7c7335a005b..29a978c6b71 100644
--- a/src/black/trans.py
+++ b/src/black/trans.py
@@ -29,7 +29,7 @@
 
 from black.comments import contains_pragma_comment
 from black.lines import Line, append_leaves
-from black.mode import Feature, Mode
+from black.mode import Feature, Mode, Preview
 from black.nodes import (
     CLOSING_BRACKETS,
     OPENING_BRACKETS,
@@ -94,43 +94,36 @@ def hug_power_op(
     else:
         raise CannotTransform("No doublestar token was found in the line.")
 
-    def is_simple_lookup(index: int, step: Literal[1, -1]) -> bool:
+    def is_simple_lookup(index: int, kind: Literal[1, -1]) -> bool:
         # Brackets and parentheses indicate calls, subscripts, etc. ...
         # basically stuff that doesn't count as "simple". Only a NAME lookup
         # or dotted lookup (eg. NAME.NAME) is OK.
-        if step == -1:
-            disallowed = {token.RPAR, token.RSQB}
-        else:
-            disallowed = {token.LPAR, token.LSQB}
-
-        while 0 <= index < len(line.leaves):
-            current = line.leaves[index]
-            if current.type in disallowed:
-                return False
-            if current.type not in {token.NAME, token.DOT} or current.value == "for":
-                # If the current token isn't disallowed, we'll assume this is simple as
-                # only the disallowed tokens are semantically attached to this lookup
-                # expression we're checking. Also, stop early if we hit the 'for' bit
-                # of a comprehension.
-                return True
+        if Preview.is_simple_lookup_for_doublestar_expression not in mode:
+            return original_is_simple_lookup_func(line, index, kind)
 
-            index += step
-
-        return True
+        else:
+            if kind == -1:
+                return handle_is_simple_look_up_prev(
+                    line, index, {token.RPAR, token.RSQB}
+                )
+            else:
+                return handle_is_simple_lookup_forward(
+                    line, index, {token.LPAR, token.LSQB}
+                )
 
-    def is_simple_operand(index: int, kind: Literal["base", "exponent"]) -> bool:
+    def is_simple_operand(index: int, kind: Literal[1, -1]) -> bool:
         # An operand is considered "simple" if's a NAME, a numeric CONSTANT, a simple
         # lookup (see above), with or without a preceding unary operator.
         start = line.leaves[index]
         if start.type in {token.NAME, token.NUMBER}:
-            return is_simple_lookup(index, step=(1 if kind == "exponent" else -1))
+            return is_simple_lookup(index, kind)
 
         if start.type in {token.PLUS, token.MINUS, token.TILDE}:
             if line.leaves[index + 1].type in {token.NAME, token.NUMBER}:
-                # step is always one as bases with a preceding unary op will be checked
+                # kind is always one as bases with a preceding unary op will be checked
                 # for simplicity starting from the next token (so it'll hit the check
                 # above).
-                return is_simple_lookup(index + 1, step=1)
+                return is_simple_lookup(index + 1, kind=1)
 
         return False
 
@@ -145,9 +138,9 @@ def is_simple_operand(index: int, kind: Literal["base", "exponent"]) -> bool:
         should_hug = (
             (0 < idx < len(line.leaves) - 1)
             and leaf.type == token.DOUBLESTAR
-            and is_simple_operand(idx - 1, kind="base")
+            and is_simple_operand(idx - 1, kind=-1)
             and line.leaves[idx - 1].value != "lambda"
-            and is_simple_operand(idx + 1, kind="exponent")
+            and is_simple_operand(idx + 1, kind=1)
         )
         if should_hug:
             new_leaf.prefix = ""
@@ -162,6 +155,99 @@ def is_simple_operand(index: int, kind: Literal["base", "exponent"]) -> bool:
     yield new_line
 
 
+def original_is_simple_lookup_func(
+    line: Line, index: int, step: Literal[1, -1]
+) -> bool:
+    if step == -1:
+        disallowed = {token.RPAR, token.RSQB}
+    else:
+        disallowed = {token.LPAR, token.LSQB}
+
+    while 0 <= index < len(line.leaves):
+        current = line.leaves[index]
+        if current.type in disallowed:
+            return False
+        if current.type not in {token.NAME, token.DOT} or current.value == "for":
+            # If the current token isn't disallowed, we'll assume this is
+            # simple as only the disallowed tokens are semantically
+            # attached to this lookup expression we're checking. Also,
+            # stop early if we hit the 'for' bit of a comprehension.
+            return True
+
+        index += step
+
+    return True
+
+
+def handle_is_simple_look_up_prev(line: Line, index: int, disallowed: Set[int]) -> bool:
+    """
+    Handling the determination of is_simple_lookup for the lines prior to the doublestar
+    token. This is required because of the need to isolate the chained expression
+    to determine the bracket or parenthesis belong to the single expression.
+    """
+    contains_disallowed = False
+    chain = []
+
+    while 0 <= index < len(line.leaves):
+        current = line.leaves[index]
+        chain.append(current)
+        if not contains_disallowed and current.type in disallowed:
+            contains_disallowed = True
+        if not is_expression_chained(chain):
+            return not contains_disallowed
+
+        index -= 1
+
+    return True
+
+
+def handle_is_simple_lookup_forward(
+    line: Line, index: int, disallowed: Set[int]
+) -> bool:
+    """
+    Handling decision is_simple_lookup for the lines behind the doublestar token.
+    This function is simplified to keep consistent with the prior logic and the forward
+    case are more straightforward and do not need to care about chained expressions.
+    """
+    while 0 <= index < len(line.leaves):
+        current = line.leaves[index]
+        if current.type in disallowed:
+            return False
+        if current.type not in {token.NAME, token.DOT} or (
+            current.type == token.NAME and current.value == "for"
+        ):
+            # If the current token isn't disallowed, we'll assume this is simple as
+            # only the disallowed tokens are semantically attached to this lookup
+            # expression we're checking. Also, stop early if we hit the 'for' bit
+            # of a comprehension.
+            return True
+
+        index += 1
+
+    return True
+
+
+def is_expression_chained(chained_leaves: List[Leaf]) -> bool:
+    """
+    Function to determine if the variable is a chained call.
+    (e.g., foo.lookup, foo().lookup, (foo.lookup())) will be recognized as chained call)
+    """
+    if len(chained_leaves) < 2:
+        return True
+
+    current_leaf = chained_leaves[-1]
+    past_leaf = chained_leaves[-2]
+
+    if past_leaf.type == token.NAME:
+        return current_leaf.type in {token.DOT}
+    elif past_leaf.type in {token.RPAR, token.RSQB}:
+        return current_leaf.type in {token.RSQB, token.RPAR}
+    elif past_leaf.type in {token.LPAR, token.LSQB}:
+        return current_leaf.type in {token.NAME, token.LPAR, token.LSQB}
+    else:
+        return False
+
+
 class StringTransformer(ABC):
     """
     An implementation of the Transformer protocol that relies on its
diff --git a/tests/data/cases/is_simple_lookup_for_doublestar_expression.py b/tests/data/cases/is_simple_lookup_for_doublestar_expression.py
new file mode 100644
index 00000000000..a0d2e2ba842
--- /dev/null
+++ b/tests/data/cases/is_simple_lookup_for_doublestar_expression.py
@@ -0,0 +1,14 @@
+# flags: --preview
+m2 = None if not isinstance(dist, Normal) else m** 2 + s * 2
+m3 = None if not isinstance(dist, Normal) else m ** 2 + s * 2
+m4 = None if not isinstance(dist, Normal) else m**2 + s * 2
+m5 = obj.method(another_obj.method()).attribute **2
+m6 = None if ... else m**2 + s**2
+
+
+# output
+m2 = None if not isinstance(dist, Normal) else m**2 + s * 2
+m3 = None if not isinstance(dist, Normal) else m**2 + s * 2
+m4 = None if not isinstance(dist, Normal) else m**2 + s * 2
+m5 = obj.method(another_obj.method()).attribute ** 2
+m6 = None if ... else m**2 + s**2
\ No newline at end of file

From dab37a6a1117d690d683121edc4d7c8fb8dd75a7 Mon Sep 17 00:00:00 2001
From: Logan Hunt <39638017+dosisod@users.noreply.github.com>
Date: Wed, 7 Feb 2024 06:55:02 -0800
Subject: [PATCH 1015/1034] Remove redundant parentheses in `case` statement
 `if` guards (#4214)

A follow up to #4024 but for `if` guards in `case` statements. I noticed this
when #4024 was made stable, and noticed I had some code that had extra parens
around the `if` guard.
---
 CHANGES.md                                    |   1 +
 docs/the_black_code_style/future_style.md     |   2 +
 src/black/linegen.py                          |   2 +
 src/black/mode.py                             |   1 +
 src/black/resources/black.schema.json         |   3 +-
 .../remove_redundant_parens_in_case_guard.py  | 114 ++++++++++++++++++
 6 files changed, 122 insertions(+), 1 deletion(-)
 create mode 100644 tests/data/cases/remove_redundant_parens_in_case_guard.py

diff --git a/CHANGES.md b/CHANGES.md
index 5d4858da811..3583348f377 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -20,6 +20,7 @@
   expression (#4154)
 - Checking for newline before adding one on docstring that is almost at the line limit
   (#4185)
+- Remove redundant parentheses in `case` statement `if` guards (#4214).
 
 ### Configuration
 
diff --git a/docs/the_black_code_style/future_style.md b/docs/the_black_code_style/future_style.md
index f4534680645..4ae46cecded 100644
--- a/docs/the_black_code_style/future_style.md
+++ b/docs/the_black_code_style/future_style.md
@@ -32,6 +32,8 @@ Currently, the following features are included in the preview style:
   expressions that involve the power operator
 - `docstring_check_for_newline`: checks if there is a newline before the terminating
   quotes of a docstring
+- `remove_redundant_guard_parens`: Removes redundant parentheses in `if` guards for
+  `case` blocks.
 
 (labels/unstable-features)=
 
diff --git a/src/black/linegen.py b/src/black/linegen.py
index c45a1308013..2b7fbc492cf 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -529,6 +529,8 @@ def __post_init__(self) -> None:
         # PEP 634
         self.visit_match_stmt = self.visit_match_case
         self.visit_case_block = self.visit_match_case
+        if Preview.remove_redundant_guard_parens in self.mode:
+            self.visit_guard = partial(v, keywords=Ø, parens={"if"})
 
 
 def _hugging_power_ops_line_to_string(
diff --git a/src/black/mode.py b/src/black/mode.py
index f9fad082e03..90c10c324a5 100644
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -179,6 +179,7 @@ class Preview(Enum):
     typed_params_trailing_comma = auto()
     is_simple_lookup_for_doublestar_expression = auto()
     docstring_check_for_newline = auto()
+    remove_redundant_guard_parens = auto()
 
 
 UNSTABLE_FEATURES: Set[Preview] = {
diff --git a/src/black/resources/black.schema.json b/src/black/resources/black.schema.json
index 04ddb32e087..8252a6c4bd8 100644
--- a/src/black/resources/black.schema.json
+++ b/src/black/resources/black.schema.json
@@ -87,7 +87,8 @@
           "multiline_string_handling",
           "typed_params_trailing_comma",
           "is_simple_lookup_for_doublestar_expression",
-          "docstring_check_for_newline"
+          "docstring_check_for_newline",
+          "remove_redundant_guard_parens"
         ]
       },
       "description": "Enable specific features included in the `--unstable` style. Requires `--preview`. No compatibility guarantees are provided on the behavior or existence of any unstable features."
diff --git a/tests/data/cases/remove_redundant_parens_in_case_guard.py b/tests/data/cases/remove_redundant_parens_in_case_guard.py
new file mode 100644
index 00000000000..bec4a3c3fcd
--- /dev/null
+++ b/tests/data/cases/remove_redundant_parens_in_case_guard.py
@@ -0,0 +1,114 @@
+# flags: --minimum-version=3.10 --preview --line-length=79
+
+match 1:
+    case _ if (True):
+        pass
+
+
+match 1:
+    case _ if (
+        True
+    ):
+        pass
+
+
+match 1:
+    case _ if (
+        # this is a comment
+        True
+    ):
+        pass
+
+
+match 1:
+    case _ if (
+        True
+        # this is a comment
+    ):
+        pass
+
+
+match 1:
+    case _ if (
+        True  # this is a comment
+    ):
+        pass
+
+
+match 1:
+    case _ if (  # this is a comment
+        True
+    ):
+        pass
+
+
+match 1:
+    case _ if (
+        True
+    ):  # this is a comment
+        pass
+
+
+match 1:
+    case _ if (True):  # comment over the line limit unless parens are removed x
+        pass
+
+
+match 1:
+    case _ if (True):  # comment over the line limit and parens should go to next line
+        pass
+
+
+# output
+
+match 1:
+    case _ if True:
+        pass
+
+
+match 1:
+    case _ if True:
+        pass
+
+
+match 1:
+    case _ if (
+        # this is a comment
+        True
+    ):
+        pass
+
+
+match 1:
+    case _ if (
+        True
+        # this is a comment
+    ):
+        pass
+
+
+match 1:
+    case _ if True:  # this is a comment
+        pass
+
+
+match 1:
+    case _ if True:  # this is a comment
+        pass
+
+
+match 1:
+    case _ if True:  # this is a comment
+        pass
+
+
+match 1:
+    case _ if True:  # comment over the line limit unless parens are removed x
+        pass
+
+
+match 1:
+    case (
+        _
+    ) if True:  # comment over the line limit and parens should go to next line
+        pass

From a20100395cf6179a81289452efad1d8e72b19682 Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Sat, 10 Feb 2024 23:55:01 -0800
Subject: [PATCH 1016/1034] Simplify check for symlinks that resolve outside
 root (#4221)

This PR does not change any behaviour.

There have been 1-2 issues about symlinks recently. Both over and under
resolving can cause problems. This makes a case where we resolve more
explicit and prevent a resolved path from leaking out via the return.
---
 src/black/__init__.py | 11 ++++-------
 src/black/files.py    | 25 +++++++++++--------------
 tests/test_black.py   | 11 +++++++----
 3 files changed, 22 insertions(+), 25 deletions(-)

diff --git a/src/black/__init__.py b/src/black/__init__.py
index 8ab5b47f974..2d4c7f655ad 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -50,9 +50,9 @@
     gen_python_files,
     get_gitignore,
     get_root_relative_path,
-    normalize_path_maybe_ignore,
     parse_pyproject_toml,
     path_is_excluded,
+    resolves_outside_root_or_cannot_stat,
     wrap_stream_for_windows,
 )
 from black.handle_ipynb_magics import (
@@ -763,12 +763,9 @@ def get_sources(
                 )
                 continue
 
-            normalized_path: Optional[str] = normalize_path_maybe_ignore(
-                path, root, report
-            )
-            if normalized_path is None:
+            if resolves_outside_root_or_cannot_stat(path, root, report):
                 if verbose:
-                    out(f'Skipping invalid source: "{normalized_path}"', fg="red")
+                    out(f'Skipping invalid source: "{path}"', fg="red")
                 continue
 
             if is_stdin:
@@ -780,7 +777,7 @@ def get_sources(
                 continue
 
             if verbose:
-                out(f'Found input source: "{normalized_path}"', fg="blue")
+                out(f'Found input source: "{path}"', fg="blue")
             sources.add(path)
         elif path.is_dir():
             path = root / (path.resolve().relative_to(root))
diff --git a/src/black/files.py b/src/black/files.py
index 960f13ee270..6c05105450c 100644
--- a/src/black/files.py
+++ b/src/black/files.py
@@ -254,26 +254,24 @@ def get_gitignore(root: Path) -> PathSpec:
         raise
 
 
-def normalize_path_maybe_ignore(
+def resolves_outside_root_or_cannot_stat(
     path: Path,
     root: Path,
     report: Optional[Report] = None,
-) -> Optional[str]:
-    """Normalize `path`. May return `None` if `path` was ignored.
-
-    `report` is where "path ignored" output goes.
+) -> bool:
+    """
+    Returns whether the path is a symbolic link that points outside the
+    root directory. Also returns True if we failed to resolve the path.
     """
     try:
-        abspath = path if path.is_absolute() else Path.cwd() / path
-        normalized_path = abspath.resolve()
-        root_relative_path = get_root_relative_path(normalized_path, root, report)
-
+        if sys.version_info < (3, 8, 6):
+            path = path.absolute()  # https://bugs.python.org/issue33660
+        resolved_path = path.resolve()
+        return get_root_relative_path(resolved_path, root, report) is None
     except OSError as e:
         if report:
             report.path_ignored(path, f"cannot be read because {e}")
-        return None
-
-    return root_relative_path
+        return True
 
 
 def get_root_relative_path(
@@ -369,8 +367,7 @@ def gen_python_files(
             report.path_ignored(child, "matches the --force-exclude regular expression")
             continue
 
-        normalized_path = normalize_path_maybe_ignore(child, root, report)
-        if normalized_path is None:
+        if resolves_outside_root_or_cannot_stat(child, root, report):
             continue
 
         if child.is_dir():
diff --git a/tests/test_black.py b/tests/test_black.py
index f876d365b12..5c6920c2b77 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -1760,12 +1760,15 @@ def test_bpo_33660_workaround(self) -> None:
             return
 
         # https://bugs.python.org/issue33660
+        # Can be removed when we drop support for Python 3.8.5
         root = Path("/")
         with change_directory(root):
             path = Path("workspace") / "project"
             report = black.Report(verbose=True)
-            normalized_path = black.normalize_path_maybe_ignore(path, root, report)
-            self.assertEqual(normalized_path, "workspace/project")
+            resolves_outside = black.resolves_outside_root_or_cannot_stat(
+                path, root, report
+            )
+            self.assertIs(resolves_outside, False)
 
     def test_normalize_path_ignore_windows_junctions_outside_of_root(self) -> None:
         if system() != "Windows":
@@ -1778,13 +1781,13 @@ def test_normalize_path_ignore_windows_junctions_outside_of_root(self) -> None:
             os.system(f"mklink /J {junction_dir} {junction_target_outside_of_root}")
 
             report = black.Report(verbose=True)
-            normalized_path = black.normalize_path_maybe_ignore(
+            resolves_outside = black.resolves_outside_root_or_cannot_stat(
                 junction_dir, root, report
             )
             # Manually delete for Python < 3.8
             os.system(f"rmdir {junction_dir}")
 
-            self.assertEqual(normalized_path, None)
+            self.assertIs(resolves_outside, True)
 
     def test_newline_comment_interaction(self) -> None:
         source = "class A:\\\r\n# type: ignore\n pass\n"

From 23dfc5b2c3b0694a8c27e58e28439591976aaf94 Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Mon, 12 Feb 2024 00:04:09 -0800
Subject: [PATCH 1017/1034] Fix ignoring input files for symlink reasons
 (#4222)

This relates to #4015, #4161 and the behaviour of os.getcwd()

Black is a big user of pathlib and as such loves doing `.resolve()`,
since for a long time it was the only good way of getting an absolute
path in pathlib. However, this has two problems:

The first minor problem is performance, e.g. in #3751 I (safely) got rid
of a bunch of `.resolve()` which made Black 40% faster on cached runs.

The second more important problem is that always resolving symlinks
results in unintuitive exclusion behaviour. For instance, a gitignored
symlink should never alter formatting of your actual code. This kind of
thing was reported by users a few times.

In #3846, I improved the exclusion rule logic for symlinks in
`gen_python_files` and everything was good.

But `gen_python_files` isn't enough, there's also `get_sources`, which
handles user specified paths directly (instead of files Black
discovers). So in #4015, I made a very similar change to #3846 for
`get_sources`, and this is where some problems began.

The core issue was the line:
```
root_relative_path = path.absolute().relative_to(root).as_posix()
```
The first issue is that despite root being computed from user inputs, we
call `.resolve()` while computing it (likely unecessarily). Which means
that `path` may not actually be relative to `root`. So I started off
this PR trying to fix that, when I ran into the second issue. Which is
that `os.getcwd()` (as called by `os.path.abspath` or `Path.absolute` or
`Path.cwd`) also often resolves symlinks!
```
>>> import os
>>> os.environ.get("PWD")
'/Users/shantanu/dev/black/symlink/bug'
>>> os.getcwd()
'/Users/shantanu/dev/black/actual/bug'
```
This also meant that the breakage often would not show up when input
relative paths.

This doesn't affect `gen_python_files` / #3846 because things are always
absolute and known to be relative to `root`.

Anyway, it looks like #4161 fixed the crash by just swallowing the error
and ignoring the file. Instead, we should just try to compute the actual
relative path. I think this PR should be quite safe, but we could also
consider reverting some of the previous changes; the associated issues
weren't too popular.

At the same time, I think there's still behaviour that can be improved
and I kind of want to make larger changes, but maybe I'll save that for
if we do something like #3952

Hopefully fixes #4205, fixes #4209, actual fix for #4077
---
 CHANGES.md            |   1 +
 src/black/__init__.py |  15 +++---
 src/black/files.py    |  44 ++++++++++------
 tests/test_black.py   | 120 ++++++++++++++++++++++++++++++++----------
 4 files changed, 127 insertions(+), 53 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 3583348f377..4fd63ac41eb 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -24,6 +24,7 @@
 
 ### Configuration
 
+- Fix issue where _Black_ would ignore input files in the presence of symlinks (#4222)
 - _Black_ now ignores `pyproject.toml` that is missing a `tool.black` section when
   discovering project root and configuration. Since _Black_ continues to use version
   control as an indicator of project root, this is expected to primarily change behavior
diff --git a/src/black/__init__.py b/src/black/__init__.py
index 2d4c7f655ad..f82b9fec5b7 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -44,12 +44,12 @@
     STDIN_PLACEHOLDER,
 )
 from black.files import (
+    best_effort_relative_path,
     find_project_root,
     find_pyproject_toml,
     find_user_pyproject_toml,
     gen_python_files,
     get_gitignore,
-    get_root_relative_path,
     parse_pyproject_toml,
     path_is_excluded,
     resolves_outside_root_or_cannot_stat,
@@ -734,6 +734,7 @@ def get_sources(
     """Compute the set of files to be formatted."""
     sources: Set[Path] = set()
 
+    assert root.is_absolute(), f"INTERNAL ERROR: `root` must be absolute but is {root}"
     using_default_exclude = exclude is None
     exclude = re_compile_maybe_verbose(DEFAULT_EXCLUDES) if exclude is None else exclude
     gitignore: Optional[Dict[Path, PathSpec]] = None
@@ -749,11 +750,12 @@ def get_sources(
 
         # Compare the logic here to the logic in `gen_python_files`.
         if is_stdin or path.is_file():
-            root_relative_path = get_root_relative_path(path, root, report)
-
-            if root_relative_path is None:
+            if resolves_outside_root_or_cannot_stat(path, root, report):
+                if verbose:
+                    out(f'Skipping invalid source: "{path}"', fg="red")
                 continue
 
+            root_relative_path = best_effort_relative_path(path, root).as_posix()
             root_relative_path = "/" + root_relative_path
 
             # Hard-exclude any files that matches the `--force-exclude` regex.
@@ -763,11 +765,6 @@ def get_sources(
                 )
                 continue
 
-            if resolves_outside_root_or_cannot_stat(path, root, report):
-                if verbose:
-                    out(f'Skipping invalid source: "{path}"', fg="red")
-                continue
-
             if is_stdin:
                 path = Path(f"{STDIN_PLACEHOLDER}{str(path)}")
 
diff --git a/src/black/files.py b/src/black/files.py
index 6c05105450c..c0cadbfd890 100644
--- a/src/black/files.py
+++ b/src/black/files.py
@@ -48,6 +48,11 @@ def _load_toml(path: Union[Path, str]) -> Dict[str, Any]:
         return tomllib.load(f)
 
 
+@lru_cache
+def _cached_resolve(path: Path) -> Path:
+    return path.resolve()
+
+
 @lru_cache
 def find_project_root(
     srcs: Sequence[str], stdin_filename: Optional[str] = None
@@ -67,9 +72,9 @@ def find_project_root(
     if stdin_filename is not None:
         srcs = tuple(stdin_filename if s == "-" else s for s in srcs)
     if not srcs:
-        srcs = [str(Path.cwd().resolve())]
+        srcs = [str(_cached_resolve(Path.cwd()))]
 
-    path_srcs = [Path(Path.cwd(), src).resolve() for src in srcs]
+    path_srcs = [_cached_resolve(Path(Path.cwd(), src)) for src in srcs]
 
     # A list of lists of parents for each 'src'. 'src' is included as a
     # "parent" of itself if it is a directory
@@ -236,7 +241,7 @@ def find_user_pyproject_toml() -> Path:
     else:
         config_root = os.environ.get("XDG_CONFIG_HOME", "~/.config")
         user_config_path = Path(config_root).expanduser() / "black"
-    return user_config_path.resolve()
+    return _cached_resolve(user_config_path)
 
 
 @lru_cache
@@ -266,27 +271,31 @@ def resolves_outside_root_or_cannot_stat(
     try:
         if sys.version_info < (3, 8, 6):
             path = path.absolute()  # https://bugs.python.org/issue33660
-        resolved_path = path.resolve()
-        return get_root_relative_path(resolved_path, root, report) is None
+        resolved_path = _cached_resolve(path)
     except OSError as e:
         if report:
             report.path_ignored(path, f"cannot be read because {e}")
         return True
-
-
-def get_root_relative_path(
-    path: Path,
-    root: Path,
-    report: Optional[Report] = None,
-) -> Optional[str]:
-    """Returns the file path relative to the 'root' directory"""
     try:
-        root_relative_path = path.absolute().relative_to(root).as_posix()
+        resolved_path.relative_to(root)
     except ValueError:
         if report:
             report.path_ignored(path, f"is a symbolic link that points outside {root}")
-        return None
-    return root_relative_path
+        return True
+    return False
+
+
+def best_effort_relative_path(path: Path, root: Path) -> Path:
+    # Precondition: resolves_outside_root_or_cannot_stat(path, root) is False
+    try:
+        return path.absolute().relative_to(root)
+    except ValueError:
+        pass
+    root_parent = next((p for p in path.parents if _cached_resolve(p) == root), None)
+    if root_parent is not None:
+        return path.relative_to(root_parent)
+    # something adversarial, fallback to path guaranteed by precondition
+    return _cached_resolve(path).relative_to(root)
 
 
 def _path_is_ignored(
@@ -339,7 +348,8 @@ def gen_python_files(
 
     assert root.is_absolute(), f"INTERNAL ERROR: `root` must be absolute but is {root}"
     for child in paths:
-        root_relative_path = child.absolute().relative_to(root).as_posix()
+        assert child.is_absolute()
+        root_relative_path = child.relative_to(root).as_posix()
 
         # First ignore files matching .gitignore, if passed
         if gitignore_dict and _path_is_ignored(
diff --git a/tests/test_black.py b/tests/test_black.py
index 5c6920c2b77..41f87cd16f8 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -2567,32 +2567,32 @@ def test_symlinks(self) -> None:
         gitignore = PathSpec.from_lines("gitwildmatch", [])
 
         regular = MagicMock()
-        regular.absolute.return_value = root / "regular.py"
+        regular.relative_to.return_value = Path("regular.py")
         regular.resolve.return_value = root / "regular.py"
         regular.is_dir.return_value = False
         regular.is_file.return_value = True
 
         outside_root_symlink = MagicMock()
-        outside_root_symlink.absolute.return_value = root / "symlink.py"
+        outside_root_symlink.relative_to.return_value = Path("symlink.py")
         outside_root_symlink.resolve.return_value = Path("/nowhere")
         outside_root_symlink.is_dir.return_value = False
         outside_root_symlink.is_file.return_value = True
 
         ignored_symlink = MagicMock()
-        ignored_symlink.absolute.return_value = root / ".mypy_cache" / "symlink.py"
+        ignored_symlink.relative_to.return_value = Path(".mypy_cache") / "symlink.py"
         ignored_symlink.is_dir.return_value = False
         ignored_symlink.is_file.return_value = True
 
         # A symlink that has an excluded name, but points to an included name
         symlink_excluded_name = MagicMock()
-        symlink_excluded_name.absolute.return_value = root / "excluded_name"
+        symlink_excluded_name.relative_to.return_value = Path("excluded_name")
         symlink_excluded_name.resolve.return_value = root / "included_name.py"
         symlink_excluded_name.is_dir.return_value = False
         symlink_excluded_name.is_file.return_value = True
 
         # A symlink that has an included name, but points to an excluded name
         symlink_included_name = MagicMock()
-        symlink_included_name.absolute.return_value = root / "included_name.py"
+        symlink_included_name.relative_to.return_value = Path("included_name.py")
         symlink_included_name.resolve.return_value = root / "excluded_name"
         symlink_included_name.is_dir.return_value = False
         symlink_included_name.is_file.return_value = True
@@ -2626,39 +2626,100 @@ def test_symlinks(self) -> None:
         outside_root_symlink.resolve.assert_called_once()
         ignored_symlink.resolve.assert_not_called()
 
+    def test_get_sources_symlink_and_force_exclude(self) -> None:
+        with TemporaryDirectory() as tempdir:
+            tmp = Path(tempdir).resolve()
+            actual = tmp / "actual"
+            actual.mkdir()
+            symlink = tmp / "symlink"
+            symlink.symlink_to(actual)
+
+            actual_proj = actual / "project"
+            actual_proj.mkdir()
+            (actual_proj / "module.py").write_text("print('hello')", encoding="utf-8")
+
+            symlink_proj = symlink / "project"
+
+            with change_directory(symlink_proj):
+                assert_collected_sources(
+                    src=["module.py"],
+                    root=symlink_proj.resolve(),
+                    expected=["module.py"],
+                )
+
+                absolute_module = symlink_proj / "module.py"
+                assert_collected_sources(
+                    src=[absolute_module],
+                    root=symlink_proj.resolve(),
+                    expected=[absolute_module],
+                )
+
+                # a few tricky tests for force_exclude
+                flat_symlink = symlink_proj / "symlink_module.py"
+                flat_symlink.symlink_to(actual_proj / "module.py")
+                assert_collected_sources(
+                    src=[flat_symlink],
+                    root=symlink_proj.resolve(),
+                    force_exclude=r"/symlink_module.py",
+                    expected=[],
+                )
+
+                target = actual_proj / "target"
+                target.mkdir()
+                (target / "another.py").write_text("print('hello')", encoding="utf-8")
+                (symlink_proj / "nested").symlink_to(target)
+
+                assert_collected_sources(
+                    src=[symlink_proj / "nested" / "another.py"],
+                    root=symlink_proj.resolve(),
+                    force_exclude=r"nested",
+                    expected=[],
+                )
+                assert_collected_sources(
+                    src=[symlink_proj / "nested" / "another.py"],
+                    root=symlink_proj.resolve(),
+                    force_exclude=r"target",
+                    expected=[symlink_proj / "nested" / "another.py"],
+                )
+
     def test_get_sources_with_stdin_symlink_outside_root(
         self,
     ) -> None:
         path = THIS_DIR / "data" / "include_exclude_tests"
         stdin_filename = str(path / "b/exclude/a.py")
         outside_root_symlink = Path("/target_directory/a.py")
+        root = Path("target_dir/").resolve().absolute()
         with patch("pathlib.Path.resolve", return_value=outside_root_symlink):
             assert_collected_sources(
-                root=Path("target_directory/"),
+                root=root,
                 src=["-"],
                 expected=[],
                 stdin_filename=stdin_filename,
             )
 
-    @patch("black.find_project_root", lambda *args: (THIS_DIR.resolve(), None))
     def test_get_sources_with_stdin(self) -> None:
         src = ["-"]
         expected = ["-"]
-        assert_collected_sources(src, expected, include="", exclude=r"/exclude/|a\.py")
+        assert_collected_sources(
+            src,
+            root=THIS_DIR.resolve(),
+            expected=expected,
+            include="",
+            exclude=r"/exclude/|a\.py",
+        )
 
-    @patch("black.find_project_root", lambda *args: (THIS_DIR.resolve(), None))
     def test_get_sources_with_stdin_filename(self) -> None:
         src = ["-"]
         stdin_filename = str(THIS_DIR / "data/collections.py")
         expected = [f"__BLACK_STDIN_FILENAME__{stdin_filename}"]
         assert_collected_sources(
             src,
-            expected,
+            root=THIS_DIR.resolve(),
+            expected=expected,
             exclude=r"/exclude/a\.py",
             stdin_filename=stdin_filename,
         )
 
-    @patch("black.find_project_root", lambda *args: (THIS_DIR.resolve(), None))
     def test_get_sources_with_stdin_filename_and_exclude(self) -> None:
         # Exclude shouldn't exclude stdin_filename since it is mimicking the
         # file being passed directly. This is the same as
@@ -2669,12 +2730,12 @@ def test_get_sources_with_stdin_filename_and_exclude(self) -> None:
         expected = [f"__BLACK_STDIN_FILENAME__{stdin_filename}"]
         assert_collected_sources(
             src,
-            expected,
+            root=THIS_DIR.resolve(),
+            expected=expected,
             exclude=r"/exclude/|a\.py",
             stdin_filename=stdin_filename,
         )
 
-    @patch("black.find_project_root", lambda *args: (THIS_DIR.resolve(), None))
     def test_get_sources_with_stdin_filename_and_extend_exclude(self) -> None:
         # Extend exclude shouldn't exclude stdin_filename since it is mimicking the
         # file being passed directly. This is the same as
@@ -2685,12 +2746,12 @@ def test_get_sources_with_stdin_filename_and_extend_exclude(self) -> None:
         expected = [f"__BLACK_STDIN_FILENAME__{stdin_filename}"]
         assert_collected_sources(
             src,
-            expected,
+            root=THIS_DIR.resolve(),
+            expected=expected,
             extend_exclude=r"/exclude/|a\.py",
             stdin_filename=stdin_filename,
         )
 
-    @patch("black.find_project_root", lambda *args: (THIS_DIR.resolve(), None))
     def test_get_sources_with_stdin_filename_and_force_exclude(self) -> None:
         # Force exclude should exclude the file when passing it through
         # stdin_filename
@@ -2698,27 +2759,32 @@ def test_get_sources_with_stdin_filename_and_force_exclude(self) -> None:
         stdin_filename = str(path / "b/exclude/a.py")
         assert_collected_sources(
             src=["-"],
+            root=THIS_DIR.resolve(),
             expected=[],
             force_exclude=r"/exclude/|a\.py",
             stdin_filename=stdin_filename,
         )
 
-    @patch("black.find_project_root", lambda *args: (THIS_DIR.resolve(), None))
     def test_get_sources_with_stdin_filename_and_force_exclude_and_symlink(
         self,
     ) -> None:
         # Force exclude should exclude a symlink based on the symlink, not its target
-        path = THIS_DIR / "data" / "include_exclude_tests"
-        stdin_filename = str(path / "symlink.py")
-        expected = [f"__BLACK_STDIN_FILENAME__{stdin_filename}"]
-        target = path / "b/exclude/a.py"
-        with patch("pathlib.Path.resolve", return_value=target):
-            assert_collected_sources(
-                src=["-"],
-                expected=expected,
-                force_exclude=r"exclude/a\.py",
-                stdin_filename=stdin_filename,
-            )
+        with TemporaryDirectory() as tempdir:
+            tmp = Path(tempdir).resolve()
+            (tmp / "exclude").mkdir()
+            (tmp / "exclude" / "a.py").write_text("print('hello')", encoding="utf-8")
+            (tmp / "symlink.py").symlink_to(tmp / "exclude" / "a.py")
+
+            stdin_filename = str(tmp / "symlink.py")
+            expected = [f"__BLACK_STDIN_FILENAME__{stdin_filename}"]
+            with change_directory(tmp):
+                assert_collected_sources(
+                    src=["-"],
+                    root=tmp,
+                    expected=expected,
+                    force_exclude=r"exclude/a\.py",
+                    stdin_filename=stdin_filename,
+                )
 
 
 class TestDeFactoAPI:

From 35e97769190d8c8fe94d9ea2d70d7d88b22a2642 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 12 Feb 2024 06:19:25 -0800
Subject: [PATCH 1018/1034] Bump pre-commit/action from 3.0.0 to 3.0.1 (#4225)

Bumps [pre-commit/action](https://github.com/pre-commit/action) from 3.0.0 to 3.0.1.
- [Release notes](https://github.com/pre-commit/action/releases)
- [Commits](https://github.com/pre-commit/action/compare/v3.0.0...v3.0.1)

---
updated-dependencies:
- dependency-name: pre-commit/action
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/lint.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index 8cb335bffb5..f75734400ce 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -35,7 +35,7 @@ jobs:
           python -m pip install tox
 
       - name: Run pre-commit hooks
-        uses: pre-commit/action@v3.0.0
+        uses: pre-commit/action@v3.0.1
 
       - name: Format ourselves
         run: |

From 8af439407c051d55f3221cc93795d20bd9af49c9 Mon Sep 17 00:00:00 2001
From: cobalt <61329810+RedGuy12@users.noreply.github.com>
Date: Mon, 12 Feb 2024 08:27:50 -0600
Subject: [PATCH 1019/1034] fix: Don't remove comments along with parens
 (#4218)

Signed-off-by: RedGuy12 <61329810+RedGuy12@users.noreply.github.com>
---
 CHANGES.md                                    |   3 +
 src/black/linegen.py                          |   6 +
 tests/data/cases/comments_in_double_parens.py | 113 ++++++++++++++++++
 3 files changed, 122 insertions(+)
 create mode 100644 tests/data/cases/comments_in_double_parens.py

diff --git a/CHANGES.md b/CHANGES.md
index 4fd63ac41eb..b1a6ae3bc1c 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -10,6 +10,9 @@
 
 <!-- Changes that affect Black's stable style -->
 
+- Fixed a bug where comments where mistakenly removed along with redundant parentheses
+  (#4218)
+
 ### Preview style
 
 <!-- Changes that affect Black's preview style -->
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 2b7fbc492cf..cc8e41dfb20 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -1553,6 +1553,9 @@ def maybe_make_parens_invisible_in_atom(
             not is_type_ignore_comment_string(middle.prefix.strip())
         ):
             first.value = ""
+            if first.prefix.strip():
+                # Preserve comments before first paren
+                middle.prefix = first.prefix + middle.prefix
             last.value = ""
         maybe_make_parens_invisible_in_atom(
             middle,
@@ -1564,6 +1567,9 @@ def maybe_make_parens_invisible_in_atom(
             # Strip the invisible parens from `middle` by replacing
             # it with the child in-between the invisible parens
             middle.replace(middle.children[1])
+            if middle.children[-1].prefix.strip():
+                # Preserve comments before last paren
+                last.prefix = middle.children[-1].prefix + last.prefix
 
         return False
 
diff --git a/tests/data/cases/comments_in_double_parens.py b/tests/data/cases/comments_in_double_parens.py
new file mode 100644
index 00000000000..80e7a5e5bf5
--- /dev/null
+++ b/tests/data/cases/comments_in_double_parens.py
@@ -0,0 +1,113 @@
+if (
+    True
+    # sdf
+):
+    print("hw")
+
+if ((
+    True
+    # sdf
+)):
+    print("hw")
+
+if ((
+    # type: ignore
+    True
+)):
+    print("hw")
+
+if ((
+    True
+    # type: ignore
+)):
+    print("hw")
+
+if (
+    # a long comment about
+    # the condition below
+    (a or b)
+):
+    pass
+
+def return_true():
+    return (
+        (
+            True  # this comment gets removed accidentally
+        )
+    )
+
+def return_true():
+    return (True)  # this comment gets removed accidentally
+
+
+if (
+    # huh comment
+    (True)
+):
+    ...
+
+if (
+    # huh
+    (
+        # comment
+        True
+    )
+):
+    ...
+
+
+# output
+
+if (
+    True
+    # sdf
+):
+    print("hw")
+
+if (
+    True
+    # sdf
+):
+    print("hw")
+
+if (
+    # type: ignore
+    True
+):
+    print("hw")
+
+if (
+    True
+    # type: ignore
+):
+    print("hw")
+
+if (
+    # a long comment about
+    # the condition below
+    a
+    or b
+):
+    pass
+
+
+def return_true():
+    return True  # this comment gets removed accidentally
+
+
+def return_true():
+    return True  # this comment gets removed accidentally
+
+
+if (
+    # huh comment
+    True
+):
+    ...
+
+if (
+    # huh
+    # comment
+    True
+):
+    ...

From 6fdf8a4af28071ed1d079c01122b34c5d587207a Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Mon, 12 Feb 2024 12:11:15 -0800
Subject: [PATCH 1020/1034] Prepare release 24.2.0 (#4226)

---
 CHANGES.md                                  | 35 +--------------------
 docs/integrations/source_version_control.md |  4 +--
 docs/usage_and_configuration/the_basics.md  |  6 ++--
 3 files changed, 6 insertions(+), 39 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index b1a6ae3bc1c..39191c1cd82 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,22 +1,14 @@
 # Change Log
 
-## Unreleased
-
-### Highlights
-
-<!-- Include any especially major or disruptive changes here -->
+## 24.2.0
 
 ### Stable style
 
-<!-- Changes that affect Black's stable style -->
-
 - Fixed a bug where comments where mistakenly removed along with redundant parentheses
   (#4218)
 
 ### Preview style
 
-<!-- Changes that affect Black's preview style -->
-
 - Move the `hug_parens_with_braces_and_square_brackets` feature to the unstable style
   due to an outstanding crash and proposed formatting tweaks (#4198)
 - Fixed a bug where base expressions caused inconsistent formatting of \*\* in tenary
@@ -35,40 +27,15 @@
   simply add an empty `[tool.black]` to the previously discovered `pyproject.toml`
   (#4204)
 
-### Packaging
-
-<!-- Changes to how Black is packaged, such as dependency requirements -->
-
-### Parser
-
-<!-- Changes to the parser or to version autodetection -->
-
-### Performance
-
-<!-- Changes that improve Black's performance. -->
-
 ### Output
 
-<!-- Changes to Black's terminal output and error messages -->
-
 - Black will swallow any `SyntaxWarning`s or `DeprecationWarning`s produced by the `ast`
   module when performing equivalence checks (#4189)
 
-### _Blackd_
-
-<!-- Changes to blackd -->
-
 ### Integrations
 
-<!-- For example, Docker, GitHub Actions, pre-commit, editors -->
-
 - Add a JSONSchema and provide a validate-pyproject entry-point (#4181)
 
-### Documentation
-
-<!-- Major changes to documentation and policies. Small docs changes
-     don't need a changelog entry. -->
-
 ## 24.1.1
 
 Bugfix release to fix a bug that made Black unusable on certain file systems with strict
diff --git a/docs/integrations/source_version_control.md b/docs/integrations/source_version_control.md
index 92279707d84..f24043026fa 100644
--- a/docs/integrations/source_version_control.md
+++ b/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.1.1
+    rev: 24.2.0
     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.1.1
+    rev: 24.2.0
     hooks:
       - id: black-jupyter
         # It is recommended to specify the latest version of Python
diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index 61c52450165..ea7a2dae5ce 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -266,8 +266,8 @@ configuration file for consistent results across environments.
 
 ```console
 $ black --version
-black, 24.1.1 (compiled: yes)
-$ black --required-version 24.1.1 -c "format = 'this'"
+black, 24.2.0 (compiled: yes)
+$ black --required-version 24.2.0 -c "format = 'this'"
 format = "this"
 $ black --required-version 31.5b2 -c "still = 'beta?!'"
 Oh no! 💥 💔 💥 The required version does not match the running version!
@@ -363,7 +363,7 @@ You can check the version of _Black_ you have installed using the `--version` fl
 
 ```console
 $ black --version
-black, 24.1.1
+black, 24.2.0
 ```
 
 #### `--config`

From d1d4fc58d3b744db35ac832cddf1d076ba5f5e7f Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Mon, 12 Feb 2024 12:46:16 -0800
Subject: [PATCH 1021/1034] Add new release template (#4228)

---
 CHANGES.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/CHANGES.md b/CHANGES.md
index 39191c1cd82..bcf6eb44fdb 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,5 +1,52 @@
 # Change Log
 
+## Unreleased
+
+### Highlights
+
+<!-- Include any especially major or disruptive changes here -->
+
+### Stable style
+
+<!-- Changes that affect Black's stable style -->
+
+### Preview style
+
+<!-- Changes that affect Black's preview style -->
+
+### Configuration
+
+<!-- Changes to how Black can be configured -->
+
+### Packaging
+
+<!-- Changes to how Black is packaged, such as dependency requirements -->
+
+### Parser
+
+<!-- Changes to the parser or to version autodetection -->
+
+### Performance
+
+<!-- Changes that improve Black's performance. -->
+
+### Output
+
+<!-- Changes to Black's terminal output and error messages -->
+
+### _Blackd_
+
+<!-- Changes to blackd -->
+
+### Integrations
+
+<!-- For example, Docker, GitHub Actions, pre-commit, editors -->
+
+### Documentation
+
+<!-- Major changes to documentation and policies. Small docs changes
+     don't need a changelog entry. -->
+
 ## 24.2.0
 
 ### Stable style

From ea66d40dd7f1eaa20256e6fccaf6d7b853ccc541 Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Sun, 25 Feb 2024 16:36:52 -0800
Subject: [PATCH 1022/1034] Update empty line documentation (#4239)

Reflects status quo following #4043

Fixes #4238
---
 docs/the_black_code_style/current_style.md | 39 +++++++++-------------
 1 file changed, 15 insertions(+), 24 deletions(-)

diff --git a/docs/the_black_code_style/current_style.md b/docs/the_black_code_style/current_style.md
index 586c79074af..68cd6175e3e 100644
--- a/docs/the_black_code_style/current_style.md
+++ b/docs/the_black_code_style/current_style.md
@@ -166,44 +166,35 @@ that in-function vertical whitespace should only be used sparingly.
 _Black_ will allow single empty lines inside functions, and single and double empty
 lines on module level left by the original editors, except when they're within
 parenthesized expressions. Since such expressions are always reformatted to fit minimal
-space, this whitespace is lost. The other exception is that it will remove any empty
-lines immediately following a statement that introduces a new indentation level.
+space, this whitespace is lost.
 
 ```python
 # in:
 
-def foo():
+def function(
+    some_argument: int,
 
-    print("All the newlines above me should be deleted!")
+    other_argument: int = 5,
+) -> EmptyLineInParenWillBeDeleted:
 
 
-if condition:
 
-    print("No newline above me!")
-
-    print("There is a newline above me, and that's OK!")
-
-
-class Point:
-
-    x: int
-    y: int
+    print("One empty line above me will be kept!")
 
+def this_is_okay_too():
+    print("No empty line here")
 # out:
 
-def foo():
-    print("All the newlines above me should be deleted!")
-
-
-if condition:
-    print("No newline above me!")
+def function(
+    some_argument: int,
+    other_argument: int = 5,
+) -> EmptyLineInParenWillBeDeleted:
 
-    print("There is a newline above me, and that's OK!")
+    print("One empty line above me will be kept!")
 
 
-class Point:
-    x: int
-    y: int
+def this_is_okay_too():
+    print("No empty line here")
 ```
 
 It will also insert proper spacing before and after function definitions. It's one line

From 899002399a26348198612503ce6ca2fc298551a6 Mon Sep 17 00:00:00 2001
From: Victorien <65306057+Viicos@users.noreply.github.com>
Date: Mon, 26 Feb 2024 16:49:39 +0100
Subject: [PATCH 1023/1034] Remove usage of `pkg_resources` in `docs/conf.py`
 (#4251)

---
 docs/conf.py | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py
index 52a849d06a4..c352f98da82 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -15,10 +15,9 @@
 
 import os
 import string
+from importlib.metadata import version
 from pathlib import Path
 
-from pkg_resources import get_distribution
-
 CURRENT_DIR = Path(__file__).parent
 
 
@@ -43,7 +42,7 @@ def make_pypi_svg(version: str) -> None:
 
 # Autopopulate version
 # The version, including alpha/beta/rc tags, but not commit hash and datestamps
-release = get_distribution("black").version.split("+")[0]
+release = version("black").split("+")[0]
 # The short X.Y version.
 version = release
 for sp in "abcfr":

From 0f18001abfe50b078317395e77508b151e271624 Mon Sep 17 00:00:00 2001
From: cobalt <61329810+RedGuy12@users.noreply.github.com>
Date: Wed, 28 Feb 2024 10:27:57 -0600
Subject: [PATCH 1024/1034] chore: Refactor `delimiter_split()` (#4257)

Signed-off-by: RedGuy12 <61329810+RedGuy12@users.noreply.github.com>
---
 src/black/linegen.py | 33 ++++++++++++++++++---------------
 1 file changed, 18 insertions(+), 15 deletions(-)

diff --git a/src/black/linegen.py b/src/black/linegen.py
index cc8e41dfb20..dea36d5a5d8 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -1135,6 +1135,14 @@ def _get_last_non_comment_leaf(line: Line) -> Optional[int]:
     return None
 
 
+def _can_add_trailing_comma(leaf: Leaf, features: Collection[Feature]) -> bool:
+    if is_vararg(leaf, within={syms.typedargslist}):
+        return Feature.TRAILING_COMMA_IN_DEF in features
+    if is_vararg(leaf, within={syms.arglist, syms.argument}):
+        return Feature.TRAILING_COMMA_IN_CALL in features
+    return True
+
+
 def _safe_add_trailing_comma(safe: bool, delimiter_priority: int, line: Line) -> Line:
     if (
         safe
@@ -1156,10 +1164,9 @@ def delimiter_split(
     If the appropriate Features are given, the split will add trailing commas
     also in function signatures and calls that contain `*` and `**`.
     """
-    try:
-        last_leaf = line.leaves[-1]
-    except IndexError:
+    if len(line.leaves) == 0:
         raise CannotSplit("Line empty") from None
+    last_leaf = line.leaves[-1]
 
     bt = line.bracket_tracker
     try:
@@ -1167,9 +1174,11 @@ def delimiter_split(
     except ValueError:
         raise CannotSplit("No delimiters found") from None
 
-    if delimiter_priority == DOT_PRIORITY:
-        if bt.delimiter_count_with_priority(delimiter_priority) == 1:
-            raise CannotSplit("Splitting a single attribute from its owner looks wrong")
+    if (
+        delimiter_priority == DOT_PRIORITY
+        and bt.delimiter_count_with_priority(delimiter_priority) == 1
+    ):
+        raise CannotSplit("Splitting a single attribute from its owner looks wrong")
 
     current_line = Line(
         mode=line.mode, depth=line.depth, inside_brackets=line.inside_brackets
@@ -1198,15 +1207,8 @@ def append_to_line(leaf: Leaf) -> Iterator[Line]:
             yield from append_to_line(comment_after)
 
         lowest_depth = min(lowest_depth, leaf.bracket_depth)
-        if leaf.bracket_depth == lowest_depth:
-            if is_vararg(leaf, within={syms.typedargslist}):
-                trailing_comma_safe = (
-                    trailing_comma_safe and Feature.TRAILING_COMMA_IN_DEF in features
-                )
-            elif is_vararg(leaf, within={syms.arglist, syms.argument}):
-                trailing_comma_safe = (
-                    trailing_comma_safe and Feature.TRAILING_COMMA_IN_CALL in features
-                )
+        if trailing_comma_safe and leaf.bracket_depth == lowest_depth:
+            trailing_comma_safe = _can_add_trailing_comma(leaf, features)
 
         if last_leaf.type == STANDALONE_COMMENT and leaf_idx == last_non_comment_leaf:
             current_line = _safe_add_trailing_comma(
@@ -1220,6 +1222,7 @@ def append_to_line(leaf: Leaf) -> Iterator[Line]:
             current_line = Line(
                 mode=line.mode, depth=line.depth, inside_brackets=line.inside_brackets
             )
+
     if current_line:
         current_line = _safe_add_trailing_comma(
             trailing_comma_safe, delimiter_priority, current_line

From d0287e1f7558d97e6c0ebd6dc5bcb5b970e2bf8c Mon Sep 17 00:00:00 2001
From: cobalt <61329810+RedGuy12@users.noreply.github.com>
Date: Wed, 28 Feb 2024 15:20:46 -0600
Subject: [PATCH 1025/1034] Make trailing comma logic more concise (#4202)

Signed-off-by: RedGuy12 <61329810+RedGuy12@users.noreply.github.com>
---
 src/black/linegen.py | 26 +++++++-------------------
 src/black/nodes.py   | 28 ++++++++++++++++++++++------
 2 files changed, 29 insertions(+), 25 deletions(-)

diff --git a/src/black/linegen.py b/src/black/linegen.py
index dea36d5a5d8..4b0dc57d544 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -31,12 +31,12 @@
     BRACKETS,
     CLOSING_BRACKETS,
     OPENING_BRACKETS,
-    RARROW,
     STANDALONE_COMMENT,
     STATEMENT,
     WHITESPACE,
     Visitor,
     ensure_visible,
+    get_annotation_type,
     is_arith_like,
     is_async_stmt_or_funcdef,
     is_atom_with_invisible_parens,
@@ -1046,11 +1046,12 @@ def bracket_split_build_line(
         result.inside_brackets = True
         result.depth += 1
         if leaves:
-            # Ensure a trailing comma for imports and standalone function arguments, but
-            # be careful not to add one after any comments or within type annotations.
             no_commas = (
+                # Ensure a trailing comma for imports and standalone function arguments
                 original.is_def
+                # Don't add one after any comments or within type annotations
                 and opening_bracket.value == "("
+                # Don't add one if there's already one there
                 and not any(
                     leaf.type == token.COMMA
                     and (
@@ -1059,22 +1060,9 @@ def bracket_split_build_line(
                     )
                     for leaf in leaves
                 )
-                # In particular, don't add one within a parenthesized return annotation.
-                # Unfortunately the indicator we're in a return annotation (RARROW) may
-                # be defined directly in the parent node, the parent of the parent ...
-                # and so on depending on how complex the return annotation is.
-                # This isn't perfect and there's some false negatives but they are in
-                # contexts were a comma is actually fine.
-                and not any(
-                    node.prev_sibling.type == RARROW
-                    for node in (
-                        leaves[0].parent,
-                        getattr(leaves[0].parent, "parent", None),
-                    )
-                    if isinstance(node, Node) and isinstance(node.prev_sibling, Leaf)
-                )
-                # Except the false negatives above for PEP 604 unions where we
-                # can't add the comma.
+                # Don't add one inside parenthesized return annotations
+                and get_annotation_type(leaves[0]) != "return"
+                # Don't add one inside PEP 604 unions
                 and not (
                     leaves[0].parent
                     and leaves[0].parent.next_sibling
diff --git a/src/black/nodes.py b/src/black/nodes.py
index a8869cba234..c0dca6e5783 100644
--- a/src/black/nodes.py
+++ b/src/black/nodes.py
@@ -3,7 +3,18 @@
 """
 
 import sys
-from typing import Final, Generic, Iterator, List, Optional, Set, Tuple, TypeVar, Union
+from typing import (
+    Final,
+    Generic,
+    Iterator,
+    List,
+    Literal,
+    Optional,
+    Set,
+    Tuple,
+    TypeVar,
+    Union,
+)
 
 if sys.version_info >= (3, 10):
     from typing import TypeGuard
@@ -951,16 +962,21 @@ def is_number_token(nl: NL) -> TypeGuard[Leaf]:
     return nl.type == token.NUMBER
 
 
-def is_part_of_annotation(leaf: Leaf) -> bool:
-    """Returns whether this leaf is part of type annotations."""
+def get_annotation_type(leaf: Leaf) -> Literal["return", "param", None]:
+    """Returns the type of annotation this leaf is part of, if any."""
     ancestor = leaf.parent
     while ancestor is not None:
         if ancestor.prev_sibling and ancestor.prev_sibling.type == token.RARROW:
-            return True
+            return "return"
         if ancestor.parent and ancestor.parent.type == syms.tname:
-            return True
+            return "param"
         ancestor = ancestor.parent
-    return False
+    return None
+
+
+def is_part_of_annotation(leaf: Leaf) -> bool:
+    """Returns whether this leaf is part of a type annotation."""
+    return get_annotation_type(leaf) is not None
 
 
 def first_leaf(node: LN) -> Optional[Leaf]:

From e4bfedbec2e8b10cc6b7b31442478f05db0ce06d Mon Sep 17 00:00:00 2001
From: cobalt <61329810+RedGuy12@users.noreply.github.com>
Date: Fri, 1 Mar 2024 09:02:56 -0600
Subject: [PATCH 1026/1034] fix: Don't move comments while splitting delimiters
 (#4248)

Signed-off-by: RedGuy12 <61329810+RedGuy12@users.noreply.github.com>
---
 CHANGES.md                                   |  2 +
 src/black/linegen.py                         | 25 ++++++++--
 tests/data/cases/split_delimiter_comments.py | 51 ++++++++++++++++++++
 3 files changed, 75 insertions(+), 3 deletions(-)
 create mode 100644 tests/data/cases/split_delimiter_comments.py

diff --git a/CHANGES.md b/CHANGES.md
index bcf6eb44fdb..e28730a3b5f 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -10,6 +10,8 @@
 
 <!-- Changes that affect Black's stable style -->
 
+- Don't move comments along with delimiters, which could cause crashes (#4248)
+
 ### Preview style
 
 <!-- Changes that affect Black's preview style -->
diff --git a/src/black/linegen.py b/src/black/linegen.py
index 4b0dc57d544..e34ff040c73 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -12,6 +12,7 @@
 from black.brackets import (
     COMMA_PRIORITY,
     DOT_PRIORITY,
+    STRING_PRIORITY,
     get_leaves_inside_matching_brackets,
     max_delimiter_priority_in_atom,
 )
@@ -1143,6 +1144,9 @@ def _safe_add_trailing_comma(safe: bool, delimiter_priority: int, line: Line) ->
     return line
 
 
+MIGRATE_COMMENT_DELIMITERS = {STRING_PRIORITY, COMMA_PRIORITY}
+
+
 @dont_increase_indentation
 def delimiter_split(
     line: Line, features: Collection[Feature], mode: Mode
@@ -1187,12 +1191,22 @@ def append_to_line(leaf: Leaf) -> Iterator[Line]:
             )
             current_line.append(leaf)
 
+    def append_comments(leaf: Leaf) -> Iterator[Line]:
+        for comment_after in line.comments_after(leaf):
+            yield from append_to_line(comment_after)
+
     last_non_comment_leaf = _get_last_non_comment_leaf(line)
     for leaf_idx, leaf in enumerate(line.leaves):
         yield from append_to_line(leaf)
 
-        for comment_after in line.comments_after(leaf):
-            yield from append_to_line(comment_after)
+        previous_priority = leaf_idx > 0 and bt.delimiters.get(
+            id(line.leaves[leaf_idx - 1])
+        )
+        if (
+            previous_priority != delimiter_priority
+            or delimiter_priority in MIGRATE_COMMENT_DELIMITERS
+        ):
+            yield from append_comments(leaf)
 
         lowest_depth = min(lowest_depth, leaf.bracket_depth)
         if trailing_comma_safe and leaf.bracket_depth == lowest_depth:
@@ -1205,8 +1219,13 @@ def append_to_line(leaf: Leaf) -> Iterator[Line]:
 
         leaf_priority = bt.delimiters.get(id(leaf))
         if leaf_priority == delimiter_priority:
-            yield current_line
+            if (
+                leaf_idx + 1 < len(line.leaves)
+                and delimiter_priority not in MIGRATE_COMMENT_DELIMITERS
+            ):
+                yield from append_comments(line.leaves[leaf_idx + 1])
 
+            yield current_line
             current_line = Line(
                 mode=line.mode, depth=line.depth, inside_brackets=line.inside_brackets
             )
diff --git a/tests/data/cases/split_delimiter_comments.py b/tests/data/cases/split_delimiter_comments.py
new file mode 100644
index 00000000000..ea29f7c034f
--- /dev/null
+++ b/tests/data/cases/split_delimiter_comments.py
@@ -0,0 +1,51 @@
+a = (
+    1 +  # type: ignore
+    2  # type: ignore
+)
+a = (
+    1  # type: ignore
+    + 2  # type: ignore
+)
+bad_split3 = (
+    "What if we have inline comments on "  # First Comment
+    "each line of a bad split? In that "  # Second Comment
+    "case, we should just leave it alone."  # Third Comment
+)
+parametrize(
+    (
+        {},
+        {},
+    ),
+    (  # foobar
+        {},
+        {},
+    ),
+)
+
+
+
+# output
+a = (
+    1  # type: ignore
+    + 2  # type: ignore
+)
+a = (
+    1  # type: ignore
+    + 2  # type: ignore
+)
+bad_split3 = (
+    "What if we have inline comments on "  # First Comment
+    "each line of a bad split? In that "  # Second Comment
+    "case, we should just leave it alone."  # Third Comment
+)
+parametrize(
+    (
+        {},
+        {},
+    ),
+    (  # foobar
+        {},
+        {},
+    ),
+)
+

From f03ee113c9f3dfeb477f2d4247bfb7de2e5f465c Mon Sep 17 00:00:00 2001
From: Zac Hatfield-Dodds <zac.hatfield.dodds@gmail.com>
Date: Sat, 2 Mar 2024 19:31:02 -0800
Subject: [PATCH 1027/1034] Ensure `blib2to3.pygram` is initialized before use
 (#4224)

---
 src/blib2to3/pytree.py | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/src/blib2to3/pytree.py b/src/blib2to3/pytree.py
index 2a0cd6d196a..4c55d7ac77d 100644
--- a/src/blib2to3/pytree.py
+++ b/src/blib2to3/pytree.py
@@ -40,12 +40,15 @@
 def type_repr(type_num: int) -> Union[str, int]:
     global _type_reprs
     if not _type_reprs:
-        from .pygram import python_symbols
+        from . import pygram
+
+        if not hasattr(pygram, "python_symbols"):
+            pygram.initialize(cache_dir=None)
 
         # printing tokens is possible but not as useful
         # from .pgen2 import token // token.__dict__.items():
-        for name in dir(python_symbols):
-            val = getattr(python_symbols, name)
+        for name in dir(pygram.python_symbols):
+            val = getattr(pygram.python_symbols, name)
             if type(val) == int:
                 _type_reprs[val] = name
     return _type_reprs.setdefault(type_num, type_num)

From 6af7d1109693c4ad3af08ecbc34649c232b47a6d Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Sat, 9 Mar 2024 17:42:29 -0800
Subject: [PATCH 1028/1034] Fix AST safety check false negative (#4270)

Fixes #4268

Previously we would allow whitespace changes in all strings, now
only in docstrings.

Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
---
 CHANGES.md            |   4 ++
 src/black/__init__.py |  15 ++++--
 src/black/parsing.py  |  42 ++++++++++++---
 tests/test_black.py   | 122 +++++++++++++++++++++++++++++++++++++-----
 4 files changed, 156 insertions(+), 27 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index e28730a3b5f..1d20a4c9210 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -11,6 +11,10 @@
 <!-- Changes that affect Black's stable style -->
 
 - Don't move comments along with delimiters, which could cause crashes (#4248)
+- Strengthen AST safety check to catch more unsafe changes to strings. Previous versions
+  of Black would incorrectly format the contents of certain unusual f-strings containing
+  nested strings with the same quote type. Now, Black will crash on such strings until
+  support for the new f-string syntax is implemented. (#4270)
 
 ### Preview style
 
diff --git a/src/black/__init__.py b/src/black/__init__.py
index f82b9fec5b7..da884e6027e 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -77,8 +77,13 @@
     syms,
 )
 from black.output import color_diff, diff, dump_to_file, err, ipynb_diff, out
-from black.parsing import InvalidInput  # noqa F401
-from black.parsing import lib2to3_parse, parse_ast, stringify_ast
+from black.parsing import (  # noqa F401
+    ASTSafetyError,
+    InvalidInput,
+    lib2to3_parse,
+    parse_ast,
+    stringify_ast,
+)
 from black.ranges import adjusted_lines, convert_unchanged_lines, parse_line_ranges
 from black.report import Changed, NothingChanged, Report
 from black.trans import iter_fexpr_spans
@@ -1511,7 +1516,7 @@ def assert_equivalent(src: str, dst: str) -> None:
     try:
         src_ast = parse_ast(src)
     except Exception as exc:
-        raise AssertionError(
+        raise ASTSafetyError(
             "cannot use --safe with this file; failed to parse source file AST: "
             f"{exc}\n"
             "This could be caused by running Black with an older Python version "
@@ -1522,7 +1527,7 @@ def assert_equivalent(src: str, dst: str) -> None:
         dst_ast = parse_ast(dst)
     except Exception as exc:
         log = dump_to_file("".join(traceback.format_tb(exc.__traceback__)), dst)
-        raise AssertionError(
+        raise ASTSafetyError(
             f"INTERNAL ERROR: Black produced invalid code: {exc}. "
             "Please report a bug on https://github.com/psf/black/issues.  "
             f"This invalid output might be helpful: {log}"
@@ -1532,7 +1537,7 @@ def assert_equivalent(src: str, dst: str) -> None:
     dst_ast_str = "\n".join(stringify_ast(dst_ast))
     if src_ast_str != dst_ast_str:
         log = dump_to_file(diff(src_ast_str, dst_ast_str, "src", "dst"))
-        raise AssertionError(
+        raise ASTSafetyError(
             "INTERNAL ERROR: Black produced code that is not equivalent to the"
             " source.  Please report a bug on "
             f"https://github.com/psf/black/issues.  This diff might be helpful: {log}"
diff --git a/src/black/parsing.py b/src/black/parsing.py
index 63c5e71a0fe..aa97a8cecea 100644
--- a/src/black/parsing.py
+++ b/src/black/parsing.py
@@ -110,6 +110,10 @@ def lib2to3_unparse(node: Node) -> str:
     return code
 
 
+class ASTSafetyError(Exception):
+    """Raised when Black's generated code is not equivalent to the old AST."""
+
+
 def _parse_single_version(
     src: str, version: Tuple[int, int], *, type_comments: bool
 ) -> ast.AST:
@@ -154,9 +158,20 @@ def _normalize(lineend: str, value: str) -> str:
     return normalized.strip()
 
 
-def stringify_ast(node: ast.AST, depth: int = 0) -> Iterator[str]:
+def stringify_ast(node: ast.AST) -> Iterator[str]:
     """Simple visitor generating strings to compare ASTs by content."""
+    return _stringify_ast(node, [])
+
 
+def _stringify_ast_with_new_parent(
+    node: ast.AST, parent_stack: List[ast.AST], new_parent: ast.AST
+) -> Iterator[str]:
+    parent_stack.append(new_parent)
+    yield from _stringify_ast(node, parent_stack)
+    parent_stack.pop()
+
+
+def _stringify_ast(node: ast.AST, parent_stack: List[ast.AST]) -> Iterator[str]:
     if (
         isinstance(node, ast.Constant)
         and isinstance(node.value, str)
@@ -167,7 +182,7 @@ def stringify_ast(node: ast.AST, depth: int = 0) -> Iterator[str]:
         # over the kind
         node.kind = None
 
-    yield f"{'  ' * depth}{node.__class__.__name__}("
+    yield f"{'    ' * len(parent_stack)}{node.__class__.__name__}("
 
     for field in sorted(node._fields):  # noqa: F402
         # TypeIgnore has only one field 'lineno' which breaks this comparison
@@ -179,7 +194,7 @@ def stringify_ast(node: ast.AST, depth: int = 0) -> Iterator[str]:
         except AttributeError:
             continue
 
-        yield f"{'  ' * (depth + 1)}{field}="
+        yield f"{'    ' * (len(parent_stack) + 1)}{field}="
 
         if isinstance(value, list):
             for item in value:
@@ -191,13 +206,15 @@ def stringify_ast(node: ast.AST, depth: int = 0) -> Iterator[str]:
                     and isinstance(item, ast.Tuple)
                 ):
                     for elt in item.elts:
-                        yield from stringify_ast(elt, depth + 2)
+                        yield from _stringify_ast_with_new_parent(
+                            elt, parent_stack, node
+                        )
 
                 elif isinstance(item, ast.AST):
-                    yield from stringify_ast(item, depth + 2)
+                    yield from _stringify_ast_with_new_parent(item, parent_stack, node)
 
         elif isinstance(value, ast.AST):
-            yield from stringify_ast(value, depth + 2)
+            yield from _stringify_ast_with_new_parent(value, parent_stack, node)
 
         else:
             normalized: object
@@ -205,6 +222,12 @@ def stringify_ast(node: ast.AST, depth: int = 0) -> Iterator[str]:
                 isinstance(node, ast.Constant)
                 and field == "value"
                 and isinstance(value, str)
+                and len(parent_stack) >= 2
+                and isinstance(parent_stack[-1], ast.Expr)
+                and isinstance(
+                    parent_stack[-2],
+                    (ast.FunctionDef, ast.AsyncFunctionDef, ast.Module, ast.ClassDef),
+                )
             ):
                 # Constant strings may be indented across newlines, if they are
                 # docstrings; fold spaces after newlines when comparing. Similarly,
@@ -215,6 +238,9 @@ def stringify_ast(node: ast.AST, depth: int = 0) -> Iterator[str]:
                 normalized = value.rstrip()
             else:
                 normalized = value
-            yield f"{'  ' * (depth + 2)}{normalized!r},  # {value.__class__.__name__}"
+            yield (
+                f"{'    ' * (len(parent_stack) + 1)}{normalized!r},  #"
+                f" {value.__class__.__name__}"
+            )
 
-    yield f"{'  ' * depth})  # /{node.__class__.__name__}"
+    yield f"{'    ' * len(parent_stack)})  # /{node.__class__.__name__}"
diff --git a/tests/test_black.py b/tests/test_black.py
index 41f87cd16f8..96f53d5e5f3 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -46,6 +46,7 @@
 from black.debug import DebugVisitor
 from black.mode import Mode, Preview
 from black.output import color_diff, diff
+from black.parsing import ASTSafetyError
 from black.report import Report
 
 # Import other test classes
@@ -1473,10 +1474,6 @@ def test_normalize_line_endings(self) -> None:
                 ff(test_file, write_back=black.WriteBack.YES)
                 self.assertEqual(test_file.read_bytes(), expected)
 
-    def test_assert_equivalent_different_asts(self) -> None:
-        with self.assertRaises(AssertionError):
-            black.assert_equivalent("{}", "None")
-
     def test_root_logger_not_used_directly(self) -> None:
         def fail(*args: Any, **kwargs: Any) -> None:
             self.fail("Record created with root logger")
@@ -1962,16 +1959,6 @@ def test_for_handled_unexpected_eof_error(self) -> None:
 
         exc_info.match("Cannot parse: 2:0: EOF in multi-line statement")
 
-    def test_equivalency_ast_parse_failure_includes_error(self) -> None:
-        with pytest.raises(AssertionError) as err:
-            black.assert_equivalent("a«»a  = 1", "a«»a  = 1")
-
-        err.match("--safe")
-        # Unfortunately the SyntaxError message has changed in newer versions so we
-        # can't match it directly.
-        err.match("invalid character")
-        err.match(r"\(<unknown>, line 1\)")
-
     def test_line_ranges_with_code_option(self) -> None:
         code = textwrap.dedent("""\
             if  a  ==  b:
@@ -2822,6 +2809,113 @@ def test_format_file_contents(self) -> None:
             black.format_file_contents("x = 1\n", fast=True, mode=black.Mode())
 
 
+class TestASTSafety(BlackBaseTestCase):
+    def check_ast_equivalence(
+        self, source: str, dest: str, *, should_fail: bool = False
+    ) -> None:
+        # If we get a failure, make sure it's not because the code itself
+        # is invalid, since that will also cause assert_equivalent() to throw
+        # ASTSafetyError.
+        source = textwrap.dedent(source)
+        dest = textwrap.dedent(dest)
+        black.parse_ast(source)
+        black.parse_ast(dest)
+        if should_fail:
+            with self.assertRaises(ASTSafetyError):
+                black.assert_equivalent(source, dest)
+        else:
+            black.assert_equivalent(source, dest)
+
+    def test_assert_equivalent_basic(self) -> None:
+        self.check_ast_equivalence("{}", "None", should_fail=True)
+        self.check_ast_equivalence("1+2", "1    +   2")
+        self.check_ast_equivalence("hi # comment", "hi")
+
+    def test_assert_equivalent_del(self) -> None:
+        self.check_ast_equivalence("del (a, b)", "del a, b")
+
+    def test_assert_equivalent_strings(self) -> None:
+        self.check_ast_equivalence('x = "x"', 'x = " x "', should_fail=True)
+        self.check_ast_equivalence(
+            '''
+            """docstring  """
+            ''',
+            '''
+            """docstring"""
+            ''',
+        )
+        self.check_ast_equivalence(
+            '''
+            """docstring  """
+            ''',
+            '''
+            """ddocstring"""
+            ''',
+            should_fail=True,
+        )
+        self.check_ast_equivalence(
+            '''
+            class A:
+                """
+
+                docstring
+
+
+                """
+            ''',
+            '''
+            class A:
+                """docstring"""
+            ''',
+        )
+        self.check_ast_equivalence(
+            """
+            def f():
+                " docstring  "
+            """,
+            '''
+            def f():
+                """docstring"""
+            ''',
+        )
+        self.check_ast_equivalence(
+            """
+            async def f():
+                "   docstring  "
+            """,
+            '''
+            async def f():
+                """docstring"""
+            ''',
+        )
+
+    def test_assert_equivalent_fstring(self) -> None:
+        major, minor = sys.version_info[:2]
+        if major < 3 or (major == 3 and minor < 12):
+            pytest.skip("relies on 3.12+ syntax")
+        # https://github.com/psf/black/issues/4268
+        self.check_ast_equivalence(
+            """print(f"{"|".join([a,b,c])}")""",
+            """print(f"{" | ".join([a,b,c])}")""",
+            should_fail=True,
+        )
+        self.check_ast_equivalence(
+            """print(f"{"|".join(['a','b','c'])}")""",
+            """print(f"{" | ".join(['a','b','c'])}")""",
+            should_fail=True,
+        )
+
+    def test_equivalency_ast_parse_failure_includes_error(self) -> None:
+        with pytest.raises(ASTSafetyError) as err:
+            black.assert_equivalent("a«»a  = 1", "a«»a  = 1")
+
+        err.match("--safe")
+        # Unfortunately the SyntaxError message has changed in newer versions so we
+        # can't match it directly.
+        err.match("invalid character")
+        err.match(r"\(<unknown>, line 1\)")
+
+
 try:
     with open(black.__file__, "r", encoding="utf-8") as _bf:
         black_source_lines = _bf.readlines()

From e5510afc06cd238cd0cba4095283943a870a7e7b Mon Sep 17 00:00:00 2001
From: Charpy <nico_github@charpenel.org>
Date: Wed, 13 Mar 2024 05:14:06 +0100
Subject: [PATCH 1029/1034] update plugin url for Thonny (#4259)

---
 docs/integrations/editors.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/integrations/editors.md b/docs/integrations/editors.md
index 7d056160fcb..6ca1205d4c2 100644
--- a/docs/integrations/editors.md
+++ b/docs/integrations/editors.md
@@ -432,4 +432,4 @@ hook global WinSetOption filetype=python %{
 
 ## Thonny
 
-Use [Thonny-black-code-format](https://github.com/Franccisco/thonny-black-code-format).
+Use [Thonny-black-formatter](https://pypi.org/project/thonny-black-formatter/).

From 719e67462c80574c81a96faa144886de6da84489 Mon Sep 17 00:00:00 2001
From: Daniel Krzeminski <dankrzeminski32@gmail.com>
Date: Tue, 12 Mar 2024 23:15:29 -0500
Subject: [PATCH 1030/1034] Fix 4227: Improve documentation for --quiet --check
 (#4236)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 CHANGES.md                                 | 1 +
 docs/usage_and_configuration/the_basics.md | 3 +++
 2 files changed, 4 insertions(+)

diff --git a/CHANGES.md b/CHANGES.md
index 1d20a4c9210..e0a034b759b 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -50,6 +50,7 @@
 
 ### Documentation
 
+- Note what happens when `--check` is used with `--quiet` (#4236)
 <!-- Major changes to documentation and policies. Small docs changes
      don't need a changelog entry. -->
 
diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index ea7a2dae5ce..7aa8a644bea 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -183,6 +183,9 @@ Don't write the files back, just return the status. _Black_ will exit with:
 - code 1 if some files would be reformatted; or
 - code 123 if there was an internal error
 
+If used in combination with `--quiet` then only the exit code will be returned, unless
+there was an internal error.
+
 ```console
 $ black test.py --check
 All done! ✨ 🍰 ✨

From 1abcffc81816257985678f08c61584ed4287f22a Mon Sep 17 00:00:00 2001
From: Kai Sforza <kai@kaictl.me>
Date: Wed, 13 Mar 2024 00:22:10 -0400
Subject: [PATCH 1031/1034] Use regex where we ignore case on windows (#4252)

On windows the path `FoObAR` is the same as `foobar`, so the output
of `black` on a windows machine could output the path to `.gitignore`
with an upper or lower-case drive letter.
---
 tests/test_black.py | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/tests/test_black.py b/tests/test_black.py
index 96f53d5e5f3..70884152d58 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -14,7 +14,7 @@
 from contextlib import contextmanager, redirect_stderr
 from dataclasses import replace
 from io import BytesIO
-from pathlib import Path
+from pathlib import Path, WindowsPath
 from platform import system
 from tempfile import TemporaryDirectory
 from typing import (
@@ -2460,7 +2460,11 @@ def test_invalid_gitignore(self) -> None:
         assert result.stderr_bytes is not None
 
         gitignore = path / ".gitignore"
-        assert f"Could not parse {gitignore}" in result.stderr_bytes.decode()
+        assert re.search(
+            f"Could not parse {gitignore}".replace("\\", "\\\\"),
+            result.stderr_bytes.decode(),
+            re.IGNORECASE if isinstance(gitignore, WindowsPath) else 0,
+        )
 
     def test_invalid_nested_gitignore(self) -> None:
         path = THIS_DIR / "data" / "invalid_nested_gitignore_tests"
@@ -2472,7 +2476,11 @@ def test_invalid_nested_gitignore(self) -> None:
         assert result.stderr_bytes is not None
 
         gitignore = path / "a" / ".gitignore"
-        assert f"Could not parse {gitignore}" in result.stderr_bytes.decode()
+        assert re.search(
+            f"Could not parse {gitignore}".replace("\\", "\\\\"),
+            result.stderr_bytes.decode(),
+            re.IGNORECASE if isinstance(gitignore, WindowsPath) else 0,
+        )
 
     def test_gitignore_that_ignores_subfolders(self) -> None:
         # If gitignore with */* is in root

From 7b5a657285f38126bf28483478bbd9ea928077ec Mon Sep 17 00:00:00 2001
From: Samson Umezulike <samson.ume@gmail.com>
Date: Fri, 15 Mar 2024 19:18:47 +0100
Subject: [PATCH 1032/1034] Fix --line-ranges behavior when ranges are at EOF
 (#4273)

Fixes #4264
---
 CHANGES.md                                    |  2 +
 src/black/__init__.py                         | 11 +++-
 src/black/ranges.py                           | 28 ++++++++
 tests/data/cases/line_ranges_exceeding_end.py | 36 ++++++++++
 .../data/cases/line_ranges_outside_source.py  |  7 ++
 tests/test_ranges.py                          | 66 ++++++++++++++++++-
 6 files changed, 148 insertions(+), 2 deletions(-)
 create mode 100644 tests/data/cases/line_ranges_exceeding_end.py
 create mode 100644 tests/data/cases/line_ranges_outside_source.py

diff --git a/CHANGES.md b/CHANGES.md
index e0a034b759b..c255c2a8347 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -15,6 +15,8 @@
   of Black would incorrectly format the contents of certain unusual f-strings containing
   nested strings with the same quote type. Now, Black will crash on such strings until
   support for the new f-string syntax is implemented. (#4270)
+- Fixed a bug where line-ranges exceeding the last code line would not work as expected
+  (#4273)
 
 ### Preview style
 
diff --git a/src/black/__init__.py b/src/black/__init__.py
index da884e6027e..6f0e128f56c 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -84,7 +84,12 @@
     parse_ast,
     stringify_ast,
 )
-from black.ranges import adjusted_lines, convert_unchanged_lines, parse_line_ranges
+from black.ranges import (
+    adjusted_lines,
+    convert_unchanged_lines,
+    parse_line_ranges,
+    sanitized_lines,
+)
 from black.report import Changed, NothingChanged, Report
 from black.trans import iter_fexpr_spans
 from blib2to3.pgen2 import token
@@ -1220,6 +1225,10 @@ def f(
         hey
 
     """
+    if lines:
+        lines = sanitized_lines(lines, src_contents)
+        if not lines:
+            return src_contents  # Nothing to format
     dst_contents = _format_str_once(src_contents, mode=mode, lines=lines)
     # Forced second pass to work around optional trailing commas (becoming
     # forced trailing commas on pass 2) interacting differently with optional
diff --git a/src/black/ranges.py b/src/black/ranges.py
index 06fa8790554..1ecaf7b0aed 100644
--- a/src/black/ranges.py
+++ b/src/black/ranges.py
@@ -45,6 +45,34 @@ def is_valid_line_range(lines: Tuple[int, int]) -> bool:
     return not lines or lines[0] <= lines[1]
 
 
+def sanitized_lines(
+    lines: Collection[Tuple[int, int]], src_contents: str
+) -> Collection[Tuple[int, int]]:
+    """Returns the valid line ranges for the given source.
+
+    This removes ranges that are entirely outside the valid lines.
+
+    Other ranges are normalized so that the start values are at least 1 and the
+    end values are at most the (1-based) index of the last source line.
+    """
+    if not src_contents:
+        return []
+    good_lines = []
+    src_line_count = src_contents.count("\n")
+    if not src_contents.endswith("\n"):
+        src_line_count += 1
+    for start, end in lines:
+        if start > src_line_count:
+            continue
+        # line-ranges are 1-based
+        start = max(start, 1)
+        if end < start:
+            continue
+        end = min(end, src_line_count)
+        good_lines.append((start, end))
+    return good_lines
+
+
 def adjusted_lines(
     lines: Collection[Tuple[int, int]],
     original_source: str,
diff --git a/tests/data/cases/line_ranges_exceeding_end.py b/tests/data/cases/line_ranges_exceeding_end.py
new file mode 100644
index 00000000000..8f17491f684
--- /dev/null
+++ b/tests/data/cases/line_ranges_exceeding_end.py
@@ -0,0 +1,36 @@
+# flags: --line-ranges=6-1000
+# NOTE: If you need to modify this file, pay special attention to the --line-ranges=
+# flag above as it's formatting specifically these lines.
+def foo1(parameter_1, parameter_2, parameter_3, parameter_4, parameter_5, parameter_6, parameter_7): pass
+def foo2(parameter_1, parameter_2, parameter_3, parameter_4, parameter_5, parameter_6, parameter_7): pass
+def foo3(parameter_1, parameter_2, parameter_3, parameter_4, parameter_5, parameter_6, parameter_7): pass
+def foo4(parameter_1, parameter_2, parameter_3, parameter_4, parameter_5, parameter_6, parameter_7): pass
+
+# output
+# flags: --line-ranges=6-1000
+# NOTE: If you need to modify this file, pay special attention to the --line-ranges=
+# flag above as it's formatting specifically these lines.
+def foo1(parameter_1, parameter_2, parameter_3, parameter_4, parameter_5, parameter_6, parameter_7): pass
+def foo2(parameter_1, parameter_2, parameter_3, parameter_4, parameter_5, parameter_6, parameter_7): pass
+def foo3(
+    parameter_1,
+    parameter_2,
+    parameter_3,
+    parameter_4,
+    parameter_5,
+    parameter_6,
+    parameter_7,
+):
+    pass
+
+
+def foo4(
+    parameter_1,
+    parameter_2,
+    parameter_3,
+    parameter_4,
+    parameter_5,
+    parameter_6,
+    parameter_7,
+):
+    pass
diff --git a/tests/data/cases/line_ranges_outside_source.py b/tests/data/cases/line_ranges_outside_source.py
new file mode 100644
index 00000000000..edec9015ff8
--- /dev/null
+++ b/tests/data/cases/line_ranges_outside_source.py
@@ -0,0 +1,7 @@
+# flags: --line-ranges=5000-6000
+# NOTE: If you need to modify this file, pay special attention to the --line-ranges=
+# flag above as it's formatting specifically these lines, in this case none.
+def foo1(parameter_1, parameter_2, parameter_3, parameter_4, parameter_5, parameter_6, parameter_7): pass
+def foo2(parameter_1, parameter_2, parameter_3, parameter_4, parameter_5, parameter_6, parameter_7): pass
+def foo3(parameter_1, parameter_2, parameter_3, parameter_4, parameter_5, parameter_6, parameter_7): pass
+def foo4(parameter_1, parameter_2, parameter_3, parameter_4, parameter_5, parameter_6, parameter_7): pass
diff --git a/tests/test_ranges.py b/tests/test_ranges.py
index d9fa9171a7f..a3028babf50 100644
--- a/tests/test_ranges.py
+++ b/tests/test_ranges.py
@@ -4,7 +4,7 @@
 
 import pytest
 
-from black.ranges import adjusted_lines
+from black.ranges import adjusted_lines, sanitized_lines
 
 
 @pytest.mark.parametrize(
@@ -183,3 +183,67 @@ def test_diffs(lines: List[Tuple[int, int]], adjusted: List[Tuple[int, int]]) ->
 12. # last line changed
 """
     assert adjusted == adjusted_lines(lines, original_source, modified_source)
+
+
+@pytest.mark.parametrize(
+    "lines,sanitized",
+    [
+        (
+            [(1, 4)],
+            [(1, 4)],
+        ),
+        (
+            [(2, 3)],
+            [(2, 3)],
+        ),
+        (
+            [(2, 10)],
+            [(2, 4)],
+        ),
+        (
+            [(0, 3)],
+            [(1, 3)],
+        ),
+        (
+            [(0, 10)],
+            [(1, 4)],
+        ),
+        (
+            [(-2, 3)],
+            [(1, 3)],
+        ),
+        (
+            [(0, 0)],
+            [],
+        ),
+        (
+            [(-2, -1)],
+            [],
+        ),
+        (
+            [(-1, 0)],
+            [],
+        ),
+        (
+            [(3, 1), (1, 3), (5, 6)],
+            [(1, 3)],
+        ),
+    ],
+)
+def test_sanitize(
+    lines: List[Tuple[int, int]], sanitized: List[Tuple[int, int]]
+) -> None:
+    source = """\
+1. import re
+2. def func(arg1,
+3.   arg2, arg3):
+4.   pass
+"""
+    assert sanitized == sanitized_lines(lines, source)
+
+    source_no_trailing_nl = """\
+    1. import re
+    2. def func(arg1,
+    3.   arg2, arg3):
+    4.   pass"""
+    assert sanitized == sanitized_lines(lines, source_no_trailing_nl)

From f00093672628d212b8965a8993cee8bedf5fe9b8 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Fri, 15 Mar 2024 12:06:12 -0700
Subject: [PATCH 1033/1034] Fix catastrophic performance in
 lines_with_leading_tabs_expanded() (#4278)

---
 CHANGES.md           | 13 ++++++++++++-
 src/black/strings.py | 18 ++++++------------
 tests/test_black.py  | 12 ++++++++++++
 3 files changed, 30 insertions(+), 13 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index c255c2a8347..ffd24feb31c 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -6,6 +6,14 @@
 
 <!-- Include any especially major or disruptive changes here -->
 
+This release is a milestone: it fixes Black's first CVE security vulnerability. If you
+run Black on untrusted input, or if you habitually put thousands of leading tab
+characters in your docstrings, you are strongly encouraged to upgrade immediately to fix
+[CVE-2024-21503](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-21503).
+
+This release also fixes a bug in Black's AST safety check that allowed Black to make
+incorrect changes to certain f-strings that are valid in Python 3.12 and higher.
+
 ### Stable style
 
 <!-- Changes that affect Black's stable style -->
@@ -36,7 +44,10 @@
 
 ### Performance
 
-<!-- Changes that improve Black's performance. -->
+- Fix catastrophic performance on docstrings that contain large numbers of leading tab
+  characters. This fixes
+  [CVE-2024-21503](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-21503).
+  (#4278)
 
 ### Output
 
diff --git a/src/black/strings.py b/src/black/strings.py
index 0e0f968824b..baa88162844 100644
--- a/src/black/strings.py
+++ b/src/black/strings.py
@@ -14,7 +14,6 @@
 STRING_PREFIX_RE: Final = re.compile(
     r"^([" + STRING_PREFIX_CHARS + r"]*)(.*)$", re.DOTALL
 )
-FIRST_NON_WHITESPACE_RE: Final = re.compile(r"\s*\t+\s*(\S)")
 UNICODE_ESCAPE_RE: Final = re.compile(
     r"(?P<backslashes>\\+)(?P<body>"
     r"(u(?P<u>[a-fA-F0-9]{4}))"  # Character with 16-bit hex value xxxx
@@ -51,18 +50,13 @@ def lines_with_leading_tabs_expanded(s: str) -> List[str]:
     """
     lines = []
     for line in s.splitlines():
-        # Find the index of the first non-whitespace character after a string of
-        # whitespace that includes at least one tab
-        match = FIRST_NON_WHITESPACE_RE.match(line)
-        if match:
-            first_non_whitespace_idx = match.start(1)
-
-            lines.append(
-                line[:first_non_whitespace_idx].expandtabs()
-                + line[first_non_whitespace_idx:]
-            )
-        else:
+        stripped_line = line.lstrip()
+        if not stripped_line or stripped_line == line:
             lines.append(line)
+        else:
+            prefix_length = len(line) - len(stripped_line)
+            prefix = line[:prefix_length].expandtabs()
+            lines.append(prefix + stripped_line)
     if s.endswith("\n"):
         lines.append("")
     return lines
diff --git a/tests/test_black.py b/tests/test_black.py
index 70884152d58..ecea4a073a3 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -48,6 +48,7 @@
 from black.output import color_diff, diff
 from black.parsing import ASTSafetyError
 from black.report import Report
+from black.strings import lines_with_leading_tabs_expanded
 
 # Import other test classes
 from tests.util import (
@@ -2041,6 +2042,17 @@ def test_line_ranges_in_pyproject_toml(self) -> None:
             b"Cannot use line-ranges in the pyproject.toml file." in result.stderr_bytes
         )
 
+    def test_lines_with_leading_tabs_expanded(self) -> None:
+        # See CVE-2024-21503. Mostly test that this completes in a reasonable
+        # time.
+        payload = "\t" * 10_000
+        assert lines_with_leading_tabs_expanded(payload) == [payload]
+
+        tab = " " * 8
+        assert lines_with_leading_tabs_expanded("\tx") == [f"{tab}x"]
+        assert lines_with_leading_tabs_expanded("\t\tx") == [f"{tab}{tab}x"]
+        assert lines_with_leading_tabs_expanded("\tx\n  y") == [f"{tab}x", "  y"]
+
 
 class TestCaching:
     def test_get_cache_dir(

From 552baf822992936134cbd31a38f69c8cfe7c0f05 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Fri, 15 Mar 2024 12:17:00 -0700
Subject: [PATCH 1034/1034] Prepare release 24.3.0 (#4279)

---
 CHANGES.md                                  | 38 ++-------------------
 docs/integrations/source_version_control.md |  4 +--
 docs/usage_and_configuration/the_basics.md  |  6 ++--
 3 files changed, 7 insertions(+), 41 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index ffd24feb31c..a1d674d5b5b 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,11 +1,9 @@
 # Change Log
 
-## Unreleased
+## 24.3.0
 
 ### Highlights
 
-<!-- Include any especially major or disruptive changes here -->
-
 This release is a milestone: it fixes Black's first CVE security vulnerability. If you
 run Black on untrusted input, or if you habitually put thousands of leading tab
 characters in your docstrings, you are strongly encouraged to upgrade immediately to fix
@@ -16,32 +14,14 @@ incorrect changes to certain f-strings that are valid in Python 3.12 and higher.
 
 ### Stable style
 
-<!-- Changes that affect Black's stable style -->
-
 - Don't move comments along with delimiters, which could cause crashes (#4248)
 - Strengthen AST safety check to catch more unsafe changes to strings. Previous versions
   of Black would incorrectly format the contents of certain unusual f-strings containing
   nested strings with the same quote type. Now, Black will crash on such strings until
   support for the new f-string syntax is implemented. (#4270)
-- Fixed a bug where line-ranges exceeding the last code line would not work as expected
+- Fix a bug where line-ranges exceeding the last code line would not work as expected
   (#4273)
 
-### Preview style
-
-<!-- Changes that affect Black's preview style -->
-
-### Configuration
-
-<!-- Changes to how Black can be configured -->
-
-### Packaging
-
-<!-- Changes to how Black is packaged, such as dependency requirements -->
-
-### Parser
-
-<!-- Changes to the parser or to version autodetection -->
-
 ### Performance
 
 - Fix catastrophic performance on docstrings that contain large numbers of leading tab
@@ -49,23 +29,9 @@ incorrect changes to certain f-strings that are valid in Python 3.12 and higher.
   [CVE-2024-21503](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-21503).
   (#4278)
 
-### Output
-
-<!-- Changes to Black's terminal output and error messages -->
-
-### _Blackd_
-
-<!-- Changes to blackd -->
-
-### Integrations
-
-<!-- For example, Docker, GitHub Actions, pre-commit, editors -->
-
 ### Documentation
 
 - Note what happens when `--check` is used with `--quiet` (#4236)
-<!-- Major changes to documentation and policies. Small docs changes
-     don't need a changelog entry. -->
 
 ## 24.2.0
 
diff --git a/docs/integrations/source_version_control.md b/docs/integrations/source_version_control.md
index f24043026fa..541debdc556 100644
--- a/docs/integrations/source_version_control.md
+++ b/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.2.0
+    rev: 24.3.0
     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.2.0
+    rev: 24.3.0
     hooks:
       - id: black-jupyter
         # It is recommended to specify the latest version of Python
diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index 7aa8a644bea..9ce72823850 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -269,8 +269,8 @@ configuration file for consistent results across environments.
 
 ```console
 $ black --version
-black, 24.2.0 (compiled: yes)
-$ black --required-version 24.2.0 -c "format = 'this'"
+black, 24.3.0 (compiled: yes)
+$ black --required-version 24.3.0 -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.2.0
+black, 24.3.0
 ```
 
 #### `--config`